Improve Relation picker for RLS

# Introduction
- Fixing app dependencyFlatEntityMaps load ( to load current app +
dependent app )
- Fix empty flat entity maps and undefined optimistic override
- Refactor the optimistic rendering to be mutation oriented at
orchestrator level

.cursor/Dockerfile

@@ -0,0 +1,34 @@
+FROM ubuntu:22.04
+
+ENV DEBIAN_FRONTEND=noninteractive
+
+RUN apt-get update && apt-get install -y \
+    curl \
+    git \
+    make \
+    build-essential \
+    postgresql-client \
+    docker.io \
+    && rm -rf /var/lib/apt/lists/*
+
+# Install nvm (project recommends nvm + .nvmrc for consistent Node versions)
+ENV NVM_DIR=/usr/local/nvm
+RUN mkdir -p $NVM_DIR \
+    && curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/master/install.sh | bash
+
+SHELL ["/bin/bash", "-c"]
+
+# Copy .nvmrc so nvm install picks up the right version
+COPY .nvmrc /tmp/.nvmrc
+
+# Install Node.js from .nvmrc, enable Corepack, and symlink binaries
+# so they're available on PATH without hardcoding a version
+RUN . $NVM_DIR/nvm.sh \
+    && nvm install $(cat /tmp/.nvmrc) \
+    && nvm alias default $(cat /tmp/.nvmrc) \
+    && corepack enable \
+    && BIN_DIR=$(dirname $(nvm which default)) \
+    && ln -sf $BIN_DIR/node /usr/local/bin/node \
+    && ln -sf $BIN_DIR/npm /usr/local/bin/npm \
+    && ln -sf $BIN_DIR/npx /usr/local/bin/npx \
+    && ln -sf $BIN_DIR/corepack /usr/local/bin/corepack

.cursor/environment.json

@@ -1,18 +1,10 @@
 {
-  "install": "curl -fsSL https://deb.nodesource.com/setup_24.x | sudo -E bash - && sudo apt-get install -y nodejs && node --version && yarn install && echo 'Installing dependencies complete'",
-  "start": "sudo service docker start && echo 'Docker service started' && sleep 3 && echo 'Starting PostgreSQL and Redis containers...' && make postgres-on-docker && make redis-on-docker && echo 'Waiting for containers to initialize...' && sleep 20 && echo 'Checking container status...' && docker ps --filter name=twenty_ && echo 'Waiting for PostgreSQL to be ready...' && until docker exec twenty_pg pg_isready -U postgres -h localhost; do echo 'PostgreSQL not ready yet, waiting...'; sleep 3; done && echo 'PostgreSQL is ready!' && echo 'Setting up database...' && cd packages/twenty-server && npx nx database:reset twenty-server || echo 'Database already initialized' && echo 'Environment setup complete!'",
+  "install": "yarn install",
+  "start": "sudo service docker start && sleep 2 && (docker start twenty_pg 2>/dev/null || make -C packages/twenty-docker postgres-on-docker) && (docker start twenty_redis 2>/dev/null || make -C packages/twenty-docker redis-on-docker) && until docker exec twenty_pg pg_isready -U postgres -h localhost 2>/dev/null; do sleep 1; done && echo 'PostgreSQL ready' && until docker exec twenty_redis redis-cli ping 2>/dev/null | grep -q PONG; do sleep 1; done && echo 'Redis ready' && bash packages/twenty-utils/setup-dev-env.sh && npx nx database:reset twenty-server",
   "terminals": [
     {
       "name": "Development Server",
-      "command": "echo 'Waiting for database to be fully ready...' && sleep 30 && until docker exec twenty_pg pg_isready -U postgres -h localhost; do echo 'Waiting for PostgreSQL...'; sleep 2; done && echo 'Starting Twenty development server...' && export SERVER_URL=http://localhost:3000 && export PG_DATABASE_URL=postgres://postgres:postgres@localhost:5432/postgres && yarn start"
-    },
-    {
-      "name": "Database Management",
-      "command": "sleep 25 && echo 'Database management terminal ready' && echo 'Waiting for PostgreSQL to be available...' && until docker exec twenty_pg pg_isready -U postgres -h localhost; do echo 'Waiting for PostgreSQL...'; sleep 2; done && echo 'PostgreSQL is ready for database operations!' && echo 'You can now run database commands like:' && echo '  npx nx database:reset twenty-server' && echo '  npx nx database:migrate twenty-server' && bash"
-    },
-    {
-      "name": "Container Logs & Status",
-      "command": "sleep 10 && echo '=== Container Status Monitor ===' && while true; do echo '\\n=== Container Status at $(date) ===' && docker ps --filter name=twenty_ --format 'table {{.Names}}\\t{{.Status}}\\t{{.Ports}}' && echo '\\n=== PostgreSQL Status ===' && (docker exec twenty_pg pg_isready -U postgres -h localhost && echo 'PostgreSQL: ✅ Ready') || echo 'PostgreSQL: ❌ Not Ready' && echo '\\n=== Redis Status ===' && (docker exec twenty_redis redis-cli ping && echo 'Redis: ✅ Ready') || echo 'Redis: ❌ Not Ready' && sleep 30; done"
+      "command": "yarn start"
     }
   ]
-} 
+}

.cursor/skills/syncable-entity-builder-and-validation/SKILL.md

@@ -0,0 +1,393 @@
+---
+name: syncable-entity-builder-and-validation
+description: Create validation logic and migration action builders for syncable entities in Twenty. Use when implementing business rule validation, uniqueness checks, foreign key validation, or building workspace migration actions for syncable entities. Validators never throw and never mutate.
+---
+
+# Syncable Entity: Builder & Validation (Step 3/6)
+
+**Purpose**: Implement business rule validation and create migration action builders.
+
+**When to use**: After completing Steps 1-2 (Types, Cache, Transform). Required before implementing action handlers.
+
+---
+
+## Quick Start
+
+This step creates:
+1. Validator service (business logic validation)
+2. Builder service (action creation)
+3. Orchestrator wiring (**CRITICAL** - often forgotten!)
+
+**Key principles**:
+- Validators **never throw** - return error arrays
+- Validators **never mutate** - pass optimistic entity maps
+- Use indexed lookups (O(1)) not `Object.values().find()` (O(n))
+
+---
+
+## Step 1: Create Validator Service
+
+**File**: `src/engine/workspace-manager/workspace-migration/workspace-migration-builder/validators/services/flat-my-entity-validator.service.ts`
+
+```typescript
+import { Injectable } from '@nestjs/common';
+import { t, msg } from '@lingui/macro';
+import { isDefined } from 'twenty-shared/utils';
+
+import { type FlatMyEntity } from 'src/engine/metadata-modules/flat-my-entity/types/flat-my-entity.type';
+import { type FlatMyEntityMaps } from 'src/engine/metadata-modules/flat-my-entity/types/flat-my-entity-maps.type';
+import { WorkspaceMigrationValidationError } from 'src/engine/workspace-manager/workspace-migration/workspace-migration-builder/validators/types/workspace-migration-validation-error.type';
+import { MyEntityExceptionCode } from 'src/engine/metadata-modules/my-entity/exceptions/my-entity-exception-code.enum';
+
+@Injectable()
+export class FlatMyEntityValidatorService {
+  validateMyEntityForCreate(
+    flatMyEntity: FlatMyEntity,
+    optimisticFlatMyEntityMaps: FlatMyEntityMaps,
+  ): WorkspaceMigrationValidationError[] {
+    const errors: WorkspaceMigrationValidationError[] = [];
+
+    // Pattern 1: Required field validation
+    if (!isDefined(flatMyEntity.name) || flatMyEntity.name.trim() === '') {
+      errors.push({
+        code: MyEntityExceptionCode.NAME_REQUIRED,
+        message: t`Name is required`,
+        userFriendlyMessage: msg`Please provide a name for this entity`,
+      });
+    }
+
+    // Pattern 2: Uniqueness check - use indexed map (O(1))
+    const existingEntityWithName = optimisticFlatMyEntityMaps.byName[flatMyEntity.name];
+
+    if (isDefined(existingEntityWithName) && existingEntityWithName.id !== flatMyEntity.id) {
+      errors.push({
+        code: MyEntityExceptionCode.MY_ENTITY_ALREADY_EXISTS,
+        message: t`Entity with name ${flatMyEntity.name} already exists`,
+        userFriendlyMessage: msg`An entity with this name already exists`,
+      });
+    }
+
+    // Pattern 3: Foreign key validation
+    if (isDefined(flatMyEntity.parentEntityId)) {
+      const parentEntity = optimisticFlatParentEntityMaps.byId[flatMyEntity.parentEntityId];
+
+      if (!isDefined(parentEntity)) {
+        errors.push({
+          code: MyEntityExceptionCode.PARENT_ENTITY_NOT_FOUND,
+          message: t`Parent entity with ID ${flatMyEntity.parentEntityId} not found`,
+          userFriendlyMessage: msg`The specified parent entity does not exist`,
+        });
+      } else if (isDefined(parentEntity.deletedAt)) {
+        errors.push({
+          code: MyEntityExceptionCode.PARENT_ENTITY_DELETED,
+          message: t`Parent entity is deleted`,
+          userFriendlyMessage: msg`Cannot reference a deleted parent entity`,
+        });
+      }
+    }
+
+    // Pattern 4: Standard entity protection
+    if (flatMyEntity.isCustom === false) {
+      errors.push({
+        code: MyEntityExceptionCode.STANDARD_ENTITY_CANNOT_BE_CREATED,
+        message: t`Cannot create standard entity`,
+        userFriendlyMessage: msg`Standard entities can only be created by the system`,
+      });
+    }
+
+    return errors;
+  }
+
+  validateMyEntityForUpdate(
+    flatMyEntity: FlatMyEntity,
+    updates: Partial<FlatMyEntity>,
+    optimisticFlatMyEntityMaps: FlatMyEntityMaps,
+  ): WorkspaceMigrationValidationError[] {
+    const errors: WorkspaceMigrationValidationError[] = [];
+
+    // Standard entity protection
+    if (flatMyEntity.isCustom === false) {
+      errors.push({
+        code: MyEntityExceptionCode.STANDARD_ENTITY_CANNOT_BE_UPDATED,
+        message: t`Cannot update standard entity`,
+        userFriendlyMessage: msg`Standard entities cannot be modified`,
+      });
+      return errors; // Early return if standard
+    }
+
+    // Uniqueness check for name changes
+    if (isDefined(updates.name) && updates.name !== flatMyEntity.name) {
+      const existingEntityWithName = optimisticFlatMyEntityMaps.byName[updates.name];
+
+      if (isDefined(existingEntityWithName) && existingEntityWithName.id !== flatMyEntity.id) {
+        errors.push({
+          code: MyEntityExceptionCode.MY_ENTITY_ALREADY_EXISTS,
+          message: t`Entity with name ${updates.name} already exists`,
+          userFriendlyMessage: msg`An entity with this name already exists`,
+        });
+      }
+    }
+
+    return errors;
+  }
+
+  validateMyEntityForDelete(
+    flatMyEntity: FlatMyEntity,
+  ): WorkspaceMigrationValidationError[] {
+    const errors: WorkspaceMigrationValidationError[] = [];
+
+    // Standard entity protection
+    if (flatMyEntity.isCustom === false) {
+      errors.push({
+        code: MyEntityExceptionCode.STANDARD_ENTITY_CANNOT_BE_DELETED,
+        message: t`Cannot delete standard entity`,
+        userFriendlyMessage: msg`Standard entities cannot be deleted`,
+      });
+    }
+
+    return errors;
+  }
+}
+```
+
+**Performance warning**: Avoid `Object.values().find()` - use indexed maps instead!
+
+```typescript
+// ❌ BAD: O(n) - slow for large datasets
+const duplicate = Object.values(optimisticFlatMyEntityMaps.byId).find(
+  (entity) => entity.name === flatMyEntity.name && entity.id !== flatMyEntity.id
+);
+
+// ✅ GOOD: O(1) - use indexed map
+const existingEntityWithName = optimisticFlatMyEntityMaps.byName[flatMyEntity.name];
+if (isDefined(existingEntityWithName) && existingEntityWithName.id !== flatMyEntity.id) {
+  // Handle duplicate
+}
+```
+
+---
+
+## Step 2: Create Builder Service
+
+**File**: `src/engine/workspace-manager/workspace-migration/workspace-migration-builder/builders/my-entity/workspace-migration-my-entity-actions-builder.service.ts`
+
+```typescript
+import { Injectable } from '@nestjs/common';
+
+import { WorkspaceEntityMigrationBuilderService } from 'src/engine/workspace-manager/workspace-migration/workspace-migration-builder/workspace-entity-migration-builder.service';
+import { FlatMyEntityValidatorService } from 'src/engine/workspace-manager/workspace-migration/workspace-migration-builder/validators/services/flat-my-entity-validator.service';
+import { type UniversalFlatMyEntity } from 'src/engine/workspace-manager/workspace-migration/universal-flat-entity/types/universal-flat-my-entity.type';
+import {
+  type UniversalCreateMyEntityAction,
+  type UniversalUpdateMyEntityAction,
+  type UniversalDeleteMyEntityAction,
+} from 'src/engine/workspace-manager/workspace-migration/workspace-migration-builder/builders/my-entity/types/workspace-migration-my-entity-action.type';
+
+@Injectable()
+export class WorkspaceMigrationMyEntityActionsBuilderService extends WorkspaceEntityMigrationBuilderService<
+  'myEntity',
+  UniversalFlatMyEntity,
+  UniversalCreateMyEntityAction,
+  UniversalUpdateMyEntityAction,
+  UniversalDeleteMyEntityAction
+> {
+  constructor(
+    private readonly flatMyEntityValidatorService: FlatMyEntityValidatorService,
+  ) {
+    super();
+  }
+
+  protected buildCreateAction(
+    universalFlatMyEntity: UniversalFlatMyEntity,
+    flatEntityMaps: AllFlatEntityMapsByMetadataName,
+  ): BuildWorkspaceMigrationActionReturnType<UniversalCreateMyEntityAction> {
+    const validationResult = this.flatMyEntityValidatorService.validateMyEntityForCreate(
+      universalFlatMyEntity,
+      flatEntityMaps.flatMyEntityMaps,
+    );
+
+    if (validationResult.length > 0) {
+      return {
+        status: 'failed',
+        errors: validationResult,
+      };
+    }
+
+    return {
+      status: 'success',
+      action: {
+        type: 'create',
+        metadataName: 'myEntity',
+        universalFlatEntity: universalFlatMyEntity,
+      },
+    };
+  }
+
+  protected buildUpdateAction(
+    universalFlatMyEntity: UniversalFlatMyEntity,
+    universalUpdates: Partial<UniversalFlatMyEntity>,
+    flatEntityMaps: AllFlatEntityMapsByMetadataName,
+  ): BuildWorkspaceMigrationActionReturnType<UniversalUpdateMyEntityAction> {
+    const validationResult = this.flatMyEntityValidatorService.validateMyEntityForUpdate(
+      universalFlatMyEntity,
+      universalUpdates,
+      flatEntityMaps.flatMyEntityMaps,
+    );
+
+    if (validationResult.length > 0) {
+      return {
+        status: 'failed',
+        errors: validationResult,
+      };
+    }
+
+    return {
+      status: 'success',
+      action: {
+        type: 'update',
+        metadataName: 'myEntity',
+        universalFlatEntity: universalFlatMyEntity,
+        universalUpdates,
+      },
+    };
+  }
+
+  protected buildDeleteAction(
+    universalFlatMyEntity: UniversalFlatMyEntity,
+  ): BuildWorkspaceMigrationActionReturnType<UniversalDeleteMyEntityAction> {
+    const validationResult = this.flatMyEntityValidatorService.validateMyEntityForDelete(
+      universalFlatMyEntity,
+    );
+
+    if (validationResult.length > 0) {
+      return {
+        status: 'failed',
+        errors: validationResult,
+      };
+    }
+
+    return {
+      status: 'success',
+      action: {
+        type: 'delete',
+        metadataName: 'myEntity',
+        universalFlatEntity: universalFlatMyEntity,
+      },
+    };
+  }
+}
+```
+
+---
+
+## Step 3: Wire into Orchestrator (**CRITICAL**)
+
+**File**: `src/engine/workspace-manager/workspace-migration/workspace-migration-builder/workspace-migration-build-orchestrator.service.ts`
+
+```typescript
+@Injectable()
+export class WorkspaceMigrationBuildOrchestratorService {
+  constructor(
+    // ... existing builders
+    private readonly workspaceMigrationMyEntityActionsBuilderService: WorkspaceMigrationMyEntityActionsBuilderService,
+  ) {}
+
+  async buildWorkspaceMigration({
+    allFlatEntityOperationByMetadataName,
+    flatEntityMaps,
+    isSystemBuild,
+  }: BuildWorkspaceMigrationInput): Promise<BuildWorkspaceMigrationOutput> {
+    // ... existing code
+
+    // Add your entity builder
+    const myEntityResult = await this.workspaceMigrationMyEntityActionsBuilderService.build({
+      flatEntitiesToCreate: allFlatEntityOperationByMetadataName.myEntity?.flatEntityToCreate ?? [],
+      flatEntitiesToUpdate: allFlatEntityOperationByMetadataName.myEntity?.flatEntityToUpdate ?? [],
+      flatEntitiesToDelete: allFlatEntityOperationByMetadataName.myEntity?.flatEntityToDelete ?? [],
+      flatEntityMaps,
+      isSystemBuild,
+    });
+
+    // ... aggregate errors
+
+    return {
+      status: aggregatedErrors.length > 0 ? 'failed' : 'success',
+      errors: aggregatedErrors,
+      actions: [
+        ...existingActions,
+        ...myEntityResult.actions,
+      ],
+    };
+  }
+}
+```
+
+**⚠️ This step is the most commonly forgotten!** Your entity won't sync without orchestrator wiring.
+
+---
+
+## Validation Patterns
+
+### Pattern 1: Required Field
+```typescript
+if (!isDefined(field) || field.trim() === '') {
+  errors.push({ code: ..., message: ..., userFriendlyMessage: ... });
+}
+```
+
+### Pattern 2: Uniqueness (O(1) lookup)
+```typescript
+const existing = optimisticMaps.byName[entity.name];
+if (isDefined(existing) && existing.id !== entity.id) {
+  errors.push({ ... });
+}
+```
+
+### Pattern 3: Foreign Key Validation
+```typescript
+if (isDefined(entity.parentId)) {
+  const parent = parentMaps.byId[entity.parentId];
+  if (!isDefined(parent)) {
+    errors.push({ code: NOT_FOUND, ... });
+  } else if (isDefined(parent.deletedAt)) {
+    errors.push({ code: DELETED, ... });
+  }
+}
+```
+
+### Pattern 4: Standard Entity Protection
+```typescript
+if (entity.isCustom === false) {
+  errors.push({ code: STANDARD_ENTITY_PROTECTED, ... });
+  return errors; // Early return
+}
+```
+
+---
+
+## Checklist
+
+Before moving to Step 4:
+
+- [ ] Validator service created
+- [ ] Validator **never throws** (returns error arrays)
+- [ ] Validator **never mutates** (uses optimistic maps)
+- [ ] All uniqueness checks use indexed maps (O(1))
+- [ ] Required field validation implemented
+- [ ] Foreign key validation implemented
+- [ ] Standard entity protection implemented
+- [ ] Builder service extends `WorkspaceEntityMigrationBuilderService`
+- [ ] Builder creates actions with universal entities
+- [ ] **Builder wired into orchestrator** (**CRITICAL**)
+- [ ] **Builder injected in orchestrator constructor**
+- [ ] **Builder called in `buildWorkspaceMigration`**
+- [ ] **Actions added to orchestrator return statement**
+
+---
+
+## Next Step
+
+Once builder and validation are complete, proceed to:
+**[Syncable Entity: Runner & Actions (Step 4/6)](../syncable-entity-runner-and-actions/SKILL.md)**
+
+For complete workflow, see `@creating-syncable-entity` rule.

.cursor/skills/syncable-entity-cache-and-transform/SKILL.md

@@ -0,0 +1,303 @@
+---
+name: syncable-entity-cache-and-transform
+description: Create cache services and transformation utilities for syncable entities in Twenty. Use when implementing entity-to-flat conversions, input DTO transpilation to universal flat entities, or cache recomputation for syncable entities.
+---
+
+# Syncable Entity: Cache & Transform (Step 2/6)
+
+**Purpose**: Create cache layer and transformation utilities to convert between different entity representations.
+
+**When to use**: After completing Step 1 (Types & Constants). Required before building validators and action handlers.
+
+---
+
+## Quick Start
+
+This step creates:
+1. Cache service for flat entity maps
+2. Entity-to-flat conversion utility
+3. Input transform utils (DTO → Universal Flat Entity)
+
+**Key principle**: Input transform utils must output **universal flat entities** (with `universalIdentifier` and foreign keys mapped to universal identifiers).
+
+---
+
+## Step 1: Create Cache Service
+
+**File**: `src/engine/metadata-modules/flat-my-entity/services/flat-my-entity-cache.service.ts`
+
+```typescript
+import { Injectable } from '@nestjs/common';
+import { InjectRepository } from '@nestjs/typeorm';
+import { Repository } from 'typeorm';
+import { v4 } from 'uuid';
+
+import { WorkspaceCache } from 'src/engine/twenty-orm/decorators/workspace-cache.decorator';
+import { MyEntityEntity } from 'src/engine/metadata-modules/my-entity/entities/my-entity.entity';
+import { type FlatMyEntityMaps } from 'src/engine/metadata-modules/flat-my-entity/types/flat-my-entity-maps.type';
+import { fromMyEntityEntityToFlatMyEntity } from 'src/engine/metadata-modules/flat-my-entity/utils/from-my-entity-entity-to-flat-my-entity.util';
+
+@Injectable()
+export class FlatMyEntityCacheService {
+  constructor(
+    @InjectRepository(MyEntityEntity, 'metadata')
+    private readonly myEntityRepository: Repository<MyEntityEntity>,
+  ) {}
+
+  @WorkspaceCache({ flatMapsKey: 'flatMyEntityMaps' })
+  async getFlatMyEntityMaps(): Promise<FlatMyEntityMaps> {
+    const myEntities = await this.myEntityRepository.find({
+      withDeleted: true, // CRITICAL: Include soft-deleted entities
+    });
+
+    const flatMyEntities = myEntities.map((entity) =>
+      fromMyEntityEntityToFlatMyEntity(entity),
+    );
+
+    return {
+      byId: Object.fromEntries(flatMyEntities.map((e) => [e.id, e])),
+      byName: Object.fromEntries(flatMyEntities.map((e) => [e.name, e])),
+    };
+  }
+}
+```
+
+**Critical rules**:
+- Use `@WorkspaceCache` decorator with unique `flatMapsKey`
+- **Always** use `withDeleted: true` to include soft-deleted entities
+- Cache key pattern: `flat{EntityName}Maps` (camelCase)
+
+---
+
+## Step 2: Entity-to-Flat Conversion
+
+**File**: `src/engine/metadata-modules/flat-my-entity/utils/from-my-entity-entity-to-flat-my-entity.util.ts`
+
+```typescript
+import { v4 } from 'uuid';
+import { type MyEntityEntity } from 'src/engine/metadata-modules/my-entity/entities/my-entity.entity';
+import { type FlatMyEntity } from 'src/engine/metadata-modules/flat-my-entity/types/flat-my-entity.type';
+
+export const fromMyEntityEntityToFlatMyEntity = (
+  entity: MyEntityEntity,
+): FlatMyEntity => {
+  return {
+    id: entity.id,
+    // Critical: generate a new UUID for universalIdentifier
+    universalIdentifier: v4(),
+    workspaceId: entity.workspaceId,
+    applicationId: entity.applicationId,
+    name: entity.name,
+    label: entity.label,
+    description: entity.description,
+    isCustom: entity.isCustom,
+    parentEntityId: entity.parentEntityId,
+    settings: entity.settings,
+    createdAt: entity.createdAt.toISOString(),
+    updatedAt: entity.updatedAt.toISOString(),
+    deletedAt: entity.deletedAt?.toISOString() ?? null,
+  };
+};
+```
+
+**Critical**: `universalIdentifier` must be a new UUID generated with `v4()` (not `entity.id`)
+
+---
+
+## Step 3: Input Transform Utils (DTO → Universal Flat Entity)
+
+**File**: `src/engine/metadata-modules/flat-my-entity/utils/from-create-my-entity-input-to-universal-flat-my-entity.util.ts`
+
+```typescript
+import { v4 } from 'uuid';
+import { sanitizeString } from 'twenty-shared/string';
+import { type CreateMyEntityInput } from 'src/engine/metadata-modules/my-entity/dtos/create-my-entity.input';
+import { type UniversalFlatMyEntity } from 'src/engine/workspace-manager/workspace-migration/universal-flat-entity/types/universal-flat-my-entity.type';
+import { resolveEntityRelationUniversalIdentifiers } from 'src/engine/metadata-modules/flat-entity/utils/resolve-entity-relation-universal-identifiers.util';
+import { type AllFlatEntityMapsByMetadataName } from 'src/engine/metadata-modules/flat-entity/types/all-flat-entity-maps-by-metadata-name.type';
+
+export const fromCreateMyEntityInputToUniversalFlatMyEntity = ({
+  input,
+  workspaceId,
+  flatEntityMaps,
+}: {
+  input: CreateMyEntityInput;
+  workspaceId: string;
+  flatEntityMaps?: AllFlatEntityMapsByMetadataName;
+}): UniversalFlatMyEntity => {
+  const id = v4();
+  const universalIdentifier = v4();
+
+  // 1. Extract foreign key IDs BEFORE sanitization
+  const parentEntityId = input.parentEntityId ?? null;
+
+  // 2. Sanitize string properties
+  const name = sanitizeString(input.name);
+  const label = sanitizeString(input.label);
+  const description = input.description ? sanitizeString(input.description) : null;
+
+  // 3. Build base flat entity
+  const baseFlatEntity = {
+    id,
+    universalIdentifier,
+    workspaceId,
+    applicationId: null,
+    name,
+    label,
+    description,
+    isCustom: true,
+    parentEntityId,
+    settings: input.settings ?? null,
+    createdAt: new Date().toISOString(),
+    updatedAt: new Date().toISOString(),
+    deletedAt: null,
+  };
+
+  // 4. Resolve foreign keys to universal identifiers (if flatEntityMaps provided)
+  if (flatEntityMaps) {
+    return resolveEntityRelationUniversalIdentifiers({
+      metadataName: 'myEntity',
+      flatEntity: baseFlatEntity,
+      flatEntityMaps,
+    });
+  }
+
+  // 5. Return with null universal foreign keys if no maps
+  return {
+    ...baseFlatEntity,
+    parentEntityUniversalIdentifier: null,
+  };
+};
+```
+
+**Key steps**:
+1. Generate IDs (`id` and `universalIdentifier` with `v4()`)
+2. Extract foreign keys **before** sanitization
+3. Sanitize all string properties
+4. Build base flat entity
+5. Resolve foreign keys → universal identifiers
+
+---
+
+## Step 4: Create Flat Entity Module
+
+**File**: `src/engine/metadata-modules/flat-my-entity/flat-my-entity.module.ts`
+
+```typescript
+import { Module } from '@nestjs/common';
+import { TypeOrmModule } from '@nestjs/typeorm';
+
+import { MyEntityEntity } from 'src/engine/metadata-modules/my-entity/entities/my-entity.entity';
+import { FlatMyEntityCacheService } from 'src/engine/metadata-modules/flat-my-entity/services/flat-my-entity-cache.service';
+
+@Module({
+  imports: [TypeOrmModule.forFeature([MyEntityEntity], 'metadata')],
+  providers: [FlatMyEntityCacheService],
+  exports: [FlatMyEntityCacheService],
+})
+export class FlatMyEntityModule {}
+```
+
+**Rules**:
+- Import entity with `'metadata'` datasource
+- Export cache service for use in other modules
+
+---
+
+## Common Patterns
+
+### Pattern: Foreign Key Resolution
+
+```typescript
+// Extract foreign keys BEFORE sanitization
+const parentEntityId = input.parentEntityId ?? null;
+
+// After building base entity, resolve to universal identifiers
+const universalFlatEntity = resolveEntityRelationUniversalIdentifiers({
+  metadataName: 'myEntity',
+  flatEntity: baseFlatEntity,
+  flatEntityMaps,
+});
+```
+
+### Pattern: JSONB with SerializedRelation
+
+```typescript
+// For JSONB properties containing foreign keys
+const settings = input.settings
+  ? {
+      ...input.settings,
+      fieldMetadataId: input.settings.fieldMetadataId,
+    }
+  : null;
+
+// After resolution, JSONB foreign keys become universal identifiers
+return resolveEntityRelationUniversalIdentifiers({
+  metadataName: 'myEntity',
+  flatEntity: { ...baseFlatEntity, settings },
+  flatEntityMaps,
+});
+```
+
+### Pattern: Update Transform
+
+```typescript
+// from-update-my-entity-input-to-universal-flat-my-entity-updates.util.ts
+export const fromUpdateMyEntityInputToUniversalFlatMyEntityUpdates = ({
+  input,
+  flatEntityMaps,
+}: {
+  input: UpdateMyEntityInput;
+  flatEntityMaps?: AllFlatEntityMapsByMetadataName;
+}): Partial<UniversalFlatMyEntity> => {
+  const updates: Partial<UniversalFlatMyEntity> = {};
+
+  if (input.name !== undefined) {
+    updates.name = sanitizeString(input.name);
+  }
+
+  if (input.parentEntityId !== undefined) {
+    updates.parentEntityId = input.parentEntityId;
+  }
+
+  updates.updatedAt = new Date().toISOString();
+
+  // Resolve foreign keys if maps provided
+  if (flatEntityMaps) {
+    return resolveEntityRelationUniversalIdentifiers({
+      metadataName: 'myEntity',
+      flatEntity: updates as any,
+      flatEntityMaps,
+    });
+  }
+
+  return updates;
+};
+```
+
+---
+
+## Checklist
+
+Before moving to Step 3:
+
+- [ ] Cache service created with `@WorkspaceCache` decorator
+- [ ] Cache uses `withDeleted: true`
+- [ ] Cache key follows `flat{EntityName}Maps` pattern
+- [ ] Entity-to-flat conversion implemented
+- [ ] `universalIdentifier` set correctly (generated with `v4()`)
+- [ ] Create input transform implemented
+- [ ] Update input transform implemented (if needed)
+- [ ] Foreign keys extracted before sanitization
+- [ ] String properties sanitized
+- [ ] Foreign keys resolved to universal identifiers
+- [ ] Flat entity module created and exports cache service
+
+---
+
+## Next Step
+
+Once cache and transform utilities are complete, proceed to:
+**[Syncable Entity: Builder & Validation (Step 3/6)](../syncable-entity-builder-and-validation/SKILL.md)**
+
+For complete workflow, see `@creating-syncable-entity` rule.

.cursor/skills/syncable-entity-integration/SKILL.md

@@ -0,0 +1,326 @@
+---
+name: syncable-entity-integration
+description: Wire syncable entity services into NestJS modules, create service layer and resolvers for Twenty entities. Use when registering builders, validators, and action handlers in modules, creating business services, or exposing entities via GraphQL API with proper exception handling.
+---
+
+# Syncable Entity: Integration (Step 5/6)
+
+**Purpose**: Wire everything together, register in modules, create services and resolvers.
+
+**When to use**: After completing Steps 1-4 (all previous steps). Required before testing.
+
+---
+
+## Quick Start
+
+This step:
+1. Registers services in 3 NestJS modules
+2. Creates service layer (returns flat entities)
+3. Creates resolver layer (converts flat → DTO)
+4. Uses exception interceptor for GraphQL
+
+**Key principle**: Services return flat entities, resolvers transpile flat → DTO.
+
+---
+
+## Step 1: Register in Builder Module
+
+**File**: `src/engine/workspace-manager/workspace-migration/workspace-migration-builder/workspace-migration-builder.module.ts`
+
+```typescript
+import { WorkspaceMigrationMyEntityActionsBuilderService } from 'src/engine/workspace-manager/workspace-migration/workspace-migration-builder/builders/my-entity/workspace-migration-my-entity-actions-builder.service';
+
+@Module({
+  imports: [
+    // ... existing imports
+  ],
+  providers: [
+    // ... existing providers
+    WorkspaceMigrationMyEntityActionsBuilderService,
+  ],
+  exports: [
+    // ... existing exports
+    WorkspaceMigrationMyEntityActionsBuilderService,
+  ],
+})
+export class WorkspaceMigrationBuilderModule {}
+```
+
+**Important**: Add to both `providers` AND `exports` (builder needs to be exported for orchestrator).
+
+---
+
+## Step 2: Register in Validators Module
+
+**File**: `src/engine/workspace-manager/workspace-migration/workspace-migration-builder/validators/workspace-migration-builder-validators.module.ts`
+
+```typescript
+import { FlatMyEntityValidatorService } from 'src/engine/workspace-manager/workspace-migration/workspace-migration-builder/validators/services/flat-my-entity-validator.service';
+
+@Module({
+  imports: [
+    // ... existing imports
+  ],
+  providers: [
+    // ... existing providers
+    FlatMyEntityValidatorService,
+  ],
+  exports: [
+    // ... existing exports
+    FlatMyEntityValidatorService,
+  ],
+})
+export class WorkspaceMigrationBuilderValidatorsModule {}
+```
+
+---
+
+## Step 3: Register Action Handlers
+
+**File**: `src/engine/workspace-manager/workspace-migration/workspace-migration-runner/action-handlers/workspace-schema-migration-runner-action-handlers.module.ts`
+
+```typescript
+import { CreateMyEntityActionHandlerService } from 'src/engine/workspace-manager/workspace-migration/workspace-migration-runner/action-handlers/my-entity/services/create-my-entity-action-handler.service';
+import { UpdateMyEntityActionHandlerService } from 'src/engine/workspace-manager/workspace-migration/workspace-migration-runner/action-handlers/my-entity/services/update-my-entity-action-handler.service';
+import { DeleteMyEntityActionHandlerService } from 'src/engine/workspace-manager/workspace-migration/workspace-migration-runner/action-handlers/my-entity/services/delete-my-entity-action-handler.service';
+
+@Module({
+  imports: [
+    // ... existing imports
+  ],
+  providers: [
+    // ... existing providers
+    CreateMyEntityActionHandlerService,
+    UpdateMyEntityActionHandlerService,
+    DeleteMyEntityActionHandlerService,
+  ],
+  exports: [
+    // ... existing exports (action handlers typically not exported)
+  ],
+})
+export class WorkspaceSchemaMigrationRunnerActionHandlersModule {}
+```
+
+**Note**: Action handlers are typically only in `providers`, not `exports`.
+
+---
+
+## Step 4: Create Service Layer
+
+**File**: `src/engine/metadata-modules/my-entity/my-entity.service.ts`
+
+```typescript
+import { Injectable } from '@nestjs/common';
+import { isDefined } from 'twenty-shared/utils';
+
+import { type FlatMyEntity } from 'src/engine/metadata-modules/flat-my-entity/types/flat-my-entity.type';
+import { WorkspaceManyOrAllFlatEntityMapsCacheService } from 'src/engine/metadata-modules/flat-entity/services/workspace-many-or-all-flat-entity-maps-cache.service';
+import { findFlatEntityByIdInFlatEntityMapsOrThrow } from 'src/engine/metadata-modules/flat-entity/utils/find-flat-entity-by-id-in-flat-entity-maps-or-throw.util';
+import { fromCreateMyEntityInputToUniversalFlatMyEntity } from 'src/engine/metadata-modules/flat-my-entity/utils/from-create-my-entity-input-to-universal-flat-my-entity.util';
+import { WorkspaceMigrationBuilderException } from 'src/engine/workspace-manager/workspace-migration/exceptions/workspace-migration-builder-exception';
+import { WorkspaceMigrationValidateBuildAndRunService } from 'src/engine/workspace-manager/workspace-migration/services/workspace-migration-validate-build-and-run-service';
+
+@Injectable()
+export class MyEntityService {
+  constructor(
+    private readonly workspaceMigrationValidateBuildAndRunService: WorkspaceMigrationValidateBuildAndRunService,
+    private readonly workspaceManyOrAllFlatEntityMapsCacheService: WorkspaceManyOrAllFlatEntityMapsCacheService,
+  ) {}
+
+  async create(input: CreateMyEntityInput, workspaceId: string): Promise<FlatMyEntity> {
+    // 1. Transform input to universal flat entity
+    const universalFlatMyEntityToCreate = fromCreateMyEntityInputToUniversalFlatMyEntity({
+      input,
+      workspaceId,
+    });
+
+    // 2. Validate, build, and run
+    const result =
+      await this.workspaceMigrationValidateBuildAndRunService.validateBuildAndRunWorkspaceMigration(
+        {
+          allFlatEntityOperationByMetadataName: {
+            myEntity: {
+              flatEntityToCreate: [universalFlatMyEntityToCreate],
+              flatEntityToDelete: [],
+              flatEntityToUpdate: [],
+            },
+          },
+          workspaceId,
+          isSystemBuild: false,
+        },
+      );
+
+    // 3. Throw if validation failed
+    if (isDefined(result)) {
+      throw new WorkspaceMigrationBuilderException(
+        result,
+        'Validation errors occurred while creating entity',
+      );
+    }
+
+    // 4. Return freshly cached flat entity
+    const { flatMyEntityMaps } =
+      await this.workspaceManyOrAllFlatEntityMapsCacheService.getOrRecomputeManyOrAllFlatEntityMaps(
+        {
+          workspaceId,
+          flatMapsKeys: ['flatMyEntityMaps'],
+        },
+      );
+
+    return findFlatEntityByIdInFlatEntityMapsOrThrow({
+      flatEntityId: universalFlatMyEntityToCreate.id,
+      flatEntityMaps: flatMyEntityMaps,
+    });
+  }
+}
+```
+
+**Service pattern**:
+1. Transform input → universal flat entity
+2. Call `validateBuildAndRunWorkspaceMigration`
+3. Throw if validation errors
+4. **Return flat entity** (not DTO)
+
+---
+
+## Step 5: Create Resolver Layer
+
+**File**: `src/engine/metadata-modules/my-entity/my-entity.resolver.ts`
+
+```typescript
+import { UseInterceptors } from '@nestjs/common';
+import { Args, Mutation, Resolver } from '@nestjs/graphql';
+
+import { WorkspaceMigrationGraphqlApiExceptionInterceptor } from 'src/engine/workspace-manager/workspace-migration/interceptors/workspace-migration-graphql-api-exception.interceptor';
+import { MyEntityService } from 'src/engine/metadata-modules/my-entity/my-entity.service';
+import { fromFlatMyEntityToMyEntityDto } from 'src/engine/metadata-modules/my-entity/utils/from-flat-my-entity-to-my-entity-dto.util';
+
+@Resolver(() => MyEntityDto)
+@UseInterceptors(WorkspaceMigrationGraphqlApiExceptionInterceptor)
+export class MyEntityResolver {
+  constructor(private readonly myEntityService: MyEntityService) {}
+
+  @Mutation(() => MyEntityDto)
+  async createMyEntity(
+    @Args('input') input: CreateMyEntityInput,
+    @Workspace() { id: workspaceId }: Workspace,
+  ): Promise<MyEntityDto> {
+    // Service returns flat entity
+    const flatMyEntity = await this.myEntityService.create(input, workspaceId);
+    
+    // Resolver converts flat entity to DTO
+    return fromFlatMyEntityToMyEntityDto(flatMyEntity);
+  }
+
+  @Mutation(() => MyEntityDto)
+  async updateMyEntity(
+    @Args('id') id: string,
+    @Args('input') input: UpdateMyEntityInput,
+    @Workspace() { id: workspaceId }: Workspace,
+  ): Promise<MyEntityDto> {
+    const flatMyEntity = await this.myEntityService.update(id, input, workspaceId);
+    return fromFlatMyEntityToMyEntityDto(flatMyEntity);
+  }
+
+  @Mutation(() => Boolean)
+  async deleteMyEntity(
+    @Args('id') id: string,
+    @Workspace() { id: workspaceId }: Workspace,
+  ) {
+    await this.myEntityService.delete(id, workspaceId);
+    return true;
+  }
+}
+```
+
+**Resolver responsibilities**:
+- Receives flat entities from service
+- **Converts flat → DTO** using conversion utility
+- Returns DTOs to GraphQL API
+- Uses exception interceptor for error formatting
+
+---
+
+## Step 6: Flat-to-DTO Conversion
+
+**File**: `src/engine/metadata-modules/my-entity/utils/from-flat-my-entity-to-my-entity-dto.util.ts`
+
+```typescript
+import { type FlatMyEntity } from 'src/engine/metadata-modules/flat-my-entity/types/flat-my-entity.type';
+import { type MyEntityDto } from 'src/engine/metadata-modules/my-entity/dtos/my-entity.dto';
+
+export const fromFlatMyEntityToMyEntityDto = (
+  flatMyEntity: FlatMyEntity,
+): MyEntityDto => {
+  return {
+    id: flatMyEntity.id,
+    name: flatMyEntity.name,
+    label: flatMyEntity.label,
+    description: flatMyEntity.description,
+    isCustom: flatMyEntity.isCustom,
+    createdAt: flatMyEntity.createdAt,
+    updatedAt: flatMyEntity.updatedAt,
+    // Convert foreign key IDs to relation objects if needed
+    // parentEntity: flatMyEntity.parentEntityId ? { id: flatMyEntity.parentEntityId } : null,
+  };
+};
+```
+
+---
+
+## Layer Responsibilities
+
+| Layer | Input | Output | Responsibility |
+|-------|-------|--------|----------------|
+| **Service** | Input DTO | Flat Entity | Business logic, validation orchestration |
+| **Resolver** | Service result | DTO | Flat → DTO conversion, GraphQL exposure |
+
+**Service Layer**:
+- Works with flat entities internally
+- Returns `FlatMyEntity` type
+- No knowledge of DTOs or GraphQL types
+
+**Resolver Layer**:
+- Receives flat entities from service
+- Converts flat entities to DTOs
+- Returns DTOs to GraphQL API
+
+---
+
+## Exception Interceptor
+
+The `WorkspaceMigrationGraphqlApiExceptionInterceptor` automatically handles:
+
+1. `FlatEntityMapsException` → Converts to GraphQL errors (NotFoundError, etc.)
+2. `WorkspaceMigrationBuilderException` → Formats validation errors with i18n
+3. `WorkspaceMigrationRunnerException` → Formats runner errors
+
+**What it does**:
+- Catches exceptions and formats for API responses
+- Translates error messages based on user locale
+- Ensures consistent error structure for frontend
+
+---
+
+## Checklist
+
+Before moving to Step 6 (Testing):
+
+- [ ] Builder registered in builder module (providers + exports)
+- [ ] Validator registered in validators module (providers + exports)
+- [ ] All 3 action handlers registered in action handlers module (providers)
+- [ ] Service layer created
+- [ ] Service returns flat entities (not DTOs)
+- [ ] Resolver layer created
+- [ ] Resolver uses exception interceptor
+- [ ] Resolver converts flat → DTO
+- [ ] Flat-to-DTO conversion utility created
+
+---
+
+## Next Step
+
+Once integration is complete, proceed to (**MANDATORY**):
+**[Syncable Entity: Integration Testing (Step 6/6)](../syncable-entity-testing/SKILL.md)**
+
+For complete workflow, see `@creating-syncable-entity` rule.

.cursor/skills/syncable-entity-runner-and-actions/SKILL.md

@@ -0,0 +1,355 @@
+---
+name: syncable-entity-runner-and-actions
+description: Implement action handlers for executing workspace migrations in Twenty. Use when creating database operations for syncable entities, implementing universal-to-flat entity transpilation, or handling create/update/delete actions in the runner layer.
+---
+
+# Syncable Entity: Runner & Actions (Step 4/6)
+
+**Purpose**: Execute migration actions against the database with proper transpilation from universal to flat entities.
+
+**When to use**: After completing Steps 1-3 (Types, Cache, Builder). Required before integration.
+
+---
+
+## Quick Start
+
+This step creates:
+1. Create action handler
+2. Update action handler
+3. Delete action handler
+4. Universal-to-flat conversion utilities
+
+**Key pattern**: Each handler has two phases:
+1. **Transpilation**: Universal action → Flat action
+2. **Execution**: Flat action → Database operation
+
+---
+
+## Step 1: Create Action Handler
+
+**File**: `src/engine/workspace-manager/workspace-migration/workspace-migration-runner/action-handlers/my-entity/services/create-my-entity-action-handler.service.ts`
+
+```typescript
+import { Injectable } from '@nestjs/common';
+import { InjectRepository } from '@nestjs/typeorm';
+import { Repository } from 'typeorm';
+
+import { WorkspaceCreateActionHandlerService } from 'src/engine/workspace-manager/workspace-migration/workspace-migration-runner/action-handlers/workspace-create-action-handler.service';
+import { MyEntityEntity } from 'src/engine/metadata-modules/my-entity/entities/my-entity.entity';
+import { fromUniversalFlatMyEntityToFlatMyEntity } from 'src/engine/workspace-manager/workspace-migration/workspace-migration-runner/action-handlers/my-entity/utils/from-universal-flat-my-entity-to-flat-my-entity.util';
+import {
+  type UniversalCreateMyEntityAction,
+  type FlatCreateMyEntityAction,
+} from 'src/engine/workspace-manager/workspace-migration/workspace-migration-builder/builders/my-entity/types/workspace-migration-my-entity-action.type';
+
+@Injectable()
+export class CreateMyEntityActionHandlerService extends WorkspaceCreateActionHandlerService<
+  'myEntity',
+  UniversalCreateMyEntityAction,
+  FlatCreateMyEntityAction
+> {
+  constructor(
+    @InjectRepository(MyEntityEntity, 'metadata')
+    private readonly myEntityRepository: Repository<MyEntityEntity>,
+  ) {
+    super();
+  }
+
+  // Phase 1: Transpile universal action to flat action
+  protected transpileUniversalActionToFlatAction(
+    universalAction: UniversalCreateMyEntityAction,
+    flatEntityMaps: AllFlatEntityMapsByMetadataName,
+  ): FlatCreateMyEntityAction {
+    return {
+      type: 'create',
+      metadataName: 'myEntity',
+      flatEntity: fromUniversalFlatMyEntityToFlatMyEntity(
+        universalAction.universalFlatEntity,
+        flatEntityMaps,
+      ),
+    };
+  }
+
+  // Phase 2: Execute flat action against database
+  protected async executeForMetadata(
+    flatActions: FlatCreateMyEntityAction[],
+  ): Promise<void> {
+    const flatEntities = flatActions.map((action) => action.flatEntity);
+
+    await this.insertFlatEntitiesInRepository({
+      repository: this.myEntityRepository,
+      flatEntities,
+    });
+  }
+
+  protected async executeForWorkspaceSchema(): Promise<void> {
+    // No workspace schema changes needed for metadata-only entity
+    return;
+  }
+}
+```
+
+**Key helper methods**:
+- `transpileUniversalActionToFlatAction`: Converts universal → flat
+- `insertFlatEntitiesInRepository`: Base class helper for inserts
+- `executeForMetadata`: Metadata database operations
+- `executeForWorkspaceSchema`: Workspace schema changes (if needed)
+
+---
+
+## Step 2: Update Action Handler
+
+**File**: `src/engine/workspace-manager/workspace-migration/workspace-migration-runner/action-handlers/my-entity/services/update-my-entity-action-handler.service.ts`
+
+```typescript
+import { Injectable } from '@nestjs/common';
+import { InjectRepository } from '@nestjs/typeorm';
+import { Repository } from 'typeorm';
+
+import { WorkspaceUpdateActionHandlerService } from 'src/engine/workspace-manager/workspace-migration/workspace-migration-runner/action-handlers/workspace-update-action-handler.service';
+import { MyEntityEntity } from 'src/engine/metadata-modules/my-entity/entities/my-entity.entity';
+import { fromUniversalFlatMyEntityToFlatMyEntity } from 'src/engine/workspace-manager/workspace-migration/workspace-migration-runner/action-handlers/my-entity/utils/from-universal-flat-my-entity-to-flat-my-entity.util';
+import { resolveUniversalUpdateRelationIdentifiersToIds } from 'src/engine/workspace-manager/workspace-migration/universal-flat-entity/utils/resolve-universal-relation-identifiers-to-ids.util';
+
+@Injectable()
+export class UpdateMyEntityActionHandlerService extends WorkspaceUpdateActionHandlerService<
+  'myEntity',
+  UniversalUpdateMyEntityAction,
+  FlatUpdateMyEntityAction
+> {
+  constructor(
+    @InjectRepository(MyEntityEntity, 'metadata')
+    private readonly myEntityRepository: Repository<MyEntityEntity>,
+  ) {
+    super();
+  }
+
+  protected transpileUniversalActionToFlatAction(
+    universalAction: UniversalUpdateMyEntityAction,
+    flatEntityMaps: AllFlatEntityMapsByMetadataName,
+  ): FlatUpdateMyEntityAction {
+    const flatEntity = fromUniversalFlatMyEntityToFlatMyEntity(
+      universalAction.universalFlatEntity,
+      flatEntityMaps,
+    );
+
+    // Resolve universal foreign keys in updates to regular IDs
+    const flatUpdates = resolveUniversalUpdateRelationIdentifiersToIds({
+      metadataName: 'myEntity',
+      universalUpdates: universalAction.universalUpdates,
+      flatEntityMaps,
+    });
+
+    return {
+      type: 'update',
+      metadataName: 'myEntity',
+      flatEntity,
+      updates: flatUpdates,
+    };
+  }
+
+  protected async executeForMetadata(
+    flatActions: FlatUpdateMyEntityAction[],
+  ): Promise<void> {
+    for (const action of flatActions) {
+      await this.myEntityRepository.update(
+        { id: action.flatEntity.id },
+        action.updates,
+      );
+    }
+  }
+
+  protected async executeForWorkspaceSchema(): Promise<void> {
+    return;
+  }
+}
+```
+
+**Update-specific helper**:
+- `resolveUniversalUpdateRelationIdentifiersToIds`: Maps universal identifiers back to regular IDs in the updates object
+
+---
+
+## Step 3: Delete Action Handler
+
+**File**: `src/engine/workspace-manager/workspace-migration/workspace-migration-runner/action-handlers/my-entity/services/delete-my-entity-action-handler.service.ts`
+
+```typescript
+import { Injectable } from '@nestjs/common';
+import { InjectRepository } from '@nestjs/typeorm';
+import { Repository } from 'typeorm';
+
+import { WorkspaceDeleteActionHandlerService } from 'src/engine/workspace-manager/workspace-migration/workspace-migration-runner/action-handlers/workspace-delete-action-handler.service';
+import { MyEntityEntity } from 'src/engine/metadata-modules/my-entity/entities/my-entity.entity';
+import { fromUniversalFlatMyEntityToFlatMyEntity } from 'src/engine/workspace-manager/workspace-migration/workspace-migration-runner/action-handlers/my-entity/utils/from-universal-flat-my-entity-to-flat-my-entity.util';
+
+@Injectable()
+export class DeleteMyEntityActionHandlerService extends WorkspaceDeleteActionHandlerService<
+  'myEntity',
+  UniversalDeleteMyEntityAction,
+  FlatDeleteMyEntityAction
+> {
+  constructor(
+    @InjectRepository(MyEntityEntity, 'metadata')
+    private readonly myEntityRepository: Repository<MyEntityEntity>,
+  ) {
+    super();
+  }
+
+  protected transpileUniversalActionToFlatAction(
+    universalAction: UniversalDeleteMyEntityAction,
+    flatEntityMaps: AllFlatEntityMapsByMetadataName,
+  ): FlatDeleteMyEntityAction {
+    // Use base class helper for delete transpilation
+    return this.transpileUniversalDeleteActionToFlatDeleteAction({
+      universalAction,
+      flatEntityMaps,
+      fromUniversalFlatEntityToFlatEntity: fromUniversalFlatMyEntityToFlatMyEntity,
+    });
+  }
+
+  protected async executeForMetadata(
+    flatActions: FlatDeleteMyEntityAction[],
+  ): Promise<void> {
+    const ids = flatActions.map((action) => action.flatEntity.id);
+
+    await this.myEntityRepository.delete(ids);
+  }
+
+  protected async executeForWorkspaceSchema(): Promise<void> {
+    return;
+  }
+}
+```
+
+**Delete-specific helper**:
+- `transpileUniversalDeleteActionToFlatDeleteAction`: Base class helper that handles standard delete transpilation
+
+---
+
+## Step 4: Universal-to-Flat Conversion
+
+**File**: `src/engine/workspace-manager/workspace-migration/workspace-migration-runner/action-handlers/my-entity/utils/from-universal-flat-my-entity-to-flat-my-entity.util.ts`
+
+```typescript
+import { resolveUniversalRelationIdentifiersToIds } from 'src/engine/workspace-manager/workspace-migration/universal-flat-entity/utils/resolve-universal-relation-identifiers-to-ids.util';
+import { type UniversalFlatMyEntity } from 'src/engine/workspace-manager/workspace-migration/universal-flat-entity/types/universal-flat-my-entity.type';
+import { type FlatMyEntity } from 'src/engine/metadata-modules/flat-my-entity/types/flat-my-entity.type';
+import { type AllFlatEntityMapsByMetadataName } from 'src/engine/metadata-modules/flat-entity/types/all-flat-entity-maps-by-metadata-name.type';
+
+export const fromUniversalFlatMyEntityToFlatMyEntity = (
+  universalFlatMyEntity: UniversalFlatMyEntity,
+  flatEntityMaps: AllFlatEntityMapsByMetadataName,
+): FlatMyEntity => {
+  // Resolve universal foreign keys back to regular IDs
+  return resolveUniversalRelationIdentifiersToIds({
+    metadataName: 'myEntity',
+    universalFlatEntity: universalFlatMyEntity,
+    flatEntityMaps,
+  }) as FlatMyEntity;
+};
+```
+
+**Key utility**:
+- `resolveUniversalRelationIdentifiersToIds`: Maps universal identifiers → regular IDs (reverse of `resolveEntityRelationUniversalIdentifiers`)
+
+---
+
+## Action Handler Patterns
+
+### Pattern: Create Handler
+```typescript
+// 1. Transpile: Universal → Flat
+protected transpileUniversalActionToFlatAction(
+  universalAction,
+  flatEntityMaps,
+) {
+  return {
+    type: 'create',
+    metadataName: 'myEntity',
+    flatEntity: fromUniversalFlatMyEntityToFlatMyEntity(
+      universalAction.universalFlatEntity,
+      flatEntityMaps,
+    ),
+  };
+}
+
+// 2. Execute: Flat → Database
+protected async executeForMetadata(flatActions) {
+  await this.insertFlatEntitiesInRepository({
+    repository: this.myEntityRepository,
+    flatEntities: flatActions.map(a => a.flatEntity),
+  });
+}
+```
+
+### Pattern: Update Handler
+```typescript
+// Transpile with update-specific resolution
+protected transpileUniversalActionToFlatAction(
+  universalAction,
+  flatEntityMaps,
+) {
+  const flatEntity = fromUniversalFlatMyEntityToFlatMyEntity(
+    universalAction.universalFlatEntity,
+    flatEntityMaps,
+  );
+
+  const flatUpdates = resolveUniversalUpdateRelationIdentifiersToIds({
+    metadataName: 'myEntity',
+    universalUpdates: universalAction.universalUpdates,
+    flatEntityMaps,
+  });
+
+  return { type: 'update', metadataName: 'myEntity', flatEntity, updates: flatUpdates };
+}
+```
+
+### Pattern: Delete Handler
+```typescript
+// Use base class helper
+protected transpileUniversalActionToFlatAction(
+  universalAction,
+  flatEntityMaps,
+) {
+  return this.transpileUniversalDeleteActionToFlatDeleteAction({
+    universalAction,
+    flatEntityMaps,
+    fromUniversalFlatEntityToFlatEntity: fromUniversalFlatMyEntityToFlatMyEntity,
+  });
+}
+
+// Delete
+protected async executeForMetadata(flatActions) {
+  const ids = flatActions.map(a => a.flatEntity.id);
+  await this.myEntityRepository.delete(ids);
+}
+```
+
+---
+
+## Checklist
+
+Before moving to Step 5:
+
+- [ ] Create action handler implemented
+- [ ] Update action handler implemented
+- [ ] Delete action handler implemented
+- [ ] All handlers extend appropriate base class
+- [ ] `transpileUniversalActionToFlatAction` implemented in all handlers
+- [ ] `executeForMetadata` implemented in all handlers
+- [ ] `executeForWorkspaceSchema` implemented (or returns empty)
+- [ ] Universal-to-flat conversion utility created
+- [ ] Create handler uses `insertFlatEntitiesInRepository`
+- [ ] Update handler uses `resolveUniversalUpdateRelationIdentifiersToIds`
+- [ ] Delete handler uses `transpileUniversalDeleteActionToFlatDeleteAction`
+- [ ] Delete handler uses hard delete (`delete()`)
+
+---
+
+## Next Step
+
+Once action handlers are complete, proceed to:
+**[Syncable Entity: Integration (Step 5/6)](../syncable-entity-integration/SKILL.md)**
+
+For complete workflow, see `@creating-syncable-entity` rule.

.cursor/skills/syncable-entity-testing/SKILL.md

@@ -0,0 +1,494 @@
+---
+name: syncable-entity-testing
+description: Create comprehensive integration tests for syncable entities in Twenty. Use when writing integration tests for metadata entities, covering validator exceptions, input transpilation errors, and CRUD operations. Tests are MANDATORY for all syncable entities.
+---
+
+# Syncable Entity: Integration Testing (Step 6/6 - MANDATORY)
+
+**Purpose**: Create comprehensive test suite covering all validation scenarios, input transpilation exceptions, and successful use cases.
+
+**When to use**: After completing Steps 1-5. Integration tests are **REQUIRED** for all syncable entities.
+
+---
+
+## Quick Start
+
+Tests must cover:
+1. **Failing scenarios** - All validator exceptions and input transpilation errors
+2. **Successful scenarios** - All CRUD operations and edge cases
+3. **Test utilities** - Reusable query factories and helper functions
+
+**Test pattern**: Two-file pattern (query factory + wrapper) for each operation.
+
+---
+
+## Step 1: Create Test Utilities
+
+### Pattern: Query Factory
+
+**File**: `test/integration/metadata/suites/my-entity/utils/create-my-entity-query-factory.util.ts`
+
+```typescript
+import gql from 'graphql-tag';
+import { type PerformMetadataQueryParams } from 'test/integration/metadata/types/perform-metadata-query.type';
+import { type CreateMyEntityInput } from 'src/engine/metadata-modules/my-entity/dtos/create-my-entity.input';
+
+export type CreateMyEntityFactoryInput = CreateMyEntityInput;
+
+const DEFAULT_MY_ENTITY_GQL_FIELDS = `
+  id
+  name
+  label
+  description
+  isCustom
+  createdAt
+  updatedAt
+`;
+
+export const createMyEntityQueryFactory = ({
+  input,
+  gqlFields = DEFAULT_MY_ENTITY_GQL_FIELDS,
+}: PerformMetadataQueryParams<CreateMyEntityFactoryInput>) => ({
+  query: gql`
+    mutation CreateMyEntity($input: CreateMyEntityInput!) {
+      createMyEntity(input: $input) {
+        ${gqlFields}
+      }
+    }
+  `,
+  variables: {
+    input,
+  },
+});
+```
+
+### Pattern: Wrapper Utility
+
+**File**: `test/integration/metadata/suites/my-entity/utils/create-my-entity.util.ts`
+
+```typescript
+import {
+  type CreateMyEntityFactoryInput,
+  createMyEntityQueryFactory,
+} from 'test/integration/metadata/suites/my-entity/utils/create-my-entity-query-factory.util';
+import { makeMetadataAPIRequest } from 'test/integration/metadata/suites/utils/make-metadata-api-request.util';
+import { type CommonResponseBody } from 'test/integration/metadata/types/common-response-body.type';
+import { type PerformMetadataQueryParams } from 'test/integration/metadata/types/perform-metadata-query.type';
+import { warnIfErrorButNotExpectedToFail } from 'test/integration/metadata/utils/warn-if-error-but-not-expected-to-fail.util';
+import { warnIfNoErrorButExpectedToFail } from 'test/integration/metadata/utils/warn-if-no-error-but-expected-to-fail.util';
+import { type MyEntityDto } from 'src/engine/metadata-modules/my-entity/dtos/my-entity.dto';
+
+export const createMyEntity = async ({
+  input,
+  gqlFields,
+  expectToFail = false,
+  token,
+}: PerformMetadataQueryParams<CreateMyEntityFactoryInput>): CommonResponseBody<{
+  createMyEntity: MyEntityDto;
+}> => {
+  const graphqlOperation = createMyEntityQueryFactory({
+    input,
+    gqlFields,
+  });
+
+  const response = await makeMetadataAPIRequest(graphqlOperation, token);
+
+  if (expectToFail === true) {
+    warnIfNoErrorButExpectedToFail({
+      response,
+      errorMessage: 'My entity creation should have failed but did not',
+    });
+  }
+
+  if (expectToFail === false) {
+    warnIfErrorButNotExpectedToFail({
+      response,
+      errorMessage: 'My entity creation has failed but should not',
+    });
+  }
+
+  return { data: response.body.data, errors: response.body.errors };
+};
+```
+
+**Required utilities** (follow same pattern):
+- `update-my-entity-query-factory.util.ts` + `update-my-entity.util.ts`
+- `delete-my-entity-query-factory.util.ts` + `delete-my-entity.util.ts`
+
+---
+
+## Step 2: Failing Creation Tests
+
+**File**: `test/integration/metadata/suites/my-entity/failing-my-entity-creation.integration-spec.ts`
+
+```typescript
+import { expectOneNotInternalServerErrorSnapshot } from 'test/integration/graphql/utils/expect-one-not-internal-server-error-snapshot.util';
+import { createMyEntity } from 'test/integration/metadata/suites/my-entity/utils/create-my-entity.util';
+import { deleteMyEntity } from 'test/integration/metadata/suites/my-entity/utils/delete-my-entity.util';
+import {
+  eachTestingContextFilter,
+  type EachTestingContext,
+} from 'twenty-shared/testing';
+import { isDefined } from 'twenty-shared/utils';
+import { type CreateMyEntityInput } from 'src/engine/metadata-modules/my-entity/dtos/create-my-entity.input';
+
+type TestContext = {
+  input: CreateMyEntityInput;
+};
+
+type GlobalTestContext = {
+  existingEntityLabel: string;
+  existingEntityName: string;
+};
+
+const globalTestContext: GlobalTestContext = {
+  existingEntityLabel: 'Existing Test Entity',
+  existingEntityName: 'existingTestEntity',
+};
+
+type CreateMyEntityTestingContext = EachTestingContext<TestContext>[];
+
+describe('My entity creation should fail', () => {
+  let existingEntityId: string | undefined;
+
+  beforeAll(async () => {
+    // Setup: Create entity for uniqueness tests
+    const { data } = await createMyEntity({
+      expectToFail: false,
+      input: {
+        name: globalTestContext.existingEntityName,
+        label: globalTestContext.existingEntityLabel,
+      },
+    });
+
+    existingEntityId = data.createMyEntity.id;
+  });
+
+  afterAll(async () => {
+    // Cleanup
+    if (isDefined(existingEntityId)) {
+      await deleteMyEntity({
+        expectToFail: false,
+        input: { id: existingEntityId },
+      });
+    }
+  });
+
+  const failingMyEntityCreationTestCases: CreateMyEntityTestingContext = [
+    // Input transpilation validation
+    {
+      title: 'when name is missing',
+      context: {
+        input: {
+          label: 'Entity Missing Name',
+        } as CreateMyEntityInput,
+      },
+    },
+    {
+      title: 'when label is missing',
+      context: {
+        input: {
+          name: 'entityMissingLabel',
+        } as CreateMyEntityInput,
+      },
+    },
+    {
+      title: 'when name is empty string',
+      context: {
+        input: {
+          name: '',
+          label: 'Empty Name Entity',
+        },
+      },
+    },
+
+    // Validator business logic
+    {
+      title: 'when name already exists (uniqueness)',
+      context: {
+        input: {
+          name: globalTestContext.existingEntityName,
+          label: 'Duplicate Name Entity',
+        },
+      },
+    },
+    {
+      title: 'when trying to create standard entity',
+      context: {
+        input: {
+          name: 'myEntity',
+          label: 'Standard Entity',
+          isCustom: false,
+        } as CreateMyEntityInput,
+      },
+    },
+
+    // Foreign key validation
+    {
+      title: 'when parentEntityId does not exist',
+      context: {
+        input: {
+          name: 'invalidParentEntity',
+          label: 'Invalid Parent Entity',
+          parentEntityId: '00000000-0000-0000-0000-000000000000',
+        },
+      },
+    },
+  ];
+
+  it.each(eachTestingContextFilter(failingMyEntityCreationTestCases))(
+    '$title',
+    async ({ context }) => {
+      const { errors } = await createMyEntity({
+        expectToFail: true,
+        input: context.input,
+      });
+
+      expectOneNotInternalServerErrorSnapshot({
+        errors,
+      });
+    },
+  );
+});
+```
+
+**Test coverage requirements**:
+- ✅ Missing required fields
+- ✅ Empty strings
+- ✅ Invalid format
+- ✅ Uniqueness violations
+- ✅ Standard entity protection
+- ✅ Foreign key validation
+
+---
+
+## Step 3: Successful Creation Tests
+
+**File**: `test/integration/metadata/suites/my-entity/successful-my-entity-creation.integration-spec.ts`
+
+```typescript
+import { createMyEntity } from 'test/integration/metadata/suites/my-entity/utils/create-my-entity.util';
+import { deleteMyEntity } from 'test/integration/metadata/suites/my-entity/utils/delete-my-entity.util';
+import { type CreateMyEntityInput } from 'src/engine/metadata-modules/my-entity/dtos/create-my-entity.input';
+
+describe('My entity creation should succeed', () => {
+  let createdEntityId: string;
+
+  afterEach(async () => {
+    if (createdEntityId) {
+      await deleteMyEntity({
+        expectToFail: false,
+        input: { id: createdEntityId },
+      });
+    }
+  });
+
+  it('should create entity with minimal required input', async () => {
+    const { data } = await createMyEntity({
+      expectToFail: false,
+      input: {
+        name: 'minimalEntity',
+        label: 'Minimal Entity',
+      },
+    });
+
+    createdEntityId = data?.createMyEntity?.id;
+
+    expect(data.createMyEntity).toMatchObject({
+      id: expect.any(String),
+      name: 'minimalEntity',
+      label: 'Minimal Entity',
+      description: null,
+      isCustom: true,
+      createdAt: expect.any(String),
+      updatedAt: expect.any(String),
+    });
+  });
+
+  it('should create entity with all optional fields', async () => {
+    const input = {
+      name: 'fullEntity',
+      label: 'Full Entity',
+      description: 'Entity with all fields specified',
+    } as const satisfies CreateMyEntityInput;
+
+    const { data } = await createMyEntity({
+      expectToFail: false,
+      input,
+    });
+
+    createdEntityId = data?.createMyEntity?.id;
+
+    expect(data.createMyEntity).toMatchObject({
+      id: expect.any(String),
+      name: 'fullEntity',
+      label: 'Full Entity',
+      description: 'Entity with all fields specified',
+      isCustom: true,
+    });
+  });
+
+  it('should sanitize input by trimming whitespace', async () => {
+    const { data } = await createMyEntity({
+      expectToFail: false,
+      input: {
+        name: '  entityWithSpaces  ',
+        label: '  Entity With Spaces  ',
+        description: '  Description with spaces  ',
+      },
+    });
+
+    createdEntityId = data?.createMyEntity?.id;
+
+    expect(data.createMyEntity).toMatchObject({
+      id: expect.any(String),
+      name: 'entityWithSpaces',
+      label: 'Entity With Spaces',
+      description: 'Description with spaces',
+    });
+  });
+
+  it('should handle long text content', async () => {
+    const longDescription = 'A'.repeat(1000);
+
+    const { data } = await createMyEntity({
+      expectToFail: false,
+      input: {
+        name: 'longDescEntity',
+        label: 'Long Description Entity',
+        description: longDescription,
+      },
+    });
+
+    createdEntityId = data?.createMyEntity?.id;
+
+    expect(data.createMyEntity).toMatchObject({
+      id: expect.any(String),
+      description: longDescription,
+    });
+  });
+});
+```
+
+**Test coverage requirements**:
+- ✅ Minimal required input
+- ✅ All optional fields
+- ✅ Input sanitization
+- ✅ Long text content
+- ✅ Special characters
+
+---
+
+## Step 4: Update and Delete Tests
+
+Create similar test files for update and delete operations:
+
+**Required files**:
+- `failing-my-entity-update.integration-spec.ts`
+- `successful-my-entity-update.integration-spec.ts`
+- `failing-my-entity-deletion.integration-spec.ts`
+- `successful-my-entity-deletion.integration-spec.ts`
+
+---
+
+## Testing Best Practices
+
+### Pattern: Cleanup
+```typescript
+afterEach(async () => {
+  if (createdEntityId) {
+    await deleteMyEntity({
+      expectToFail: false,
+      input: { id: createdEntityId },
+    });
+  }
+});
+```
+
+### Pattern: Type-Safe Inputs
+```typescript
+const input = {
+  name: 'myEntity',
+  label: 'My Entity',
+} as const satisfies CreateMyEntityInput;
+```
+
+### Pattern: Snapshot Testing
+```typescript
+expectOneNotInternalServerErrorSnapshot({
+  errors,
+});
+```
+
+---
+
+## Running Tests
+
+```bash
+# Run all entity tests
+npx jest test/integration/metadata/suites/my-entity --config=packages/twenty-server/jest.config.mjs
+
+# Run specific test file
+npx jest test/integration/metadata/suites/my-entity/failing-my-entity-creation.integration-spec.ts --config=packages/twenty-server/jest.config.mjs
+
+# Update snapshots
+npx jest test/integration/metadata/suites/my-entity --updateSnapshot --config=packages/twenty-server/jest.config.mjs
+```
+
+---
+
+## Complete Test Checklist
+
+### Test Utilities
+- [ ] `create-my-entity-query-factory.util.ts` created
+- [ ] `create-my-entity.util.ts` created
+- [ ] `update-my-entity-query-factory.util.ts` created
+- [ ] `update-my-entity.util.ts` created
+- [ ] `delete-my-entity-query-factory.util.ts` created
+- [ ] `delete-my-entity.util.ts` created
+
+### Failing Tests Coverage
+- [ ] Missing required fields
+- [ ] Empty string validation
+- [ ] Uniqueness violations
+- [ ] Standard entity protection
+- [ ] Foreign key validation
+- [ ] JSONB property validation (if applicable)
+
+### Successful Tests Coverage
+- [ ] Create with minimal input
+- [ ] Create with all optional fields
+- [ ] Input sanitization (whitespace)
+- [ ] Long text content
+- [ ] Update single field
+- [ ] Update multiple fields
+- [ ] Successful deletion
+
+### Snapshot Tests
+- [ ] All failing tests use `expectOneNotInternalServerErrorSnapshot`
+- [ ] Snapshots committed to `__snapshots__/` directory
+
+---
+
+## Success Criteria
+
+Your integration tests are complete when:
+
+✅ All test utilities created (minimum 6 files)
+✅ Failing creation tests cover all validators
+✅ Failing update tests cover business rules
+✅ Failing deletion tests cover protection rules
+✅ Successful tests cover all use cases
+✅ All snapshots generated and committed
+✅ All tests pass consistently
+✅ Test coverage meets requirements (>80%)
+
+---
+
+## Final Step
+
+✅ **Step 6 Complete!** → Your syncable entity is fully tested and production-ready!
+
+**Congratulations!** You've successfully created a new syncable entity in Twenty's workspace migration system.
+
+For complete workflow, see `@creating-syncable-entity` rule.

.cursor/skills/syncable-entity-types-and-constants/SKILL.md

@@ -0,0 +1,340 @@
+---
+name: syncable-entity-types-and-constants
+description: Define types, entities, and central constant registrations for syncable entities in Twenty's workspace migration system. Use when creating new syncable entities, defining TypeORM entities, flat entity types, or registering in central constants (ALL_ENTITY_PROPERTIES_CONFIGURATION_BY_METADATA_NAME, ALL_ONE_TO_MANY_METADATA_RELATIONS, ALL_MANY_TO_ONE_METADATA_FOREIGN_KEY, ALL_MANY_TO_ONE_METADATA_RELATIONS).
+---
+
+# Syncable Entity: Types & Constants (Step 1/6)
+
+**Purpose**: Define all types, entities, and register in central constants. This is the foundation - everything else depends on these types being correct.
+
+**When to use**: First step when creating any new syncable entity. Must be completed before other steps.
+
+---
+
+## Quick Start
+
+This step creates:
+1. Metadata name constant (twenty-shared)
+2. TypeORM entity (extends `SyncableEntity`)
+3. Flat entity types
+4. Action types (universal + flat)
+5. Central constant registrations (5 constants)
+
+---
+
+## Step 1: Add Metadata Name
+
+**File**: `packages/twenty-shared/src/metadata/all-metadata-name.constant.ts`
+
+```typescript
+export const ALL_METADATA_NAME = {
+  // ... existing entries
+  myEntity: 'myEntity',
+} as const;
+```
+
+---
+
+## Step 2: Create TypeORM Entity
+
+**File**: `src/engine/metadata-modules/my-entity/entities/my-entity.entity.ts`
+
+```typescript
+import { Entity, Column, ManyToOne, JoinColumn } from 'typeorm';
+import { SyncableEntity } from 'src/engine/workspace-manager/types/syncable-entity.interface';
+
+@Entity({ name: 'myEntity' })
+export class MyEntityEntity extends SyncableEntity {
+  @Column({ type: 'varchar' })
+  name: string;
+
+  @Column({ type: 'varchar' })
+  label: string;
+
+  @Column({ type: 'boolean', default: true })
+  isCustom: boolean;
+
+  // Foreign key example (optional)
+  @Column({ type: 'uuid', nullable: true })
+  parentEntityId: string | null;
+
+  @ManyToOne(() => ParentEntityEntity, { nullable: true })
+  @JoinColumn({ name: 'parentEntityId' })
+  parentEntity: ParentEntityEntity | null;
+
+  // JSONB column example (optional)
+  @Column({ type: 'jsonb', nullable: true })
+  settings: Record<string, any> | null;
+}
+```
+
+**Key rules**:
+- Must extend `SyncableEntity` (provides `id`, `universalIdentifier`, `applicationId`, etc.)
+- Must have `isCustom` boolean column
+- Use `@Column({ type: 'jsonb' })` for JSON data
+
+---
+
+## Step 3: Define Flat Entity Types
+
+**File**: `src/engine/metadata-modules/flat-my-entity/types/flat-my-entity.type.ts`
+
+```typescript
+import { type FlatEntityFrom } from 'src/engine/metadata-modules/flat-entity/types/flat-entity-from.type';
+import { type MyEntityEntity } from 'src/engine/metadata-modules/my-entity/entities/my-entity.entity';
+
+export type FlatMyEntity = FlatEntityFrom<MyEntityEntity>;
+```
+
+**Maps file** (if entity has indexed lookups):
+
+```typescript
+// flat-my-entity-maps.type.ts
+export type FlatMyEntityMaps = {
+  byId: Record<string, FlatMyEntity>;
+  byName: Record<string, FlatMyEntity>;
+  // Add other indexes as needed
+};
+```
+
+---
+
+## Step 4: Define Editable Properties
+
+**File**: `src/engine/metadata-modules/flat-my-entity/constants/editable-flat-my-entity-properties.constant.ts`
+
+```typescript
+export const EDITABLE_FLAT_MY_ENTITY_PROPERTIES = [
+  'name',
+  'label',
+  'description',
+  'parentEntityId',
+  'settings',
+] as const satisfies ReadonlyArray<keyof FlatMyEntity>;
+```
+
+**Rule**: Only include properties that can be updated (exclude `id`, `createdAt`, `universalIdentifier`, etc.)
+
+---
+
+## Step 5: Define Action Types
+
+**File**: `src/engine/workspace-manager/workspace-migration/workspace-migration-builder/builders/my-entity/types/workspace-migration-my-entity-action.type.ts`
+
+```typescript
+import { type FlatMyEntity } from 'src/engine/metadata-modules/flat-my-entity/types/flat-my-entity.type';
+import { type UniversalFlatMyEntity } from 'src/engine/workspace-manager/workspace-migration/universal-flat-entity/types/universal-flat-my-entity.type';
+
+// Universal actions (used by builder/runner)
+export type UniversalCreateMyEntityAction = {
+  type: 'create';
+  metadataName: 'myEntity';
+  universalFlatEntity: UniversalFlatMyEntity;
+};
+
+export type UniversalUpdateMyEntityAction = {
+  type: 'update';
+  metadataName: 'myEntity';
+  universalFlatEntity: UniversalFlatMyEntity;
+  universalUpdates: Partial<UniversalFlatMyEntity>;
+};
+
+export type UniversalDeleteMyEntityAction = {
+  type: 'delete';
+  metadataName: 'myEntity';
+  universalFlatEntity: UniversalFlatMyEntity;
+};
+
+// Flat actions (internal to runner)
+export type FlatCreateMyEntityAction = {
+  type: 'create';
+  metadataName: 'myEntity';
+  flatEntity: FlatMyEntity;
+};
+
+export type FlatUpdateMyEntityAction = {
+  type: 'update';
+  metadataName: 'myEntity';
+  flatEntity: FlatMyEntity;
+  updates: Partial<FlatMyEntity>;
+};
+
+export type FlatDeleteMyEntityAction = {
+  type: 'delete';
+  metadataName: 'myEntity';
+  flatEntity: FlatMyEntity;
+};
+```
+
+---
+
+## Step 6: Register in Central Constants
+
+### 6a. AllFlatEntityTypesByMetadataName
+
+**File**: `src/engine/metadata-modules/flat-entity/types/all-flat-entity-types-by-metadata-name.ts`
+
+```typescript
+export type AllFlatEntityTypesByMetadataName = {
+  // ... existing entries
+  myEntity: {
+    flatEntityMaps: FlatMyEntityMaps;
+    universalActions: {
+      create: UniversalCreateMyEntityAction;
+      update: UniversalUpdateMyEntityAction;
+      delete: UniversalDeleteMyEntityAction;
+    };
+    flatActions: {
+      create: FlatCreateMyEntityAction;
+      update: FlatUpdateMyEntityAction;
+      delete: FlatDeleteMyEntityAction;
+    };
+    flatEntity: FlatMyEntity;
+    universalFlatEntity: UniversalFlatMyEntity;
+    entity: MyEntityEntity;
+  };
+};
+```
+
+### 6b. ALL_ENTITY_PROPERTIES_CONFIGURATION_BY_METADATA_NAME
+
+**File**: `src/engine/metadata-modules/flat-entity/constant/all-entity-properties-configuration-by-metadata-name.constant.ts`
+
+```typescript
+export const ALL_ENTITY_PROPERTIES_CONFIGURATION_BY_METADATA_NAME = {
+  // ... existing entries
+  myEntity: {
+    name: { toCompare: true },
+    label: { toCompare: true },
+    description: { toCompare: true },
+    parentEntityId: {
+      toCompare: true,
+      universalProperty: 'parentEntityUniversalIdentifier',
+    },
+    settings: {
+      toCompare: true,
+      toStringify: true,
+      universalProperty: 'universalSettings',
+    },
+  },
+} as const;
+```
+
+**Rules**:
+- `toCompare: true` → Editable property (checked for changes)
+- `toStringify: true` → JSONB/object property (needs JSON serialization)
+- `universalProperty` → Maps to universal version (for foreign keys & JSONB with `SerializedRelation`)
+
+### 6c. ALL_ONE_TO_MANY_METADATA_RELATIONS
+
+**File**: `src/engine/metadata-modules/flat-entity/constant/all-one-to-many-metadata-relations.constant.ts`
+
+This constant is **type-checked** — values for `metadataName`, `flatEntityForeignKeyAggregator`, and `universalFlatEntityForeignKeyAggregator` are derived from entity type definitions. The aggregator names follow the pattern: remove trailing `'s'` from the relation property name, then append `Ids` or `UniversalIdentifiers`.
+
+```typescript
+export const ALL_ONE_TO_MANY_METADATA_RELATIONS = {
+  // ... existing entries
+  myEntity: {
+    // If myEntity has a `childEntities: ChildEntityEntity[]` property:
+    childEntities: {
+      metadataName: 'childEntity',
+      flatEntityForeignKeyAggregator: 'childEntityIds',
+      universalFlatEntityForeignKeyAggregator: 'childEntityUniversalIdentifiers',
+    },
+    // null for relations to non-syncable entities
+    someNonSyncableRelation: null,
+  },
+} as const;
+```
+
+### 6d. ALL_MANY_TO_ONE_METADATA_FOREIGN_KEY
+
+**File**: `src/engine/metadata-modules/flat-entity/constant/all-many-to-one-metadata-foreign-key.constant.ts`
+
+Low-level primitive constant. Only contains `foreignKey` — the column name ending in `Id` that stores the foreign key. Type-checked against entity properties.
+
+```typescript
+export const ALL_MANY_TO_ONE_METADATA_FOREIGN_KEY = {
+  // ... existing entries
+  myEntity: {
+    workspace: null,
+    application: null,
+    parentEntity: {
+      foreignKey: 'parentEntityId',
+    },
+  },
+} as const;
+```
+
+### 6e. ALL_MANY_TO_ONE_METADATA_RELATIONS
+
+**File**: `src/engine/metadata-modules/flat-entity/constant/all-many-to-one-metadata-relations.constant.ts`
+
+Derived from both `ALL_MANY_TO_ONE_METADATA_FOREIGN_KEY` (for `foreignKey` type and `universalForeignKey` derivation) and `ALL_ONE_TO_MANY_METADATA_RELATIONS` (for `inverseOneToManyProperty` key constraint). This is the main constant consumed by utils and optimistic tooling.
+
+```typescript
+export const ALL_MANY_TO_ONE_METADATA_RELATIONS = {
+  // ... existing entries
+  myEntity: {
+    workspace: null,
+    application: null,
+    parentEntity: {
+      metadataName: 'parentEntity',
+      foreignKey: 'parentEntityId',
+      inverseOneToManyProperty: 'myEntities',  // key in ALL_ONE_TO_MANY_METADATA_RELATIONS['parentEntity'], or null if no inverse
+      isNullable: false,
+      universalForeignKey: 'parentEntityUniversalIdentifier',
+    },
+  },
+} as const;
+```
+
+**Derivation dependency graph**:
+
+```
+ALL_MANY_TO_ONE_METADATA_FOREIGN_KEY     ALL_ONE_TO_MANY_METADATA_RELATIONS
+(foreignKey only)                        (metadataName, aggregators)
+  │                                        │
+  │ FK type + universalFK derivation       │ inverseOneToManyProperty keys
+  │                                        │
+  └────────────────┬───────────────────────┘
+                   ▼
+    ALL_MANY_TO_ONE_METADATA_RELATIONS
+    (metadataName, foreignKey, inverseOneToManyProperty,
+     isNullable, universalForeignKey)
+```
+
+**Rules**:
+- `workspace: null`, `application: null` — always present, always null (non-syncable relations)
+- `inverseOneToManyProperty` — must be a key in `ALL_ONE_TO_MANY_METADATA_RELATIONS[targetMetadataName]`, or `null` if the target entity doesn't expose an inverse one-to-many relation
+- `universalForeignKey` — derived from `foreignKey` by replacing the `Id` suffix with `UniversalIdentifier`
+- Optimistic utils resolve `flatEntityForeignKeyAggregator` / `universalFlatEntityForeignKeyAggregator` at runtime by looking up `inverseOneToManyProperty` in `ALL_ONE_TO_MANY_METADATA_RELATIONS`
+
+---
+
+## Checklist
+
+Before moving to Step 2:
+
+- [ ] Metadata name added to `ALL_METADATA_NAME`
+- [ ] TypeORM entity created (extends `SyncableEntity`)
+- [ ] `isCustom` column added
+- [ ] Flat entity type defined
+- [ ] Flat entity maps type defined (if needed)
+- [ ] Editable properties constant defined
+- [ ] Universal and flat action types defined
+- [ ] Registered in `AllFlatEntityTypesByMetadataName`
+- [ ] Registered in `ALL_ENTITY_PROPERTIES_CONFIGURATION_BY_METADATA_NAME`
+- [ ] Registered in `ALL_ONE_TO_MANY_METADATA_RELATIONS` (if entity has one-to-many relations)
+- [ ] Registered in `ALL_MANY_TO_ONE_METADATA_FOREIGN_KEY`
+- [ ] Registered in `ALL_MANY_TO_ONE_METADATA_RELATIONS`
+- [ ] TypeScript compiles without errors
+
+---
+
+## Next Step
+
+Once all types and constants are defined, proceed to:
+**[Syncable Entity: Cache & Transform (Step 2/6)](../syncable-entity-cache-and-transform/SKILL.md)**
+
+For complete workflow, see `@creating-syncable-entity` rule.

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

@@ -11,7 +11,7 @@ on:
 jobs:
   deploy-main:
     timeout-minutes: 3
-    runs-on: ubuntu-latest
+    runs-on: depot-ubuntu-24.04
     steps:
       - name: Repository Dispatch
         uses: peter-evans/repository-dispatch@v2

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

@@ -11,7 +11,7 @@ on:
 jobs:
   deploy-tag:
     timeout-minutes: 3
-    runs-on: ubuntu-latest
+    runs-on: depot-ubuntu-24.04
     steps:
       - name: Repository Dispatch
         uses: peter-evans/repository-dispatch@v2

.github/workflows/changed-files.yaml

@@ -16,7 +16,7 @@ permissions:
 jobs:
   changed-files:
     timeout-minutes: 5
-    runs-on: ubuntu-latest
+    runs-on: depot-ubuntu-24.04
     outputs:
       any_changed: ${{ steps.changed-files.outputs.any_changed }}
     steps:

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

@@ -34,7 +34,7 @@ jobs:
     needs: changed-files-check
     if: needs.changed-files-check.outputs.any_changed == 'true'
     timeout-minutes: 45
-    runs-on: ubuntu-latest
+    runs-on: depot-ubuntu-24.04
     services:
       postgres:
         image: twentycrm/twenty-postgres-spilo

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

@@ -20,11 +20,12 @@ jobs:
     with:
       files: |
         packages/create-twenty-app/**
+        !packages/create-twenty-app/package.json
   create-app-test:
     needs: changed-files-check
     if: needs.changed-files-check.outputs.any_changed == 'true'
     timeout-minutes: 30
-    runs-on: ubuntu-latest
+    runs-on: depot-ubuntu-24.04
     strategy:
       matrix:
         task: [lint, typecheck, test]
@@ -49,7 +50,7 @@ jobs:
   ci-create-app-status-check:
     if: always() && !cancelled()
     timeout-minutes: 5
-    runs-on: ubuntu-latest
+    runs-on: depot-ubuntu-24.04
     needs: [changed-files-check, create-app-test]
     steps:
       - name: Fail job if any needs failed

.github/workflows/ci-docs.yaml

@@ -27,7 +27,7 @@ jobs:
     needs: changed-files-check
     if: needs.changed-files-check.outputs.any_changed == 'true'
     timeout-minutes: 10
-    runs-on: ubuntu-latest
+    runs-on: depot-ubuntu-24.04
     steps:
       - name: Cancel Previous Runs
         uses: styfle/cancel-workflow-action@0.11.0

.github/workflows/ci-emails.yaml

@@ -25,7 +25,7 @@ jobs:
     needs: changed-files-check
     if: needs.changed-files-check.outputs.any_changed == 'true'
     timeout-minutes: 10
-    runs-on: depot-ubuntu-24.04-8
+    runs-on: ubuntu-latest-8-cores
     steps:
       - name: Fetch custom Github Actions and base branch history
         uses: actions/checkout@v4
@@ -56,7 +56,7 @@ jobs:
   ci-emails-status-check:
     if: always() && !cancelled()
     timeout-minutes: 5
-    runs-on: ubuntu-latest
+    runs-on: depot-ubuntu-24.04
     needs: [changed-files-check, emails-test]
     steps:
       - name: Fail job if any needs failed

.github/workflows/ci-front.yaml

@@ -14,8 +14,8 @@ concurrency:
 
 env:
   # restore-cache action adds 'v4-' prefix and '-<branch>-<sha>' suffix to the key
-  STORYBOOK_BUILD_CACHE_KEY_FOR_RESTORE_ACTION: storybook-build-depot-ubuntu-24.04-8-runner
-  STORYBOOK_BUILD_CACHE_KEY_FOR_SAVE_ACTION: v4-storybook-build-depot-ubuntu-24.04-8-runner-${{ github.ref_name }}-${{ github.sha }}
+  STORYBOOK_BUILD_CACHE_KEY_FOR_RESTORE_ACTION: storybook-build-ubuntu-latest-8-cores-runner
+  STORYBOOK_BUILD_CACHE_KEY_FOR_SAVE_ACTION: v4-storybook-build-ubuntu-latest-8-cores-runner-${{ github.ref_name }}-${{ github.sha }}
 
 jobs:
   changed-files-check:
@@ -27,18 +27,22 @@ jobs:
         packages/twenty-front/**
         packages/twenty-ui/**
         packages/twenty-shared/**
+        packages/twenty-sdk/**
+        !packages/twenty-sdk/package.json
   changed-files-check-e2e:
     uses: ./.github/workflows/changed-files.yaml
     with:
       files: |
         packages/**
+        !packages/create-twenty-app/package.json
+        !packages/twenty-sdk/package.json
         playwright.config.ts
         .github/workflows/ci-front.yaml
   front-sb-build:
     needs: changed-files-check
     if: needs.changed-files-check.outputs.any_changed == 'true'
     timeout-minutes: 30
-    runs-on: depot-ubuntu-24.04-8
+    runs-on: ubuntu-latest-8-cores
     env:
       REACT_APP_SERVER_BASE_URL: http://localhost:3000
     steps:
@@ -64,7 +68,7 @@ jobs:
           key: ${{ env.STORYBOOK_BUILD_CACHE_KEY_FOR_SAVE_ACTION }}
   front-sb-test:
     timeout-minutes: 30
-    runs-on: depot-ubuntu-24.04-8
+    runs-on: ubuntu-latest-8-cores
     needs: front-sb-build
     strategy:
       fail-fast: false
@@ -85,6 +89,7 @@ jobs:
         run: |
           npx nx build twenty-shared
           npx nx build twenty-ui
+          npx nx build twenty-sdk
       - name: Install Playwright
         run: |
           cd packages/twenty-front
@@ -110,7 +115,7 @@ jobs:
           path: packages/twenty-front/coverage/storybook/coverage-shard-${{matrix.shard}}.json
   merge-reports-and-check-coverage:
     timeout-minutes: 30
-    runs-on: ubuntu-latest
+    runs-on: depot-ubuntu-24.04
     needs: front-sb-test
     env:
       PATH_TO_COVERAGE: packages/twenty-front/coverage/storybook
@@ -138,7 +143,7 @@ jobs:
     timeout-minutes: 30
     if: false
     needs: front-sb-build
-    runs-on: depot-ubuntu-24.04-8
+    runs-on: ubuntu-latest-8-cores
     env:
       REACT_APP_SERVER_BASE_URL: http://127.0.0.1:3000
       CHROMATIC_PROJECT_TOKEN: ${{ secrets.CHROMATIC_PROJECT_TOKEN }}
@@ -164,8 +169,9 @@ jobs:
     needs: changed-files-check
     if: needs.changed-files-check.outputs.any_changed == 'true'
     timeout-minutes: 30
-    runs-on: ubuntu-latest
+    runs-on: depot-ubuntu-24.04
     env:
+      NODE_OPTIONS: '--max-old-space-size=4096'
       TASK_CACHE_KEY: front-task-${{ matrix.task }}
     strategy:
       matrix:
@@ -192,6 +198,7 @@ jobs:
           tag: scope:frontend
           tasks: reset:env
       - name: Run ${{ matrix.task }} task
+        id: run-task
         uses: ./.github/actions/nx-affected
         with:
           tag: scope:frontend
@@ -204,7 +211,7 @@ jobs:
     needs: changed-files-check
     if: needs.changed-files-check.outputs.any_changed == 'true'
     timeout-minutes: 30
-    runs-on: depot-ubuntu-24.04-8
+    runs-on: ubuntu-latest-8-cores
     env:
       NODE_OPTIONS: "--max-old-space-size=10240"
     steps:
@@ -229,7 +236,7 @@ jobs:
           path: packages/twenty-front/build
           retention-days: 1
   e2e-test:
-    runs-on: ubuntu-latest
+    runs-on: depot-ubuntu-24.04
     needs: [changed-files-check-e2e, front-build]
     if: |
       always() &&
@@ -339,7 +346,7 @@ jobs:
   ci-front-status-check:
     if: always() && !cancelled()
     timeout-minutes: 5
-    runs-on: ubuntu-latest
+    runs-on: depot-ubuntu-24.04
     needs:
       [
         changed-files-check,
@@ -356,7 +363,7 @@ jobs:
   ci-e2e-status-check:
     if: always() && !cancelled()
     timeout-minutes: 5
-    runs-on: ubuntu-latest
+    runs-on: depot-ubuntu-24.04
     needs: [changed-files-check-e2e, e2e-test]
     steps:
       - name: Fail job if any needs failed

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

@@ -25,7 +25,7 @@ defaults:
 jobs:
   create_pr:
     timeout-minutes: 10
-    runs-on: ubuntu-latest
+    runs-on: depot-ubuntu-24.04
     steps:
       - name: Checkout
         uses: actions/checkout@v4

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

@@ -15,7 +15,7 @@ defaults:
 jobs:
   tag_and_release:
     timeout-minutes: 10
-    runs-on: ubuntu-latest
+    runs-on: depot-ubuntu-24.04
     if: github.event.pull_request.merged == true && contains(github.event.pull_request.labels.*.name, 'release')
     steps:
       - name: Check PR Author

.github/workflows/ci-sdk.yaml

@@ -18,14 +18,15 @@ jobs:
     with:
       files: |
         packages/twenty-sdk/**
+        !packages/twenty-sdk/package.json
   sdk-test:
     needs: changed-files-check
     if: needs.changed-files-check.outputs.any_changed == 'true'
     timeout-minutes: 30
-    runs-on: ubuntu-latest
+    runs-on: depot-ubuntu-24.04
     strategy:
       matrix:
-        task: [lint, typecheck, test:unit, test:integration]
+        task: [lint, typecheck, test:unit, storybook:build, storybook:test, test:integration]
     steps:
       - name: Cancel Previous Runs
         uses: styfle/cancel-workflow-action@0.11.0
@@ -39,64 +40,62 @@ jobs:
         uses: ./.github/actions/yarn-install
       - name: Build
         run: npx nx build twenty-sdk
+      - name: Install Playwright
+        if: contains(matrix.task, 'storybook')
+        run: npx playwright install chromium
       - name: Run ${{ matrix.task }} task
         uses: ./.github/actions/nx-affected
         with:
           tag: scope:sdk
           tasks: ${{ matrix.task }}
-  # TODO: Re-enable sdk-e2e-test once application sync is stable
-  # sdk-e2e-test:
-  #   timeout-minutes: 30
-  #   runs-on: depot-ubuntu-24.04-8
-  #   needs: [changed-files-check, sdk-test]
-  #   if: needs.changed-files-check.outputs.any_changed == 'true'
-  #   services:
-  #     postgres:
-  #       image: twentycrm/twenty-postgres-spilo
-  #       env:
-  #         PGUSER_SUPERUSER: postgres
-  #         PGPASSWORD_SUPERUSER: postgres
-  #         ALLOW_NOSSL: 'true'
-  #         SPILO_PROVIDER: 'local'
-  #       ports:
-  #         - 5432:5432
-  #       options: >-
-  #         --health-cmd pg_isready
-  #         --health-interval 10s
-  #         --health-timeout 5s
-  #         --health-retries 5
-  #     redis:
-  #       image: redis
-  #       ports:
-  #         - 6379:6379
-  #   env:
-  #     NODE_ENV: test
-  #   steps:
-  #     - name: Fetch custom Github Actions and base branch history
-  #       uses: actions/checkout@v4
-  #       with:
-  #         fetch-depth: 0
-  #     - name: Install dependencies
-  #       uses: ./.github/actions/yarn-install
-  #     - name: Server / Append billing config to .env.test
-  #       working-directory: packages/twenty-server
-  #       run: |
-  #         echo "" >> .env.test
-  #         echo "IS_BILLING_ENABLED=true" >> .env.test
-  #         echo "BILLING_STRIPE_API_KEY=test-api-key" >> .env.test
-  #         echo "BILLING_STRIPE_BASE_PLAN_PRODUCT_ID=test-base-plan-product-id" >> .env.test
-  #         echo "BILLING_STRIPE_WEBHOOK_SECRET=test-webhook-secret" >> .env.test
-  #         echo "BILLING_PLAN_REQUIRED_LINK=http://localhost:3001/stripe-redirection" >> .env.test
-  #     - name: Server / Create Test DB
-  #       run: |
-  #         PGPASSWORD=postgres psql -h localhost -p 5432 -U postgres -d postgres -c 'CREATE DATABASE "test";'
-  #     - name: SDK / Run E2E Tests
-  #       run: npx nx test:e2e twenty-sdk
+  sdk-e2e-test:
+    timeout-minutes: 30
+    runs-on: ubuntu-latest-8-cores
+    needs: [changed-files-check, sdk-test]
+    if: needs.changed-files-check.outputs.any_changed == 'true'
+    services:
+      postgres:
+        image: twentycrm/twenty-postgres-spilo
+        env:
+          PGUSER_SUPERUSER: postgres
+          PGPASSWORD_SUPERUSER: postgres
+          ALLOW_NOSSL: 'true'
+          SPILO_PROVIDER: 'local'
+        ports:
+          - 5432:5432
+        options: >-
+          --health-cmd pg_isready
+          --health-interval 10s
+          --health-timeout 5s
+          --health-retries 5
+      redis:
+        image: redis
+        ports:
+          - 6379:6379
+    env:
+      NODE_ENV: test
+    steps:
+      - name: Fetch custom Github Actions and base branch history
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - name: Install dependencies
+        uses: ./.github/actions/yarn-install
+      - name: Build
+        run: npx nx build twenty-sdk
+      - name: Server / Create Test DB
+        run: |
+          PGPASSWORD=postgres psql -h localhost -p 5432 -U postgres -d postgres -c 'CREATE DATABASE "test";'
+      - name: SDK / Run e2e Tests
+        uses: ./.github/actions/nx-affected
+        with:
+          tag: scope:sdk
+          tasks: test:e2e
   ci-sdk-status-check:
     if: always() && !cancelled()
     timeout-minutes: 5
-    runs-on: ubuntu-latest
-    needs: [changed-files-check, sdk-test]
+    runs-on: depot-ubuntu-24.04
+    needs: [changed-files-check, sdk-test, sdk-e2e-test]
     steps:
       - name: Fail job if any needs failed
         if: contains(needs.*.result, 'failure')

.github/workflows/ci-server.yaml

@@ -31,7 +31,7 @@ jobs:
     needs: changed-files-check
     if: needs.changed-files-check.outputs.any_changed == 'true'
     timeout-minutes: 30
-    runs-on: depot-ubuntu-24.04-8
+    runs-on: ubuntu-latest-8-cores
     services:
       postgres:
         image: twentycrm/twenty-postgres-spilo
@@ -143,7 +143,7 @@ jobs:
           key: ${{ steps.restore-server-setup-cache.outputs.cache-primary-key }}
   server-test:
     timeout-minutes: 30
-    runs-on: depot-ubuntu-24.04-8
+    runs-on: ubuntu-latest-8-cores
     needs: server-setup
     steps:
       - name: Fetch custom Github Actions and base branch history
@@ -164,7 +164,7 @@ jobs:
 
   server-integration-test:
     timeout-minutes: 30
-    runs-on: depot-ubuntu-24.04-8
+    runs-on: ubuntu-latest-8-cores
     needs: server-setup
     strategy:
       fail-fast: false
@@ -250,7 +250,7 @@ jobs:
   ci-server-status-check:
     if: always() && !cancelled()
     timeout-minutes: 5
-    runs-on: ubuntu-latest
+    runs-on: depot-ubuntu-24.04
     needs: [changed-files-check, server-setup, server-test, server-integration-test]
     steps:
       - name: Fail job if any needs failed

.github/workflows/ci-shared.yaml

@@ -22,7 +22,9 @@ jobs:
     needs: changed-files-check
     if: needs.changed-files-check.outputs.any_changed == 'true'
     timeout-minutes: 30
-    runs-on: ubuntu-latest
+    runs-on: depot-ubuntu-24.04
+    env:
+      NODE_OPTIONS: '--max-old-space-size=4096'
     strategy:
       matrix:
         task: [lint, typecheck, test]
@@ -45,7 +47,7 @@ jobs:
   ci-shared-status-check:
     if: always() && !cancelled()
     timeout-minutes: 5
-    runs-on: ubuntu-latest
+    runs-on: depot-ubuntu-24.04
     needs: [changed-files-check, shared-test]
     steps:
       - name: Fail job if any needs failed

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

@@ -23,7 +23,7 @@ jobs:
     needs: changed-files-check
     if: needs.changed-files-check.outputs.any_changed == 'true'
     timeout-minutes: 30
-    runs-on: ubuntu-latest
+    runs-on: depot-ubuntu-24.04
     steps:
       - name: Checkout
         uses: actions/checkout@v4
@@ -92,7 +92,7 @@ jobs:
   ci-test-docker-compose-status-check:
     if: always() && !cancelled()
     timeout-minutes: 5
-    runs-on: ubuntu-latest
+    runs-on: depot-ubuntu-24.04
     needs: [changed-files-check, test]
     steps:
       - name: Fail job if any needs failed

.github/workflows/ci-utils.yaml

@@ -25,7 +25,7 @@ concurrency:
 jobs:
   danger-js:
     timeout-minutes: 5
-    runs-on: ubuntu-latest
+    runs-on: depot-ubuntu-24.04
     if: github.event.action != 'closed'
     steps:
       - uses: actions/checkout@v4
@@ -38,7 +38,7 @@ jobs:
 
   congratulate:
     timeout-minutes: 3
-    runs-on: ubuntu-latest
+    runs-on: depot-ubuntu-24.04
     if: github.event.action == 'closed' && github.event.pull_request.merged == true
     steps:
       - uses: actions/checkout@v4

.github/workflows/ci-website.yaml

@@ -23,7 +23,7 @@ jobs:
     needs: changed-files-check
     if: needs.changed-files-check.outputs.any_changed == 'true'
     timeout-minutes: 10
-    runs-on: ubuntu-latest
+    runs-on: depot-ubuntu-24.04
     services:
       postgres:
         image: twentycrm/twenty-postgres-spilo
@@ -65,7 +65,7 @@ jobs:
   ci-website-status-check:
     if: always() && !cancelled()
     timeout-minutes: 5
-    runs-on: ubuntu-latest
+    runs-on: depot-ubuntu-24.04
     needs: [changed-files-check, website-build]
     steps:
       - name: Fail job if any needs failed

.github/workflows/claude.yml

@@ -0,0 +1,174 @@
+name: Claude Code
+
+on:
+  issue_comment:
+    types: [created]
+  pull_request_review_comment:
+    types: [created]
+  pull_request_review:
+    types: [submitted]
+  issues:
+    types: [opened, assigned]
+  repository_dispatch:
+    types: [claude-core-team-issues]
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.event.issue.number || github.event.pull_request.number || github.event.client_payload.issue_number }}
+  cancel-in-progress: false
+
+jobs:
+  claude:
+    if: |
+      (github.event_name == 'issue_comment' && contains(github.event.comment.body, '@claude') && github.event.comment.user.type != 'Bot') ||
+      (github.event_name == 'pull_request_review_comment' && contains(github.event.comment.body, '@claude') && github.event.comment.user.type != 'Bot') ||
+      (github.event_name == 'pull_request_review' && contains(github.event.review.body, '@claude') && github.event.review.user.type != 'Bot') ||
+      (github.event_name == 'issues' && (contains(github.event.issue.body, '@claude') || contains(github.event.issue.title, '@claude')))
+    runs-on: depot-ubuntu-24.04
+    timeout-minutes: 60
+    permissions:
+      contents: write
+      pull-requests: write
+      issues: write
+      id-token: write
+    services:
+      postgres:
+        image: postgres:16
+        env:
+          POSTGRES_USER: postgres
+          POSTGRES_PASSWORD: postgres
+          POSTGRES_DB: postgres
+        ports:
+          - 5432:5432
+        options: >-
+          --health-cmd pg_isready
+          --health-interval 10s
+          --health-timeout 5s
+          --health-retries 5
+      redis:
+        image: redis
+        ports:
+          - 6379:6379
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - name: Install dependencies
+        uses: ./.github/actions/yarn-install
+      - name: Run Claude Code
+        id: claude-code
+        uses: anthropics/claude-code-action@v1
+        with:
+          claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
+          additional_permissions: |
+            actions: read
+          claude_args: '--max-turns 200 --model opus --allowedTools "Edit,Write,WebFetch,Bash(bash packages/twenty-utils/setup-dev-env.sh),Bash(npx nx *),Bash(npx jest *),Bash(yarn *),Bash(git *),Bash(gh *),Bash(sed *),Bash(python3 *),Bash(rm *),Bash(find *),Bash(grep *),Bash(cat *),Bash(ls *),Bash(head *),Bash(tail *),Bash(wc *),Bash(sort *),Bash(uniq *),Bash(mkdir *),Bash(cp *),Bash(mv *),Bash(touch *),Bash(chmod *),Bash(echo *),Bash(curl *),Bash(cd *),Bash(pwd *),Bash(diff *),Bash(xargs *),Bash(awk *),Bash(cut *),Bash(tee *),Bash(tr *)"'
+          settings: |
+            {
+              "env": {
+                "PG_DATABASE_URL": "postgres://postgres:postgres@localhost:5432/default"
+              }
+            }
+      - name: Post Create-PR link if Claude ran out of turns
+        if: failure()
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          BRANCH=$(git branch --show-current)
+          if [ "$BRANCH" = "main" ] || [ "$BRANCH" = "" ]; then
+            exit 0
+          fi
+          AHEAD=$(git rev-list --count main.."$BRANCH" 2>/dev/null || echo "0")
+          if [ "$AHEAD" = "0" ]; then
+            exit 0
+          fi
+          EXISTING_PR=$(gh pr list --head "$BRANCH" --json number --jq '.[0].number' 2>/dev/null || echo "")
+          if [ -n "$EXISTING_PR" ]; then
+            exit 0
+          fi
+          ISSUE_NUMBER="${{ github.event.issue.number || github.event.pull_request.number }}"
+          ENCODED_BRANCH=$(python3 -c "import urllib.parse; print(urllib.parse.quote('$BRANCH', safe=''))")
+          PR_URL="https://github.com/${{ github.repository }}/compare/main...${ENCODED_BRANCH}?quick_pull=1"
+          BODY="⚠️ Claude ran out of turns before creating a PR. Work has been pushed to [\`$BRANCH\`](https://github.com/${{ github.repository }}/tree/$ENCODED_BRANCH).\n\n[**Create PR →**]($PR_URL)"
+          if [ -n "$ISSUE_NUMBER" ]; then
+            gh issue comment "$ISSUE_NUMBER" --body "$(echo -e "$BODY")"
+          fi
+
+  claude-cross-repo:
+    if: github.event_name == 'repository_dispatch'
+    runs-on: depot-ubuntu-24.04
+    timeout-minutes: 60
+    permissions:
+      contents: write
+      pull-requests: write
+      issues: write
+      id-token: write
+    services:
+      postgres:
+        image: postgres:16
+        env:
+          POSTGRES_USER: postgres
+          POSTGRES_PASSWORD: postgres
+          POSTGRES_DB: postgres
+        ports:
+          - 5432:5432
+        options: >-
+          --health-cmd pg_isready
+          --health-interval 10s
+          --health-timeout 5s
+          --health-retries 5
+      redis:
+        image: redis
+        ports:
+          - 6379:6379
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - name: Install dependencies
+        uses: ./.github/actions/yarn-install
+      - name: Build prompt from dispatch payload
+        id: prompt
+        uses: actions/github-script@v7
+        with:
+          script: |
+            const p = context.payload.client_payload;
+            let prompt;
+            if (p.comment_body) {
+              prompt = `You are responding to a comment on issue #${p.issue_number} ("${p.issue_title}") in the ${p.repo_full_name} repository.\n\nThe comment by @${p.sender} says:\n\n${p.comment_body}\n\nIssue body:\n\n${p.issue_body}\n\nPlease help with this request. The code you are working with is the twenty codebase (this repository).`;
+            } else {
+              prompt = `You are responding to issue #${p.issue_number} ("${p.issue_title}") in the ${p.repo_full_name} repository, opened by @${p.sender}.\n\nIssue body:\n\n${p.issue_body}\n\nPlease help with this request. The code you are working with is the twenty codebase (this repository).`;
+            }
+            core.setOutput('prompt', prompt);
+            core.setOutput('repo', p.repo_full_name);
+            core.setOutput('issue_number', p.issue_number);
+      - name: Run Claude Code
+        id: claude
+        uses: anthropics/claude-code-action@v1
+        with:
+          claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
+          prompt: ${{ steps.prompt.outputs.prompt }}
+          additional_permissions: |
+            actions: read
+          claude_args: '--max-turns 200 --model opus --allowedTools "Edit,Write,WebFetch,Bash(bash packages/twenty-utils/setup-dev-env.sh),Bash(npx nx *),Bash(npx jest *),Bash(yarn *),Bash(git *),Bash(gh *),Bash(sed *),Bash(python3 *),Bash(rm *),Bash(find *),Bash(grep *),Bash(cat *),Bash(ls *),Bash(head *),Bash(tail *),Bash(wc *),Bash(sort *),Bash(uniq *),Bash(mkdir *),Bash(cp *),Bash(mv *),Bash(touch *),Bash(chmod *),Bash(echo *),Bash(curl *),Bash(cd *),Bash(pwd *),Bash(diff *),Bash(xargs *),Bash(awk *),Bash(cut *),Bash(tee *),Bash(tr *)"'
+          settings: |
+            {
+              "env": {
+                "PG_DATABASE_URL": "postgres://postgres:postgres@localhost:5432/default"
+              }
+            }
+      - name: Post response to source issue
+        if: always()
+        uses: actions/github-script@v7
+        with:
+          github-token: ${{ secrets.TWENTY_DISPATCH_TOKEN }}
+          script: |
+            const [owner, repo] = '${{ steps.prompt.outputs.repo }}'.split('/');
+            const issueNumber = parseInt('${{ steps.prompt.outputs.issue_number }}', 10);
+
+            await github.rest.issues.createComment({
+              owner,
+              repo,
+              issue_number: issueNumber,
+              body: `Claude finished processing this request. [See workflow run](${context.serverUrl}/${context.repo.owner}/${context.repo.repo}/actions/runs/${context.runId})`
+            });

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

@@ -34,7 +34,7 @@ concurrency:
 jobs:
   pull_docs_translations:
     name: Pull docs translations
-    runs-on: ubuntu-latest
+    runs-on: depot-ubuntu-24.04
     steps:
       - name: Checkout
         uses: actions/checkout@v4
@@ -107,10 +107,13 @@ jobs:
       - name: Regenerate docs.json
         run: yarn docs:generate
 
+      - name: Regenerate documentation paths constants
+        run: yarn docs:generate-paths
+
       - name: Commit artifacts to pull request branch
         if: github.event_name == 'pull_request'
         run: |
-          git add packages/twenty-docs/docs.json packages/twenty-docs/navigation/navigation.template.json
+          git add packages/twenty-docs/docs.json packages/twenty-docs/navigation/navigation.template.json packages/twenty-shared/src/constants/DocumentationPaths.ts
           if git diff --staged --quiet --exit-code; then
             echo "No navigation/doc changes to commit."
             exit 0

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

@@ -21,7 +21,7 @@ concurrency:
 jobs:
   push_docs:
     name: Push documentation to Crowdin
-    runs-on: ubuntu-latest
+    runs-on: depot-ubuntu-24.04
     steps:
       - name: Checkout
         uses: actions/checkout@v4

.github/workflows/i18n-pull.yaml

@@ -32,7 +32,7 @@ concurrency:
 jobs:
   pull_translations:
     name: Pull translations
-    runs-on: ubuntu-latest
+    runs-on: depot-ubuntu-24.04
     steps:
       - name: Checkout
         uses: actions/checkout@v4

.github/workflows/i18n-push.yaml

@@ -17,7 +17,7 @@ concurrency:
 jobs:
   extract_translations:
     name: Extract and upload translations
-    runs-on: ubuntu-latest
+    runs-on: depot-ubuntu-24.04
     steps:
       - name: Checkout
         uses: actions/checkout@v4

.github/workflows/i18n-qa-report.yaml

@@ -18,7 +18,7 @@ concurrency:
 jobs:
   qa_report:
     name: Generate QA Report
-    runs-on: ubuntu-latest
+    runs-on: depot-ubuntu-24.04
     steps:
       - name: Checkout
         uses: actions/checkout@v4

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

@@ -26,7 +26,7 @@ jobs:
   trigger-preview:
     if: github.event.action == 'opened' || github.event.action == 'synchronize' || github.event.action == 'reopened' || (github.event.action == 'labeled' && github.event.label.name == 'preview-app')
     timeout-minutes: 5
-    runs-on: ubuntu-latest
+    runs-on: depot-ubuntu-24.04
     steps:
       - name: Trigger preview environment workflow
         uses: peter-evans/repository-dispatch@v2

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

@@ -11,13 +11,13 @@ on:
 jobs:
   preview-environment:
     timeout-minutes: 310
-    runs-on: ubuntu-latest
+    runs-on: depot-ubuntu-24.04
     steps:
       - name: Checkout PR
         uses: actions/checkout@v4
         with:
           ref: ${{ github.event.client_payload.pr_head_sha }}
-      
+
       - name: Run compose setup
         run: |
           echo "Patching docker-compose.yml..."
@@ -25,17 +25,17 @@ jobs:
           yq eval 'del(.services.server.image)' -i packages/twenty-docker/docker-compose.yml
           yq eval '.services.server.build.context = "../../"' -i packages/twenty-docker/docker-compose.yml
           yq eval '.services.server.build.dockerfile = "./packages/twenty-docker/twenty/Dockerfile"' -i packages/twenty-docker/docker-compose.yml
-          
+
           yq eval 'del(.services.worker.image)' -i packages/twenty-docker/docker-compose.yml
           yq eval '.services.worker.build.context = "../../"' -i packages/twenty-docker/docker-compose.yml
           yq eval '.services.worker.build.dockerfile = "./packages/twenty-docker/twenty/Dockerfile"' -i packages/twenty-docker/docker-compose.yml
-          
+
           echo "Adding SIGN_IN_PREFILLED environment variable to server service..."
           yq eval '.services.server.environment.SIGN_IN_PREFILLED = "${SIGN_IN_PREFILLED}"' -i packages/twenty-docker/docker-compose.yml
-          
+
           echo "Setting up .env file..."
           cp packages/twenty-docker/.env.example packages/twenty-docker/.env
-          
+
           echo "Generating secrets..."
           echo "" >> packages/twenty-docker/.env
           echo "# === Randomly generated secrets ===" >> packages/twenty-docker/.env
@@ -46,24 +46,24 @@ jobs:
           cd packages/twenty-docker/
           docker compose build
         working-directory: ./
-      
+
       - name: Create Tunnel
         id: expose-tunnel
         uses: codetalkio/expose-tunnel@v1.5.0
         with:
           service: bore.pub
           port: 3000
-      
+
       - name: Start services with correct SERVER_URL
         run: |
           cd packages/twenty-docker/
-          
+
           # Update the SERVER_URL with the tunnel URL
           echo "Setting SERVER_URL to ${{ steps.expose-tunnel.outputs.tunnel-url }}"
           sed -i '/SERVER_URL=/d' .env
           echo "" >> .env
           echo "SERVER_URL=${{ steps.expose-tunnel.outputs.tunnel-url }}" >> .env
-          
+
           # Start the services
           echo "Docker compose up..."
           docker compose up -d || {
@@ -71,7 +71,7 @@ jobs:
               docker compose logs
               exit 1
           }
-          
+
           echo "Waiting for services to be ready..."
           count=0
           while [ ! $(docker inspect --format='{{.State.Health.Status}}' twenty-db-1) = "healthy" ] || [ ! $(docker inspect --format='{{.State.Health.Status}}' twenty-server-1) = "healthy" ]; do
@@ -84,7 +84,7 @@ jobs:
               fi
               echo "Still waiting for services... ($count/60)"
           done
-          
+
           echo "All services are up and running!"
         working-directory: ./
 
@@ -104,7 +104,7 @@ jobs:
           echo "✅ Preview Environment Ready!"
           echo "🔗 Preview URL: ${{ steps.expose-tunnel.outputs.tunnel-url }}"
           echo "⏱️ This environment will be available for 5 hours"
-      
+
       - name: Post comment on PR
         uses: actions/github-script@v6
         with:
@@ -113,21 +113,21 @@ jobs:
             const COMMENT_MARKER = '<!-- PR_PREVIEW_ENV -->';
             const commentBody = `${COMMENT_MARKER}
             🚀 **Preview Environment Ready!**
-            
+
             Your preview environment is available at: ${{ steps.expose-tunnel.outputs.tunnel-url }}
-            
+
             This environment will automatically shut down when the PR is closed or after 5 hours.`;
-            
+
             // Get all comments
             const {data: comments} = await github.rest.issues.listComments({
               owner: context.repo.owner,
               repo: context.repo.repo,
               issue_number: ${{ github.event.client_payload.pr_number }},
             });
-            
+
             // Find our comment
             const botComment = comments.find(comment => comment.body.includes(COMMENT_MARKER));
-            
+
             if (botComment) {
               // Update existing comment
               await github.rest.issues.updateComment({
@@ -147,13 +147,13 @@ jobs:
               });
               console.log('Created new comment');
             }
-      
+
       - name: Keep tunnel alive for 5 hours
         run: timeout 300m sleep 18000 # Stop on whichever we reach first (300m or 5hour sleep)
-      
+
       - name: Cleanup
         if: always()
         run: |
           cd packages/twenty-docker/
           docker compose down -v
-        working-directory: ./ 
+        working-directory: ./

.gitignore

@@ -10,6 +10,7 @@
 .nx/installation
 .nx/cache
 .nx/workspace-data
+.nx/nxw.js
 
 .pnp.*
 .yarn/*
@@ -49,3 +50,4 @@ dump.rdb
 mcp.json
 /.junie/
 TRANSLATION_QA_REPORT.md
+.playwright-mcp/

.nx/nxw.js

@@ -1,115 +0,0 @@
-"use strict";
-// This file should be committed to your repository! It wraps Nx and ensures
-// that your local installation matches nx.json.
-// See: https://nx.dev/recipes/installation/install-non-javascript for more info.
-
-
-
-
-Object.defineProperty(exports, "__esModule", { value: true });
-const fs = require('fs');
-const path = require('path');
-const cp = require('child_process');
-const installationPath = path.join(__dirname, 'installation', 'package.json');
-function matchesCurrentNxInstall(currentInstallation, nxJsonInstallation) {
-    if (!currentInstallation.devDependencies ||
-        !Object.keys(currentInstallation.devDependencies).length) {
-        return false;
-    }
-    try {
-        if (currentInstallation.devDependencies['nx'] !==
-            nxJsonInstallation.version ||
-            require(path.join(path.dirname(installationPath), 'node_modules', 'nx', 'package.json')).version !== nxJsonInstallation.version) {
-            return false;
-        }
-        for (const [plugin, desiredVersion] of Object.entries(nxJsonInstallation.plugins || {})) {
-            if (currentInstallation.devDependencies[plugin] !== desiredVersion) {
-                return false;
-            }
-        }
-        return true;
-    }
-    catch {
-        return false;
-    }
-}
-function ensureDir(p) {
-    if (!fs.existsSync(p)) {
-        fs.mkdirSync(p, { recursive: true });
-    }
-}
-function getCurrentInstallation() {
-    try {
-        return require(installationPath);
-    }
-    catch {
-        return {
-            name: 'nx-installation',
-            version: '0.0.0',
-            devDependencies: {},
-        };
-    }
-}
-function performInstallation(currentInstallation, nxJson) {
-    fs.writeFileSync(installationPath, JSON.stringify({
-        name: 'nx-installation',
-        devDependencies: {
-            nx: nxJson.installation.version,
-            ...nxJson.installation.plugins,
-        },
-    }));
-    try {
-        cp.execSync('npm i', {
-            cwd: path.dirname(installationPath),
-            stdio: 'inherit',
-        });
-    }
-    catch (e) {
-        // revert possible changes to the current installation
-        fs.writeFileSync(installationPath, JSON.stringify(currentInstallation));
-        // rethrow
-        throw e;
-    }
-}
-function ensureUpToDateInstallation() {
-    const nxJsonPath = path.join(__dirname, '..', 'nx.json');
-    let nxJson;
-    try {
-        nxJson = require(nxJsonPath);
-        if (!nxJson.installation) {
-            console.error('[NX]: The "installation" entry in the "nx.json" file is required when running the nx wrapper. See https://nx.dev/recipes/installation/install-non-javascript');
-            process.exit(1);
-        }
-    }
-    catch {
-        console.error('[NX]: The "nx.json" file is required when running the nx wrapper. See https://nx.dev/recipes/installation/install-non-javascript');
-        process.exit(1);
-    }
-    try {
-        ensureDir(path.join(__dirname, 'installation'));
-        const currentInstallation = getCurrentInstallation();
-        if (!matchesCurrentNxInstall(currentInstallation, nxJson.installation)) {
-            performInstallation(currentInstallation, nxJson);
-        }
-    }
-    catch (e) {
-        const messageLines = [
-            '[NX]: Nx wrapper failed to synchronize installation.',
-        ];
-        if (e instanceof Error) {
-            messageLines.push('');
-            messageLines.push(e.message);
-            messageLines.push(e.stack);
-        }
-        else {
-            messageLines.push(e.toString());
-        }
-        console.error(messageLines.join('\n'));
-        process.exit(1);
-    }
-}
-if (!process.env.NX_WRAPPER_SKIP_INSTALL) {
-    ensureUpToDateInstallation();
-}
-
-require('./installation/node_modules/nx/bin/nx');

.vscode/tasks.json

@@ -22,6 +22,28 @@
 				"close": false
 			},
 			"problemMatcher": []
+		},
+		{
+			"label": "twenty-server - run unit test file",
+			"type": "shell",
+			"command": "npx nx run twenty-server:jest -- --config ./jest.config.mjs ${relativeFile} --silent=false ${input:watchMode} ${input:updateSnapshot}",
+			"options": {
+				"cwd": "${workspaceFolder}/packages/twenty-server",
+				"env": {
+					"NODE_ENV": "test",
+					"NODE_OPTIONS": "--max-old-space-size=12288 --import tsx/esm"
+				},
+				"shell": {
+					"executable": "/bin/zsh",
+					"args": ["-l", "-c"]
+				}
+			},
+			"presentation": {
+				"reveal": "always",
+				"panel": "new",
+				"close": false
+			},
+			"problemMatcher": []
 		}
 	],
 	"inputs": [

CLAUDE.md

@@ -21,30 +21,33 @@ npx nx run twenty-server:worker  # Start background worker
 
 ### Testing
 ```bash
-# Run tests
+# 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         # Build Storybook
-npx nx storybook:test twenty-front     # Run Storybook tests
+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.
+# 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)
-npx nx lint:diff-with-main twenty-front           # Lint only files changed vs main
-npx nx lint:diff-with-main twenty-server          # Lint only files changed vs main
-npx nx lint:diff-with-main twenty-front --configuration=fix  # Auto-fix files changed vs main
+# 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)
-npx nx lint twenty-front      # Lint all files in frontend
-npx nx lint twenty-server     # Lint all files in backend
-npx nx lint twenty-front --fix  # Auto-fix all linting issues
+# 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
@@ -57,7 +60,8 @@ npx nx fmt twenty-server
 
 ### Build
 ```bash
-# Build packages
+# Build packages (twenty-shared must be built first)
+npx nx build twenty-shared
 npx nx build twenty-front
 npx nx build twenty-server
 ```
@@ -69,7 +73,7 @@ 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
 
-# Generate migration
+# Generate migration (replace [name] with kebab-case descriptive name)
 npx nx run twenty-server:typeorm migration:generate src/database/typeorm/core/migrations/common/[name] -d src/database/typeorm/core/core.datasource.ts
 
 # Sync metadata
@@ -78,8 +82,9 @@ npx nx run twenty-server:command workspace:sync-metadata
 
 ### GraphQL
 ```bash
-# Generate GraphQL types
+# 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
@@ -107,13 +112,36 @@ packages/
 - **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**
+- **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
-- **Recoil** for global state management
-- Component-specific state with React hooks
+- **Recoil** 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
@@ -122,36 +150,54 @@ packages/
 - **Redis** for caching and session management
 - **BullMQ** for background job processing
 
-### Database
+### Database & Migrations
 - **PostgreSQL** as primary database
 - **Redis** for caching and sessions
-- **TypeORM migrations** for schema management
 - **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
+
+### 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 and type checking after code changes
-2. Test changes with relevant test suites
-3. Ensure database migrations are properly structured
+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
 4. Check that GraphQL schema changes are backward compatible
+5. Run `graphql:generate` after any GraphQL schema changes
 
 ### Code Style Notes
 - Use **Emotion** for styling with styled-components pattern
 - Follow **Nx** workspace conventions for imports
 - Use **Lingui** for internationalization
-- Components should be in their own directories with tests and stories
+- Apply security first, then formatting (sanitize before format)
 
 ### Testing Strategy
-- **Unit tests** with Jest for both frontend and backend
-- **Integration tests** for critical backend workflows
-- **Storybook** for component development and testing
-- **E2E tests** with Playwright for critical user flows
+- **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()`
+
+## CI Environment (GitHub Actions)
+
+When running in CI, the dev environment is **not** pre-configured. Dependencies are installed but builds, env files, and databases are not set up.
+
+- **Before running tests, builds, lint, type checks, or DB operations**, run: `bash packages/twenty-utils/setup-dev-env.sh`
+- **Skip the setup script** for tasks that only read code — architecture questions, code review, documentation, etc.
+- The script is idempotent and safe to run multiple times.
 
 ## 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/` - Development guidelines and best practices
+- `.cursor/rules/` - Detailed development guidelines and best practices

README.md

@@ -28,7 +28,7 @@ See:
 🚀 [Self-hosting](https://docs.twenty.com/developers/self-hosting/docker-compose)
 🖥️ [Local Setup](https://docs.twenty.com/developers/local-setup)
 
-# Does the world need another CRM?
+# Why Twenty
 
 We built Twenty for three reasons:
 
@@ -120,6 +120,7 @@ Below are a few features we have implemented to date:
   <a href="https://greptile.com"><img src="./packages/twenty-website/public/images/readme/greptile.png" height="30" alt="Greptile" /></a>
   <a href="https://sentry.io/"><img src="./packages/twenty-website/public/images/readme/sentry.png" height="30" alt="Sentry" /></a>
   <a href="https://crowdin.com/"><img src="./packages/twenty-website/public/images/readme/crowdin.png" height="30" alt="Crowdin" /></a>
+  <a href="https://e2b.dev/"><img src="./packages/twenty-website/public/images/readme/e2b.svg" height="30" alt="E2B" /></a>
 </p>
 
   Thanks to these amazing services that we use and recommend for UI testing (Chromatic), code review (Greptile), catching bugs (Sentry) and translating (Crowdin).

eslint.config.mjs

@@ -11,7 +11,9 @@ import unicornPlugin from 'eslint-plugin-unicorn';
 import unusedImportsPlugin from 'eslint-plugin-unused-imports';
 import jsoncParser from 'jsonc-eslint-parser';
 
-const twentyRules = await nxPlugin.loadWorkspaceRules('packages/twenty-eslint-rules');
+const twentyRules = await nxPlugin.loadWorkspaceRules(
+  'packages/twenty-eslint-rules',
+);
 
 export default [
   // Base JavaScript configuration
@@ -65,6 +67,10 @@ export default [
               sourceTag: 'scope:sdk',
               onlyDependOnLibsWithTags: ['scope:sdk', 'scope:shared'],
             },
+            {
+              sourceTag: 'scope:create-app',
+              onlyDependOnLibsWithTags: ['scope:create-app', 'scope:shared'],
+            },
             {
               sourceTag: 'scope:shared',
               onlyDependOnLibsWithTags: ['scope:shared'],
@@ -197,7 +203,7 @@ export default [
     plugins: {
       ...mdxPlugin.flat.plugins,
       '@nx': nxPlugin,
-      'twenty': { rules: twentyRules },
+      twenty: { rules: twentyRules },
     },
   },
   mdxPlugin.flatCodeBlocks,

nx.json

@@ -118,6 +118,7 @@
       "outputs": ["{projectRoot}/coverage"],
       "options": {
         "jestConfig": "{projectRoot}/jest.config.mjs",
+        "silent": true,
         "coverage": true,
         "coverageReporters": ["text-summary"],
         "cacheDirectory": "../../.cache/jest/{projectRoot}"
@@ -272,9 +273,6 @@
       "inputs": ["default", "^default"]
     }
   },
-  "installation": {
-    "version": "22.3.3"
-  },
   "generators": {
     "@nx/react": {
       "application": {

package.json

@@ -22,6 +22,7 @@
     "googleapis": "105",
     "hex-rgb": "^5.0.0",
     "immer": "^10.1.1",
+    "jotai": "^2.17.1",
     "libphonenumber-js": "^1.10.26",
     "lodash.camelcase": "^4.3.0",
     "lodash.chunk": "^4.2.0",
@@ -90,10 +91,10 @@
     "@storybook/react-vite": "^10.1.11",
     "@storybook/test-runner": "^0.24.2",
     "@stylistic/eslint-plugin": "^1.5.0",
-    "@swc-node/register": "1.8.0",
+    "@swc-node/register": "1.11.1",
     "@swc/cli": "^0.3.12",
-    "@swc/core": "1.13.3",
-    "@swc/helpers": "~0.5.2",
+    "@swc/core": "1.15.11",
+    "@swc/helpers": "~0.5.18",
     "@swc/jest": "^0.2.39",
     "@testing-library/dom": "^10.4.0",
     "@testing-library/jest-dom": "^6.6.3",
@@ -136,10 +137,10 @@
     "@typescript-eslint/parser": "^8.39.0",
     "@typescript-eslint/utils": "^8.39.0",
     "@typescript/native-preview": "^7.0.0-dev.20260116.1",
-    "@vitejs/plugin-react-swc": "3.11.0",
-    "@vitest/browser-playwright": "^4.0.17",
-    "@vitest/coverage-istanbul": "^4.0.17",
-    "@vitest/coverage-v8": "^4.0.17",
+    "@vitejs/plugin-react-swc": "4.2.3",
+    "@vitest/browser-playwright": "^4.0.18",
+    "@vitest/coverage-istanbul": "^4.0.18",
+    "@vitest/coverage-v8": "^4.0.18",
     "@yarnpkg/types": "^4.0.0",
     "chromatic": "^6.18.0",
     "concurrently": "^8.2.2",
@@ -182,10 +183,11 @@
     "ts-jest": "^29.1.1",
     "ts-loader": "^9.2.3",
     "ts-node": "10.9.1",
+    "tsc-alias": "^1.8.16",
     "tsconfig-paths": "^4.2.0",
     "tsx": "^4.17.0",
     "vite": "^7.0.0",
-    "vitest": "^4.0.17"
+    "vitest": "^4.0.18"
   },
   "engines": {
     "node": "^24.5.0",
@@ -210,6 +212,7 @@
   "scripts": {
     "docs:generate": "tsx packages/twenty-docs/scripts/generate-docs-json.ts",
     "docs:generate-navigation-template": "tsx packages/twenty-docs/scripts/generate-navigation-template.ts",
+    "docs:generate-paths": "tsx packages/twenty-docs/scripts/generate-documentation-paths.ts",
     "start": "npx concurrently --kill-others 'npx nx run-many -t start -p twenty-server twenty-front' 'npx wait-on tcp:3000 && npx nx run twenty-server:worker'"
   },
   "workspaces": {

packages/create-twenty-app/README.md

@@ -15,9 +15,12 @@
 Create Twenty App is the official scaffolding CLI for building apps on top of [Twenty CRM](https://twenty.com). It sets up a ready‑to‑run project that works seamlessly with the [twenty-sdk](https://www.npmjs.com/package/twenty-sdk).
 
 - Zero‑config project bootstrap
-- Preconfigured scripts for auth, generate, dev sync, one‑off sync, uninstall
+- Preconfigured scripts for auth, dev mode (watch & sync), uninstall, and function management
 - Strong TypeScript support and typed client generation
 
+## Documentation
+See Twenty application documentation https://docs.twenty.com/developers/extend/capabilities/apps
+
 ## Prerequisites
 - Node.js 24+ (recommended) and Yarn 4
 - A Twenty workspace and an API key (create one at https://app.twenty.com/settings/api-webhooks)
@@ -32,41 +35,86 @@ cd my-twenty-app
 corepack enable
 yarn install
 
-# Get Help
-yarn run help
+# Get help and list all available commands
+yarn twenty help
 
 # Authenticate using your API key (you'll be prompted)
-yarn auth:login
+yarn twenty auth:login
 
 # Add a new entity to your application (guided)
-yarn entity:add
+yarn twenty entity:add
 
-# Generate a typed Twenty client and workspace entity types
-yarn app:generate
+# Start dev mode: watches, builds, and syncs local changes to your workspace
+# (also auto-generates a typed API client in node_modules/twenty-sdk/generated)
+yarn twenty app:dev
 
-# Start dev mode: automatically syncs local changes to your workspace
-yarn app:dev
+# Watch your application's function logs
+yarn twenty function:logs
 
-# Or run a one‑time sync
-yarn app:sync
+# Execute a function with a JSON payload
+yarn twenty function:execute -n my-function -p '{"key": "value"}'
 
-# Watch your application's functions logs
-yarn function:logs
+# Execute the post-install function
+yarn twenty function:execute --postInstall
 
 # Uninstall the application from the current workspace
-yarn app:uninstall
+yarn twenty app:uninstall
 ```
 
+## Scaffolding modes
+
+Control which example files are included when creating a new app:
+
+| Flag | Behavior |
+|------|----------|
+| `-e, --exhaustive` | **(default)** Creates all example files without prompting |
+| `-m, --minimal` | Creates only core files (`application-config.ts` and `default-role.ts`) |
+| `-i, --interactive` | Prompts you to select which examples to include |
+
+```bash
+# Default: all examples included
+npx create-twenty-app@latest my-app
+
+# Minimal: only core files
+npx create-twenty-app@latest my-app -m
+
+# Interactive: choose which examples to include
+npx create-twenty-app@latest my-app -i
+```
+
+In interactive mode, you can pick from:
+- **Example object** — a custom CRM object definition (`objects/example-object.ts`)
+- **Example field** — a custom field on the example object (`fields/example-field.ts`)
+- **Example logic function** — a server-side handler with HTTP trigger (`logic-functions/hello-world.ts`)
+- **Example front component** — a React UI component (`front-components/hello-world.tsx`)
+- **Example view** — a saved view for the example object (`views/example-view.ts`)
+- **Example navigation menu item** — a sidebar link (`navigation-menu-items/example-navigation-menu-item.ts`)
+- **Example skill** — an AI agent skill definition (`skills/example-skill.ts`)
+
 ## What gets scaffolded
-- A minimal app structure ready for Twenty
-- TypeScript configuration
-- Prewired scripts that wrap the `twenty` CLI from twenty-sdk
-- Example placeholders to help you add entities, actions, and sync logic
+
+**Core files (always created):**
+- `application-config.ts` — Application metadata configuration
+- `roles/default-role.ts` — Default role for logic functions
+- `logic-functions/post-install.ts` — Post-install logic function (runs after app installation)
+- TypeScript configuration, ESLint, package.json, .gitignore
+- A prewired `twenty` script that delegates to the `twenty` CLI from twenty-sdk
+
+**Example files (controlled by scaffolding mode):**
+- `objects/example-object.ts` — Example custom object with a text field
+- `fields/example-field.ts` — Example standalone field extending the example object
+- `logic-functions/hello-world.ts` — Example logic function with HTTP trigger
+- `front-components/hello-world.tsx` — Example front component
+- `views/example-view.ts` — Example saved view for the example object
+- `navigation-menu-items/example-navigation-menu-item.ts` — Example sidebar navigation link
+- `skills/example-skill.ts` — Example AI agent skill definition
 
 ## Next steps
-- Explore the generated project and add your first entity with `yarn entity:add`.
-- Keep your types up‑to‑date using `yarn app:generate`.
-- Use `yarn app:dev` while you iterate to see changes instantly in your workspace.
+- Run `yarn twenty help` to see all available commands.
+- Use `yarn twenty auth:login` to authenticate with your Twenty workspace.
+- Explore the generated project and add your first entity with `yarn twenty entity:add` (logic functions, front components, objects, roles, views, navigation menu items, skills).
+- Use `yarn twenty app:dev` while you iterate — it watches, builds, and syncs changes to your workspace in real time.
+- Types are auto‑generated by `yarn twenty app:dev` and stored in `node_modules/twenty-sdk/generated`.
 
 
 ## Publish your application
@@ -94,8 +142,8 @@ git push
 Our team reviews contributions for quality, security, and reusability before merging.
 
 ## Troubleshooting
-- Auth prompts not appearing: run `yarn auth:login` again and verify the API key permissions.
-- Types not generated: ensure `yarn app:generate` runs without errors, then re‑start `yarn app:dev`.
+- Auth prompts not appearing: run `yarn twenty auth:login` again and verify the API key permissions.
+- Types not generated: ensure `yarn twenty app:dev` is running — it auto‑generates the typed client.
 
 ## Contributing
 - See our [GitHub](https://github.com/twentyhq/twenty)

packages/create-twenty-app/eslint.config.mjs

@@ -1,111 +1,20 @@
-import js from '@eslint/js';
-import typescriptEslint from '@typescript-eslint/eslint-plugin';
-import typescriptParser from '@typescript-eslint/parser';
-import prettierPlugin from 'eslint-plugin-prettier';
+import baseConfig from '../../eslint.config.mjs';
 
 export default [
-  js.configs.recommended,
+  ...baseConfig,
   {
-    files: ['**/*.ts', '**/*.tsx'],
-    languageOptions: {
-      parser: typescriptParser,
-      parserOptions: {
-        ecmaVersion: 2022,
-        sourceType: 'module',
-      },
-      globals: {
-        // Node.js globals
-        process: 'readonly',
-        console: 'readonly',
-        Buffer: 'readonly',
-        __dirname: 'readonly',
-        __filename: 'readonly',
-        global: 'readonly',
-        setTimeout: 'readonly',
-        clearTimeout: 'readonly',
-        setInterval: 'readonly',
-        clearInterval: 'readonly',
-        // Browser globals that Node.js also has
-        URL: 'readonly',
-        URLSearchParams: 'readonly',
-        // Node.js types
-        NodeJS: 'readonly',
-      },
-    },
-    plugins: {
-      '@typescript-eslint': typescriptEslint,
-      prettier: prettierPlugin,
-    },
+    ignores: ['**/dist/**'],
+  },
+  {
+    files: ['**/*.{js,jsx,ts,tsx}'],
     rules: {
-      ...typescriptEslint.configs.recommended.rules,
       'prettier/prettier': 'error',
-      '@typescript-eslint/no-unused-vars': ['error', { argsIgnorePattern: '^_' }],
-      '@typescript-eslint/no-explicit-any': 'off',
-      '@typescript-eslint/explicit-function-return-type': 'off',
-      '@typescript-eslint/explicit-module-boundary-types': 'off',
-      '@typescript-eslint/no-empty-function': 'off',
-      'no-useless-escape': 'off',
     },
   },
   {
-    files: ['**/*.js'],
-    languageOptions: {
-      ecmaVersion: 2022,
-      sourceType: 'module',
-      globals: {
-        process: 'readonly',
-        console: 'readonly',
-        Buffer: 'readonly',
-        __dirname: 'readonly',
-        __filename: 'readonly',
-        global: 'readonly',
-      },
-    },
-  },
-  {
-    files: ['**/*.test.ts', '**/*.spec.ts', '**/__tests__/**/*.ts'],
-    languageOptions: {
-      parser: typescriptParser,
-      parserOptions: {
-        ecmaVersion: 2022,
-        sourceType: 'module',
-      },
-      globals: {
-        // Node.js globals
-        process: 'readonly',
-        console: 'readonly',
-        Buffer: 'readonly',
-        __dirname: 'readonly',
-        __filename: 'readonly',
-        global: 'readonly',
-        // Jest globals
-        describe: 'readonly',
-        it: 'readonly',
-        test: 'readonly',
-        expect: 'readonly',
-        jest: 'readonly',
-        beforeEach: 'readonly',
-        afterEach: 'readonly',
-        beforeAll: 'readonly',
-        afterAll: 'readonly',
-      },
-    },
-    plugins: {
-      '@typescript-eslint': typescriptEslint,
-      prettier: prettierPlugin,
-    },
     rules: {
-      ...typescriptEslint.configs.recommended.rules,
-      'prettier/prettier': 'error',
-      '@typescript-eslint/no-unused-vars': ['error', { argsIgnorePattern: '^_' }],
-      '@typescript-eslint/no-explicit-any': 'off',
-      '@typescript-eslint/explicit-function-return-type': 'off',
-      '@typescript-eslint/explicit-module-boundary-types': 'off',
-      '@typescript-eslint/no-empty-function': 'off',
-      'no-useless-escape': 'off',
+      'no-console': 'off',
     },
-  },
-  {
-    ignores: ['dist/**', 'node_modules/**'],
+    ignores: ['src/**/*.ts', '!src/cli/**/*.ts'],
   },
 ];

packages/create-twenty-app/package.json

@@ -1,11 +1,13 @@
 {
   "name": "create-twenty-app",
-  "version": "0.3.1",
+  "version": "0.6.0",
   "description": "Command-line interface to create Twenty application",
   "main": "dist/cli.cjs",
   "bin": "dist/cli.cjs",
   "files": [
-    "dist/**/*"
+    "dist",
+    "README.md",
+    "package.json"
   ],
   "scripts": {
     "build": "npx rimraf dist && npx vite build"
@@ -43,6 +45,9 @@
     "@types/lodash.kebabcase": "^4.1.7",
     "@types/lodash.startcase": "^4",
     "@types/node": "^20.0.0",
+    "twenty-sdk": "workspace:*",
+    "twenty-shared": "workspace:*",
+    "typescript": "^5.9.2",
     "vite": "^7.0.0",
     "vite-plugin-dts": "^4.5.4",
     "vite-tsconfig-paths": "^4.2.1"

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

@@ -2,6 +2,7 @@
 import chalk from 'chalk';
 import { Command, CommanderError } from 'commander';
 import { CreateAppCommand } from '@/create-app.command';
+import { type ScaffoldingMode } from '@/types/scaffolding-options';
 import packageJson from '../package.json';
 
 const program = new Command(packageJson.name)
@@ -12,18 +13,58 @@ const program = new Command(packageJson.name)
     'Output the current version of create-twenty-app.',
   )
   .argument('[directory]')
+  .option('-e, --exhaustive', 'Create all example entities (default)')
+  .option(
+    '-m, --minimal',
+    'Create only core entities (application-config and default-role)',
+  )
+  .option(
+    '-i, --interactive',
+    'Interactively choose which entity examples to include',
+  )
   .helpOption('-h, --help', 'Display this help message.')
-  .action(async (directory?: string) => {
-    if (directory && !/^[a-z0-9-]+$/.test(directory)) {
-      console.error(
-        chalk.red(
-          `Invalid directory "${directory}". Must contain only lowercase letters, numbers, and hyphens`,
-        ),
-      );
-      process.exit(1);
-    }
-    await new CreateAppCommand().execute(directory);
-  });
+  .action(
+    async (
+      directory?: string,
+      options?: {
+        exhaustive?: boolean;
+        minimal?: boolean;
+        interactive?: boolean;
+      },
+    ) => {
+      const modeFlags = [
+        options?.exhaustive,
+        options?.minimal,
+        options?.interactive,
+      ].filter(Boolean);
+
+      if (modeFlags.length > 1) {
+        console.error(
+          chalk.red(
+            'Error: --exhaustive, --minimal, and --interactive are mutually exclusive.',
+          ),
+        );
+        process.exit(1);
+      }
+
+      if (directory && !/^[a-z0-9-]+$/.test(directory)) {
+        console.error(
+          chalk.red(
+            `Invalid directory "${directory}". Must contain only lowercase letters, numbers, and hyphens`,
+          ),
+        );
+        process.exit(1);
+      }
+
+      const mode: ScaffoldingMode = options?.minimal
+        ? 'minimal'
+        : options?.interactive
+          ? 'interactive'
+          : 'exhaustive';
+
+      await new CreateAppCommand().execute(directory, mode);
+    },
+  );
 
 program.exitOverride();
 

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

@@ -0,0 +1,9 @@
+## Base documentation
+
+- Documentation: https://docs.twenty.com/developers/extend/capabilities/apps
+- Rich app example: https://github.com/twentyhq/twenty/tree/main/packages/twenty-sdk/src/cli/__tests__/apps/rich-app
+
+## 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.

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

@@ -5,41 +5,41 @@ This is a [Twenty](https://twenty.com) application project bootstrapped with [`c
 First, authenticate to your workspace:
 
 ```bash
-yarn auth:login
+yarn twenty auth:login
 ```
 
 Then, start development mode to sync your app and watch for changes:
 
 ```bash
-yarn app:dev
-```
-
-Or run a one-time sync:
-
-```bash
-yarn app:sync
+yarn twenty app:dev
 ```
 
 Open your Twenty instance and go to `/settings/applications` section to see the result.
 
 ## Available Commands
 
+Run `yarn twenty help` to list all available commands. Common commands:
+
 ```bash
 # Authentication
-yarn auth:login     # Authenticate with Twenty
-yarn auth:logout    # Remove credentials
-yarn auth:status    # Check auth status
+yarn twenty auth:login     # Authenticate with Twenty
+yarn twenty auth:logout    # Remove credentials
+yarn twenty auth:status    # Check auth status
+yarn twenty auth:switch    # Switch default workspace
+yarn twenty auth:list      # List all configured workspaces
 
 # Application
-yarn app:dev        # Start dev mode (sync + watch)
-yarn app:sync       # One-time sync
-yarn entity:add     # Add a new entity (function, object, role)
-yarn app:generate   # Generate typed Twenty client
-yarn function:logs  # Stream function logs
-yarn function:execute  # Execute a function with JSON payload
-yarn app:uninstall  # Uninstall app from workspace
+yarn twenty app:dev        # Start dev mode (watch, build, sync, and auto-generate typed client)
+yarn twenty entity:add     # Add a new entity (object, field, function, front-component, role, view, navigation-menu-item)
+yarn twenty function:logs  # Stream function logs
+yarn twenty function:execute  # Execute a function with JSON payload
+yarn twenty app:uninstall  # Uninstall app from workspace
 ```
 
+## LLMs instructions
+
+Main docs and pitfalls are available in LLMS.md file.
+
 ## Learn More
 
 To learn more about Twenty applications, take a look at the following resources:

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

@@ -8,14 +8,24 @@ import inquirer from 'inquirer';
 import kebabCase from 'lodash.kebabcase';
 import * as path from 'path';
 
+import {
+  type ExampleOptions,
+  type ScaffoldingMode,
+} from '@/types/scaffolding-options';
+
 const CURRENT_EXECUTION_DIRECTORY = process.env.INIT_CWD || process.cwd();
 
 export class CreateAppCommand {
-  async execute(directory?: string): Promise<void> {
+  async execute(
+    directory?: string,
+    mode: ScaffoldingMode = 'exhaustive',
+  ): Promise<void> {
     try {
       const { appName, appDisplayName, appDirectory, appDescription } =
         await this.getAppInfos(directory);
 
+      const exampleOptions = await this.resolveExampleOptions(mode);
+
       await this.validateDirectory(appDirectory);
 
       this.logCreationInfo({ appDirectory, appName });
@@ -27,6 +37,7 @@ export class CreateAppCommand {
         appDisplayName,
         appDescription,
         appDirectory,
+        exampleOptions,
       });
 
       await install(appDirectory);
@@ -92,6 +103,103 @@ export class CreateAppCommand {
     return { appName, appDisplayName, appDirectory, appDescription };
   }
 
+  private async resolveExampleOptions(
+    mode: ScaffoldingMode,
+  ): Promise<ExampleOptions> {
+    if (mode === 'minimal') {
+      return {
+        includeExampleObject: false,
+        includeExampleField: false,
+        includeExampleLogicFunction: false,
+        includeExampleFrontComponent: false,
+        includeExampleView: false,
+        includeExampleNavigationMenuItem: false,
+        includeExampleSkill: false,
+      };
+    }
+
+    if (mode === 'exhaustive') {
+      return {
+        includeExampleObject: true,
+        includeExampleField: true,
+        includeExampleLogicFunction: true,
+        includeExampleFrontComponent: true,
+        includeExampleView: true,
+        includeExampleNavigationMenuItem: true,
+        includeExampleSkill: true,
+      };
+    }
+
+    const { selectedExamples } = await inquirer.prompt([
+      {
+        type: 'checkbox',
+        name: 'selectedExamples',
+        message: 'Select which example files to include:',
+        choices: [
+          {
+            name: 'Example object (custom object definition)',
+            value: 'object',
+            checked: true,
+          },
+          {
+            name: 'Example field (custom field on the example object)',
+            value: 'field',
+            checked: true,
+          },
+          {
+            name: 'Example logic function (server-side handler)',
+            value: 'logicFunction',
+            checked: true,
+          },
+          {
+            name: 'Example front component (React UI component)',
+            value: 'frontComponent',
+            checked: true,
+          },
+          {
+            name: 'Example view (saved view for the example object)',
+            value: 'view',
+            checked: true,
+          },
+          {
+            name: 'Example navigation menu item (sidebar link)',
+            value: 'navigationMenuItem',
+            checked: true,
+          },
+          {
+            name: 'Example skill (AI agent skill definition)',
+            value: 'skill',
+            checked: true,
+          },
+        ],
+      },
+    ]);
+
+    const includeField = selectedExamples.includes('field');
+    const includeView = selectedExamples.includes('view');
+    const includeObject =
+      selectedExamples.includes('object') || includeField || includeView;
+
+    if ((includeField || includeView) && !selectedExamples.includes('object')) {
+      console.log(
+        chalk.yellow(
+          'Note: Example object auto-included because example field/view depends on it.',
+        ),
+      );
+    }
+
+    return {
+      includeExampleObject: includeObject,
+      includeExampleField: includeField,
+      includeExampleLogicFunction: selectedExamples.includes('logicFunction'),
+      includeExampleFrontComponent: selectedExamples.includes('frontComponent'),
+      includeExampleView: includeView,
+      includeExampleNavigationMenuItem:
+        selectedExamples.includes('navigationMenuItem'),
+      includeExampleSkill: selectedExamples.includes('skill'),
+    };
+  }
+
   private async validateDirectory(appDirectory: string): Promise<void> {
     if (!(await fs.pathExists(appDirectory))) {
       return;

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

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

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

@@ -1,7 +1,9 @@
-import * as fs from 'fs-extra';
-import { join } from 'path';
-import { tmpdir } from 'os';
+import { type ExampleOptions } from '@/types/scaffolding-options';
+import { GENERATED_DIR } from 'twenty-shared/application';
 import { copyBaseApplicationProject } from '@/utils/app-template';
+import * as fs from 'fs-extra';
+import { tmpdir } from 'os';
+import { join } from 'path';
 
 // Mock fs-extra's copy function to skip copying base template (not available during tests)
 jest.mock('fs-extra', () => {
@@ -12,6 +14,29 @@ jest.mock('fs-extra', () => {
   };
 });
 
+const APPLICATION_FILE_NAME = 'application-config.ts';
+const DEFAULT_ROLE_FILE_NAME = 'default-role.ts';
+
+const ALL_EXAMPLES: ExampleOptions = {
+  includeExampleObject: true,
+  includeExampleField: true,
+  includeExampleLogicFunction: true,
+  includeExampleFrontComponent: true,
+  includeExampleView: true,
+  includeExampleNavigationMenuItem: true,
+  includeExampleSkill: true,
+};
+
+const NO_EXAMPLES: ExampleOptions = {
+  includeExampleObject: false,
+  includeExampleField: false,
+  includeExampleSkill: false,
+  includeExampleLogicFunction: false,
+  includeExampleFrontComponent: false,
+  includeExampleView: false,
+  includeExampleNavigationMenuItem: false,
+};
+
 describe('copyBaseApplicationProject', () => {
   let testAppDirectory: string;
 
@@ -32,24 +57,25 @@ describe('copyBaseApplicationProject', () => {
     }
   });
 
-  it('should create the correct folder structure with src/app/', async () => {
+  it('should create the correct folder structure with src/', async () => {
     await copyBaseApplicationProject({
       appName: 'my-test-app',
       appDisplayName: 'My Test App',
       appDescription: 'A test application',
       appDirectory: testAppDirectory,
+      exampleOptions: ALL_EXAMPLES,
     });
 
-    // Verify src/app/ folder exists
+    // Verify src/ folder exists
     const srcAppPath = join(testAppDirectory, 'src');
     expect(await fs.pathExists(srcAppPath)).toBe(true);
 
-    // Verify application.config.ts exists in src/app/
-    const appConfigPath = join(srcAppPath, 'application.config.ts');
+    // Verify application-config.ts exists in src/
+    const appConfigPath = join(srcAppPath, APPLICATION_FILE_NAME);
     expect(await fs.pathExists(appConfigPath)).toBe(true);
 
-    // Verify default-function.role.ts exists in src/app/
-    const roleConfigPath = join(srcAppPath, 'default-function.role.ts');
+    // Verify default-role.ts exists in src/
+    const roleConfigPath = join(srcAppPath, 'roles', DEFAULT_ROLE_FILE_NAME);
     expect(await fs.pathExists(roleConfigPath)).toBe(true);
   });
 
@@ -59,6 +85,7 @@ describe('copyBaseApplicationProject', () => {
       appDisplayName: 'My Test App',
       appDescription: 'A test application',
       appDirectory: testAppDirectory,
+      exampleOptions: ALL_EXAMPLES,
     });
 
     const packageJsonPath = join(testAppDirectory, 'package.json');
@@ -67,9 +94,8 @@ describe('copyBaseApplicationProject', () => {
     const packageJson = await fs.readJson(packageJsonPath);
     expect(packageJson.name).toBe('my-test-app');
     expect(packageJson.version).toBe('0.1.0');
-    expect(packageJson.dependencies['twenty-sdk']).toBe('0.3.1');
-    expect(packageJson.scripts['app:sync']).toBe('twenty app:sync');
-    expect(packageJson.scripts['app:dev']).toBe('twenty app:dev');
+    expect(packageJson.dependencies['twenty-sdk']).toBe('latest');
+    expect(packageJson.scripts['twenty']).toBe('twenty');
   });
 
   it('should create .gitignore file', async () => {
@@ -78,6 +104,7 @@ describe('copyBaseApplicationProject', () => {
       appDisplayName: 'My Test App',
       appDescription: 'A test application',
       appDirectory: testAppDirectory,
+      exampleOptions: ALL_EXAMPLES,
     });
 
     const gitignorePath = join(testAppDirectory, '.gitignore');
@@ -85,7 +112,7 @@ describe('copyBaseApplicationProject', () => {
 
     const gitignoreContent = await fs.readFile(gitignorePath, 'utf8');
     expect(gitignoreContent).toContain('/node_modules');
-    expect(gitignoreContent).toContain('generated');
+    expect(gitignoreContent).toContain(GENERATED_DIR);
   });
 
   it('should create yarn.lock file', async () => {
@@ -94,6 +121,7 @@ describe('copyBaseApplicationProject', () => {
       appDisplayName: 'My Test App',
       appDescription: 'A test application',
       appDirectory: testAppDirectory,
+      exampleOptions: ALL_EXAMPLES,
     });
 
     const yarnLockPath = join(testAppDirectory, 'yarn.lock');
@@ -103,30 +131,27 @@ describe('copyBaseApplicationProject', () => {
     expect(yarnLockContent).toContain('yarn lockfile v1');
   });
 
-  it('should create application.config.ts with defineApp and correct values', async () => {
+  it('should create application-config.ts with defineApplication and correct values', async () => {
     await copyBaseApplicationProject({
       appName: 'my-test-app',
       appDisplayName: 'My Test App',
       appDescription: 'A test application',
       appDirectory: testAppDirectory,
+      exampleOptions: ALL_EXAMPLES,
     });
 
-    const appConfigPath = join(
-      testAppDirectory,
-      'src',
-      'application.config.ts',
-    );
+    const appConfigPath = join(testAppDirectory, 'src', APPLICATION_FILE_NAME);
     const appConfigContent = await fs.readFile(appConfigPath, 'utf8');
 
-    // Verify it uses defineApp
+    // Verify it uses defineApplication
     expect(appConfigContent).toContain(
-      "import { defineApp } from 'twenty-sdk'",
+      "import { defineApplication } from 'twenty-sdk'",
     );
-    expect(appConfigContent).toContain('export default defineApp({');
+    expect(appConfigContent).toContain('export default defineApplication({');
 
     // Verify it imports the role identifier
     expect(appConfigContent).toContain(
-      "import { DEFAULT_FUNCTION_ROLE_UNIVERSAL_IDENTIFIER } from 'src/default-function.role'",
+      "import { DEFAULT_ROLE_UNIVERSAL_IDENTIFIER } from 'src/roles/default-role'",
     );
 
     // Verify display name and description
@@ -140,22 +165,24 @@ describe('copyBaseApplicationProject', () => {
 
     // Verify it references the role
     expect(appConfigContent).toContain(
-      'functionRoleUniversalIdentifier: DEFAULT_FUNCTION_ROLE_UNIVERSAL_IDENTIFIER',
+      'defaultRoleUniversalIdentifier: DEFAULT_ROLE_UNIVERSAL_IDENTIFIER',
     );
   });
 
-  it('should create default-function.role.ts with defineRole and correct values', async () => {
+  it('should create default-role.ts with defineRole and correct values', async () => {
     await copyBaseApplicationProject({
       appName: 'my-test-app',
       appDisplayName: 'My Test App',
       appDescription: 'A test application',
       appDirectory: testAppDirectory,
+      exampleOptions: ALL_EXAMPLES,
     });
 
     const roleConfigPath = join(
       testAppDirectory,
       'src',
-      'default-function.role.ts',
+      'roles',
+      DEFAULT_ROLE_FILE_NAME,
     );
     const roleConfigContent = await fs.readFile(roleConfigPath, 'utf8');
 
@@ -167,7 +194,7 @@ describe('copyBaseApplicationProject', () => {
 
     // Verify it exports the universal identifier constant
     expect(roleConfigContent).toContain(
-      'export const DEFAULT_FUNCTION_ROLE_UNIVERSAL_IDENTIFIER',
+      'export const DEFAULT_ROLE_UNIVERSAL_IDENTIFIER',
     );
 
     // Verify role label includes app name
@@ -183,7 +210,7 @@ describe('copyBaseApplicationProject', () => {
 
     // Verify it has a universalIdentifier (UUID format)
     expect(roleConfigContent).toMatch(
-      /universalIdentifier: DEFAULT_FUNCTION_ROLE_UNIVERSAL_IDENTIFIER/,
+      /universalIdentifier: DEFAULT_ROLE_UNIVERSAL_IDENTIFIER/,
     );
   });
 
@@ -193,6 +220,7 @@ describe('copyBaseApplicationProject', () => {
       appDisplayName: 'My Test App',
       appDescription: 'A test application',
       appDirectory: testAppDirectory,
+      exampleOptions: ALL_EXAMPLES,
     });
 
     // Verify fs.copy was called with correct destination
@@ -209,13 +237,10 @@ describe('copyBaseApplicationProject', () => {
       appDisplayName: 'My Test App',
       appDescription: '',
       appDirectory: testAppDirectory,
+      exampleOptions: ALL_EXAMPLES,
     });
 
-    const appConfigPath = join(
-      testAppDirectory,
-      'src',
-      'application.config.ts',
-    );
+    const appConfigPath = join(testAppDirectory, 'src', APPLICATION_FILE_NAME);
     const appConfigContent = await fs.readFile(appConfigPath, 'utf8');
 
     expect(appConfigContent).toContain("description: ''");
@@ -230,6 +255,7 @@ describe('copyBaseApplicationProject', () => {
       appDisplayName: 'App One',
       appDescription: 'First app',
       appDirectory: firstAppDir,
+      exampleOptions: ALL_EXAMPLES,
     });
 
     // Create second app
@@ -240,15 +266,16 @@ describe('copyBaseApplicationProject', () => {
       appDisplayName: 'App Two',
       appDescription: 'Second app',
       appDirectory: secondAppDir,
+      exampleOptions: ALL_EXAMPLES,
     });
 
     // Read both app configs
     const firstAppConfig = await fs.readFile(
-      join(firstAppDir, 'src', 'application.config.ts'),
+      join(firstAppDir, 'src', APPLICATION_FILE_NAME),
       'utf8',
     );
     const secondAppConfig = await fs.readFile(
-      join(secondAppDir, 'src', 'application.config.ts'),
+      join(secondAppDir, 'src', APPLICATION_FILE_NAME),
       'utf8',
     );
 
@@ -272,6 +299,7 @@ describe('copyBaseApplicationProject', () => {
       appDisplayName: 'App One',
       appDescription: 'First app',
       appDirectory: firstAppDir,
+      exampleOptions: ALL_EXAMPLES,
     });
 
     // Create second app
@@ -282,21 +310,22 @@ describe('copyBaseApplicationProject', () => {
       appDisplayName: 'App Two',
       appDescription: 'Second app',
       appDirectory: secondAppDir,
+      exampleOptions: ALL_EXAMPLES,
     });
 
-    // Read both role configs
     const firstRoleConfig = await fs.readFile(
-      join(firstAppDir, 'src', 'default-function.role.ts'),
+      join(firstAppDir, 'src', 'roles', DEFAULT_ROLE_FILE_NAME),
       'utf8',
     );
+
     const secondRoleConfig = await fs.readFile(
-      join(secondAppDir, 'src', 'default-function.role.ts'),
+      join(secondAppDir, 'src', 'roles', DEFAULT_ROLE_FILE_NAME),
       'utf8',
     );
 
     // Extract UUIDs using regex
     const uuidRegex =
-      /DEFAULT_FUNCTION_ROLE_UNIVERSAL_IDENTIFIER =\s*'([0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})'/;
+      /DEFAULT_ROLE_UNIVERSAL_IDENTIFIER =\s*'([0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})'/;
     const firstUuid = firstRoleConfig.match(uuidRegex)?.[1];
     const secondUuid = secondRoleConfig.match(uuidRegex)?.[1];
 
@@ -304,4 +333,347 @@ describe('copyBaseApplicationProject', () => {
     expect(secondUuid).toBeDefined();
     expect(firstUuid).not.toBe(secondUuid);
   });
+
+  describe('scaffolding modes', () => {
+    describe('exhaustive mode (all examples)', () => {
+      it('should create all example files when all options are enabled', async () => {
+        await copyBaseApplicationProject({
+          appName: 'my-test-app',
+          appDisplayName: 'My Test App',
+          appDescription: 'A test application',
+          appDirectory: testAppDirectory,
+          exampleOptions: ALL_EXAMPLES,
+        });
+
+        const srcPath = join(testAppDirectory, 'src');
+
+        expect(
+          await fs.pathExists(join(srcPath, 'objects', 'example-object.ts')),
+        ).toBe(true);
+        expect(
+          await fs.pathExists(join(srcPath, 'fields', 'example-field.ts')),
+        ).toBe(true);
+        expect(
+          await fs.pathExists(
+            join(srcPath, 'logic-functions', 'hello-world.ts'),
+          ),
+        ).toBe(true);
+        expect(
+          await fs.pathExists(
+            join(srcPath, 'front-components', 'hello-world.tsx'),
+          ),
+        ).toBe(true);
+        expect(
+          await fs.pathExists(join(srcPath, 'views', 'example-view.ts')),
+        ).toBe(true);
+        expect(
+          await fs.pathExists(
+            join(
+              srcPath,
+              'navigation-menu-items',
+              'example-navigation-menu-item.ts',
+            ),
+          ),
+        ).toBe(true);
+      });
+    });
+
+    describe('minimal mode (no examples)', () => {
+      it('should create only core files when no examples are enabled', async () => {
+        await copyBaseApplicationProject({
+          appName: 'my-test-app',
+          appDisplayName: 'My Test App',
+          appDescription: 'A test application',
+          appDirectory: testAppDirectory,
+          exampleOptions: NO_EXAMPLES,
+        });
+
+        const srcPath = join(testAppDirectory, 'src');
+
+        // Core files should exist
+        expect(await fs.pathExists(join(srcPath, APPLICATION_FILE_NAME))).toBe(
+          true,
+        );
+        expect(
+          await fs.pathExists(join(srcPath, 'roles', DEFAULT_ROLE_FILE_NAME)),
+        ).toBe(true);
+
+        // Example files should not exist
+        expect(
+          await fs.pathExists(join(srcPath, 'objects', 'example-object.ts')),
+        ).toBe(false);
+        expect(
+          await fs.pathExists(join(srcPath, 'fields', 'example-field.ts')),
+        ).toBe(false);
+        expect(
+          await fs.pathExists(
+            join(srcPath, 'logic-functions', 'hello-world.ts'),
+          ),
+        ).toBe(false);
+        expect(
+          await fs.pathExists(
+            join(srcPath, 'front-components', 'hello-world.tsx'),
+          ),
+        ).toBe(false);
+        expect(
+          await fs.pathExists(join(srcPath, 'views', 'example-view.ts')),
+        ).toBe(false);
+        expect(
+          await fs.pathExists(
+            join(
+              srcPath,
+              'navigation-menu-items',
+              'example-navigation-menu-item.ts',
+            ),
+          ),
+        ).toBe(false);
+      });
+    });
+
+    describe('selective examples', () => {
+      it('should create only front component when only that option is enabled', async () => {
+        await copyBaseApplicationProject({
+          appName: 'my-test-app',
+          appDisplayName: 'My Test App',
+          appDescription: 'A test application',
+          appDirectory: testAppDirectory,
+          exampleOptions: {
+            includeExampleObject: false,
+            includeExampleField: false,
+            includeExampleSkill: false,
+            includeExampleLogicFunction: false,
+            includeExampleFrontComponent: true,
+            includeExampleView: false,
+            includeExampleNavigationMenuItem: false,
+          },
+        });
+
+        const srcPath = join(testAppDirectory, 'src');
+
+        expect(
+          await fs.pathExists(
+            join(srcPath, 'front-components', 'hello-world.tsx'),
+          ),
+        ).toBe(true);
+        expect(
+          await fs.pathExists(join(srcPath, 'objects', 'example-object.ts')),
+        ).toBe(false);
+        expect(
+          await fs.pathExists(join(srcPath, 'fields', 'example-field.ts')),
+        ).toBe(false);
+        expect(
+          await fs.pathExists(
+            join(srcPath, 'logic-functions', 'hello-world.ts'),
+          ),
+        ).toBe(false);
+      });
+
+      it('should create only logic function when only that option is enabled', async () => {
+        await copyBaseApplicationProject({
+          appName: 'my-test-app',
+          appDisplayName: 'My Test App',
+          appDescription: 'A test application',
+          appDirectory: testAppDirectory,
+          exampleOptions: {
+            includeExampleObject: false,
+            includeExampleSkill: false,
+            includeExampleField: false,
+            includeExampleLogicFunction: true,
+            includeExampleFrontComponent: false,
+            includeExampleView: false,
+            includeExampleNavigationMenuItem: false,
+          },
+        });
+
+        const srcPath = join(testAppDirectory, 'src');
+
+        expect(
+          await fs.pathExists(
+            join(srcPath, 'logic-functions', 'hello-world.ts'),
+          ),
+        ).toBe(true);
+        expect(
+          await fs.pathExists(join(srcPath, 'objects', 'example-object.ts')),
+        ).toBe(false);
+      });
+    });
+  });
+
+  describe('example object', () => {
+    it('should create example-object.ts with defineObject and correct structure', async () => {
+      await copyBaseApplicationProject({
+        appName: 'my-test-app',
+        appDisplayName: 'My Test App',
+        appDescription: 'A test application',
+        appDirectory: testAppDirectory,
+        exampleOptions: ALL_EXAMPLES,
+      });
+
+      const objectPath = join(
+        testAppDirectory,
+        'src',
+        'objects',
+        'example-object.ts',
+      );
+
+      expect(await fs.pathExists(objectPath)).toBe(true);
+
+      const content = await fs.readFile(objectPath, 'utf8');
+
+      expect(content).toContain(
+        "import { defineObject, FieldType } from 'twenty-sdk'",
+      );
+      expect(content).toContain('export default defineObject({');
+      expect(content).toContain(
+        'export const EXAMPLE_OBJECT_UNIVERSAL_IDENTIFIER',
+      );
+      expect(content).toContain('export const NAME_FIELD_UNIVERSAL_IDENTIFIER');
+      expect(content).toContain("nameSingular: 'exampleItem'");
+      expect(content).toContain("namePlural: 'exampleItems'");
+      expect(content).toContain('FieldType.TEXT');
+      expect(content).toContain(
+        'labelIdentifierFieldMetadataUniversalIdentifier: NAME_FIELD_UNIVERSAL_IDENTIFIER',
+      );
+    });
+
+    it('should generate unique UUIDs for example objects across apps', async () => {
+      const firstAppDir = join(testAppDirectory, 'app1');
+      await fs.ensureDir(firstAppDir);
+      await copyBaseApplicationProject({
+        appName: 'app-one',
+        appDisplayName: 'App One',
+        appDescription: 'First app',
+        appDirectory: firstAppDir,
+        exampleOptions: ALL_EXAMPLES,
+      });
+
+      const secondAppDir = join(testAppDirectory, 'app2');
+      await fs.ensureDir(secondAppDir);
+      await copyBaseApplicationProject({
+        appName: 'app-two',
+        appDisplayName: 'App Two',
+        appDescription: 'Second app',
+        appDirectory: secondAppDir,
+        exampleOptions: ALL_EXAMPLES,
+      });
+
+      const firstContent = await fs.readFile(
+        join(firstAppDir, 'src', 'objects', 'example-object.ts'),
+        'utf8',
+      );
+      const secondContent = await fs.readFile(
+        join(secondAppDir, 'src', 'objects', 'example-object.ts'),
+        'utf8',
+      );
+
+      const uuidRegex =
+        /EXAMPLE_OBJECT_UNIVERSAL_IDENTIFIER =\s*'([0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})'/;
+      const firstUuid = firstContent.match(uuidRegex)?.[1];
+      const secondUuid = secondContent.match(uuidRegex)?.[1];
+
+      expect(firstUuid).toBeDefined();
+      expect(secondUuid).toBeDefined();
+      expect(firstUuid).not.toBe(secondUuid);
+    });
+  });
+
+  describe('example field', () => {
+    it('should create example-field.ts with defineField referencing the object', async () => {
+      await copyBaseApplicationProject({
+        appName: 'my-test-app',
+        appDisplayName: 'My Test App',
+        appDescription: 'A test application',
+        appDirectory: testAppDirectory,
+        exampleOptions: ALL_EXAMPLES,
+      });
+
+      const fieldPath = join(
+        testAppDirectory,
+        'src',
+        'fields',
+        'example-field.ts',
+      );
+
+      expect(await fs.pathExists(fieldPath)).toBe(true);
+
+      const content = await fs.readFile(fieldPath, 'utf8');
+
+      expect(content).toContain(
+        "import { defineField, FieldType } from 'twenty-sdk'",
+      );
+      expect(content).toContain(
+        "import { EXAMPLE_OBJECT_UNIVERSAL_IDENTIFIER } from 'src/objects/example-object'",
+      );
+      expect(content).toContain('export default defineField({');
+      expect(content).toContain(
+        'objectUniversalIdentifier: EXAMPLE_OBJECT_UNIVERSAL_IDENTIFIER',
+      );
+      expect(content).toContain('FieldType.NUMBER');
+      expect(content).toContain("name: 'priority'");
+    });
+  });
+
+  describe('example view', () => {
+    it('should create example-view.ts with defineView referencing the object', async () => {
+      await copyBaseApplicationProject({
+        appName: 'my-test-app',
+        appDisplayName: 'My Test App',
+        appDescription: 'A test application',
+        appDirectory: testAppDirectory,
+        exampleOptions: ALL_EXAMPLES,
+      });
+
+      const viewPath = join(
+        testAppDirectory,
+        'src',
+        'views',
+        'example-view.ts',
+      );
+
+      expect(await fs.pathExists(viewPath)).toBe(true);
+
+      const content = await fs.readFile(viewPath, 'utf8');
+
+      expect(content).toContain("import { defineView } from 'twenty-sdk'");
+      expect(content).toContain(
+        "import { EXAMPLE_OBJECT_UNIVERSAL_IDENTIFIER } from 'src/objects/example-object'",
+      );
+      expect(content).toContain('export default defineView({');
+      expect(content).toContain(
+        'objectUniversalIdentifier: EXAMPLE_OBJECT_UNIVERSAL_IDENTIFIER',
+      );
+      expect(content).toContain("name: 'example-view'");
+    });
+  });
+
+  describe('example navigation menu item', () => {
+    it('should create example-navigation-menu-item.ts with defineNavigationMenuItem', async () => {
+      await copyBaseApplicationProject({
+        appName: 'my-test-app',
+        appDisplayName: 'My Test App',
+        appDescription: 'A test application',
+        appDirectory: testAppDirectory,
+        exampleOptions: ALL_EXAMPLES,
+      });
+
+      const navPath = join(
+        testAppDirectory,
+        'src',
+        'navigation-menu-items',
+        'example-navigation-menu-item.ts',
+      );
+
+      expect(await fs.pathExists(navPath)).toBe(true);
+
+      const content = await fs.readFile(navPath, 'utf8');
+
+      expect(content).toContain(
+        "import { defineNavigationMenuItem } from 'twenty-sdk'",
+      );
+      expect(content).toContain('export default defineNavigationMenuItem({');
+      expect(content).toContain("name: 'example-navigation-menu-item'");
+      expect(content).toContain("icon: 'IconList'");
+      expect(content).toContain('position: 0');
+    });
+  });
 });

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

@@ -1,19 +1,24 @@
 import * as fs from 'fs-extra';
 import { join } from 'path';
 import { v4 } from 'uuid';
+import { ASSETS_DIR } from 'twenty-shared/application';
 
-const APP_FOLDER = 'src';
+import { type ExampleOptions } from '@/types/scaffolding-options';
+
+const SRC_FOLDER = 'src';
 
 export const copyBaseApplicationProject = async ({
   appName,
   appDisplayName,
   appDescription,
   appDirectory,
+  exampleOptions,
 }: {
   appName: string;
   appDisplayName: string;
   appDescription: string;
   appDirectory: string;
+  exampleOptions: ExampleOptions;
 }) => {
   await fs.copy(join(__dirname, './constants/base-application'), appDirectory);
 
@@ -21,32 +26,95 @@ export const copyBaseApplicationProject = async ({
 
   await createGitignore(appDirectory);
 
+  await createPublicAssetDirectory(appDirectory);
+
   await createYarnLock(appDirectory);
 
-  const appFolderPath = join(appDirectory, APP_FOLDER);
+  const sourceFolderPath = join(appDirectory, SRC_FOLDER);
 
-  await fs.ensureDir(appFolderPath);
+  await fs.ensureDir(sourceFolderPath);
 
-  await createDefaultServerlessFunctionRoleConfig({
+  await createDefaultRoleConfig({
     displayName: appDisplayName,
-    appDirectory: appFolderPath,
+    appDirectory: sourceFolderPath,
+    fileFolder: 'roles',
+    fileName: 'default-role.ts',
   });
 
-  await createDefaultFrontComponent({
-    appDirectory: appFolderPath,
-  });
+  if (exampleOptions.includeExampleObject) {
+    await createExampleObject({
+      appDirectory: sourceFolderPath,
+      fileFolder: 'objects',
+      fileName: 'example-object.ts',
+    });
+  }
 
-  await createDefaultFunction({
-    appDirectory: appFolderPath,
+  if (exampleOptions.includeExampleField) {
+    await createExampleField({
+      appDirectory: sourceFolderPath,
+      fileFolder: 'fields',
+      fileName: 'example-field.ts',
+    });
+  }
+
+  if (exampleOptions.includeExampleLogicFunction) {
+    await createDefaultFunction({
+      appDirectory: sourceFolderPath,
+      fileFolder: 'logic-functions',
+      fileName: 'hello-world.ts',
+    });
+  }
+
+  if (exampleOptions.includeExampleFrontComponent) {
+    await createDefaultFrontComponent({
+      appDirectory: sourceFolderPath,
+      fileFolder: 'front-components',
+      fileName: 'hello-world.tsx',
+    });
+  }
+
+  if (exampleOptions.includeExampleView) {
+    await createExampleView({
+      appDirectory: sourceFolderPath,
+      fileFolder: 'views',
+      fileName: 'example-view.ts',
+    });
+  }
+
+  if (exampleOptions.includeExampleNavigationMenuItem) {
+    await createExampleNavigationMenuItem({
+      appDirectory: sourceFolderPath,
+      fileFolder: 'navigation-menu-items',
+      fileName: 'example-navigation-menu-item.ts',
+    });
+  }
+
+  if (exampleOptions.includeExampleSkill) {
+    await createExampleSkill({
+      appDirectory: sourceFolderPath,
+      fileFolder: 'skills',
+      fileName: 'example-skill.ts',
+    });
+  }
+
+  await createDefaultPostInstallFunction({
+    appDirectory: sourceFolderPath,
+    fileFolder: 'logic-functions',
+    fileName: 'post-install.ts',
   });
 
   await createApplicationConfig({
     displayName: appDisplayName,
     description: appDescription,
-    appDirectory: appFolderPath,
+    appDirectory: sourceFolderPath,
+    fileName: 'application-config.ts',
   });
 };
 
+const createPublicAssetDirectory = async (appDirectory: string) => {
+  await fs.ensureDir(join(appDirectory, ASSETS_DIR));
+};
+
 const createYarnLock = async (appDirectory: string) => {
   const yarnLockContent = `# THIS IS AN AUTOGENERATED FILE. DO NOT EDIT THIS FILE DIRECTLY.
 # yarn lockfile v1
@@ -71,7 +139,9 @@ generated
 
 # dev
 /dist/
-.twenty
+
+.twenty/*
+!.twenty/output/
 
 # production
 /build
@@ -96,22 +166,26 @@ yarn-error.log*
   await fs.writeFile(join(appDirectory, '.gitignore'), gitignoreContent);
 };
 
-const createDefaultServerlessFunctionRoleConfig = async ({
+const createDefaultRoleConfig = async ({
   displayName,
   appDirectory,
+  fileFolder,
+  fileName,
 }: {
   displayName: string;
   appDirectory: string;
+  fileFolder?: string;
+  fileName: string;
 }) => {
   const universalIdentifier = v4();
 
   const content = `import { defineRole } from 'twenty-sdk';
 
-export const DEFAULT_FUNCTION_ROLE_UNIVERSAL_IDENTIFIER =
+export const DEFAULT_ROLE_UNIVERSAL_IDENTIFIER =
   '${universalIdentifier}';
 
 export default defineRole({
-  universalIdentifier: DEFAULT_FUNCTION_ROLE_UNIVERSAL_IDENTIFIER,
+  universalIdentifier: DEFAULT_ROLE_UNIVERSAL_IDENTIFIER,
   label: '${displayName} default function role',
   description: '${displayName} default function role',
   canReadAllObjectRecords: true,
@@ -121,13 +195,18 @@ export default defineRole({
 });
 `;
 
-  await fs.writeFile(join(appDirectory, 'default-function.role.ts'), content);
+  await fs.ensureDir(join(appDirectory, fileFolder ?? ''));
+  await fs.writeFile(join(appDirectory, fileFolder ?? '', fileName), content);
 };
 
 const createDefaultFrontComponent = async ({
   appDirectory,
+  fileFolder,
+  fileName,
 }: {
   appDirectory: string;
+  fileFolder?: string;
+  fileName: string;
 }) => {
   const universalIdentifier = v4();
 
@@ -150,68 +229,267 @@ export default defineFrontComponent({
 });
 `;
 
-  await fs.writeFile(
-    join(appDirectory, 'hello-world.front-component.tsx'),
-    content,
-  );
+  await fs.ensureDir(join(appDirectory, fileFolder ?? ''));
+  await fs.writeFile(join(appDirectory, fileFolder ?? '', fileName), content);
 };
 
 const createDefaultFunction = async ({
   appDirectory,
+  fileFolder,
+  fileName,
 }: {
   appDirectory: string;
+  fileFolder?: string;
+  fileName: string;
 }) => {
   const universalIdentifier = v4();
-  const triggerUniversalIdentifier = v4();
 
-  const content = `import { defineFunction } from 'twenty-sdk';
+  const content = `import { defineLogicFunction } from 'twenty-sdk';
 
 const handler = async (): Promise<{ message: string }> => {
   return { message: 'Hello, World!' };
 };
 
-export default defineFunction({
+export default defineLogicFunction({
   universalIdentifier: '${universalIdentifier}',
-  name: 'hello-world-function',
-  description: 'A sample serverless function',
+  name: 'hello-world-logic-function',
+  description: 'A simple logic function',
   timeoutSeconds: 5,
   handler,
-  triggers: [
+  httpRouteTriggerSettings: {
+    path: '/hello-world-logic-function',
+    httpMethod: 'GET',
+    isAuthRequired: false,
+  },
+});
+`;
+
+  await fs.ensureDir(join(appDirectory, fileFolder ?? ''));
+  await fs.writeFile(join(appDirectory, fileFolder ?? '', fileName), content);
+};
+
+const createDefaultPostInstallFunction = async ({
+  appDirectory,
+  fileFolder,
+  fileName,
+}: {
+  appDirectory: string;
+  fileFolder?: string;
+  fileName: string;
+}) => {
+  const universalIdentifier = v4();
+
+  const content = `import { defineLogicFunction } from 'twenty-sdk';
+
+export const POST_INSTALL_UNIVERSAL_IDENTIFIER = '${universalIdentifier}';
+
+const handler = async (): Promise<void> => {
+  console.log('Post install logic function executed successfully!');
+};
+
+export default defineLogicFunction({
+  universalIdentifier: POST_INSTALL_UNIVERSAL_IDENTIFIER,
+  name: 'post-install',
+  description: 'Runs after installation to set up the application.',
+  timeoutSeconds: 300,
+  handler,
+});
+`;
+
+  await fs.ensureDir(join(appDirectory, fileFolder ?? ''));
+  await fs.writeFile(join(appDirectory, fileFolder ?? '', fileName), content);
+};
+
+const createExampleObject = async ({
+  appDirectory,
+  fileFolder,
+  fileName,
+}: {
+  appDirectory: string;
+  fileFolder?: string;
+  fileName: string;
+}) => {
+  const objectUniversalIdentifier = v4();
+  const nameFieldUniversalIdentifier = v4();
+
+  const content = `import { defineObject, FieldType } from 'twenty-sdk';
+
+export const EXAMPLE_OBJECT_UNIVERSAL_IDENTIFIER =
+  '${objectUniversalIdentifier}';
+
+export const NAME_FIELD_UNIVERSAL_IDENTIFIER =
+  '${nameFieldUniversalIdentifier}';
+
+export default defineObject({
+  universalIdentifier: EXAMPLE_OBJECT_UNIVERSAL_IDENTIFIER,
+  nameSingular: 'exampleItem',
+  namePlural: 'exampleItems',
+  labelSingular: 'Example item',
+  labelPlural: 'Example items',
+  description: 'A sample custom object',
+  icon: 'IconBox',
+  labelIdentifierFieldMetadataUniversalIdentifier: NAME_FIELD_UNIVERSAL_IDENTIFIER,
+  fields: [
     {
-      universalIdentifier: '${triggerUniversalIdentifier}',
-      type: 'route',
-      path: '/hello-world-function',
-      httpMethod: 'GET',
-      isAuthRequired: false,
+      universalIdentifier: NAME_FIELD_UNIVERSAL_IDENTIFIER,
+      type: FieldType.TEXT,
+      name: 'name',
+      label: 'Name',
+      description: 'Name of the example item',
+      icon: 'IconAbc',
     },
   ],
 });
 `;
 
-  await fs.writeFile(join(appDirectory, 'hello-world.function.ts'), content);
+  await fs.ensureDir(join(appDirectory, fileFolder ?? ''));
+  await fs.writeFile(join(appDirectory, fileFolder ?? '', fileName), content);
+};
+
+const createExampleField = async ({
+  appDirectory,
+  fileFolder,
+  fileName,
+}: {
+  appDirectory: string;
+  fileFolder?: string;
+  fileName: string;
+}) => {
+  const universalIdentifier = v4();
+
+  const content = `import { defineField, FieldType } from 'twenty-sdk';
+import { EXAMPLE_OBJECT_UNIVERSAL_IDENTIFIER } from 'src/objects/example-object';
+
+export default defineField({
+  objectUniversalIdentifier: EXAMPLE_OBJECT_UNIVERSAL_IDENTIFIER,
+  universalIdentifier: '${universalIdentifier}',
+  type: FieldType.NUMBER,
+  name: 'priority',
+  label: 'Priority',
+  description: 'Priority level for the example item (1-10)',
+});
+`;
+
+  await fs.ensureDir(join(appDirectory, fileFolder ?? ''));
+  await fs.writeFile(join(appDirectory, fileFolder ?? '', fileName), content);
+};
+
+const createExampleView = async ({
+  appDirectory,
+  fileFolder,
+  fileName,
+}: {
+  appDirectory: string;
+  fileFolder?: string;
+  fileName: string;
+}) => {
+  const universalIdentifier = v4();
+
+  const content = `import { defineView } from 'twenty-sdk';
+import { EXAMPLE_OBJECT_UNIVERSAL_IDENTIFIER } from 'src/objects/example-object';
+
+export default defineView({
+  universalIdentifier: '${universalIdentifier}',
+  name: 'example-view',
+  objectUniversalIdentifier: EXAMPLE_OBJECT_UNIVERSAL_IDENTIFIER,
+  icon: 'IconList',
+  position: 0,
+});
+`;
+
+  await fs.ensureDir(join(appDirectory, fileFolder ?? ''));
+  await fs.writeFile(join(appDirectory, fileFolder ?? '', fileName), content);
+};
+
+const createExampleNavigationMenuItem = async ({
+  appDirectory,
+  fileFolder,
+  fileName,
+}: {
+  appDirectory: string;
+  fileFolder?: string;
+  fileName: string;
+}) => {
+  const universalIdentifier = v4();
+
+  const content = `import { defineNavigationMenuItem } from 'twenty-sdk';
+
+export default defineNavigationMenuItem({
+  universalIdentifier: '${universalIdentifier}',
+  name: 'example-navigation-menu-item',
+  icon: 'IconList',
+  position: 0,
+  // Link to a view:
+  // viewUniversalIdentifier: '...',
+  // Or link to an object:
+  // targetObjectUniversalIdentifier: '...',
+  // Or link to an external URL:
+  // link: 'https://example.com',
+});
+`;
+
+  await fs.ensureDir(join(appDirectory, fileFolder ?? ''));
+  await fs.writeFile(join(appDirectory, fileFolder ?? '', fileName), content);
+};
+
+const createExampleSkill = async ({
+  appDirectory,
+  fileFolder,
+  fileName,
+}: {
+  appDirectory: string;
+  fileFolder?: string;
+  fileName: string;
+}) => {
+  const universalIdentifier = v4();
+
+  const content = `import { defineSkill } from 'twenty-sdk';
+
+export const EXAMPLE_SKILL_UNIVERSAL_IDENTIFIER =
+  '${universalIdentifier}';
+
+export default defineSkill({
+  universalIdentifier: EXAMPLE_SKILL_UNIVERSAL_IDENTIFIER,
+  name: 'example-skill',
+  label: 'Example Skill',
+  description: 'A sample skill for your application',
+  icon: 'IconBrain',
+  content: 'Add your skill instructions here. Skills provide context and capabilities to AI agents.',
+});
+`;
+
+  await fs.ensureDir(join(appDirectory, fileFolder ?? ''));
+  await fs.writeFile(join(appDirectory, fileFolder ?? '', fileName), content);
 };
 
 const createApplicationConfig = async ({
   displayName,
   description,
   appDirectory,
+  fileFolder,
+  fileName,
 }: {
   displayName: string;
   description?: string;
   appDirectory: string;
+  fileFolder?: string;
+  fileName: string;
 }) => {
-  const content = `import { defineApp } from 'twenty-sdk';
-import { DEFAULT_FUNCTION_ROLE_UNIVERSAL_IDENTIFIER } from 'src/default-function.role';
+  const content = `import { defineApplication } from 'twenty-sdk';
+import { DEFAULT_ROLE_UNIVERSAL_IDENTIFIER } from 'src/roles/default-role';
+import { POST_INSTALL_UNIVERSAL_IDENTIFIER } from 'src/logic-functions/post-install';
 
-export default defineApp({
+export default defineApplication({
   universalIdentifier: '${v4()}',
   displayName: '${displayName}',
   description: '${description ?? ''}',
-  functionRoleUniversalIdentifier: DEFAULT_FUNCTION_ROLE_UNIVERSAL_IDENTIFIER,
+  defaultRoleUniversalIdentifier: DEFAULT_ROLE_UNIVERSAL_IDENTIFIER,
+  postInstallLogicFunctionUniversalIdentifier: POST_INSTALL_UNIVERSAL_IDENTIFIER,
 });
 `;
 
-  await fs.writeFile(join(appDirectory, 'application.config.ts'), content);
+  await fs.ensureDir(join(appDirectory, fileFolder ?? ''));
+  await fs.writeFile(join(appDirectory, fileFolder ?? '', fileName), content);
 };
 
 const createPackageJson = async ({
@@ -232,31 +510,18 @@ const createPackageJson = async ({
     },
     packageManager: 'yarn@4.9.2',
     scripts: {
-      'auth:login': 'twenty auth:login',
-      'auth:logout': 'twenty auth:logout',
-      'auth:status': 'twenty auth:status',
-      'auth:switch': 'twenty auth:switch',
-      'auth:list': 'twenty auth:list',
-      'app:dev': 'twenty app:dev',
-      'app:build': 'twenty app:build',
-      'app:sync': 'twenty app:sync',
-      'entity:add': 'twenty entity:add',
-      'app:generate': 'twenty app:generate',
-      'function:logs': 'twenty function:logs',
-      'function:execute': 'twenty function:execute',
-      'app:uninstall': 'twenty app:uninstall',
-      help: 'twenty help',
+      twenty: 'twenty',
       lint: 'eslint',
       'lint:fix': 'eslint --fix',
     },
     dependencies: {
-      'twenty-sdk': '0.3.1',
+      'twenty-sdk': 'latest',
     },
     devDependencies: {
       typescript: '^5.9.3',
       '@types/node': '^24.7.2',
-      '@types/react': '^19.0.2',
-      react: '^19.0.2',
+      '@types/react': '^18.2.0',
+      react: '^18.2.0',
       eslint: '^9.32.0',
       'typescript-eslint': '^8.50.0',
     },

packages/create-twenty-app/tsconfig.json

@@ -12,7 +12,8 @@
     "types": ["jest", "node"],
     "paths": {
       "@/*": ["./src/*"]
-    }
+    },
+    "jsx": "react"
   },
   "include": [
     "src/**/*.ts",

packages/create-twenty-app/vite.config.ts

@@ -4,6 +4,7 @@ import { defineConfig } from 'vite';
 import dts from 'vite-plugin-dts';
 import tsconfigPaths from 'vite-tsconfig-paths';
 import packageJson from './package.json';
+import type { PackageJson } from 'type-fest';
 
 const moduleEntries = Object.keys((packageJson as any).exports || {})
   .filter(
@@ -70,13 +71,23 @@ export default defineConfig(() => {
       outDir: 'dist',
       lib: { entry: entries, name: 'create-twenty-app' },
       rollupOptions: {
-        external: [
-          ...Object.keys((packageJson as any).dependencies || {}),
-          'path',
-          'fs',
-          'child_process',
-          'util',
-        ],
+        external: (id: string) => {
+          if (/^node:/.test(id)) {
+            return true;
+          }
+
+          const builtins = ['path', 'fs', 'child_process', 'util'];
+
+          if (builtins.includes(id)) {
+            return true;
+          }
+
+          const deps = Object.keys(
+            (packageJson as PackageJson).dependencies || {},
+          );
+
+          return deps.some((dep) => id === dep || id.startsWith(dep + '/'));
+        },
         output: [
           {
             format: 'es',

packages/twenty-apps/community/last-email-interaction/package.json

@@ -17,7 +17,6 @@
   },
   "scripts": {
     "auth": "twenty auth login",
-    "generate": "twenty app generate",
     "dev": "twenty app dev",
     "sync": "twenty app sync",
     "uninstall": "twenty app uninstall",

packages/twenty-apps/community/mailchimp-synchronizer/package.json

@@ -17,7 +17,6 @@
   },
   "scripts": {
     "auth": "twenty auth login",
-    "generate": "twenty app generate",
     "dev": "twenty app dev",
     "sync": "twenty app sync",
     "uninstall": "twenty app uninstall",

packages/twenty-apps/community/stripe-synchronizer/package.json

@@ -17,7 +17,6 @@
   },
   "scripts": {
     "auth": "twenty auth login",
-    "generate": "twenty app generate",
     "dev": "twenty app dev",
     "sync": "twenty app sync",
     "uninstall": "twenty app uninstall",

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

@@ -11,7 +11,6 @@
   "scripts": {
     "create-entity": "twenty app add",
     "dev": "twenty app dev",
-    "generate": "twenty app generate",
     "sync": "twenty app sync",
     "uninstall": "twenty app uninstall",
     "auth": "twenty auth login"

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

@@ -13,7 +13,7 @@ const config: ApplicationConfig = {
       isSecret: false,
     },
   },
-  functionRoleUniversalIdentifier: 'b648f87b-1d26-4961-b974-0908fd991061',
+  defaultRoleUniversalIdentifier: 'b648f87b-1d26-4961-b974-0908fd991061',
 };
 
 export default config;

packages/twenty-apps/hello-world/src/objects/postCard.ts

@@ -95,7 +95,7 @@ export class PostCard {
     label: 'Notes',
     icon: 'IconComment',
     inverseSideTargetUniversalIdentifier:
-      STANDARD_OBJECT_UNIVERSAL_IDENTIFIERS.note,
+      STANDARD_OBJECT_UNIVERSAL_IDENTIFIERS.note.universalIdentifier,
     onDelete: OnDeleteAction.CASCADE,
   })
   notes: Note[];

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

@@ -14,7 +14,7 @@ export const functionRole: RoleConfig = {
   canBeAssignedToApiKeys: false,
   objectPermissions: [
     {
-      objectNameSingular: 'postCard',
+      objectUniversalIdentifier: '9f9882af-170c-4879-b013-f9628b77c050',
       canReadObjectRecords: true,
       canUpdateObjectRecords: true,
       canSoftDeleteObjectRecords: false,
@@ -23,8 +23,8 @@ export const functionRole: RoleConfig = {
   ],
   fieldPermissions: [
     {
-      objectNameSingular: 'postCard',
-      fieldName: 'content',
+      objectUniversalIdentifier: '9f9882af-170c-4879-b013-f9628b77c050',
+      fieldUniversalIdentifier: 'b2c37dc0-8ae7-470e-96cd-1476b47dfaff',
       canReadFieldValue: false,
       canUpdateFieldValue: false,
     },

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

@@ -8,8 +8,24 @@
     "yarn": ">=4.0.2"
   },
   "packageManager": "yarn@4.9.2",
+  "scripts": {
+    "auth:login": "twenty auth login",
+    "auth:logout": "twenty auth logout",
+    "auth:status": "twenty auth status",
+    "auth:switch": "twenty auth switch",
+    "auth:list": "twenty auth list",
+    "app:dev": "twenty app dev",
+    "app:sync": "twenty app sync",
+    "entity:add": "twenty entity add",
+    "function:logs": "twenty function logs",
+    "function:execute": "twenty function execute",
+    "app:uninstall": "twenty app uninstall",
+    "help": "twenty help",
+    "lint": "eslint",
+    "lint:fix": "eslint --fix"
+  },
   "dependencies": {
-    "twenty-sdk": "0.0.4"
+    "twenty-sdk": "0.3.1"
   },
   "devDependencies": {
     "@types/node": "^24.7.2"

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

@@ -1,6 +1,6 @@
-import { type ApplicationConfig } from 'twenty-sdk/application';
+import { defineApp } from 'twenty-sdk';
 
-const config: ApplicationConfig = {
+export default defineApp({
   universalIdentifier: '94f7db30-59e5-4b09-a5fe-64cd3d4a65b0',
   displayName: 'Self Hosting',
   description: 'Used to manage billing and telemetry of self-hosted instances',
@@ -16,6 +16,4 @@ const config: ApplicationConfig = {
       isSecret: false,
     },
   },
-};
-
-export default config;
+});

packages/twenty-apps/internal/self-hosting/src/app/selfHostingUser.object.ts

@@ -0,0 +1,18 @@
+import { FieldType, defineObject } from 'twenty-sdk';
+
+export default defineObject({
+  universalIdentifier: '06f3fb53-599e-4c6b-9df6-8f731973afd7',
+  nameSingular: 'selfHostingUser',
+  namePlural: 'selfHostingUsers',
+  labelSingular: 'Self Hosting User',
+  labelPlural: 'Self Hosting Users',
+  fields: [
+    {
+      type: FieldType.EMAILS,
+      name: 'email',
+      label: 'Email',
+      description: 'The email of the self hosting user',
+      universalIdentifier: 'a4b7892c-431a-4d44-973e-a5481652704f',
+    },
+  ],
+});

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

@@ -0,0 +1,132 @@
+import { defineFunction } from 'twenty-sdk';
+import { createClient } from '../../generated';
+
+// TODO: import from twenty-sdk when 0.4.0 is deployed
+type ServerlessFunctionEvent<TBody = object> = {
+  headers: Record<string, string | undefined>;
+  queryStringParameters: Record<string, string | undefined>;
+  pathParameters: Record<string, string | undefined>;
+  body: TBody | null;
+  isBase64Encoded: boolean;
+  requestContext: {
+    http: {
+      method: string;
+      path: string;
+    };
+  };
+};
+
+type TelemetryEventPayload = {
+  action: string;
+  timestamp: string;
+  version: string;
+  payload: {
+    userId: string | null;
+    workspaceId: string | null;
+    payload?: {
+      events?: Array<{
+        userId?: string;
+        userEmail?: string;
+        userFirstName?: string;
+        userLastName?: string;
+        locale?: string;
+        serverUrl?: string;
+      }>;
+    };
+  };
+};
+
+export const main = async (
+  params: ServerlessFunctionEvent<TelemetryEventPayload>,
+): Promise<{ success: boolean; message: string; error?: string }> => {
+  try {
+    const { action, payload } = params.body || {};
+
+    if (action !== 'user_signup') {
+      return {
+        success: true,
+        message: `Event type '${action}' ignored`,
+      };
+    }
+
+    const userEmail =
+      payload?.payload?.events?.[0]?.userEmail ||
+      payload?.payload?.events?.[0]?.userId;
+
+    if (!userEmail) {
+      return {
+        success: false,
+        message: 'No email found in telemetry event',
+        error: 'Missing userEmail in payload',
+      };
+    }
+
+    if (
+      userEmail.toLowerCase().includes('example') ||
+      userEmail.toLowerCase().includes('test')
+    ) {
+      return {
+        success: true,
+        message: `Email '${userEmail}' ignored (contains test/example data)`,
+      };
+    }
+
+    const client = createClient({
+      url: `${process.env.TWENTY_API_URL}/graphql`,
+      headers: {
+        'Content-Type': 'application/json',
+        Authorization: `Bearer ${process.env.TWENTY_API_KEY}`,
+      },
+    });
+
+    // Create or update selfHostingUser record
+    const result = await client.mutation({
+      createSelfHostingUser: {
+        __args: {
+          data: {
+            name:
+              payload?.payload?.events?.[0]?.userFirstName +
+              ' ' +
+              payload?.payload?.events?.[0]?.userLastName,
+            email: {
+              primaryEmail: userEmail,
+              additionalEmails: null,
+            },
+          },
+          upsert: true,
+        },
+        id: true,
+        email: {
+          primaryEmail: true,
+        },
+      },
+    });
+
+    return {
+      success: true,
+      message: `Self hosting user created/updated: ${result.createSelfHostingUser?.id}`,
+    };
+  } catch (error) {
+    return {
+      success: false,
+      message: 'Failed to process telemetry event',
+      error: error instanceof Error ? error.message : String(error),
+    };
+  }
+};
+
+export default defineFunction({
+  universalIdentifier: '10104201-622b-4a5e-9f27-8f2af19b2a3c',
+  name: 'telemetry-webhook',
+  timeoutSeconds: 5,
+  handler: main,
+  triggers: [
+    {
+      universalIdentifier: '7c8e3f5a-9b4c-4d1e-8f2a-1b3c4d5e6f7a',
+      type: 'route',
+      path: '/webhook/telemetry',
+      httpMethod: 'POST',
+      isAuthRequired: false,
+    },
+  ],
+});

packages/twenty-apps/internal/self-hosting/src/selfHostingUser.ts

@@ -1,18 +0,0 @@
-import { FieldMetadata, FieldMetadataType, ObjectMetadata } from 'twenty-sdk/application';
-
-@ObjectMetadata({
-  universalIdentifier: '06f3fb53-599e-4c6b-9df6-8f731973afd7',
-  nameSingular: 'selfHostingUser',
-  namePlural: 'selfHostingUsers',
-  labelSingular: 'Self Hosting User',
-  labelPlural: 'Self Hosting Users',
-})
-export class SelfHostingUser {
-  @FieldMetadata({
-    type: FieldMetadataType.EMAILS,
-    label: 'Email',
-    description: 'The email of the self hosting user',
-    universalIdentifier: '06f3fb53-599e-4c6b-9df6-8f731973afd7',
-  })
-  email: object;
-}

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

@@ -1,114 +0,0 @@
-import { type ServerlessFunctionConfig } from 'twenty-sdk/application';
-import { createClient } from '../generated';
-
-type TelemetryEventPayload = {
-  action: string;
-  timestamp: string;
-  version: string;
-  payload: {
-    userId: string | null;
-    workspaceId: string | null;
-    payload?: {
-      events?: Array<{
-        userId?: string;
-        userEmail?: string;
-        userFirstName?: string;
-        userLastName?: string;
-        locale?: string;
-        serverUrl?: string;
-      }>;
-    };
-  };
-};
-
-export const main = async (
-  params: TelemetryEventPayload,
-): Promise<{ success: boolean; message: string; error?: string }> => {
-  try {
-    const { action, payload } = params;
-
-    if (action !== 'user_signup') {
-      return {
-        success: true,
-        message: `Event type '${action}' ignored`,
-      };
-    }
-
-    const userEmail =
-      payload?.payload?.events?.[0]?.userEmail ||
-      payload?.payload?.events?.[0]?.userId;
-
-    if (!userEmail) {
-      return {
-        success: false,
-        message: 'No email found in telemetry event',
-        error: 'Missing userEmail in payload',
-      };
-    }
-
-    if (
-      userEmail.toLowerCase().includes('example') ||
-      userEmail.toLowerCase().includes('test')
-    ) {
-      return {
-        success: true,
-        message: `Email '${userEmail}' ignored (contains test/example data)`,
-      };
-    }
-
-    const client = createClient({
-      url: `${process.env.TWENTY_API_URL}/graphql`,
-      headers: {
-        'Content-Type': 'application/json',
-        Authorization: `Bearer ${process.env.TWENTY_API_KEY}`,
-      },
-    });
-
-    // Create or update selfHostingUser record
-    const result = await client.mutation({
-      createSelfHostingUser: {
-        __args: {
-          data: {
-            name: payload?.payload?.events?.[0]?.userFirstName + ' ' + payload?.payload?.events?.[0]?.userLastName,
-            email: {
-              primaryEmail: userEmail,
-              additionalEmails: null,
-            },
-          },
-          upsert: true,
-        },
-        id: true,
-        email: {
-          primaryEmail: true,
-        },
-      },
-    });
-
-    return {
-      success: true,
-      message: `Self hosting user created/updated: ${result.createSelfHostingUser?.id}`,
-    };
-  } catch (error) {
-    return {
-      success: false,
-      message: 'Failed to process telemetry event',
-      error: error instanceof Error ? error.message : String(error),
-    };
-  }
-};
-
-export const config: ServerlessFunctionConfig = {
-  universalIdentifier: '10104201-622b-4a5e-9f27-8f2af19b2a3c',
-  name: 'telemetry-webhook',
-  timeoutSeconds: 5,
-  triggers: [
-    {
-      universalIdentifier: '7c8e3f5a-9b4c-4d1e-8f2a-1b3c4d5e6f7a',
-      type: 'route',
-      path: '/webhook/telemetry',
-      httpMethod: 'POST',
-      isAuthRequired: false,
-    },
-  ],
-};
-

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

@@ -20,7 +20,11 @@
     "lib": ["es2020", "dom"],
     "skipLibCheck": true,
     "skipDefaultLibCheck": true,
-    "resolveJsonModule": true
+    "resolveJsonModule": true,
+    "paths": {
+      "src/*": ["./src/*"],
+      "~/*": ["./*"]
+    }
   },
   "exclude": [
     "node_modules",

packages/twenty-docker/helm/twenty/templates/_helpers.tpl

@@ -42,25 +42,50 @@
 {{- regexFind "\\|(.+)$" . | trimPrefix "|" -}}
 {{- end -}}
 
-{{/* Compose DB connection URL */}}
-{{- define "twenty.dbUrl" -}}
-{{- if .Values.server.env.PG_DATABASE_URL -}}
-{{- .Values.server.env.PG_DATABASE_URL -}}
-{{- else if .Values.db.enabled -}}
-{{- $host := printf "%s-db" (include "twenty.fullname" .) -}}
-{{- $user := .Values.db.internal.appUser | default "twenty_app_user" -}}
-{{- $pass := .Values.db.internal.appPassword | default (randAlphaNum 32) -}}
-{{- $db := .Values.db.internal.database | default "twenty" -}}
-{{- printf "postgres://%s:%s@%s.%s.svc.cluster.local/%s" $user $pass $host (include "twenty.namespace" .) $db -}}
+{{/* Check if using external secret for database password */}}
+{{- define "twenty.db.useExternalSecret" -}}
+{{- if and (not .Values.db.enabled) .Values.db.external.secretName .Values.db.external.passwordKey -}}
+true
 {{- else -}}
+false
+{{- end -}}
+{{- end -}}
+
+{{/* Database URL secret name */}}
+{{- define "twenty.dbUrl.secretName" -}}
+{{- printf "%s-db-url" (include "twenty.fullname" .) -}}
+{{- end -}}
+
+{{/* Database password secret name */}}
+{{- define "twenty.dbPassword.secretName" -}}
+{{- if eq (include "twenty.db.useExternalSecret" .) "true" -}}
+{{- .Values.db.external.secretName -}}
+{{- else -}}
+{{- include "twenty.dbUrl.secretName" . -}}
+{{- end -}}
+{{- end -}}
+
+{{/* Database password secret key */}}
+{{- define "twenty.dbPassword.secretKey" -}}
+{{- if eq (include "twenty.db.useExternalSecret" .) "true" -}}
+{{- .Values.db.external.passwordKey -}}
+{{- else if .Values.db.enabled -}}
+appPassword
+{{- else -}}
+password
+{{- end -}}
+{{- end -}}
+
+{{/* Database URL template for external secret (will be evaluated at runtime) */}}
+{{- define "twenty.dbUrl.template" -}}
+{{- if eq (include "twenty.db.useExternalSecret" .) "true" -}}
 {{- $scheme := "postgres" -}}
 {{- $host := .Values.db.external.host -}}
 {{- $port := .Values.db.external.port | default 5432 -}}
 {{- $user := .Values.db.external.user | default "postgres" -}}
-{{- $pass := .Values.db.external.password | default "postgres" -}}
 {{- $db := .Values.db.external.database | default "twenty" -}}
 {{- $qs := ternary "?sslmode=require" "" (eq .Values.db.external.ssl true) -}}
-{{- printf "%s://%s:%s@%s:%v/%s%s" $scheme $user $pass $host $port $db $qs -}}
+{{- printf "%s://%s:$(DB_PASSWORD)@%s:%v/%s%s" $scheme $user $host $port $db $qs -}}
 {{- end -}}
 {{- end -}}
 
@@ -78,9 +103,11 @@
 {{- end -}}
 {{- end -}}
 
-{{/* Compose Server URL from ingress, else service */}}
+{{/* Compose Server URL from override, ingress, or service */}}
 {{- define "twenty.serverUrl" -}}
-{{- if and .Values.server.ingress.enabled (gt (len .Values.server.ingress.hosts) 0) -}}
+{{- if .Values.server.env.SERVER_URL -}}
+{{- .Values.server.env.SERVER_URL -}}
+{{- else if and .Values.server.ingress.enabled (gt (len .Values.server.ingress.hosts) 0) -}}
 {{- $host := (index .Values.server.ingress.hosts 0).host -}}
 {{- $tls := gt (len .Values.server.ingress.tls) 0 -}}
 {{- $scheme := ternary "https" "http" $tls -}}

packages/twenty-docker/helm/twenty/templates/deployment-server.yaml

@@ -116,11 +116,21 @@ spec:
             - >-
               npx -y typeorm migration:run -d dist/database/typeorm/core/core.datasource
           env:
+            {{- if eq (include "twenty.db.useExternalSecret" .) "true" }}
+            - name: DB_PASSWORD
+              valueFrom:
+                secretKeyRef:
+                  name: {{ include "twenty.dbPassword.secretName" . }}
+                  key: {{ include "twenty.dbPassword.secretKey" . }}
+            - name: PG_DATABASE_URL
+              value: {{ include "twenty.dbUrl.template" . | quote }}
+            {{- else }}
             - name: PG_DATABASE_URL
               valueFrom:
                 secretKeyRef:
-                  name: {{ include "twenty.fullname" . }}-db-url
+                  name: {{ include "twenty.dbUrl.secretName" . }}
                   key: url
+            {{- end }}
       containers:
         - name: server
           {{- $img := include "twenty.server.image" . }}
@@ -129,11 +139,21 @@ spec:
           env:
             - name: SERVER_URL
               value: {{ include "twenty.serverUrl" . | quote }}
+            {{- if eq (include "twenty.db.useExternalSecret" .) "true" }}
+            - name: DB_PASSWORD
+              valueFrom:
+                secretKeyRef:
+                  name: {{ include "twenty.dbPassword.secretName" . }}
+                  key: {{ include "twenty.dbPassword.secretKey" . }}
+            - name: PG_DATABASE_URL
+              value: {{ include "twenty.dbUrl.template" . | quote }}
+            {{- else }}
             - name: PG_DATABASE_URL
               valueFrom:
                 secretKeyRef:
-                  name: {{ include "twenty.fullname" . }}-db-url
+                  name: {{ include "twenty.dbUrl.secretName" . }}
                   key: url
+            {{- end }}
             - name: REDIS_URL
               value: {{ include "twenty.redisUrl" . | quote }}
             - name: SIGN_IN_PREFILLED

packages/twenty-docker/helm/twenty/templates/deployment-worker.yaml

@@ -52,11 +52,21 @@ spec:
           env:
             - name: SERVER_URL
               value: {{ include "twenty.serverUrl" . | quote }}
+            {{- if eq (include "twenty.db.useExternalSecret" .) "true" }}
+            - name: DB_PASSWORD
+              valueFrom:
+                secretKeyRef:
+                  name: {{ include "twenty.dbPassword.secretName" . }}
+                  key: {{ include "twenty.dbPassword.secretKey" . }}
+            - name: PG_DATABASE_URL
+              value: {{ include "twenty.dbUrl.template" . | quote }}
+            {{- else }}
             - name: PG_DATABASE_URL
               valueFrom:
                 secretKeyRef:
-                  name: {{ include "twenty.fullname" . }}-db-url
+                  name: {{ include "twenty.dbUrl.secretName" . }}
                   key: url
+            {{- end }}
             - name: REDIS_URL
               value: {{ include "twenty.redisUrl" . | quote }}
             - name: STORAGE_TYPE

packages/twenty-docker/helm/twenty/templates/secret-db-url.yaml

@@ -1,4 +1,5 @@
 {{- $secretName := printf "%s-db-url" (include "twenty.fullname" .) -}}
+{{- if .Values.db.enabled -}}
 {{- $existingSecret := lookup "v1" "Secret" (include "twenty.namespace" .) $secretName -}}
 {{- $appPassword := "" -}}
 {{- if $existingSecret -}}
@@ -20,3 +21,25 @@ type: Opaque
 stringData:
   url: {{ printf "postgres://%s:%s@%s-db.%s.svc.cluster.local/%s" (urlquery $appUser) (urlquery $appPassword) (include "twenty.fullname" .) (include "twenty.namespace" .) (.Values.db.internal.database | default "twenty") | quote }}
   appPassword: {{ $appPassword | quote }}
+{{- else if not .Values.db.external.secretName -}}
+{{- $scheme := "postgres" -}}
+{{- $host := .Values.db.external.host -}}
+{{- $port := .Values.db.external.port | default 5432 -}}
+{{- $user := .Values.db.external.user | default "postgres" -}}
+{{- $pass := .Values.db.external.password | default "" -}}
+{{- $db := .Values.db.external.database | default "twenty" -}}
+{{- $qs := ternary "?sslmode=require" "" (eq .Values.db.external.ssl true) -}}
+apiVersion: v1
+kind: Secret
+metadata:
+  name: {{ $secretName }}
+  namespace: {{ include "twenty.namespace" . }}
+  labels:
+    app.kubernetes.io/name: {{ include "twenty.name" . }}
+    app.kubernetes.io/instance: {{ .Release.Name }}
+    app.kubernetes.io/component: server
+type: Opaque
+stringData:
+  url: {{ printf "%s://%s:%s@%s:%v/%s%s" $scheme (urlquery $user) (urlquery $pass) $host $port $db $qs | quote }}
+  password: {{ $pass | quote }}
+{{- end -}}

packages/twenty-docker/helm/twenty/values.schema.json

@@ -45,6 +45,7 @@
         "env": {
           "type": "object",
           "properties": {
+            "SERVER_URL": { "type": "string", "description": "Override for the server URL (e.g., https://crm.example.com). If not set, derived from ingress or service." },
             "NODE_PORT": { "type": "integer", "minimum": 1 },
             "PG_DATABASE_URL": { "type": "string" },
             "REDIS_URL": { "type": "string" },

packages/twenty-docker/helm/twenty/values.yaml

@@ -19,8 +19,13 @@ storage:
     bucket: ""
     region: ""
     endpoint: ""
+    # Option A: direct values
     accessKeyId: ""
     secretAccessKey: ""
+    # Option B: reference a Secret
+    # secretName: my-s3-creds
+    # accessKeyIdKey: accessKeyId
+    # secretAccessKeyKey: secretAccessKey
 
 # Auth tokens (random if not provided)
 secrets:
@@ -137,6 +142,8 @@ db:
     password: ""
     database: twenty
     ssl: false
+    secretName: ""
+    passwordKey: ""
 
 # Redis
 redisInternal:

packages/twenty-docker/twenty/Dockerfile

@@ -14,6 +14,7 @@ COPY ./packages/twenty-server/patches /app/packages/twenty-server/patches
 COPY ./packages/twenty-ui/package.json /app/packages/twenty-ui/
 COPY ./packages/twenty-shared/package.json /app/packages/twenty-shared/
 COPY ./packages/twenty-front/package.json /app/packages/twenty-front/
+COPY ./packages/twenty-sdk/package.json /app/packages/twenty-sdk/
 
 # Install all dependencies
 RUN yarn && yarn cache clean && npx nx reset
@@ -39,6 +40,7 @@ ARG REACT_APP_SERVER_BASE_URL
 COPY ./packages/twenty-front /app/packages/twenty-front
 COPY ./packages/twenty-ui /app/packages/twenty-ui
 COPY ./packages/twenty-shared /app/packages/twenty-shared
+COPY ./packages/twenty-sdk /app/packages/twenty-sdk
 RUN npx nx build twenty-front
 
 

packages/twenty-docker/twenty/entrypoint.sh

@@ -17,7 +17,10 @@ setup_and_migrate_db() {
         yarn database:migrate:prod
     fi
 
+    yarn command:prod cache:flush
     yarn command:prod upgrade
+    yarn command:prod cache:flush
+
     echo "Successfully migrated DB!"
 }
 

packages/twenty-docs/developers/contribute/capabilities/local-setup.mdx

@@ -159,6 +159,12 @@ You should run all commands in the following steps from the root of the project.
       CREATE ROLE postgres WITH SUPERUSER LOGIN;
     ```
     This creates a superuser role named `postgres` with login access.
+      ```bash
+      Role name | Attributes  | Member of
+      -----------+-------------+-----------
+      postgres  | Superuser   | {}
+      john      | Superuser   | {}
+    ```
 
     **Option 2:** If you have docker installed:
     ```bash

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

@@ -9,16 +9,14 @@ Apps are currently in alpha testing. The feature is functional but still evolvin
 
 ## What Are Apps?
 
-Apps let you build and manage Twenty customizations **as code**. Instead of configuring everything through the UI, you define your data model and serverless functions in code — making it faster to build, maintain, and roll out to multiple workspaces.
+Apps let you build and manage Twenty customizations **as code**. Instead of configuring everything through the UI, you define your data model and logic functions in code — making it faster to build, maintain, and roll out to multiple workspaces.
 
 **What you can do today:**
 - Define custom objects and fields as code (managed data model)
-- Build serverless functions with custom triggers
+- Build logic functions with custom triggers
+- Define skills for AI agents
 - Deploy the same app across multiple workspaces
 
-**Coming soon:**
-- Custom UI layouts and components
-
 ## Prerequisites
 
 - Node.js 24+ and Yarn 4
@@ -29,7 +27,7 @@ Apps let you build and manage Twenty customizations **as code**. Instead of conf
 Create a new app using the official scaffolder, then authenticate and start developing:
 
 ```bash filename="Terminal"
-# Scaffold a new app
+# Scaffold a new app (includes all examples by default)
 npx create-twenty-app@latest my-twenty-app
 cd my-twenty-app
 
@@ -38,35 +36,45 @@ corepack enable
 yarn install
 
 # Authenticate using your API key (you'll be prompted)
-yarn auth:login
+yarn twenty auth:login
 
 # Start dev mode: automatically syncs local changes to your workspace
-yarn app:dev
+yarn twenty app:dev
+```
+
+The scaffolder supports three modes for controlling which example files are included:
+
+```bash filename="Terminal"
+# Default (exhaustive): all examples (object, field, logic function, front component, view, navigation menu item, skill)
+npx create-twenty-app@latest my-app
+
+# Minimal: only core files (application-config.ts and default-role.ts)
+npx create-twenty-app@latest my-app --minimal
+
+# Interactive: select which examples to include
+npx create-twenty-app@latest my-app --interactive
 ```
 
 From here you can:
 
 ```bash filename="Terminal"
 # Add a new entity to your application (guided)
-yarn app:create-entity
+yarn twenty entity:add
 
-# Generate a typed Twenty client and workspace entity types
-yarn app:generate
-
-# Run a one‑time sync (instead of watch mode)
-yarn app:sync
-
-# Watch your application's functions logs
-yarn function:logs
+# Watch your application's function logs
+yarn twenty function:logs
 
 # Execute a function by name
-yarn function:execute -n my-function -p '{"name": "test"}'
+yarn twenty function:execute -n my-function -p '{"name": "test"}'
+
+# Execute the post-install function
+yarn twenty function:execute --postInstall
 
 # Uninstall the application from the current workspace
-yarn app:uninstall
+yarn twenty app:uninstall
 
 # Display commands' help
-yarn app:help
+yarn twenty help
 ```
 
 See also: the CLI reference pages for [create-twenty-app](https://www.npmjs.com/package/create-twenty-app) and [twenty-sdk CLI](https://www.npmjs.com/package/twenty-sdk).
@@ -78,9 +86,9 @@ When you run `npx create-twenty-app@latest my-twenty-app`, the scaffolder:
 - Copies a minimal base application into `my-twenty-app/`
 - Adds a local `twenty-sdk` dependency and Yarn 4 configuration
 - Creates config files and scripts wired to the `twenty` CLI
-- Generates a default application config and a default function role
+- Generates core files (application config, default function role, post-install function) plus example files based on the scaffolding mode
 
-A freshly scaffolded app looks like this:
+A freshly scaffolded app with the default `--exhaustive` mode looks like this:
 
 ```text filename="my-twenty-app/"
 my-twenty-app/
@@ -94,83 +102,80 @@ my-twenty-app/
   eslint.config.mjs
   tsconfig.json
   README.md
+  public/                           # Public assets folder (images, fonts, etc.)
   src/
-    app/
-      application.config.ts     # Required - main application configuration
-      default-function.role.ts  # Default role for serverless functions
-      // your entities (*.object.ts, *.function.ts, *.role.ts)
-    utils/                      # Optional - handler implementations & utilities
+  ├── application-config.ts           # Required - main application configuration
+  ├── roles/
+  │   └── default-role.ts               # Default role for logic functions
+  ├── objects/
+  │   └── example-object.ts             # Example custom object definition
+  ├── fields/
+  │   └── example-field.ts              # Example standalone field definition
+  ├── logic-functions/
+  │   ├── hello-world.ts                # Example logic function
+  │   └── post-install.ts               # Post-install logic function
+  ├── front-components/
+  │   └── hello-world.tsx               # Example front component
+  ├── views/
+  │   └── example-view.ts                # Example saved view definition
+  ├── navigation-menu-items/
+  │   └── example-navigation-menu-item.ts # Example sidebar navigation link
+  └── skills/
+      └── example-skill.ts                # Example AI agent skill definition
 ```
 
-### Convention-over-configuration
-
-Applications use a **convention-over-configuration** approach where entities are detected by their file suffix. This allows flexible organization within the `src/app/` folder:
-
-| File suffix | Entity type |
-|-------------|-------------|
-| `*.object.ts` | Custom object definitions |
-| `*.function.ts` | Serverless function definitions |
-| `*.role.ts` | Role definitions |
-
-### Supported folder organizations
-
-You can organize your entities in any of these patterns:
-
-**Traditional (by type):**
-```text
-src/app/
-├── application.config.ts
-├── objects/
-│   └── postCard.object.ts
-├── functions/
-│   └── createPostCard.function.ts
-└── roles/
-    └── admin.role.ts
-```
-
-**Feature-based:**
-```text
-src/app/
-├── application.config.ts
-└── post-card/
-    ├── postCard.object.ts
-    ├── createPostCard.function.ts
-    └── postCardAdmin.role.ts
-```
-
-**Flat:**
-```text
-src/app/
-├── application.config.ts
-├── postCard.object.ts
-├── createPostCard.function.ts
-└── admin.role.ts
-```
+With `--minimal`, only the core files are created (`application-config.ts`, `roles/default-role.ts`, and `logic-functions/post-install.ts`). With `--interactive`, you choose which example files to include.
 
 At a high level:
 
-- **package.json**: Declares the app name, version, engines (Node 24+, Yarn 4), and adds `twenty-sdk` plus scripts like `dev`, `sync`, `generate`, `create-entity`, `logs`, `uninstall`, and `auth` that delegate to the local `twenty` CLI.
+- **package.json**: Declares the app name, version, engines (Node 24+, Yarn 4), and adds `twenty-sdk` plus a `twenty` script that delegates to the local `twenty` CLI. Run `yarn twenty help` to list all available commands.
 - **.gitignore**: Ignores common artifacts such as `node_modules`, `.yarn`, `generated/` (typed client), `dist/`, `build/`, coverage folders, log files, and `.env*` files.
 - **yarn.lock**, **.yarnrc.yml**, **.yarn/**: Lock and configure the Yarn 4 toolchain used by the project.
 - **.nvmrc**: Pins the Node.js version expected by the project.
 - **eslint.config.mjs** and **tsconfig.json**: Provide linting and TypeScript configuration for your app's TypeScript sources.
 - **README.md**: A short README in the app root with basic instructions.
-- **src/app/**: The main place where you define your application-as-code:
-  - `application.config.ts`: Global configuration for your app (metadata and runtime wiring). See "Application config" below.
-  - `*.role.ts`: Role definitions used by your serverless functions. See "Default function role" below.
-  - `*.object.ts`: Custom object definitions.
-  - `*.function.ts`: Serverless function definitions.
-- **src/utils/**: Optional folder for handler implementations and utilities.
+- **public/**: A folder for storing public assets (images, fonts, static files) that will be served with your application. Files placed here are uploaded during sync and accessible at runtime.
+- **src/**: The main place where you define your application-as-code
+
+### Entity detection
+
+The SDK detects entities by parsing your TypeScript files for **`export default define<Entity>({...})`** calls. Each entity type has a corresponding helper function exported from `twenty-sdk`:
+
+| Helper function | Entity type |
+|-----------------|-------------|
+| `defineObject()` | Custom object definitions |
+| `defineLogicFunction()` | Logic function definitions |
+| `defineFrontComponent()` | Front component definitions |
+| `defineRole()` | Role definitions |
+| `defineField()` | Field extensions for existing objects |
+| `defineView()` | Saved view definitions |
+| `defineNavigationMenuItem()` | Navigation menu item definitions |
+| `defineSkill()` | AI agent skill definitions |
+
+<Note>
+**File naming is flexible.** Entity detection is AST-based — the SDK scans your source files for the `export default define<Entity>({...})` pattern. You can organize your files and folders however you like. Grouping by entity type (e.g., `logic-functions/`, `roles/`) is just a convention for code organization, not a requirement.
+</Note>
+
+Example of a detected entity:
+```typescript
+// This file can be named anything and placed anywhere in src/
+import { defineObject, FieldType } from 'twenty-sdk';
+
+export default defineObject({
+  universalIdentifier: '...',
+  nameSingular: 'postCard',
+  // ... rest of config
+});
+```
 
 Later commands will add more files and folders:
 
-- `yarn app:generate` will create a `generated/` folder (typed Twenty client + workspace types).
-- `yarn app:create-entity` will add entity definition files under `src/app/` for your custom objects, functions, or roles.
-l
+- `yarn twenty app:dev` will auto-generate a typed API client in `node_modules/twenty-sdk/generated` (typed Twenty client + workspace types).
+- `yarn twenty entity:add` will add entity definition files under `src/` for your custom objects, functions, front components, roles, skills, and more.
 
 ## Authentication
 
-The first time you run `yarn auth:login`, you'll be prompted for:
+The first time you run `yarn twenty auth:login`, you'll be prompted for:
 
 - API URL (defaults to http://localhost:3000 or your current workspace profile)
 - API key
@@ -181,25 +186,25 @@ Your credentials are stored per-user in `~/.twenty/config.json`. You can maintai
 
 ```bash filename="Terminal"
 # Login interactively (recommended)
-yarn auth:login
+yarn twenty auth:login
 
 # Login to a specific workspace profile
-yarn auth:login --workspace my-custom-workspace
+yarn twenty auth:login --workspace my-custom-workspace
 
 # List all configured workspaces
-yarn auth:list
+yarn twenty auth:list
 
 # Switch the default workspace (interactive)
-yarn auth:switch
+yarn twenty auth:switch
 
 # Switch to a specific workspace
-yarn auth:switch production
+yarn twenty auth:switch production
 
 # Check current authentication status
-yarn auth:status
+yarn twenty auth:status
 ```
 
-Once you've switched workspaces with `auth:switch`, all subsequent commands will use that workspace by default. You can still override it temporarily with `--workspace <name>`.
+Once you've switched workspaces with `yarn twenty auth:switch`, all subsequent commands will use that workspace by default. You can still override it temporarily with `--workspace <name>`.
 
 ## Use the SDK resources (types & config)
 
@@ -207,16 +212,21 @@ The twenty-sdk provides typed building blocks and helper functions you use insid
 
 ### Helper functions
 
-The SDK provides four helper functions with built-in validation for defining your app entities:
+The SDK provides helper functions for defining your app entities. As described in [Entity detection](#entity-detection), you must use `export default define<Entity>({...})` for your entities to be detected:
 
 | Function | Purpose |
 |----------|---------|
-| `defineApp()` | Configure application metadata |
+| `defineApplication()` | Configure application metadata (required, one per app) |
 | `defineObject()` | Define custom objects with fields |
-| `defineFunction()` | Define serverless functions with handlers |
+| `defineLogicFunction()` | Define logic functions with handlers |
+| `defineFrontComponent()` | Define front components for custom UI |
 | `defineRole()` | Configure role permissions and object access |
+| `defineField()` | Extend existing objects with additional fields |
+| `defineView()` | Define saved views for objects |
+| `defineNavigationMenuItem()` | Define sidebar navigation links |
+| `defineSkill()` | Define AI agent skills |
 
-These functions validate your configuration at runtime and provide better IDE autocompletion and type safety.
+These functions validate your configuration at build time and provide IDE autocompletion and type safety.
 
 ### Defining objects
 
@@ -297,80 +307,35 @@ Key points:
 - The `universalIdentifier` must be unique and stable across deployments.
 - Each field requires a `name`, `type`, `label`, and its own stable `universalIdentifier`.
 - The `fields` array is optional — you can define objects without custom fields.
-- You can scaffold new objects using `yarn app:create-entity`, which guides you through naming, fields, and relationships.
+- You can scaffold new objects using `yarn twenty entity:add`, which guides you through naming, fields, and relationships.
 
 <Note>
-**Base fields are created automatically.** When you define a custom object, Twenty automatically adds standard fields such as `name`, `createdAt`, `updatedAt`, `createdBy`, `position`, and `deletedAt`. You don't need to define these in your `fields` array — only add your custom fields.
+**Base fields are created automatically.** When you define a custom object, Twenty automatically adds standard fields
+  such as `id`, `name`, `createdAt`, `updatedAt`, `createdBy`, `updatedBy` and `deletedAt`.
+  You don't need to define these in your `fields` array — only add your custom fields.
+  You can override default fields by defining a field with the same name in your `fields` array,
+  but this is not recommended.
 </Note>
 
-<Accordion title="Alternative: Decorator-based syntax">
-You can also define objects using TypeScript decorators. This approach uses class-based syntax with `@Object`, `@Field`, and `@Relation` decorators:
 
-```typescript
-import {
-  type AddressField,
-  Field,
-  FieldType,
-  type FullNameField,
-  Object,
-  OnDeleteAction,
-  Relation,
-  RelationType,
-  STANDARD_OBJECT_UNIVERSAL_IDENTIFIERS,
-} from 'twenty-sdk';
-import { type Note } from '../../generated';
+### Application config (application-config.ts)
 
-@Object({
-  universalIdentifier: '54b589ca-eeed-4950-a176-358418b85c05',
-  nameSingular: 'postCard',
-  namePlural: 'postCards',
-  labelSingular: 'Post card',
-  labelPlural: 'Post cards',
-  description: 'A post card object',
-  icon: 'IconMail',
-})
-export class PostCard {
-  @Field({
-    universalIdentifier: '58a0a314-d7ea-4865-9850-7fb84e72f30b',
-    type: FieldType.TEXT,
-    label: 'Content',
-    description: "Postcard's content",
-    icon: 'IconAbc',
-  })
-  content: string;
-
-  @Relation({
-    universalIdentifier: 'c9e2b4f4-b9ad-4427-9b42-9971b785edfe',
-    type: RelationType.ONE_TO_MANY,
-    label: 'Notes',
-    icon: 'IconComment',
-    inverseSideTargetUniversalIdentifier: STANDARD_OBJECT_UNIVERSAL_IDENTIFIERS.note,
-    onDelete: OnDeleteAction.CASCADE,
-  })
-  notes: Note[];
-}
-```
-
-Note: The decorator approach requires `experimentalDecorators` in your TypeScript config.
-</Accordion>
-
-
-### Application config (application.config.ts)
-
-Every app has a single `application.config.ts` file that describes:
+Every app has a single `application-config.ts` file that describes:
 
 - **Who the app is**: identifiers, display name, and description.
 - **How its functions run**: which role they use for permissions.
 - **(Optional) variables**: key–value pairs exposed to your functions as environment variables.
+- **(Optional) post-install function**: a logic function that runs after the app is installed.
 
-Use `defineApp()` to define your application configuration:
+Use `defineApplication()` to define your application configuration:
 
 ```typescript
-// src/app/application.config.ts
-import { defineApp } from 'twenty-sdk';
-import { DEFAULT_FUNCTION_ROLE_UNIVERSAL_IDENTIFIER } from './default-function.role';
+// src/application-config.ts
+import { defineApplication } from 'twenty-sdk';
+import { DEFAULT_ROLE_UNIVERSAL_IDENTIFIER } from 'src/roles/default-role';
+import { POST_INSTALL_UNIVERSAL_IDENTIFIER } from 'src/logic-functions/post-install';
 
-export default defineApp({
+export default defineApplication({
   universalIdentifier: '4ec0391d-18d5-411c-b2f3-266ddc1c3ef7',
   displayName: 'My Twenty App',
   description: 'My first Twenty app',
@@ -383,18 +348,20 @@ export default defineApp({
       isSecret: false,
     },
   },
-  functionRoleUniversalIdentifier: DEFAULT_FUNCTION_ROLE_UNIVERSAL_IDENTIFIER,
+  defaultRoleUniversalIdentifier: DEFAULT_ROLE_UNIVERSAL_IDENTIFIER,
+  postInstallLogicFunctionUniversalIdentifier: POST_INSTALL_UNIVERSAL_IDENTIFIER,
 });
 ```
 
 Notes:
 - `universalIdentifier` fields are deterministic IDs you own; generate them once and keep them stable across syncs.
 - `applicationVariables` become environment variables for your functions (for example, `DEFAULT_RECIPIENT_NAME` is available as `process.env.DEFAULT_RECIPIENT_NAME`).
-- `functionRoleUniversalIdentifier` must match the role you define in your `*.role.ts` file (see below).
+- `defaultRoleUniversalIdentifier` must match the role file (see below).
+- `postInstallLogicFunctionUniversalIdentifier` (optional) points to a logic function that runs automatically after the app is installed. See [Post-install functions](#post-install-functions).
 
 #### Roles and permissions
 
-Applications can define roles that encapsulate permissions on your workspace's objects and actions. The field `functionRoleUniversalIdentifier` in `application.config.ts` designates the default role used by your app's serverless functions.
+Applications can define roles that encapsulate permissions on your workspace's objects and actions. The field `defaultRoleUniversalIdentifier` in `application-config.ts` designates the default role used by your app's logic functions.
 
 - The runtime API key injected as `TWENTY_API_KEY` is derived from this default function role.
 - The typed client will be restricted to the permissions granted to that role.
@@ -405,14 +372,14 @@ Applications can define roles that encapsulate permissions on your workspace's o
 When you scaffold a new app, the CLI also creates a default role file. Use `defineRole()` to define roles with built-in validation:
 
 ```typescript
-// src/app/default-function.role.ts
+// src/roles/default-role.ts
 import { defineRole, PermissionFlag } from 'twenty-sdk';
 
-export const DEFAULT_FUNCTION_ROLE_UNIVERSAL_IDENTIFIER =
+export const DEFAULT_ROLE_UNIVERSAL_IDENTIFIER =
   'b648f87b-1d26-4961-b974-0908fd991061';
 
 export default defineRole({
-  universalIdentifier: DEFAULT_FUNCTION_ROLE_UNIVERSAL_IDENTIFIER,
+  universalIdentifier: DEFAULT_ROLE_UNIVERSAL_IDENTIFIER,
   label: 'Default function role',
   description: 'Default role for function Twenty client',
   canReadAllObjectRecords: false,
@@ -425,7 +392,7 @@ export default defineRole({
   canBeAssignedToApiKeys: false,
   objectPermissions: [
     {
-      objectNameSingular: 'postCard',
+      objectUniversalIdentifier: '9f9882af-170c-4879-b013-f9628b77c050',
       canReadObjectRecords: true,
       canUpdateObjectRecords: true,
       canSoftDeleteObjectRecords: false,
@@ -434,8 +401,8 @@ export default defineRole({
   ],
   fieldPermissions: [
     {
-      objectNameSingular: 'postCard',
-      fieldName: 'content',
+      objectUniversalIdentifier: '9f9882af-170c-4879-b013-f9628b77c050',
+      fieldUniversalIdentifier: 'b2c37dc0-8ae7-470e-96cd-1476b47dfaff',
       canReadFieldValue: false,
       canUpdateFieldValue: false,
     },
@@ -444,10 +411,10 @@ export default defineRole({
 });
 ```
 
-The `universalIdentifier` of this role is then referenced in `application.config.ts` as `functionRoleUniversalIdentifier`. In other words:
+The `universalIdentifier` of this role is then referenced in `application-config.ts` as `defaultRoleUniversalIdentifier`. In other words:
 
 - **\*.role.ts** defines what the default function role can do.
-- **application.config.ts** points to that role so your functions inherit its permissions.
+- **application-config.ts** points to that role so your functions inherit its permissions.
 
 Notes:
 - Start from the scaffolded role, then progressively restrict it following least‑privilege.
@@ -455,22 +422,17 @@ Notes:
 - `permissionFlags` control access to platform-level capabilities. Keep them minimal; add only what you need.
 - See a working example in the Hello World app: [`packages/twenty-apps/hello-world/src/roles/function-role.ts`](https://github.com/twentyhq/twenty/blob/main/packages/twenty-apps/hello-world/src/roles/function-role.ts).
 
-### Serverless function config and entrypoint
+### Logic function config and entrypoint
 
-Each function file uses `defineFunction()` to export a configuration with a handler and optional triggers. Use the `*.function.ts` file suffix for automatic detection.
+Each function file uses `defineLogicFunction()` to export a configuration with a handler and optional triggers.
 
 ```typescript
-// src/app/createPostCard.function.ts
-import { defineFunction } from 'twenty-sdk';
+// src/app/createPostCard.logic-function.ts
+import { defineLogicFunction } from 'twenty-sdk';
 import type { DatabaseEventPayload, ObjectRecordCreateEvent, CronPayload, RoutePayload } from 'twenty-sdk';
-import Twenty, { type Person } from '../../generated';
+import Twenty, { type Person } from '~/generated';
 
-const handler = async (
-  params:
-    | RoutePayload
-    | DatabaseEventPayload<ObjectRecordCreateEvent<Person>>
-    | CronPayload,
-) => {
+const handler = async (params: RoutePayload) => {
   const client = new Twenty(); // generated typed client
   const name = 'name' in params.queryStringParameters
     ? params.queryStringParameters.name ?? process.env.DEFAULT_RECIPIENT_NAME ?? 'Hello world'
@@ -486,7 +448,7 @@ const handler = async (
   return result;
 };
 
-export default defineFunction({
+export default defineLogicFunction({
   universalIdentifier: 'e56d363b-0bdc-4d8a-a393-6f0d1c75bdcf',
   name: 'create-new-post-card',
   timeoutSeconds: 2,
@@ -501,18 +463,18 @@ export default defineFunction({
       isAuthRequired: false,
     },
     // Cron trigger (CRON pattern)
-    {
-      universalIdentifier: 'dd802808-0695-49e1-98c9-d5c9e2704ce2',
-      type: 'cron',
-      pattern: '0 0 1 1 *',
-    },
+    // {
+    //   universalIdentifier: 'dd802808-0695-49e1-98c9-d5c9e2704ce2',
+    //   type: 'cron',
+    //   pattern: '0 0 1 1 *',
+    // },
     // Database event trigger
-    {
-      universalIdentifier: '203f1df3-4a82-4d06-a001-b8cf22a31156',
-      type: 'databaseEvent',
-      eventName: 'person.updated',
-      updatedFields: ['name'],
-    },
+    // {
+    //   universalIdentifier: '203f1df3-4a82-4d06-a001-b8cf22a31156',
+    //   type: 'databaseEvent',
+    //   eventName: 'person.updated',
+    //   updatedFields: ['name'],
+    // },
   ],
 });
 ```
@@ -528,6 +490,54 @@ Notes:
 - The `triggers` array is optional. Functions without triggers can be used as utility functions called by other functions.
 - You can mix multiple trigger types in a single function.
 
+### Post-install functions
+
+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.
+
+When you scaffold a new app with `create-twenty-app`, a post-install function is generated for you at `src/logic-functions/post-install.ts`:
+
+```typescript
+// src/logic-functions/post-install.ts
+import { defineLogicFunction } from 'twenty-sdk';
+
+export const POST_INSTALL_UNIVERSAL_IDENTIFIER = '<generated-uuid>';
+
+const handler = async (): Promise<void> => {
+  console.log('Post install logic function executed successfully!');
+};
+
+export default defineLogicFunction({
+  universalIdentifier: POST_INSTALL_UNIVERSAL_IDENTIFIER,
+  name: 'post-install',
+  description: 'Runs after installation to set up the application.',
+  timeoutSeconds: 300,
+  handler,
+});
+```
+
+The function is wired into your app by referencing its universal identifier in `application-config.ts`:
+
+```typescript
+import { POST_INSTALL_UNIVERSAL_IDENTIFIER } from 'src/logic-functions/post-install';
+
+export default defineApplication({
+  // ...
+  postInstallLogicFunctionUniversalIdentifier: POST_INSTALL_UNIVERSAL_IDENTIFIER,
+});
+```
+
+You can also manually execute the post-install function at any time using the CLI:
+
+```bash filename="Terminal"
+yarn twenty function:execute --postInstall
+```
+
+Key points:
+- Post-install functions are standard logic functions — they use `defineLogicFunction()` like any other function.
+- The `postInstallLogicFunctionUniversalIdentifier` field in `defineApplication()` is optional. If omitted, no function runs after installation.
+- The default timeout is set to 300 seconds (5 minutes) to allow for longer setup tasks like data seeding.
+- Post-install functions do not need triggers — they are invoked by the platform during installation or manually via `function:execute --postInstall`.
+
 ### Route trigger payload
 
 <Warning>
@@ -552,10 +562,10 @@ const handler = async (event: RoutePayload) => {
 **To migrate existing functions:** Update your handler to destructure from `event.body`, `event.queryStringParameters`, or `event.pathParameters` instead of directly from the params object.
 </Warning>
 
-When a route trigger invokes your function, it receives a `RoutePayload` object that follows the AWS HTTP API v2 format. Import the type from `twenty-sdk`:
+When a route trigger invokes your logic function, it receives a `RoutePayload` object that follows the AWS HTTP API v2 format. Import the type from `twenty-sdk`:
 
 ```typescript
-import { defineFunction, type RoutePayload } from 'twenty-sdk';
+import { defineLogicFunction, type RoutePayload } from 'twenty-sdk';
 
 const handler = async (event: RoutePayload) => {
   // Access request data
@@ -582,10 +592,10 @@ The `RoutePayload` type has the following structure:
 
 ### Forwarding HTTP headers
 
-By default, HTTP headers from incoming requests are **not** passed to your serverless function for security reasons. To access specific headers, explicitly list them in the `forwardedRequestHeaders` array:
+By default, HTTP headers from incoming requests are **not** passed to your logic function for security reasons. To access specific headers, explicitly list them in the `forwardedRequestHeaders` array:
 
 ```typescript
-export default defineFunction({
+export default defineLogicFunction({
   universalIdentifier: 'e56d363b-0bdc-4d8a-a393-6f0d1c75bdcf',
   name: 'webhook-handler',
   handler,
@@ -620,23 +630,158 @@ const handler = async (event: RoutePayload) => {
 
 You can create new functions in two ways:
 
-- **Scaffolded**: Run `yarn app:create-entity` and choose the option to add a new function. This generates a starter file with a handler and config.
-- **Manual**: Create a new `*.function.ts` file and use `defineFunction()`, following the same pattern.
+- **Scaffolded**: Run `yarn twenty entity:add` and choose the option to add a new logic function. This generates a starter file with a handler and config.
+- **Manual**: Create a new `*.logic-function.ts` file and use `defineLogicFunction()`, following the same pattern.
+
+### Marking a logic function as a tool
+
+Logic functions can be exposed as **tools** for AI agents and workflows. When a function is marked as a tool, it becomes discoverable by Twenty's AI features and can be selected as a step in workflow automations.
+
+To mark a logic function as a tool, set `isTool: true` and provide a `toolInputSchema` describing the expected input parameters using [JSON Schema](https://json-schema.org/):
+
+```typescript
+// src/logic-functions/enrich-company.logic-function.ts
+import { defineLogicFunction } from 'twenty-sdk';
+import Twenty from '~/generated';
+
+const handler = async (params: { companyName: string; domain?: string }) => {
+  const client = new Twenty();
+
+  const result = await client.mutation({
+    createTask: {
+      __args: {
+        data: {
+          title: `Enrich data for ${params.companyName}`,
+          body: `Domain: ${params.domain ?? 'unknown'}`,
+        },
+      },
+      id: true,
+    },
+  });
+
+  return { taskId: result.createTask.id };
+};
+
+export default defineLogicFunction({
+  universalIdentifier: 'f47ac10b-58cc-4372-a567-0e02b2c3d479',
+  name: 'enrich-company',
+  description: 'Enrich a company record with external data',
+  timeoutSeconds: 10,
+  handler,
+  isTool: true,
+  toolInputSchema: {
+    type: 'object',
+    properties: {
+      companyName: {
+        type: 'string',
+        description: 'The name of the company to enrich',
+      },
+      domain: {
+        type: 'string',
+        description: 'The company website domain (optional)',
+      },
+    },
+    required: ['companyName'],
+  },
+});
+```
+
+Key points:
+
+- **`isTool`** (`boolean`, default: `false`): When set to `true`, the function is registered as a tool and becomes available to AI agents and workflow automations.
+- **`toolInputSchema`** (`object`, optional): A JSON Schema object that describes the parameters your function accepts. AI agents use this schema to understand what inputs the tool expects and to validate calls. If omitted, the schema defaults to `{ type: 'object', properties: {} }` (no parameters).
+- Functions with `isTool: false` (or unset) are **not** exposed as tools. They can still be executed directly or called by other functions, but will not appear in tool discovery.
+- **Tool naming**: When exposed as a tool, the function name is automatically normalized to `logic_function_<name>` (lowercased, non-alphanumeric characters replaced with underscores). For example, `enrich-company` becomes `logic_function_enrich_company`.
+- You can combine `isTool` with triggers — a function can be both a tool (callable by AI agents) and triggered by events (cron, database events, routes) at the same time.
+
+<Note>
+**Write a good `description`.** AI agents rely on the function's `description` field to decide when to use the tool. Be specific about what the tool does and when it should be called.
+</Note>
+
+### Front components
+
+Front components let you build custom React components that render within Twenty's UI. Use `defineFrontComponent()` to define components with built-in validation:
+
+```typescript
+// src/my-widget.front-component.tsx
+import { defineFrontComponent } from 'twenty-sdk';
+
+const MyWidget = () => {
+  return (
+    <div style={{ padding: '20px', fontFamily: 'sans-serif' }}>
+      <h1>My Custom Widget</h1>
+      <p>This is a custom front component for Twenty.</p>
+    </div>
+  );
+};
+
+export default defineFrontComponent({
+  universalIdentifier: 'a1b2c3d4-e5f6-7890-abcd-ef1234567890',
+  name: 'my-widget',
+  description: 'A custom widget component',
+  component: MyWidget,
+});
+```
+
+Key points:
+- Front components are React components that render in isolated contexts within Twenty.
+- Use the `*.front-component.tsx` file suffix for automatic detection.
+- The `component` field references your React component.
+- Components are built and synced automatically during `yarn twenty app:dev`.
+
+You can create new front components in two ways:
+
+- **Scaffolded**: Run `yarn twenty entity:add` and choose the option to add a new front component.
+- **Manual**: Create a new `*.front-component.tsx` file and use `defineFrontComponent()`.
+
+### Skills
+
+Skills define reusable instructions and capabilities that AI agents can use within your workspace. Use `defineSkill()` to define skills with built-in validation:
+
+```typescript
+// src/skills/example-skill.ts
+import { defineSkill } from 'twenty-sdk';
+
+export default defineSkill({
+  universalIdentifier: 'a1b2c3d4-e5f6-7890-abcd-ef1234567890',
+  name: 'sales-outreach',
+  label: 'Sales Outreach',
+  description: 'Guides the AI agent through a structured sales outreach process',
+  icon: 'IconBrain',
+  content: `You are a sales outreach assistant. When reaching out to a prospect:
+1. Research the company and recent news
+2. Identify the prospect's role and likely pain points
+3. Draft a personalized message referencing specific details
+4. Keep the tone professional but conversational`,
+});
+```
+
+Key points:
+- `name` is a unique identifier string for the skill (kebab-case recommended).
+- `label` is the human-readable display name shown in the UI.
+- `content` contains the skill instructions — this is the text the AI agent uses.
+- `icon` (optional) sets the icon displayed in the UI.
+- `description` (optional) provides additional context about the skill's purpose.
+
+You can create new skills in two ways:
+
+- **Scaffolded**: Run `yarn twenty entity:add` and choose the option to add a new skill.
+- **Manual**: Create a new file and use `defineSkill()`, following the same pattern.
 
 ### Generated typed client
 
-Run yarn app:generate to create a local typed client in generated/ based on your workspace schema. Use it in your functions:
+The typed client is auto-generated by `yarn twenty app:dev` and stored in `node_modules/twenty-sdk/generated` based on your workspace schema. Use it in your functions:
 
 ```typescript
-import Twenty from './generated';
+import Twenty from '~/generated';
 
 const client = new Twenty();
 const { me } = await client.query({ me: { id: true, displayName: true } });
 ```
 
-The client is re-generated by `yarn app:generate`. Re-run after changing your objects and `yarn app:sync` or when onboarding to a new workspace.
+The client is re-generated automatically by `yarn twenty app:dev` whenever your objects or fields change.
 
-#### Runtime credentials in serverless functions
+#### Runtime credentials in logic functions
 
 When your function runs on Twenty, the platform injects credentials as environment variables before your code executes:
 
@@ -645,46 +790,84 @@ When your function runs on Twenty, the platform injects credentials as environme
 
 Notes:
 - You do not need to pass URL or API key to the generated client. It reads `TWENTY_API_URL` and `TWENTY_API_KEY` from process.env at runtime.
-- The API key's permissions are determined by the role referenced in your `application.config.ts` via `functionRoleUniversalIdentifier`. This is the default role used by serverless functions of your application.
-- Applications can define roles to follow least‑privilege. Grant only the permissions your functions need, then point `functionRoleUniversalIdentifier` to that role's universal identifier.
+- The API key's permissions are determined by the role referenced in your `application-config.ts` via `defaultRoleUniversalIdentifier`. This is the default role used by logic functions of your application.
+- Applications can define roles to follow least‑privilege. Grant only the permissions your functions need, then point `defaultRoleUniversalIdentifier` to that role's universal identifier.
 
+#### Uploading files
+
+The generated `Twenty` client includes an `uploadFile` method for attaching files to file-type fields on your workspace objects. Because standard GraphQL clients do not support multipart file uploads natively, the client provides this dedicated method that implements the [GraphQL multipart request specification](https://github.com/jaydenseric/graphql-multipart-request-spec) under the hood.
+
+```typescript
+import Twenty from '~/generated';
+import * as fs from 'fs';
+
+const client = new Twenty();
+
+const fileBuffer = fs.readFileSync('./invoice.pdf');
+
+const uploadedFile = await client.uploadFile(
+  fileBuffer,                                         // file contents as a Buffer
+  'invoice.pdf',                                      // filename
+  'application/pdf',                                  // MIME type (defaults to 'application/octet-stream')
+  '58a0a314-d7ea-4865-9850-7fb84e72f30b',            // field universal identifier
+);
+
+console.log(uploadedFile);
+// { id: '...', path: '...', size: 12345, createdAt: '...', url: 'https://...' }
+```
+
+The method signature:
+
+```typescript
+uploadFile(
+  fileBuffer: Buffer,
+  filename: string,
+  contentType: string,
+  fieldMetadataUniversalIdentifier: string,
+): Promise<{ id: string; path: string; size: number; createdAt: string; url: string }>
+```
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `fileBuffer` | `Buffer` | The raw file contents |
+| `filename` | `string` | The name of the file (used for storage and display) |
+| `contentType` | `string` | MIME type of the file (defaults to `application/octet-stream` if omitted) |
+| `fieldMetadataUniversalIdentifier` | `string` | The `universalIdentifier` of the file-type field on your object |
+
+Key points:
+- The method sends the file to the **metadata endpoint** (not the main GraphQL endpoint), where the upload mutation is resolved.
+- It uses the field's `universalIdentifier` (not its workspace-specific ID), so your upload code works across any workspace where your app is installed — consistent with how apps reference fields everywhere else.
+- The returned `url` is a signed URL you can use to access the uploaded file.
 
 ### Hello World example
 
-Explore a minimal, end-to-end example that demonstrates objects, functions, and multiple triggers [here](https://github.com/twentyhq/twenty/tree/main/packages/twenty-apps/hello-world):
+Explore a minimal, end-to-end example that demonstrates objects, logic functions, front components, and multiple triggers [here](https://github.com/twentyhq/twenty/tree/main/packages/twenty-apps/hello-world):
 
 ## Manual setup (without the scaffolder)
 
-While we recommend using `create-twenty-app` for the best getting-started experience, you can also set up a project manually. Do not install the CLI globally. Instead, add `twenty-sdk` as a local dependency and wire scripts in your package.json:
+While we recommend using `create-twenty-app` for the best getting-started experience, you can also set up a project manually. Do not install the CLI globally. Instead, add `twenty-sdk` as a local dependency and wire a single script in your package.json:
 
 ```bash filename="Terminal"
 yarn add -D twenty-sdk
 ```
 
-Then add scripts like these:
+Then add a `twenty` script:
 
 ```json filename="package.json"
 {
   "scripts": {
-    "auth": "twenty auth login",
-    "generate": "twenty app generate",
-    "dev": "twenty app dev",
-    "sync": "twenty app sync",
-    "uninstall": "twenty app uninstall",
-    "logs": "twenty app logs",
-    "create-entity": "twenty app add",
-    "help": "twenty --help"
+    "twenty": "twenty"
   }
 }
 ```
 
-Now you can run the same commands via Yarn, e.g. `yarn app:dev`, `yarn app:sync`, etc.
+Now you can run all commands via `yarn twenty <command>`, e.g. `yarn twenty app:dev`, `yarn twenty help`, etc.
 
 ## Troubleshooting
 
-- Authentication errors: run `yarn auth:login` and ensure your API key has the required permissions.
+- Authentication errors: run `yarn twenty auth:login` and ensure your API key has the required permissions.
 - Cannot connect to server: verify the API URL and that the Twenty server is reachable.
-- Types or client missing/outdated: run `yarn app:generate` and then `yarn app:dev`.
-- Dev mode not syncing: ensure `yarn app:dev` is running and that changes are not ignored by your environment.
+- Types or client missing/outdated: restart `yarn twenty app:dev` — it auto-generates the typed client.
+- Dev mode not syncing: ensure `yarn twenty app:dev` is running and that changes are not ignored by your environment.
 
 Discord Help Channel: https://discord.com/channels/1130383047699738754/1130386664812982322

packages/twenty-docs/developers/self-host/capabilities/setup.mdx

@@ -289,19 +289,19 @@ yarn command:prod cron:workflow:automated-cron-trigger
 **Environment-only mode:** If you set `IS_CONFIG_VARIABLES_IN_DB_ENABLED=false`, add these variables to your `.env` file instead.
 </Warning>
 
-## Serverless Functions
+## Logic Functions
 
-Twenty supports serverless functions for workflows and custom logic. The execution environment is configured via the `SERVERLESS_TYPE` environment variable.
+Twenty supports logic functions for workflows and custom logic. The execution environment is configured via the `SERVERLESS_TYPE` environment variable.
 
 <Warning>
-**Security Notice:** The local serverless driver (`SERVERLESS_TYPE=LOCAL`) runs code directly on the host in a Node.js process with no sandboxing. It should only be used for trusted code in development. For production deployments handling untrusted code, we highly recommend using `SERVERLESS_TYPE=LAMBDA` or `SERVERLESS_TYPE=DISABLED`.
+**Security Notice:** The local driver (`SERVERLESS_TYPE=LOCAL`) runs code directly on the host in a Node.js process with no sandboxing. It should only be used for trusted code in development. For production deployments handling untrusted code, we highly recommend using `SERVERLESS_TYPE=LAMBDA` or `SERVERLESS_TYPE=DISABLED`.
 </Warning>
 
 ### Available Drivers
 
 | Driver | Environment Variable | Use Case | Security Level |
 |--------|---------------------|----------|----------------|
-| Disabled | `SERVERLESS_TYPE=DISABLED` | Disable serverless functions entirely | N/A |
+| Disabled | `SERVERLESS_TYPE=DISABLED` | Disable logic functions entirely | N/A |
 | Local | `SERVERLESS_TYPE=LOCAL` | Development and trusted environments | Low (no sandboxing) |
 | Lambda | `SERVERLESS_TYPE=LAMBDA` | Production with untrusted code | High (hardware-level isolation) |
 
@@ -321,11 +321,11 @@ SERVERLESS_LAMBDA_ACCESS_KEY_ID=your-access-key
 SERVERLESS_LAMBDA_SECRET_ACCESS_KEY=your-secret-key
 ```
 
-**To disable serverless functions:**
+**To disable logic functions:**
 ```bash
 SERVERLESS_TYPE=DISABLED
 ```
 
 <Note>
-When using `SERVERLESS_TYPE=DISABLED`, any attempt to execute a serverless function will return an error. This is useful if you want to run Twenty without serverless function capabilities.
+When using `SERVERLESS_TYPE=DISABLED`, any attempt to execute a logic function will return an error. This is useful if you want to run Twenty without logic function capabilities.
 </Note>

packages/twenty-docs/l/ar/developers/contribute/capabilities/local-setup.mdx

@@ -170,6 +170,13 @@ cd twenty
 
     يقوم هذا بإنشاء دور مشرف نظام باسم `postgres` مع إمكانية تسجيل الدخول.
 
+    ```bash
+    اسم الدور | الخصائص  | عضو في
+    -----------+-------------+-----------
+    postgres  | مشرف نظام   | {}
+    john      | مشرف نظام   | {}
+    ```
+
     **الخيار 2:** إذا كنت قد قمت بتثبيت docker:
 
     ```bash

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

@@ -9,18 +9,15 @@ description: أنشئ وأدِر تخصيصات Twenty على هيئة كود.
 
 ## ما هي التطبيقات؟
 
-تتيح لك التطبيقات إنشاء وإدارة تخصيصات Twenty **ككود**. بدلًا من تكوين كل شيء عبر واجهة المستخدم، تُعرِّف نموذج بياناتك ووظائف بلا خادم في الكود — مما يجعل الإنشاء والصيانة والنشر إلى مساحات عمل متعددة أسرع.
+تتيح لك التطبيقات إنشاء وإدارة تخصيصات Twenty **ككود**. بدلًا من تكوين كل شيء عبر واجهة المستخدم، تُعرِّف نموذج بياناتك ووظائف المنطق في الكود — مما يجعل البناء والصيانة والنشر إلى مساحات عمل متعددة أسرع.
 
 **ما الذي يمكنك فعله اليوم:**
 
 * عرِّف كائنات وحقولًا مخصصة على شكل كود (نموذج بيانات مُدار)
-* أنشئ وظائف بلا خادم مع مشغلات مخصصة
+* أنشئ وظائف منطقية مع مشغلات مخصصة
+* حدد المهارات لوكلاء الذكاء الاصطناعي
 * انشر التطبيق نفسه عبر مساحات عمل متعددة
 
-**قريبًا:**
-
-* تخطيطات ومكونات واجهة مستخدم مخصصة
-
 ## المتطلبات الأساسية
 
 * Node.js 24+ وYarn 4
@@ -31,7 +28,7 @@ description: أنشئ وأدِر تخصيصات Twenty على هيئة كود.
 أنشئ تطبيقًا جديدًا باستخدام المُهيئ الرسمي، ثم قم بالمصادقة وابدأ التطوير:
 
 ```bash filename="Terminal"
-# إنشاء تطبيق جديد
+# إنشاء تطبيق جديد (يتضمن جميع الأمثلة افتراضيًا)
 npx create-twenty-app@latest my-twenty-app
 cd my-twenty-app
 
@@ -40,35 +37,45 @@ corepack enable
 yarn install
 
 # قم بالمصادقة باستخدام مفتاح واجهة برمجة التطبيقات الخاص بك (سيُطلب منك ذلك)
-yarn auth:login
+yarn twenty auth:login
 
 # ابدأ وضع التطوير: يُزامن التغييرات المحلية تلقائيًا مع مساحة العمل الخاصة بك
-yarn app:dev
+yarn twenty app:dev
+```
+
+يدعم المُنشئ ثلاثة أوضاع للتحكم في ملفات الأمثلة التي سيتم تضمينها:
+
+```bash filename="Terminal"
+# الافتراضي (شامل): جميع الأمثلة (كائن، حقل، دالة منطقية، مكوّن الواجهة الأمامية، عرض، عنصر قائمة التنقل، مهارة)
+npx create-twenty-app@latest my-app
+
+# الأدنى: الملفات الأساسية فقط (application-config.ts و default-role.ts)
+npx create-twenty-app@latest my-app --minimal
+
+# التفاعلي: اختر الأمثلة التي تريد تضمينها
+npx create-twenty-app@latest my-app --interactive
 ```
 
 من هنا يمكنك:
 
 ```bash filename="Terminal"
 # Add a new entity to your application (guided)
-yarn app:create-entity
+yarn twenty entity:add
 
-# Generate a typed Twenty client and workspace entity types
-yarn app:generate
-
-# Run a one‑time sync (instead of watch mode)
-yarn app:sync
-
-# Watch your application's functions logs
-yarn function:logs
+# Watch your application's function logs
+yarn twenty function:logs
 
 # Execute a function by name
-yarn function:execute -n my-function -p '{"name": "test"}'
+yarn twenty function:execute -n my-function -p '{"name": "test"}'
+
+# Execute the post-install function
+yarn twenty function:execute --postInstall
 
 # Uninstall the application from the current workspace
-yarn app:uninstall
+yarn twenty app:uninstall
 
 # Display commands' help
-yarn app:help
+yarn twenty help
 ```
 
 راجع أيضًا: صفحات مرجع CLI لـ [create-twenty-app](https://www.npmjs.com/package/create-twenty-app) و[twenty-sdk CLI](https://www.npmjs.com/package/twenty-sdk).
@@ -80,9 +87,9 @@ yarn app:help
 * ينسخ تطبيقًا أساسيًا مصغّرًا إلى `my-twenty-app/`
 * يضيف اعتمادًا محليًا `twenty-sdk` وتهيئة Yarn 4
 * ينشئ ملفات ضبط ونصوصًا مرتبطة بـ `twenty` CLI
-* يُولّد ضبطًا افتراضيًا للتطبيق ودورًا افتراضيًا للوظيفة
+* يُنشئ الملفات الأساسية (تهيئة التطبيق، دور الدالة الافتراضي، دالة ما بعد التثبيت) بالإضافة إلى ملفات الأمثلة بحسب وضع الإنشاء
 
-يبدو التطبيق المُنشأ حديثًا بالقالب كما يلي:
+يبدو التطبيق المُنشأ حديثًا باستخدام الوضع الافتراضي `--exhaustive` كما يلي:
 
 ```text filename="my-twenty-app/"
 my-twenty-app/
@@ -96,86 +103,81 @@ my-twenty-app/
   eslint.config.mjs
   tsconfig.json
   README.md
+  public/                           # مجلد الأصول العامة (صور، خطوط، إلخ)
   src/
-    app/
-      application.config.ts     # مطلوب - التكوين الرئيسي للتطبيق
-      default-function.role.ts  # الدور الافتراضي للوظائف بدون خادم
-      // الكيانات الخاصة بك (*.object.ts, *.function.ts, *.role.ts)
-    utils/                      # اختياري - تنفيذات المُعالِجات والأدوات المساعدة
+  ├── application-config.ts           # مطلوب - إعدادات التطبيق الرئيسية
+  ├── roles/
+  │   └── default-role.ts               # الدور الافتراضي للدوال المنطقية
+  ├── objects/
+  │   └── example-object.ts             # تعريف كائن مخصص — مثال
+  ├── fields/
+  │   └── example-field.ts              # تعريف حقل مستقل — مثال
+  ├── logic-functions/
+  │   ├── hello-world.ts                # دالة منطقية — مثال
+  │   └── post-install.ts               # دالة منطقية لما بعد التثبيت
+  ├── front-components/
+  │   └── hello-world.tsx               # مكوّن واجهة أمامية — مثال
+  ├── views/
+  │   └── example-view.ts                # تعريف عرض محفوظ — مثال
+  ├── navigation-menu-items/
+  │   └── example-navigation-menu-item.ts # رابط تنقّل في الشريط الجانبي — مثال
+  └── skills/
+      └── example-skill.ts                # تعريف مهارة لوكيل الذكاء الاصطناعي — مثال
 ```
 
-### الاتفاقية فوق التهيئة
-
-تستخدم التطبيقات نهج **الاتفاقية فوق التهيئة** حيث تُكتشف الكيانات عبر لاحقة اسم الملف. يتيح ذلك تنظيمًا مرنًا داخل مجلد `src/app/`:
-
-| لاحقة الملف     | نوع الكيان             |
-| --------------- | ---------------------- |
-| `*.object.ts`   | تعريفات كائنات مخصصة   |
-| `*.function.ts` | تعريفات وظائف بلا خادم |
-| `*.role.ts`     | تعريفات الأدوار        |
-
-### طرق تنظيم المجلدات المدعومة
-
-يمكنك تنظيم الكيانات بأي من الأنماط التالية:
-
-**تقليدي (حسب النوع):**
-
-```text
-src/app/
-├── application.config.ts
-├── objects/
-│   └── postCard.object.ts
-├── functions/
-│   └── createPostCard.function.ts
-└── roles/
-    └── admin.role.ts
-```
-
-**حسب الميزة:**
-
-```text
-src/app/
-├── application.config.ts
-└── post-card/
-    ├── postCard.object.ts
-    ├── createPostCard.function.ts
-    └── postCardAdmin.role.ts
-```
-
-**مسطح:**
-
-```text
-src/app/
-├── application.config.ts
-├── postCard.object.ts
-├── createPostCard.function.ts
-└── admin.role.ts
-```
+مع `--minimal`، سيتم إنشاء الملفات الأساسية فقط (`application-config.ts` و`roles/default-role.ts` و`logic-functions/post-install.ts`). مع `--interactive`، تختار ملفات الأمثلة التي تريد تضمينها.
 
 بشكل عام:
 
-* **package.json**: يصرّح باسم التطبيق والإصدار والمحرّكات (Node 24+، Yarn 4)، ويضيف `twenty-sdk` فضلًا عن نصوص مثل `dev` و`sync` و`generate` و`create-entity` و`logs` و`uninstall` و`auth` التي تفوِّض إلى `twenty` CLI المحلي.
+* **package.json**: يصرّح باسم التطبيق والإصدار والمحرّكات (Node 24+، Yarn 4)، ويضيف `twenty-sdk` بالإضافة إلى نص برمجي `twenty` يفوِّض إلى `twenty` CLI المحلي. شغِّل `yarn twenty help` لعرض جميع الأوامر المتاحة.
 * **.gitignore**: يتجاهل العناصر الشائعة مثل `node_modules` و`.yarn` و`generated/` (عميل مضبوط الأنواع) و`dist/` و`build/` ومجلدات التغطية وملفات السجلات وملفات `.env*`.
 * **yarn.lock**، **.yarnrc.yml**، **.yarn/**: تقوم بقفل وتكوين حزمة أدوات Yarn 4 المستخدمة في المشروع.
 * **.nvmrc**: يثبّت إصدار Node.js المتوقع للمشروع.
 * **eslint.config.mjs** و**tsconfig.json**: يقدّمان إعدادات الفحص والتهيئة لـ TypeScript لمصادر TypeScript في تطبيقك.
 * **README.md**: ملف README قصير في جذر التطبيق يتضمن تعليمات أساسية.
-* **src/app/**: المكان الرئيسي حيث تعرّف تطبيقك ككود:
-  * `application.config.ts`: التكوين العام لتطبيقك (بيانات وصفية وربط وقت التشغيل). انظر "تكوين التطبيق" أدناه.
-  * `*.role.ts`: تعريفات الأدوار المستخدمة بواسطة وظائفك بلا خادم. انظر "الدور الافتراضي للوظيفة" أدناه.
-  * `*.object.ts`: تعريفات كائنات مخصصة.
-  * `*.function.ts`: تعريفات وظائف بلا خادم.
-* **src/utils/**: مجلد اختياري لتنفيذات المعالجات والأدوات المساعدة.
+* **public/**: مجلد لتخزين الأصول العامة (صور، خطوط، ملفات ثابتة) التي سيتم تقديمها مع تطبيقك. الملفات الموضوعة هنا تُرفع أثناء المزامنة وتكون متاحة أثناء وقت التشغيل.
+* **src/**: المكان الرئيسي حيث تعرّف تطبيقك ككود
+
+### اكتشاف الكيانات
+
+يكتشف SDK الكيانات عبر تحليل ملفات TypeScript الخاصة بك بحثًا عن استدعاءات **`export default define<Entity>({...})`**. يحتوي كل نوع كيان على دالة مساعدة مقابلة يتم تصديرها من `twenty-sdk`:
+
+| دالة مساعدة                  | نوع الكيان                           |
+| ---------------------------- | ------------------------------------ |
+| `defineObject()`             | تعريفات كائنات مخصصة                 |
+| `defineLogicFunction()`      | تعريفات الوظائف المنطقية             |
+| `defineFrontComponent()`     | Front component definitions          |
+| `defineRole()`               | تعريفات الأدوار                      |
+| `defineField()`              | امتدادات الحقول للكائنات الموجودة    |
+| `defineView()`               | تعريفات العروض المحفوظة              |
+| `defineNavigationMenuItem()` | تعريفات عناصر قائمة التنقل           |
+| `defineSkill()`              | تعريفات مهارات وكيل الذكاء الاصطناعي |
+
+<Note>
+  **تسمية الملفات مرنة.** يعتمد اكتشاف الكيانات على بنية الشجرة المجردة (AST) — إذ يقوم SDK بفحص ملفات المصدر لديك بحثًا عن النمط `export default define<Entity>({...})`. يمكنك تنظيم ملفاتك ومجلداتك كيفما تشاء. التجميع حسب نوع الكيان (مثلًا، `logic-functions/` و`roles/`) هو مجرد عرف لتنظيم الشيفرة، وليس مطلبًا إلزاميًا.
+</Note>
+
+مثال على كيان تم اكتشافه:
+
+```typescript
+// This file can be named anything and placed anywhere in src/
+import { defineObject, FieldType } from 'twenty-sdk';
+
+export default defineObject({
+  universalIdentifier: '...',
+  nameSingular: 'postCard',
+  // ... rest of config
+});
+```
 
 ستضيف الأوامر اللاحقة مزيدًا من الملفات والمجلدات:
 
-* `yarn app:generate` سيُنشئ مجلدًا `generated/` (عميل Twenty مضبوط الأنواع + أنواع مساحة العمل).
-* `yarn app:create-entity` سيضيف ملفات تعريف الكيانات تحت `src/app/` لكائناتك المخصصة أو الوظائف أو الأدوار.
-  l
+* `yarn twenty app:dev` سيولّد تلقائيًا عميل API مضبوط الأنواع في `node_modules/twenty-sdk/generated` (عميل Twenty مضبوط الأنواع + أنواع مساحة العمل).
+* `yarn twenty entity:add` سيضيف ملفات تعريف الكيانات ضمن `src/` لكائناتك المخصّصة، والوظائف، ومكوّنات الواجهة الأمامية، والأدوار، والمهارات، وغير ذلك.
 
 ## المصادقة
 
-في المرة الأولى التي تشغّل فيها `yarn auth:login`، سيُطلب منك إدخال:
+في المرة الأولى التي تشغّل فيها `yarn twenty auth:login`، سيُطلب منك إدخال:
 
 * عنوان URL لواجهة برمجة التطبيقات (الافتراضي http://localhost:3000 أو ملف تعريف مساحة العمل الحالية لديك)
 * مفتاح واجهة برمجة التطبيقات
@@ -185,26 +187,26 @@ src/app/
 ### Managing workspaces
 
 ```bash filename="Terminal"
-# Login interactively (recommended)
-yarn auth:login
+# تسجيل الدخول تفاعليًا (مُوصى به)
+yarn twenty auth:login
 
-# Login to a specific workspace profile
-yarn auth:login --workspace my-custom-workspace
+# تسجيل الدخول إلى ملف تعريف لمساحة عمل محددة
+yarn twenty auth:login --workspace my-custom-workspace
 
-# List all configured workspaces
-yarn auth:list
+# عرض جميع مساحات العمل المُكوَّنة
+yarn twenty auth:list
 
-# Switch the default workspace (interactive)
-yarn auth:switch
+# تبديل مساحة العمل الافتراضية (تفاعليًا)
+yarn twenty auth:switch
 
-# Switch to a specific workspace
-yarn auth:switch production
+# التبديل إلى مساحة عمل محددة
+yarn twenty auth:switch production
 
-# Check current authentication status
-yarn auth:status
+# التحقق من حالة المصادقة الحالية
+yarn twenty auth:status
 ```
 
-Once you've switched workspaces with `auth:switch`, all subsequent commands will use that workspace by default. You can still override it temporarily with `--workspace <name>`.
+بمجرد أن تقوم بالتبديل بين مساحات العمل باستخدام `yarn twenty auth:switch`، ستستخدم جميع الأوامر اللاحقة تلك المساحة افتراضيًا. You can still override it temporarily with `--workspace <name>`.
 
 ## استخدم موارد SDK (الأنواع والتكوين)
 
@@ -212,16 +214,21 @@ Once you've switched workspaces with `auth:switch`, all subsequent commands will
 
 ### دوال مساعدة
 
-يوفّر SDK أربع دوال مساعدة مع تحقق مدمج لتعريف كيانات تطبيقك:
+يوفّر SDK دوالًا مساعدة لتعريف كيانات تطبيقك. كما هو موضح في [اكتشاف الكيانات](#entity-detection)، يجب استخدام `export default define<Entity>({...})` كي يتم اكتشاف كياناتك:
 
-| دالة               | الغرض                                    |
-| ------------------ | ---------------------------------------- |
-| `defineApp()`      | تهيئة بيانات التطبيق الوصفية             |
-| `defineObject()`   | تعريف كائنات مخصصة مع حقول               |
-| `defineFunction()` | تعريف وظائف بلا خادم مع معالجات          |
-| `defineRole()`     | تهيئة صلاحيات الدور والوصول إلى الكائنات |
+| دالة                         | الغرض                                                |
+| ---------------------------- | ---------------------------------------------------- |
+| `defineApplication()`        | تهيئة بيانات التعريف للتطبيق (مطلوب، واحد لكل تطبيق) |
+| `defineObject()`             | تعريف كائنات مخصصة مع حقول                           |
+| `defineLogicFunction()`      | تعريف وظائف منطقية مع معالجات                        |
+| `defineFrontComponent()`     | عرِّف مكوّنات أمامية لواجهة مستخدم مخصّصة            |
+| `defineRole()`               | تهيئة صلاحيات الدور والوصول إلى الكائنات             |
+| `defineField()`              | وسّع الكائنات الموجودة بحقول إضافية                  |
+| `defineView()`               | تعريف العروض المحفوظة للكائنات                       |
+| `defineNavigationMenuItem()` | تعريف روابط التنقل في الشريط الجانبي                 |
+| `defineSkill()`              | عرّف مهارات وكيل الذكاء الاصطناعي                    |
 
-تتحقق هذه الدوال من تكوينك في وقت التشغيل وتوفر إكمالًا تلقائيًا أفضل في بيئة التطوير وأمان أنواع أعلى.
+تتحقق هذه الدوال من تكوينك وقت البناء وتوفّر إكمالًا تلقائيًا في بيئة التطوير وأمان الأنواع.
 
 ### تعريف الكائنات
 
@@ -302,79 +309,34 @@ export default defineObject({
 * `universalIdentifier` يجب أن يكون فريدًا وثابتًا عبر عمليات النشر.
 * يتطلب كل حقل `name` و`type` و`label` ومعرّف `universalIdentifier` ثابتًا خاصًا به.
 * المصفوفة `fields` اختيارية — يمكنك تعريف كائنات بدون حقول مخصصة.
-* يمكنك إنشاء كائنات جديدة باستخدام `yarn app:create-entity`، والذي يرشدك خلال التسمية والحقول والعلاقات.
+* يمكنك إنشاء كائنات جديدة باستخدام `yarn twenty entity:add`، والذي يرشدك خلال التسمية والحقول والعلاقات.
 
 <Note>
-  **يتم إنشاء الحقول الأساسية تلقائيًا.** عند تعريف كائن مخصص، يضيف Twenty تلقائيًا حقولًا قياسية مثل `name` و`createdAt` و`updatedAt` و`createdBy` و`position` و`deletedAt`. لا تحتاج إلى تعريف هذه في مصفوفة `fields` — أضف فقط حقولك المخصصة.
+  **يتم إنشاء الحقول الأساسية تلقائيًا.** عند تعريف كائن مخصص، يضيف Twenty تلقائيًا حقولًا قياسية
+  مثل `id` و`name` و`createdAt` و`updatedAt` و`createdBy` و`updatedBy` و`deletedAt`.
+  لا تحتاج إلى تعريف هذه في مصفوفة `fields` — أضف فقط حقولك المخصصة.
+  يمكنك تجاوز الحقول الافتراضية من خلال تعريف حقل بالاسم نفسه في مصفوفة `fields` الخاصة بك،
+  لكن هذا غير مستحسن.
 </Note>
 
-<Accordion title="بديل: صياغة قائمة على المزيّنات">
-  يمكنك أيضًا تعريف كائنات باستخدام مزيّنات TypeScript. يستخدم هذا النهج صياغة معتمدة على الأصناف مع مزيّنات `@Object` و`@Field` و`@Relation`:
+### تكوين التطبيق (application-config.ts)
 
-  ```typescript
-  import {
-    type AddressField,
-    Field,
-    FieldType,
-    type FullNameField,
-    Object,
-    OnDeleteAction,
-    Relation,
-    RelationType,
-    STANDARD_OBJECT_UNIVERSAL_IDENTIFIERS,
-  } from 'twenty-sdk';
-  import { type Note } from '../../generated';
-
-  @Object({
-    universalIdentifier: '54b589ca-eeed-4950-a176-358418b85c05',
-    nameSingular: 'postCard',
-    namePlural: 'postCards',
-    labelSingular: 'Post card',
-    labelPlural: 'Post cards',
-    description: 'A post card object',
-    icon: 'IconMail',
-  })
-  export class PostCard {
-    @Field({
-      universalIdentifier: '58a0a314-d7ea-4865-9850-7fb84e72f30b',
-      type: FieldType.TEXT,
-      label: 'Content',
-      description: "Postcard's content",
-      icon: 'IconAbc',
-    })
-    content: string;
-
-    @Relation({
-      universalIdentifier: 'c9e2b4f4-b9ad-4427-9b42-9971b785edfe',
-      type: RelationType.ONE_TO_MANY,
-      label: 'Notes',
-      icon: 'IconComment',
-      inverseSideTargetUniversalIdentifier: STANDARD_OBJECT_UNIVERSAL_IDENTIFIERS.note,
-      onDelete: OnDeleteAction.CASCADE,
-    })
-    notes: Note[];
-  }
-  ```
-
-  ملاحظة: يتطلب نهج المزيّنات `experimentalDecorators` في تهيئة TypeScript لديك.
-</Accordion>
-
-### تكوين التطبيق (application.config.ts)
-
-كل تطبيق لديه ملف واحد `application.config.ts` يصف:
+كل تطبيق لديه ملف واحد `application-config.ts` يصف:
 
 * **هوية التطبيق**: المعرفات، اسم العرض، والوصف.
 * **كيفية تشغيل وظائفه**: الدور الذي تستخدمه للأذونات.
 * **متغيرات (اختياري)**: أزواج مفتاح-قيمة تُعرض لوظائفك كمتغيرات بيئة.
+* **(Optional) post-install function**: a logic function that runs after the app is installed.
 
-استخدم `defineApp()` لتعريف تهيئة تطبيقك:
+Use `defineApplication()` to define your application configuration:
 
 ```typescript
-// src/app/application.config.ts
-import { defineApp } from 'twenty-sdk';
-import { DEFAULT_FUNCTION_ROLE_UNIVERSAL_IDENTIFIER } from './default-function.role';
+// src/application-config.ts
+import { defineApplication } from 'twenty-sdk';
+import { DEFAULT_ROLE_UNIVERSAL_IDENTIFIER } from 'src/roles/default-role';
+import { POST_INSTALL_UNIVERSAL_IDENTIFIER } from 'src/logic-functions/post-install';
 
-export default defineApp({
+export default defineApplication({
   universalIdentifier: '4ec0391d-18d5-411c-b2f3-266ddc1c3ef7',
   displayName: 'My Twenty App',
   description: 'My first Twenty app',
@@ -387,7 +349,8 @@ export default defineApp({
       isSecret: false,
     },
   },
-  functionRoleUniversalIdentifier: DEFAULT_FUNCTION_ROLE_UNIVERSAL_IDENTIFIER,
+  defaultRoleUniversalIdentifier: DEFAULT_ROLE_UNIVERSAL_IDENTIFIER,
+  postInstallLogicFunctionUniversalIdentifier: POST_INSTALL_UNIVERSAL_IDENTIFIER,
 });
 ```
 
@@ -395,11 +358,12 @@ export default defineApp({
 
 * حقول `universalIdentifier` هي معرّفات حتمية تخصك؛ أنشئها مرة واحدة واحتفظ بها ثابتة عبر عمليات المزامنة.
 * `applicationVariables` تصبح متغيرات بيئة لوظائفك (على سبيل المثال، `DEFAULT_RECIPIENT_NAME` متاح كـ `process.env.DEFAULT_RECIPIENT_NAME`).
-* `functionRoleUniversalIdentifier` يجب أن يطابق الدور الذي تعرّفه في ملف `*.role.ts` (انظر أدناه).
+* `defaultRoleUniversalIdentifier` يجب أن يطابق ملف الدور (انظر أدناه).
+* `postInstallLogicFunctionUniversalIdentifier` (optional) points to a logic function that runs automatically after the app is installed. See [Post-install functions](#post-install-functions).
 
 #### الأدوار والصلاحيات
 
-يمكن للتطبيقات تعريف أدوار تُغلّف الصلاحيات على كائنات وإجراءات مساحة العمل لديك. يعين الحقل `functionRoleUniversalIdentifier` في `application.config.ts` الدور الافتراضي الذي تستخدمه الوظائف بلا خادم في تطبيقك.
+يمكن للتطبيقات تعريف أدوار تُغلّف الصلاحيات على كائنات وإجراءات مساحة العمل لديك. يعين الحقل `defaultRoleUniversalIdentifier` في `application-config.ts` الدور الافتراضي الذي تستخدمه وظائف المنطق في تطبيقك.
 
 * مفتاح واجهة البرمجة في وقت التشغيل المحقون باسم `TWENTY_API_KEY` مستمد من دور الوظيفة الافتراضي هذا.
 * سيُقيَّد العميل مضبوط الأنواع بالأذونات الممنوحة لذلك الدور.
@@ -410,14 +374,14 @@ export default defineApp({
 عند توليد تطبيق جديد بالقالب، ينشئ CLI أيضًا ملف دور افتراضي. استخدم `defineRole()` لتعريف أدوار مع تحقق مدمج:
 
 ```typescript
-// src/app/default-function.role.ts
+// src/roles/default-role.ts
 import { defineRole, PermissionFlag } from 'twenty-sdk';
 
-export const DEFAULT_FUNCTION_ROLE_UNIVERSAL_IDENTIFIER =
+export const DEFAULT_ROLE_UNIVERSAL_IDENTIFIER =
   'b648f87b-1d26-4961-b974-0908fd991061';
 
 export default defineRole({
-  universalIdentifier: DEFAULT_FUNCTION_ROLE_UNIVERSAL_IDENTIFIER,
+  universalIdentifier: DEFAULT_ROLE_UNIVERSAL_IDENTIFIER,
   label: 'Default function role',
   description: 'Default role for function Twenty client',
   canReadAllObjectRecords: false,
@@ -430,7 +394,7 @@ export default defineRole({
   canBeAssignedToApiKeys: false,
   objectPermissions: [
     {
-      objectNameSingular: 'postCard',
+      objectUniversalIdentifier: '9f9882af-170c-4879-b013-f9628b77c050',
       canReadObjectRecords: true,
       canUpdateObjectRecords: true,
       canSoftDeleteObjectRecords: false,
@@ -439,8 +403,8 @@ export default defineRole({
   ],
   fieldPermissions: [
     {
-      objectNameSingular: 'postCard',
-      fieldName: 'content',
+      objectUniversalIdentifier: '9f9882af-170c-4879-b013-f9628b77c050',
+      fieldUniversalIdentifier: 'b2c37dc0-8ae7-470e-96cd-1476b47dfaff',
       canReadFieldValue: false,
       canUpdateFieldValue: false,
     },
@@ -449,10 +413,10 @@ export default defineRole({
 });
 ```
 
-يُشار بعد ذلك إلى `universalIdentifier` لهذا الدور في `application.config.ts` باسم `functionRoleUniversalIdentifier`. بعبارة أخرى:
+يُشار بعد ذلك إلى `universalIdentifier` لهذا الدور في `application-config.ts` باسم `defaultRoleUniversalIdentifier`. بعبارة أخرى:
 
 * **\\*.role.ts** يحدد ما يمكن أن يفعله الدور الافتراضي للوظيفة.
-* **application.config.ts** يشير إلى ذلك الدور بحيث ترث وظائفك صلاحياته.
+* **application-config.ts** يشير إلى ذلك الدور بحيث ترث وظائفك أذوناته.
 
 الملاحظات:
 
@@ -461,22 +425,17 @@ export default defineRole({
 * `permissionFlags` تتحكم في الوصول إلى القدرات على مستوى المنصة. اجعلها في الحد الأدنى؛ أضف فقط ما تحتاجه.
 * اطّلع على مثال عملي في تطبيق Hello World: [`packages/twenty-apps/hello-world/src/roles/function-role.ts`](https://github.com/twentyhq/twenty/blob/main/packages/twenty-apps/hello-world/src/roles/function-role.ts).
 
-### تكوين وظيفة بلا خادم ونقطة الدخول
+### تكوين الوظيفة المنطقية ونقطة الدخول
 
-كل ملف وظيفة يستخدم `defineFunction()` لتصدير تكوين مع معالج ومشغلات اختيارية. استخدم لاحقة الملف `*.function.ts` للاكتشاف التلقائي.
+كل ملف وظيفة يستخدم `defineLogicFunction()` لتصدير تكوين مع معالج ومشغّلات اختيارية.
 
 ```typescript
-// src/app/createPostCard.function.ts
-import { defineFunction } from 'twenty-sdk';
+// src/app/createPostCard.logic-function.ts
+import { defineLogicFunction } from 'twenty-sdk';
 import type { DatabaseEventPayload, ObjectRecordCreateEvent, CronPayload, RoutePayload } from 'twenty-sdk';
-import Twenty, { type Person } from '../../generated';
+import Twenty, { type Person } from '~/generated';
 
-const handler = async (
-  params:
-    | RoutePayload
-    | DatabaseEventPayload<ObjectRecordCreateEvent<Person>>
-    | CronPayload,
-) => {
+const handler = async (params: RoutePayload) => {
   const client = new Twenty(); // generated typed client
   const name = 'name' in params.queryStringParameters
     ? params.queryStringParameters.name ?? process.env.DEFAULT_RECIPIENT_NAME ?? 'Hello world'
@@ -492,7 +451,7 @@ const handler = async (
   return result;
 };
 
-export default defineFunction({
+export default defineLogicFunction({
   universalIdentifier: 'e56d363b-0bdc-4d8a-a393-6f0d1c75bdcf',
   name: 'create-new-post-card',
   timeoutSeconds: 2,
@@ -507,18 +466,18 @@ export default defineFunction({
       isAuthRequired: false,
     },
     // Cron trigger (CRON pattern)
-    {
-      universalIdentifier: 'dd802808-0695-49e1-98c9-d5c9e2704ce2',
-      type: 'cron',
-      pattern: '0 0 1 1 *',
-    },
+    // {
+    //   universalIdentifier: 'dd802808-0695-49e1-98c9-d5c9e2704ce2',
+    //   type: 'cron',
+    //   pattern: '0 0 1 1 *',
+    // },
     // Database event trigger
-    {
-      universalIdentifier: '203f1df3-4a82-4d06-a001-b8cf22a31156',
-      type: 'databaseEvent',
-      eventName: 'person.updated',
-      updatedFields: ['name'],
-    },
+    // {
+    //   universalIdentifier: '203f1df3-4a82-4d06-a001-b8cf22a31156',
+    //   type: 'databaseEvent',
+    //   eventName: 'person.updated',
+    //   updatedFields: ['name'],
+    // },
   ],
 });
 ```
@@ -539,6 +498,55 @@ export default defineFunction({
 * المصفوفة `triggers` اختيارية. يمكن استخدام الوظائف بدون مشغلات كوظائف مساعدة تُستدعى بواسطة وظائف أخرى.
 * يمكنك مزج أنواع متعددة من المشغلات في وظيفة واحدة.
 
+### Post-install functions
+
+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.
+
+عند إنشاء هيكل تطبيق جديد باستخدام `create-twenty-app`، يتم إنشاء دالة ما بعد التثبيت لك في `src/logic-functions/post-install.ts`:
+
+```typescript
+// src/logic-functions/post-install.ts
+import { defineLogicFunction } from 'twenty-sdk';
+
+export const POST_INSTALL_UNIVERSAL_IDENTIFIER = '<generated-uuid>';
+
+const handler = async (): Promise<void> => {
+  console.log('Post install logic function executed successfully!');
+};
+
+export default defineLogicFunction({
+  universalIdentifier: POST_INSTALL_UNIVERSAL_IDENTIFIER,
+  name: 'post-install',
+  description: 'Runs after installation to set up the application.',
+  timeoutSeconds: 300,
+  handler,
+});
+```
+
+يتم ربط الدالة بتطبيقك من خلال الإشارة إلى المعرِّف العالمي الخاص بها في `application-config.ts`:
+
+```typescript
+import { POST_INSTALL_UNIVERSAL_IDENTIFIER } from 'src/logic-functions/post-install';
+
+export default defineApplication({
+  // ...
+  postInstallLogicFunctionUniversalIdentifier: POST_INSTALL_UNIVERSAL_IDENTIFIER,
+});
+```
+
+يمكنك أيضًا تنفيذ دالة ما بعد التثبيت يدويًا في أي وقت باستخدام CLI:
+
+```bash filename="Terminal"
+yarn twenty function:execute --postInstall
+```
+
+النقاط الرئيسية:
+
+* دوال ما بعد التثبيت هي دوال منطقية قياسية — فهي تستخدم `defineLogicFunction()` مثل أي دالة أخرى.
+* حقل `postInstallLogicFunctionUniversalIdentifier` في `defineApplication()` اختياري. إذا تم تجاهله، لن يتم تشغيل أي دالة بعد التثبيت.
+* تم تعيين مهلة افتراضية إلى 300 ثانية (5 دقائق) للسماح بمهام الإعداد الأطول مثل تهيئة البيانات.
+* لا تحتاج دوال ما بعد التثبيت إلى مُشغِّلات — حيث يستدعيها النظام الأساسي أثناء التثبيت أو يدويًا عبر `function:execute --postInstall`.
+
 ### حمولة مشغل المسار
 
 <Warning>
@@ -565,10 +573,10 @@ export default defineFunction({
   **لترحيل الدوال الحالية:** حدّث المعالج لديك لفكّ البنية من `event.body` أو `event.queryStringParameters` أو `event.pathParameters` بدلاً من القراءة مباشرةً من كائن params.
 </Warning>
 
-عندما يستدعي مشغّل المسار دالتك، فإنه يتلقى كائنًا من النوع `RoutePayload` يتبع تنسيق AWS HTTP API v2. استورد النوع من `twenty-sdk`:
+عندما يستدعي مشغّل المسار وظيفتك المنطقية، يتلقى كائنًا من النوع `RoutePayload` يتبع تنسيق AWS HTTP API v2. استورد النوع من `twenty-sdk`:
 
 ```typescript
-import { defineFunction, type RoutePayload } from 'twenty-sdk';
+import { defineLogicFunction, type RoutePayload } from 'twenty-sdk';
 
 const handler = async (event: RoutePayload) => {
   // Access request data
@@ -595,10 +603,10 @@ const handler = async (event: RoutePayload) => {
 
 ### تمرير رؤوس HTTP
 
-افتراضيًا، لا يتم تمرير رؤوس HTTP من الطلبات الواردة إلى دالتك بدون خادم لأسباب أمنية. للوصول إلى رؤوس محددة، قم بإدراجها صراحةً في مصفوفة `forwardedRequestHeaders`:
+افتراضيًا، **لا** تُمرَّر رؤوس HTTP من الطلبات الواردة إلى وظيفتك المنطقية لأسباب أمنية. للوصول إلى رؤوس محددة، قم بإدراجها صراحةً في مصفوفة `forwardedRequestHeaders`:
 
 ```typescript
-export default defineFunction({
+export default defineLogicFunction({
   universalIdentifier: 'e56d363b-0bdc-4d8a-a393-6f0d1c75bdcf',
   name: 'webhook-handler',
   handler,
@@ -633,23 +641,160 @@ const handler = async (event: RoutePayload) => {
 
 يمكنك إنشاء وظائف جديدة بطريقتين:
 
-* **مُنشأ بالقالب**: شغّل `yarn app:create-entity` واختر خيار إضافة وظيفة جديدة. يُولّد هذا ملفًا مبدئيًا مع معالج وتكوين.
-* **يدوي**: أنشئ ملفًا جديدًا `*.function.ts` واستخدم `defineFunction()` مع اتباع النمط نفسه.
+* **مُنشأ بالقالب**: شغّل `yarn twenty entity:add` واختر خيار إضافة وظيفة منطقية جديدة. يُولّد هذا ملفًا مبدئيًا مع معالج وتكوين.
+* **يدوي**: أنشئ ملفًا جديدًا `*.logic-function.ts` واستخدم `defineLogicFunction()` مع اتباع النمط نفسه.
+
+### تمييز دالة منطقية كأداة
+
+يمكن إتاحة الدوال المنطقية بوصفها **أدوات** لوكلاء الذكاء الاصطناعي وسير العمل. عندما يتم تمييز دالة كأداة، تصبح قابلة للاكتشاف بواسطة ميزات الذكاء الاصطناعي الخاصة بـ Twenty ويمكن اختيارها كخطوة في أتمتة سير العمل.
+
+لتمييز دالة منطقية كأداة، عيّن `isTool: true` وقدّم `toolInputSchema` يصف معاملات الإدخال المتوقعة باستخدام [مخطط JSON](https://json-schema.org/):
+
+```typescript
+// src/logic-functions/enrich-company.logic-function.ts
+import { defineLogicFunction } from 'twenty-sdk';
+import Twenty from '~/generated';
+
+const handler = async (params: { companyName: string; domain?: string }) => {
+  const client = new Twenty();
+
+  const result = await client.mutation({
+    createTask: {
+      __args: {
+        data: {
+          title: `Enrich data for ${params.companyName}`,
+          body: `Domain: ${params.domain ?? 'unknown'}`,
+        },
+      },
+      id: true,
+    },
+  });
+
+  return { taskId: result.createTask.id };
+};
+
+export default defineLogicFunction({
+  universalIdentifier: 'f47ac10b-58cc-4372-a567-0e02b2c3d479',
+  name: 'enrich-company',
+  description: 'Enrich a company record with external data',
+  timeoutSeconds: 10,
+  handler,
+  isTool: true,
+  toolInputSchema: {
+    type: 'object',
+    properties: {
+      companyName: {
+        type: 'string',
+        description: 'The name of the company to enrich',
+      },
+      domain: {
+        type: 'string',
+        description: 'The company website domain (optional)',
+      },
+    },
+    required: ['companyName'],
+  },
+});
+```
+
+النقاط الرئيسية:
+
+* **`isTool`** (`boolean`, الافتراضي: `false`): عند ضبطه على `true`، يتم تسجيل الدالة كأداة وتصبح متاحة لوكلاء الذكاء الاصطناعي ولأتمتة سير العمل.
+* **`toolInputSchema`** (`object`, اختياري): كائن JSON Schema يصف المعلمات التي تقبلها دالتك. يستخدم وكلاء الذكاء الاصطناعي هذا المخطط لفهم المدخلات التي تتوقعها الأداة وللتحقق من صحة الاستدعاءات. إذا تم إغفاله، فالقيمة الافتراضية للمخطط هي `{ type: 'object', properties: {} }` (من دون معلمات).
+* الدوال التي لديها `isTool: false` (أو غير معيَّنة) **غير** معروضة كأدوات. لا يزال بالإمكان تنفيذها مباشرةً أو استدعاؤها بواسطة دوال أخرى، لكنها لن تظهر في اكتشاف الأدوات.
+* **تسمية الأداة**: عند كشفها كأداة، يتم تطبيع اسم الدالة تلقائيًا إلى `logic_function_<name>` (تحويله إلى أحرف صغيرة، واستبدال المحارف غير الأبجدية الرقمية بشرطات سفلية). على سبيل المثال، `enrich-company` تصبح `logic_function_enrich_company`.
+* يمكنك دمج `isTool` مع المشغِّلات — إذ يمكن للدالة أن تكون أداة (قابلة للاستدعاء من قِبل وكلاء الذكاء الاصطناعي) وأن تُشغَّل بواسطة أحداث (cron، وأحداث قاعدة البيانات، والمسارات) في الوقت نفسه.
+
+<Note>
+  **اكتب `description` جيدًا.** يعتمد وكلاء الذكاء الاصطناعي على حقل `description` الخاص بالدالة لتحديد وقت استخدام الأداة. كن محددًا بشأن ما تفعله الأداة ومتى ينبغي استدعاؤها.
+</Note>
+
+### المكوّنات الأمامية
+
+تتيح لك المكوّنات الأمامية إنشاء مكوّنات React مخصّصة تُعرَض داخل واجهة مستخدم Twenty. استخدم `defineFrontComponent()` لتعريف مكوّنات مع تحقّق مدمج:
+
+```typescript
+// src/my-widget.front-component.tsx
+import { defineFrontComponent } from 'twenty-sdk';
+
+const MyWidget = () => {
+  return (
+    <div style={{ padding: '20px', fontFamily: 'sans-serif' }}>
+      <h1>My Custom Widget</h1>
+      <p>This is a custom front component for Twenty.</p>
+    </div>
+  );
+};
+
+export default defineFrontComponent({
+  universalIdentifier: 'a1b2c3d4-e5f6-7890-abcd-ef1234567890',
+  name: 'my-widget',
+  description: 'A custom widget component',
+  component: MyWidget,
+});
+```
+
+النقاط الرئيسية:
+
+* المكوّنات الأمامية هي مكوّنات React تُعرَض ضمن سياقات معزولة داخل Twenty.
+* استخدم لاحقة الملف `*.front-component.tsx` للاكتشاف التلقائي.
+* يشير الحقل `component` إلى مكوّن React الخاص بك.
+* يتم بناء المكوّنات ومزامنتها تلقائيًا أثناء `yarn twenty app:dev`.
+
+يمكنك إنشاء مكوّنات أمامية جديدة بطريقتين:
+
+* **مُنشأ بالقالب**: شغّل `yarn twenty entity:add` واختر خيار إضافة مكوّن أمامي جديد.
+* **يدوي**: أنشئ ملفًا جديدًا `*.front-component.tsx` واستخدم `defineFrontComponent()`.
+
+### المهارات
+
+تُحدِّد المهارات تعليمات وإمكانات قابلة لإعادة الاستخدام يمكن لوكلاء الذكاء الاصطناعي استخدامها داخل مساحة العمل لديك. استخدم `defineSkill()` لتعريف مهارات مع تحقّق مدمج:
+
+```typescript
+// src/skills/example-skill.ts
+import { defineSkill } from 'twenty-sdk';
+
+export default defineSkill({
+  universalIdentifier: 'a1b2c3d4-e5f6-7890-abcd-ef1234567890',
+  name: 'sales-outreach',
+  label: 'التواصل البيعي',
+  description: 'يرشد وكيل الذكاء الاصطناعي خلال عملية منظّمة للتواصل البيعي',
+  icon: 'IconBrain',
+  content: `أنت مساعد للتواصل البيعي. عند التواصل مع عميل محتمل:
+1. ابحث عن الشركة وآخر الأخبار
+2. حدِّد دور العميل المحتمل ونقاط الألم المرجّحة
+3. صِغ رسالة مخصّصة تشير إلى تفاصيل محدّدة
+4. حافظ على نبرة احترافية ولكن حوارية`,
+});
+```
+
+النقاط الرئيسية:
+
+* `name` هي سلسلة معرّف فريدة للمهارة (يُنصَح باستخدام kebab-case).
+* `label` هو اسم العرض المقروء للبشر الظاهر في واجهة المستخدم.
+* `content` يحتوي على تعليمات المهارة — وهو النص الذي يستخدمه وكيل الذكاء الاصطناعي.
+* `icon` (اختياري) يحدّد الأيقونة المعروضة في واجهة المستخدم.
+* `description` (اختياري) يوفّر سياقًا إضافيًا حول غرض المهارة.
+
+يمكنك إنشاء مهارات جديدة بطريقتين:
+
+* **مُنشأ بالقالب**: شغِّل `yarn twenty entity:add` واختر خيار إضافة مهارة جديدة.
+* **يدوي**: أنشئ ملفًا جديدًا واستخدم `defineSkill()` مع اتباع النمط نفسه.
 
 ### عميل مُولَّد مضبوط الأنواع
 
-شغّل yarn app:generate لإنشاء عميل محلي مضبوط الأنواع في generated/ استنادًا إلى مخطط مساحة العمل لديك. استخدمه في وظائفك:
+يُولَّد العميل مضبوط الأنواع تلقائيًا بواسطة `yarn twenty app:dev` ويُخزَّن في `node_modules/twenty-sdk/generated` استنادًا إلى مخطط مساحة العمل لديك. استخدمه في وظائفك:
 
 ```typescript
-import Twenty from './generated';
+import Twenty from '~/generated';
 
 const client = new Twenty();
 const { me } = await client.query({ me: { id: true, displayName: true } });
 ```
 
-يُعاد توليد العميل بواسطة `yarn app:generate`. أعِد تشغيله بعد تغيير كائناتك وتشغيل `yarn app:sync` أو عند الانضمام إلى مساحة عمل جديدة.
+يُعاد توليد العميل تلقائيًا بواسطة `yarn twenty app:dev` كلما تغيّرت كائناتك أو حقولك.
 
-#### بيانات الاعتماد في وقت التشغيل في الوظائف بلا خادم
+#### بيانات الاعتماد وقت التشغيل في الوظائف المنطقية
 
 عندما تعمل وظيفتك على Twenty، يقوم النظام الأساسي بحقن بيانات الاعتماد كمتغيرات بيئة قبل تنفيذ كودك:
 
@@ -659,45 +804,85 @@ const { me } = await client.query({ me: { id: true, displayName: true } });
 الملاحظات:
 
 * لا تحتاج إلى تمرير عنوان URL أو مفتاح واجهة برمجة التطبيقات إلى العميل المُولَّد. يقوم بقراءة `TWENTY_API_URL` و`TWENTY_API_KEY` من process.env وقت التشغيل.
-* تُحدَّد أذونات مفتاح واجهة برمجة التطبيقات بواسطة الدور المشار إليه في `application.config.ts` عبر `functionRoleUniversalIdentifier`. هذا هو الدور الافتراضي الذي تستخدمه الوظائف بلا خادم في تطبيقك.
-* يمكن للتطبيقات تعريف أدوار لاتباع مبدأ أقل الامتياز. امنح فقط الأذونات التي تحتاجها وظائفك، ثم وجّه `functionRoleUniversalIdentifier` إلى المعرّف الشامل لذلك الدور.
+* تُحدَّد أذونات مفتاح واجهة برمجة التطبيقات بواسطة الدور المشار إليه في `application-config.ts` عبر `defaultRoleUniversalIdentifier`. هذا هو الدور الافتراضي الذي تستخدمه الوظائف المنطقية في تطبيقك.
+* يمكن للتطبيقات تعريف أدوار لاتباع مبدأ أقل الامتياز. امنح فقط الأذونات التي تحتاجها وظائفك، ثم وجّه `defaultRoleUniversalIdentifier` إلى المعرّف الشامل لذلك الدور.
+
+#### رفع الملفات
+
+يتضمن العميل `Twenty` المُولَّد طريقة `uploadFile` لإرفاق الملفات بالحقول من نوع ملف ضمن كائنات مساحة العمل الخاصة بك. نظرًا لأن عملاء GraphQL القياسيون لا يدعمون تحميل الملفات متعددة الأجزاء افتراضيًا، يوفر العميل هذه الطريقة المخصصة التي تطبق [مواصفة طلب GraphQL متعدد الأجزاء](https://github.com/jaydenseric/graphql-multipart-request-spec) في الخلفية.
+
+```typescript
+import Twenty from '~/generated';
+import * as fs from 'fs';
+
+const client = new Twenty();
+
+const fileBuffer = fs.readFileSync('./invoice.pdf');
+
+const uploadedFile = await client.uploadFile(
+  fileBuffer,                                         // file contents as a Buffer
+  'invoice.pdf',                                      // filename
+  'application/pdf',                                  // MIME type (defaults to 'application/octet-stream')
+  '58a0a314-d7ea-4865-9850-7fb84e72f30b',            // field universal identifier
+);
+
+console.log(uploadedFile);
+// { id: '...', path: '...', size: 12345, createdAt: '...', url: 'https://...' }
+```
+
+توقيع الطريقة:
+
+```typescript
+uploadFile(
+  fileBuffer: Buffer,
+  filename: string,
+  contentType: string,
+  fieldMetadataUniversalIdentifier: string,
+): Promise<{ id: string; path: string; size: number; createdAt: string; url: string }>
+```
+
+| المعلمة                            | النوع    | الوصف                                                                              |
+| ---------------------------------- | -------- | ---------------------------------------------------------------------------------- |
+| `fileBuffer`                       | `Buffer` | المحتوى الخام للملف                                                                |
+| `filename`                         | `string` | اسم الملف (يُستخدم للتخزين والعرض)                                                 |
+| `contentType`                      | `string` | نوع MIME للملف (القيمة الافتراضية هي `application/octet-stream` إذا لم يتم تحديده) |
+| `fieldMetadataUniversalIdentifier` | `string` | قيمة `universalIdentifier` لحقل نوع الملف في كائنك                                 |
+
+النقاط الرئيسية:
+
+* ترسل هذه الطريقة الملف إلى **نقطة نهاية البيانات الوصفية** (وليست نقطة النهاية الرئيسية لـ GraphQL)، حيث تُنفَّذ عملية الرفع.
+* تستخدم `universalIdentifier` الخاص بالحقل (وليس المعرّف الخاص بمساحة العمل)، ليعمل كود الرفع لديك عبر أي مساحة عمل مُثبَّت فيها تطبيقك — بما يتماشى مع كيفية إشارة التطبيقات إلى الحقول في كل مكان آخر.
+* العنوان `url` المُعاد هو عنوان URL موقّع يمكنك استخدامه للوصول إلى الملف المرفوع.
 
 ### مثال Hello World
 
-استكشف مثالًا بسيطًا شاملًا من البداية إلى النهاية يوضح الكائنات والوظائف ومشغلات متعددة [هنا](https://github.com/twentyhq/twenty/tree/main/packages/twenty-apps/hello-world):
+استكشف مثالًا بسيطًا شاملًا من البداية إلى النهاية يوضح الكائنات والوظائف المنطقية والمكوّنات الأمامية ومشغّلات متعددة [هنا](https://github.com/twentyhq/twenty/tree/main/packages/twenty-apps/hello-world):
 
 ## إعداد يدوي (بدون المهيئ)
 
-بينما نوصي باستخدام `create-twenty-app` للحصول على أفضل تجربة للبدء، يمكنك أيضًا إعداد مشروع يدويًا. لا تثبّت CLI عالميًا. بدل ذلك، أضف `twenty-sdk` كاعتماد محلي ووصل السكربتات في ملف package.json لديك:
+بينما نوصي باستخدام `create-twenty-app` للحصول على أفضل تجربة للبدء، يمكنك أيضًا إعداد مشروع يدويًا. لا تثبّت CLI عالميًا. بدل ذلك، أضف `twenty-sdk` كاعتماد محلي واربط سكربتًا واحدًا في ملف package.json لديك:
 
 ```bash filename="Terminal"
 yarn add -D twenty-sdk
 ```
 
-ثم أضف نصوصًا مثل هذه:
+ثم أضف سكربتًا باسم `twenty`:
 
 ```json filename="package.json"
 {
   "scripts": {
-    "auth": "twenty auth login",
-    "generate": "twenty app generate",
-    "dev": "twenty app dev",
-    "sync": "twenty app sync",
-    "uninstall": "twenty app uninstall",
-    "logs": "twenty app logs",
-    "create-entity": "twenty app add",
-    "help": "twenty --help"
+    "twenty": "twenty"
   }
 }
 ```
 
-يمكنك الآن تشغيل الأوامر نفسها عبر Yarn، مثل `yarn app:dev` و`yarn app:sync`، إلخ.
+الآن يمكنك تشغيل جميع الأوامر عبر `yarn twenty <command>`، مثلًا: `yarn twenty app:dev`، `yarn twenty help`، إلخ.
 
 ## استكشاف الأخطاء وإصلاحها
 
-* أخطاء المصادقة: شغّل `yarn auth:login` وتأكد من أن مفتاح واجهة برمجة التطبيقات لديك يمتلك الأذونات المطلوبة.
+* أخطاء المصادقة: شغّل `yarn twenty auth:login` وتأكد من أن مفتاح واجهة برمجة التطبيقات لديك يمتلك الأذونات المطلوبة.
 * يتعذّر الاتصال بالخادم: تحقق من عنوان URL لواجهة البرمجة وأن خادم Twenty قابل للوصول.
-* الأنواع أو العميل مفقود/قديم: شغّل `yarn app:generate` ثم `yarn app:dev`.
-* وضع التطوير لا يزامن: تأكد من أن `yarn app:dev` قيد التشغيل وأن التغييرات ليست متجاهلة من بيئتك.
+* الأنواع أو العميل مفقود/قديم: أعد تشغيل `yarn twenty app:dev` — فهو ينشئ العميل مضبوط الأنواع بشكل تلقائي.
+* وضع التطوير لا يزامن: تأكد من أن `yarn twenty app:dev` قيد التشغيل وأن التغييرات ليست متجاهلة من بيئتك.
 
 قناة المساعدة على Discord: https://discord.com/channels/1130383047699738754/1130386664812982322

packages/twenty-docs/l/ar/developers/self-host/capabilities/setup.mdx

@@ -292,19 +292,19 @@ yarn command:prod cron:workflow:automated-cron-trigger
   **وضع بيئي فقط:** إذا كنت قد ضبطت `IS_CONFIG_VARIABLES_IN_DB_ENABLED=false`، فأضف هذه المتغيرات إلى ملف `.env` الخاص بك بدلاً من ذلك.
 </Warning>
 
-## وظائف بلا خادم
+## الوظائف المنطقية
 
-تدعم Twenty وظائف بلا خادم لعمليات سير العمل والمنطق المخصص. يتم تكوين بيئة التنفيذ عبر متغير البيئة `SERVERLESS_TYPE`.
+تدعم Twenty الوظائف المنطقية لعمليات سير العمل والمنطق المخصص. يتم تكوين بيئة التنفيذ عبر متغير البيئة `SERVERLESS_TYPE`.
 
 <Warning>
-  **ملاحظة أمنية:** يقوم برنامج التشغيل المحلي لوظائف بلا خادم (`SERVERLESS_TYPE=LOCAL`) بتشغيل الشيفرة مباشرةً على المضيف ضمن عملية Node.js من دون عزل. يجب استخدامه فقط للشيفرة الموثوقة أثناء التطوير. بالنسبة لعمليات النشر الإنتاجية التي تتعامل مع شيفرة غير موثوق بها، نوصي بشدة باستخدام `SERVERLESS_TYPE=LAMBDA` أو `SERVERLESS_TYPE=DISABLED`.
+  **ملاحظة أمنية:** يقوم برنامج التشغيل المحلي (`SERVERLESS_TYPE=LOCAL`) بتشغيل الشيفرة مباشرةً على المضيف ضمن عملية Node.js من دون عزل. يجب استخدامه فقط للشيفرة الموثوقة أثناء التطوير. بالنسبة لعمليات النشر الإنتاجية التي تتعامل مع شيفرة غير موثوق بها، نوصي بشدة باستخدام `SERVERLESS_TYPE=LAMBDA` أو `SERVERLESS_TYPE=DISABLED`.
 </Warning>
 
 ### برامج التشغيل المتاحة
 
 | برنامج التشغيل | متغير البيئة               | حالة الاستخدام                  | مستوى الأمان                  |
 | -------------- | -------------------------- | ------------------------------- | ----------------------------- |
-| معطل           | `SERVERLESS_TYPE=DISABLED` | تعطيل وظائف بلا خادم بالكامل    | غير متاح                      |
+| معطل           | `SERVERLESS_TYPE=DISABLED` | تعطيل الوظائف المنطقية بالكامل  | غير متاح                      |
 | محلي           | `SERVERLESS_TYPE=LOCAL`    | بيئات التطوير والبيئات الموثوقة | منخفض (من دون عزل)            |
 | Lambda         | `SERVERLESS_TYPE=LAMBDA`   | الإنتاج مع شيفرة غير موثوق بها  | مرتفع (عزل على مستوى الأجهزة) |
 
@@ -326,12 +326,12 @@ SERVERLESS_LAMBDA_ACCESS_KEY_ID=your-access-key
 SERVERLESS_LAMBDA_SECRET_ACCESS_KEY=your-secret-key
 ```
 
-**لتعطيل وظائف بلا خادم:**
+**لتعطيل الوظائف المنطقية:**
 
 ```bash
 SERVERLESS_TYPE=DISABLED
 ```
 
 <Note>
-  عند استخدام `SERVERLESS_TYPE=DISABLED`، ستؤدي أي محاولة لتنفيذ وظيفة بلا خادم إلى إرجاع خطأ. يكون هذا مفيدًا إذا كنت ترغب في تشغيل Twenty من دون قدرات وظائف بلا خادم.
+  عند استخدام `SERVERLESS_TYPE=DISABLED`، ستؤدي أي محاولة لتنفيذ وظيفة منطقية إلى إرجاع خطأ. يكون هذا مفيدًا إذا كنت ترغب في تشغيل Twenty من دون إمكانات الوظائف المنطقية.
 </Note>

packages/twenty-docs/l/ar/user-guide/ai/overview.mdx

@@ -59,4 +59,4 @@ description: ميزات مدعومة بالذكاء الاصطناعي قادم
 سنحدّث هذا القسم عندما تصبح ميزات الذكاء الاصطناعي متاحة. وفي هذه الأثناء:
 
 * تابع [GitHub](https://github.com/twentyhq/twenty) للاطّلاع على تحديثات التطوير
-* انضم إلى [Discord](https://discord.gg/twenty) لمشاركة الملاحظات وطلبات الميزات
+* انضم إلى [Discord](https://discord.gg/UfGNZJfAG6) لمشاركة الملاحظات وطلبات الميزات

packages/twenty-docs/l/ar/user-guide/data-model/capabilities/relation-fields.mdx

@@ -39,12 +39,16 @@ description: اربط السجلات عبر كائنات مختلفة باستخ
 
 **مثال:** يمكن ربط العديد من الأشخاص بالعديد من المشاريع، والعكس صحيح.
 
-<Warning>
-  **متعدد-إلى-متعدد غير مدعوم بعد.**
+تستخدم العلاقات من نوع متعدد إلى متعدد نمط **كائن ربط**: كائن وسيط يربط بين الجانبين. باستخدام ميزة علاقة الربط، تعرض Twenty السجلات المرتبطة النهائية مباشرةً، مع إخفاء الكائن الوسيط من واجهة المستخدم.
 
-  هذا النوع من العلاقات مُخطّط للنصف الأول من عام 2026. كحل بديل، أنشئ كائنًا وسيطًا "junction" (مثال: "Project Assignments") لديه علاقات من نوع متعدد-إلى-واحد مع كلا الكائنين.
+<img src="/images/user-guide/fields/junction-relation-diagram.png" style={{width:'100%'}} />
+
+<Warning>
+  **ميزة المختبر**: يجب تمكين علاقات الربط في **الإعدادات → التحديثات → المختبر** قبل الاستخدام.
 </Warning>
 
+راجع [كيفية إنشاء علاقات متعدد-إلى-متعدد](/l/ar/user-guide/data-model/how-tos/create-many-to-many-relations) للحصول على دليل كامل خطوة بخطوة.
+
 ## إنشاء حقل علاقة
 
 1. اذهب إلى **الإعدادات → نموذج البيانات**

packages/twenty-docs/l/ar/user-guide/data-model/how-tos/create-many-to-many-relations.mdx

@@ -0,0 +1,180 @@
+---
+title: إنشاء علاقات متعدد-إلى-متعدد
+description: اربط السجلات حيث يمكن ربط عناصر كثيرة على كلا الجانبين معًا باستخدام كائنات الربط.
+---
+
+تتيح علاقات متعدد-إلى-متعدد ربط سجلات متعددة على كلا الجانبين. على سبيل المثال: يمكن للعديد من الأشخاص العمل على العديد من المشاريع، ويمكن لكل مشروع أن يضم العديد من الأشخاص.
+
+<Warning>
+  **ميزة المختبر**: علاقات الربط متاحة حاليًا في المختبر. فعِّلها في **الإعدادات → التحديثات → المختبر** قبل اتباع هذا الدليل.
+</Warning>
+
+<Note>
+  تتطلب هذه الميزة أيضًا تفعيل **الوضع المتقدم** (زر التبديل في أسفل يمين صفحة الإعدادات).
+</Note>
+
+## متى نستخدم علاقات متعدد-إلى-متعدد
+
+استخدم علاقات متعدد-إلى-متعدد عندما يمكن لكل جانب من العلاقة أن يحتوي على عدة ارتباطات:
+
+| العلاقة            | مثال                                                                  |
+| ------------------ | --------------------------------------------------------------------- |
+| الأشخاص ↔ المشاريع | قد يعمل الشخص على عدة مشاريع؛ ويضم المشروع عدة أعضاء فريق             |
+| الشركات ↔ الوسوم   | يمكن أن تحتوي الشركة على عدة وسوم؛ ويمكن أن ينطبق الوسم على عدة شركات |
+| المنتجات ↔ الطلبات | يمكن أن يوجد المنتج في عدة طلبات؛ ويحتوي الطلب على عدة منتجات         |
+
+## كيف يعمل
+
+تستخدم Twenty نمط **كائن الربط** لعلاقات متعدد-إلى-متعدد. يوضع كائن الربط بين كائنين ويحتفظ بالارتباطات:
+
+```
+People ←→ Project Assignments ←→ Projects
+```
+
+يحتوي كائن **تعيينات المشروع** (كائن ربط) على:
+
+* علاقة مع الأشخاص (متعدد-إلى-واحد)
+* علاقة مع المشاريع (متعدد-إلى-واحد)
+
+عند تفعيل مفتاح علاقة الربط، تعرض Twenty السجلات المرتبطة مباشرةً بدلًا من إظهار سجلات كائن الربط الوسيطة.
+
+## المتطلبات الأساسية
+
+1. **تفعيل علاقات الربط في المختبر**: انتقل إلى **الإعدادات → التحديثات → المختبر** وفعِّل **علاقات الربط**
+2. **فعِّل الوضع المتقدم**: شغِّل **الوضع المتقدم** من أسفل يمين الشريط الجانبي لصفحة الإعدادات
+3. خطِّط نموذج البيانات الخاص بك:
+   * ما الكائنان اللذان ستربطهما؟
+   * ما الاسم الذي ينبغي أن يُطلق على كائن الربط؟
+
+## الخطوة 1: إنشاء كائن الربط
+
+أولًا، أنشئ الكائن الوسيط الذي سيحتفظ بالارتباطات.
+
+1. اذهب إلى **الإعدادات → نموذج البيانات**
+2. انقر **+ كائن جديد**
+3. سمِّه تسمية وصفية (مثلًا: "تعيين مشروع"، "عضو فريق"، "طلب منتج")
+4. انقر على **حفظ**
+
+<Tip>
+  **اتفاقية التسمية**: استخدم اسمًا يصف العلاقة، مثل "تعيين مشروع" أو "عضوية الفريق". هذا يجعل نموذج البيانات أسهل في الفهم.
+</Tip>
+
+## الخطوة 2: إنشاء علاقات من كائن الربط
+
+أضِف حقول علاقة من كائن الربط إلى كلا الكائنين اللذين تريد ربطهما.
+
+### العلاقة الأولى (كائن الربط → الكائن A)
+
+1. حدِّد كائن الربط في **الإعدادات → نموذج البيانات**
+2. انقر **+ إضافة حقل**
+3. اختر **العلاقة** كنوع الحقل
+4. اختر الكائن الأول (مثلًا، "الأشخاص")
+5. عيِّن نوع العلاقة إلى **متعدد-إلى-واحد** (يمكن لعديد من التعيينات الارتباط بشخص واحد)
+6. قم بتسمية الحقول:
+   * الحقل على كائن الربط: مثلًا، "شخص"
+   * الحقل على الأشخاص: مثلًا، "تعيينات المشروع"
+7. انقر على **حفظ**
+
+### العلاقة الثانية (كائن الربط → الكائن B)
+
+1. وأنت ما زلت في كائن الربط، انقر **+ إضافة حقل**
+2. اختر **العلاقة** كنوع الحقل
+3. اختر الكائن الثاني (مثلًا، "المشاريع")
+4. عيِّن نوع العلاقة إلى **متعدد-إلى-واحد**
+5. قم بتسمية الحقول:
+   * الحقل على كائن الربط: مثلًا، "مشروع"
+   * الحقل على المشاريع: مثلًا، "أعضاء الفريق"
+6. انقر على **حفظ**
+
+## الخطوة 3: ضبط عرض علاقة الربط
+
+قم الآن بضبط كائنات المصدر لعرض السجلات المرتبطة مباشرةً، مع تجاوز كائن الربط الوسيط.
+
+1. اذهب إلى **الإعدادات → نموذج البيانات**
+2. اختر الكائن الأول (مثلًا، "الأشخاص")
+3. اعثر على حقل العلاقة الذي يشير إلى كائن الربط (مثلًا، "تعيينات المشروع")
+4. انقر لتحرير الحقل
+5. فعّل **"هذه علاقة بكائن ربط"**
+6. حدِّد **العلاقة الهدف** (مثلًا، "مشروع" — الحقل على كائن الربط الذي يشير إلى الجانب الآخر)
+7. انقر على **حفظ**
+
+{/* TODO: Add image
+<img src="/images/user-guide/fields/junction-relation-toggle.png" style={{width:'100%'}}/>
+*/}
+
+كرِّر على الكائن الآخر:
+
+1. اختر "المشاريع" في نموذج البيانات
+2. حرِّر حقل العلاقة "أعضاء الفريق"
+3. فعّل مفتاح الربط
+4. حدِّد "شخص" كالعلاقة الهدف
+5. حفظ
+
+## النتيجة
+
+بعد التكوين:
+
+* في سجل **شخص**، يعرض حقل "تعيينات المشروع" **المشاريع** مباشرةً (وليس سجلات التعيين)
+* في سجل **مشروع**، يعرض حقل "أعضاء الفريق" **الأشخاص** مباشرةً
+
+لا يزال كائن الربط موجودًا ويخزّن الارتباطات، لكن واجهة المستخدم تقدّم عرضًا أوضح لعلاقات متعدد-إلى-متعدد.
+
+## مثال: الأشخاص ↔ المشاريع
+
+إليك شرحًا كاملًا خطوة بخطوة:
+
+### إنشاء كائن الربط
+
+* الاسم: **تعيين مشروع**
+* الوصف: "يربط الأشخاص بالمشاريع التي يعملون عليها"
+
+### إضافة علاقات
+
+1. **تعيين مشروع → الأشخاص**
+   * النوع: متعدد-إلى-واحد
+   * الحقل على التعيين: "شخص"
+   * الحقل على الأشخاص: "تعيينات المشروع"
+
+2. **تعيين مشروع → المشاريع**
+   * النوع: متعدد-إلى-واحد
+   * الحقل على التعيين: "مشروع"
+   * الحقل على المشاريع: "أعضاء الفريق"
+
+### ضبط عرض علاقة الربط
+
+1. على كائن **الأشخاص**:
+   * حرِّر حقل "تعيينات المشروع"
+   * فعّل مفتاح الربط
+   * الهدف: "مشروع"
+
+2. على كائن **المشاريع**:
+   * حرِّر حقل "أعضاء الفريق"
+   * فعّل مفتاح الربط
+   * الهدف: "شخص"
+
+### استخدمه
+
+* افتح سجل شخص → سترى مشاريعه مباشرةً
+* افتح سجل مشروع → سترى أعضاء الفريق مباشرةً
+* أنشئ ارتباطات جديدة من أي جانب
+
+## إضافة بيانات إضافية إلى الارتباطات
+
+نظرًا لأن كائن الربط كائن حقيقي، يمكنك إضافة حقول مخصصة لتخزين معلومات حول العلاقة:
+
+* **الدور**: "مطوّر"، "مصمّم"، "مدير"
+* **تاريخ البدء**: متى انضمّوا إلى المشروع
+* **الساعات المخصّصة**: عدد الساعات الأسبوعية على هذا المشروع
+
+للوصول إلى هذه البيانات، انتقل إلى كائن الربط مباشرةً أو استعلم عنها عبر واجهة API.
+
+## القيود
+
+* **استيراد/تصدير CSV**: لا يُدعم استيراد علاقات متعدد-إلى-متعدد مباشرةً. بدلًا من ذلك، استورد السجلات إلى كائن الربط.
+* **عوامل التصفية**: قد تكون خيارات التصفية حسب علاقات متعدد-إلى-متعدد محدودة.
+
+## ذات صلة
+
+* [حقول العلاقات](/l/ar/user-guide/data-model/capabilities/relation-fields) — شرح أنواع العلاقات
+* [إنشاء كائنات مخصصة](/l/ar/user-guide/data-model/how-tos/create-custom-objects) — كيفية إنشاء الكائنات
+* [إنشاء حقول العلاقات](/l/ar/user-guide/data-model/how-tos/create-relation-fields) — إعداد العلاقات الأساسي

packages/twenty-docs/l/ar/user-guide/getting-started/capabilities/glossary.mdx

@@ -9,7 +9,7 @@ description: تعرّف على المصطلحات الأساسية المستخ
 
 ## التطبيقات
 
-التطبيقات هي امتدادات مخصّصة مُنشأة على شكل شيفرة يمكنها تعريف نماذج البيانات ووظائف بدون خوادم. تمكّن المطورين من إنشاء تخصيصات قابلة لإعادة الاستخدام يمكن نشرها عبر مساحات عمل متعددة.
+التطبيقات هي امتدادات مخصّصة مُنشأة على شكل شيفرة يمكنها تعريف نماذج البيانات والوظائف المنطقية. تمكّن المطورين من إنشاء تخصيصات قابلة لإعادة الاستخدام يمكن نشرها عبر مساحات عمل متعددة.
 
 ## إجراءات الكود
 

packages/twenty-docs/l/ar/user-guide/workflows/capabilities/send-emails-from-workflows.mdx

@@ -136,7 +136,7 @@ image: /images/user-guide/workflows/workflow.png
 | **تأكيدات الفعاليات**                   | تفاصيل الفعالية أو جدول الأعمال  |
 
 <Note>
-  المرفقات ثابتة—يتم إرسال الملف نفسه إلى جميع المستلمين. بالنسبة للمستندات الديناميكية (مثل عروض الأسعار المخصصة)، أنشئ الملفات وأرفقها باستخدام [وظيفة بدون خادم](/l/ar/user-guide/workflows/how-tos/connect-to-other-tools/generate-pdf-from-twenty).
+  المرفقات ثابتة—يتم إرسال الملف نفسه إلى جميع المستلمين. بالنسبة للمستندات الديناميكية (مثل عروض الأسعار المخصصة)، أنشئ الملفات وأرفقها باستخدام [وظيفة منطقية](/l/ar/user-guide/workflows/how-tos/connect-to-other-tools/generate-pdf-from-twenty).
 </Note>
 
 ## أفضل الممارسات

packages/twenty-docs/l/ar/user-guide/workflows/capabilities/workflow-actions.mdx

@@ -256,7 +256,7 @@ import { VimeoEmbed } from '/snippets/vimeo-embed.mdx';
 * اختبر الكود مباشرة في الخطوة
 
 <Note>
-  إذا كنت بحاجة إلى استخدام مفاتيح API خارجية في كودك، فيجب إدخالها مباشرةً في جسم الدالة. لا يمكنك تكوين مفاتيح API في مكان آخر والإشارة إليها في الدالة عديمة الخادم.
+  إذا كنت بحاجة إلى استخدام مفاتيح API خارجية في كودك، فيجب إدخالها مباشرةً في جسم الدالة. لا يمكنك تكوين مفاتيح API في مكان آخر والإشارة إليها في الدالة المنطقية.
 </Note>
 
 <Tip>

packages/twenty-docs/l/ar/user-guide/workflows/how-tos/connect-to-other-tools/generate-pdf-from-twenty.mdx

@@ -7,7 +7,7 @@ description: أنشئ سير عمل لإنشاء ملف PDF (مثل عرض سع
 
 ## نظرة عامة
 
-يستخدم سير العمل هذا **المحفز اليدوي** بحيث يتمكن المستخدمون من إنشاء ملف PDF عند الطلب لأي سجل محدد. **وظيفة بلا خادم** تتولى ما يلي:
+يستخدم سير العمل هذا **المحفز اليدوي** بحيث يتمكن المستخدمون من إنشاء ملف PDF عند الطلب لأي سجل محدد. تتولى **الوظيفة المنطقية** ما يلي:
 
 1. تنزيل ملف PDF من عنوان URL (من خدمة إنشاء PDF)
 2. رفع الملف إلى Twenty
@@ -17,7 +17,7 @@ description: أنشئ سير عمل لإنشاء ملف PDF (مثل عرض سع
 
 قبل إعداد سير العمل:
 
-1. **أنشئ مفتاح API**: انتقل إلى **الإعدادات → واجهات برمجة التطبيقات** ثم أنشئ مفتاح API جديدًا. ستحتاج إلى هذا الرمز المميز للوظيفة بلا خادم.
+1. **أنشئ مفتاح API**: انتقل إلى **الإعدادات → واجهات برمجة التطبيقات** ثم أنشئ مفتاح API جديدًا. ستحتاج إلى هذا الرمز المميز للوظيفة المنطقية.
 2. **قم بإعداد خدمة إنشاء PDF** (اختياري): إذا كنت تريد إنشاء ملفات PDF ديناميكيًا (مثل عروض الأسعار)، فاستخدم خدمة مثل Carbone أو PDFMonkey أو DocuSeal لإنشاء ملف PDF والحصول على رابط تنزيل.
 
 ## إعداد خطوة بخطوة
@@ -32,9 +32,9 @@ description: أنشئ سير عمل لإنشاء ملف PDF (مثل عرض سع
   باستخدام المحفز اليدوي، يمكن للمستخدمين تشغيل سير العمل هذا عبر زر يظهر في أعلى اليمين عند تحديد سجل، وذلك لإنشاء ملف PDF وإرفاقه.
 </Tip>
 
-### الخطوة 2: إضافة وظيفة بلا خادم
+### الخطوة 2: إضافة وظيفة منطقية
 
-1. أضف إجراء **وظيفة بلا خادم**
+1. أضف إجراء **Code** (وظيفة منطقية)
 2. أنشئ وظيفة جديدة باستخدام الكود أدناه
 3. قم بتهيئة معلمات الإدخال
 
@@ -45,10 +45,10 @@ description: أنشئ سير عمل لإنشاء ملف PDF (مثل عرض سع
 | `companyId` | `{{trigger.object.id}}` |
 
 <Note>
-  إذا كنت تُرفق إلى كائن مختلف (شخص، فرصة، إلخ)، فأعد تسمية المعلمة وفقًا لذلك (مثلًا، `personId`، `opportunityId`) وحدث الوظيفة بلا خادم.
+  إذا كنت تُرفِقه بكائن مختلف (شخص، فرصة، إلخ)، فأعد تسمية المعلمة وفقًا لذلك (مثلًا، `personId`، `opportunityId`) وحدّث الوظيفة المنطقية.
 </Note>
 
-#### كود الوظيفة بلا خادم
+#### كود الوظيفة المنطقية
 
 ```typescript
 export const main = async (
@@ -172,7 +172,7 @@ export const main = async (
 إذا كنت تستخدم خدمة إنشاء PDF، يمكنك:
 
 1. أولًا، أنشئ إجراء طلب HTTP لإنشاء ملف PDF
-2. مرّر رابط ملف PDF المُعاد إلى الوظيفة بلا خادم كمعلمة
+2. مرّر رابط ملف PDF المُعاد إلى الوظيفة المنطقية كمعلمة
 
 ```typescript
 export const main = async (
@@ -211,7 +211,7 @@ export const main = async (
 * **DocuSeal** - منصة أتمتة المستندات
 * **Documint** - إنشاء مستندات يعتمد على واجهة برمجة التطبيقات أولًا
 
-توفر كل خدمة واجهة برمجة تطبيقات تُرجع رابط ملف PDF، ويمكنك بعدها تمريره إلى الوظيفة بلا خادم.
+توفر كل خدمة واجهة برمجة تطبيقات تُرجع رابط ملف PDF، ويمكنك بعدها تمريره إلى الوظيفة المنطقية.
 
 ## استكشاف الأخطاء وإصلاحها
 
@@ -224,5 +224,5 @@ export const main = async (
 ## ذات صلة
 
 * [مشغلات سير العمل](/l/ar/user-guide/workflows/capabilities/workflow-triggers)
-* [وظائف بلا خادم](/l/ar/user-guide/workflows/capabilities/workflow-actions#serverless-function)
+* [الوظائف المنطقية](/l/ar/user-guide/workflows/capabilities/workflow-actions#code)
 * [إنشاء عرض سعر أو فاتورة من Twenty](/l/ar/user-guide/workflows/how-tos/connect-to-other-tools/generate-quote-or-invoice-from-twenty)

packages/twenty-docs/l/ar/user-guide/workflows/how-tos/need-more-help/workflows-faq.mdx

@@ -131,7 +131,7 @@ description: الأسئلة الشائعة حول سير العمل في Twenty.
   </Accordion>
 
   <Accordion title="ما أقصى وقت تنفيذ لإجراءات Code؟">
-    إجراءات Code (دوال بلا خادم) لديها **مهلة افتراضية قدرها 5 دقائق** (300 ثانية).
+    إجراءات Code (دوال منطقية) لديها **مهلة افتراضية قدرها 5 دقائق** (300 ثانية).
 
     أقصى مهلة يمكن ضبطها هي **15 دقيقة** (900 ثانية).
 

packages/twenty-docs/l/cs/developers/contribute/capabilities/local-setup.mdx

@@ -169,6 +169,13 @@ Všechny příkazy v následujících krocích byste měli provádět z kořene
 
     Tím vytvoříte superuživatelskou roli pojmenovanou `postgres` s přístupovými právy.
 
+    ```bash
+    Jméno role | Vlastnosti  | Členem
+    -----------+-------------+-----------
+    postgres  | Superuživatel   | {}
+    john      | Superuživatel   | {}
+    ```
+
     **Možnost 2:** Pokud máte nainstalován docker:
 
     ```bash

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

@@ -9,18 +9,15 @@ description: Vytvářejte a spravujte přizpůsobení Twenty jako kód.
 
 ## Co jsou aplikace?
 
-Aplikace vám umožňují vytvářet a spravovat přizpůsobení Twenty **jako kód**. Místo konfigurace všeho přes uživatelské rozhraní definujete v kódu svůj datový model a serverless funkce — což zrychluje vývoj, údržbu i nasazování do více pracovních prostorů.
+Aplikace vám umožňují vytvářet a spravovat přizpůsobení Twenty **jako kód**. Místo konfigurace všeho přes uživatelské rozhraní definujete v kódu svůj datový model a logické funkce — což zrychluje vývoj, údržbu i nasazování do více pracovních prostorů.
 
 **Co můžete dělat už dnes:**
 
 * Definujte vlastní objekty a pole jako kód (spravovaný datový model)
-* Vytvářejte serverless funkce s vlastními spouštěči
+* Vytvářejte logické funkce s vlastními spouštěči
+* Definujte dovednosti agentů AI
 * Nasazujte stejnou aplikaci do více pracovních prostorů
 
-**Již brzy:**
-
-* Vlastní rozvržení a komponenty uživatelského rozhraní
-
 ## Předpoklady
 
 * Node.js 24+ a Yarn 4
@@ -31,7 +28,7 @@ Aplikace vám umožňují vytvářet a spravovat přizpůsobení Twenty **jako k
 Vytvořte novou aplikaci pomocí oficiálního scaffolderu, poté se ověřte a začněte vyvíjet:
 
 ```bash filename="Terminal"
-# Vygenerujte kostru nové aplikace
+# Vygenerujte kostru nové aplikace (ve výchozím nastavení zahrnuje všechny příklady)
 npx create-twenty-app@latest my-twenty-app
 cd my-twenty-app
 
@@ -40,35 +37,45 @@ corepack enable
 yarn install
 
 # Přihlaste se pomocí svého API klíče (budete vyzváni)
-yarn auth:login
+yarn twenty auth:login
 
 # Spusťte vývojový režim: automaticky synchronizuje místní změny s vaším pracovním prostorem
-yarn app:dev
+yarn twenty app:dev
+```
+
+Nástroj pro generování kostry podporuje tři režimy pro řízení toho, které ukázkové soubory jsou zahrnuty:
+
+```bash filename="Terminal"
+# Výchozí (úplný): všechny příklady (objekt, pole, logická funkce, front-endová komponenta, zobrazení, položka navigační nabídky, dovednost)
+npx create-twenty-app@latest my-app
+
+# Minimální: pouze základní soubory (application-config.ts a default-role.ts)
+npx create-twenty-app@latest my-app --minimal
+
+# Interaktivní: vyberte, které příklady zahrnout
+npx create-twenty-app@latest my-app --interactive
 ```
 
 Odtud můžete:
 
 ```bash filename="Terminal"
-# Add a new entity to your application (guided)
-yarn app:create-entity
+# Přidejte do vaší aplikace novou entitu (s průvodcem)
+yarn twenty entity:add
 
-# Generate a typed Twenty client and workspace entity types
-yarn app:generate
+# Sledujte logy funkcí vaší aplikace
+yarn twenty function:logs
 
-# Run a one‑time sync (instead of watch mode)
-yarn app:sync
+# Spusťte funkci podle názvu
+yarn twenty function:execute -n my-function -p '{"name": "test"}'
 
-# Watch your application's functions logs
-yarn function:logs
+# Spusťte postinstalační funkci
+yarn twenty function:execute --postInstall
 
-# Execute a function by name
-yarn function:execute -n my-function -p '{"name": "test"}'
+# Odinstalujte aplikaci z aktuálního pracovního prostoru
+yarn twenty app:uninstall
 
-# Uninstall the application from the current workspace
-yarn app:uninstall
-
-# Display commands' help
-yarn app:help
+# Zobrazte nápovědu k příkazům
+yarn twenty help
 ```
 
 Viz také: referenční stránky CLI pro [create-twenty-app](https://www.npmjs.com/package/create-twenty-app) a [twenty-sdk CLI](https://www.npmjs.com/package/twenty-sdk).
@@ -80,9 +87,9 @@ Když spustíte `npx create-twenty-app@latest my-twenty-app`, scaffolder:
 * Zkopíruje minimální základní aplikaci do `my-twenty-app/`
 * Přidá lokální závislost `twenty-sdk` a konfiguraci pro Yarn 4
 * Vytvoří konfigurační soubory a skripty napojené na `twenty` CLI
-* Vygeneruje výchozí konfiguraci aplikace a výchozí roli funkcí
+* Vygeneruje základní soubory (konfigurace aplikace, výchozí role funkcí, postinstalační funkce) a k nim ukázkové soubory podle zvoleného režimu generování kostry
 
-Čerstvě vytvořená aplikace vypadá takto:
+Čerstvě vygenerovaná aplikace s výchozím režimem `--exhaustive` vypadá takto:
 
 ```text filename="my-twenty-app/"
 my-twenty-app/
@@ -96,86 +103,81 @@ my-twenty-app/
   eslint.config.mjs
   tsconfig.json
   README.md
+  public/                           # Složka s veřejnými prostředky (obrázky, písma apod.)
   src/
-    app/
-      application.config.ts     # Povinné - hlavní konfigurace aplikace
-      default-function.role.ts  # Výchozí role pro serverless funkce
-      // vaše entity (*.object.ts, *.function.ts, *.role.ts)
-    utils/                      # Volitelné - implementace handlerů a nástroje
+  ├── application-config.ts           # Povinné – hlavní konfigurace aplikace
+  ├── roles/
+  │   └── default-role.ts               # Výchozí role pro logické funkce
+  ├── objects/
+  │   └── example-object.ts             # Ukázková definice vlastního objektu
+  ├── fields/
+  │   └── example-field.ts              # Ukázková samostatná definice pole
+  ├── logic-functions/
+  │   ├── hello-world.ts                # Ukázková logická funkce
+  │   └── post-install.ts               # Postinstalační logická funkce
+  ├── front-components/
+  │   └── hello-world.tsx               # Ukázková front-endová komponenta
+  ├── views/
+  │   └── example-view.ts                # Ukázková definice uloženého zobrazení
+  ├── navigation-menu-items/
+  │   └── example-navigation-menu-item.ts # Ukázkový odkaz postranní navigace
+  └── skills/
+      └── example-skill.ts                # Ukázková definice dovednosti agenta AI
 ```
 
-### Konvence před konfigurací
-
-Aplikace používají přístup **konvence před konfigurací**, kde jsou entity detekovány podle přípony souboru. To umožňuje flexibilní organizaci ve složce `src/app/`:
-
-| Přípona souboru | Typ entity                 |
-| --------------- | -------------------------- |
-| `*.object.ts`   | Definice vlastních objektů |
-| `*.function.ts` | Definice serverless funkcí |
-| `*.role.ts`     | Definice rolí              |
-
-### Podporované uspořádání složek
-
-Entity můžete uspořádat podle některého z těchto vzorů:
-
-**Tradiční (podle typu):**
-
-```text
-src/app/
-├── application.config.ts
-├── objects/
-│   └── postCard.object.ts
-├── functions/
-│   └── createPostCard.function.ts
-└── roles/
-    └── admin.role.ts
-```
-
-**Podle funkcí:**
-
-```text
-src/app/
-├── application.config.ts
-└── post-card/
-    ├── postCard.object.ts
-    ├── createPostCard.function.ts
-    └── postCardAdmin.role.ts
-```
-
-**Plochá:**
-
-```text
-src/app/
-├── application.config.ts
-├── postCard.object.ts
-├── createPostCard.function.ts
-└── admin.role.ts
-```
+S volbou `--minimal` se vytvoří pouze základní soubory (`application-config.ts`, `roles/default-role.ts` a `logic-functions/post-install.ts`). S volbou `--interactive` si vyberete, které ukázkové soubory chcete zahrnout.
 
 V kostce:
 
-* **package.json**: Deklaruje název aplikace, verzi, engines (Node 24+, Yarn 4) a přidává `twenty-sdk` plus skripty jako `dev`, `sync`, `generate`, `create-entity`, `logs`, `uninstall` a `auth`, které delegují na lokální `twenty` CLI.
+* **package.json**: Deklaruje název aplikace, verzi, engines (Node 24+, Yarn 4) a přidává `twenty-sdk` plus skript `twenty`, který deleguje na lokální `twenty` CLI. Spusťte `yarn twenty help` pro výpis všech dostupných příkazů.
 * **.gitignore**: Ignoruje běžné artefakty jako `node_modules`, `.yarn`, `generated/` (typovaný klient), `dist/`, `build/`, složky s coverage, logy a soubory `.env*`.
 * **yarn.lock**, **.yarnrc.yml**, **.yarn/**: Zamykají a konfigurují nástrojový řetězec Yarn 4 používaný projektem.
 * **.nvmrc**: Fixuje verzi Node.js požadovanou projektem.
 * **eslint.config.mjs** a **tsconfig.json**: Poskytují lintování a konfiguraci TypeScriptu pro zdrojové soubory vaší aplikace v TypeScriptu.
 * **README.md**: Krátké README v kořeni aplikace se základními pokyny.
-* **src/app/**: Hlavní místo, kde definujete svou aplikaci jako kód:
-  * `application.config.ts`: Globální konfigurace vaší aplikace (metadata a napojení za běhu). Viz „Konfigurace aplikace“ níže.
-  * `*.role.ts`: Definice rolí používané vašimi serverless funkcemi. Viz „Výchozí role funkce“ níže.
-  * `*.object.ts`: Definice vlastních objektů.
-  * `*.function.ts`: Definice serverless funkcí.
-* **src/utils/**: Volitelná složka pro implementace obslužných funkcí a pomocné nástroje.
+* **public/**: Složka pro ukládání veřejných prostředků (obrázky, písma, statické soubory), které bude vaše aplikace poskytovat. Soubory umístěné zde se během synchronizace nahrají a jsou za běhu dostupné.
+* **src/**: Hlavní místo, kde definujete svou aplikaci jako kód
+
+### Detekce entit
+
+SDK detekuje entity analýzou vašich souborů TypeScript a hledá volání **`export default define<Entity>({...})`**. Každý typ entity má odpovídající pomocnou funkci exportovanou z `twenty-sdk`:
+
+| Pomocná funkce               | Typ entity                            |
+| ---------------------------- | ------------------------------------- |
+| `defineObject()`             | Definice vlastních objektů            |
+| `defineLogicFunction()`      | Definice logických funkcí             |
+| `defineFrontComponent()`     | Definice frontendových komponent      |
+| `defineRole()`               | Definice rolí                         |
+| `defineField()`              | Rozšíření polí u existujících objektů |
+| `defineView()`               | Definice uložených zobrazení          |
+| `defineNavigationMenuItem()` | Definice položek navigační nabídky    |
+| `defineSkill()`              | Definice dovedností agenta AI         |
+
+<Note>
+  **Pojmenování souborů je flexibilní.** Detekce entit je založená na AST — SDK prochází vaše zdrojové soubory a hledá vzor `export default define<Entity>({...})`. Soubory a složky můžete organizovat, jak chcete. Seskupování podle typu entity (např. `logic-functions/`, `roles/`) je pouze konvence pro organizaci kódu, nikoli požadavek.
+</Note>
+
+Příklad detekované entity:
+
+```typescript
+// This file can be named anything and placed anywhere in src/
+import { defineObject, FieldType } from 'twenty-sdk';
+
+export default defineObject({
+  universalIdentifier: '...',
+  nameSingular: 'postCard',
+  // ... rest of config
+});
+```
 
 Pozdější příkazy přidají další soubory a složky:
 
-* `yarn app:generate` vytvoří složku `generated/` (typovaný klient Twenty + typy pracovního prostoru).
-* `yarn app:create-entity` přidá soubory s definicemi entit do `src/app/` pro vaše vlastní objekty, funkce nebo role.
-  l
+* `yarn twenty app:dev` automaticky vygeneruje typovaného klienta API v `node_modules/twenty-sdk/generated` (typovaný klient Twenty + typy pracovního prostoru).
+* `yarn twenty entity:add` přidá soubory s definicemi entit do `src/` pro vaše vlastní objekty, funkce, frontové komponenty, role, dovednosti a další.
 
 ## Ověření
 
-Při prvním spuštění `yarn auth:login` budete vyzváni k zadání:
+Při prvním spuštění `yarn twenty auth:login` budete vyzváni k zadání:
 
 * URL API (výchozí je http://localhost:3000 nebo váš aktuální profil pracovního prostoru)
 * Klíč API
@@ -186,25 +188,25 @@ Vaše přihlašovací údaje se ukládají pro jednotlivé uživatele do `~/.twe
 
 ```bash filename="Terminal"
 # Login interactively (recommended)
-yarn auth:login
+yarn twenty auth:login
 
 # Login to a specific workspace profile
-yarn auth:login --workspace my-custom-workspace
+yarn twenty auth:login --workspace my-custom-workspace
 
 # List all configured workspaces
-yarn auth:list
+yarn twenty auth:list
 
 # Switch the default workspace (interactive)
-yarn auth:switch
+yarn twenty auth:switch
 
 # Switch to a specific workspace
-yarn auth:switch production
+yarn twenty auth:switch production
 
 # Check current authentication status
-yarn auth:status
+yarn twenty auth:status
 ```
 
-Jakmile přepnete pracovní prostor pomocí `auth:switch`, všechny následující příkazy budou tento pracovní prostor používat jako výchozí. Můžete jej stále dočasně přepsat pomocí `--workspace <name>`.
+Jakmile přepnete pracovní prostor pomocí `yarn twenty auth:switch`, všechny následující příkazy budou tento pracovní prostor používat jako výchozí. Můžete jej stále dočasně přepsat pomocí `--workspace <name>`.
 
 ## Používejte zdroje SDK (typy a konfiguraci)
 
@@ -212,16 +214,21 @@ twenty-sdk poskytuje typované stavební bloky a pomocné funkce, které použí
 
 ### Pomocné funkce
 
-SDK poskytuje čtyři pomocné funkce s vestavěnou validací pro definování entit vaší aplikace:
+SDK poskytuje pomocné funkce pro definování entit vaší aplikace. Jak je popsáno v [Detekce entit](#entity-detection), musíte použít `export default define<Entity>({...})`, aby byly vaše entity detekovány:
 
-| Funkce             | Účel                                             |
-| ------------------ | ------------------------------------------------ |
-| `defineApp()`      | Konfigurace metadat aplikace                     |
-| `defineObject()`   | Definice vlastních objektů s poli                |
-| `defineFunction()` | Definice serverless funkcí s obslužnými funkcemi |
-| `defineRole()`     | Konfigurace oprávnění rolí a přístupu k objektům |
+| Funkce                       | Účel                                                              |
+| ---------------------------- | ----------------------------------------------------------------- |
+| `defineApplication()`        | Nakonfigurujte metadata aplikace (povinné, jedno na aplikaci)     |
+| `defineObject()`             | Definice vlastních objektů s poli                                 |
+| `defineLogicFunction()`      | Definice logických funkcí s obslužnými funkcemi                   |
+| `defineFrontComponent()`     | Definujte frontendové komponenty pro vlastní uživatelské rozhraní |
+| `defineRole()`               | Konfigurace oprávnění rolí a přístupu k objektům                  |
+| `defineField()`              | Rozšiřte existující objekty o další pole                          |
+| `defineView()`               | Definujte uložená zobrazení pro objekty                           |
+| `defineNavigationMenuItem()` | Definujte odkazy postranní navigace                               |
+| `defineSkill()`              | Definuje dovednosti agenta AI                                     |
 
-Tyto funkce validují vaši konfiguraci za běhu a poskytují lepší automatické doplňování v IDE a lepší typovou bezpečnost.
+Tyto funkce validují vaši konfiguraci v době sestavení a poskytují automatické doplňování v IDE a typovou bezpečnost.
 
 ### Definování objektů
 
@@ -302,79 +309,34 @@ Hlavní body:
 * Hodnota `universalIdentifier` musí být jedinečná a stabilní napříč nasazeními.
 * Každé pole vyžaduje `name`, `type`, `label` a svůj vlastní stabilní `universalIdentifier`.
 * Pole `fields` je volitelné — objekty můžete definovat i bez vlastních polí.
-* Nové objekty můžete vygenerovat pomocí `yarn app:create-entity`, který vás provede pojmenováním, poli a vztahy.
+* Nové objekty můžete vygenerovat pomocí `yarn twenty entity:add`, který vás provede pojmenováním, poli a vztahy.
 
 <Note>
-  **Základní pole jsou vytvořena automaticky.** Když definujete vlastní objekt, Twenty automaticky přidá standardní pole jako `name`, `createdAt`, `updatedAt`, `createdBy`, `position` a `deletedAt`. Nemusíte je definovat v poli `fields` — přidejte pouze svá vlastní pole.
+  **Základní pole jsou vytvořena automaticky.** Když definujete vlastní objekt, Twenty automaticky přidá standardní pole
+  jako `id`, `name`, `createdAt`, `updatedAt`, `createdBy`, `updatedBy` a `deletedAt`.
+  Nemusíte je definovat v poli `fields` — přidejte pouze svá vlastní pole.
+  Výchozí pole můžete přepsat definováním pole se stejným názvem v poli `fields`,
+  ale to se nedoporučuje.
 </Note>
 
-<Accordion title="Alternativa: Syntaxe založená na dekorátorech">
-  Objekty můžete definovat také pomocí dekorátorů TypeScriptu. Tento přístup používá třídovou syntaxi s dekorátory `@Object`, `@Field` a `@Relation`:
+### Konfigurace aplikace (application-config.ts)
 
-  ```typescript
-  import {
-    type AddressField,
-    Field,
-    FieldType,
-    type FullNameField,
-    Object,
-    OnDeleteAction,
-    Relation,
-    RelationType,
-    STANDARD_OBJECT_UNIVERSAL_IDENTIFIERS,
-  } from 'twenty-sdk';
-  import { type Note } from '../../generated';
-
-  @Object({
-    universalIdentifier: '54b589ca-eeed-4950-a176-358418b85c05',
-    nameSingular: 'postCard',
-    namePlural: 'postCards',
-    labelSingular: 'Post card',
-    labelPlural: 'Post cards',
-    description: 'A post card object',
-    icon: 'IconMail',
-  })
-  export class PostCard {
-    @Field({
-      universalIdentifier: '58a0a314-d7ea-4865-9850-7fb84e72f30b',
-      type: FieldType.TEXT,
-      label: 'Content',
-      description: "Postcard's content",
-      icon: 'IconAbc',
-    })
-    content: string;
-
-    @Relation({
-      universalIdentifier: 'c9e2b4f4-b9ad-4427-9b42-9971b785edfe',
-      type: RelationType.ONE_TO_MANY,
-      label: 'Notes',
-      icon: 'IconComment',
-      inverseSideTargetUniversalIdentifier: STANDARD_OBJECT_UNIVERSAL_IDENTIFIERS.note,
-      onDelete: OnDeleteAction.CASCADE,
-    })
-    notes: Note[];
-  }
-  ```
-
-  Poznámka: Přístup s dekorátory vyžaduje `experimentalDecorators` v konfiguraci TypeScriptu.
-</Accordion>
-
-### Konfigurace aplikace (application.config.ts)
-
-Každá aplikace má jeden soubor `application.config.ts`, který popisuje:
+Každá aplikace má jeden soubor `application-config.ts`, který popisuje:
 
 * **Identitu aplikace**: identifikátory, zobrazovaný název a popis.
 * **Jak běží její funkce**: kterou roli používají pro oprávnění.
 * **(Volitelné) proměnné**: dvojice klíč–hodnota zpřístupněné vašim funkcím jako proměnné prostředí.
+* **(Volitelná) postinstalační funkce**: logická funkce, která se spouští po instalaci aplikace.
 
-K definování konfigurace aplikace použijte `defineApp()`:
+Use `defineApplication()` to define your application configuration:
 
 ```typescript
-// src/app/application.config.ts
-import { defineApp } from 'twenty-sdk';
-import { DEFAULT_FUNCTION_ROLE_UNIVERSAL_IDENTIFIER } from './default-function.role';
+// src/application-config.ts
+import { defineApplication } from 'twenty-sdk';
+import { DEFAULT_ROLE_UNIVERSAL_IDENTIFIER } from 'src/roles/default-role';
+import { POST_INSTALL_UNIVERSAL_IDENTIFIER } from 'src/logic-functions/post-install';
 
-export default defineApp({
+export default defineApplication({
   universalIdentifier: '4ec0391d-18d5-411c-b2f3-266ddc1c3ef7',
   displayName: 'My Twenty App',
   description: 'My first Twenty app',
@@ -387,7 +349,8 @@ export default defineApp({
       isSecret: false,
     },
   },
-  functionRoleUniversalIdentifier: DEFAULT_FUNCTION_ROLE_UNIVERSAL_IDENTIFIER,
+  defaultRoleUniversalIdentifier: DEFAULT_ROLE_UNIVERSAL_IDENTIFIER,
+  postInstallLogicFunctionUniversalIdentifier: POST_INSTALL_UNIVERSAL_IDENTIFIER,
 });
 ```
 
@@ -395,11 +358,12 @@ Poznámky:
 
 * Pole `universalIdentifier` jsou deterministická ID, která vlastníte; vygenerujte je jednou a udržujte je stabilní napříč synchronizacemi.
 * `applicationVariables` se stanou proměnnými prostředí pro vaše funkce (například `DEFAULT_RECIPIENT_NAME` je dostupné jako `process.env.DEFAULT_RECIPIENT_NAME`).
-* `functionRoleUniversalIdentifier` se musí shodovat s rolí, kterou definujete ve svém souboru `*.role.ts` (viz níže).
+* `defaultRoleUniversalIdentifier` se musí shodovat se souborem role (viz níže).
+* `postInstallLogicFunctionUniversalIdentifier` (volitelné) odkazuje na logickou funkci, která se automaticky spustí po instalaci aplikace. Viz [Postinstalační funkce](#post-install-functions).
 
 #### Role a oprávnění
 
-Aplikace mohou definovat role, které zapouzdřují oprávnění k objektům a akcím ve vašem pracovním prostoru. Pole `functionRoleUniversalIdentifier` v `application.config.ts` určuje výchozí roli používanou serverless funkcemi vaší aplikace.
+Aplikace mohou definovat role, které zapouzdřují oprávnění k objektům a akcím ve vašem pracovním prostoru. Pole `defaultRoleUniversalIdentifier` v `application-config.ts` určuje výchozí roli používanou logickými funkcemi vaší aplikace.
 
 * Běhový klíč API vložený jako `TWENTY_API_KEY` je odvozen z této výchozí role funkcí.
 * Typovaný klient bude omezen oprávněními udělenými této roli.
@@ -410,14 +374,14 @@ Aplikace mohou definovat role, které zapouzdřují oprávnění k objektům a a
 Když vygenerujete novou aplikaci, CLI také vytvoří výchozí soubor role. K definování rolí s vestavěnou validací použijte `defineRole()`:
 
 ```typescript
-// src/app/default-function.role.ts
+// src/roles/default-role.ts
 import { defineRole, PermissionFlag } from 'twenty-sdk';
 
-export const DEFAULT_FUNCTION_ROLE_UNIVERSAL_IDENTIFIER =
+export const DEFAULT_ROLE_UNIVERSAL_IDENTIFIER =
   'b648f87b-1d26-4961-b974-0908fd991061';
 
 export default defineRole({
-  universalIdentifier: DEFAULT_FUNCTION_ROLE_UNIVERSAL_IDENTIFIER,
+  universalIdentifier: DEFAULT_ROLE_UNIVERSAL_IDENTIFIER,
   label: 'Default function role',
   description: 'Default role for function Twenty client',
   canReadAllObjectRecords: false,
@@ -430,7 +394,7 @@ export default defineRole({
   canBeAssignedToApiKeys: false,
   objectPermissions: [
     {
-      objectNameSingular: 'postCard',
+      objectUniversalIdentifier: '9f9882af-170c-4879-b013-f9628b77c050',
       canReadObjectRecords: true,
       canUpdateObjectRecords: true,
       canSoftDeleteObjectRecords: false,
@@ -439,8 +403,8 @@ export default defineRole({
   ],
   fieldPermissions: [
     {
-      objectNameSingular: 'postCard',
-      fieldName: 'content',
+      objectUniversalIdentifier: '9f9882af-170c-4879-b013-f9628b77c050',
+      fieldUniversalIdentifier: 'b2c37dc0-8ae7-470e-96cd-1476b47dfaff',
       canReadFieldValue: false,
       canUpdateFieldValue: false,
     },
@@ -449,10 +413,10 @@ export default defineRole({
 });
 ```
 
-Na `universalIdentifier` této role se poté odkazuje v `application.config.ts` jako na `functionRoleUniversalIdentifier`. Jinými slovy:
+Na `universalIdentifier` této role se poté odkazuje v `application-config.ts` jako na `defaultRoleUniversalIdentifier`. Jinými slovy:
 
 * **\*.role.ts** definuje, co může výchozí role funkce dělat.
-* **application.config.ts** ukazuje na tuto roli, aby vaše funkce zdědily její oprávnění.
+* **application-config.ts** ukazuje na tuto roli, aby vaše funkce zdědily její oprávnění.
 
 Poznámky:
 
@@ -461,22 +425,17 @@ Poznámky:
 * `permissionFlags` řídí přístup k schopnostem na úrovni platformy. Držte je na minimu; přidávejte pouze to, co potřebujete.
 * Podívejte se na funkční příklad v aplikaci Hello World: [`packages/twenty-apps/hello-world/src/roles/function-role.ts`](https://github.com/twentyhq/twenty/blob/main/packages/twenty-apps/hello-world/src/roles/function-role.ts).
 
-### Konfigurace serverless funkcí a vstupní bod
+### Konfigurace logických funkcí a vstupní bod
 
-Každý soubor funkce používá `defineFunction()` k exportu konfigurace s obslužnou funkcí (handlerem) a volitelnými spouštěči. Pro automatickou detekci použijte příponu souboru `*.function.ts`.
+Každý soubor funkce používá `defineLogicFunction()` k exportu konfigurace s obslužnou funkcí (handlerem) a volitelnými spouštěči.
 
 ```typescript
-// src/app/createPostCard.function.ts
-import { defineFunction } from 'twenty-sdk';
+// src/app/createPostCard.logic-function.ts
+import { defineLogicFunction } from 'twenty-sdk';
 import type { DatabaseEventPayload, ObjectRecordCreateEvent, CronPayload, RoutePayload } from 'twenty-sdk';
-import Twenty, { type Person } from '../../generated';
+import Twenty, { type Person } from '~/generated';
 
-const handler = async (
-  params:
-    | RoutePayload
-    | DatabaseEventPayload<ObjectRecordCreateEvent<Person>>
-    | CronPayload,
-) => {
+const handler = async (params: RoutePayload) => {
   const client = new Twenty(); // generated typed client
   const name = 'name' in params.queryStringParameters
     ? params.queryStringParameters.name ?? process.env.DEFAULT_RECIPIENT_NAME ?? 'Hello world'
@@ -492,7 +451,7 @@ const handler = async (
   return result;
 };
 
-export default defineFunction({
+export default defineLogicFunction({
   universalIdentifier: 'e56d363b-0bdc-4d8a-a393-6f0d1c75bdcf',
   name: 'create-new-post-card',
   timeoutSeconds: 2,
@@ -507,18 +466,18 @@ export default defineFunction({
       isAuthRequired: false,
     },
     // Cron trigger (CRON pattern)
-    {
-      universalIdentifier: 'dd802808-0695-49e1-98c9-d5c9e2704ce2',
-      type: 'cron',
-      pattern: '0 0 1 1 *',
-    },
+    // {
+    //   universalIdentifier: 'dd802808-0695-49e1-98c9-d5c9e2704ce2',
+    //   type: 'cron',
+    //   pattern: '0 0 1 1 *',
+    // },
     // Database event trigger
-    {
-      universalIdentifier: '203f1df3-4a82-4d06-a001-b8cf22a31156',
-      type: 'databaseEvent',
-      eventName: 'person.updated',
-      updatedFields: ['name'],
-    },
+    // {
+    //   universalIdentifier: '203f1df3-4a82-4d06-a001-b8cf22a31156',
+    //   type: 'databaseEvent',
+    //   eventName: 'person.updated',
+    //   updatedFields: ['name'],
+    // },
   ],
 });
 ```
@@ -539,6 +498,55 @@ Poznámky:
 * Pole `triggers` je volitelné. Funkce bez spouštěčů lze použít jako pomocné funkce volané jinými funkcemi.
 * V jedné funkci můžete kombinovat více typů spouštěčů.
 
+### Postinstalační funkce
+
+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.
+
+Když vygenerujete kostru nové aplikace pomocí `create-twenty-app`, vytvoří se pro vás postinstalační funkce v `src/logic-functions/post-install.ts`:
+
+```typescript
+// src/logic-functions/post-install.ts
+import { defineLogicFunction } from 'twenty-sdk';
+
+export const POST_INSTALL_UNIVERSAL_IDENTIFIER = '<generated-uuid>';
+
+const handler = async (): Promise<void> => {
+  console.log('Post install logic function executed successfully!');
+};
+
+export default defineLogicFunction({
+  universalIdentifier: POST_INSTALL_UNIVERSAL_IDENTIFIER,
+  name: 'post-install',
+  description: 'Runs after installation to set up the application.',
+  timeoutSeconds: 300,
+  handler,
+});
+```
+
+Funkce je připojena do vaší aplikace odkazem na její univerzální identifikátor v `application-config.ts`:
+
+```typescript
+import { POST_INSTALL_UNIVERSAL_IDENTIFIER } from 'src/logic-functions/post-install';
+
+export default defineApplication({
+  // ...
+  postInstallLogicFunctionUniversalIdentifier: POST_INSTALL_UNIVERSAL_IDENTIFIER,
+});
+```
+
+Postinstalační funkci můžete také kdykoli spustit ručně pomocí CLI:
+
+```bash filename="Terminal"
+yarn twenty function:execute --postInstall
+```
+
+Hlavní body:
+
+* Postinstalační funkce jsou standardní logické funkce — používají `defineLogicFunction()` stejně jako jakákoli jiná funkce.
+* Pole `postInstallLogicFunctionUniversalIdentifier` v `defineApplication()` je volitelné. Pokud je vynecháno, po instalaci se nespustí žádná funkce.
+* Výchozí časový limit je nastaven na 300 sekund (5 minut), aby umožnil delší úlohy nastavení, jako je naplnění daty.
+* Postinstalační funkce nepotřebují spouštěče — jsou spouštěny platformou během instalace nebo ručně pomocí `function:execute --postInstall`.
+
 ### Payload spouštěče trasy
 
 <Warning>
@@ -565,10 +573,10 @@ Poznámky:
   **Jak migrovat existující funkce:** Aktualizujte svůj handler tak, aby destrukturoval z `event.body`, `event.queryStringParameters` nebo `event.pathParameters` místo přímo z objektu params.
 </Warning>
 
-Když spouštěč trasy vyvolá vaši funkci, ta obdrží objekt `RoutePayload`, který odpovídá formátu AWS HTTP API v2. Importujte typ z `twenty-sdk`:
+Když spouštěč trasy vyvolá vaši logickou funkci, ta obdrží objekt `RoutePayload`, který odpovídá formátu AWS HTTP API v2. Importujte typ z `twenty-sdk`:
 
 ```typescript
-import { defineFunction, type RoutePayload } from 'twenty-sdk';
+import { defineLogicFunction, type RoutePayload } from 'twenty-sdk';
 
 const handler = async (event: RoutePayload) => {
   // Access request data
@@ -595,10 +603,10 @@ Typ `RoutePayload` má následující strukturu:
 
 ### Přeposílání záhlaví HTTP
 
-Ve výchozím nastavení se záhlaví HTTP z příchozích požadavků z bezpečnostních důvodů do vaší serverless funkce **ne** předávají. Chcete-li zpřístupnit konkrétní záhlaví, výslovně je uveďte v poli `forwardedRequestHeaders`:
+Ve výchozím nastavení se záhlaví HTTP z příchozích požadavků z bezpečnostních důvodů do vaší logické funkce **ne** předávají. Chcete-li zpřístupnit konkrétní záhlaví, výslovně je uveďte v poli `forwardedRequestHeaders`:
 
 ```typescript
-export default defineFunction({
+export default defineLogicFunction({
   universalIdentifier: 'e56d363b-0bdc-4d8a-a393-6f0d1c75bdcf',
   name: 'webhook-handler',
   handler,
@@ -633,23 +641,160 @@ const handler = async (event: RoutePayload) => {
 
 Nové funkce můžete vytvářet dvěma způsoby:
 
-* **Vygenerované**: Spusťte `yarn app:create-entity` a zvolte možnost přidat novou funkci. Tím se vygeneruje startovací soubor s obslužnou funkcí a konfigurací.
-* **Ruční**: Vytvořte nový soubor `*.function.ts` a použijte `defineFunction()` podle stejného vzoru.
+* **Vygenerované**: Spusťte `yarn twenty entity:add` a zvolte možnost přidat novou logickou funkci. Tím se vygeneruje startovací soubor s obslužnou funkcí a konfigurací.
+* **Ruční**: Vytvořte nový soubor `*.logic-function.ts` a použijte `defineLogicFunction()` podle stejného vzoru.
+
+### Označení logické funkce jako nástroje
+
+Logické funkce lze zpřístupnit jako **nástroje** pro agenty AI a pracovní postupy. Když je funkce označena jako nástroj, stane se dohledatelnou funkcemi AI produktu Twenty a lze ji vybrat jako krok v automatizacích pracovních postupů.
+
+Chcete-li označit logickou funkci jako nástroj, nastavte `isTool: true` a poskytněte `toolInputSchema` popisující očekávané vstupní parametry pomocí [JSON Schema](https://json-schema.org/):
+
+```typescript
+// src/logic-functions/enrich-company.logic-function.ts
+import { defineLogicFunction } from 'twenty-sdk';
+import Twenty from '~/generated';
+
+const handler = async (params: { companyName: string; domain?: string }) => {
+  const client = new Twenty();
+
+  const result = await client.mutation({
+    createTask: {
+      __args: {
+        data: {
+          title: `Enrich data for ${params.companyName}`,
+          body: `Domain: ${params.domain ?? 'unknown'}`,
+        },
+      },
+      id: true,
+    },
+  });
+
+  return { taskId: result.createTask.id };
+};
+
+export default defineLogicFunction({
+  universalIdentifier: 'f47ac10b-58cc-4372-a567-0e02b2c3d479',
+  name: 'enrich-company',
+  description: 'Enrich a company record with external data',
+  timeoutSeconds: 10,
+  handler,
+  isTool: true,
+  toolInputSchema: {
+    type: 'object',
+    properties: {
+      companyName: {
+        type: 'string',
+        description: 'The name of the company to enrich',
+      },
+      domain: {
+        type: 'string',
+        description: 'The company website domain (optional)',
+      },
+    },
+    required: ['companyName'],
+  },
+});
+```
+
+Hlavní body:
+
+* **`isTool`** (`boolean`, výchozí: `false`): Když je nastaveno na `true`, funkce je zaregistrována jako nástroj a zpřístupní se agentům AI a automatizacím pracovních postupů.
+* **`toolInputSchema`** (`object`, volitelné): Objekt JSON Schema, který popisuje parametry, jež vaše funkce přijímá. Agenti AI používají toto schéma k pochopení toho, jaké vstupy nástroj očekává, a k ověřování volání. Pokud je vynecháno, schéma má výchozí podobu `{ type: 'object', properties: {} }` (žádné parametry).
+* Funkce s `isTool: false` (nebo není nastaveno) **nejsou** zpřístupněny jako nástroje. Stále je lze spouštět přímo nebo volat z jiných funkcí, ale neobjeví se ve vyhledávání nástrojů.
+* **Pojmenování nástrojů**: Když je funkce zpřístupněna jako nástroj, její název se automaticky normalizuje na `logic_function_<name>` (převedeno na malá písmena, nealfanumerické znaky jsou nahrazeny podtržítky). Například `enrich-company` se změní na `logic_function_enrich_company`.
+* Můžete kombinovat `isTool` se spouštěči — funkce může být zároveň nástrojem (volatelným agenty AI) i spouštěna událostmi (cron, databázové události, routes).
+
+<Note>
+  **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>
+
+### Frontendové komponenty
+
+Frontendové komponenty vám umožňují vytvářet vlastní React komponenty, které se vykreslují v rozhraní Twenty. K definování komponent s vestavěnou validací použijte `defineFrontComponent()`:
+
+```typescript
+// src/my-widget.front-component.tsx
+import { defineFrontComponent } from 'twenty-sdk';
+
+const MyWidget = () => {
+  return (
+    <div style={{ padding: '20px', fontFamily: 'sans-serif' }}>
+      <h1>My Custom Widget</h1>
+      <p>This is a custom front component for Twenty.</p>
+    </div>
+  );
+};
+
+export default defineFrontComponent({
+  universalIdentifier: 'a1b2c3d4-e5f6-7890-abcd-ef1234567890',
+  name: 'my-widget',
+  description: 'A custom widget component',
+  component: MyWidget,
+});
+```
+
+Hlavní body:
+
+* Frontendové komponenty jsou React komponenty, které se vykreslují v izolovaných kontextech v rámci Twenty.
+* Pro automatickou detekci použijte příponu souboru `*.front-component.tsx`.
+* Pole `component` odkazuje na vaši React komponentu.
+* Komponenty se během `yarn twenty app:dev` automaticky sestaví a synchronizují.
+
+Nové frontendové komponenty můžete vytvořit dvěma způsoby:
+
+* **Vygenerované**: Spusťte `yarn twenty entity:add` a zvolte možnost přidat novou frontendovou komponentu.
+* **Ruční**: Vytvořte nový soubor `*.front-component.tsx` a použijte `defineFrontComponent()`.
+
+### Dovednosti
+
+Dovednosti definují znovupoužitelné pokyny a schopnosti, které mohou agenti AI používat ve vašem pracovním prostoru. K definování dovedností s vestavěnou validací použijte `defineSkill()`:
+
+```typescript
+// src/skills/example-skill.ts
+import { defineSkill } from 'twenty-sdk';
+
+export default defineSkill({
+  universalIdentifier: 'a1b2c3d4-e5f6-7890-abcd-ef1234567890',
+  name: 'sales-outreach',
+  label: 'Sales Outreach',
+  description: 'Guides the AI agent through a structured sales outreach process',
+  icon: 'IconBrain',
+  content: `You are a sales outreach assistant. When reaching out to a prospect:
+1. Research the company and recent news
+2. Identify the prospect's role and likely pain points
+3. Draft a personalized message referencing specific details
+4. Keep the tone professional but conversational`,
+});
+```
+
+Hlavní body:
+
+* `name` je jedinečný identifikátor dovednosti (doporučuje se kebab-case).
+* `label` je uživatelsky čitelný název zobrazovaný v UI.
+* `content` obsahuje pokyny dovednosti — je to text, který agent AI používá.
+* `icon` (volitelné) nastavuje ikonu zobrazovanou v UI.
+* `description` (volitelné) poskytuje doplňující kontext o účelu dovednosti.
+
+Nové dovednosti můžete vytvářet dvěma způsoby:
+
+* **Vygenerované**: Spusťte `yarn twenty entity:add` a zvolte možnost přidat novou dovednost.
+* **Ruční**: Vytvořte nový soubor a použijte `defineSkill()` podle stejného vzoru.
 
 ### Generovaný typovaný klient
 
-Spusťte yarn app:generate a vytvořte lokálního typovaného klienta v generated/ na základě schématu vašeho pracovního prostoru. Použijte jej ve svých funkcích:
+Typovaný klient je automaticky generován pomocí `yarn twenty app:dev` a ukládá se do `node_modules/twenty-sdk/generated` podle schématu vašeho pracovního prostoru. Použijte jej ve svých funkcích:
 
 ```typescript
-import Twenty from './generated';
+import Twenty from '~/generated';
 
 const client = new Twenty();
 const { me } = await client.query({ me: { id: true, displayName: true } });
 ```
 
-Klient je znovu generován příkazem `yarn app:generate`. Spusťte jej znovu po změně objektů a po `yarn app:sync`, případně při připojení k novému pracovnímu prostoru.
+Klient se automaticky znovu generuje pomocí `yarn twenty app:dev` kdykoli se změní vaše objekty nebo pole.
 
-#### Běhové přihlašovací údaje v serverless funkcích
+#### Běhové přihlašovací údaje v logických funkcích
 
 Když vaše funkce běží na Twenty, platforma před spuštěním kódu vloží přihlašovací údaje jako proměnné prostředí:
 
@@ -659,45 +804,85 @@ Když vaše funkce běží na Twenty, platforma před spuštěním kódu vloží
 Poznámky:
 
 * Není nutné předávat URL ani klíč API vygenerovanému klientovi. Za běhu čte `TWENTY_API_URL` a `TWENTY_API_KEY` z process.env.
-* Oprávnění API klíče jsou určena rolí odkazovanou v `application.config.ts` prostřednictvím `functionRoleUniversalIdentifier`. Toto je výchozí role používaná serverless funkcemi vaší aplikace.
-* Aplikace mohou definovat role podle principu nejmenších oprávnění. Udělte pouze oprávnění, která vaše funkce potřebují, a poté nastavte `functionRoleUniversalIdentifier` na univerzální identifikátor této role.
+* Oprávnění klíče API jsou určena rolí odkazovanou ve vašem `application-config.ts` prostřednictvím `defaultRoleUniversalIdentifier`. Toto je výchozí role používaná logickými funkcemi vaší aplikace.
+* Aplikace mohou definovat role podle principu nejmenších oprávnění. Udělte pouze oprávnění, která vaše funkce potřebují, a poté nastavte `defaultRoleUniversalIdentifier` na univerzální identifikátor této role.
+
+#### Nahrávání souborů
+
+Vygenerovaný klient `Twenty` obsahuje metodu `uploadFile` pro připojování souborů k polím typu souboru u objektů ve vašem pracovním prostoru. Protože standardní klienti GraphQL nativně nepodporují nahrávání souborů pomocí multipart, klient poskytuje tuto speciální metodu, která interně implementuje [specifikaci multipart požadavků GraphQL](https://github.com/jaydenseric/graphql-multipart-request-spec).
+
+```typescript
+import Twenty from '~/generated';
+import * as fs from 'fs';
+
+const client = new Twenty();
+
+const fileBuffer = fs.readFileSync('./invoice.pdf');
+
+const uploadedFile = await client.uploadFile(
+  fileBuffer,                                         // file contents as a Buffer
+  'invoice.pdf',                                      // filename
+  'application/pdf',                                  // MIME type (defaults to 'application/octet-stream')
+  '58a0a314-d7ea-4865-9850-7fb84e72f30b',            // field universal identifier
+);
+
+console.log(uploadedFile);
+// { id: '...', path: '...', size: 12345, createdAt: '...', url: 'https://...' }
+```
+
+Signatura metody:
+
+```typescript
+uploadFile(
+  fileBuffer: Buffer,
+  filename: string,
+  contentType: string,
+  fieldMetadataUniversalIdentifier: string,
+): Promise<{ id: string; path: string; size: number; createdAt: string; url: string }>
+```
+
+| Parametr                           | Typ      | Popis                                                                       |
+| ---------------------------------- | -------- | --------------------------------------------------------------------------- |
+| `fileBuffer`                       | `Buffer` | Surový obsah souboru                                                        |
+| `filename`                         | `string` | Název souboru (používá se pro ukládání a zobrazení)                         |
+| `contentType`                      | `string` | Typ MIME souboru (pokud je vynechán, výchozí je `application/octet-stream`) |
+| `fieldMetadataUniversalIdentifier` | `string` | `universalIdentifier` pole typu souboru ve vašem objektu                    |
+
+Hlavní body:
+
+* Metoda odešle soubor na **koncový bod metadat** (nikoli na hlavní koncový bod GraphQL), kde se provede mutace nahrání.
+* Používá `universalIdentifier` pole (nikoli jeho ID specifické pro pracovní prostor), takže váš kód pro nahrávání funguje ve všech pracovních prostorech, kde je vaše aplikace nainstalována — v souladu s tím, jak aplikace odkazují na pole všude jinde.
+* Vrácená hodnota `url` je podepsaná adresa URL, kterou můžete použít k přístupu k nahranému souboru.
 
 ### Příklad Hello World
 
-Prozkoumejte minimalistický end-to-end příklad, který demonstruje objekty, funkce a více spouštěčů [zde](https://github.com/twentyhq/twenty/tree/main/packages/twenty-apps/hello-world):
+Prozkoumejte minimalistický end-to-end příklad, který demonstruje objekty, logické funkce, frontendové komponenty a více spouštěčů [zde](https://github.com/twentyhq/twenty/tree/main/packages/twenty-apps/hello-world):
 
 ## Ruční nastavení (bez scaffolderu)
 
-Ačkoli pro nejlepší začátky doporučujeme použít `create-twenty-app`, projekt můžete nastavit i ručně. Neinstalujte CLI globálně. Místo toho přidejte `twenty-sdk` jako lokální závislost a propojte skripty v souboru package.json:
+Ačkoli pro nejlepší začátky doporučujeme použít `create-twenty-app`, projekt můžete nastavit i ručně. Neinstalujte CLI globálně. Místo toho přidejte `twenty-sdk` jako lokální závislost a přidejte jeden skript do souboru package.json:
 
 ```bash filename="Terminal"
 yarn add -D twenty-sdk
 ```
 
-Poté přidejte skripty jako tyto:
+Poté přidejte skript `twenty`:
 
 ```json filename="package.json"
 {
   "scripts": {
-    "auth": "twenty auth login",
-    "generate": "twenty app generate",
-    "dev": "twenty app dev",
-    "sync": "twenty app sync",
-    "uninstall": "twenty app uninstall",
-    "logs": "twenty app logs",
-    "create-entity": "twenty app add",
-    "help": "twenty --help"
+    "twenty": "twenty"
   }
 }
 ```
 
-Nyní můžete spouštět stejné příkazy přes Yarn, např. `yarn app:dev`, `yarn app:sync` atd.
+Nyní můžete spouštět všechny příkazy přes `yarn twenty <command>`, např. `yarn twenty app:dev`, `yarn twenty help` atd.
 
 ## Řešení potíží
 
-* Chyby ověření: spusťte `yarn auth:login` a ujistěte se, že váš klíč API má požadovaná oprávnění.
+* Chyby ověření: spusťte `yarn twenty auth:login` a ujistěte se, že váš klíč API má požadovaná oprávnění.
 * Nelze se připojit k serveru: ověřte URL API a že je server Twenty dosažitelný.
-* Typy nebo klient chybí/jsou zastaralé: spusťte `yarn app:generate` a poté `yarn app:dev`.
-* Režim vývoje nesynchronizuje: ujistěte se, že běží `yarn app:dev` a že vaše prostředí změny neignoruje.
+* Types or client missing/outdated: restart `yarn twenty app:dev` — it auto-generates the typed client.
+* Režim vývoje se nesynchronizuje: ujistěte se, že běží `yarn twenty app:dev` a že vaše prostředí změny neignoruje.
 
 Kanál podpory na Discordu: https://discord.com/channels/1130383047699738754/1130386664812982322

packages/twenty-docs/l/cs/developers/self-host/capabilities/setup.mdx

@@ -292,19 +292,19 @@ yarn command:prod cron:workflow:automated-cron-trigger
   **Režim pouze s prostředím:** Pokud nastavíte `IS_CONFIG_VARIABLES_IN_DB_ENABLED=false`, přidejte tyto proměnné do souboru `.env`
 </Warning>
 
-## Serverless funkce
+## Logické funkce
 
-Twenty podporuje serverless funkce pro pracovní postupy a vlastní logiku. Běhové prostředí se konfiguruje pomocí proměnné prostředí `SERVERLESS_TYPE`.
+Twenty podporuje logické funkce pro pracovní postupy a vlastní logiku. Běhové prostředí se konfiguruje pomocí proměnné prostředí `SERVERLESS_TYPE`.
 
 <Warning>
-  **Upozornění na zabezpečení:** Místní serverless ovladač (`SERVERLESS_TYPE=LOCAL`) spouští kód přímo na hostiteli v procesu Node.js bez sandboxu. Měl by být používán pouze pro důvěryhodný kód při vývoji. Pro produkční nasazení, která pracují s nedůvěryhodným kódem, důrazně doporučujeme použít `SERVERLESS_TYPE=LAMBDA` nebo `SERVERLESS_TYPE=DISABLED`.
+  **Upozornění na zabezpečení:** Místní ovladač (`SERVERLESS_TYPE=LOCAL`) spouští kód přímo na hostiteli v procesu Node.js bez sandboxu. Měl by být používán pouze pro důvěryhodný kód při vývoji. Pro produkční nasazení, která pracují s nedůvěryhodným kódem, důrazně doporučujeme použít `SERVERLESS_TYPE=LAMBDA` nebo `SERVERLESS_TYPE=DISABLED`.
 </Warning>
 
 ### Dostupné ovladače
 
 | Ovladač   | Proměnná prostředí         | Případ použití                             | Úroveň zabezpečení                  |
 | --------- | -------------------------- | ------------------------------------------ | ----------------------------------- |
-| Neaktivní | `SERVERLESS_TYPE=DISABLED` | Úplně zakázat serverless funkce            | N/A                                 |
+| Neaktivní | `SERVERLESS_TYPE=DISABLED` | Úplně zakázat logické funkce               | N/A                                 |
 | Lokální   | `SERVERLESS_TYPE=LOCAL`    | Vývojová a důvěryhodná prostředí           | Nízká (bez sandboxu)                |
 | Lambda    | `SERVERLESS_TYPE=LAMBDA`   | Produkční prostředí s nedůvěryhodným kódem | Vysoká (izolace na úrovni hardwaru) |
 
@@ -326,12 +326,12 @@ SERVERLESS_LAMBDA_ACCESS_KEY_ID=your-access-key
 SERVERLESS_LAMBDA_SECRET_ACCESS_KEY=your-secret-key
 ```
 
-**Pro zakázání serverless funkcí:**
+**Pro zakázání logických funkcí:**
 
 ```bash
 SERVERLESS_TYPE=DISABLED
 ```
 
 <Note>
-  Při použití `SERVERLESS_TYPE=DISABLED` skončí každý pokus o spuštění serverless funkce chybou. To je užitečné, pokud chcete provozovat Twenty bez podpory serverless funkcí.
+  Při použití `SERVERLESS_TYPE=DISABLED` skončí každý pokus o spuštění logické funkce chybou. To je užitečné, pokud chcete provozovat Twenty bez podpory logických funkcí.
 </Note>

packages/twenty-docs/l/cs/user-guide/ai/overview.mdx

@@ -59,4 +59,4 @@ To zajistí, že AI agenti budou respektovat vaše zásady správy dat a budou p
 Tuto sekci budeme aktualizovat, jakmile budou funkce AI k dispozici. Mezitím:
 
 * Sledujte náš [GitHub](https://github.com/twentyhq/twenty) pro novinky o vývoji
-* Přidejte se na náš [Discord](https://discord.gg/twenty) a podělte se o zpětnou vazbu a návrhy na nové funkce
+* Přidejte se na náš [Discord](https://discord.gg/UfGNZJfAG6) a podělte se o zpětnou vazbu a návrhy na nové funkce

packages/twenty-docs/l/cs/user-guide/data-model/capabilities/relation-fields.mdx

@@ -39,12 +39,16 @@ Mnoho záznamů v Objektu A může být propojeno s mnoha záznamy v Objektu B.
 
 **Příklad:** Mnoho lidí může být propojeno s mnoha projekty a naopak.
 
-<Warning>
-  **Mnoho k mnoha zatím není podporováno.**
+Vztahy typu mnoho-na-mnoho používají vzor zvaný **spojovací objekt**: zprostředkující objekt, který propojuje obě strany. S funkcí spojovacího vztahu zobrazuje Twenty přímo výsledné propojené záznamy a zprostředkující objekt v UI skrývá.
 
-  Tento typ relace je plánován na 1. pololetí 2026. Jako dočasné řešení vytvořte prostřední "spojovací" objekt (např. "Project Assignments"), který má relace typu mnoho k jednomu k oběma objektům.
+<img src="/images/user-guide/fields/junction-relation-diagram.png" style={{width:'100%'}} />
+
+<Warning>
+  **Experimentální funkce**: Vztahy přes spojovací objekt je před použitím nutné povolit v **Settings → Updates → Lab**.
 </Warning>
 
+Podívejte se na [Jak vytvořit vztahy typu mnoho k mnoha](/l/cs/user-guide/data-model/how-tos/create-many-to-many-relations) pro úplný návod krok za krokem.
+
 ## Vytvoření relačního pole
 
 1. Přejděte do **Nastavení → Datový model**

packages/twenty-docs/l/cs/user-guide/data-model/how-tos/create-many-to-many-relations.mdx

@@ -0,0 +1,180 @@
+---
+title: Vytváření vztahů mnoho-na-mnoho
+description: Propojte záznamy, kde lze mnoho položek na obou stranách vzájemně propojit pomocí spojovacích objektů.
+---
+
+Vztahy mnoho-na-mnoho vám umožňují propojit více záznamů na obou stranách. Například: mnoho lidí může pracovat na mnoha projektech a každý projekt může mít mnoho lidí.
+
+<Warning>
+  **Lab Feature**: Vztahy přes spojovací objekt jsou momentálně v Lab. Povolte je v **Settings → Updates → Lab** předtím, než budete pokračovat podle tohoto návodu.
+</Warning>
+
+<Note>
+  Tato funkce také vyžaduje, aby byl povolen **Advanced mode** (přepínač je vpravo dole v Settings).
+</Note>
+
+## Kdy použít mnoho-na-mnoho
+
+Použijte mnoho-na-mnoho, když obě strany vztahu mohou mít více propojení:
+
+| Vztah                 | Příklad                                                                     |
+| --------------------- | --------------------------------------------------------------------------- |
+| Lidé ↔ Projekty       | Osoba pracuje na více projektech; projekt má více členů týmu                |
+| Společnosti ↔ Štítky  | Společnost může mít více štítků; štítek může platit pro více společností    |
+| Produkty ↔ Objednávky | Produkt může být v několika objednávkách; objednávka obsahuje více produktů |
+
+## Jak to funguje
+
+Twenty používá u vztahů mnoho-na-mnoho vzor **spojovacího objektu**. Spojovací objekt leží mezi dvěma objekty a uchovává propojení:
+
+```
+People ←→ Project Assignments ←→ Projects
+```
+
+Objekt **Project Assignments** (spojovací) má:
+
+* Vztah na People (mnoho k jednomu)
+* Vztah na Projects (mnoho k jednomu)
+
+Když povolíte přepínač pro vztah přes spojovací objekt, Twenty zobrazí propojené záznamy přímo místo zobrazení prostředních záznamů spojovacího objektu.
+
+## Předpoklady
+
+1. **Povolte Junction Relations v Lab**: Přejděte do **Settings → Updates → Lab** a povolte **Junction Relations**
+2. **Povolte Advanced mode**: Zapněte **Advanced mode** vpravo dole na postranním panelu Settings
+3. Naplánujte svůj datový model:
+   * Které dva objekty propojujete?
+   * Jak by se měl jmenovat spojovací objekt?
+
+## Krok 1: Vytvořte spojovací objekt
+
+Nejprve vytvořte mezilehlý objekt, který bude uchovávat propojení.
+
+1. Přejděte do **Nastavení → Datový model**
+2. Klikněte na **+ New object**
+3. Pojmenujte jej výstižně (např. "Project Assignment", "Team Member", "Product Order")
+4. Klikněte na **Uložit**
+
+<Tip>
+  **Konvence pojmenování**: Použijte název, který popisuje vztah, například "Project Assignment" nebo "Team Membership". Tím bude datový model srozumitelnější.
+</Tip>
+
+## Krok 2: Vytvořte vztahy ze spojovacího objektu
+
+Přidejte relační pole ze spojovacího objektu do obou objektů, které chcete propojit.
+
+### První vztah (Junction → Objekt A)
+
+1. Vyberte svůj spojovací objekt v **Settings → Data Model**
+2. Klikněte na **+ Add Field**
+3. Zvolte **Relation** jako typ pole
+4. Vyberte první objekt (např. "People")
+5. Nastavte typ vztahu na **Many-to-One** (mnoho přiřazení může odkazovat na jednu osobu)
+6. Pojmenujte pole:
+   * Pole na spojovacím objektu: např. "Person"
+   * Pole na People: např. "Project Assignments"
+7. Klikněte na **Uložit**
+
+### Druhý vztah (Junction → Objekt B)
+
+1. Stále na spojovacím objektu klikněte na **+ Add Field**
+2. Zvolte **Relation** jako typ pole
+3. Vyberte druhý objekt (např. "Projects")
+4. Nastavte typ vztahu na **Many-to-One**
+5. Pojmenujte pole:
+   * Pole na spojovacím objektu: např. "Project"
+   * Pole na Projects: např. "Team Members"
+6. Klikněte na **Uložit**
+
+## Krok 3: Nakonfigurujte zobrazení vztahu přes spojovací objekt
+
+Nyní nakonfigurujte zdrojové objekty tak, aby zobrazovaly propojené záznamy přímo a přeskočily mezilehlý spojovací objekt.
+
+1. Přejděte do **Nastavení → Datový model**
+2. Vyberte první objekt (např. "People")
+3. Najděte relační pole směřující na spojovací objekt (např. "Project Assignments")
+4. Klikněte pro úpravu pole
+5. Povolte **"This is a relation to a Junction Object"**
+6. Vyberte **Target relation** (např. "Project" — pole na spojovacím objektu, které ukazuje na druhou stranu)
+7. Klikněte na **Uložit**
+
+{/* TODO: Add image
+<img src="/images/user-guide/fields/junction-relation-toggle.png" style={{width:'100%'}}/>
+*/}
+
+Opakujte pro druhý objekt:
+
+1. Vyberte "Projects" v Data Model
+2. Upravte relační pole "Team Members"
+3. Povolte přepínač pro vztah přes spojovací objekt
+4. Vyberte "Person" jako cílový vztah
+5. Uložit
+
+## Výsledek
+
+Po konfiguraci:
+
+* Na záznamu **Person** pole "Project Assignments" zobrazuje přímo **Projects** (nikoli záznamy přiřazení)
+* Na záznamu **Project** pole "Team Members" zobrazuje přímo **People**
+
+Spojovací objekt stále existuje a ukládá propojení, ale rozhraní zobrazuje čistší pohled mnoho-na-mnoho.
+
+## Příklad: Lidé ↔ Projekty
+
+Zde je kompletní postup:
+
+### Vytvořte spojovací objekt
+
+* Název: **Project Assignment**
+* Popis: "Propojuje lidi s projekty, na kterých pracují"
+
+### Přidejte vztahy
+
+1. **Project Assignment → People**
+   * Typ: Many-to-One
+   * Pole na Assignment: "Person"
+   * Pole na People: "Project Assignments"
+
+2. **Project Assignment → Projects**
+   * Typ: Many-to-One
+   * Pole na Assignment: "Project"
+   * Pole na Projects: "Team Members"
+
+### Nakonfigurujte zobrazení spojovacího objektu
+
+1. Na objektu **People**:
+   * Upravte pole "Project Assignments"
+   * Povolte přepínač pro vztah přes spojovací objekt
+   * Cíl: "Project"
+
+2. Na objektu **Projects**:
+   * Upravte pole "Team Members"
+   * Povolte přepínač pro vztah přes spojovací objekt
+   * Cíl: "Person"
+
+### Použití
+
+* Otevřete záznam osoby → Uvidíte její projekty přímo
+* Otevřete záznam projektu → Uvidíte členy týmu přímo
+* Vytvářejte nová propojení z obou stran
+
+## Přidávání doplňkových dat do propojení
+
+Protože spojovací objekt je skutečný objekt, můžete přidat vlastní pole k ukládání informací o vztahu:
+
+* **Role**: "Developer", "Designer", "Manager"
+* **Start Date**: Kdy se k projektu připojili
+* **Hours Allocated**: Týdenní počet hodin na tomto projektu
+
+Pro přístup k těmto datům přejděte přímo na spojovací objekt nebo jej dotazujte přes API.
+
+## Omezení
+
+* **CSV Import/Export**: Přímý import vztahů mnoho-na-mnoho není podporován. Místo toho importujte záznamy do spojovacího objektu.
+* **Filters**: Filtrování podle vztahů mnoho-na-mnoho může mít omezené možnosti.
+
+## Související
+
+* [Relační pole](/l/cs/user-guide/data-model/capabilities/relation-fields) — vysvětlení typů vztahů
+* [Vytváření vlastních objektů](/l/cs/user-guide/data-model/how-tos/create-custom-objects) — jak vytvářet objekty
+* [Vytváření relačních polí](/l/cs/user-guide/data-model/how-tos/create-relation-fields) — základní nastavení vztahů

packages/twenty-docs/l/cs/user-guide/getting-started/capabilities/glossary.mdx

@@ -9,7 +9,7 @@ API (rozhraní pro programování aplikací) umožňuje propojení Twenty s dal
 
 ## Aplikace
 
-Aplikace jsou vlastní rozšíření vytvořená jako kód, která mohou definovat datové modely a bezserverové funkce. Umožňují vývojářům vytvářet znovupoužitelné přizpůsobení, které lze nasadit do více pracovních prostorů.
+Aplikace jsou vlastní rozšíření vytvořená jako kód, která mohou definovat datové modely a logické funkce. Umožňují vývojářům vytvářet znovupoužitelné přizpůsobení, které lze nasadit do více pracovních prostorů.
 
 ## Akce kódu
 

packages/twenty-docs/l/cs/user-guide/workflows/capabilities/send-emails-from-workflows.mdx

@@ -136,7 +136,7 @@ K e-mailům odesílaným z pracovních postupů můžete přikládat soubory. P
 | **Potvrzení událostí**     | Podrobnosti o události nebo program |
 
 <Note>
-  Přílohy jsou statické—všem příjemcům se posílá stejný soubor. U dynamických dokumentů (například personalizovaných nabídek) soubory vygenerujte a přiložte pomocí [Serverless funkce](/l/cs/user-guide/workflows/how-tos/connect-to-other-tools/generate-pdf-from-twenty).
+  Přílohy jsou statické—všem příjemcům se posílá stejný soubor. U dynamických dokumentů (například personalizovaných nabídek) soubory vygenerujte a přiložte pomocí [Logic funkce](/l/cs/user-guide/workflows/how-tos/connect-to-other-tools/generate-pdf-from-twenty).
 </Note>
 
 ## Osvědčené postupy

packages/twenty-docs/l/cs/user-guide/workflows/capabilities/workflow-actions.mdx

@@ -256,7 +256,7 @@ Spouští vlastní JavaScript ve vašem pracovním postupu.
 * Testovat kód přímo ve kroku
 
 <Note>
-  Pokud potřebujete ve svém kódu použít externí klíče API, musíte je zadat přímo do těla funkce. Klíče API nelze nakonfigurovat jinde a odkazovat na ně v bezserverové funkci.
+  Pokud potřebujete ve svém kódu použít externí klíče API, musíte je zadat přímo do těla funkce. You cannot configure API keys elsewhere and reference them in the logic function.
 </Note>
 
 <Tip>