Fix form field select + form field number (#18538)

Before
<img width="398" height="138" alt="Capture d’écran 2026-03-10 à 16 23
19"
src="https://github.com/user-attachments/assets/c28c0a7f-6911-4c77-a45c-42a79073a92a"
/>

After
<img width="398" height="138" alt="Capture d’écran 2026-03-10 à 16 32
56"
src="https://github.com/user-attachments/assets/b93d2fe9-5928-4803-8d5e-30a0a9eeb28f"
/>

Addition:
- hover on forget password
- settings field width

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

@@ -11,7 +11,7 @@ permissions:
 
 concurrency:
   group: ${{ github.workflow }}-${{ github.event_name == 'merge_group' && github.event.merge_group.base_ref || github.ref }}
-  cancel-in-progress: true
+  cancel-in-progress: ${{ github.event_name != 'merge_group' }}
 
 jobs:
   e2e-test:

package.json

@@ -206,6 +206,7 @@
       "packages/twenty-e2e-testing",
       "packages/twenty-shared",
       "packages/twenty-sdk",
+      "packages/twenty-standard-application",
       "packages/twenty-apps",
       "packages/twenty-cli",
       "packages/create-twenty-app",

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

@@ -1,7 +1,7 @@
 ## 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
+- Rich app example: https://github.com/twentyhq/twenty/tree/main/packages/twenty-sdk/src/app-seeds/rich-app
 
 ## UUID requirement
 

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

@@ -386,6 +386,12 @@ describe('copyBaseApplicationProject', () => {
           ),
         ).toBe(true);
 
+        expect(
+          await fs.pathExists(
+            join(testAppDirectory, '.github', 'workflows', 'ci.yml'),
+          ),
+        ).toBe(true);
+
         // Install functions should always exist
         expect(
           await fs.pathExists(
@@ -464,6 +470,12 @@ describe('copyBaseApplicationProject', () => {
             join(srcPath, '__tests__', 'app-install.integration-test.ts'),
           ),
         ).toBe(false);
+
+        expect(
+          await fs.pathExists(
+            join(testAppDirectory, '.github', 'workflows', 'ci.yml'),
+          ),
+        ).toBe(false);
       });
     });
 

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

@@ -110,6 +110,37 @@ describe('scaffoldIntegrationTest', () => {
     });
   });
 
+  describe('github workflow', () => {
+    it('should create .github/workflows/ci.yml with correct structure', async () => {
+      await scaffoldIntegrationTest({
+        appDirectory: testAppDirectory,
+        sourceFolderPath,
+      });
+
+      const workflowPath = join(
+        testAppDirectory,
+        '.github',
+        'workflows',
+        'ci.yml',
+      );
+
+      expect(await fs.pathExists(workflowPath)).toBe(true);
+
+      const content = await fs.readFile(workflowPath, 'utf8');
+
+      expect(content).toContain('name: CI');
+      expect(content).toContain('TWENTY_VERSION: latest');
+      expect(content).toContain('twenty-version: ${{ env.TWENTY_VERSION }}');
+      expect(content).toContain('actions/checkout@v4');
+      expect(content).toContain('spawn-twenty-docker-image@main');
+      expect(content).toContain('actions/setup-node@v4');
+      expect(content).toContain('yarn install --immutable');
+      expect(content).toContain('yarn test');
+      expect(content).toContain('TWENTY_API_URL');
+      expect(content).toContain('TWENTY_TEST_API_KEY');
+    });
+  });
+
   describe('tsconfig.spec.json', () => {
     it('should create tsconfig.spec.json extending the base tsconfig', async () => {
       await scaffoldIntegrationTest({

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

@@ -25,6 +25,7 @@ export const scaffoldIntegrationTest = async ({
 
   await createVitestConfig(appDirectory);
   await createTsconfigSpec(appDirectory);
+  await createGithubWorkflow(appDirectory);
 };
 
 const createVitestConfig = async (appDirectory: string) => {
@@ -211,3 +212,56 @@ describe('App installation', () => {
   await fs.ensureDir(join(appDirectory, fileFolder ?? ''));
   await fs.writeFile(join(appDirectory, fileFolder ?? '', fileName), content);
 };
+
+const DEFAULT_TWENTY_VERSION = 'latest';
+
+const createGithubWorkflow = async (appDirectory: string) => {
+  const content = `name: CI
+
+on:
+  push:
+    branches:
+      - main
+  pull_request: {}
+
+env:
+  TWENTY_VERSION: ${DEFAULT_TWENTY_VERSION}
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Spawn Twenty instance
+        id: twenty
+        uses: twentyhq/twenty/.github/actions/spawn-twenty-docker-image@main
+        with:
+          twenty-version: \${{ env.TWENTY_VERSION }}
+          github-token: \${{ secrets.GITHUB_TOKEN }}
+
+      - name: Enable Corepack
+        run: corepack enable
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version-file: '.nvmrc'
+          cache: 'yarn'
+
+      - name: Install dependencies
+        run: yarn install --immutable
+
+      - name: Run integration tests
+        run: yarn test
+        env:
+          TWENTY_API_URL: \${{ steps.twenty.outputs.server-url }}
+          TWENTY_TEST_API_KEY: \${{ steps.twenty.outputs.access-token }}
+`;
+
+  const workflowDir = join(appDirectory, '.github', 'workflows');
+
+  await fs.ensureDir(workflowDir);
+  await fs.writeFile(join(workflowDir, 'ci.yml'), content);
+};

packages/twenty-apps/.gitignore

@@ -1,2 +1,3 @@
 generated
+.twenty
 

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

@@ -1,7 +1,7 @@
 ## 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
+- Rich app example: https://github.com/twentyhq/twenty/tree/main/packages/twenty-sdk/src/app-seeds/rich-app
 
 ## UUID requirement
 - All generated UUIDs must be valid UUID v4.

packages/twenty-apps/community/apollo-enrich/src/logic-functions/get-authentication-token-pairs.ts

@@ -1,5 +1,5 @@
 import { defineLogicFunction, RoutePayload } from "twenty-sdk";
-import { MetadataApiClient } from 'twenty-sdk/generated';
+import { MetadataApiClient } from 'twenty-sdk/clients';
 
 export const OAUTH_TOKEN_PAIRS_PATH = '/oauth/token-pairs';
 

packages/twenty-apps/community/apollo-enrich/src/logic-functions/on-company-updated.ts

@@ -3,7 +3,7 @@ import {
   type DatabaseEventPayload,
   type ObjectRecordUpdateEvent,
 } from 'twenty-sdk';
-import { CoreApiClient } from 'twenty-sdk/generated';
+import { CoreApiClient } from 'twenty-sdk/clients';
 
 type CompanyRecord = {
   id: string;

packages/twenty-apps/fixtures/function-execute-app/application.config.ts

@@ -1,4 +1,4 @@
-import { defineApplication } from '@/sdk';
+import { defineApplication } from 'twenty-sdk';
 
 import { DEFAULT_ROLE_UNIVERSAL_IDENTIFIER } from './my.role';
 

packages/twenty-apps/fixtures/function-execute-app/my.role.ts

@@ -1,4 +1,4 @@
-import { defineRole } from '@/sdk';
+import { defineRole } from 'twenty-sdk';
 
 export const DEFAULT_ROLE_UNIVERSAL_IDENTIFIER =
   '9f992b6c-17e9-4381-bab5-b6150b574304';

packages/twenty-apps/fixtures/function-execute-app/src/logic-functions/add-numbers.function.ts

@@ -1,4 +1,4 @@
-import { defineLogicFunction } from '@/sdk';
+import { defineLogicFunction } from 'twenty-sdk';
 
 export const ADD_NUMBERS_UNIVERSAL_IDENTIFIER =
   'f9e5589c-e951-4d99-85db-0a305ab53502';

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

@@ -3,13 +3,13 @@
     "target": "ES2020",
     "module": "ESNext",
     "moduleResolution": "bundler",
-    "esModuleInterop": true,
     "strict": true,
+    "esModuleInterop": true,
     "skipLibCheck": true,
     "jsx": "react-jsx",
     "baseUrl": ".",
     "paths": {
-      "@/*": ["../../../../../src/*"]
+      "src/*": ["./src/*"]
     }
   },
   "include": ["**/*"],

packages/twenty-apps/fixtures/invalid-app/application.config.ts

@@ -1,4 +1,4 @@
-import { defineApplication } from '@/sdk';
+import { defineApplication } from 'twenty-sdk';
 
 export default defineApplication({
   universalIdentifier: 'invalid-app-0000-0000-0000-000000000001',

packages/twenty-apps/fixtures/invalid-app/src/first.object.ts

@@ -1,4 +1,4 @@
-import { defineObject, FieldType } from '@/sdk';
+import { defineObject, FieldType } from 'twenty-sdk';
 
 const DUPLICATE_ID = 'duplicate-id-0000-0000-000000000001';
 

packages/twenty-apps/fixtures/invalid-app/src/second.object.ts

@@ -1,4 +1,4 @@
-import { defineObject, FieldType } from '@/sdk';
+import { defineObject, FieldType } from 'twenty-sdk';
 
 const DUPLICATE_ID = 'duplicate-id-0000-0000-000000000001';
 

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

@@ -9,7 +9,7 @@
     "jsx": "react-jsx",
     "baseUrl": ".",
     "paths": {
-      "@/*": ["../../../../../src/*"]
+      "src/*": ["./src/*"]
     }
   },
   "include": ["**/*"],

packages/twenty-apps/fixtures/minimal-app/application.config.ts

@@ -1,4 +1,4 @@
-import { defineApplication } from '@/sdk';
+import { defineApplication } from 'twenty-sdk';
 
 export default defineApplication({
   universalIdentifier: 'e1e2e3e4-e5e6-4000-8000-000000000001',

packages/twenty-apps/fixtures/minimal-app/my.front-component.tsx

@@ -1,4 +1,4 @@
-import { defineFrontComponent } from '@/sdk';
+import { defineFrontComponent } from 'twenty-sdk';
 
 export const MyComponent = () => {
   return (

packages/twenty-apps/fixtures/minimal-app/my.function.ts

@@ -1,4 +1,4 @@
-import { defineLogicFunction } from '@/sdk';
+import { defineLogicFunction } from 'twenty-sdk';
 
 const myHandler = () => {
   return 'my-function-result';

packages/twenty-apps/fixtures/minimal-app/my.object.ts

@@ -1,4 +1,4 @@
-import { FieldType, defineObject } from '@/sdk';
+import { FieldType, defineObject } from 'twenty-sdk';
 
 export default defineObject({
   universalIdentifier: 'e1e2e3e4-e5e6-4000-8000-000000000030',

packages/twenty-apps/fixtures/minimal-app/my.role.ts

@@ -1,4 +1,4 @@
-import { defineRole } from '@/sdk';
+import { defineRole } from 'twenty-sdk';
 
 export default defineRole({
   universalIdentifier: 'e1e2e3e4-e5e6-4000-8000-000000000040',

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

@@ -1,5 +1,5 @@
 {
-  "name": "rich-app",
+  "name": "minimal-app",
   "version": "0.1.0",
   "license": "MIT",
   "engines": {

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

@@ -9,8 +9,9 @@
     "jsx": "react-jsx",
     "baseUrl": ".",
     "paths": {
-      "@/*": ["../../../../../src/*"]
+      "src/*": ["./src/*"]
     }
   },
-  "include": ["**/*"]
+  "include": ["**/*"],
+  "exclude": ["node_modules", "dist", ".twenty"]
 }

packages/twenty-apps/fixtures/postcard-app/application.config.ts

@@ -1,4 +1,4 @@
-import { defineApplication } from '@/sdk';
+import { defineApplication } from 'twenty-sdk';
 import { DEFAULT_ROLE_UNIVERSAL_IDENTIFIER } from './src/roles/default-function.role';
 
 export default defineApplication({

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

@@ -1,5 +1,5 @@
 {
-  "name": "root-app",
+  "name": "postcard-app",
   "version": "0.1.0",
   "license": "MIT",
   "engines": {

packages/twenty-apps/fixtures/postcard-app/src/components/card.front-component.tsx

@@ -1,4 +1,4 @@
-import { defineFrontComponent } from '@/sdk';
+import { defineFrontComponent } from 'twenty-sdk';
 import { CardDisplay } from '../utils/card-display.component';
 
 export default defineFrontComponent({

packages/twenty-apps/fixtures/postcard-app/src/components/greeting.front-component.tsx

@@ -1,4 +1,4 @@
-import { defineFrontComponent } from '@/sdk';
+import { defineFrontComponent } from 'twenty-sdk';
 import { DEFAULT_NAME, formatGreeting } from '../utils/greeting.util';
 
 const GreetingComponent = () => {

packages/twenty-apps/fixtures/postcard-app/src/components/test.front-component.tsx

@@ -1,4 +1,4 @@
-import { defineFrontComponent } from '@/sdk';
+import { defineFrontComponent } from 'twenty-sdk';
 
 export const TestComponent = () => {
   return (

packages/twenty-apps/fixtures/postcard-app/src/fields/post-card-on-post-card-recipient.field.ts

@@ -1,10 +1,10 @@
 import {
   POST_CARD_ON_POST_CARD_RECIPIENT_ID,
   POST_CARD_RECIPIENTS_ON_POST_CARD_ID,
-} from '@/cli/__tests__/apps/rich-app/src/fields/post-card-recipients-on-post-card.field';
-import { POST_CARD_RECIPIENT_UNIVERSAL_IDENTIFIER } from '@/cli/__tests__/apps/rich-app/src/objects/post-card-recipient.object';
-import { defineField, FieldType, OnDeleteAction, RelationType } from '@/sdk';
-import { POST_CARD_UNIVERSAL_IDENTIFIER } from '@/cli/__tests__/apps/rich-app/src/objects/post-card.object';
+} from './post-card-recipients-on-post-card.field';
+import { POST_CARD_RECIPIENT_UNIVERSAL_IDENTIFIER } from '../objects/post-card-recipient.object';
+import { defineField, FieldType, OnDeleteAction, RelationType } from 'twenty-sdk';
+import { POST_CARD_UNIVERSAL_IDENTIFIER } from '../objects/post-card.object';
 
 export default defineField({
   universalIdentifier: POST_CARD_ON_POST_CARD_RECIPIENT_ID,

packages/twenty-apps/fixtures/postcard-app/src/fields/post-card-recipients-on-post-card.field.ts

@@ -1,6 +1,6 @@
-import { POST_CARD_RECIPIENT_UNIVERSAL_IDENTIFIER } from '@/cli/__tests__/apps/rich-app/src/objects/post-card-recipient.object';
-import { defineField, FieldType, RelationType } from '@/sdk';
-import { POST_CARD_UNIVERSAL_IDENTIFIER } from '@/cli/__tests__/apps/rich-app/src/objects/post-card.object';
+import { POST_CARD_RECIPIENT_UNIVERSAL_IDENTIFIER } from '../objects/post-card-recipient.object';
+import { defineField, FieldType, RelationType } from 'twenty-sdk';
+import { POST_CARD_UNIVERSAL_IDENTIFIER } from '../objects/post-card.object';
 
 export const POST_CARD_RECIPIENTS_ON_POST_CARD_ID =
   'a1a2b3c4-0001-4a7b-8c9d-0e1f2a3b4c5d';

packages/twenty-apps/fixtures/postcard-app/src/fields/post-card-recipients-on-recipient.field.ts

@@ -1,6 +1,6 @@
-import { defineField, FieldType, RelationType } from '@/sdk';
-import { RECIPIENT_UNIVERSAL_IDENTIFIER } from '@/cli/__tests__/apps/rich-app/src/objects/recipient.object';
-import { POST_CARD_RECIPIENT_UNIVERSAL_IDENTIFIER } from '@/cli/__tests__/apps/rich-app/src/objects/post-card-recipient.object';
+import { defineField, FieldType, RelationType } from 'twenty-sdk';
+import { RECIPIENT_UNIVERSAL_IDENTIFIER } from '../objects/recipient.object';
+import { POST_CARD_RECIPIENT_UNIVERSAL_IDENTIFIER } from '../objects/post-card-recipient.object';
 
 export const POST_CARD_RECIPIENTS_ON_RECIPIENT_ID =
   'a1a2b3c4-0003-4a7b-8c9d-0e1f2a3b4c5d';

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

@@ -1,5 +1,5 @@
-import { defineField, FieldType } from '@/sdk';
-import { POST_CARD_UNIVERSAL_IDENTIFIER } from '@/cli/__tests__/apps/rich-app/src/objects/post-card.object';
+import { defineField, FieldType } from 'twenty-sdk';
+import { POST_CARD_UNIVERSAL_IDENTIFIER } from '../objects/post-card.object';
 
 export default defineField({
   objectUniversalIdentifier: POST_CARD_UNIVERSAL_IDENTIFIER,

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

@@ -1,5 +1,5 @@
-import { defineField, FieldType } from '@/sdk';
-import { POST_CARD_UNIVERSAL_IDENTIFIER } from '@/cli/__tests__/apps/rich-app/src/objects/post-card.object';
+import { defineField, FieldType } from 'twenty-sdk';
+import { POST_CARD_UNIVERSAL_IDENTIFIER } from '../objects/post-card.object';
 
 export default defineField({
   objectUniversalIdentifier: POST_CARD_UNIVERSAL_IDENTIFIER,

packages/twenty-apps/fixtures/postcard-app/src/fields/recipient-on-post-card-recipient.field.ts

@@ -1,10 +1,10 @@
-import { defineField, FieldType, RelationType, OnDeleteAction } from '@/sdk';
-import { RECIPIENT_UNIVERSAL_IDENTIFIER } from '@/cli/__tests__/apps/rich-app/src/objects/recipient.object';
-import { POST_CARD_RECIPIENT_UNIVERSAL_IDENTIFIER } from '@/cli/__tests__/apps/rich-app/src/objects/post-card-recipient.object';
+import { defineField, FieldType, RelationType, OnDeleteAction } from 'twenty-sdk';
+import { RECIPIENT_UNIVERSAL_IDENTIFIER } from '../objects/recipient.object';
+import { POST_CARD_RECIPIENT_UNIVERSAL_IDENTIFIER } from '../objects/post-card-recipient.object';
 import {
   POST_CARD_RECIPIENTS_ON_RECIPIENT_ID,
   RECIPIENT_ON_POST_CARD_RECIPIENT_ID,
-} from '@/cli/__tests__/apps/rich-app/src/fields/post-card-recipients-on-recipient.field';
+} from './post-card-recipients-on-recipient.field';
 
 export default defineField({
   universalIdentifier: RECIPIENT_ON_POST_CARD_RECIPIENT_ID,

packages/twenty-apps/fixtures/postcard-app/src/logic-functions/greeting.function.ts

@@ -1,4 +1,4 @@
-import { defineLogicFunction } from '@/sdk';
+import { defineLogicFunction } from 'twenty-sdk';
 import { DEFAULT_NAME, formatGreeting } from '../utils/greeting.util';
 
 const greetingHandler = () => {

packages/twenty-apps/fixtures/postcard-app/src/logic-functions/lookup-recipient.function.ts

@@ -1,4 +1,4 @@
-import { defineLogicFunction } from '@/sdk';
+import { defineLogicFunction } from 'twenty-sdk';
 
 const handler = async (params: { recipientName: string }) => {
   return { found: true, name: params.recipientName };

packages/twenty-apps/fixtures/postcard-app/src/logic-functions/on-post-card-created.function.ts

@@ -1,4 +1,4 @@
-import { defineLogicFunction } from '@/sdk';
+import { defineLogicFunction } from 'twenty-sdk';
 
 const handler = async () => {
   return { processed: true };

packages/twenty-apps/fixtures/postcard-app/src/logic-functions/test-function-2.function.ts

@@ -1,4 +1,4 @@
-import { defineLogicFunction } from '@/sdk';
+import { defineLogicFunction } from 'twenty-sdk';
 import { testFunction2 } from '../utils/test-function-2.util';
 
 export default defineLogicFunction({

packages/twenty-apps/fixtures/postcard-app/src/logic-functions/test-function.function.ts

@@ -1,4 +1,4 @@
-import { defineLogicFunction } from '@/sdk';
+import { defineLogicFunction } from 'twenty-sdk';
 import { formatFarewell } from '../utils/greeting.util';
 
 const handler = () => {

packages/twenty-apps/fixtures/postcard-app/src/navigation-menu-items/post-card-recipients.navigation-menu-item.ts

@@ -1,5 +1,5 @@
-import { defineNavigationMenuItem } from '@/sdk';
-import { ALL_POST_CARD_RECIPIENTS_VIEW_ID } from '@/cli/__tests__/apps/rich-app/src/views/all-post-card-recipients.view';
+import { defineNavigationMenuItem } from 'twenty-sdk';
+import { ALL_POST_CARD_RECIPIENTS_VIEW_ID } from '../views/all-post-card-recipients.view';
 
 export default defineNavigationMenuItem({
   universalIdentifier: 'c1a2b3c4-0003-4a7b-8c9d-0e1f2a3b4c5d',

packages/twenty-apps/fixtures/postcard-app/src/navigation-menu-items/post-cards.navigation-menu-item.ts

@@ -1,5 +1,5 @@
-import { defineNavigationMenuItem } from '@/sdk';
-import { ALL_POST_CARDS_VIEW_ID } from '@/cli/__tests__/apps/rich-app/src/views/all-post-cards.view';
+import { defineNavigationMenuItem } from 'twenty-sdk';
+import { ALL_POST_CARDS_VIEW_ID } from '../views/all-post-cards.view';
 
 export default defineNavigationMenuItem({
   universalIdentifier: 'c1a2b3c4-0001-4a7b-8c9d-0e1f2a3b4c5d',

packages/twenty-apps/fixtures/postcard-app/src/navigation-menu-items/recipients.navigation-menu-item.ts

@@ -1,5 +1,5 @@
-import { defineNavigationMenuItem } from '@/sdk';
-import { ALL_RECIPIENTS_VIEW_ID } from '@/cli/__tests__/apps/rich-app/src/views/all-recipients.view';
+import { defineNavigationMenuItem } from 'twenty-sdk';
+import { ALL_RECIPIENTS_VIEW_ID } from '../views/all-recipients.view';
 
 export default defineNavigationMenuItem({
   universalIdentifier: 'c1a2b3c4-0002-4a7b-8c9d-0e1f2a3b4c5d',

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

@@ -1,4 +1,4 @@
-import { defineObject, FieldType } from '@/sdk';
+import { defineObject, FieldType } from 'twenty-sdk';
 
 export const POST_CARD_RECIPIENT_UNIVERSAL_IDENTIFIER =
   'e1a2b3c4-5e6f-4a7b-8c9d-0e1f2a3b4c5e';

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

@@ -1,4 +1,4 @@
-import { defineObject, FieldType } from '@/sdk';
+import { defineObject, FieldType } from 'twenty-sdk';
 
 enum PostCardStatus {
   DRAFT = 'DRAFT',

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

@@ -1,4 +1,4 @@
-import { defineObject, FieldType } from '@/sdk';
+import { defineObject, FieldType } from 'twenty-sdk';
 
 export const RECIPIENT_UNIVERSAL_IDENTIFIER =
   'd1a2b3c4-5e6f-4a7b-8c9d-0e1f2a3b4c5d';

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

@@ -1,8 +1,8 @@
-import { PermissionFlag, defineRole } from '@/sdk';
+import { PermissionFlag, defineRole } from 'twenty-sdk';
 import {
   CONTENT_FIELD_UNIVERSAL_IDENTIFIER,
   POST_CARD_UNIVERSAL_IDENTIFIER,
-} from '@/cli/__tests__/apps/rich-app/src/objects/post-card.object';
+} from '../objects/post-card.object';
 
 export const DEFAULT_ROLE_UNIVERSAL_IDENTIFIER =
   'b648f87b-1d26-4961-b974-0908fd991061';

packages/twenty-apps/fixtures/postcard-app/src/root.front-component.tsx

@@ -1,4 +1,4 @@
-import { defineFrontComponent } from '@/sdk';
+import { defineFrontComponent } from 'twenty-sdk';
 
 export const RootComponent = () => {
   return (

packages/twenty-apps/fixtures/postcard-app/src/root.function.ts

@@ -1,4 +1,4 @@
-import { defineLogicFunction } from '@/sdk';
+import { defineLogicFunction } from 'twenty-sdk';
 
 const rootHandler = () => {
   return 'root-function-result';

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

@@ -1,4 +1,4 @@
-import { defineObject, FieldType } from '@/sdk';
+import { defineObject, FieldType } from 'twenty-sdk';
 
 export default defineObject({
   universalIdentifier: 'b0b1b2b3-b4b5-4000-8000-000000000001',

packages/twenty-apps/fixtures/postcard-app/src/root.role.ts

@@ -1,4 +1,4 @@
-import { defineRole } from '@/sdk';
+import { defineRole } from 'twenty-sdk';
 
 export default defineRole({
   universalIdentifier: 'c0c1c2c3-c4c5-4000-8000-000000000001',

packages/twenty-apps/fixtures/postcard-app/src/views/all-post-card-recipients.view.ts

@@ -1,8 +1,8 @@
 import {
   POST_CARD_RECIPIENT_UNIVERSAL_IDENTIFIER,
   SENT_AT_FIELD_UNIVERSAL_IDENTIFIER,
-} from '@/cli/__tests__/apps/rich-app/src/objects/post-card-recipient.object';
-import { defineView } from '@/sdk';
+} from '../objects/post-card-recipient.object';
+import { defineView } from 'twenty-sdk';
 import { ViewType } from 'twenty-shared/types';
 
 export const ALL_POST_CARD_RECIPIENTS_VIEW_ID =

packages/twenty-apps/fixtures/postcard-app/src/views/all-post-cards.view.ts

@@ -1,8 +1,8 @@
-import { defineView } from '@/sdk';
+import { defineView } from 'twenty-sdk';
 import {
   CONTENT_FIELD_UNIVERSAL_IDENTIFIER,
   POST_CARD_UNIVERSAL_IDENTIFIER,
-} from '@/cli/__tests__/apps/rich-app/src/objects/post-card.object';
+} from '../objects/post-card.object';
 import { ViewType } from 'twenty-shared/types';
 
 export const ALL_POST_CARDS_VIEW_ID = 'b1a2b3c4-0001-4a7b-8c9d-0e1f2a3b4c5d';

packages/twenty-apps/fixtures/postcard-app/src/views/all-recipients.view.ts

@@ -1,8 +1,8 @@
 import {
   RECIPIENT_EMAIL_FIELD_UNIVERSAL_IDENTIFIER,
   RECIPIENT_UNIVERSAL_IDENTIFIER,
-} from '@/cli/__tests__/apps/rich-app/src/objects/recipient.object';
-import { defineView } from '@/sdk';
+} from '../objects/recipient.object';
+import { defineView } from 'twenty-sdk';
 import { ViewType } from 'twenty-shared/types';
 
 export const ALL_RECIPIENTS_VIEW_ID = 'b1a2b3c4-0002-4a7b-8c9d-0e1f2a3b4c5d';

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

@@ -9,8 +9,9 @@
     "jsx": "react-jsx",
     "baseUrl": ".",
     "paths": {
-      "@/*": ["../../../../../src/*"]
+      "src/*": ["./src/*"]
     }
   },
-  "include": ["**/*"]
+  "include": ["**/*"],
+  "exclude": ["node_modules", "dist", ".twenty"]
 }

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

@@ -1,10 +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
+- Rich app example: https://github.com/twentyhq/twenty/tree/main/packages/twenty-sdk/src/app-seeds/rich-app
 
 ## UUID requirement
-
 - All generated UUIDs must be valid UUID v4.
 
 ## Common Pitfalls

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

@@ -1,7 +1,7 @@
 ## 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
+- Rich app example: https://github.com/twentyhq/twenty/tree/main/packages/twenty-sdk/src/app-seeds/rich-app
 
 ## Common Pitfalls
 

packages/twenty-apps/internal/call-recording/src/front-components/seed-call-recordings.tsx

@@ -5,7 +5,7 @@ import {
 } from 'src/constants/seed-call-recordings-universal-identifiers';
 import { MOCK_CALL_RECORDINGS } from 'src/data/mock-call-recordings';
 import { defineFrontComponent } from 'twenty-sdk';
-import { CoreApiClient } from 'twenty-sdk/generated';
+import { CoreApiClient } from 'twenty-sdk/clients';
 
 type SeedStatus = 'seeding' | 'done' | 'error';
 

packages/twenty-apps/internal/call-recording/src/front-components/summarize-person-recordings.tsx

@@ -6,7 +6,7 @@ import {
   SUMMARIZE_PERSON_RECORDINGS_FRONT_COMPONENT_UNIVERSAL_IDENTIFIER,
 } from 'src/constants/summarize-person-recordings-universal-identifiers';
 import { defineFrontComponent, useRecordId } from 'twenty-sdk';
-import { CoreApiClient } from 'twenty-sdk/generated';
+import { CoreApiClient } from 'twenty-sdk/clients';
 import { isDefined } from 'twenty-shared/utils';
 
 const SUMMARIZATION_SYSTEM_PROMPT = [
@@ -40,7 +40,9 @@ const summarizeAllRecordings = async (
   const summariesText = recordings
     .map(
       (recording, index) =>
-        `### ${index + 1}. ${recording.name ?? 'Untitled'} (${recording.createdAt})\n${recording.summary?.markdown ?? 'No summary available'}`,
+        `### ${index + 1}. ${recording.name ?? 'Untitled'} (${
+          recording.createdAt
+        })\n${recording.summary?.markdown ?? 'No summary available'}`,
     )
     .join('\n\n---\n\n');
 

packages/twenty-apps/internal/call-recording/src/hooks/useCallRecording.ts

@@ -1,6 +1,6 @@
 import { useEffect, useState } from 'react';
 import { useRecordId } from 'twenty-sdk';
-import { CoreApiClient } from 'twenty-sdk/generated';
+import { CoreApiClient } from 'twenty-sdk/clients';
 import { isDefined } from 'twenty-shared/utils';
 
 type CallRecording = {

packages/twenty-apps/internal/call-recording/src/logic-functions/end-recording.ts

@@ -8,7 +8,7 @@ import {
 } from 'src/utils/match-participants';
 import { summarizeTranscript } from 'src/utils/summarize-transcript';
 import { defineLogicFunction } from 'twenty-sdk';
-import { CoreApiClient, MetadataApiClient } from 'twenty-sdk/generated';
+import { CoreApiClient, MetadataApiClient } from 'twenty-sdk/clients';
 import { z } from 'zod';
 
 interface LocalTranscriptWord {

packages/twenty-apps/internal/call-recording/src/utils/match-participants.ts

@@ -1,4 +1,4 @@
-import { CoreApiClient } from 'twenty-sdk/generated';
+import { CoreApiClient } from 'twenty-sdk/clients';
 
 export interface Participant {
   id: string;

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

@@ -5,8 +5,14 @@ import {
   type ObjectRecordUpdateEvent,
 } from 'twenty-sdk';
 import { SELF_HOSTING_USER_NAME_SINGULAR } from 'src/objects/selfHostingUser.object';
-import { type SelfHostingUser } from 'twenty-sdk/generated/core';
-import { CoreApiClient } from 'twenty-sdk/generated';
+import { CoreApiClient } from 'twenty-sdk/clients';
+
+type SelfHostingUser = {
+  id: string;
+  email?: { primaryEmail?: string };
+  name?: { firstName?: string; lastName?: string };
+  personId?: string;
+};
 
 const handler = async (
   params: DatabaseEventPayload<

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

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

packages/twenty-docker/twenty/Dockerfile

@@ -15,6 +15,7 @@ COPY ./packages/twenty-ui/package.json /app/packages/twenty-ui/
 COPY ./packages/twenty-shared/package.json /app/packages/twenty-shared/
 COPY ./packages/twenty-front/package.json /app/packages/twenty-front/
 COPY ./packages/twenty-sdk/package.json /app/packages/twenty-sdk/
+COPY ./packages/twenty-standard-application/package.json /app/packages/twenty-standard-application/
 
 # Install all dependencies
 RUN yarn && yarn cache clean && npx nx reset
@@ -26,11 +27,15 @@ FROM common-deps AS twenty-server-build
 # Copy sourcecode after installing dependences to accelerate subsequents builds
 COPY ./packages/twenty-emails /app/packages/twenty-emails
 COPY ./packages/twenty-shared /app/packages/twenty-shared
+COPY ./packages/twenty-ui /app/packages/twenty-ui
+COPY ./packages/twenty-sdk /app/packages/twenty-sdk
+COPY ./packages/twenty-standard-application /app/packages/twenty-standard-application
 COPY ./packages/twenty-server /app/packages/twenty-server
 
+RUN npx nx build twenty-standard-application
 RUN npx nx run twenty-server:build
 
-RUN yarn workspaces focus --production twenty-emails twenty-shared twenty-server
+RUN yarn workspaces focus --production twenty-emails twenty-shared twenty-sdk twenty-standard-application twenty-server
 
 # Build the front
 FROM common-deps AS twenty-front-build

packages/twenty-docs/developers/extend/api.mdx

@@ -0,0 +1,140 @@
+---
+title: APIs
+description: Query and modify your CRM data programmatically using REST or GraphQL.
+---
+
+import { VimeoEmbed } from '/snippets/vimeo-embed.mdx';
+
+Twenty was built to be developer-friendly, offering powerful APIs that adapt to your custom data model. We provide four distinct API types to meet different integration needs.
+
+## Developer-First Approach
+
+Twenty generates APIs specifically for your data model:
+- **No long IDs required**: Use your object and field names directly in endpoints
+- **Standard and custom objects treated equally**: Your custom objects get the same API treatment as built-in ones
+- **Dedicated endpoints**: Each object and field gets its own API endpoint
+- **Custom documentation**: Generated specifically for your workspace's data model
+
+<Note>
+Your personalized API documentation is available under **Settings → API & Webhooks** after creating an API key. Since Twenty generates APIs that match your custom data model, the documentation is unique to your workspace.
+</Note>
+
+## The Two API Types
+
+### Core API
+Accessed on `/rest/` or `/graphql/`
+
+Work with your actual **records** (the data):
+- Create, read, update, delete People, Companies, Opportunities, etc.
+- Query and filter data
+- Manage record relationships
+
+### Metadata API
+Accessed on `/rest/metadata/` or `/metadata/`
+
+Manage your **workspace and data model**:
+- Create, modify, or delete objects and fields
+- Configure workspace settings
+- Define relationships between objects
+
+## REST vs GraphQL
+
+Both Core and Metadata APIs are available in REST and GraphQL formats:
+
+| Format | Available Operations |
+|--------|---------------------|
+| **REST** | CRUD, batch operations, upserts |
+| **GraphQL** | Same + **batch upserts**, relationship queries in one call |
+
+Choose based on your needs — both formats access the same data.
+
+## API Endpoints
+
+| Environment | Base URL |
+|-------------|----------|
+| **Cloud** | `https://api.twenty.com/` |
+| **Self-Hosted** | `https://{your-domain}/` |
+
+## Authentication
+
+Every API request requires an API key in the header:
+
+```
+Authorization: Bearer YOUR_API_KEY
+```
+
+### Create an API Key
+
+1. Go to **Settings → APIs & Webhooks**
+2. Click **+ Create key**
+3. Configure:
+   - **Name**: Descriptive name for the key
+   - **Expiration Date**: When the key expires
+4. Click **Save**
+5. **Copy immediately** — the key is only shown once
+
+<VimeoEmbed videoId="928786722" title="Creating API key" />
+
+<Warning>
+Your API key grants access to sensitive data. Don't share it with untrusted services. If compromised, disable it immediately and generate a new one.
+</Warning>
+
+### Assign a Role to an API Key
+
+For better security, assign a specific role to limit access:
+
+1. Go to **Settings → Roles**
+2. Click on the role to assign
+3. Open the **Assignment** tab
+4. Under **API Keys**, click **+ Assign to API key**
+5. Select the API key
+
+The key will inherit that role's permissions. See [Permissions](/user-guide/permissions-access/capabilities/permissions) for details.
+
+### Manage API Keys
+
+**Regenerate**: Settings → APIs & Webhooks → Click key → **Regenerate**
+
+**Delete**: Settings → APIs & Webhooks → Click key → **Delete**
+
+## API Playground
+
+Test your APIs directly in the browser with our built-in playground — available for both **REST** and **GraphQL**.
+
+### Access the Playground
+
+1. Go to **Settings → APIs & Webhooks**
+2. Create an API key (required)
+3. Click on **REST API** or **GraphQL API** to open the playground
+
+### What You Get
+
+- **Interactive documentation**: Generated for your specific data model
+- **Live testing**: Execute real API calls against your workspace
+- **Schema explorer**: Browse available objects, fields, and relationships
+- **Request builder**: Construct queries with autocomplete
+
+The playground reflects your custom objects and fields, so documentation is always accurate for your workspace.
+
+## Batch Operations
+
+Both REST and GraphQL support batch operations:
+- **Batch size**: Up to 60 records per request
+- **Operations**: Create, update, delete multiple records
+
+**GraphQL-only features:**
+- **Batch Upsert**: Create or update in one call
+- Use plural object names (e.g., `CreateCompanies` instead of `CreateCompany`)
+
+## Rate Limits
+
+API requests are throttled to ensure platform stability:
+
+| Limit | Value |
+|-------|-------|
+| **Requests** | 100 calls per minute |
+| **Batch size** | 60 records per call |
+
+<Tip>
+Use batch operations to maximize throughput — process up to 60 records in a single API call instead of making individual requests.
+</Tip>

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

@@ -0,0 +1,677 @@
+---
+title: Building Apps
+description: Define objects, logic functions, front components, and more with the Twenty SDK.
+---
+
+<Warning>
+Apps are currently in alpha testing. The feature is functional but still evolving.
+</Warning>
+
+## Use the SDK resources (types & config)
+
+The twenty-sdk provides typed building blocks and helper functions you use inside your app. Below are the key pieces you'll touch most often.
+
+### Helper functions
+
+The SDK provides helper functions for defining your app entities. As described in [Entity detection](/developers/extend/apps/getting-started#entity-detection), you must use `export default define<Entity>({...})` for your entities to be detected:
+
+| Function | Purpose |
+|----------|---------|
+| `defineApplication` | Configure application metadata (required, one per app) |
+| `defineObject` | Define custom objects with fields |
+| `defineLogicFunction` | Define logic functions with handlers |
+| `definePreInstallLogicFunction` | Define a pre-install logic function (one per app) |
+| `definePostInstallLogicFunction` | Define a post-install logic function (one per app) |
+| `defineFrontComponent` | Define front components for custom UI |
+| `defineRole` | Configure role permissions and object access |
+| `defineField` | Extend existing objects with additional fields |
+| `defineView` | Define saved views for objects |
+| `defineNavigationMenuItem` | Define sidebar navigation links |
+| `defineSkill` | Define AI agent skills |
+
+These functions validate your configuration at build time and provide IDE autocompletion and type safety.
+
+### Defining objects
+
+Custom objects describe both schema and behavior for records in your workspace. Use `defineObject()` to define objects with built-in validation:
+
+```typescript
+// src/app/postCard.object.ts
+import { defineObject, FieldType } from 'twenty-sdk';
+
+enum PostCardStatus {
+  DRAFT = 'DRAFT',
+  SENT = 'SENT',
+  DELIVERED = 'DELIVERED',
+  RETURNED = 'RETURNED',
+}
+
+export default defineObject({
+  universalIdentifier: '54b589ca-eeed-4950-a176-358418b85c05',
+  nameSingular: 'postCard',
+  namePlural: 'postCards',
+  labelSingular: 'Post Card',
+  labelPlural: 'Post Cards',
+  description: 'A post card object',
+  icon: 'IconMail',
+  fields: [
+    {
+      universalIdentifier: '58a0a314-d7ea-4865-9850-7fb84e72f30b',
+      name: 'content',
+      type: FieldType.TEXT,
+      label: 'Content',
+      description: "Postcard's content",
+      icon: 'IconAbc',
+    },
+    {
+      universalIdentifier: 'c6aa31f3-da76-4ac6-889f-475e226009ac',
+      name: 'recipientName',
+      type: FieldType.FULL_NAME,
+      label: 'Recipient name',
+      icon: 'IconUser',
+    },
+    {
+      universalIdentifier: '95045777-a0ad-49ec-98f9-22f9fc0c8266',
+      name: 'recipientAddress',
+      type: FieldType.ADDRESS,
+      label: 'Recipient address',
+      icon: 'IconHome',
+    },
+    {
+      universalIdentifier: '87b675b8-dd8c-4448-b4ca-20e5a2234a1e',
+      name: 'status',
+      type: FieldType.SELECT,
+      label: 'Status',
+      icon: 'IconSend',
+      defaultValue: `'${PostCardStatus.DRAFT}'`,
+      options: [
+        { value: PostCardStatus.DRAFT, label: 'Draft', position: 0, color: 'gray' },
+        { value: PostCardStatus.SENT, label: 'Sent', position: 1, color: 'orange' },
+        { value: PostCardStatus.DELIVERED, label: 'Delivered', position: 2, color: 'green' },
+        { value: PostCardStatus.RETURNED, label: 'Returned', position: 3, color: 'orange' },
+      ],
+    },
+    {
+      universalIdentifier: 'e06abe72-5b44-4e7f-93be-afc185a3c433',
+      name: 'deliveredAt',
+      type: FieldType.DATE_TIME,
+      label: 'Delivered at',
+      icon: 'IconCheck',
+      isNullable: true,
+      defaultValue: null,
+    },
+  ],
+});
+```
+
+Key points:
+
+- Use `defineObject()` for built-in validation and better IDE support.
+- The `universalIdentifier` must be unique and stable across deployments.
+- Each field requires a `name`, `type`, `label`, and its own stable `universalIdentifier`.
+- The `fields` array is optional — you can define objects without custom fields.
+- You can scaffold new objects using `yarn twenty 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 `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>
+
+
+### Application config (application-config.ts)
+
+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) pre-install function**: a logic function that runs before the app is installed.
+- **(Optional) post-install function**: a logic function that runs after the app is installed.
+
+Use `defineApplication()` to define your application configuration:
+
+```typescript
+// src/application-config.ts
+import { defineApplication } from 'twenty-sdk';
+import { DEFAULT_ROLE_UNIVERSAL_IDENTIFIER } from 'src/roles/default-role';
+
+export default defineApplication({
+  universalIdentifier: '4ec0391d-18d5-411c-b2f3-266ddc1c3ef7',
+  displayName: 'My Twenty App',
+  description: 'My first Twenty app',
+  icon: 'IconWorld',
+  applicationVariables: {
+    DEFAULT_RECIPIENT_NAME: {
+      universalIdentifier: '19e94e59-d4fe-4251-8981-b96d0a9f74de',
+      description: 'Default recipient name for postcards',
+      value: 'Jane Doe',
+      isSecret: false,
+    },
+  },
+  defaultRoleUniversalIdentifier: DEFAULT_ROLE_UNIVERSAL_IDENTIFIER,
+});
+```
+
+Notes:
+- `universalIdentifier` fields are deterministic IDs you own; generate them once and keep them stable across syncs.
+- `applicationVariables` become environment variables for your functions (for example, `DEFAULT_RECIPIENT_NAME` is available as `process.env.DEFAULT_RECIPIENT_NAME`).
+- `defaultRoleUniversalIdentifier` must match the role file (see below).
+- Pre-install and post-install functions are automatically detected during the manifest build. See [Pre-install functions](#pre-install-functions) and [Post-install functions](#post-install-functions).
+
+#### Roles and permissions
+
+Applications can define roles that encapsulate permissions on your workspace's objects and actions. The field `defaultRoleUniversalIdentifier` in `application-config.ts` designates the default role used by your app's logic functions.
+
+- The runtime API key injected as `TWENTY_API_KEY` is derived from this default function role.
+- The typed client will be restricted to the permissions granted to that role.
+- Follow least‑privilege: create a dedicated role with only the permissions your functions need, then reference its universal identifier.
+
+##### Default function role (*.role.ts)
+
+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/roles/default-role.ts
+import { defineRole, PermissionFlag } from 'twenty-sdk';
+
+export const DEFAULT_ROLE_UNIVERSAL_IDENTIFIER =
+  'b648f87b-1d26-4961-b974-0908fd991061';
+
+export default defineRole({
+  universalIdentifier: DEFAULT_ROLE_UNIVERSAL_IDENTIFIER,
+  label: 'Default function role',
+  description: 'Default role for function Twenty client',
+  canReadAllObjectRecords: false,
+  canUpdateAllObjectRecords: false,
+  canSoftDeleteAllObjectRecords: false,
+  canDestroyAllObjectRecords: false,
+  canUpdateAllSettings: false,
+  canBeAssignedToAgents: false,
+  canBeAssignedToUsers: false,
+  canBeAssignedToApiKeys: false,
+  objectPermissions: [
+    {
+      objectUniversalIdentifier: '9f9882af-170c-4879-b013-f9628b77c050',
+      canReadObjectRecords: true,
+      canUpdateObjectRecords: true,
+      canSoftDeleteObjectRecords: false,
+      canDestroyObjectRecords: false,
+    },
+  ],
+  fieldPermissions: [
+    {
+      objectUniversalIdentifier: '9f9882af-170c-4879-b013-f9628b77c050',
+      fieldUniversalIdentifier: 'b2c37dc0-8ae7-470e-96cd-1476b47dfaff',
+      canReadFieldValue: false,
+      canUpdateFieldValue: false,
+    },
+  ],
+  permissionFlags: [PermissionFlag.APPLICATIONS],
+});
+```
+
+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.
+
+Notes:
+- Start from the scaffolded role, then progressively restrict it following least‑privilege.
+- Replace the `objectPermissions` and `fieldPermissions` with the objects/fields your functions need.
+- `permissionFlags` control access to platform-level capabilities. Keep them minimal; add only what you need.
+- See a working example in the Hello World app: [`packages/twenty-apps/hello-world/src/roles/function-role.ts`](https://github.com/twentyhq/twenty/blob/main/packages/twenty-apps/hello-world/src/roles/function-role.ts).
+
+### Logic function config and entrypoint
+
+Each function file uses `defineLogicFunction()` to export a configuration with a handler and optional triggers.
+
+```typescript
+// src/app/createPostCard.logic-function.ts
+import { defineLogicFunction } from 'twenty-sdk';
+import type { DatabaseEventPayload, ObjectRecordCreateEvent, CronPayload, RoutePayload } from 'twenty-sdk';
+import { CoreApiClient, type Person } from 'twenty-sdk/generated';
+
+const handler = async (params: RoutePayload) => {
+  const client = new CoreApiClient();
+  const name = 'name' in params.queryStringParameters
+    ? params.queryStringParameters.name ?? process.env.DEFAULT_RECIPIENT_NAME ?? 'Hello world'
+    : 'Hello world';
+
+  const result = await client.mutation({
+    createPostCard: {
+      __args: { data: { name } },
+      id: true,
+      name: true,
+    },
+  });
+  return result;
+};
+
+export default defineLogicFunction({
+  universalIdentifier: 'e56d363b-0bdc-4d8a-a393-6f0d1c75bdcf',
+  name: 'create-new-post-card',
+  timeoutSeconds: 2,
+  handler,
+  triggers: [
+    // Public HTTP route trigger '/s/post-card/create'
+    {
+      universalIdentifier: 'c9f84c8d-b26d-40d1-95dd-4f834ae5a2c6',
+      type: 'route',
+      path: '/post-card/create',
+      httpMethod: 'GET',
+      isAuthRequired: false,
+    },
+    // Cron trigger (CRON pattern)
+    // {
+    //   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'],
+    // },
+  ],
+});
+```
+
+Common trigger types:
+- **route**: Exposes your function on an HTTP path and method **under the `/s/` endpoint**:
+> e.g. `path: '/post-card/create',` -> call on `<APP_URL>/s/post-card/create`
+- **cron**: Runs your function on a schedule using a CRON expression.
+- **databaseEvent**: Runs on workspace object lifecycle events. When the event operation is `updated`, specific fields to listen to can be specified in the `updatedFields` array. If left undefined or empty, any update will trigger the function.
+> e.g. `person.updated`
+
+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.
+
+### Pre-install functions
+
+A pre-install function is a logic function that runs automatically before your app is installed on a workspace. This is useful for validation tasks, prerequisite checks, or preparing workspace state before the main installation proceeds.
+
+When you scaffold a new app with `create-twenty-app`, a pre-install function is generated for you at `src/logic-functions/pre-install.ts`:
+
+```typescript
+// src/logic-functions/pre-install.ts
+import { definePreInstallLogicFunction, type InstallLogicFunctionPayload } from 'twenty-sdk';
+
+const handler = async (payload: InstallLogicFunctionPayload): Promise<void> => {
+  console.log('Pre install logic function executed successfully!', payload.previousVersion);
+};
+
+export default definePreInstallLogicFunction({
+  universalIdentifier: '<generated-uuid>',
+  name: 'pre-install',
+  description: 'Runs before installation to prepare the application.',
+  timeoutSeconds: 300,
+  handler,
+});
+```
+
+You can also manually execute the pre-install function at any time using the CLI:
+
+```bash filename="Terminal"
+yarn twenty function:execute --preInstall
+```
+
+Key points:
+- Pre-install functions use `definePreInstallLogicFunction()` — a specialized variant that omits trigger settings (`cronTriggerSettings`, `databaseEventTriggerSettings`, `httpRouteTriggerSettings`, `isTool`).
+- The handler receives an `InstallLogicFunctionPayload` with `{ previousVersion: string }` — the version of the app that was previously installed (or an empty string for fresh installs).
+- Only one pre-install function is allowed per application. The manifest build will error if more than one is detected.
+- The function's `universalIdentifier` is automatically set as `preInstallLogicFunctionUniversalIdentifier` on the application manifest during the build — you do not need to reference it in `defineApplication()`.
+- The default timeout is set to 300 seconds (5 minutes) to allow for longer preparation tasks.
+- Pre-install functions do not need triggers — they are invoked by the platform before installation or manually via `function:execute --preInstall`.
+
+### 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 { definePostInstallLogicFunction, type InstallLogicFunctionPayload } from 'twenty-sdk';
+
+const handler = async (payload: InstallLogicFunctionPayload): Promise<void> => {
+  console.log('Post install logic function executed successfully!', payload.previousVersion);
+};
+
+export default definePostInstallLogicFunction({
+  universalIdentifier: '<generated-uuid>',
+  name: 'post-install',
+  description: 'Runs after installation to set up the application.',
+  timeoutSeconds: 300,
+  handler,
+});
+```
+
+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 use `definePostInstallLogicFunction()` — a specialized variant that omits trigger settings (`cronTriggerSettings`, `databaseEventTriggerSettings`, `httpRouteTriggerSettings`, `isTool`).
+- The handler receives an `InstallLogicFunctionPayload` with `{ previousVersion: string }` — the version of the app that was previously installed (or an empty string for fresh installs).
+- Only one post-install function is allowed per application. The manifest build will error if more than one is detected.
+- The function's `universalIdentifier` is automatically set as `postInstallLogicFunctionUniversalIdentifier` on the application manifest during the build — you do not need to reference it in `defineApplication()`.
+- The default timeout is set to 300 seconds (5 minutes) to allow for longer setup tasks like data seeding.
+- Post-install functions do not need triggers — they are invoked by the platform during installation or manually via `function:execute --postInstall`.
+
+### Route trigger payload
+
+<Warning>
+**Breaking change (v1.16, January 2026):** The route trigger payload format has changed. Prior to v1.16, query parameters, path parameters, and body were sent directly as the payload. Starting with v1.16, they are nested inside a structured `RoutePayload` object.
+
+**Before v1.16:**
+```typescript
+const handler = async (params) => {
+  const { param1, param2 } = params; // Direct access
+};
+```
+
+**After v1.16:**
+```typescript
+const handler = async (event: RoutePayload) => {
+  const { param1, param2 } = event.body; // Access via .body
+  const { queryParam } = event.queryStringParameters;
+  const { id } = event.pathParameters;
+};
+```
+
+**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 logic function, it receives a `RoutePayload` object that follows the AWS HTTP API v2 format. Import the type from `twenty-sdk`:
+
+```typescript
+import { defineLogicFunction, type RoutePayload } from 'twenty-sdk';
+
+const handler = async (event: RoutePayload) => {
+  // Access request data
+  const { headers, queryStringParameters, pathParameters, body } = event;
+
+  // HTTP method and path are available in requestContext
+  const { method, path } = event.requestContext.http;
+
+  return { message: 'Success' };
+};
+```
+
+The `RoutePayload` type has the following structure:
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `headers` | `Record<string, string \| undefined>` | HTTP headers (only those listed in `forwardedRequestHeaders`) |
+| `queryStringParameters` | `Record<string, string \| undefined>` | Query string parameters (multiple values joined with commas) |
+| `pathParameters` | `Record<string, string \| undefined>` | Path parameters extracted from the route pattern (e.g., `/users/:id` → `{ id: '123' }`) |
+| `body` | `object \| null` | Parsed request body (JSON) |
+| `isBase64Encoded` | `boolean` | Whether the body is base64 encoded |
+| `requestContext.http.method` | `string` | HTTP method (GET, POST, PUT, PATCH, DELETE) |
+| `requestContext.http.path` | `string` | Raw request path |
+
+### Forwarding HTTP headers
+
+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 defineLogicFunction({
+  universalIdentifier: 'e56d363b-0bdc-4d8a-a393-6f0d1c75bdcf',
+  name: 'webhook-handler',
+  handler,
+  triggers: [
+    {
+      universalIdentifier: 'c9f84c8d-b26d-40d1-95dd-4f834ae5a2c6',
+      type: 'route',
+      path: '/webhook',
+      httpMethod: 'POST',
+      isAuthRequired: false,
+      forwardedRequestHeaders: ['x-webhook-signature', 'content-type'],
+    },
+  ],
+});
+```
+
+In your handler, you can then access these headers:
+
+```typescript
+const handler = async (event: RoutePayload) => {
+  const signature = event.headers['x-webhook-signature'];
+  const contentType = event.headers['content-type'];
+
+  // Validate webhook signature...
+  return { received: true };
+};
+```
+
+<Note>
+  Header names are normalized to lowercase. Access them using lowercase keys (for example, `event.headers['content-type']`).
+</Note>
+
+You can create new functions in two ways:
+
+- **Scaffolded**: Run `yarn twenty entity:add` and choose the option to add a new logic function. This generates a starter file with a handler and config.
+- **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 { CoreApiClient } from 'twenty-sdk/generated';
+
+const handler = async (params: { companyName: string; domain?: string }) => {
+  const client = new CoreApiClient();
+
+  const result = await client.mutation({
+    createTask: {
+      __args: {
+        data: {
+          title: `Enrich data for ${params.companyName}`,
+          body: `Domain: ${params.domain ?? 'unknown'}`,
+        },
+      },
+      id: true,
+    },
+  });
+
+  return { taskId: result.createTask.id };
+};
+
+export default defineLogicFunction({
+  universalIdentifier: 'f47ac10b-58cc-4372-a567-0e02b2c3d479',
+  name: 'enrich-company',
+  description: 'Enrich a company record with external data',
+  timeoutSeconds: 10,
+  handler,
+  isTool: true,
+  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/front-components/my-widget.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.
+- 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 `.tsx` file and use `defineFrontComponent()`, following the same pattern.
+
+### 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 clients
+
+Two typed clients are auto-generated by `yarn twenty app:dev` and stored in `node_modules/twenty-sdk/generated` based on your workspace schema:
+
+- **`CoreApiClient`** — queries the `/graphql` endpoint for workspace data
+- **`MetadataApiClient`** — queries the `/metadata` endpoint for workspace configuration and file uploads
+
+```typescript
+import { CoreApiClient, MetadataApiClient } from 'twenty-sdk/generated';
+
+const client = new CoreApiClient();
+const { me } = await client.query({ me: { id: true, displayName: true } });
+
+const metadataClient = new MetadataApiClient();
+const { currentWorkspace } = await metadataClient.query({ currentWorkspace: { id: true } });
+```
+
+Both clients are re-generated automatically by `yarn twenty app:dev` whenever your objects or fields change.
+
+#### Runtime credentials in logic functions
+
+When your function runs on Twenty, the platform injects credentials as environment variables before your code executes:
+
+- `TWENTY_API_URL`: Base URL of the Twenty API your app targets.
+- `TWENTY_API_KEY`: Short‑lived key scoped to your application's default function role.
+
+Notes:
+- You do not need to pass URL or API key to the generated client. It reads `TWENTY_API_URL` and `TWENTY_API_KEY` from process.env at runtime.
+- The API key's permissions are determined by the role referenced in your `application-config.ts` via `defaultRoleUniversalIdentifier`. This is the default role used by logic functions of your application.
+- Applications can define roles to follow least‑privilege. Grant only the permissions your functions need, then point `defaultRoleUniversalIdentifier` to that role's universal identifier.
+
+#### Uploading files
+
+The generated `MetadataApiClient` includes an `uploadFile` method for attaching files to file-type fields on your workspace objects. Because standard GraphQL clients do not support multipart file uploads natively, the client provides this dedicated method that implements the [GraphQL multipart request specification](https://github.com/jaydenseric/graphql-multipart-request-spec) under the hood.
+
+```typescript
+import { MetadataApiClient } from 'twenty-sdk/generated';
+import * as fs from 'fs';
+
+const metadataClient = new MetadataApiClient();
+
+const fileBuffer = fs.readFileSync('./invoice.pdf');
+
+const uploadedFile = await metadataClient.uploadFile(
+  fileBuffer,                                         // file contents as a Buffer
+  'invoice.pdf',                                      // filename
+  'application/pdf',                                  // MIME type (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 `uploadFile` method is available on `MetadataApiClient` because the upload mutation is resolved by the `/metadata` endpoint.
+- It uses the field's `universalIdentifier` (not its workspace-specific ID), so your upload code works across any workspace where your app is installed — consistent with how apps reference fields everywhere else.
+- 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, logic functions, front components, and multiple triggers [here](https://github.com/twentyhq/twenty/tree/main/packages/twenty-apps/hello-world).

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

@@ -0,0 +1,231 @@
+---
+title: Getting Started
+description: Create your first Twenty app in minutes.
+---
+
+<Warning>
+Apps are currently in alpha testing. The feature is functional but still evolving.
+</Warning>
+
+Apps let you extend Twenty with custom objects, fields, logic functions, AI skills, and UI components — all managed as code.
+
+**What you can do today:**
+- Define custom objects and fields as code (managed data model)
+- Build logic functions with custom triggers (HTTP routes, cron, database events)
+- Define skills for AI agents
+- Build front components that render inside Twenty's UI
+- Deploy the same app across multiple workspaces
+
+## Prerequisites
+
+- Node.js 24+ and Yarn 4
+- A Twenty workspace and an API key (create one at https://app.twenty.com/settings/api-webhooks)
+
+## Getting Started
+
+Create a new app using the official scaffolder, then authenticate and start developing:
+
+```bash filename="Terminal"
+# Scaffold a new app (includes all examples by default)
+npx create-twenty-app@latest my-twenty-app
+cd my-twenty-app
+
+# Start dev mode: automatically syncs local changes to your workspace
+yarn twenty app:dev
+```
+
+The scaffolder supports two modes for controlling which example files are included:
+
+```bash filename="Terminal"
+# Default (exhaustive): all examples (object, field, logic function, front component, view, navigation menu item, skill)
+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
+```
+
+From here you can:
+
+```bash filename="Terminal"
+# Add a new entity to your application (guided)
+yarn twenty entity:add
+
+# Watch your application's function logs
+yarn twenty function:logs
+
+# Execute a function by name
+yarn twenty function:execute -n my-function -p '{"name": "test"}'
+
+# Execute the pre-install function
+yarn twenty function:execute --preInstall
+
+# Execute the post-install function
+yarn twenty function:execute --postInstall
+
+# Uninstall the application from the current workspace
+yarn twenty app:uninstall
+
+# Display commands' 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).
+
+## Project structure (scaffolded)
+
+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 core files (application config, default function role, pre-install and post-install functions) plus example files based on the scaffolding mode
+
+A freshly scaffolded app with the default `--exhaustive` mode looks like this:
+
+```text filename="my-twenty-app/"
+my-twenty-app/
+  package.json
+  yarn.lock
+  .gitignore
+  .nvmrc
+  .yarnrc.yml
+  .yarn/
+    install-state.gz
+  .oxlintrc.json
+  tsconfig.json
+  README.md
+  public/                           # Public assets folder (images, fonts, etc.)
+  src/
+  ├── 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
+  │   ├── pre-install.ts                # Pre-install 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
+```
+
+With `--minimal`, only the core files are created (`application-config.ts`, `roles/default-role.ts`, `logic-functions/pre-install.ts`, and `logic-functions/post-install.ts`).
+
+At a high level:
+
+- **package.json**: Declares the app name, version, engines (Node 24+, Yarn 4), and adds `twenty-sdk` plus a `twenty` script that delegates to the local `twenty` CLI. Run `yarn twenty help` to list all available commands.
+- **.gitignore**: Ignores common artifacts such as `node_modules`, `.yarn`, `generated/` (typed client), `dist/`, `build/`, coverage folders, log files, and `.env*` files.
+- **yarn.lock**, **.yarnrc.yml**, **.yarn/**: Lock and configure the Yarn 4 toolchain used by the project.
+- **.nvmrc**: Pins the Node.js version expected by the project.
+- **.oxlintrc.json** and **tsconfig.json**: Provide linting and TypeScript configuration for your app's TypeScript sources.
+- **README.md**: A short README in the app root with basic instructions.
+- **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 |
+| `definePreInstallLogicFunction` | Pre-install logic function (runs before installation) |
+| `definePostInstallLogicFunction` | Post-install logic function (runs after installation) |
+| `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 twenty app:dev` will auto-generate two typed API clients in `node_modules/twenty-sdk/generated`: `CoreApiClient` (for workspace data via `/graphql`) and `MetadataApiClient` (for workspace configuration and file uploads via `/metadata`).
+- `yarn twenty entity:add` will add entity definition files under `src/` for your custom objects, functions, front components, roles, skills, and more.
+
+## Authentication
+
+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
+
+Your credentials are stored per-user in `~/.twenty/config.json`. You can maintain multiple profiles and switch between them.
+
+### Managing workspaces
+
+```bash filename="Terminal"
+# Login interactively (recommended)
+yarn twenty auth:login
+
+# Login to a specific workspace profile
+yarn twenty auth:login --workspace my-custom-workspace
+
+# List all configured workspaces
+yarn twenty auth:list
+
+# Switch the default workspace (interactive)
+yarn twenty auth:switch
+
+# Switch to a specific workspace
+yarn twenty auth:switch production
+
+# Check current authentication status
+yarn twenty auth:status
+```
+
+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>`.
+
+## 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 a single script in your package.json:
+
+```bash filename="Terminal"
+yarn add -D twenty-sdk
+```
+
+Then add a `twenty` script:
+
+```json filename="package.json"
+{
+  "scripts": {
+    "twenty": "twenty"
+  }
+}
+```
+
+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 twenty auth:login` and ensure your API key has the required permissions.
+- Cannot connect to server: verify the API URL and that the Twenty server is reachable.
+- Types or client missing/outdated: restart `yarn twenty app:dev` — it auto-generates the typed client.
+- Dev mode not syncing: ensure `yarn twenty app:dev` is running and that changes are not ignored by your environment.
+
+Discord Help Channel: https://discord.com/channels/1130383047699738754/1130386664812982322

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

@@ -0,0 +1,119 @@
+---
+title: Publishing
+description: Distribute your Twenty app to the marketplace or deploy it internally.
+---
+
+<Warning>
+Apps are currently in alpha testing. The feature is functional but still evolving.
+</Warning>
+
+## Overview
+
+Once your app is [built and tested locally](/developers/extend/apps/building), you have two paths for distributing it:
+
+- **Publish to npm** — list your app in the Twenty marketplace for any workspace to discover and install.
+- **Push a tarball** — deploy your app to a specific Twenty server for internal use without making it publicly available.
+
+## Publishing to npm
+
+Publishing to npm makes your app discoverable in the Twenty marketplace. Any Twenty workspace can browse, install, and upgrade marketplace apps directly from the UI.
+
+### Requirements
+
+- An [npm](https://www.npmjs.com) account
+- Your package name **must** use the `twenty-app-` prefix (e.g., `twenty-app-postcard-sender`)
+
+### Steps
+
+1. **Build your app** — the CLI compiles your TypeScript sources and generates the application manifest:
+
+```bash filename="Terminal"
+yarn twenty app:build
+```
+
+2. **Publish to npm** — push the built package to the npm registry:
+
+```bash filename="Terminal"
+npx twenty app:publish
+```
+
+### Auto-discovery
+
+Packages with the `twenty-app-` prefix are automatically discovered by the Twenty marketplace catalog. Once published, your app appears in the marketplace within a few minutes — no manual registration or approval required.
+
+### CI publishing
+
+The scaffolded project includes a GitHub Actions workflow that publishes on every release. It runs `app:build`, then `npm publish --provenance` from the build output:
+
+```yaml filename=".github/workflows/publish.yml"
+name: Publish
+on:
+  release:
+    types: [published]
+
+permissions:
+  contents: read
+  id-token: write
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: "24"
+          registry-url: https://registry.npmjs.org
+      - run: yarn install --immutable
+      - run: npx twenty app:build
+      - run: npm publish --provenance --access public
+        working-directory: .twenty/output
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+```
+
+For other CI systems (GitLab CI, CircleCI, etc.), the same three commands apply: `yarn install`, `npx twenty app:build`, then `npm publish` from `.twenty/output`.
+
+<Tip>
+**npm provenance** is optional but recommended. Publishing with `--provenance` adds a trust badge to your npm listing, letting users verify the package was built from a specific commit in a public CI pipeline. See the [npm provenance docs](https://docs.npmjs.com/generating-provenance-statements) for setup instructions.
+</Tip>
+
+## Internal distribution
+
+For apps you don't want publicly available — proprietary tools, enterprise-only integrations, or experimental builds — you can push a tarball directly to a Twenty server.
+
+### Push a tarball
+
+Build your app and deploy it to a specific server in one step:
+
+```bash filename="Terminal"
+npx twenty app:publish --server <server-url>
+```
+
+Any workspace on that server can then install and upgrade the app from the **Applications** settings page.
+
+### Version management
+
+To release an update:
+
+1. Bump the `version` field in your `package.json`
+2. Push a new tarball with `npx twenty app:publish --server <server-url>`
+3. Workspaces on that server will see the upgrade available in their settings
+
+<Note>
+Internal apps are scoped to the server they're pushed to. They won't appear in the public marketplace and can't be installed by workspaces on other servers.
+</Note>
+
+## App categories
+
+Twenty organizes apps into three categories based on how they're distributed:
+
+| Category | How it works | Visible in marketplace? |
+|----------|-------------|------------------------|
+| **Development** | Local dev mode apps running via `yarn twenty app:dev`. Used for building and testing. | No |
+| **Published** | Apps published to npm with the `twenty-app-` prefix. Listed in the marketplace for any workspace to install. | Yes |
+| **Internal** | Apps deployed via tarball to a specific server. Available only to workspaces on that server. | No |
+
+<Tip>
+Start in **Development** mode while building your app. When it's ready, choose **Published** (npm) for broad distribution or **Internal** (tarball) for private deployment.
+</Tip>

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

@@ -319,6 +319,71 @@ Key points:
   but this is not recommended.
 </Note>
 
+### Defining fields on existing objects
+
+Use `defineField()` to add custom fields to existing objects — both standard objects (like `company`, `person`, `opportunity`) and custom objects defined by other apps. Each field lives in its own file and references the target object by its `universalIdentifier`.
+
+To reference standard objects, import `STANDARD_OBJECT_UNIVERSAL_IDENTIFIERS` from `twenty-sdk`. This constant provides stable identifiers for all built-in objects and their fields:
+
+```typescript
+// src/fields/apollo-total-funding.field.ts
+import {
+  defineField,
+  FieldType,
+  STANDARD_OBJECT_UNIVERSAL_IDENTIFIERS,
+} from 'twenty-sdk';
+
+export default defineField({
+  universalIdentifier: 'c90ae72d-4ddf-4f22-882f-eef98c91e40e',
+  objectUniversalIdentifier:
+    STANDARD_OBJECT_UNIVERSAL_IDENTIFIERS.company.universalIdentifier,
+  type: FieldType.CURRENCY,
+  name: 'apolloTotalFunding',
+  label: 'Total Funding',
+  description: 'Total funding raised by the company',
+  icon: 'IconCash',
+});
+```
+
+Key points:
+
+- `objectUniversalIdentifier` tells Twenty which object to attach the field to. Use `STANDARD_OBJECT_UNIVERSAL_IDENTIFIERS.<objectName>.universalIdentifier` for standard objects.
+- Each field requires its own stable `universalIdentifier`, a `name`, `type`, `label`, and the target `objectUniversalIdentifier`.
+- You can scaffold new fields using `yarn twenty entity:add` and choosing the field option.
+- `STANDARD_OBJECT_UNIVERSAL_IDENTIFIERS` is also exported as `STANDARD_OBJECT` for convenience — both refer to the same constant.
+
+Available standard objects include: `attachment`, `blocklist`, `calendarChannel`, `calendarEvent`, `calendarEventParticipant`, `company`, `connectedAccount`, `dashboard`, `favorite`, `favoriteFolder`, `message`, `messageChannel`, `messageParticipant`, `messageThread`, `note`, `noteTarget`, `opportunity`, `person`, `task`, `taskTarget`, `timelineActivity`, `workflow`, `workflowAutomatedTrigger`, `workflowRun`, `workflowVersion`, and `workspaceMember`.
+
+Each standard object also exposes its field identifiers. For example, to reference a specific field on a standard object in role permissions:
+
+```typescript
+STANDARD_OBJECT_UNIVERSAL_IDENTIFIERS.company.fields.name.universalIdentifier
+```
+
+#### Relation fields on existing objects
+
+You can also define relation fields that link existing objects to your custom objects:
+
+```typescript
+// src/fields/people-on-call-recording.field.ts
+import { defineField, FieldType, RelationType, STANDARD_OBJECT_UNIVERSAL_IDENTIFIERS } from 'twenty-sdk';
+import { CALL_RECORDING_OBJECT_UNIVERSAL_IDENTIFIER } from 'src/objects/call-recording';
+import { CALL_RECORDING_ON_PERSON_ID } from 'src/fields/call-recording-on-person.field';
+
+export default defineField({
+  universalIdentifier: '4a2b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d',
+  objectUniversalIdentifier:
+    CALL_RECORDING_OBJECT_UNIVERSAL_IDENTIFIER,
+  type: FieldType.RELATION,
+  name: 'person',
+  label: 'Person',
+  relationTargetObjectMetadataUniversalIdentifier:
+    STANDARD_OBJECT_UNIVERSAL_IDENTIFIERS.person.universalIdentifier,
+  relationTargetFieldMetadataUniversalIdentifier:
+    CALL_RECORDING_ON_PERSON_ID,
+  relationType: RelationType.MANY_TO_ONE,
+});
+```
 
 ### Application config (application-config.ts)
 
@@ -760,6 +825,255 @@ 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 `.tsx` file and use `defineFrontComponent()`, following the same pattern.
 
+#### Where front components can be used
+
+Front components can render in two locations within Twenty:
+
+- **Side panel** — Non-headless front components open in the right-hand side panel. This is the default behavior when a front component is triggered from the command menu.
+- **Widgets (dashboards and record pages)** — Front components can be embedded as widgets inside page layouts. When configuring a dashboard or a record page layout, users can add a front component widget.
+
+#### Headless vs non-headless
+
+Front components come in two rendering modes controlled by the `isHeadless` option:
+
+**Non-headless (default)** — The component renders a visible UI. When triggered from the command menu it opens in the side panel. This is the default behavior when `isHeadless` is `false` or omitted.
+
+**Headless** — The component mounts invisibly in the background. It does not open the side panel. Headless components are designed for actions that execute logic and then unmount themselves — for example, running an async task, navigating to a page, or showing a confirmation modal. They pair naturally with the SDK Command components described below.
+
+```typescript
+export default defineFrontComponent({
+  universalIdentifier: 'a1b2c3d4-e5f6-7890-abcd-ef1234567890',
+  name: 'my-action',
+  description: 'Runs an action without opening the side panel',
+  component: MyAction,
+  isHeadless: true,
+  command: {
+    universalIdentifier: 'b2c3d4e5-f6a7-8901-bcde-f12345678901',
+    label: 'Run my action',
+  },
+});
+```
+
+#### Adding command menu items
+
+To make a front component appear as an item in Twenty's command menu, add the `command` property to `defineFrontComponent()`. When users open the command menu (Cmd+K / Ctrl+K), the item shows up and triggers the front component on click.
+
+The `command` object accepts the following fields:
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `universalIdentifier` | `string` (required) | Unique ID for the command menu item |
+| `label` | `string` (required) | Display label shown in the command menu |
+| `icon` | `string` (optional) | Icon name (e.g., `'IconSparkles'`) |
+| `isPinned` | `boolean` (optional) | Whether the command is pinned at the top of the menu |
+| `availabilityType` | `'GLOBAL' \| 'RECORD_SELECTION'` (optional) | `GLOBAL` shows the command everywhere; `RECORD_SELECTION` shows it only in record contexts |
+| `availabilityObjectUniversalIdentifier` | `string` (optional) | Restrict the command to a specific object type (e.g., Person) |
+
+Here is an example from the call-recording app that adds a command scoped to Person records:
+
+```typescript
+import { defineFrontComponent } from 'twenty-sdk';
+
+export default defineFrontComponent({
+  universalIdentifier: 'c3d4e5f6-a7b8-9012-cdef-123456789012',
+  name: 'Summarize Person Call Recordings',
+  description: 'Generates a summary of call recordings for a person',
+  component: SummarizePersonRecordings,
+  command: {
+    universalIdentifier: 'd4e5f6a7-b8c9-0123-defa-234567890123',
+    label: 'Summarize call recordings',
+    icon: 'IconSparkles',
+    isPinned: false,
+    availabilityType: 'RECORD_SELECTION',
+    availabilityObjectUniversalIdentifier:
+      '20202020-e674-48e5-a542-72570eee7213',
+  },
+});
+```
+
+When the command is synced, it appears in the command menu. If the front component is non-headless the side panel opens with the component rendered inside. If it is headless the component mounts in the background and executes its logic.
+
+#### SDK Command components
+
+The `twenty-sdk` package provides four Command helper components designed for headless front components. Each component executes an action on mount, handles errors by showing a snackbar notification, and automatically unmounts the front component when done.
+
+Import them from `twenty-sdk/command`:
+
+- **`Command`** — Runs an async callback via the `execute` prop.
+- **`CommandLink`** — Navigates to an app path. Props: `to`, `params`, `queryParams`, `options`.
+- **`CommandModal`** — Opens a confirmation modal. If the user confirms, executes the `execute` callback. Props: `title`, `subtitle`, `execute`, `confirmButtonText`, `confirmButtonAccent`.
+- **`CommandOpenSidePanelPage`** — Opens a specific side panel page. Props: `page`, `pageTitle`, `pageIcon`.
+
+Here is a full example of a headless front component using `Command` to run an action from the command menu:
+
+```typescript
+// src/front-components/run-action.tsx
+import { defineFrontComponent } from 'twenty-sdk';
+import { Command } from 'twenty-sdk/command';
+import { CoreApiClient } from 'twenty-sdk/clients';
+
+const RunAction = () => {
+  const execute = async () => {
+    const client = new CoreApiClient();
+
+    await client.mutation({
+      createTask: {
+        __args: { data: { title: 'Created by my app' } },
+        id: true,
+      },
+    });
+  };
+
+  return <Command execute={execute} />;
+};
+
+export default defineFrontComponent({
+  universalIdentifier: 'e5f6a7b8-c9d0-1234-efab-345678901234',
+  name: 'run-action',
+  description: 'Creates a task from the command menu',
+  component: RunAction,
+  isHeadless: true,
+  command: {
+    universalIdentifier: 'f6a7b8c9-d0e1-2345-fabc-456789012345',
+    label: 'Run my action',
+    icon: 'IconPlayerPlay',
+  },
+});
+```
+
+And an example using `CommandModal` to ask for confirmation before executing:
+
+```typescript
+// src/front-components/delete-draft.tsx
+import { defineFrontComponent } from 'twenty-sdk';
+import { CommandModal } from 'twenty-sdk/command';
+
+const DeleteDraft = () => {
+  const execute = async () => {
+    // perform the deletion
+  };
+
+  return (
+    <CommandModal
+      title="Delete draft?"
+      subtitle="This action cannot be undone."
+      execute={execute}
+      confirmButtonText="Delete"
+      confirmButtonAccent="danger"
+    />
+  );
+};
+
+export default defineFrontComponent({
+  universalIdentifier: 'a7b8c9d0-e1f2-3456-abcd-567890123456',
+  name: 'delete-draft',
+  description: 'Deletes a draft with confirmation',
+  component: DeleteDraft,
+  isHeadless: true,
+  command: {
+    universalIdentifier: 'b8c9d0e1-f2a3-4567-bcde-678901234567',
+    label: 'Delete draft',
+    icon: 'IconTrash',
+  },
+});
+```
+
+#### Execution context
+
+Every front component receives an execution context that provides information about where and how it is running. Access context values using hooks from `twenty-sdk`:
+
+| Hook | Return type | Description |
+|------|-------------|-------------|
+| `useFrontComponentId()` | `string` | The unique ID of the current front component instance |
+| `useRecordId()` | `string \| null` | The ID of the current record, when the component runs in a record context (e.g., a record page widget or a command scoped to a record). Returns `null` otherwise. |
+| `useUserId()` | `string \| null` | The ID of the current user |
+
+```typescript
+import { useRecordId, useUserId } from 'twenty-sdk';
+
+const MyWidget = () => {
+  const recordId = useRecordId();
+  const userId = useUserId();
+
+  return (
+    <div>
+      <p>Record: {recordId ?? 'none'}</p>
+      <p>User: {userId ?? 'anonymous'}</p>
+    </div>
+  );
+};
+```
+
+The context is reactive — if the surrounding record changes, hooks automatically return the updated values.
+
+#### Host API functions
+
+Front components run in an isolated sandbox but can interact with Twenty's UI through a set of functions provided by the host. Import them directly from `twenty-sdk`:
+
+```typescript
+import {
+  navigate,
+  closeSidePanel,
+  enqueueSnackbar,
+  unmountFrontComponent,
+  openSidePanelPage,
+  openCommandConfirmationModal,
+} from 'twenty-sdk';
+```
+
+| Function | Signature | Description |
+|----------|-----------|-------------|
+| `navigate` | `(to, params?, queryParams?, options?) => Promise<void>` | Navigate to a typed app path within Twenty |
+| `closeSidePanel` | `() => Promise<void>` | Close the side panel |
+| `enqueueSnackbar` | `(params) => Promise<void>` | Show a snackbar notification. Params: `message`, `variant` (`'error'`, `'success'`, `'info'`, `'warning'`), optional `duration`, `detailedMessage`, `dedupeKey` |
+| `unmountFrontComponent` | `() => Promise<void>` | Unmount the current front component (used by headless components to clean up after execution) |
+| `openSidePanelPage` | `(params) => Promise<void>` | Open a page in the side panel. Params: `page`, `pageTitle`, `pageIcon`, `shouldResetSearchState` |
+| `openCommandConfirmationModal` | `(params) => Promise<'confirm' \| 'cancel'>` | Show a confirmation modal and wait for the user's response. Params: `title`, `subtitle`, `confirmButtonText`, `confirmButtonAccent` (`'default'`, `'blue'`, `'danger'`) |
+
+Here is an example that uses the host API to show a snackbar and close the side panel after an action completes:
+
+```typescript
+import { defineFrontComponent, useRecordId } from 'twenty-sdk';
+import { enqueueSnackbar, closeSidePanel } from 'twenty-sdk';
+import { CoreApiClient } from 'twenty-sdk/clients';
+
+const ArchiveRecord = () => {
+  const recordId = useRecordId();
+
+  const handleArchive = async () => {
+    const client = new CoreApiClient();
+
+    await client.mutation({
+      updateTask: {
+        __args: { id: recordId, data: { status: 'ARCHIVED' } },
+        id: true,
+      },
+    });
+
+    await enqueueSnackbar({
+      message: 'Record archived',
+      variant: 'success',
+    });
+
+    await closeSidePanel();
+  };
+
+  return (
+    <div style={{ padding: '20px' }}>
+      <p>Archive this record?</p>
+      <button onClick={handleArchive}>Archive</button>
+    </div>
+  );
+};
+
+export default defineFrontComponent({
+  universalIdentifier: 'c9d0e1f2-a3b4-5678-cdef-789012345678',
+  name: 'archive-record',
+  description: 'Archives the current record',
+  component: ArchiveRecord,
+});
+```
+
 ### Skills
 
 Skills define reusable instructions and capabilities that AI agents can use within your workspace. Use `defineSkill()` to define skills with built-in validation:

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

@@ -14,20 +14,18 @@ Twenty is designed to be extensible. Use our APIs, webhooks, and app framework t
 
 - **APIs**: Query and modify your CRM data programmatically using REST or GraphQL
 - **Webhooks**: Receive real-time notifications when events occur in Twenty
-- **Apps**: Build custom applications that extend Twenty's capabilities - Coming soon!
+- **Apps**: Build custom applications that extend Twenty's capabilities
 
 ## Getting Started
 
 <CardGroup cols={2}>
-  <Card title="APIs" icon="code" href="/developers/extend/capabilities/apis">
+  <Card title="APIs" icon="code" href="/developers/extend/api">
     Connect to Twenty programmatically
   </Card>
-  <Card title="Webhooks" icon="bell" href="/developers/extend/capabilities/webhooks">
+  <Card title="Webhooks" icon="bell" href="/developers/extend/webhooks">
     Get notified of events in real-time
   </Card>
-  <Card title="Apps" icon="puzzle-piece" href="/developers/extend/capabilities/apps">
-    Build customizations as code (Alpha)
+  <Card title="Apps" icon="puzzle-piece" href="/developers/extend/apps/getting-started">
+    Build customizations as code
   </Card>
 </CardGroup>
-
-

packages/twenty-docs/developers/extend/webhooks.mdx

@@ -0,0 +1,117 @@
+---
+title: Webhooks
+description: Receive real-time notifications when events occur in your CRM.
+---
+
+import { VimeoEmbed } from '/snippets/vimeo-embed.mdx';
+
+
+Webhooks push data to your systems in real-time when events occur in Twenty — no polling required. Use them to keep external systems in sync, trigger automations, or send alerts.
+
+## Create a Webhook
+
+1. Go to **Settings → APIs & Webhooks → Webhooks**
+2. Click **+ Create webhook**
+3. Enter your webhook URL (must be publicly accessible)
+4. Click **Save**
+
+The webhook activates immediately and starts sending notifications.
+
+<VimeoEmbed videoId="928786708" title="Creating a webhook" />
+
+### Manage Webhooks
+
+**Edit**: Click the webhook → Update URL → **Save**
+
+**Delete**: Click the webhook → **Delete** → Confirm
+
+## Events
+
+Twenty sends webhooks for these event types:
+
+| Event | Example |
+|-------|---------|
+| **Record Created** | `person.created`, `company.created`, `note.created` |
+| **Record Updated** | `person.updated`, `company.updated`, `opportunity.updated` |
+| **Record Deleted** | `person.deleted`, `company.deleted` |
+
+All event types are sent to your webhook URL. Event filtering may be added in future releases.
+
+## Payload Format
+
+Each webhook sends an HTTP POST with a JSON body:
+
+```json
+{
+  "event": "person.created",
+  "data": {
+    "id": "abc12345",
+    "firstName": "Alice",
+    "lastName": "Doe",
+    "email": "alice@example.com",
+    "createdAt": "2025-02-10T15:30:45Z",
+    "createdBy": "user_123"
+  },
+  "timestamp": "2025-02-10T15:30:50Z"
+}
+```
+
+| Field | Description |
+|-------|-------------|
+| `event` | What happened (e.g., `person.created`) |
+| `data` | The full record that was created/updated/deleted |
+| `timestamp` | When the event occurred (UTC) |
+
+<Note>
+Respond with a **2xx HTTP status** (200-299) to acknowledge receipt. Non-2xx responses are logged as delivery failures.
+</Note>
+
+## Webhook Validation
+
+Twenty signs each webhook request for security. Validate signatures to ensure requests are authentic.
+
+### Headers
+
+| Header | Description |
+|--------|-------------|
+| `X-Twenty-Webhook-Signature` | HMAC SHA256 signature |
+| `X-Twenty-Webhook-Timestamp` | Request timestamp |
+
+### Validation Steps
+
+1. Get the timestamp from `X-Twenty-Webhook-Timestamp`
+2. Create the string: `{timestamp}:{JSON payload}`
+3. Compute HMAC SHA256 using your webhook secret
+4. Compare with `X-Twenty-Webhook-Signature`
+
+### Example (Node.js)
+
+```javascript
+const crypto = require("crypto");
+
+const timestamp = req.headers["x-twenty-webhook-timestamp"];
+const payload = JSON.stringify(req.body);
+const secret = "your-webhook-secret";
+
+const stringToSign = `${timestamp}:${payload}`;
+const expectedSignature = crypto
+  .createHmac("sha256", secret)
+  .update(stringToSign)
+  .digest("hex");
+
+const receivedSignature = req.headers["x-twenty-webhook-signature"];
+const isValid = crypto.timingSafeEqual(
+  Buffer.from(expectedSignature, "hex"),
+  Buffer.from(receivedSignature, "hex")
+);
+```
+
+## Webhooks vs Workflows
+
+| Method | Direction | Use Case |
+|--------|-----------|----------|
+| **Webhooks** | OUT | Automatically notify external systems of any record change |
+| **Workflow + HTTP Request** | OUT | Send data out with custom logic (filters, transformations) |
+| **Workflow Webhook Trigger** | IN | Receive data into Twenty from external systems |
+
+For receiving external data, see [Set Up a Webhook Trigger](/user-guide/workflows/how-tos/connect-to-other-tools/set-up-a-webhook-trigger).

packages/twenty-docs/docs.json

@@ -358,13 +358,14 @@
                 "group": "Extend",
                 "icon": "plug",
                 "pages": [
-                  "developers/extend/extend",
+                  "developers/extend/api",
+                  "developers/extend/webhooks",
                   {
-                    "group": "Capabilities",
+                    "group": "Apps",
                     "pages": [
-                      "developers/extend/capabilities/apis",
-                      "developers/extend/capabilities/webhooks",
-                      "developers/extend/capabilities/apps"
+                      "developers/extend/apps/getting-started",
+                      "developers/extend/apps/building",
+                      "developers/extend/apps/publishing"
                     ]
                   }
                 ]
@@ -803,13 +804,14 @@
                 "group": "Étendre",
                 "icon": "plug",
                 "pages": [
-                  "l/fr/developers/extend/extend",
+                  "l/fr/developers/extend/api",
+                  "l/fr/developers/extend/webhooks",
                   {
-                    "group": "Capacités",
+                    "group": "Apps",
                     "pages": [
-                      "l/fr/developers/extend/capabilities/apis",
-                      "l/fr/developers/extend/capabilities/webhooks",
-                      "l/fr/developers/extend/capabilities/apps"
+                      "l/fr/developers/extend/apps/getting-started",
+                      "l/fr/developers/extend/apps/building",
+                      "l/fr/developers/extend/apps/publishing"
                     ]
                   }
                 ]
@@ -1248,13 +1250,14 @@
                 "group": "التوسيع",
                 "icon": "plug",
                 "pages": [
-                  "l/ar/developers/extend/extend",
+                  "l/ar/developers/extend/api",
+                  "l/ar/developers/extend/webhooks",
                   {
-                    "group": "القدرات",
+                    "group": "التطبيقات",
                     "pages": [
-                      "l/ar/developers/extend/capabilities/apis",
-                      "l/ar/developers/extend/capabilities/webhooks",
-                      "l/ar/developers/extend/capabilities/apps"
+                      "l/ar/developers/extend/apps/getting-started",
+                      "l/ar/developers/extend/apps/building",
+                      "l/ar/developers/extend/apps/publishing"
                     ]
                   }
                 ]
@@ -1693,13 +1696,14 @@
                 "group": "Rozšíření",
                 "icon": "plug",
                 "pages": [
-                  "l/cs/developers/extend/extend",
+                  "l/cs/developers/extend/api",
+                  "l/cs/developers/extend/webhooks",
                   {
-                    "group": "Možnosti",
+                    "group": "Apps",
                     "pages": [
-                      "l/cs/developers/extend/capabilities/apis",
-                      "l/cs/developers/extend/capabilities/webhooks",
-                      "l/cs/developers/extend/capabilities/apps"
+                      "l/cs/developers/extend/apps/getting-started",
+                      "l/cs/developers/extend/apps/building",
+                      "l/cs/developers/extend/apps/publishing"
                     ]
                   }
                 ]
@@ -2138,13 +2142,14 @@
                 "group": "Erweitern",
                 "icon": "plug",
                 "pages": [
-                  "l/de/developers/extend/extend",
+                  "l/de/developers/extend/api",
+                  "l/de/developers/extend/webhooks",
                   {
-                    "group": "Funktionen",
+                    "group": "Apps",
                     "pages": [
-                      "l/de/developers/extend/capabilities/apis",
-                      "l/de/developers/extend/capabilities/webhooks",
-                      "l/de/developers/extend/capabilities/apps"
+                      "l/de/developers/extend/apps/getting-started",
+                      "l/de/developers/extend/apps/building",
+                      "l/de/developers/extend/apps/publishing"
                     ]
                   }
                 ]
@@ -2583,13 +2588,14 @@
                 "group": "Ampliar",
                 "icon": "plug",
                 "pages": [
-                  "l/es/developers/extend/extend",
+                  "l/es/developers/extend/api",
+                  "l/es/developers/extend/webhooks",
                   {
-                    "group": "Capacidades",
+                    "group": "Apps",
                     "pages": [
-                      "l/es/developers/extend/capabilities/apis",
-                      "l/es/developers/extend/capabilities/webhooks",
-                      "l/es/developers/extend/capabilities/apps"
+                      "l/es/developers/extend/apps/getting-started",
+                      "l/es/developers/extend/apps/building",
+                      "l/es/developers/extend/apps/publishing"
                     ]
                   }
                 ]
@@ -3028,13 +3034,14 @@
                 "group": "Estendi",
                 "icon": "plug",
                 "pages": [
-                  "l/it/developers/extend/extend",
+                  "l/it/developers/extend/api",
+                  "l/it/developers/extend/webhooks",
                   {
-                    "group": "Funzionalità",
+                    "group": "App",
                     "pages": [
-                      "l/it/developers/extend/capabilities/apis",
-                      "l/it/developers/extend/capabilities/webhooks",
-                      "l/it/developers/extend/capabilities/apps"
+                      "l/it/developers/extend/apps/getting-started",
+                      "l/it/developers/extend/apps/building",
+                      "l/it/developers/extend/apps/publishing"
                     ]
                   }
                 ]
@@ -3473,13 +3480,14 @@
                 "group": "拡張",
                 "icon": "plug",
                 "pages": [
-                  "l/ja/developers/extend/extend",
+                  "l/ja/developers/extend/api",
+                  "l/ja/developers/extend/webhooks",
                   {
-                    "group": "機能",
+                    "group": "Apps",
                     "pages": [
-                      "l/ja/developers/extend/capabilities/apis",
-                      "l/ja/developers/extend/capabilities/webhooks",
-                      "l/ja/developers/extend/capabilities/apps"
+                      "l/ja/developers/extend/apps/getting-started",
+                      "l/ja/developers/extend/apps/building",
+                      "l/ja/developers/extend/apps/publishing"
                     ]
                   }
                 ]
@@ -3918,13 +3926,14 @@
                 "group": "확장",
                 "icon": "plug",
                 "pages": [
-                  "l/ko/developers/extend/extend",
+                  "l/ko/developers/extend/api",
+                  "l/ko/developers/extend/webhooks",
                   {
-                    "group": "기능",
+                    "group": "Apps",
                     "pages": [
-                      "l/ko/developers/extend/capabilities/apis",
-                      "l/ko/developers/extend/capabilities/webhooks",
-                      "l/ko/developers/extend/capabilities/apps"
+                      "l/ko/developers/extend/apps/getting-started",
+                      "l/ko/developers/extend/apps/building",
+                      "l/ko/developers/extend/apps/publishing"
                     ]
                   }
                 ]
@@ -4363,13 +4372,14 @@
                 "group": "Extend",
                 "icon": "plug",
                 "pages": [
-                  "l/pt/developers/extend/extend",
+                  "l/pt/developers/extend/api",
+                  "l/pt/developers/extend/webhooks",
                   {
-                    "group": "Capabilities",
+                    "group": "Aplicativos",
                     "pages": [
-                      "l/pt/developers/extend/capabilities/apis",
-                      "l/pt/developers/extend/capabilities/webhooks",
-                      "l/pt/developers/extend/capabilities/apps"
+                      "l/pt/developers/extend/apps/getting-started",
+                      "l/pt/developers/extend/apps/building",
+                      "l/pt/developers/extend/apps/publishing"
                     ]
                   }
                 ]
@@ -4808,13 +4818,14 @@
                 "group": "Extend",
                 "icon": "plug",
                 "pages": [
-                  "l/ro/developers/extend/extend",
+                  "l/ro/developers/extend/api",
+                  "l/ro/developers/extend/webhooks",
                   {
-                    "group": "Capabilities",
+                    "group": "Aplicații",
                     "pages": [
-                      "l/ro/developers/extend/capabilities/apis",
-                      "l/ro/developers/extend/capabilities/webhooks",
-                      "l/ro/developers/extend/capabilities/apps"
+                      "l/ro/developers/extend/apps/getting-started",
+                      "l/ro/developers/extend/apps/building",
+                      "l/ro/developers/extend/apps/publishing"
                     ]
                   }
                 ]
@@ -5253,13 +5264,14 @@
                 "group": "Расширяйте",
                 "icon": "plug",
                 "pages": [
-                  "l/ru/developers/extend/extend",
+                  "l/ru/developers/extend/api",
+                  "l/ru/developers/extend/webhooks",
                   {
-                    "group": "Возможности",
+                    "group": "Приложения",
                     "pages": [
-                      "l/ru/developers/extend/capabilities/apis",
-                      "l/ru/developers/extend/capabilities/webhooks",
-                      "l/ru/developers/extend/capabilities/apps"
+                      "l/ru/developers/extend/apps/getting-started",
+                      "l/ru/developers/extend/apps/building",
+                      "l/ru/developers/extend/apps/publishing"
                     ]
                   }
                 ]
@@ -5698,13 +5710,14 @@
                 "group": "Genişlet",
                 "icon": "plug",
                 "pages": [
-                  "l/tr/developers/extend/extend",
+                  "l/tr/developers/extend/api",
+                  "l/tr/developers/extend/webhooks",
                   {
-                    "group": "Yetkinlikler",
+                    "group": "Uygulamalar",
                     "pages": [
-                      "l/tr/developers/extend/capabilities/apis",
-                      "l/tr/developers/extend/capabilities/webhooks",
-                      "l/tr/developers/extend/capabilities/apps"
+                      "l/tr/developers/extend/apps/getting-started",
+                      "l/tr/developers/extend/apps/building",
+                      "l/tr/developers/extend/apps/publishing"
                     ]
                   }
                 ]
@@ -6143,13 +6156,14 @@
                 "group": "扩展",
                 "icon": "plug",
                 "pages": [
-                  "l/zh/developers/extend/extend",
+                  "l/zh/developers/extend/api",
+                  "l/zh/developers/extend/webhooks",
                   {
-                    "group": "功能",
+                    "group": "应用",
                     "pages": [
-                      "l/zh/developers/extend/capabilities/apis",
-                      "l/zh/developers/extend/capabilities/webhooks",
-                      "l/zh/developers/extend/capabilities/apps"
+                      "l/zh/developers/extend/apps/getting-started",
+                      "l/zh/developers/extend/apps/building",
+                      "l/zh/developers/extend/apps/publishing"
                     ]
                   }
                 ]
@@ -6272,6 +6286,22 @@
     }
   },
   "redirects": [
+    {
+      "source": "/developers/extend/capabilities/api",
+      "destination": "/developers/extend/api"
+    },
+    {
+      "source": "/developers/extend/capabilities/apis",
+      "destination": "/developers/extend/api"
+    },
+    {
+      "source": "/developers/extend/capabilities/webhooks",
+      "destination": "/developers/extend/webhooks"
+    },
+    {
+      "source": "/developers/extend/capabilities/apps",
+      "destination": "/developers/extend/apps/getting-started"
+    },
     {
       "source": "/developers/local-setup",
       "destination": "/developers/contribute/capabilities/local-setup"
@@ -6302,27 +6332,27 @@
     },
     {
       "source": "/developers/api-and-webhooks",
-      "destination": "/developers/extend/extend"
+      "destination": "/developers/extend/api"
     },
     {
       "source": "/developers/api-and-webhooks/apis-overview",
-      "destination": "/developers/extend/capabilities/apis"
+      "destination": "/developers/extend/api"
     },
     {
       "source": "/developers/api-and-webhooks/api",
-      "destination": "/developers/extend/capabilities/apis"
+      "destination": "/developers/extend/api"
     },
     {
       "source": "/developers/api-and-webhooks/api-keys",
-      "destination": "/developers/extend/capabilities/apis"
+      "destination": "/developers/extend/api"
     },
     {
       "source": "/developers/api-and-webhooks/webhooks",
-      "destination": "/developers/extend/capabilities/webhooks"
+      "destination": "/developers/extend/webhooks"
     },
     {
       "source": "/developers/api-and-webhooks/integrations",
-      "destination": "/developers/extend/capabilities/apis"
+      "destination": "/developers/extend/api"
     },
     {
       "source": "/developers/bugs-and-requests",

packages/twenty-docs/l/ar/developers/extend/api.mdx

@@ -0,0 +1,147 @@
+---
+title: واجهات برمجة التطبيقات
+description: استعلم وعدّل بيانات إدارة علاقات العملاء (CRM) لديك برمجياً باستخدام REST أو GraphQL.
+---
+
+import { VimeoEmbed } from '/snippets/vimeo-embed.mdx';
+
+تم تصميم Twenty ليكون صديقًا للمطورين، حيث يوفر واجهات برمجة قوية تتكيف مع نموذج البيانات المخصص. نحن نوفر أربعة أنواع متميزة من واجهات برمجة التطبيقات لتلبية احتياجات التكامل المختلفة.
+
+## نهج المطوّر أولاً
+
+تقوم Twenty بإنشاء واجهات برمجة التطبيقات خصيصاً لنموذج بياناتك:
+
+* **لا حاجة إلى معرفات طويلة**: استخدم أسماء الكائنات والحقول مباشرة في نقاط النهاية
+* **معاملة متساوية للكائنات القياسية والمخصصة**: تحصل كائناتك المخصصة على نفس معاملة واجهة برمجة التطبيقات كما هو الحال مع الكائنات المضمنة
+* **نقاط نهاية مخصصة**: يحصل كل كائن وحقل على نقطة نهاية API الخاصة به
+* **وثائق مخصصة**: يتم إنشاؤها خصيصًا لنموذج بيانات مساحة عملك
+
+<Note>
+وثائق واجهة برمجة التطبيقات المخصصة لك متاحة ضمن **الإعدادات → واجهات برمجة التطبيقات وخطافات الويب** بعد إنشاء مفتاح API. نظرًا لأن Twenty تُنشئ واجهات برمجة تطبيقات تتطابق مع نموذج البيانات المخصص لديك، فإن الوثائق فريدة لمساحة عملك.
+</Note>
+
+## نوعا واجهات برمجة التطبيقات
+
+### واجهة برمجة التطبيقات الأساسية
+
+يتم الوصول إليها عبر `/rest/` أو `/graphql/`
+
+تعامَل مع **السجلات** الفعلية لديك (البيانات):
+
+* إنشاء وقراءة وتحديث وحذف الأشخاص والشركات والفرص، إلخ.
+* استعلام وتصفية البيانات
+* إدارة العلاقات بين السجلات
+
+### واجهة برمجة البيانات الوصفية
+
+يتم الوصول إليها عبر `/rest/metadata/` أو `/metadata/`
+
+إدارة **مساحة العمل ونموذج البيانات** لديك:
+
+* إنشاء أو تعديل أو حذف الكائنات والحقول
+* تكوين إعدادات مساحة العمل
+* تعريف العلاقات بين الكائنات
+
+## REST مقابل GraphQL
+
+تتوفر واجهات برمجة التطبيقات الأساسية وواجهات البيانات الوصفية بصيغتي REST وGraphQL:
+
+| التنسيق     | العمليات المتاحة                                                              |
+| ----------- | ----------------------------------------------------------------------------- |
+| **REST**    | CRUD، عمليات الدفعات، إدراج/تحديث                                             |
+| **GraphQL** | نفس الشيء + **عمليات إدراج/تحديث مجمعة**، واستعلامات العلاقات في استدعاء واحد |
+
+اختر بناءً على احتياجاتك — كلا الصيغتين تصلان إلى البيانات نفسها.
+
+## نقاط نهاية API
+
+| البيئة                | عنوان URL الأساسي         |
+| --------------------- | ------------------------- |
+| **السحابة**           | `https://api.twenty.com/` |
+| **الاستضافة الذاتية** | `https://{your-domain}/`  |
+
+## المصادقة
+
+كل طلب API يتطلب تضمين مفتاح API في رأس الطلب:
+
+```
+Authorization: Bearer YOUR_API_KEY
+```
+
+### قم بإنشاء مفتاح API
+
+1. انتقل إلى **الإعدادات → واجهات برمجة التطبيقات وخطافات الويب**
+2. انقر على **+ إنشاء مفتاح**
+3. التكوين:
+   * **الاسم**: اسم وصفي للمفتاح
+   * **تاريخ الانتهاء**: متى تنتهي صلاحية المفتاح
+4. انقر على **حفظ**
+5. **انسخه فوراً** — يظهر المفتاح مرة واحدة فقط
+
+<VimeoEmbed videoId="928786722" title="إنشاء مفتاح API" />
+
+<Warning>
+يمنح مفتاح API الخاص بك الوصول إلى بيانات حساسة. لا تشاركه مع خدمات غير موثوقة. إذا تم اختراقه، عطّلْه فوراً وأنشئ مفتاحاً جديداً.
+</Warning>
+
+### تعيين دور لمفتاح API
+
+لتحسين الأمان، عيّن دوراً محدداً لتقييد الوصول:
+
+1. اذهب إلى **الإعدادات → الأدوار**
+2. انقر على الدور الذي ترغب في تعيينه
+3. افتح علامة التبويب **التعيين**
+4. ضمن **مفاتيح API**، انقر على **+ تعيين إلى مفتاح API**
+5. حدد مفتاح API
+
+سيرث المفتاح أذونات ذلك الدور. راجع [الأذونات](/l/ar/user-guide/permissions-access/capabilities/permissions) للحصول على التفاصيل.
+
+### إدارة مفاتيح API
+
+**إعادة التوليد**: الإعدادات → واجهات برمجة التطبيقات وخطافات الويب → انقر على المفتاح → **إعادة التوليد**
+
+**حذف**: الإعدادات → واجهات برمجة التطبيقات وخطافات الويب → انقر على المفتاح → **حذف**
+
+## ملعب واجهة برمجة التطبيقات
+
+اختبر واجهات برمجة التطبيقات لديك مباشرة في المتصفح باستخدام الملعب المدمج لدينا — متاح لكلٍ من **REST** و**GraphQL**.
+
+### الوصول إلى الملعب
+
+1. انتقل إلى **الإعدادات → واجهات برمجة التطبيقات وخطافات الويب**
+2. أنشئ مفتاح API (مطلوب)
+3. انقر على **REST API** أو **GraphQL API** لفتح الملعب
+
+### ما الذي ستحصل عليه
+
+* **وثائق تفاعلية**: يتم إنشاؤها لنموذج البيانات المحدد لديك
+* **اختبارات حيّة**: تنفيذ استدعاءات API فعلية على مساحة عملك
+* **مستكشف المخطط**: تصفح الكائنات والحقول والعلاقات المتاحة
+* **منشئ الطلبات**: أنشئ الاستعلامات مع الإكمال التلقائي
+
+يعكس الملعب الكائنات والحقول المخصصة لديك، لذا تكون الوثائق دائماً دقيقة لمساحة عملك.
+
+## عمليات الدفعات
+
+كلٌ من REST وGraphQL يدعمان عمليات الدفعات:
+
+* **حجم الدفعة**: حتى 60 سجل لكل طلب
+* **العمليات**: إنشاء وتحديث وحذف سجلات متعددة
+
+**ميزات خاصة بـ GraphQL:**
+
+* **إدراج/تحديث دفعي**: إنشاء أو تحديث في استدعاء واحد
+* استخدم الأسماء الجمع للكائنات (على سبيل المثال، `CreateCompanies` بدلاً من `CreateCompany`)
+
+## حدود المعدل
+
+يتم تنظيم طلبات API لضمان استقرار المنصة:
+
+| الحد           | القيمة                 |
+| -------------- | ---------------------- |
+| **الطلبات**    | 100 استدعاء في الدقيقة |
+| **حجم الدفعة** | 60 سجل لكل استدعاء     |
+
+<Tip>
+استخدم عمليات الدفعات لزيادة الإنتاجية — عالج ما يصل إلى 60 سجلًا في استدعاء API واحد بدلاً من إجراء طلبات فردية.
+</Tip>

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

@@ -0,0 +1,689 @@
+---
+title: بناء التطبيقات
+description: عرّف الكائنات، والدوال المنطقية، ومكوّنات الواجهة الأمامية، وغير ذلك باستخدام Twenty SDK.
+---
+
+<Warning>
+التطبيقات حاليًا في مرحلة الاختبار الألفا. الميزة تعمل لكنها لا تزال قيد التطور.
+</Warning>
+
+## استخدم موارد SDK (الأنواع والتكوين)
+
+يوفّر twenty-sdk كتلَ بناءٍ مضبوطة الأنواع ودوال مساعدة تستخدمها داخل تطبيقك. فيما يلي الأجزاء الأساسية التي ستتعامل معها غالبًا.
+
+### دوال مساعدة
+
+يوفّر SDK دوالًا مساعدة لتعريف كيانات تطبيقك. كما هو موضح في [اكتشاف الكيانات](/l/ar/developers/extend/apps/getting-started#entity-detection)، يجب استخدام `export default define<Entity>({...})` كي يتم اكتشاف كياناتك:
+
+| دالة                             | الغرض                                                |
+| -------------------------------- | ---------------------------------------------------- |
+| `defineApplication`              | تهيئة بيانات التعريف للتطبيق (مطلوب، واحد لكل تطبيق) |
+| `defineObject`                   | تعريف كائنات مخصصة مع حقول                           |
+| `defineLogicFunction`            | تعريف وظائف منطقية مع معالجات                        |
+| `definePreInstallLogicFunction`  | تعريف دالة منطقية لما قبل التثبيت (واحدة لكل تطبيق)  |
+| `definePostInstallLogicFunction` | تعريف دالة منطقية لما بعد التثبيت (واحدة لكل تطبيق)  |
+| `defineFrontComponent`           | عرِّف مكوّنات أمامية لواجهة مستخدم مخصّصة            |
+| `defineRole`                     | تهيئة صلاحيات الدور والوصول إلى الكائنات             |
+| `defineField`                    | وسّع الكائنات الموجودة بحقول إضافية                  |
+| `defineView`                     | تعريف العروض المحفوظة للكائنات                       |
+| `defineNavigationMenuItem`       | تعريف روابط التنقل في الشريط الجانبي                 |
+| `defineSkill`                    | عرّف مهارات وكيل الذكاء الاصطناعي                    |
+
+تتحقق هذه الدوال من تكوينك وقت البناء وتوفّر إكمالًا تلقائيًا في بيئة التطوير وأمان الأنواع.
+
+### تعريف الكائنات
+
+تصف الكائنات المخصصة كلًا من المخطط والسلوك للسجلات في مساحة عملك. استخدم `defineObject()` لتعريف كائنات مع تحقق مدمج:
+
+```typescript
+// src/app/postCard.object.ts
+import { defineObject, FieldType } from 'twenty-sdk';
+
+enum PostCardStatus {
+  DRAFT = 'DRAFT',
+  SENT = 'SENT',
+  DELIVERED = 'DELIVERED',
+  RETURNED = 'RETURNED',
+}
+
+export default defineObject({
+  universalIdentifier: '54b589ca-eeed-4950-a176-358418b85c05',
+  nameSingular: 'postCard',
+  namePlural: 'postCards',
+  labelSingular: 'Post Card',
+  labelPlural: 'Post Cards',
+  description: 'A post card object',
+  icon: 'IconMail',
+  fields: [
+    {
+      universalIdentifier: '58a0a314-d7ea-4865-9850-7fb84e72f30b',
+      name: 'content',
+      type: FieldType.TEXT,
+      label: 'Content',
+      description: "Postcard's content",
+      icon: 'IconAbc',
+    },
+    {
+      universalIdentifier: 'c6aa31f3-da76-4ac6-889f-475e226009ac',
+      name: 'recipientName',
+      type: FieldType.FULL_NAME,
+      label: 'Recipient name',
+      icon: 'IconUser',
+    },
+    {
+      universalIdentifier: '95045777-a0ad-49ec-98f9-22f9fc0c8266',
+      name: 'recipientAddress',
+      type: FieldType.ADDRESS,
+      label: 'Recipient address',
+      icon: 'IconHome',
+    },
+    {
+      universalIdentifier: '87b675b8-dd8c-4448-b4ca-20e5a2234a1e',
+      name: 'status',
+      type: FieldType.SELECT,
+      label: 'Status',
+      icon: 'IconSend',
+      defaultValue: `'${PostCardStatus.DRAFT}'`,
+      options: [
+        { value: PostCardStatus.DRAFT, label: 'Draft', position: 0, color: 'gray' },
+        { value: PostCardStatus.SENT, label: 'Sent', position: 1, color: 'orange' },
+        { value: PostCardStatus.DELIVERED, label: 'Delivered', position: 2, color: 'green' },
+        { value: PostCardStatus.RETURNED, label: 'Returned', position: 3, color: 'orange' },
+      ],
+    },
+    {
+      universalIdentifier: 'e06abe72-5b44-4e7f-93be-afc185a3c433',
+      name: 'deliveredAt',
+      type: FieldType.DATE_TIME,
+      label: 'Delivered at',
+      icon: 'IconCheck',
+      isNullable: true,
+      defaultValue: null,
+    },
+  ],
+});
+```
+
+النقاط الرئيسية:
+
+* استخدم `defineObject()` للحصول على تحقق مدمج ودعم أفضل من IDE.
+* `universalIdentifier` يجب أن يكون فريدًا وثابتًا عبر عمليات النشر.
+* يتطلب كل حقل `name` و`type` و`label` ومعرّف `universalIdentifier` ثابتًا خاصًا به.
+* المصفوفة `fields` اختيارية — يمكنك تعريف كائنات بدون حقول مخصصة.
+* يمكنك إنشاء كائنات جديدة باستخدام `yarn twenty entity:add`، والذي يرشدك خلال التسمية والحقول والعلاقات.
+
+<Note>
+**يتم إنشاء الحقول الأساسية تلقائيًا.** عند تعريف كائن مخصص، يضيف Twenty تلقائيًا حقولًا قياسية
+مثل `id` و`name` و`createdAt` و`updatedAt` و`createdBy` و`updatedBy` و`deletedAt`.
+لا تحتاج إلى تعريف هذه في مصفوفة `fields` — أضف فقط حقولك المخصصة.
+يمكنك تجاوز الحقول الافتراضية من خلال تعريف حقل بالاسم نفسه في مصفوفة `fields` الخاصة بك،
+لكن هذا غير مستحسن.
+</Note>
+
+### تكوين التطبيق (application-config.ts)
+
+كل تطبيق لديه ملف واحد `application-config.ts` يصف:
+
+* **هوية التطبيق**: المعرفات، اسم العرض، والوصف.
+* **كيفية تشغيل وظائفه**: الدور الذي تستخدمه للأذونات.
+* **متغيرات (اختياري)**: أزواج مفتاح-قيمة تُعرض لوظائفك كمتغيرات بيئة.
+* **(اختياري) دالة ما قبل التثبيت**: دالة منطقية تعمل قبل تثبيت التطبيق.
+* **(اختياري) دالة ما بعد التثبيت**: دالة منطقية تعمل بعد تثبيت التطبيق.
+
+استخدم `defineApplication()` لتعريف تهيئة تطبيقك:
+
+```typescript
+// src/application-config.ts
+import { defineApplication } from 'twenty-sdk';
+import { DEFAULT_ROLE_UNIVERSAL_IDENTIFIER } from 'src/roles/default-role';
+
+export default defineApplication({
+  universalIdentifier: '4ec0391d-18d5-411c-b2f3-266ddc1c3ef7',
+  displayName: 'My Twenty App',
+  description: 'My first Twenty app',
+  icon: 'IconWorld',
+  applicationVariables: {
+    DEFAULT_RECIPIENT_NAME: {
+      universalIdentifier: '19e94e59-d4fe-4251-8981-b96d0a9f74de',
+      description: 'Default recipient name for postcards',
+      value: 'Jane Doe',
+      isSecret: false,
+    },
+  },
+  defaultRoleUniversalIdentifier: DEFAULT_ROLE_UNIVERSAL_IDENTIFIER,
+});
+```
+
+الملاحظات:
+
+* حقول `universalIdentifier` هي معرّفات حتمية تخصك؛ أنشئها مرة واحدة واحتفظ بها ثابتة عبر عمليات المزامنة.
+* `applicationVariables` تصبح متغيرات بيئة لوظائفك (على سبيل المثال، `DEFAULT_RECIPIENT_NAME` متاح كـ `process.env.DEFAULT_RECIPIENT_NAME`).
+* `defaultRoleUniversalIdentifier` يجب أن يطابق ملف الدور (انظر أدناه).
+* يتم اكتشاف دوال ما قبل التثبيت وما بعد التثبيت تلقائيًا أثناء إنشاء ملف البيان. راجع [دوال ما قبل التثبيت](#pre-install-functions) و[دوال ما بعد التثبيت](#post-install-functions).
+
+#### الأدوار والصلاحيات
+
+يمكن للتطبيقات تعريف أدوار تُغلّف الصلاحيات على كائنات وإجراءات مساحة العمل لديك. يعين الحقل `defaultRoleUniversalIdentifier` في `application-config.ts` الدور الافتراضي الذي تستخدمه وظائف المنطق في تطبيقك.
+
+* مفتاح واجهة البرمجة في وقت التشغيل المحقون باسم `TWENTY_API_KEY` مستمد من دور الوظيفة الافتراضي هذا.
+* سيُقيَّد العميل مضبوط الأنواع بالأذونات الممنوحة لذلك الدور.
+* اتبع مبدأ أقل الامتياز: أنشئ دورًا مخصصًا بالأذونات التي تحتاجها وظائفك فقط، ثم أشِر إلى معرّفه الشامل.
+
+##### الدور الافتراضي للوظيفة (*.role.ts)
+
+عند توليد تطبيق جديد بالقالب، ينشئ CLI أيضًا ملف دور افتراضي. استخدم `defineRole()` لتعريف أدوار مع تحقق مدمج:
+
+```typescript
+// src/roles/default-role.ts
+import { defineRole, PermissionFlag } from 'twenty-sdk';
+
+export const DEFAULT_ROLE_UNIVERSAL_IDENTIFIER =
+  'b648f87b-1d26-4961-b974-0908fd991061';
+
+export default defineRole({
+  universalIdentifier: DEFAULT_ROLE_UNIVERSAL_IDENTIFIER,
+  label: 'Default function role',
+  description: 'Default role for function Twenty client',
+  canReadAllObjectRecords: false,
+  canUpdateAllObjectRecords: false,
+  canSoftDeleteAllObjectRecords: false,
+  canDestroyAllObjectRecords: false,
+  canUpdateAllSettings: false,
+  canBeAssignedToAgents: false,
+  canBeAssignedToUsers: false,
+  canBeAssignedToApiKeys: false,
+  objectPermissions: [
+    {
+      objectUniversalIdentifier: '9f9882af-170c-4879-b013-f9628b77c050',
+      canReadObjectRecords: true,
+      canUpdateObjectRecords: true,
+      canSoftDeleteObjectRecords: false,
+      canDestroyObjectRecords: false,
+    },
+  ],
+  fieldPermissions: [
+    {
+      objectUniversalIdentifier: '9f9882af-170c-4879-b013-f9628b77c050',
+      fieldUniversalIdentifier: 'b2c37dc0-8ae7-470e-96cd-1476b47dfaff',
+      canReadFieldValue: false,
+      canUpdateFieldValue: false,
+    },
+  ],
+  permissionFlags: [PermissionFlag.APPLICATIONS],
+});
+```
+
+يُشار بعد ذلك إلى `universalIdentifier` لهذا الدور في `application-config.ts` باسم `defaultRoleUniversalIdentifier`. بعبارة أخرى:
+
+* **\\*.role.ts** يحدد ما يمكن أن يفعله الدور الافتراضي للوظيفة.
+* **application-config.ts** يشير إلى ذلك الدور بحيث ترث وظائفك أذوناته.
+
+الملاحظات:
+
+* ابدأ من الدور المُنشأ بالقالب، ثم قيّده تدريجيًا باتباع مبدأ أقل الامتياز.
+* استبدل `objectPermissions` و`fieldPermissions` بالكائنات/الحقول التي تحتاجها وظائفك.
+* `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).
+
+### تكوين الوظيفة المنطقية ونقطة الدخول
+
+كل ملف وظيفة يستخدم `defineLogicFunction()` لتصدير تكوين مع معالج ومشغّلات اختيارية.
+
+```typescript
+// src/app/createPostCard.logic-function.ts
+import { defineLogicFunction } from 'twenty-sdk';
+import type { DatabaseEventPayload, ObjectRecordCreateEvent, CronPayload, RoutePayload } from 'twenty-sdk';
+import { CoreApiClient, type Person } from 'twenty-sdk/generated';
+
+const handler = async (params: RoutePayload) => {
+  const client = new CoreApiClient();
+  const name = 'name' in params.queryStringParameters
+    ? params.queryStringParameters.name ?? process.env.DEFAULT_RECIPIENT_NAME ?? 'Hello world'
+    : 'Hello world';
+
+  const result = await client.mutation({
+    createPostCard: {
+      __args: { data: { name } },
+      id: true,
+      name: true,
+    },
+  });
+  return result;
+};
+
+export default defineLogicFunction({
+  universalIdentifier: 'e56d363b-0bdc-4d8a-a393-6f0d1c75bdcf',
+  name: 'create-new-post-card',
+  timeoutSeconds: 2,
+  handler,
+  triggers: [
+    // Public HTTP route trigger '/s/post-card/create'
+    {
+      universalIdentifier: 'c9f84c8d-b26d-40d1-95dd-4f834ae5a2c6',
+      type: 'route',
+      path: '/post-card/create',
+      httpMethod: 'GET',
+      isAuthRequired: false,
+    },
+    // Cron trigger (CRON pattern)
+    // {
+    //   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'],
+    // },
+  ],
+});
+```
+
+أنواع المشغلات الشائعة:
+
+* **route**: يعرِض وظيفتك على مسار وطريقة HTTP **تحت نقطة النهاية `/s/`**:
+
+> مثال: `path: '/post-card/create',` -> الاستدعاء على `<APP_URL>/s/post-card/create`
+
+* **cron**: يشغّل وظيفتك على جدول باستخدام تعبير CRON.
+* **databaseEvent**: يعمل على أحداث دورة حياة كائنات مساحة العمل. عندما تكون عملية الحدث هي `updated`، يمكن تحديد الحقول المحددة المراد الاستماع إليها في مصفوفة `updatedFields`. إذا تُركت غير معرّفة أو فارغة، فسيؤدي أي تحديث إلى تشغيل الدالة.
+
+> مثال: `person.updated`
+
+الملاحظات:
+
+* المصفوفة `triggers` اختيارية. يمكن استخدام الوظائف بدون مشغلات كوظائف مساعدة تُستدعى بواسطة وظائف أخرى.
+* يمكنك مزج أنواع متعددة من المشغلات في وظيفة واحدة.
+
+### دوال ما قبل التثبيت
+
+دالة ما قبل التثبيت هي دالة منطقية تعمل تلقائيًا قبل تثبيت تطبيقك على مساحة عمل. يفيد ذلك في مهام التحقق، وفحص المتطلبات المسبقة، أو تجهيز حالة مساحة العمل قبل متابعة التثبيت الرئيسي.
+
+عند إنشاء هيكل تطبيق جديد باستخدام `create-twenty-app`، يتم إنشاء دالة ما قبل التثبيت لك في `src/logic-functions/pre-install.ts`:
+
+```typescript
+// src/logic-functions/pre-install.ts
+import { definePreInstallLogicFunction, type InstallLogicFunctionPayload } from 'twenty-sdk';
+
+const handler = async (payload: InstallLogicFunctionPayload): Promise<void> => {
+  console.log('Pre install logic function executed successfully!', payload.previousVersion);
+};
+
+export default definePreInstallLogicFunction({
+  universalIdentifier: '<generated-uuid>',
+  name: 'pre-install',
+  description: 'Runs before installation to prepare the application.',
+  timeoutSeconds: 300,
+  handler,
+});
+```
+
+يمكنك أيضًا تنفيذ دالة ما قبل التثبيت يدويًا في أي وقت باستخدام CLI:
+
+```bash filename="Terminal"
+yarn twenty function:execute --preInstall
+```
+
+النقاط الرئيسية:
+
+* تستخدم دوال ما قبل التثبيت `definePreInstallLogicFunction()` — وهو إصدار متخصص يستبعد إعدادات المُشغِّل (`cronTriggerSettings` و`databaseEventTriggerSettings` و`httpRouteTriggerSettings` و`isTool`).
+* يتلقى المُعالج `InstallLogicFunctionPayload` يحوي `{ previousVersion: string }` — إصدار التطبيق الذي كان مُثبّتًا سابقًا (أو سلسلة فارغة للتثبيتات الجديدة).
+* يُسمح بدالة ما قبل التثبيت واحدة فقط لكل تطبيق. سيُنتج إنشاء ملف البيان خطأً إذا تم اكتشاف أكثر من واحدة.
+* يتم تعيين `universalIdentifier` للدالة تلقائيًا كـ `preInstallLogicFunctionUniversalIdentifier` في بيان التطبيق أثناء الإنشاء — لست بحاجة إلى الإشارة إليه في `defineApplication()`.
+* تم ضبط المهلة الافتراضية على 300 ثانية (5 دقائق) للسماح بمهام التحضير الأطول.
+* لا تحتاج دوال ما قبل التثبيت إلى مُشغِّلات — إذ يستدعيها النظام الأساسي قبل التثبيت أو يدويًا عبر `function:execute --preInstall`.
+
+### دوال ما بعد التثبيت
+
+دالة ما بعد التثبيت هي دالة منطقية تعمل تلقائيًا بعد تثبيت تطبيقك على مساحة عمل. هذا مفيد لمهام الإعداد لمرة واحدة مثل تهيئة البيانات الافتراضية، وإنشاء السجلات الأولية، أو تكوين إعدادات مساحة العمل.
+
+عند إنشاء هيكل تطبيق جديد باستخدام `create-twenty-app`، يتم إنشاء دالة ما بعد التثبيت لك في `src/logic-functions/post-install.ts`:
+
+```typescript
+// src/logic-functions/post-install.ts
+import { definePostInstallLogicFunction, type InstallLogicFunctionPayload } from 'twenty-sdk';
+
+const handler = async (payload: InstallLogicFunctionPayload): Promise<void> => {
+  console.log('Post install logic function executed successfully!', payload.previousVersion);
+};
+
+export default definePostInstallLogicFunction({
+  universalIdentifier: '<generated-uuid>',
+  name: 'post-install',
+  description: 'Runs after installation to set up the application.',
+  timeoutSeconds: 300,
+  handler,
+});
+```
+
+يمكنك أيضًا تنفيذ دالة ما بعد التثبيت يدويًا في أي وقت باستخدام CLI:
+
+```bash filename="Terminal"
+yarn twenty function:execute --postInstall
+```
+
+النقاط الرئيسية:
+
+* تستخدم دوال ما بعد التثبيت `definePostInstallLogicFunction()` — وهو إصدار متخصص يستبعد إعدادات المُشغِّل (`cronTriggerSettings` و`databaseEventTriggerSettings` و`httpRouteTriggerSettings` و`isTool`).
+* يتلقى المُعالج `InstallLogicFunctionPayload` يحوي `{ previousVersion: string }` — إصدار التطبيق الذي كان مُثبّتًا سابقًا (أو سلسلة فارغة للتثبيتات الجديدة).
+* يُسمح بدالة ما بعد التثبيت واحدة فقط لكل تطبيق. سيُنتج إنشاء ملف البيان خطأً إذا تم اكتشاف أكثر من واحدة.
+* يتم تعيين `universalIdentifier` للدالة تلقائيًا كـ `postInstallLogicFunctionUniversalIdentifier` في بيان التطبيق أثناء الإنشاء — لست بحاجة إلى الإشارة إليه في `defineApplication()`.
+* تم تعيين مهلة افتراضية إلى 300 ثانية (5 دقائق) للسماح بمهام الإعداد الأطول مثل تهيئة البيانات.
+* لا تحتاج دوال ما بعد التثبيت إلى مُشغِّلات — حيث يستدعيها النظام الأساسي أثناء التثبيت أو يدويًا عبر `function:execute --postInstall`.
+
+### حمولة مشغل المسار
+
+<Warning>
+**تغيير غير متوافق (v1.16، يناير 2026):** لقد تغير تنسيق حمولة مشغل المسار. قبل v1.16، كانت معلمات الاستعلام، ومعلمات المسار، وجسم الطلب تُرسل مباشرةً كحمولة. بدءًا من v1.16، أصبحت متداخلة داخل كائن منظَّم `RoutePayload`.
+
+**قبل v1.16:**
+```typescript
+const handler = async (params) => {
+  const { param1, param2 } = params; // Direct access
+};
+```
+
+**بعد v1.16:**
+```typescript
+const handler = async (event: RoutePayload) => {
+  const { param1, param2 } = event.body; // Access via .body
+  const { queryParam } = event.queryStringParameters;
+  const { id } = event.pathParameters;
+};
+```
+
+**لترحيل الدوال الحالية:** حدّث المعالج لديك لفكّ البنية من `event.body` أو `event.queryStringParameters` أو `event.pathParameters` بدلاً من القراءة مباشرةً من كائن params.
+</Warning>
+
+عندما يستدعي مشغّل المسار وظيفتك المنطقية، يتلقى كائنًا من النوع `RoutePayload` يتبع تنسيق AWS HTTP API v2. استورد النوع من `twenty-sdk`:
+
+```typescript
+import { defineLogicFunction, type RoutePayload } from 'twenty-sdk';
+
+const handler = async (event: RoutePayload) => {
+  // Access request data
+  const { headers, queryStringParameters, pathParameters, body } = event;
+
+  // HTTP method and path are available in requestContext
+  const { method, path } = event.requestContext.http;
+
+  return { message: 'Success' };
+};
+```
+
+يحتوي نوع `RoutePayload` على البنية التالية:
+
+| الخاصية                      | النوع                                 | الوصف                                                                                   |
+| ---------------------------- | ------------------------------------- | --------------------------------------------------------------------------------------- |
+| `headers`                    | `Record<string, string \| undefined>` | رؤوس HTTP (فقط تلك المدرجة في `forwardedRequestHeaders`)                                |
+| `queryStringParameters`      | `Record<string, string \| undefined>` | معلمات سلسلة الاستعلام (تُضمّ القيم المتعددة باستخدام فواصل)                            |
+| `pathParameters`             | `Record<string, string \| undefined>` | معلمات المسار المستخرجة من نمط المسار (على سبيل المثال، `/users/:id` → `{ id: '123' }`) |
+| `المحتوى`                    | `object \| null`                      | جسم الطلب المُحلَّل (JSON)                                                              |
+| `isBase64Encoded`            | `قيمة منطقية`                         | ما إذا كان جسم الطلب مُرمَّزًا بترميز base64                                            |
+| `requestContext.http.method` | `string`                              | طريقة HTTP (GET, POST, PUT, PATCH, DELETE)                                              |
+| `requestContext.http.path`   | `string`                              | المسار الخام للطلب                                                                      |
+
+### تمرير رؤوس HTTP
+
+افتراضيًا، **لا** تُمرَّر رؤوس HTTP من الطلبات الواردة إلى دالتك المنطقية لأسباب أمنية. للوصول إلى رؤوس محددة، قم بإدراجها صراحةً في مصفوفة `forwardedRequestHeaders`:
+
+```typescript
+export default defineLogicFunction({
+  universalIdentifier: 'e56d363b-0bdc-4d8a-a393-6f0d1c75bdcf',
+  name: 'webhook-handler',
+  handler,
+  triggers: [
+    {
+      universalIdentifier: 'c9f84c8d-b26d-40d1-95dd-4f834ae5a2c6',
+      type: 'route',
+      path: '/webhook',
+      httpMethod: 'POST',
+      isAuthRequired: false,
+      forwardedRequestHeaders: ['x-webhook-signature', 'content-type'],
+    },
+  ],
+});
+```
+
+في المعالج الخاص بك، يمكنك حينها الوصول إلى هذه الرؤوس:
+
+```typescript
+const handler = async (event: RoutePayload) => {
+  const signature = event.headers['x-webhook-signature'];
+  const contentType = event.headers['content-type'];
+
+  // Validate webhook signature...
+  return { received: true };
+};
+```
+
+<Note>
+  تُحوَّل أسماء الرؤوس إلى أحرف صغيرة. يمكنك الوصول إليها باستخدام مفاتيح بأحرف صغيرة (على سبيل المثال، `event.headers['content-type']`).
+</Note>
+
+يمكنك إنشاء وظائف جديدة بطريقتين:
+
+* **مُنشأ بالقالب**: شغّل `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 { CoreApiClient } from 'twenty-sdk/generated';
+
+const handler = async (params: { companyName: string; domain?: string }) => {
+  const client = new CoreApiClient();
+
+  const result = await client.mutation({
+    createTask: {
+      __args: {
+        data: {
+          title: `Enrich data for ${params.companyName}`,
+          body: `Domain: ${params.domain ?? 'unknown'}`,
+        },
+      },
+      id: true,
+    },
+  });
+
+  return { taskId: result.createTask.id };
+};
+
+export default defineLogicFunction({
+  universalIdentifier: 'f47ac10b-58cc-4372-a567-0e02b2c3d479',
+  name: 'enrich-company',
+  description: 'Enrich a company record with external data',
+  timeoutSeconds: 10,
+  handler,
+  isTool: true,
+  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/front-components/my-widget.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.
+* يشير الحقل `component` إلى مكوّن React الخاص بك.
+* يتم بناء المكوّنات ومزامنتها تلقائيًا أثناء `yarn twenty app:dev`.
+
+يمكنك إنشاء مكوّنات أمامية جديدة بطريقتين:
+
+* **مُنشأ بالقالب**: شغّل `yarn twenty entity:add` واختر خيار إضافة مكوّن أمامي جديد.
+* **يدوي**: أنشئ ملفًا جديدًا `.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: '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`,
+});
+```
+
+النقاط الرئيسية:
+
+* `name` هي سلسلة معرّف فريدة للمهارة (يُنصَح باستخدام kebab-case).
+* `label` هو اسم العرض المقروء للبشر الظاهر في واجهة المستخدم.
+* `content` يحتوي على تعليمات المهارة — وهو النص الذي يستخدمه وكيل الذكاء الاصطناعي.
+* `icon` (اختياري) يحدّد الأيقونة المعروضة في واجهة المستخدم.
+* `description` (اختياري) يوفّر سياقًا إضافيًا حول غرض المهارة.
+
+يمكنك إنشاء مهارات جديدة بطريقتين:
+
+* **مُنشأ بالقالب**: شغِّل `yarn twenty entity:add` واختر خيار إضافة مهارة جديدة.
+* **يدوي**: أنشئ ملفًا جديدًا واستخدم `defineSkill()` مع اتباع النمط نفسه.
+
+### عملاء مُولَّدون مضبوطو الأنواع
+
+يتم توليد عميلين مضبوطي الأنواع تلقائيًا بواسطة `yarn twenty app:dev` وتخزينهما في `node_modules/twenty-sdk/generated` استنادًا إلى مخطط مساحة العمل لديك:
+
+* **`CoreApiClient`** — يُجري استعلامات إلى نقطة النهاية `/graphql` للحصول على بيانات مساحة العمل
+* **`MetadataApiClient`** — يستعلم عن نقطة النهاية `/metadata` لتكوين مساحة العمل وتحميل الملفات.
+
+```typescript
+import { CoreApiClient, MetadataApiClient } from 'twenty-sdk/generated';
+
+const client = new CoreApiClient();
+const { me } = await client.query({ me: { id: true, displayName: true } });
+
+const metadataClient = new MetadataApiClient();
+const { currentWorkspace } = await metadataClient.query({ currentWorkspace: { id: true } });
+```
+
+يُعاد توليد كلا العميلين تلقائيًا بواسطة `yarn twenty app:dev` كلما تغيّرت كائناتك أو حقولك.
+
+#### بيانات الاعتماد وقت التشغيل في الدوال المنطقية
+
+عندما تعمل دالتك على Twenty، يقوم النظام الأساسي بحقن بيانات الاعتماد كمتغيرات بيئة قبل تنفيذ كودك:
+
+* `TWENTY_API_URL`: عنوان URL الأساسي لواجهة Twenty البرمجية التي يستهدفها تطبيقك.
+* `TWENTY_API_KEY`: مفتاح قصير العمر ذو نطاق يقتصر على الدور الافتراضي لوظيفة تطبيقك.
+
+الملاحظات:
+
+* لا تحتاج إلى تمرير عنوان URL أو مفتاح واجهة برمجة التطبيقات إلى العميل المُولَّد. يقوم بقراءة `TWENTY_API_URL` و`TWENTY_API_KEY` من process.env وقت التشغيل.
+* تُحدَّد أذونات مفتاح واجهة برمجة التطبيقات بواسطة الدور المشار إليه في `application-config.ts` عبر `defaultRoleUniversalIdentifier`. هذا هو الدور الافتراضي الذي تستخدمه الدوال المنطقية في تطبيقك.
+* يمكن للتطبيقات تعريف أدوار لاتباع مبدأ أقل الامتياز. امنح فقط الأذونات التي تحتاجها وظائفك، ثم وجّه `defaultRoleUniversalIdentifier` إلى المعرّف الشامل لذلك الدور.
+
+#### رفع الملفات
+
+يتضمن `MetadataApiClient` المُولَّد طريقة `uploadFile` لإرفاق الملفات بالحقول من نوع ملف ضمن كائنات مساحة العمل الخاصة بك. نظرًا لأن عملاء GraphQL القياسيون لا يدعمون تحميل الملفات متعددة الأجزاء افتراضيًا، يوفر العميل هذه الطريقة المخصصة التي تطبق [مواصفة طلب GraphQL متعدد الأجزاء](https://github.com/jaydenseric/graphql-multipart-request-spec) في الخلفية.
+
+```typescript
+import { MetadataApiClient } from 'twenty-sdk/generated';
+import * as fs from 'fs';
+
+const metadataClient = new MetadataApiClient();
+
+const fileBuffer = fs.readFileSync('./invoice.pdf');
+
+const uploadedFile = await metadataClient.uploadFile(
+  fileBuffer,                                         // file contents as a Buffer
+  'invoice.pdf',                                      // filename
+  'application/pdf',                                  // MIME type (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` لحقل نوع الملف في كائنك                                 |
+
+النقاط الرئيسية:
+
+* تتوفر طريقة `uploadFile` على `MetadataApiClient` لأن عملية الـ mutation الخاصة بالرفع تُعالَج عبر نقطة النهاية `/metadata`.
+* تستخدم `universalIdentifier` الخاص بالحقل (وليس المعرّف الخاص بمساحة العمل)، ليعمل كود الرفع لديك عبر أي مساحة عمل مُثبَّت فيها تطبيقك — بما يتماشى مع كيفية إشارة التطبيقات إلى الحقول في كل مكان آخر.
+* العنوان `url` المُعاد هو عنوان URL موقّع يمكنك استخدامه للوصول إلى الملف المرفوع.
+
+### مثال Hello World
+
+استكشف مثالًا بسيطًا شاملًا من البداية إلى النهاية يوضح الكائنات والوظائف المنطقية والمكوّنات الأمامية ومشغّلات متعددة [هنا](https://github.com/twentyhq/twenty/tree/main/packages/twenty-apps/hello-world).

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

@@ -0,0 +1,233 @@
+---
+title: البدء
+description: أنشئ أول تطبيق Twenty خلال دقائق.
+---
+
+<Warning>
+التطبيقات حاليًا في مرحلة الاختبار الألفا. الميزة تعمل لكنها لا تزال قيد التطور.
+</Warning>
+
+تتيح لك التطبيقات توسيع Twenty باستخدام كائنات وحقول ووظائف منطقية ومهارات ذكاء اصطناعي ومكونات واجهة مستخدم مخصصة — جميعها تُدار ككود.
+
+**ما الذي يمكنك فعله اليوم:**
+
+* عرِّف كائنات وحقولًا مخصصة على شكل كود (نموذج بيانات مُدار)
+* أنشئ وظائف منطقية مع مشغلات مخصصة (مسارات HTTP، cron، أحداث قاعدة البيانات)
+* حدد المهارات لوكلاء الذكاء الاصطناعي
+* أنشئ مكونات واجهية تُعرَض داخل واجهة مستخدم Twenty
+* انشر التطبيق نفسه عبر مساحات عمل متعددة
+
+## المتطلبات الأساسية
+
+* Node.js 24+ وYarn 4
+* مساحة عمل Twenty ومفتاح واجهة برمجة التطبيقات (أنشئ واحدًا على https://app.twenty.com/settings/api-webhooks)
+
+## البدء
+
+أنشئ تطبيقًا جديدًا باستخدام المُهيئ الرسمي، ثم قم بالمصادقة وابدأ التطوير:
+
+```bash filename="Terminal"
+# Scaffold a new app (includes all examples by default)
+npx create-twenty-app@latest my-twenty-app
+cd my-twenty-app
+
+# Start dev mode: automatically syncs local changes to your workspace
+yarn twenty app:dev
+```
+
+يدعم المُهيئ وضعين للتحكم في ملفات الأمثلة التي سيتم تضمينها:
+
+```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
+```
+
+من هنا يمكنك:
+
+```bash filename="Terminal"
+# Add a new entity to your application (guided)
+yarn twenty entity:add
+
+# Watch your application's function logs
+yarn twenty function:logs
+
+# Execute a function by name
+yarn twenty function:execute -n my-function -p '{"name": "test"}'
+
+# Execute the pre-install function
+yarn twenty function:execute --preInstall
+
+# Execute the post-install function
+yarn twenty function:execute --postInstall
+
+# Uninstall the application from the current workspace
+yarn twenty app:uninstall
+
+# Display commands' 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).
+
+## هيكل المشروع (مُنشأ بالقالب)
+
+عند تشغيل `npx create-twenty-app@latest my-twenty-app`، يقوم المُهيئ بما يلي:
+
+* ينسخ تطبيقًا أساسيًا مصغّرًا إلى `my-twenty-app/`
+* يضيف اعتمادًا محليًا `twenty-sdk` وتهيئة Yarn 4
+* ينشئ ملفات ضبط ونصوصًا مرتبطة بـ `twenty` CLI
+* يُنشئ الملفات الأساسية (تهيئة التطبيق، دور الدالة الافتراضي، دالتا ما قبل التثبيت وما بعد التثبيت) بالإضافة إلى ملفات أمثلة استنادًا إلى وضع الإنشاء.
+
+يبدو التطبيق المُنشأ حديثًا باستخدام الوضع الافتراضي `--exhaustive` كما يلي:
+
+```text filename="my-twenty-app/"
+my-twenty-app/
+  package.json
+  yarn.lock
+  .gitignore
+  .nvmrc
+  .yarnrc.yml
+  .yarn/
+    install-state.gz
+  .oxlintrc.json
+  tsconfig.json
+  README.md
+  public/                           # Public assets folder (images, fonts, etc.)
+  src/
+  ├── 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
+  │   ├── pre-install.ts                # Pre-install 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
+```
+
+مع `--minimal`، سيتم إنشاء الملفات الأساسية فقط (`application-config.ts`، `roles/default-role.ts`، `logic-functions/pre-install.ts`، و`logic-functions/post-install.ts`).
+
+بشكل عام:
+
+* **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 المتوقع للمشروع.
+* **.oxlintrc.json** و **tsconfig.json**: يقدّمان إعدادات الفحص والتهيئة لـ TypeScript لمصادر TypeScript في تطبيقك.
+* **README.md**: ملف README قصير في جذر التطبيق يتضمن تعليمات أساسية.
+* **public/**: مجلد لتخزين الأصول العامة (صور، خطوط، ملفات ثابتة) التي سيتم تقديمها مع تطبيقك. الملفات الموضوعة هنا تُرفع أثناء المزامنة وتكون متاحة أثناء وقت التشغيل.
+* **src/**: المكان الرئيسي حيث تعرّف تطبيقك ككود
+
+### اكتشاف الكيانات
+
+يكتشف SDK الكيانات عبر تحليل ملفات TypeScript الخاصة بك بحثًا عن استدعاءات **`export default define<Entity>({...})`**. يحتوي كل نوع كيان على دالة مساعدة مقابلة يتم تصديرها من `twenty-sdk`:
+
+| دالة مساعدة                      | نوع الكيان                                     |
+| -------------------------------- | ---------------------------------------------- |
+| `defineObject`                   | تعريفات كائنات مخصصة                           |
+| `defineLogicFunction`            | تعريفات الوظائف المنطقية                       |
+| `definePreInstallLogicFunction`  | دالة منطقية لما قبل التثبيت (تعمل قبل التثبيت) |
+| `definePostInstallLogicFunction` | دالة منطقية لما بعد التثبيت (تعمل بعد التثبيت) |
+| `defineFrontComponent`           | تعريفات المكونات الواجهية                      |
+| `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 twenty app:dev` بتوليد عميلين API مضبوطي الأنواع تلقائيًا في `node_modules/twenty-sdk/generated`: `CoreApiClient` (لبيانات مساحة العمل عبر `/graphql`) و`MetadataApiClient` (لتكوين مساحة العمل وتحميل الملفات عبر `/metadata`).
+* `yarn twenty entity:add` سيضيف ملفات تعريف الكيانات ضمن `src/` لكائناتك المخصّصة، والوظائف، ومكوّنات الواجهة الأمامية، والأدوار، والمهارات، وغير ذلك.
+
+## المصادقة
+
+في المرة الأولى التي تشغّل فيها `yarn twenty auth:login`، سيُطلب منك إدخال:
+
+* عنوان URL لواجهة برمجة التطبيقات (الافتراضي http://localhost:3000 أو ملف تعريف مساحة العمل الحالية لديك)
+* مفتاح واجهة برمجة التطبيقات
+
+تُخزَّن بيانات اعتمادك لكل مستخدم في `~/.twenty/config.json`. يمكنك الاحتفاظ بملفات تعريف متعددة والتبديل بينها.
+
+### إدارة مساحات العمل
+
+```bash filename="Terminal"
+# Login interactively (recommended)
+yarn twenty auth:login
+
+# Login to a specific workspace profile
+yarn twenty auth:login --workspace my-custom-workspace
+
+# List all configured workspaces
+yarn twenty auth:list
+
+# Switch the default workspace (interactive)
+yarn twenty auth:switch
+
+# Switch to a specific workspace
+yarn twenty auth:switch production
+
+# Check current authentication status
+yarn twenty auth:status
+```
+
+بمجرد أن تقوم بالتبديل بين مساحات العمل باستخدام `yarn twenty auth:switch`، ستستخدم جميع الأوامر اللاحقة تلك المساحة افتراضيًا. لا يزال بإمكانك تجاوزه مؤقتًا باستخدام `--workspace <name>`.
+
+## إعداد يدوي (بدون المهيئ)
+
+بينما نوصي باستخدام `create-twenty-app` للحصول على أفضل تجربة للبدء، يمكنك أيضًا إعداد مشروع يدويًا. لا تثبّت CLI عالميًا. بدل ذلك، أضف `twenty-sdk` كاعتماد محلي واربط سكربتًا واحدًا في ملف package.json لديك:
+
+```bash filename="Terminal"
+yarn add -D twenty-sdk
+```
+
+ثم أضف سكربتًا باسم `twenty`:
+
+```json filename="package.json"
+{
+  "scripts": {
+    "twenty": "twenty"
+  }
+}
+```
+
+الآن يمكنك تشغيل جميع الأوامر عبر `yarn twenty <command>`، مثلًا: `yarn twenty app:dev`، `yarn twenty help`، إلخ.
+
+## استكشاف الأخطاء وإصلاحها
+
+* أخطاء المصادقة: شغّل `yarn twenty auth:login` وتأكد من أن مفتاح واجهة برمجة التطبيقات لديك يمتلك الأذونات المطلوبة.
+* يتعذّر الاتصال بالخادم: تحقق من عنوان URL لواجهة برمجة التطبيقات وأن خادم Twenty قابل للوصول.
+* الأنواع أو العميل مفقود/قديم: أعد تشغيل `yarn twenty app:dev` — فهو ينشئ العميل مضبوط الأنواع بشكل تلقائي.
+* وضع التطوير لا يزامن: تأكد من أن `yarn twenty app:dev` قيد التشغيل وأن التغييرات ليست متجاهلة من بيئتك.
+
+قناة المساعدة على Discord: https://discord.com/channels/1130383047699738754/1130386664812982322

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

@@ -0,0 +1,119 @@
+---
+title: النشر
+description: وزّع تطبيق Twenty الخاص بك على سوق Twenty أو انشره داخليًا.
+---
+
+<Warning>
+التطبيقات حاليًا في مرحلة الاختبار الألفا. الميزة تعمل لكنها لا تزال قيد التطور.
+</Warning>
+
+## نظرة عامة
+
+بمجرد أن يكون تطبيقك [مبنيًا ومختبرًا محليًا](/l/ar/developers/extend/apps/building)، لديك مساران لتوزيعه:
+
+* **النشر على npm** — أدرج تطبيقك في سوق Twenty ليتسنى لأي مساحة عمل اكتشافه وتثبيته.
+* **إرسال tarball** — انشر تطبيقك إلى خادم Twenty معيّن للاستخدام الداخلي من دون جعله متاحًا للعامة.
+
+## النشر على npm
+
+يُتيح النشر على npm إمكانية العثور على تطبيقك في سوق Twenty. يمكن لأي مساحة عمل في Twenty استعراض تطبيقات السوق وتثبيتها وترقيتها مباشرةً من واجهة المستخدم.
+
+### المتطلبات
+
+* حساب على [npm](https://www.npmjs.com)
+* يجب أن يستخدم اسم الحزمة البادئة `twenty-app-` (مثلًا، `twenty-app-postcard-sender`)
+
+### الخطوات
+
+1. **قم ببناء تطبيقك** — تقوم أداة CLI بتجميع مصادر TypeScript الخاصة بك وإنشاء ملف بيان التطبيق:
+
+```bash filename="Terminal"
+yarn twenty app:build
+```
+
+2. **النشر على npm** — ادفع الحزمة المبنية إلى سجل npm:
+
+```bash filename="Terminal"
+npx twenty app:publish
+```
+
+### الاكتشاف التلقائي
+
+تُكتشف الحِزم التي تحمل البادئة `twenty-app-` تلقائيًا بواسطة فهرس سوق Twenty. بعد نشره، سيظهر تطبيقك في السوق خلال بضع دقائق — من دون الحاجة إلى تسجيل يدوي أو موافقة يدوية.
+
+### النشر عبر CI
+
+يتضمن المشروع المُولَّد سير عمل GitHub Actions يقوم بالنشر عند كل إصدار. يشغِّل `app:build`، ثم ينفِّذ `npm publish --provenance` من مخرجات البناء:
+
+```yaml filename=".github/workflows/publish.yml"
+name: Publish
+on:
+  release:
+    types: [published]
+
+permissions:
+  contents: read
+  id-token: write
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: "24"
+          registry-url: https://registry.npmjs.org
+      - run: yarn install --immutable
+      - run: npx twenty app:build
+      - run: npm publish --provenance --access public
+        working-directory: .twenty/output
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+```
+
+بالنسبة لأنظمة CI الأخرى (GitLab CI، CircleCI، إلخ)، تنطبق الأوامر الثلاثة نفسها: `yarn install`، ثم `npx twenty app:build`، ثم `npm publish` من `.twenty/output`.
+
+<Tip>
+**npm provenance** اختياري ولكنه موصى به. يضيف النشر باستخدام `--provenance` شارة ثقة إلى إدراجك على npm، مما يتيح للمستخدمين التحقق من أن الحزمة تم بناؤها من التزام محدد ضمن خط أنابيب CI عام. راجع [وثائق npm provenance](https://docs.npmjs.com/generating-provenance-statements) للحصول على تعليمات الإعداد.
+</Tip>
+
+## التوزيع الداخلي
+
+بالنسبة للتطبيقات التي لا تريد إتاحتها للعامة — مثل الأدوات المملوكة، أو عمليات التكامل الخاصة بالمؤسسات فقط، أو الإصدارات التجريبية — يمكنك إرسال tarball مباشرةً إلى خادم Twenty.
+
+### إرسال tarball
+
+قم ببناء تطبيقك وانشره إلى خادم محدد في خطوة واحدة:
+
+```bash filename="Terminal"
+npx twenty app:publish --server <server-url>
+```
+
+يمكن لأي مساحة عمل على ذلك الخادم بعدها تثبيت التطبيق وترقيته من صفحة الإعدادات **التطبيقات**.
+
+### إدارة الإصدارات
+
+لطرح تحديث:
+
+1. ارفع قيمة الحقل `version` في ملف `package.json`
+2. أرسل tarball جديدًا باستخدام `npx twenty app:publish --server <server-url>`
+3. سترى مساحات العمل على ذلك الخادم الترقية متاحة في إعداداتها
+
+<Note>
+التطبيقات الداخلية مقتصرة على الخادم الذي تُرسل إليه. لن تظهر في السوق العام ولا يمكن لمساحات العمل على خوادم أخرى تثبيتها.
+</Note>
+
+## فئات التطبيقات
+
+تُنظِّم Twenty التطبيقات في ثلاث فئات استنادًا إلى طريقة توزيعها:
+
+| الفئة       | كيف يعمل                                                                                             | مرئي في سوق Twenty؟ |
+| ----------- | ---------------------------------------------------------------------------------------------------- | ------------------- |
+| **التطوير** | تطبيقات وضع التطوير المحلي التي تعمل عبر `yarn twenty app:dev`. تُستخدم للبناء والاختبار.            | لا                  |
+| **منشور**   | تطبيقات منشورة على npm مع البادئة `twenty-app-`. مدرجة في سوق Twenty لتتمكن أي مساحة عمل من تثبيتها. | نعم                 |
+| **داخلي**   | تطبيقات منشورة عبر tarball إلى خادم محدد. متاحة فقط لمساحات العمل على ذلك الخادم.                    | لا                  |
+
+<Tip>
+ابدأ في وضع **التطوير** أثناء بناء تطبيقك. عندما يصبح جاهزًا، اختر **منشور** (npm) للتوزيع الواسع أو **داخلي** (tarball) للنشر الخاص.
+</Tip>

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

@@ -171,7 +171,7 @@ export default defineObject({
 
 ستضيف الأوامر اللاحقة مزيدًا من الملفات والمجلدات:
 
-* سيقوم `yarn twenty app:dev` بتوليد عميلين API مضبوطي الأنواع تلقائيًا في `node_modules/twenty-sdk/generated`: `CoreApiClient` (لبيانات مساحة العمل عبر `/graphql`) و`MetadataApiClient` (لتكوين مساحة العمل وتحميل الملفات عبر `/metadata`).
+* سيقوم `yarn twenty app:dev` بتوليد عميلين API مضبوطي الأنواع تلقائيًا في `node_modules/twenty-sdk/clients`: `CoreApiClient` (لبيانات مساحة العمل عبر `/graphql`) و`MetadataApiClient` (لتكوين مساحة العمل وتحميل الملفات عبر `/metadata`).
 * `yarn twenty entity:add` سيضيف ملفات تعريف الكيانات ضمن `src/` لكائناتك المخصّصة، والوظائف، ومكوّنات الواجهة الأمامية، والأدوار، والمهارات، وغير ذلك.
 
 ## المصادقة
@@ -228,7 +228,7 @@ yarn twenty auth:status
 | `defineView()`                     | تعريف العروض المحفوظة للكائنات                       |
 | `defineNavigationMenuItem()`       | تعريف روابط التنقل في الشريط الجانبي                 |
 | `defineSkill()`                    | عرّف مهارات وكيل الذكاء الاصطناعي                    |
-| `defineAgent()`                    | Define AI agents with system prompts                 |
+| `defineAgent()`                    | عرِّف وكلاء الذكاء الاصطناعي باستخدام موجهات النظام  |
 
 تتحقق هذه الدوال من تكوينك وقت البناء وتوفّر إكمالًا تلقائيًا في بيئة التطوير وأمان الأنواع.
 
@@ -321,6 +321,72 @@ export default defineObject({
 لكن هذا غير مستحسن.
 </Note>
 
+### تعريف الحقول على الكائنات الموجودة
+
+استخدم `defineField()` لإضافة حقول مخصصة إلى الكائنات الموجودة — سواء الكائنات القياسية (مثل `company` و`person` و`opportunity`) أو الكائنات المخصصة التي تُعرِّفها تطبيقات أخرى. يوجد كل حقل في ملفه الخاص ويشير إلى الكائن الهدف بواسطة `universalIdentifier` الخاص به.
+
+للإشارة إلى الكائنات القياسية، استورد `STANDARD_OBJECT_UNIVERSAL_IDENTIFIERS` من `twenty-sdk`. يوفر هذا الثابت معرِّفات مستقرة لجميع الكائنات المضمنة وحقولها:
+
+```typescript
+// src/fields/apollo-total-funding.field.ts
+import {
+  defineField,
+  FieldType,
+  STANDARD_OBJECT_UNIVERSAL_IDENTIFIERS,
+} from 'twenty-sdk';
+
+export default defineField({
+  universalIdentifier: 'c90ae72d-4ddf-4f22-882f-eef98c91e40e',
+  objectUniversalIdentifier:
+    STANDARD_OBJECT_UNIVERSAL_IDENTIFIERS.company.universalIdentifier,
+  type: FieldType.CURRENCY,
+  name: 'apolloTotalFunding',
+  label: 'Total Funding',
+  description: 'Total funding raised by the company',
+  icon: 'IconCash',
+});
+```
+
+النقاط الرئيسية:
+
+* `objectUniversalIdentifier` يُحدِّد لـ Twenty الكائن الذي سيُرفَق به الحقل. استخدم `STANDARD_OBJECT_UNIVERSAL_IDENTIFIERS.<objectName>.universalIdentifier` للكائنات القياسية.
+* يتطلب كل حقل `universalIdentifier` ثابتًا خاصًا به، و`name`، و`type`، و`label`، و`objectUniversalIdentifier` الخاص بالكائن الهدف.
+* يمكنك إنشاء حقول جديدة باستخدام `yarn twenty entity:add` واختيار خيار الحقل.
+* يُصدَّر `STANDARD_OBJECT_UNIVERSAL_IDENTIFIERS` أيضًا باسم `STANDARD_OBJECT` لسهولة الاستخدام — كلاهما يشير إلى الثابت نفسه.
+
+تشمل الكائنات القياسية المتاحة: `attachment`، `blocklist`، `calendarChannel`، `calendarEvent`، `calendarEventParticipant`، `company`، `connectedAccount`، `dashboard`، `favorite`، `favoriteFolder`، `message`، `messageChannel`، `messageParticipant`، `messageThread`، `note`، `noteTarget`، `opportunity`، `person`، `task`، `taskTarget`، `timelineActivity`، `workflow`، `workflowAutomatedTrigger`، `workflowRun`، `workflowVersion`، و`workspaceMember`.
+
+يُوفِّر كل كائن قياسي أيضًا معرّفات حقوله. على سبيل المثال، للإشارة إلى حقل محدد على كائن قياسي ضمن أذونات الأدوار:
+
+```typescript
+STANDARD_OBJECT_UNIVERSAL_IDENTIFIERS.company.fields.name.universalIdentifier
+```
+
+#### حقول العلاقات على الكائنات الموجودة
+
+يمكنك أيضًا تعريف حقول علاقات تربط الكائنات الموجودة بكائناتك المخصصة:
+
+```typescript
+// src/fields/people-on-call-recording.field.ts
+import { defineField, FieldType, RelationType, STANDARD_OBJECT_UNIVERSAL_IDENTIFIERS } from 'twenty-sdk';
+import { CALL_RECORDING_OBJECT_UNIVERSAL_IDENTIFIER } from 'src/objects/call-recording';
+import { CALL_RECORDING_ON_PERSON_ID } from 'src/fields/call-recording-on-person.field';
+
+export default defineField({
+  universalIdentifier: '4a2b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d',
+  objectUniversalIdentifier:
+    CALL_RECORDING_OBJECT_UNIVERSAL_IDENTIFIER,
+  type: FieldType.RELATION,
+  name: 'person',
+  label: 'Person',
+  relationTargetObjectMetadataUniversalIdentifier:
+    STANDARD_OBJECT_UNIVERSAL_IDENTIFIERS.person.universalIdentifier,
+  relationTargetFieldMetadataUniversalIdentifier:
+    CALL_RECORDING_ON_PERSON_ID,
+  relationType: RelationType.MANY_TO_ONE,
+});
+```
+
 ### تكوين التطبيق (application-config.ts)
 
 كل تطبيق لديه ملف واحد `application-config.ts` يصف:
@@ -434,7 +500,7 @@ export default defineRole({
 // src/app/createPostCard.logic-function.ts
 import { defineLogicFunction } from 'twenty-sdk';
 import type { DatabaseEventPayload, ObjectRecordCreateEvent, CronPayload, RoutePayload } from 'twenty-sdk';
-import { CoreApiClient, type Person } from 'twenty-sdk/generated';
+import { CoreApiClient, type Person } from 'twenty-sdk/clients';
 
 const handler = async (params: RoutePayload) => {
   const client = new CoreApiClient();
@@ -679,7 +745,7 @@ const handler = async (event: RoutePayload) => {
 ```typescript
 // src/logic-functions/enrich-company.logic-function.ts
 import { defineLogicFunction } from 'twenty-sdk';
-import { CoreApiClient } from 'twenty-sdk/generated';
+import { CoreApiClient } from 'twenty-sdk/clients';
 
 const handler = async (params: { companyName: string; domain?: string }) => {
   const client = new CoreApiClient();
@@ -771,6 +837,255 @@ export default defineFrontComponent({
 * **مُنشأ بالقالب**: شغّل `yarn twenty entity:add` واختر خيار إضافة مكوّن أمامي جديد.
 * **يدوي**: أنشئ ملفًا جديدًا `.tsx` واستخدم `defineFrontComponent()` مع اتباع النمط نفسه.
 
+#### أين يمكن استخدام مكوّنات الواجهة الأمامية
+
+يمكن عرض مكوّنات الواجهة الأمامية في موقعين داخل Twenty:
+
+* **اللوحة الجانبية** — المكوّنات غير عديمة الرأس تفتح في اللوحة الجانبية اليمنى. هذا هو السلوك الافتراضي عندما يتم تشغيل مكوّن واجهة أمامية من قائمة الأوامر.
+* **الويدجت (لوحات المعلومات وصفحات السجلات)** — يمكن تضمين مكوّنات الواجهة الأمامية كويدجت داخل تخطيطات الصفحات. عند تكوين لوحة معلومات أو تخطيط صفحة سجل، يمكن للمستخدمين إضافة ويدجت لمكوّن واجهة أمامية.
+
+#### عديم الرأس مقابل غير عديم الرأس
+
+تأتي مكوّنات الواجهة الأمامية بوضعَي عرض يتحكّم بهما الخيار `isHeadless`:
+
+**غير عديم الرأس (افتراضي)** — يعرض المكوّن واجهة مستخدم مرئية. عند تشغيله من قائمة الأوامر يفتح في اللوحة الجانبية. هذا هو السلوك الافتراضي عندما تكون `isHeadless` تساوي `false` أو يتم تجاهلها.
+
+**عديم الرأس** — يتم تركيب المكوّن بشكل غير مرئي في الخلفية. لا يفتح اللوحة الجانبية. تم تصميم المكوّنات عديمة الرأس لإجراءات تنفّذ منطقًا ثم تُزيل تركيبها ذاتيًا — على سبيل المثال، تشغيل مهمة غير متزامنة، أو الانتقال إلى صفحة، أو إظهار نافذة تأكيد منبثقة. تتوافق بشكل طبيعي مع مكوّنات Command في SDK الموصوفة أدناه.
+
+```typescript
+export default defineFrontComponent({
+  universalIdentifier: 'a1b2c3d4-e5f6-7890-abcd-ef1234567890',
+  name: 'my-action',
+  description: 'Runs an action without opening the side panel',
+  component: MyAction,
+  isHeadless: true,
+  command: {
+    universalIdentifier: 'b2c3d4e5-f6a7-8901-bcde-f12345678901',
+    label: 'Run my action',
+  },
+});
+```
+
+#### إضافة عناصر قائمة الأوامر
+
+لجعل مكوّن واجهة أمامية يظهر كعنصر في قائمة الأوامر في Twenty، أضف الخاصية `command` إلى `defineFrontComponent()`. عند فتح المستخدمين لقائمة الأوامر (Cmd+K / Ctrl+K)، يظهر العنصر ويشغّل مكوّن الواجهة الأمامية عند النقر.
+
+يقبل كائن `command` الحقول التالية:
+
+| الحقل                                   | النوع                                      | الوصف                                                                           |
+| --------------------------------------- | ------------------------------------------ | ------------------------------------------------------------------------------- |
+| `universalIdentifier`                   | `string` (إلزامي)                          | معرّف فريد لعنصر قائمة الأوامر                                                  |
+| `التسمية`                               | `string` (إلزامي)                          | التسمية المعروضة في قائمة الأوامر                                               |
+| `أيقونة`                                | `string` (اختياري)                         | اسم الأيقونة (مثال: `'IconSparkles'`)                                           |
+| `isPinned`                              | `boolean` (اختياري)                        | ما إذا كان الأمر مثبتًا أعلى القائمة                                            |
+| `availabilityType`                      | `'GLOBAL' \| 'RECORD_SELECTION'` (اختياري) | `GLOBAL` يعرض الأمر في كل مكان؛ `RECORD_SELECTION` يعرضه فقط في سياقات السجلّات |
+| `availabilityObjectUniversalIdentifier` | `string` (اختياري)                         | تقييد الأمر بنوع كائن محدّد (مثال: Person)                                      |
+
+إليك مثالًا من تطبيق تسجيل المكالمات يضيف أمرًا محصورًا بسجلات Person:
+
+```typescript
+import { defineFrontComponent } from 'twenty-sdk';
+
+export default defineFrontComponent({
+  universalIdentifier: 'c3d4e5f6-a7b8-9012-cdef-123456789012',
+  name: 'Summarize Person Call Recordings',
+  description: 'Generates a summary of call recordings for a person',
+  component: SummarizePersonRecordings,
+  command: {
+    universalIdentifier: 'd4e5f6a7-b8c9-0123-defa-234567890123',
+    label: 'Summarize call recordings',
+    icon: 'IconSparkles',
+    isPinned: false,
+    availabilityType: 'RECORD_SELECTION',
+    availabilityObjectUniversalIdentifier:
+      '20202020-e674-48e5-a542-72570eee7213',
+  },
+});
+```
+
+عند مزامنة الأمر، يظهر في قائمة الأوامر. إذا كان مكوّن الواجهة الأمامية غير عديم الرأس، تُفتح اللوحة الجانبية مع عرض المكوّن بداخلها. إذا كان عديم الرأس، فسيتم تركيب المكوّن في الخلفية وتنفيذ منطقه.
+
+#### مكوّنات Command في SDK
+
+توفر حزمة `twenty-sdk` أربعة مكوّنات مساعدة من نوع Command مصممة للمكوّنات عديمة الرأس في الواجهة الأمامية. كل مكوّن ينفّذ إجراءً عند التركيب، ويتعامل مع الأخطاء بعرض إشعار Snackbar، ويزيل تركيب مكوّن الواجهة الأمامية تلقائيًا عند الانتهاء.
+
+استوردها من `twenty-sdk/command`:
+
+* **`Command`** — يشغّل رد نداء غير متزامن عبر الخاصية `execute`.
+* **`CommandLink`** — ينتقل إلى مسار في التطبيق. الخصائص: `to`، `params`، `queryParams`، `options`.
+* **`CommandModal`** — يفتح نافذة تأكيد منبثقة. إذا أكّد المستخدم، ينفّذ رد النداء `execute`. الخصائص: `title`، `subtitle`، `execute`، `confirmButtonText`، `confirmButtonAccent`.
+* **`CommandOpenSidePanelPage`** — يفتح صفحة محدّدة في اللوحة الجانبية. الخصائص: `page`، `pageTitle`، `pageIcon`.
+
+فيما يلي مثال كامل لمكوّن واجهة أمامية عديم الرأس يستخدم `Command` لتشغيل إجراء من قائمة الأوامر:
+
+```typescript
+// src/front-components/run-action.tsx
+import { defineFrontComponent } from 'twenty-sdk';
+import { Command } from 'twenty-sdk/command';
+import { CoreApiClient } from 'twenty-sdk/clients';
+
+const RunAction = () => {
+  const execute = async () => {
+    const client = new CoreApiClient();
+
+    await client.mutation({
+      createTask: {
+        __args: { data: { title: 'Created by my app' } },
+        id: true,
+      },
+    });
+  };
+
+  return <Command execute={execute} />;
+};
+
+export default defineFrontComponent({
+  universalIdentifier: 'e5f6a7b8-c9d0-1234-efab-345678901234',
+  name: 'run-action',
+  description: 'Creates a task from the command menu',
+  component: RunAction,
+  isHeadless: true,
+  command: {
+    universalIdentifier: 'f6a7b8c9-d0e1-2345-fabc-456789012345',
+    label: 'Run my action',
+    icon: 'IconPlayerPlay',
+  },
+});
+```
+
+ومثال يستخدم `CommandModal` لطلب التأكيد قبل التنفيذ:
+
+```typescript
+// src/front-components/delete-draft.tsx
+import { defineFrontComponent } from 'twenty-sdk';
+import { CommandModal } from 'twenty-sdk/command';
+
+const DeleteDraft = () => {
+  const execute = async () => {
+    // perform the deletion
+  };
+
+  return (
+    <CommandModal
+      title="Delete draft?"
+      subtitle="This action cannot be undone."
+      execute={execute}
+      confirmButtonText="Delete"
+      confirmButtonAccent="danger"
+    />
+  );
+};
+
+export default defineFrontComponent({
+  universalIdentifier: 'a7b8c9d0-e1f2-3456-abcd-567890123456',
+  name: 'delete-draft',
+  description: 'Deletes a draft with confirmation',
+  component: DeleteDraft,
+  isHeadless: true,
+  command: {
+    universalIdentifier: 'b8c9d0e1-f2a3-4567-bcde-678901234567',
+    label: 'Delete draft',
+    icon: 'IconTrash',
+  },
+});
+```
+
+#### سياق التنفيذ
+
+يتلقّى كل مكوّن واجهة أمامية سياق تنفيذ يوفّر معلومات حول مكان وكيفية تشغيله. يمكنك الوصول إلى قيم السياق باستخدام الخطافات من `twenty-sdk`:
+
+| الخطّاف                 | نوع القيمة المرجعة | الوصف                                                                                                               |
+| ----------------------- | ------------------ | ------------------------------------------------------------------------------------------------------------------- |
+| `useFrontComponentId()` | `string`           | المعرّف الفريد لمثيل مكوّن الواجهة الأمامية الحالي                                                                  |
+| `useRecordId()`         | `string \| null`   | معرّف السجل الحالي، عندما يعمل المكوّن في سياق سجل (مثال: ويدجت صفحة سجل أو أمر محصور بسجل). يُرجع `null` خلاف ذلك. |
+| `useUserId()`           | `string \| null`   | معرّف المستخدم الحالي                                                                                               |
+
+```typescript
+import { useRecordId, useUserId } from 'twenty-sdk';
+
+const MyWidget = () => {
+  const recordId = useRecordId();
+  const userId = useUserId();
+
+  return (
+    <div>
+      <p>Record: {recordId ?? 'none'}</p>
+      <p>User: {userId ?? 'anonymous'}</p>
+    </div>
+  );
+};
+```
+
+السياق تفاعلي — إذا تغيّر السجل المحيط، فستُرجع الخطافات القيم المحدّثة تلقائيًا.
+
+#### دوال واجهة برمجة تطبيقات المضيف
+
+تعمل مكوّنات الواجهة الأمامية في بيئة معزولة، لكنها تستطيع التفاعل مع واجهة مستخدم Twenty عبر مجموعة من الدوال التي يوفّرها المضيف. استوردها مباشرةً من `twenty-sdk`:
+
+```typescript
+import {
+  navigate,
+  closeSidePanel,
+  enqueueSnackbar,
+  unmountFrontComponent,
+  openSidePanelPage,
+  openCommandConfirmationModal,
+} from 'twenty-sdk';
+```
+
+| دالة                           | التوقيع                                                  | الوصف                                                                                                                                                         |
+| ------------------------------ | -------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `التنقل`                       | `(to, params?, queryParams?, options?) => Promise<void>` | الانتقال إلى مسار تطبيق محدّد النوع داخل Twenty                                                                                                               |
+| `closeSidePanel`               | `() => Promise<void>`                                    | إغلاق اللوحة الجانبية                                                                                                                                         |
+| `enqueueSnackbar`              | `(params) => Promise<void>`                              | عرض إشعار Snackbar. المعاملات: `message`، `variant` (`'error'`، `'success'`، `'info'`، `'warning'`)، `duration` اختياري، `detailedMessage`، `dedupeKey`       |
+| `unmountFrontComponent`        | `() => Promise<void>`                                    | إلغاء تركيب مكوّن الواجهة الأمامية الحالي (تستخدمه المكوّنات عديمة الرأس للتنظيف بعد التنفيذ)                                                                 |
+| `openSidePanelPage`            | `(params) => Promise<void>`                              | فتح صفحة في اللوحة الجانبية. المعاملات: `page`، `pageTitle`، `pageIcon`، `shouldResetSearchState`                                                             |
+| `openCommandConfirmationModal` | `(params) => Promise<'confirm' \| 'cancel'>`             | عرض نافذة تأكيد منبثقة والانتظار لرد المستخدم. المعاملات: `title`، `subtitle`، `confirmButtonText`، `confirmButtonAccent` (`'default'`، `'blue'`، `'danger'`) |
+
+فيما يلي مثال يستخدم واجهة برمجة تطبيقات المضيف لعرض Snackbar وإغلاق اللوحة الجانبية بعد اكتمال الإجراء:
+
+```typescript
+import { defineFrontComponent, useRecordId } from 'twenty-sdk';
+import { enqueueSnackbar, closeSidePanel } from 'twenty-sdk';
+import { CoreApiClient } from 'twenty-sdk/clients';
+
+const ArchiveRecord = () => {
+  const recordId = useRecordId();
+
+  const handleArchive = async () => {
+    const client = new CoreApiClient();
+
+    await client.mutation({
+      updateTask: {
+        __args: { id: recordId, data: { status: 'ARCHIVED' } },
+        id: true,
+      },
+    });
+
+    await enqueueSnackbar({
+      message: 'Record archived',
+      variant: 'success',
+    });
+
+    await closeSidePanel();
+  };
+
+  return (
+    <div style={{ padding: '20px' }}>
+      <p>Archive this record?</p>
+      <button onClick={handleArchive}>Archive</button>
+    </div>
+  );
+};
+
+export default defineFrontComponent({
+  universalIdentifier: 'c9d0e1f2-a3b4-5678-cdef-789012345678',
+  name: 'archive-record',
+  description: 'Archives the current record',
+  component: ArchiveRecord,
+});
+```
+
 ### المهارات
 
 تُحدِّد المهارات تعليمات وإمكانات قابلة لإعادة الاستخدام يمكن لوكلاء الذكاء الاصطناعي استخدامها داخل مساحة العمل لديك. استخدم `defineSkill()` لتعريف مهارات مع تحقّق مدمج:
@@ -806,9 +1121,9 @@ export default defineSkill({
 * **مُنشأ بالقالب**: شغِّل `yarn twenty entity:add` واختر خيار إضافة مهارة جديدة.
 * **يدوي**: أنشئ ملفًا جديدًا واستخدم `defineSkill()` مع اتباع النمط نفسه.
 
-### Agents
+### الوكلاء
 
-Agents define AI agents with system prompts that can operate within your workspace. Use `defineAgent()` to define agents with built-in validation:
+تمكّنك ميزة الوكلاء من تعريف وكلاء ذكاء اصطناعي قادرين على العمل ضمن مساحة عملك، باستخدام موجهات النظام. استخدم `defineAgent()` لتعريف وكلاء مع تحقق مدمج:
 
 ```typescript
 // src/agents/example-agent.ts
@@ -830,26 +1145,27 @@ export default defineAgent({
 
 النقاط الرئيسية:
 
-* `name` is a unique identifier string for the agent (kebab-case recommended).
+* `name` هي سلسلة معرّف فريدة للوكيل (يُنصَح باستخدام kebab-case).
 * `label` هو اسم العرض المقروء للبشر الظاهر في واجهة المستخدم.
-* `prompt` contains the system prompt — this is the instruction text that defines the agent's behavior.
+* `prompt` يحتوي موجه النظام — وهو نص التعليمات الذي يحدد سلوك الوكيل.
 * `icon` (اختياري) يحدّد الأيقونة المعروضة في واجهة المستخدم.
-* `description` (optional) provides additional context about the agent's purpose.
+* `description` (اختياري) يوفّر سياقًا إضافيًا حول غرض الوكيل.
 
-You can create new agents in two ways:
+يمكنك إنشاء وكلاء جدد بطريقتين:
 
-* **Scaffolded**: Run `yarn twenty entity:add` and choose the option to add a new agent.
-* **Manual**: Create a new file and use `defineAgent()`, following the same pattern.
+* **مُنشأ بالقالب**: شغِّل `yarn twenty entity:add` واختر خيار إضافة وكيل جديد.
+* **يدوي**: أنشئ ملفًا جديدًا واستخدم `defineAgent()` مع اتباع النمط نفسه.
 
 ### عملاء مُولَّدون مضبوطو الأنواع
 
-يتم توليد عميلين مضبوطي الأنواع تلقائيًا بواسطة `yarn twenty app:dev` وتخزينهما في `node_modules/twenty-sdk/generated` استنادًا إلى مخطط مساحة العمل لديك:
+يتم توليد عميلين مضبوطي الأنواع تلقائيًا بواسطة `yarn twenty app:dev` وتخزينهما في `node_modules/twenty-sdk/clients` استنادًا إلى مخطط مساحة العمل لديك:
 
 * **`CoreApiClient`** — يُجري استعلامات إلى نقطة النهاية `/graphql` للحصول على بيانات مساحة العمل
 * **`MetadataApiClient`** — يستعلم عن نقطة النهاية `/metadata` لتكوين مساحة العمل وتحميل الملفات.
 
 ```typescript
-import { CoreApiClient, MetadataApiClient } from 'twenty-sdk/generated';
+import { CoreApiClient } from 'twenty-sdk/clients';
+import { MetadataApiClient } from 'twenty-sdk/clients';
 
 const client = new CoreApiClient();
 const { me } = await client.query({ me: { id: true, displayName: true } });
@@ -858,7 +1174,7 @@ const metadataClient = new MetadataApiClient();
 const { currentWorkspace } = await metadataClient.query({ currentWorkspace: { id: true } });
 ```
 
-يُعاد توليد كلا العميلين تلقائيًا بواسطة `yarn twenty app:dev` كلما تغيّرت كائناتك أو حقولك.
+`CoreApiClient` يُعاد توليده تلقائيًا بواسطة `yarn twenty app:dev` كلما تغيّرت كائناتك أو حقولك. `MetadataApiClient` يأتي مُجهزًا مسبقًا مع SDK.
 
 #### بيانات الاعتماد وقت التشغيل في الوظائف المنطقية
 
@@ -875,10 +1191,10 @@ const { currentWorkspace } = await metadataClient.query({ currentWorkspace: { id
 
 #### رفع الملفات
 
-يتضمن `MetadataApiClient` المُولَّد طريقة `uploadFile` لإرفاق الملفات بالحقول من نوع ملف ضمن كائنات مساحة العمل الخاصة بك. نظرًا لأن عملاء GraphQL القياسيون لا يدعمون تحميل الملفات متعددة الأجزاء افتراضيًا، يوفر العميل هذه الطريقة المخصصة التي تطبق [مواصفة طلب GraphQL متعدد الأجزاء](https://github.com/jaydenseric/graphql-multipart-request-spec) في الخلفية.
+يتضمن `MetadataApiClient` طريقة `uploadFile` لإرفاق الملفات بالحقول من نوع ملف ضمن كائنات مساحة العمل الخاصة بك. نظرًا لأن عملاء GraphQL القياسيون لا يدعمون تحميل الملفات متعددة الأجزاء افتراضيًا، يوفر العميل هذه الطريقة المخصصة التي تطبق [مواصفة طلب GraphQL متعدد الأجزاء](https://github.com/jaydenseric/graphql-multipart-request-spec) في الخلفية.
 
 ```typescript
-import { MetadataApiClient } from 'twenty-sdk/generated';
+import { MetadataApiClient } from 'twenty-sdk/clients';
 import * as fs from 'fs';
 
 const metadataClient = new MetadataApiClient();

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

@@ -15,18 +15,18 @@ description: وسّع وظائف Twenty باستخدام واجهات برمجة
 
 * **واجهات برمجة التطبيقات**: استعلم وعدّل بيانات إدارة علاقات العملاء (CRM) لديك برمجياً باستخدام REST أو GraphQL
 * **خطافات الويب**: استقبل إشعارات في الوقت الفعلي عند وقوع أحداث في Twenty
-* **التطبيقات**: أنشئ تطبيقات مخصصة توسّع قدرات Twenty - قريباً!
+* **التطبيقات**: أنشئ تطبيقات مخصصة توسّع قدرات Twenty
 
 ## البدء
 
 <CardGroup cols={٢}>
-  <Card title="واجهات برمجة التطبيقات" icon="كود" href="/l/ar/developers/extend/capabilities/apis">
+  <Card title="واجهات برمجة التطبيقات" icon="كود" href="/l/ar/developers/extend/api">
     اتصل بـ Twenty برمجياً
   </Card>
-  <Card title="الويب هوكس" icon="bell" href="/l/ar/developers/extend/capabilities/webhooks">
+  <Card title="الويب هوكس" icon="bell" href="/l/ar/developers/extend/webhooks">
     احصل على إشعارات بالأحداث في الوقت الفعلي
   </Card>
-  <Card title="التطبيقات" icon="puzzle-piece" href="/l/ar/developers/extend/capabilities/apps">
-    أنشئ تخصيصات كرمز برمجي (ألفا)
+  <Card title="التطبيقات" icon="puzzle-piece" href="/l/ar/developers/extend/apps/getting-started">
+    أنشئ تخصيصات كرمز برمجي
   </Card>
 </CardGroup>

packages/twenty-docs/l/ar/developers/extend/webhooks.mdx

@@ -0,0 +1,116 @@
+---
+title: خطافات الويب
+description: استقبل إشعارات في الوقت الفعلي عند وقوع أحداث في نظام إدارة علاقات العملاء (CRM) الخاص بك.
+---
+
+import { VimeoEmbed } from '/snippets/vimeo-embed.mdx';
+
+تدفع خطافات الويب البيانات إلى أنظمتك في الوقت الفعلي عند وقوع أحداث في Twenty — دون الحاجة إلى الاستطلاع الدوري. استخدمها للحفاظ على تزامن الأنظمة الخارجية، وتشغيل الأتمتة، أو إرسال التنبيهات.
+
+## إنشاء خطاف ويب
+
+1. انتقل إلى **الإعدادات → APIs & Webhooks → Webhooks**
+2. انقر على **+ إنشاء خطاف ويب**
+3. أدخل عنوان URL لخطاف الويب الخاص بك (يجب أن يكون قابلاً للوصول علنًا)
+4. انقر على **حفظ**
+
+يتم تفعيل خطاف الويب فورًا ويبدأ في إرسال الإشعارات.
+
+<VimeoEmbed videoId="928786708" title="إنشاء خطاف ويب" />
+
+### إدارة خطافات الويب
+
+**تحرير**: انقر على خطاف الويب → تحديث عنوان URL → **حفظ**
+
+**حذف**: انقر على خطاف الويب → **حذف** → تأكيد
+
+## الأحداث
+
+يرسل Twenty خطافات الويب لأنواع الأحداث التالية:
+
+| حدث             | مثال                                                       |
+| --------------- | ---------------------------------------------------------- |
+| **إنشاء سجل**   | `person.created`, `company.created`, `note.created`        |
+| **تحديث السجل** | `person.updated`, `company.updated`, `opportunity.updated` |
+| **حذف السجل**   | `person.deleted`, `company.deleted`                        |
+
+يتم إرسال جميع أنواع الأحداث إلى عنوان URL لخطاف الويب الخاص بك. قد تتم إضافة تصفية الأحداث في الإصدارات المستقبلية.
+
+## تنسيق الحمولة
+
+يرسل كل خطاف ويب طلب HTTP من نوع POST يتضمن جسمًا بصيغة JSON:
+
+```json
+{
+  "event": "person.created",
+  "data": {
+    "id": "abc12345",
+    "firstName": "Alice",
+    "lastName": "Doe",
+    "email": "alice@example.com",
+    "createdAt": "2025-02-10T15:30:45Z",
+    "createdBy": "user_123"
+  },
+  "timestamp": "2025-02-10T15:30:50Z"
+}
+```
+
+| الحقل       | الوصف                                           |
+| ----------- | ----------------------------------------------- |
+| `event`     | ما الذي حدث (على سبيل المثال، `person.created`) |
+| `data`      | السجل الكامل الذي تم إنشاؤه/تحديثه/حذفه         |
+| `timestamp` | وقت حدوث الحدث (UTC)                            |
+
+<Note>
+استجب بحالة **HTTP 2xx** ‏(200-299) لتأكيد الاستلام. تُسجَّل الاستجابات غير 2xx كإخفاقات في التسليم.
+</Note>
+
+## التحقق من صحة خطاف الويب
+
+يقوم Twenty بتوقيع كل طلب خطاف ويب لأغراض الأمان. تحقّق من التواقيع للتأكد من أن الطلبات أصيلة.
+
+### الرؤوس
+
+| الترويسة                     | الوصف               |
+| ---------------------------- | ------------------- |
+| `X-Twenty-Webhook-Signature` | توقيع HMAC SHA256   |
+| `X-Twenty-Webhook-Timestamp` | الطابع الزمني للطلب |
+
+### خطوات التحقق
+
+1. احصل على الطابع الزمني من `X-Twenty-Webhook-Timestamp`
+2. أنشئ السلسلة: `{timestamp}:{JSON payload}`
+3. احسب HMAC SHA256 باستخدام سر خطاف الويب الخاص بك
+4. قارِن مع `X-Twenty-Webhook-Signature`
+
+### مثال (Node.js)
+
+```javascript
+const crypto = require("crypto");
+
+const timestamp = req.headers["x-twenty-webhook-timestamp"];
+const payload = JSON.stringify(req.body);
+const secret = "your-webhook-secret";
+
+const stringToSign = `${timestamp}:${payload}`;
+const expectedSignature = crypto
+  .createHmac("sha256", secret)
+  .update(stringToSign)
+  .digest("hex");
+
+const receivedSignature = req.headers["x-twenty-webhook-signature"];
+const isValid = crypto.timingSafeEqual(
+  Buffer.from(expectedSignature, "hex"),
+  Buffer.from(receivedSignature, "hex")
+);
+```
+
+## خطافات الويب مقابل سير العمل
+
+| طريقة                         | الاتجاه | حالة الاستخدام                                              |
+| ----------------------------- | ------- | ----------------------------------------------------------- |
+| **خطافات الويب**              | OUT     | إخطار الأنظمة الخارجية تلقائيًا بأي تغيير في السجل          |
+| **سير العمل + طلب HTTP**      | OUT     | إرسال البيانات إلى الخارج بمنطق مخصص (عوامل تصفية، تحويلات) |
+| **مشغّل خطاف ويب لسير العمل** | IN      | استقبال البيانات في Twenty من الأنظمة الخارجية              |
+
+لاستقبال البيانات الخارجية، راجع [إعداد مشغّل خطاف الويب](/l/ar/user-guide/workflows/how-tos/connect-to-other-tools/set-up-a-webhook-trigger).

packages/twenty-docs/l/ar/navigation.json

@@ -149,8 +149,8 @@
         "extend": {
           "label": "التوسيع",
           "groups": {
-            "extendCapabilities": {
-              "label": "القدرات"
+            "apps": {
+              "label": "التطبيقات"
             }
           }
         },

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

@@ -24,7 +24,7 @@ import { VimeoEmbed } from '/snippets/vimeo-embed.mdx';
 * يتم تصدير **الأعمدة المرئية** فقط
 * يتم تصدير **السجلات المصفّاة** فقط (استنادًا إلى العرض الحالي لديك)
 
-<Note>بالنسبة لعمليات التصدير الأكبر (أكثر من 20,000 سجل)، استخدم عوامل التصفية للتصدير على دفعات أو استخدم [واجهة برمجة التطبيقات (API)](/l/ar/developers/extend/capabilities/apis).</Note>
+<Note>بالنسبة لعمليات التصدير الأكبر (أكثر من 20,000 سجل)، استخدم عوامل التصفية للتصدير على دفعات أو استخدم [واجهة برمجة التطبيقات (API)](/l/ar/developers/extend/api).</Note>
 
 ### الصلاحيات
 
@@ -148,7 +148,7 @@ import { VimeoEmbed } from '/snippets/vimeo-embed.mdx';
 2. استخدم واجهة برمجة تطبيقات GraphQL للاستعلام عن السجلات
 3. عالج النتائج في تطبيقك
 
-راجع: [وثائق واجهة برمجة التطبيقات (API)](/l/ar/developers/extend/capabilities/apis)
+راجع: [وثائق واجهة برمجة التطبيقات (API)](/l/ar/developers/extend/api)
 
 ## نصائح وأفضل الممارسات
 
@@ -206,4 +206,4 @@ import { VimeoEmbed } from '/snippets/vimeo-embed.mdx';
 
 * [كيفية تحديث السجلات الموجودة](/l/ar/user-guide/data-migration/how-tos/update-existing-records-via-import) — حرّر وأعد استيراد ملف التصدير الخاص بك
 * [كيفية استيراد البيانات عبر واجهة برمجة التطبيقات (API)](/l/ar/user-guide/data-migration/how-tos/import-data-via-api) — لمجموعات البيانات الكبيرة
-* [وثائق واجهة برمجة التطبيقات (API)](/l/ar/developers/extend/capabilities/apis) — أنشئ عمليات سير عمل تصدير مخصصة
+* [وثائق واجهة برمجة التطبيقات (API)](/l/ar/developers/extend/api) — أنشئ عمليات سير عمل تصدير مخصصة

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

@@ -57,10 +57,10 @@ description: متى وكيف تستخدم واجهات API الخاصة بـ Twe
 
 تدعم Twenty نوعين من واجهات API:
 
-| واجهة برمجة التطبيقات | الأفضل لـ                                              | التوثيق                                           |
-| --------------------- | ------------------------------------------------------ | ------------------------------------------------- |
-| **GraphQL**           | استعلامات مرنة، وجلب البيانات المرتبطة، وعمليات معقّدة | [وثائق API](/l/ar/developers/extend/capabilities/apis) |
-| **REST**              | عمليات CRUD بسيطة، وأنماط REST مألوفة                  | [وثائق API](/l/ar/developers/extend/capabilities/apis) |
+| واجهة برمجة التطبيقات | الأفضل لـ                                              | التوثيق                             |
+| --------------------- | ------------------------------------------------------ | ----------------------------------- |
+| **GraphQL**           | استعلامات مرنة، وجلب البيانات المرتبطة، وعمليات معقّدة | [وثائق API](/l/ar/developers/extend/api) |
+| **REST**              | عمليات CRUD بسيطة، وأنماط REST مألوفة                  | [وثائق API](/l/ar/developers/extend/api) |
 
 كلتا واجهتي API تدعمان:
 
@@ -173,4 +173,4 @@ description: متى وكيف تستخدم واجهات API الخاصة بـ Twe
 
 للحصول على تفاصيل التنفيذ الكاملة وأمثلة الشيفرة ومرجع المخطط (schema):
 
-* [وثائق API](/l/ar/developers/extend/capabilities/apis)
+* [وثائق API](/l/ar/developers/extend/api)

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

@@ -35,7 +35,7 @@ description: Twenty هو نظام إدارة علاقات العملاء (CRM)
 * **لوحات التحكم:** تتبع الأداء باستخدام تقارير مخصصة وتصوّرات مرئية. [عرض لوحات التحكم](/l/ar/user-guide/dashboards/overview).
 * **الأذونات والوصول:** تحكّم في مَن يمكنه عرض بياناتك وتحريرها وإدارتها باستخدام أذونات مستندة إلى الأدوار. [تكوين الوصول](/l/ar/user-guide/permissions-access/overview).
 * **الملاحظات والمهام:** أنشئ ملاحظات ومهام مرتبطة بسجلاتك لتحسين التعاون.
-* **واجهة برمجة التطبيقات والويب هوكس:** الاتصال بالتطبيقات الأخرى وإنشاء عمليات تكامل مخصصة. [ابدأ التكامل](/l/ar/developers/extend/capabilities/apis).
+* **واجهة برمجة التطبيقات والويب هوكس:** الاتصال بالتطبيقات الأخرى وإنشاء عمليات تكامل مخصصة. [ابدأ التكامل](/l/ar/developers/extend/api).
 
 ## انضم الآن
 

packages/twenty-docs/l/ar/user-guide/workflows/how-tos/crm-automations/display-related-record-data.mdx

@@ -95,7 +95,7 @@ description: اعرض بيانات من سجلات مرتبطة (مثل معلو
    * حجم الشركة: `{{searchRecords[0].employees}}`
 
 <Note>
-**قيود المهام والملاحظات**: العلاقات في المهام والملاحظات مُحدّدة في الشفرة كعلاقات متعدّدة-لمتعدّدة وليست متاحة بعد في محفّزات أو إجراءات سير العمل. للوصول إلى هذه العلاقات، استخدم بدلًا من ذلك [API](/l/ar/developers/extend/capabilities/apis).
+**قيود المهام والملاحظات**: العلاقات في المهام والملاحظات مُحدّدة في الشفرة كعلاقات متعدّدة-لمتعدّدة وليست متاحة بعد في محفّزات أو إجراءات سير العمل. للوصول إلى هذه العلاقات، استخدم بدلًا من ذلك [API](/l/ar/developers/extend/api).
 </Note>
 
 ## مزامنة ثنائية الاتجاه

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

@@ -77,7 +77,7 @@ To avoid unnecessary [re-renders](/l/cs/developers/contribute/capabilities/front
 
 ### Správa stavu
 
-[Jotai](https://jotai.org/) zajišťuje správu stavu.
+[Jotai](https://jotai.org/) handles state management.
 
 Podívejte se na [osvědčené postupy](/l/cs/developers/contribute/capabilities/frontend-development/best-practices-front#state-management) pro více informací o správě stavu.
 

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

@@ -171,7 +171,7 @@ export default defineObject({
 
 Pozdější příkazy přidají další soubory a složky:
 
-* `yarn twenty app:dev` automaticky vygeneruje dva typované API klienty v `node_modules/twenty-sdk/generated`: `CoreApiClient` (pro data pracovního prostoru přes `/graphql`) a `MetadataApiClient` (pro konfiguraci pracovního prostoru a nahrávání souborů přes `/metadata`).
+* `yarn twenty app:dev` will auto-generate two typed API clients in `node_modules/twenty-sdk/clients`: `CoreApiClient` (for workspace data via `/graphql`) and `MetadataApiClient` (for workspace configuration and file uploads via `/metadata`).
 * `yarn twenty entity:add` přidá soubory s definicemi entit do `src/` pro vaše vlastní objekty, funkce, frontové komponenty, role, dovednosti a další.
 
 ## Ověření
@@ -228,7 +228,7 @@ SDK poskytuje pomocné funkce pro definování entit vaší aplikace. Jak je pop
 | `defineView()`                     | Definujte uložená zobrazení pro objekty                           |
 | `defineNavigationMenuItem()`       | Definujte odkazy postranní navigace                               |
 | `defineSkill()`                    | Definuje dovednosti agenta AI                                     |
-| `defineAgent()`                    | Define AI agents with system prompts                              |
+| `defineAgent()`                    | Definujte AI agenty pomocí systémových promptů                    |
 
 Tyto funkce validují vaši konfiguraci v době sestavení a poskytují automatické doplňování v IDE a typovou bezpečnost.
 
@@ -434,7 +434,7 @@ Každý soubor funkce používá `defineLogicFunction()` k exportu konfigurace s
 // src/app/createPostCard.logic-function.ts
 import { defineLogicFunction } from 'twenty-sdk';
 import type { DatabaseEventPayload, ObjectRecordCreateEvent, CronPayload, RoutePayload } from 'twenty-sdk';
-import { CoreApiClient, type Person } from 'twenty-sdk/generated';
+import { CoreApiClient, type Person } from 'twenty-sdk/clients';
 
 const handler = async (params: RoutePayload) => {
   const client = new CoreApiClient();
@@ -679,7 +679,7 @@ Chcete-li označit logickou funkci jako nástroj, nastavte `isTool: true` a posk
 ```typescript
 // src/logic-functions/enrich-company.logic-function.ts
 import { defineLogicFunction } from 'twenty-sdk';
-import { CoreApiClient } from 'twenty-sdk/generated';
+import { CoreApiClient } from 'twenty-sdk/clients';
 
 const handler = async (params: { companyName: string; domain?: string }) => {
   const client = new CoreApiClient();
@@ -808,7 +808,7 @@ Nové dovednosti můžete vytvářet dvěma způsoby:
 
 ### Agenti
 
-Agents define AI agents with system prompts that can operate within your workspace. Use `defineAgent()` to define agents with built-in validation:
+Agenti jsou AI agenti se systémovými prompty, kteří mohou fungovat ve vašem pracovním prostoru. K definování agentů s vestavěnou validací použijte `defineAgent()`:
 
 ```typescript
 // src/agents/example-agent.ts
@@ -830,26 +830,27 @@ export default defineAgent({
 
 Hlavní body:
 
-* `name` is a unique identifier string for the agent (kebab-case recommended).
+* `name` je jedinečný identifikátor agenta (doporučuje se kebab-case).
 * `label` je uživatelsky čitelný název zobrazovaný v UI.
-* `prompt` contains the system prompt — this is the instruction text that defines the agent's behavior.
+* `prompt` obsahuje systémový prompt — jde o instrukční text, který určuje chování agenta.
 * `icon` (volitelné) nastavuje ikonu zobrazovanou v UI.
-* `description` (optional) provides additional context about the agent's purpose.
+* `description` (volitelné) poskytuje doplňující kontext o účelu agenta.
 
-You can create new agents in two ways:
+Nové agenty můžete vytvářet dvěma způsoby:
 
-* **Scaffolded**: Run `yarn twenty entity:add` and choose the option to add a new agent.
-* **Manual**: Create a new file and use `defineAgent()`, following the same pattern.
+* **Vygenerované**: Spusťte `yarn twenty entity:add` a zvolte možnost přidat nového agenta.
+* **Ruční**: Vytvořte nový soubor a použijte `defineAgent()` podle stejného vzoru.
 
 ### Generované typované klienty
 
-Dva typované klienty jsou automaticky generovány pomocí `yarn twenty app:dev` a ukládají se do `node_modules/twenty-sdk/generated` podle schématu vašeho pracovního prostoru:
+Two typed clients are auto-generated by `yarn twenty app:dev` and stored in `node_modules/twenty-sdk/clients` based on your workspace schema:
 
 * **`CoreApiClient`** — provádí dotazy na endpoint `/graphql` za účelem získání dat pracovního prostoru
 * **`MetadataApiClient`** — odesílá dotazy na endpoint `/metadata` pro konfiguraci pracovního prostoru a nahrávání souborů
 
 ```typescript
-import { CoreApiClient, MetadataApiClient } from 'twenty-sdk/generated';
+import { CoreApiClient } from 'twenty-sdk/clients';
+import { MetadataApiClient } from 'twenty-sdk/clients';
 
 const client = new CoreApiClient();
 const { me } = await client.query({ me: { id: true, displayName: true } });
@@ -858,7 +859,7 @@ const metadataClient = new MetadataApiClient();
 const { currentWorkspace } = await metadataClient.query({ currentWorkspace: { id: true } });
 ```
 
-Oba klienti se automaticky znovu generují pomocí `yarn twenty app:dev` kdykoli se změní vaše objekty nebo pole.
+`CoreApiClient` is re-generated automatically by `yarn twenty app:dev` whenever your objects or fields change. `MetadataApiClient` ships pre-built with the SDK.
 
 #### Běhové přihlašovací údaje v logických funkcích
 
@@ -875,10 +876,10 @@ Poznámky:
 
 #### Nahrávání souborů
 
-Vygenerovaný `MetadataApiClient` 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).
+The `MetadataApiClient` includes an `uploadFile` method for attaching files to file-type fields on your workspace objects. 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 { MetadataApiClient } from 'twenty-sdk/generated';
+import { MetadataApiClient } from 'twenty-sdk/clients';
 import * as fs from 'fs';
 
 const metadataClient = new MetadataApiClient();

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

@@ -1,6 +1,7 @@
 ---
 title: Rozšiřte
 description: Rozšiřte funkčnost Twenty pomocí rozhraní API, webhooků a vlastních aplikací.
+redirect: /developers/introduction
 ---
 
 <Frame>
@@ -20,13 +21,13 @@ Twenty je navrženo tak, aby bylo rozšiřitelné. Použijte naše rozhraní API
 ## Začínáme
 
 <CardGroup cols={2}>
-  <Card title="API" icon="kód" href="/l/cs/developers/extend/capabilities/apis">
+  <Card title="API" icon="kód" href="/l/cs/developers/api">
     Programově se připojte k Twenty
   </Card>
-  <Card title="Webhooky" icon="bell" href="/l/cs/developers/extend/capabilities/webhooks">
+  <Card title="Webhooky" icon="bell" href="/l/cs/developers/webhooks">
     Dostávejte oznámení o událostech v reálném čase
   </Card>
-  <Card title="Aplikace" icon="puzzle-piece" href="/l/cs/developers/extend/capabilities/apps">
+  <Card title="Aplikace" icon="puzzle-piece" href="/l/cs/developers/apps/apps">
     Vytvářejte přizpůsobení jako kód (Alpha)
   </Card>
 </CardGroup>

packages/twenty-docs/l/cs/developers/introduction.mdx

@@ -5,18 +5,28 @@ description: Vítejte v dokumentaci pro vývojáře Twenty, která je vaším zd
 
 import { CardTitle } from "/snippets/card-title.mdx"
 
-<CardGroup cols={3}>
-  <Card href="/l/cs/developers/extend/extend" img="/images/user-guide/integrations/plug.png">
-    <CardTitle>Rozšiřte</CardTitle>
-    Vytvářejte integrace pomocí API, webhooků a vlastních aplikací.
+<CardGroup cols={2}>
+  <Card href="/l/cs/developers/api" icon="code">
+    <CardTitle>API</CardTitle>
+    Dotazujte a upravujte data CRM pomocí REST nebo GraphQL.
   </Card>
 
-  <Card href="/l/cs/developers/self-host/self-host" img="/images/user-guide/what-is-twenty/20.png">
+  <Card href="/l/cs/developers/webhooks" icon="bell">
+    <CardTitle>Webhooks</CardTitle>
+    Přijímejte oznámení v reálném čase při výskytu událostí.
+  </Card>
+
+  <Card href="/l/cs/developers/apps/apps" icon="puzzle-piece">
+    <CardTitle>Apps</CardTitle>
+    Vytvářejte vlastní aplikace rozšiřující možnosti Twenty.
+  </Card>
+
+  <Card href="/l/cs/developers/self-host/self-host" icon="desktop">
     <CardTitle>Hostujte sami</CardTitle>
     Nasaďte a spravujte Twenty na vlastní infrastruktuře.
   </Card>
 
-  <Card href="/l/cs/developers/contribute/contribute" img="/images/user-guide/github/github-header.png">
+  <Card href="/l/cs/developers/contribute/contribute" icon="github">
     <CardTitle>Přispějte</CardTitle>
     Připojte se k naší open-source komunitě a přispívejte do Twenty.
   </Card>