fix: pass instanceId or guard against missing context in CreateNewIndexRecordNoSelectionRecordCommand

https://sonarly.com/issue/6956?type=bug `CreateNewIndexRecordNoSelectionRecordCommand` renders on dashboard show pages without a `ViewComponentInstanceContext` provider, causing `useCreateNewIndexRecord` to throw because neither `instanceId` prop nor context value is available for the `recordGroupDefinitionsComponentSelector`.
2026-03-25 22:27:42 +00:00
1171 changed files with 28101 additions and 52787 deletions
@@ -36,9 +36,6 @@ jobs:
    services:
      postgres:
        image: twentycrm/twenty-postgres-spilo
-        credentials:
-          username: ${{ vars.DOCKERHUB_USERNAME }}
-          password: ${{ secrets.DOCKERHUB_PASSWORD }}
        env:
          PGUSER_SUPERUSER: postgres
          PGPASSWORD_SUPERUSER: postgres
@@ -53,16 +50,10 @@ jobs:
          --health-retries 5
      redis:
        image: redis
-        credentials:
-          username: ${{ vars.DOCKERHUB_USERNAME }}
-          password: ${{ secrets.DOCKERHUB_PASSWORD }}
        ports:
          - 6379:6379
      clickhouse:
        image: clickhouse/clickhouse-server:25.8.8
-        credentials:
-          username: ${{ vars.DOCKERHUB_USERNAME }}
-          password: ${{ secrets.DOCKERHUB_PASSWORD }}
        env:
          CLICKHOUSE_PASSWORD: clickhousePassword
          CLICKHOUSE_URL: "http://default:clickhousePassword@localhost:8123/twenty"
@@ -152,6 +143,7 @@ jobs:
          set_env_var "CLICKHOUSE_PASSWORD" "clickhousePassword"

          npx nx run twenty-server:database:init:prod
+          npx nx run twenty-server:database:migrate:prod

      - name: Seed current branch database with test data
        run: |
@@ -304,6 +296,7 @@ jobs:
          set_env_var "CLICKHOUSE_PASSWORD" "clickhousePassword"

          npx nx run twenty-server:database:init:prod
+          npx nx run twenty-server:database:migrate:prod

      - name: Seed main branch database with test data
        run: |
@@ -402,12 +395,6 @@ jobs:
          # Clean up temp directory
          rm -rf /tmp/current-branch-files

-      - name: Login to Docker Hub
-        uses: docker/login-action@v3
-        with:
-          username: ${{ vars.DOCKERHUB_USERNAME }}
-          password: ${{ secrets.DOCKERHUB_PASSWORD }}
-
      - name: Install OpenAPI Diff Tool
        run: |
          # Using the Java-based OpenAPITools/openapi-diff via Docker
@@ -37,9 +37,6 @@ jobs:
    services:
      postgres:
        image: twentycrm/twenty-postgres-spilo
-        credentials:
-          username: ${{ vars.DOCKERHUB_USERNAME }}
-          password: ${{ secrets.DOCKERHUB_PASSWORD }}
        env:
          PGUSER_SUPERUSER: postgres
          PGPASSWORD_SUPERUSER: postgres
@@ -54,13 +51,8 @@ jobs:
          --health-retries 5
      redis:
        image: redis
-        credentials:
-          username: ${{ vars.DOCKERHUB_USERNAME }}
-          password: ${{ secrets.DOCKERHUB_PASSWORD }}
        ports:
          - 6379:6379
-    env:
-      PUBLISHABLE_PACKAGES: twenty-client-sdk twenty-sdk create-twenty-app
    steps:
      - name: Fetch custom Github Actions and base branch history
        uses: actions/checkout@v4
@@ -74,13 +66,13 @@ jobs:
        run: |
          CI_VERSION="0.0.0-ci.$(date +%s)"
          echo "CI_VERSION=$CI_VERSION" >> $GITHUB_ENV
-          npx nx run-many -t set-local-version -p $PUBLISHABLE_PACKAGES --releaseVersion=$CI_VERSION
+          npx nx run-many -t set-local-version -p twenty-sdk twenty-client-sdk create-twenty-app --releaseVersion=$CI_VERSION

      - name: Build packages
        run: |
-          for pkg in $PUBLISHABLE_PACKAGES; do
-            npx nx build $pkg
-          done
+          npx nx build twenty-sdk
+          npx nx build twenty-client-sdk
+          npx nx build create-twenty-app

      - name: Install and start Verdaccio
        run: |
@@ -97,13 +89,11 @@ jobs:

      - name: Publish packages to local registry
        run: |
-          yarn config set npmRegistryServer http://localhost:4873
-          yarn config set unsafeHttpWhitelist --json '["localhost"]'
-          yarn config set npmAuthToken ci-auth-token
+          npm set //localhost:4873/:_authToken "ci-auth-token"

-          for pkg in $PUBLISHABLE_PACKAGES; do
+          for pkg in twenty-sdk twenty-client-sdk create-twenty-app; do
            cd packages/$pkg
-            yarn npm publish --tag ci
+            npm publish --registry http://localhost:4873 --tag ci
            cd ../..
          done

@@ -26,9 +26,6 @@ jobs:
    services:
      postgres:
        image: twentycrm/twenty-postgres-spilo
-        credentials:
-          username: ${{ vars.DOCKERHUB_USERNAME }}
-          password: ${{ secrets.DOCKERHUB_PASSWORD }}
        env:
          PGUSER_SUPERUSER: postgres
          PGPASSWORD_SUPERUSER: postgres
@@ -43,9 +40,6 @@ jobs:
          --health-retries 5
      redis:
        image: redis
-        credentials:
-          username: ${{ vars.DOCKERHUB_USERNAME }}
-          password: ${{ secrets.DOCKERHUB_PASSWORD }}
        ports:
          - 6379:6379
    steps:
@@ -57,9 +57,6 @@ jobs:
    services:
      postgres:
        image: twentycrm/twenty-postgres-spilo
-        credentials:
-          username: ${{ vars.DOCKERHUB_USERNAME }}
-          password: ${{ secrets.DOCKERHUB_PASSWORD }}
        env:
          PGUSER_SUPERUSER: postgres
          PGPASSWORD_SUPERUSER: postgres
@@ -74,9 +71,6 @@ jobs:
          --health-retries 5
      redis:
        image: redis
-        credentials:
-          username: ${{ vars.DOCKERHUB_USERNAME }}
-          password: ${{ secrets.DOCKERHUB_PASSWORD }}
        ports:
          - 6379:6379
    env:
@@ -84,9 +84,6 @@ jobs:
    services:
      postgres:
        image: twentycrm/twenty-postgres-spilo
-        credentials:
-          username: ${{ vars.DOCKERHUB_USERNAME }}
-          password: ${{ secrets.DOCKERHUB_PASSWORD }}
        env:
          PGUSER_SUPERUSER: postgres
          PGPASSWORD_SUPERUSER: postgres
@@ -101,9 +98,6 @@ jobs:
          --health-retries 5
      redis:
        image: redis
-        credentials:
-          username: ${{ vars.DOCKERHUB_USERNAME }}
-          password: ${{ secrets.DOCKERHUB_PASSWORD }}
        ports:
          - 6379:6379
    steps:
@@ -128,6 +122,7 @@ jobs:
          PGPASSWORD=postgres psql -h localhost -p 5432 -U postgres -d postgres -c 'CREATE DATABASE "default";'
          PGPASSWORD=postgres psql -h localhost -p 5432 -U postgres -d postgres -c 'CREATE DATABASE "test";'
          npx nx run twenty-server:database:init:prod
+          npx nx run twenty-server:database:migrate:prod
      - name: Worker / Run
        run: |
          timeout 30s npx nx run twenty-server:worker || exit_code=$?
@@ -232,9 +227,6 @@ jobs:
    services:
      postgres:
        image: twentycrm/twenty-postgres-spilo
-        credentials:
-          username: ${{ vars.DOCKERHUB_USERNAME }}
-          password: ${{ secrets.DOCKERHUB_PASSWORD }}
        env:
          PGUSER_SUPERUSER: postgres
          PGPASSWORD_SUPERUSER: postgres
@@ -249,16 +241,10 @@ jobs:
          --health-retries 5
      redis:
        image: redis
-        credentials:
-          username: ${{ vars.DOCKERHUB_USERNAME }}
-          password: ${{ secrets.DOCKERHUB_PASSWORD }}
        ports:
          - 6379:6379
      clickhouse:
        image: clickhouse/clickhouse-server:25.8.8
-        credentials:
-          username: ${{ vars.DOCKERHUB_USERNAME }}
-          password: ${{ secrets.DOCKERHUB_PASSWORD }}
        env:
          CLICKHOUSE_PASSWORD: clickhousePassword
          CLICKHOUSE_URL: "http://default:clickhousePassword@localhost:8123/twenty"
@@ -27,11 +27,6 @@ jobs:
    steps:
      - name: Checkout
        uses: actions/checkout@v4
-      - name: Login to Docker Hub
-        uses: docker/login-action@v3
-        with:
-          username: ${{ vars.DOCKERHUB_USERNAME }}
-          password: ${{ secrets.DOCKERHUB_PASSWORD }}
      - name: Run compose
        run: |
          echo "Patching docker-compose.yml..."
@@ -102,11 +97,6 @@ jobs:
    steps:
      - name: Checkout
        uses: actions/checkout@v4
-      - name: Login to Docker Hub
-        uses: docker/login-action@v3
-        with:
-          username: ${{ vars.DOCKERHUB_USERNAME }}
-          password: ${{ secrets.DOCKERHUB_PASSWORD }}
      - name: Create frontend placeholder
        run: |
          mkdir -p packages/twenty-front/build
@@ -27,9 +27,6 @@ jobs:
    services:
      postgres:
        image: twentycrm/twenty-postgres-spilo
-        credentials:
-          username: ${{ vars.DOCKERHUB_USERNAME }}
-          password: ${{ secrets.DOCKERHUB_PASSWORD }}
        env:
          PGUSER_SUPERUSER: postgres
          PGPASSWORD_SUPERUSER: postgres
@@ -30,9 +30,6 @@ jobs:
    services:
      postgres:
        image: twentycrm/twenty-postgres-spilo
-        credentials:
-          username: ${{ vars.DOCKERHUB_USERNAME }}
-          password: ${{ secrets.DOCKERHUB_PASSWORD }}
        env:
          PGUSER_SUPERUSER: postgres
          PGPASSWORD_SUPERUSER: postgres
@@ -47,9 +44,6 @@ jobs:
          --health-retries 5
      redis:
        image: redis
-        credentials:
-          username: ${{ vars.DOCKERHUB_USERNAME }}
-          password: ${{ secrets.DOCKERHUB_PASSWORD }}
        ports:
          - 6379:6379
    steps:
@@ -17,12 +17,6 @@ jobs:
        with:
          ref: ${{ github.event.client_payload.pr_head_sha }}

-      - name: Login to Docker Hub
-        uses: docker/login-action@v3
-        with:
-          username: ${{ vars.DOCKERHUB_USERNAME }}
-          password: ${{ secrets.DOCKERHUB_PASSWORD }}
-
      - name: Run compose setup
        run: |
          echo "Patching docker-compose.yml..."
@@ -6,4 +6,4 @@ enableInlineHunks: true

 nodeLinker: node-modules

-yarnPath: .yarn/releases/yarn-4.13.0.cjs
+yarnPath: .yarn/releases/yarn-4.9.2.cjs
@@ -175,7 +175,7 @@
  },
  "license": "AGPL-3.0",
  "name": "twenty",
-  "packageManager": "yarn@4.13.0",
+  "packageManager": "yarn@4.9.2",
  "resolutions": {
    "graphql": "16.8.1",
    "type-fest": "4.10.1",
@@ -203,7 +203,6 @@
      "packages/twenty-utils",
      "packages/twenty-zapier",
      "packages/twenty-website",
-      "packages/twenty-website-new",
      "packages/twenty-docs",
      "packages/twenty-e2e-testing",
      "packages/twenty-shared",
@@ -41,7 +41,7 @@ cd my-twenty-app

 # Or do it manually:
 yarn twenty server start          # Start local Twenty server
-yarn twenty remote add http://localhost:2020 --as local  # Authenticate via OAuth
+yarn twenty remote add --local    # Authenticate via OAuth

 # Start dev mode: watches, builds, and syncs local changes to your workspace
 # (also auto-generates typed CoreApiClient — MetadataApiClient ships pre-built — both available via `twenty-client-sdk`)
@@ -122,10 +122,18 @@ yarn twenty server reset     # Wipe all data and start fresh

 The server is pre-seeded with a workspace and user (`tim@apple.dev` / `tim@apple.dev`).

+### How to use a local Twenty instance
+
+If you're already running a local Twenty instance, you can connect to it instead of using Docker. Pass the port your local server is listening on (default: `3000`):
+
+```bash
+npx create-twenty-app@latest my-app --port 3000
+```
+
 ## Next steps

 - Run `yarn twenty help` to see all available commands.
- Use `yarn twenty remote add <url>` to authenticate with your Twenty workspace via OAuth.
+- Use `yarn twenty remote add --local` to authenticate with your Twenty workspace via OAuth.
 - Explore the generated project and add your first entity with `yarn twenty add` (logic functions, front components, objects, roles, views, navigation menu items, skills).
 - Use `yarn twenty dev` while you iterate — it watches, builds, and syncs changes to your workspace in real time.
 - `CoreApiClient` is auto-generated by `yarn twenty dev`. `MetadataApiClient` (for workspace configuration and file uploads via `/metadata`) ships pre-built with the SDK. Both are available via `import { CoreApiClient } from 'twenty-client-sdk/core'` and `import { MetadataApiClient } from 'twenty-client-sdk/metadata'`.
@@ -169,7 +177,7 @@ Our team reviews contributions for quality, security, and reusability before mer
 ## Troubleshooting

 - Server not starting: check Docker is running (`docker info`), then try `yarn twenty server logs`.
- Auth not working: make sure you're logged in to Twenty in the browser first, then run `yarn twenty remote add <url>`.
+- Auth not working: make sure you're logged in to Twenty in the browser first, then run `yarn twenty remote add --local`.
 - Types not generated: ensure `yarn twenty dev` is running — it auto-generates the typed client.

 ## Contributing
@@ -1,6 +1,6 @@
 {
  "name": "create-twenty-app",
-  "version": "0.8.0-canary.6",
+  "version": "0.8.0-canary.2",
  "description": "Command-line interface to create Twenty application",
  "main": "dist/cli.cjs",
  "bin": "dist/cli.cjs",
@@ -36,7 +36,6 @@
    "lodash.camelcase": "^4.3.0",
    "lodash.kebabcase": "^4.1.1",
    "lodash.startcase": "^4.4.0",
-    "twenty-sdk": "workspace:*",
    "uuid": "^13.0.0"
  },
  "devDependencies": {
@@ -46,6 +45,7 @@
    "@types/lodash.kebabcase": "^4.1.7",
    "@types/lodash.startcase": "^4",
    "@types/node": "^20.0.0",
+    "twenty-sdk": "workspace:*",
    "twenty-shared": "workspace:*",
    "typescript": "^5.9.2",
    "vite": "^7.0.0",
@@ -31,6 +31,10 @@ const program = new Command(packageJson.name)
    '--skip-local-instance',
    'Skip the local Twenty instance setup prompt',
  )
+  .option(
+    '-p, --port <port>',
+    'Port of an existing Twenty server (skips Docker setup)',
+  )
  .helpOption('-h, --help', 'Display this help message.')
  .action(
    async (
@@ -42,6 +46,7 @@ const program = new Command(packageJson.name)
        displayName?: string;
        description?: string;
        skipLocalInstance?: boolean;
+        port?: string;
      },
    ) => {
      const modeFlags = [options?.exhaustive, options?.minimal].filter(Boolean);
@@ -71,6 +76,8 @@ const program = new Command(packageJson.name)

      const mode: ScaffoldingMode = options?.minimal ? 'minimal' : 'exhaustive';

+      const port = options?.port ? parseInt(options.port, 10) : undefined;
+
      await new CreateAppCommand().execute({
        directory,
        mode,
@@ -78,6 +85,7 @@ const program = new Command(packageJson.name)
        displayName: options?.displayName,
        description: options?.description,
        skipLocalInstance: options?.skipLocalInstance,
+        port,
      });
    },
  );
@@ -1,18 +1,18 @@
+import { basename } from 'path';
 import { copyBaseApplicationProject } from '@/utils/app-template';
 import { convertToLabel } from '@/utils/convert-to-label';
 import { install } from '@/utils/install';
+import {
+  type LocalInstanceResult,
+  setupLocalInstance,
+} from '@/utils/setup-local-instance';
 import { tryGitInit } from '@/utils/try-git-init';
 import chalk from 'chalk';
 import * as fs from 'fs-extra';
 import inquirer from 'inquirer';
 import kebabCase from 'lodash.kebabcase';
+import { execSync } from 'node:child_process';
 import * as path from 'path';
-import { basename } from 'path';
-import {
-  authLoginOAuth,
-  serverStart,
-  type ServerStartResult,
-} from 'twenty-sdk/cli';
 import { isDefined } from 'twenty-shared/utils';

 import {
@@ -29,6 +29,7 @@ type CreateAppOptions = {
  displayName?: string;
  description?: string;
  skipLocalInstance?: boolean;
+  port?: number;
 };

 export class CreateAppCommand {
@@ -59,22 +60,17 @@ export class CreateAppCommand {

      await tryGitInit(appDirectory);

-      let serverResult: ServerStartResult | undefined;
+      let localResult: LocalInstanceResult = { running: false };

      if (!options.skipLocalInstance) {
-        const startResult = await serverStart({
-          onProgress: (message: string) => console.log(chalk.gray(message)),
-        });
+        localResult = await setupLocalInstance(appDirectory, options.port);

-        if (startResult.success) {
-          serverResult = startResult.data;
-          await this.connectToLocal(serverResult.url);
-        } else {
-          console.log(chalk.yellow(`\n${startResult.error.message}`));
+        if (localResult.running && localResult.serverUrl) {
+          await this.connectToLocal(appDirectory, localResult.serverUrl);
        }
      }

-      this.logSuccess(appDirectory, serverResult);
+      this.logSuccess(appDirectory, localResult);
    } catch (error) {
      console.error(
        chalk.red('\nCreate application failed:'),
@@ -201,24 +197,19 @@ export class CreateAppCommand {
    );
  }

-  private async connectToLocal(serverUrl: string): Promise<void> {
+  private async connectToLocal(
+    appDirectory: string,
+    serverUrl: string,
+  ): Promise<void> {
    try {
-      const result = await authLoginOAuth({
-        apiUrl: serverUrl,
-        remote: 'local',
+      execSync(`yarn twenty remote add ${serverUrl} --as local`, {
+        cwd: appDirectory,
+        stdio: 'inherit',
      });
-
-      if (!result.success) {
-        console.log(
-          chalk.yellow(
-            'Authentication skipped. Run `yarn twenty remote add` manually.',
-          ),
-        );
-      }
    } catch {
      console.log(
        chalk.yellow(
-          'Authentication skipped. Run `yarn twenty remote add` manually.',
+          'Authentication skipped. Run `yarn twenty remote add --local` manually.',
        ),
      );
    }
@@ -226,17 +217,17 @@ export class CreateAppCommand {

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

    console.log(chalk.blue('\nApplication created. Next steps:'));
    console.log(chalk.gray(`- cd ${dirName}`));

-    if (!serverResult) {
+    if (!localResult.running) {
      console.log(
        chalk.gray(
-          '- yarn twenty remote add          # Authenticate with Twenty',
+          '- yarn twenty remote add --local  # Authenticate with Twenty',
        ),
      );
    }
@@ -794,7 +794,6 @@ const createPackageJson = async ({
      npm: 'please-use-yarn',
      yarn: '>=4.0.2',
    },
-    keywords: ['twenty-app'],
    packageManager: 'yarn@4.9.2',
    scripts,
    devDependencies,
@@ -0,0 +1,106 @@
+import chalk from 'chalk';
+import { execSync } from 'node:child_process';
+
+const LOCAL_PORTS = [2020, 3000];
+
+// Minimal health check — the full implementation lives in twenty-sdk
+const isServerReady = async (port: number): Promise<boolean> => {
+  const controller = new AbortController();
+  const timeoutId = setTimeout(() => controller.abort(), 3000);
+
+  try {
+    const response = await fetch(`http://localhost:${port}/healthz`, {
+      signal: controller.signal,
+    });
+
+    const body = await response.json();
+
+    return body.status === 'ok';
+  } catch {
+    return false;
+  } finally {
+    clearTimeout(timeoutId);
+  }
+};
+
+const detectRunningServer = async (
+  preferredPort?: number,
+): Promise<number | null> => {
+  const ports = preferredPort ? [preferredPort] : LOCAL_PORTS;
+
+  for (const port of ports) {
+    if (await isServerReady(port)) {
+      return port;
+    }
+  }
+
+  return null;
+};
+
+export type LocalInstanceResult = {
+  running: boolean;
+  serverUrl?: string;
+};
+
+export const setupLocalInstance = async (
+  appDirectory: string,
+  preferredPort?: number,
+): Promise<LocalInstanceResult> => {
+  const detectedPort = await detectRunningServer(preferredPort);
+
+  if (detectedPort) {
+    const serverUrl = `http://localhost:${detectedPort}`;
+
+    console.log(chalk.green(`Twenty server detected on ${serverUrl}.\n`));
+
+    return { running: true, serverUrl };
+  }
+
+  if (preferredPort) {
+    console.log(
+      chalk.yellow(
+        `No Twenty server found on port ${preferredPort}.\n` +
+          'Start your server and run `yarn twenty remote add --local` manually.\n',
+      ),
+    );
+
+    return { running: false };
+  }
+
+  console.log(chalk.blue('Setting up local Twenty instance...\n'));
+
+  try {
+    execSync('yarn twenty server start', {
+      cwd: appDirectory,
+      stdio: 'inherit',
+    });
+  } catch {
+    return { running: false };
+  }
+
+  console.log(chalk.gray('Waiting for Twenty to be ready...\n'));
+
+  const startTime = Date.now();
+  const timeoutMs = 180 * 1000;
+
+  while (Date.now() - startTime < timeoutMs) {
+    if (await isServerReady(LOCAL_PORTS[0])) {
+      const serverUrl = `http://localhost:${LOCAL_PORTS[0]}`;
+
+      console.log(chalk.green(`Server running on '${serverUrl}'\n`));
+
+      return { running: true, serverUrl };
+    }
+
+    await new Promise((resolve) => setTimeout(resolve, 2000));
+  }
+
+  console.log(
+    chalk.yellow(
+      'Twenty server did not become healthy in time.\n',
+      "Check: 'yarn twenty server logs'\n",
+    ),
+  );
+
+  return { running: false };
+};
@@ -5,7 +5,7 @@ This is a [Twenty](https://twenty.com) application project bootstrapped with [`c
 First, authenticate to your workspace:

 ```bash
-yarn twenty remote add http://localhost:2020 --as local
+yarn twenty remote add --local
 ```

 Then, start development mode to sync your app and watch for changes:
@@ -22,7 +22,7 @@ Run `yarn twenty help` to list all available commands. Common commands:

 ```bash
 # Remotes & Authentication
-yarn twenty remote add http://localhost:2020 --as local     # Authenticate with Twenty
+yarn twenty remote add --local     # Authenticate with Twenty
 yarn twenty remote status         # Check auth status
 yarn twenty remote switch         # Switch default remote
 yarn twenty remote list           # List all configured remotes
@@ -9,11 +9,22 @@
  },
  "packageManager": "yarn@4.9.2",
  "scripts": {
-    "twenty": "twenty"
+    "remote:add": "twenty remote add --local",
+    "remote:status": "twenty remote status",
+    "remote:switch": "twenty remote switch",
+    "remote:list": "twenty remote list",
+    "remote:remove": "twenty remote remove",
+    "dev": "twenty dev",
+    "add": "twenty add",
+    "logs": "twenty logs",
+    "exec": "twenty exec",
+    "uninstall": "twenty uninstall",
+    "help": "twenty help",
+    "lint": "oxlint -c .oxlintrc.json .",
+    "lint:fix": "oxlint --fix -c .oxlintrc.json ."
  },
  "dependencies": {
-    "twenty-sdk": "latest",
-    "twenty-client-sdk": "latest"
+    "twenty-sdk": "latest"
  },
  "devDependencies": {
    "typescript": "^5.9.3",
@@ -5,7 +5,7 @@ This is a [Twenty](https://twenty.com) application project bootstrapped with [`c
 First, authenticate to your workspace:

 ```bash
-yarn twenty remote add http://localhost:2020 --as local
+yarn twenty remote add --local
 ```

 Then, start development mode to sync your app and watch for changes:
@@ -22,7 +22,7 @@ Run `yarn twenty help` to list all available commands. Common commands:

 ```bash
 # Remotes & Authentication
-yarn twenty remote add http://localhost:2020 --as local     # Authenticate with Twenty
+yarn twenty remote add --local     # Authenticate with Twenty
 yarn twenty remote status         # Check auth status
 yarn twenty remote switch         # Switch default remote
 yarn twenty remote list           # List all configured remotes
@@ -5,7 +5,7 @@ This is a [Twenty](https://twenty.com) application project bootstrapped with [`c
 First, authenticate to your workspace:

 ```bash
-yarn twenty remote add http://localhost:2020 --as local
+yarn twenty remote add --local
 ```

 Then, start development mode to sync your app and watch for changes:
@@ -22,7 +22,7 @@ Run `yarn twenty help` to list all available commands. Common commands:

 ```bash
 # Remotes & Authentication
-yarn twenty remote add http://localhost:2020 --as local     # Authenticate with Twenty
+yarn twenty remote add --local     # Authenticate with Twenty
 yarn twenty remote status         # Check auth status
 yarn twenty remote switch         # Switch default remote
 yarn twenty remote list           # List all configured remotes
@@ -1,6 +1,6 @@
 {
  "name": "twenty-client-sdk",
-  "version": "0.8.0-canary.6",
+  "version": "0.7.0-canary.0",
  "sideEffects": false,
  "license": "AGPL-3.0",
  "scripts": {
@@ -38,6 +38,9 @@ type ApplicationRegistration {
  id: UUID!
  universalIdentifier: String!
  name: String!
+  description: String
+  logoUrl: String
+  author: String
  oAuthClientId: String!
  oAuthRedirectUris: [String!]!
  oAuthScopes: [String!]!
@@ -45,6 +48,8 @@ type ApplicationRegistration {
  sourceType: ApplicationRegistrationSourceType!
  sourcePackage: String
  latestAvailableVersion: String
+  websiteUrl: String
+  termsUrl: String
  isListed: Boolean!
  isFeatured: Boolean!
  createdAt: DateTime!
@@ -338,7 +343,6 @@ type Field {
  defaultValue: JSON
  options: JSON
  settings: JSON
-  objectMetadataId: UUID!
  isLabelSyncedWithName: Boolean
  morphId: UUID
  createdAt: DateTime!
@@ -536,7 +540,6 @@ input FieldFilter {
  isActive: BooleanFieldComparison
  isSystem: BooleanFieldComparison
  isUIReadOnly: BooleanFieldComparison
-  objectMetadataId: UUIDFilterComparison
 }

 input IndexFilter {
@@ -775,7 +778,8 @@ type Workspace {
  viewGroups: [ViewGroup!]
  viewSorts: [ViewSort!]
  metadataVersion: Float!
-  databaseSchema: String
+  databaseUrl: String!
+  databaseSchema: String!
  subdomain: String!
  customDomain: String
  isGoogleAuthEnabled: Boolean!
@@ -1720,13 +1724,20 @@ enum FeatureFlagKey {
  IS_UNIQUE_INDEXES_ENABLED
  IS_JSON_FILTER_ENABLED
  IS_AI_ENABLED
+  IS_APPLICATION_ENABLED
  IS_MARKETPLACE_ENABLED
  IS_RECORD_PAGE_LAYOUT_EDITING_ENABLED
  IS_PUBLIC_DOMAIN_ENABLED
  IS_EMAILING_DOMAIN_ENABLED
+  IS_DASHBOARD_V2_ENABLED
+  IS_ATTACHMENT_MIGRATED
+  IS_NOTE_TARGET_MIGRATED
+  IS_TASK_TARGET_MIGRATED
+  IS_ROW_LEVEL_PERMISSION_PREDICATES_ENABLED
  IS_JUNCTION_RELATIONS_ENABLED
  IS_COMMAND_MENU_ITEM_ENABLED
  IS_NAVIGATION_MENU_ITEM_ENABLED
+  IS_DATE_TIME_WHOLE_DAY_FILTER_ENABLED
  IS_NAVIGATION_MENU_ITEM_EDITING_ENABLED
  IS_DRAFT_EMAIL_ENABLED
  IS_USAGE_ANALYTICS_ENABLED
@@ -1736,7 +1747,6 @@ enum FeatureFlagKey {
  IS_CONNECTED_ACCOUNT_MIGRATED
  IS_GRAPHQL_QUERY_TIMING_ENABLED
  IS_RECORD_TABLE_WIDGET_ENABLED
-  IS_DATASOURCE_MIGRATED
 }

 type ClientConfig {
@@ -1769,12 +1779,6 @@ type ClientConfig {
  isClickHouseConfigured: Boolean!
 }

-type UsageBreakdownItem {
-  key: String!
-  label: String
-  creditsUsed: Float!
-}
-
 type ConfigVariable {
  name: String!
  description: String!
@@ -2269,11 +2273,6 @@ type FieldConnection {
  edges: [FieldEdge!]!
 }

-type LogicFunctionLogs {
-  """Execution Logs"""
-  logs: String!
-}
-
 type DeleteTwoFactorAuthenticationMethod {
  """Boolean that confirms query was dispatched"""
  success: Boolean!
@@ -2374,26 +2373,6 @@ type Impersonate {
  workspace: WorkspaceUrlsAndId!
 }

-type UsageTimeSeries {
-  date: String!
-  creditsUsed: Float!
-}
-
-type UsageUserDaily {
-  userWorkspaceId: String!
-  dailyUsage: [UsageTimeSeries!]!
-}
-
-type UsageAnalytics {
-  usageByUser: [UsageBreakdownItem!]!
-  usageByOperationType: [UsageBreakdownItem!]!
-  usageByModel: [UsageBreakdownItem!]!
-  timeSeries: [UsageTimeSeries!]!
-  periodStart: DateTime!
-  periodEnd: DateTime!
-  userDailyUsage: UsageUserDaily
-}
-
 type DevelopmentApplication {
  id: String!
  universalIdentifier: String!
@@ -2416,30 +2395,91 @@ type File {
  createdAt: DateTime!
 }

+type MarketplaceAppField {
+  name: String!
+  type: String!
+  label: String!
+  description: String
+  icon: String
+  objectUniversalIdentifier: String
+  universalIdentifier: String
+}
+
+type MarketplaceAppObject {
+  universalIdentifier: String!
+  nameSingular: String!
+  namePlural: String!
+  labelSingular: String!
+  labelPlural: String!
+  description: String
+  icon: String
+  fields: [MarketplaceAppField!]!
+}
+
+type MarketplaceAppLogicFunction {
+  name: String!
+  description: String
+  timeoutSeconds: Int
+}
+
+type MarketplaceAppFrontComponent {
+  name: String!
+  description: String
+}
+
+type MarketplaceAppRoleObjectPermission {
+  objectUniversalIdentifier: String!
+  canReadObjectRecords: Boolean
+  canUpdateObjectRecords: Boolean
+  canSoftDeleteObjectRecords: Boolean
+  canDestroyObjectRecords: Boolean
+}
+
+type MarketplaceAppRoleFieldPermission {
+  objectUniversalIdentifier: String!
+  fieldUniversalIdentifier: String!
+  canReadFieldValue: Boolean
+  canUpdateFieldValue: Boolean
+}
+
+type MarketplaceAppDefaultRole {
+  id: String!
+  label: String!
+  description: String
+  canReadAllObjectRecords: Boolean!
+  canUpdateAllObjectRecords: Boolean!
+  canSoftDeleteAllObjectRecords: Boolean!
+  canDestroyAllObjectRecords: Boolean!
+  canUpdateAllSettings: Boolean!
+  canAccessAllTools: Boolean!
+  objectPermissions: [MarketplaceAppRoleObjectPermission!]!
+  fieldPermissions: [MarketplaceAppRoleFieldPermission!]!
+  permissionFlags: [String!]!
+}
+
 type MarketplaceApp {
  id: String!
  name: String!
  description: String!
  icon: String!
+  version: String!
  author: String!
  category: String!
  logo: String
+  screenshots: [String!]!
+  aboutDescription: String!
+  providers: [String!]!
+  websiteUrl: String
+  termsUrl: String
+  objects: [MarketplaceAppObject!]!
+  fields: [MarketplaceAppField!]!
+  logicFunctions: [MarketplaceAppLogicFunction!]!
+  frontComponents: [MarketplaceAppFrontComponent!]!
+  defaultRole: MarketplaceAppDefaultRole
  sourcePackage: String
  isFeatured: Boolean!
 }

-type MarketplaceAppDetail {
-  universalIdentifier: String!
-  id: String!
-  name: String!
-  sourceType: ApplicationRegistrationSourceType!
-  sourcePackage: String
-  latestAvailableVersion: String
-  isListed: Boolean!
-  isFeatured: Boolean!
-  manifest: JSON
-}
-
 type PublicDomain {
  id: UUID!
  domain: String!
@@ -2528,6 +2568,36 @@ type PostgresCredentials {
  workspaceId: UUID!
 }

+type UsageBreakdownItem {
+  key: String!
+  label: String
+  creditsUsed: Float!
+}
+
+type UsageTimeSeries {
+  date: String!
+  creditsUsed: Float!
+}
+
+type UsageUserDaily {
+  userWorkspaceId: String!
+  dailyUsage: [UsageTimeSeries!]!
+}
+
+type UsageAnalytics {
+  usageByUser: [UsageBreakdownItem!]!
+  usageByOperationType: [UsageBreakdownItem!]!
+  timeSeries: [UsageTimeSeries!]!
+  periodStart: DateTime!
+  periodEnd: DateTime!
+  userDailyUsage: UsageUserDaily
+}
+
+type LogicFunctionLogs {
+  """Execution Logs"""
+  logs: String!
+}
+
 type FrontComponent {
  id: UUID!
  name: String!
@@ -3020,7 +3090,6 @@ enum AllMetadataName {
  navigationMenuItem
  permissionFlag
  objectPermission
-  fieldPermission
  frontComponent
  webhook
 }
@@ -3183,7 +3252,6 @@ type Query {
  findApplicationRegistrationStats(id: String!): ApplicationRegistrationStats!
  findApplicationRegistrationVariables(applicationRegistrationId: String!): [ApplicationRegistrationVariable!]!
  applicationRegistrationTarballUrl(id: String!): String
-  getApplicationShareLink(id: String!): String!
  currentUser: User!
  currentWorkspace: Workspace!
  getPublicWorkspaceDataByDomain(origin: String): PublicWorkspaceData!
@@ -3203,15 +3271,14 @@ type Query {
  getAiProviders: JSON!
  getModelsDevProviders: [ModelsDevProviderSuggestion!]!
  getModelsDevSuggestions(providerType: String!): [ModelsDevModelSuggestion!]!
-  getAdminAiUsageByWorkspace(periodStart: DateTime, periodEnd: DateTime): [UsageBreakdownItem!]!
-  getUsageAnalytics(input: UsageAnalyticsInput): UsageAnalytics!
  getPostgresCredentials: PostgresCredentials
  findManyPublicDomains: [PublicDomain!]!
  getEmailingDomains: [EmailingDomain!]!
  findManyMarketplaceApps: [MarketplaceApp!]!
-  findMarketplaceAppDetail(universalIdentifier: String!): MarketplaceAppDetail!
+  findOneMarketplaceApp(universalIdentifier: String!): MarketplaceApp!
  findManyApplications: [Application!]!
  findOneApplication(id: UUID, universalIdentifier: UUID): Application!
+  getUsageAnalytics(input: UsageAnalyticsInput): UsageAnalytics!
 }

 input GetApiKeyInput {
@@ -3324,14 +3391,6 @@ input UsageAnalyticsInput {
  periodStart: DateTime
  periodEnd: DateTime
  userWorkspaceId: String
-  operationTypes: [UsageOperationType!]
-}
-
-enum UsageOperationType {
-  AI_CHAT_TOKEN
-  AI_WORKFLOW_TOKEN
-  WORKFLOW_EXECUTION
-  CODE_EXECUTION
 }

 type Mutation {
@@ -3442,7 +3501,6 @@ type Mutation {
  createViewGroup(input: CreateViewGroupInput!): ViewGroup!
  createManyViewGroups(inputs: [CreateViewGroupInput!]!): [ViewGroup!]!
  updateViewGroup(input: UpdateViewGroupInput!): ViewGroup!
-  updateManyViewGroups(inputs: [UpdateViewGroupInput!]!): [ViewGroup!]!
  deleteViewGroup(input: DeleteViewGroupInput!): ViewGroup!
  destroyViewGroup(input: DestroyViewGroupInput!): ViewGroup!
  updateMessageFolder(input: UpdateMessageFolderInput!): MessageFolder!
@@ -3531,7 +3589,6 @@ type Mutation {
  verifyEmailingDomain(id: String!): EmailingDomain!
  createOneAppToken(input: CreateOneAppTokenInput!): AppToken!
  installMarketplaceApp(universalIdentifier: String!, version: String): Boolean!
-  syncMarketplaceCatalog: Boolean!
  installApplication(appRegistrationId: String!, version: String): Boolean!
  runWorkspaceMigration(workspaceMigration: WorkspaceMigrationInput!): Boolean!
  uninstallApplication(universalIdentifier: String!): Boolean!
@@ -4215,8 +4272,8 @@ input CreateFieldInput {
  defaultValue: JSON
  options: JSON
  settings: JSON
-  objectMetadataId: UUID!
  isLabelSyncedWithName: Boolean
+  objectMetadataId: UUID!
  isRemoteCreation: Boolean
  relationCreationPayload: JSON
  morphRelationsCreationPayload: [JSON!]
@@ -4244,7 +4301,6 @@ input UpdateFieldInput {
  defaultValue: JSON
  options: JSON
  settings: JSON
-  objectMetadataId: UUID
  isLabelSyncedWithName: Boolean
  morphRelationsUpdatePayload: [JSON!]
 }
@@ -4377,9 +4433,14 @@ input GetAuthorizationUrlForSSOInput {

 input CreateApplicationRegistrationInput {
  name: String!
+  description: String
+  logoUrl: String
+  author: String
  universalIdentifier: String
  oAuthRedirectUris: [String!]
  oAuthScopes: [String!]
+  websiteUrl: String
+  termsUrl: String
 }

 input UpdateApplicationRegistrationInput {
@@ -4389,8 +4450,13 @@ input UpdateApplicationRegistrationInput {

 input UpdateApplicationRegistrationPayload {
  name: String
+  description: String
+  logoUrl: String
+  author: String
  oAuthRedirectUris: [String!]
  oAuthScopes: [String!]
+  websiteUrl: String
+  termsUrl: String
  isListed: Boolean
 }

@@ -42,6 +42,9 @@ export interface ApplicationRegistration {
    id: Scalars['UUID']
    universalIdentifier: Scalars['String']
    name: Scalars['String']
+    description?: Scalars['String']
+    logoUrl?: Scalars['String']
+    author?: Scalars['String']
    oAuthClientId: Scalars['String']
    oAuthRedirectUris: Scalars['String'][]
    oAuthScopes: Scalars['String'][]
@@ -49,6 +52,8 @@ export interface ApplicationRegistration {
    sourceType: ApplicationRegistrationSourceType
    sourcePackage?: Scalars['String']
    latestAvailableVersion?: Scalars['String']
+    websiteUrl?: Scalars['String']
+    termsUrl?: Scalars['String']
    isListed: Scalars['Boolean']
    isFeatured: Scalars['Boolean']
    createdAt: Scalars['DateTime']
@@ -291,7 +296,6 @@ export interface Field {
    defaultValue?: Scalars['JSON']
    options?: Scalars['JSON']
    settings?: Scalars['JSON']
-    objectMetadataId: Scalars['UUID']
    isLabelSyncedWithName?: Scalars['Boolean']
    morphId?: Scalars['UUID']
    createdAt: Scalars['DateTime']
@@ -560,7 +564,8 @@ export interface Workspace {
    viewGroups?: ViewGroup[]
    viewSorts?: ViewSort[]
    metadataVersion: Scalars['Float']
-    databaseSchema?: Scalars['String']
+    databaseUrl: Scalars['String']
+    databaseSchema: Scalars['String']
    subdomain: Scalars['String']
    customDomain?: Scalars['String']
    isGoogleAuthEnabled: Scalars['Boolean']
@@ -1422,7 +1427,7 @@ export interface PublicFeatureFlag {
    __typename: 'PublicFeatureFlag'
 }

-export type FeatureFlagKey = 'IS_UNIQUE_INDEXES_ENABLED' | 'IS_JSON_FILTER_ENABLED' | 'IS_AI_ENABLED' | 'IS_MARKETPLACE_ENABLED' | 'IS_RECORD_PAGE_LAYOUT_EDITING_ENABLED' | 'IS_PUBLIC_DOMAIN_ENABLED' | 'IS_EMAILING_DOMAIN_ENABLED' | 'IS_JUNCTION_RELATIONS_ENABLED' | 'IS_COMMAND_MENU_ITEM_ENABLED' | 'IS_NAVIGATION_MENU_ITEM_ENABLED' | 'IS_NAVIGATION_MENU_ITEM_EDITING_ENABLED' | 'IS_DRAFT_EMAIL_ENABLED' | 'IS_USAGE_ANALYTICS_ENABLED' | 'IS_RICH_TEXT_V1_MIGRATED' | 'IS_DIRECT_GRAPHQL_EXECUTION_ENABLED' | 'IS_RECORD_PAGE_LAYOUT_GLOBAL_EDITION_ENABLED' | 'IS_CONNECTED_ACCOUNT_MIGRATED' | 'IS_GRAPHQL_QUERY_TIMING_ENABLED' | 'IS_RECORD_TABLE_WIDGET_ENABLED' | 'IS_DATASOURCE_MIGRATED'
+export type FeatureFlagKey = 'IS_UNIQUE_INDEXES_ENABLED' | 'IS_JSON_FILTER_ENABLED' | 'IS_AI_ENABLED' | 'IS_APPLICATION_ENABLED' | 'IS_MARKETPLACE_ENABLED' | 'IS_RECORD_PAGE_LAYOUT_EDITING_ENABLED' | 'IS_PUBLIC_DOMAIN_ENABLED' | 'IS_EMAILING_DOMAIN_ENABLED' | 'IS_DASHBOARD_V2_ENABLED' | 'IS_ATTACHMENT_MIGRATED' | 'IS_NOTE_TARGET_MIGRATED' | 'IS_TASK_TARGET_MIGRATED' | 'IS_ROW_LEVEL_PERMISSION_PREDICATES_ENABLED' | 'IS_JUNCTION_RELATIONS_ENABLED' | 'IS_COMMAND_MENU_ITEM_ENABLED' | 'IS_NAVIGATION_MENU_ITEM_ENABLED' | 'IS_DATE_TIME_WHOLE_DAY_FILTER_ENABLED' | 'IS_NAVIGATION_MENU_ITEM_EDITING_ENABLED' | 'IS_DRAFT_EMAIL_ENABLED' | 'IS_USAGE_ANALYTICS_ENABLED' | 'IS_RICH_TEXT_V1_MIGRATED' | 'IS_DIRECT_GRAPHQL_EXECUTION_ENABLED' | 'IS_RECORD_PAGE_LAYOUT_GLOBAL_EDITION_ENABLED' | 'IS_CONNECTED_ACCOUNT_MIGRATED' | 'IS_GRAPHQL_QUERY_TIMING_ENABLED' | 'IS_RECORD_TABLE_WIDGET_ENABLED'

 export interface ClientConfig {
    appVersion?: Scalars['String']
@@ -1455,13 +1460,6 @@ export interface ClientConfig {
    __typename: 'ClientConfig'
 }

-export interface UsageBreakdownItem {
-    key: Scalars['String']
-    label?: Scalars['String']
-    creditsUsed: Scalars['Float']
-    __typename: 'UsageBreakdownItem'
-}
-
 export interface ConfigVariable {
    name: Scalars['String']
    description: Scalars['String']
@@ -1939,12 +1937,6 @@ export interface FieldConnection {
    __typename: 'FieldConnection'
 }

-export interface LogicFunctionLogs {
-    /** Execution Logs */
-    logs: Scalars['String']
-    __typename: 'LogicFunctionLogs'
-}
-
 export interface DeleteTwoFactorAuthenticationMethod {
    /** Boolean that confirms query was dispatched */
    success: Scalars['Boolean']
@@ -2066,29 +2058,6 @@ export interface Impersonate {
    __typename: 'Impersonate'
 }

-export interface UsageTimeSeries {
-    date: Scalars['String']
-    creditsUsed: Scalars['Float']
-    __typename: 'UsageTimeSeries'
-}
-
-export interface UsageUserDaily {
-    userWorkspaceId: Scalars['String']
-    dailyUsage: UsageTimeSeries[]
-    __typename: 'UsageUserDaily'
-}
-
-export interface UsageAnalytics {
-    usageByUser: UsageBreakdownItem[]
-    usageByOperationType: UsageBreakdownItem[]
-    usageByModel: UsageBreakdownItem[]
-    timeSeries: UsageTimeSeries[]
-    periodStart: Scalars['DateTime']
-    periodEnd: Scalars['DateTime']
-    userDailyUsage?: UsageUserDaily
-    __typename: 'UsageAnalytics'
-}
-
 export interface DevelopmentApplication {
    id: Scalars['String']
    universalIdentifier: Scalars['String']
@@ -2115,32 +2084,99 @@ export interface File {
    __typename: 'File'
 }

+export interface MarketplaceAppField {
+    name: Scalars['String']
+    type: Scalars['String']
+    label: Scalars['String']
+    description?: Scalars['String']
+    icon?: Scalars['String']
+    objectUniversalIdentifier?: Scalars['String']
+    universalIdentifier?: Scalars['String']
+    __typename: 'MarketplaceAppField'
+}
+
+export interface MarketplaceAppObject {
+    universalIdentifier: Scalars['String']
+    nameSingular: Scalars['String']
+    namePlural: Scalars['String']
+    labelSingular: Scalars['String']
+    labelPlural: Scalars['String']
+    description?: Scalars['String']
+    icon?: Scalars['String']
+    fields: MarketplaceAppField[]
+    __typename: 'MarketplaceAppObject'
+}
+
+export interface MarketplaceAppLogicFunction {
+    name: Scalars['String']
+    description?: Scalars['String']
+    timeoutSeconds?: Scalars['Int']
+    __typename: 'MarketplaceAppLogicFunction'
+}
+
+export interface MarketplaceAppFrontComponent {
+    name: Scalars['String']
+    description?: Scalars['String']
+    __typename: 'MarketplaceAppFrontComponent'
+}
+
+export interface MarketplaceAppRoleObjectPermission {
+    objectUniversalIdentifier: Scalars['String']
+    canReadObjectRecords?: Scalars['Boolean']
+    canUpdateObjectRecords?: Scalars['Boolean']
+    canSoftDeleteObjectRecords?: Scalars['Boolean']
+    canDestroyObjectRecords?: Scalars['Boolean']
+    __typename: 'MarketplaceAppRoleObjectPermission'
+}
+
+export interface MarketplaceAppRoleFieldPermission {
+    objectUniversalIdentifier: Scalars['String']
+    fieldUniversalIdentifier: Scalars['String']
+    canReadFieldValue?: Scalars['Boolean']
+    canUpdateFieldValue?: Scalars['Boolean']
+    __typename: 'MarketplaceAppRoleFieldPermission'
+}
+
+export interface MarketplaceAppDefaultRole {
+    id: Scalars['String']
+    label: Scalars['String']
+    description?: Scalars['String']
+    canReadAllObjectRecords: Scalars['Boolean']
+    canUpdateAllObjectRecords: Scalars['Boolean']
+    canSoftDeleteAllObjectRecords: Scalars['Boolean']
+    canDestroyAllObjectRecords: Scalars['Boolean']
+    canUpdateAllSettings: Scalars['Boolean']
+    canAccessAllTools: Scalars['Boolean']
+    objectPermissions: MarketplaceAppRoleObjectPermission[]
+    fieldPermissions: MarketplaceAppRoleFieldPermission[]
+    permissionFlags: Scalars['String'][]
+    __typename: 'MarketplaceAppDefaultRole'
+}
+
 export interface MarketplaceApp {
    id: Scalars['String']
    name: Scalars['String']
    description: Scalars['String']
    icon: Scalars['String']
+    version: Scalars['String']
    author: Scalars['String']
    category: Scalars['String']
    logo?: Scalars['String']
+    screenshots: Scalars['String'][]
+    aboutDescription: Scalars['String']
+    providers: Scalars['String'][]
+    websiteUrl?: Scalars['String']
+    termsUrl?: Scalars['String']
+    objects: MarketplaceAppObject[]
+    fields: MarketplaceAppField[]
+    logicFunctions: MarketplaceAppLogicFunction[]
+    frontComponents: MarketplaceAppFrontComponent[]
+    defaultRole?: MarketplaceAppDefaultRole
    sourcePackage?: Scalars['String']
    isFeatured: Scalars['Boolean']
    __typename: 'MarketplaceApp'
 }

-export interface MarketplaceAppDetail {
-    universalIdentifier: Scalars['String']
-    id: Scalars['String']
-    name: Scalars['String']
-    sourceType: ApplicationRegistrationSourceType
-    sourcePackage?: Scalars['String']
-    latestAvailableVersion?: Scalars['String']
-    isListed: Scalars['Boolean']
-    isFeatured: Scalars['Boolean']
-    manifest?: Scalars['JSON']
-    __typename: 'MarketplaceAppDetail'
-}
-
 export interface PublicDomain {
    id: Scalars['UUID']
    domain: Scalars['String']
@@ -2233,6 +2269,41 @@ export interface PostgresCredentials {
    __typename: 'PostgresCredentials'
 }

+export interface UsageBreakdownItem {
+    key: Scalars['String']
+    label?: Scalars['String']
+    creditsUsed: Scalars['Float']
+    __typename: 'UsageBreakdownItem'
+}
+
+export interface UsageTimeSeries {
+    date: Scalars['String']
+    creditsUsed: Scalars['Float']
+    __typename: 'UsageTimeSeries'
+}
+
+export interface UsageUserDaily {
+    userWorkspaceId: Scalars['String']
+    dailyUsage: UsageTimeSeries[]
+    __typename: 'UsageUserDaily'
+}
+
+export interface UsageAnalytics {
+    usageByUser: UsageBreakdownItem[]
+    usageByOperationType: UsageBreakdownItem[]
+    timeSeries: UsageTimeSeries[]
+    periodStart: Scalars['DateTime']
+    periodEnd: Scalars['DateTime']
+    userDailyUsage?: UsageUserDaily
+    __typename: 'UsageAnalytics'
+}
+
+export interface LogicFunctionLogs {
+    /** Execution Logs */
+    logs: Scalars['String']
+    __typename: 'LogicFunctionLogs'
+}
+
 export interface FrontComponent {
    id: Scalars['UUID']
    name: Scalars['String']
@@ -2605,7 +2676,7 @@ export interface CollectionHash {
    __typename: 'CollectionHash'
 }

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

 export interface MinimalObjectMetadata {
    id: Scalars['UUID']
@@ -2733,7 +2804,6 @@ export interface Query {
    findApplicationRegistrationStats: ApplicationRegistrationStats
    findApplicationRegistrationVariables: ApplicationRegistrationVariable[]
    applicationRegistrationTarballUrl?: Scalars['String']
-    getApplicationShareLink: Scalars['String']
    currentUser: User
    currentWorkspace: Workspace
    getPublicWorkspaceDataByDomain: PublicWorkspaceData
@@ -2753,15 +2823,14 @@ export interface Query {
    getAiProviders: Scalars['JSON']
    getModelsDevProviders: ModelsDevProviderSuggestion[]
    getModelsDevSuggestions: ModelsDevModelSuggestion[]
-    getAdminAiUsageByWorkspace: UsageBreakdownItem[]
-    getUsageAnalytics: UsageAnalytics
    getPostgresCredentials?: PostgresCredentials
    findManyPublicDomains: PublicDomain[]
    getEmailingDomains: EmailingDomain[]
    findManyMarketplaceApps: MarketplaceApp[]
-    findMarketplaceAppDetail: MarketplaceAppDetail
+    findOneMarketplaceApp: MarketplaceApp
    findManyApplications: Application[]
    findOneApplication: Application
+    getUsageAnalytics: UsageAnalytics
    __typename: 'Query'
 }

@@ -2777,8 +2846,6 @@ export type SortNulls = 'NULLS_FIRST' | 'NULLS_LAST'

 export type EventLogTable = 'WORKSPACE_EVENT' | 'PAGEVIEW' | 'OBJECT_EVENT' | 'USAGE_EVENT'

-export type UsageOperationType = 'AI_CHAT_TOKEN' | 'AI_WORKFLOW_TOKEN' | 'WORKFLOW_EXECUTION' | 'CODE_EXECUTION'
-
 export interface Mutation {
    addQueryToEventStream: Scalars['Boolean']
    removeQueryFromEventStream: Scalars['Boolean']
@@ -2887,7 +2954,6 @@ export interface Mutation {
    createViewGroup: ViewGroup
    createManyViewGroups: ViewGroup[]
    updateViewGroup: ViewGroup
-    updateManyViewGroups: ViewGroup[]
    deleteViewGroup: ViewGroup
    destroyViewGroup: ViewGroup
    updateMessageFolder: MessageFolder
@@ -2976,7 +3042,6 @@ export interface Mutation {
    verifyEmailingDomain: EmailingDomain
    createOneAppToken: AppToken
    installMarketplaceApp: Scalars['Boolean']
-    syncMarketplaceCatalog: Scalars['Boolean']
    installApplication: Scalars['Boolean']
    runWorkspaceMigration: Scalars['Boolean']
    uninstallApplication: Scalars['Boolean']
@@ -3044,6 +3109,9 @@ export interface ApplicationRegistrationGenqlSelection{
    id?: boolean | number
    universalIdentifier?: boolean | number
    name?: boolean | number
+    description?: boolean | number
+    logoUrl?: boolean | number
+    author?: boolean | number
    oAuthClientId?: boolean | number
    oAuthRedirectUris?: boolean | number
    oAuthScopes?: boolean | number
@@ -3051,6 +3119,8 @@ export interface ApplicationRegistrationGenqlSelection{
    sourceType?: boolean | number
    sourcePackage?: boolean | number
    latestAvailableVersion?: boolean | number
+    websiteUrl?: boolean | number
+    termsUrl?: boolean | number
    isListed?: boolean | number
    isFeatured?: boolean | number
    createdAt?: boolean | number
@@ -3290,7 +3360,6 @@ export interface FieldGenqlSelection{
    defaultValue?: boolean | number
    options?: boolean | number
    settings?: boolean | number
-    objectMetadataId?: boolean | number
    isLabelSyncedWithName?: boolean | number
    morphId?: boolean | number
    createdAt?: boolean | number
@@ -3407,7 +3476,7 @@ export interface ObjectGenqlSelection{
    __scalar?: boolean | number
 }

-export interface FieldFilter {and?: (FieldFilter[] | null),or?: (FieldFilter[] | null),id?: (UUIDFilterComparison | null),isCustom?: (BooleanFieldComparison | null),isActive?: (BooleanFieldComparison | null),isSystem?: (BooleanFieldComparison | null),isUIReadOnly?: (BooleanFieldComparison | null),objectMetadataId?: (UUIDFilterComparison | null)}
+export interface FieldFilter {and?: (FieldFilter[] | null),or?: (FieldFilter[] | null),id?: (UUIDFilterComparison | null),isCustom?: (BooleanFieldComparison | null),isActive?: (BooleanFieldComparison | null),isSystem?: (BooleanFieldComparison | null),isUIReadOnly?: (BooleanFieldComparison | null)}

 export interface IndexFilter {and?: (IndexFilter[] | null),or?: (IndexFilter[] | null),id?: (UUIDFilterComparison | null),isCustom?: (BooleanFieldComparison | null)}

@@ -3584,6 +3653,7 @@ export interface WorkspaceGenqlSelection{
    viewGroups?: ViewGroupGenqlSelection
    viewSorts?: ViewSortGenqlSelection
    metadataVersion?: boolean | number
+    databaseUrl?: boolean | number
    databaseSchema?: boolean | number
    subdomain?: boolean | number
    customDomain?: boolean | number
@@ -4514,14 +4584,6 @@ export interface ClientConfigGenqlSelection{
    __scalar?: boolean | number
 }

-export interface UsageBreakdownItemGenqlSelection{
-    key?: boolean | number
-    label?: boolean | number
-    creditsUsed?: boolean | number
-    __typename?: boolean | number
-    __scalar?: boolean | number
-}
-
 export interface ConfigVariableGenqlSelection{
    name?: boolean | number
    description?: boolean | number
@@ -5034,13 +5096,6 @@ export interface FieldConnectionGenqlSelection{
    __scalar?: boolean | number
 }

-export interface LogicFunctionLogsGenqlSelection{
-    /** Execution Logs */
-    logs?: boolean | number
-    __typename?: boolean | number
-    __scalar?: boolean | number
-}
-
 export interface DeleteTwoFactorAuthenticationMethodGenqlSelection{
    /** Boolean that confirms query was dispatched */
    success?: boolean | number
@@ -5183,32 +5238,6 @@ export interface ImpersonateGenqlSelection{
    __scalar?: boolean | number
 }

-export interface UsageTimeSeriesGenqlSelection{
-    date?: boolean | number
-    creditsUsed?: boolean | number
-    __typename?: boolean | number
-    __scalar?: boolean | number
-}
-
-export interface UsageUserDailyGenqlSelection{
-    userWorkspaceId?: boolean | number
-    dailyUsage?: UsageTimeSeriesGenqlSelection
-    __typename?: boolean | number
-    __scalar?: boolean | number
-}
-
-export interface UsageAnalyticsGenqlSelection{
-    usageByUser?: UsageBreakdownItemGenqlSelection
-    usageByOperationType?: UsageBreakdownItemGenqlSelection
-    usageByModel?: UsageBreakdownItemGenqlSelection
-    timeSeries?: UsageTimeSeriesGenqlSelection
-    periodStart?: boolean | number
-    periodEnd?: boolean | number
-    userDailyUsage?: UsageUserDailyGenqlSelection
-    __typename?: boolean | number
-    __scalar?: boolean | number
-}
-
 export interface DevelopmentApplicationGenqlSelection{
    id?: boolean | number
    universalIdentifier?: boolean | number
@@ -5239,34 +5268,107 @@ export interface FileGenqlSelection{
    __scalar?: boolean | number
 }

+export interface MarketplaceAppFieldGenqlSelection{
+    name?: boolean | number
+    type?: boolean | number
+    label?: boolean | number
+    description?: boolean | number
+    icon?: boolean | number
+    objectUniversalIdentifier?: boolean | number
+    universalIdentifier?: boolean | number
+    __typename?: boolean | number
+    __scalar?: boolean | number
+}
+
+export interface MarketplaceAppObjectGenqlSelection{
+    universalIdentifier?: boolean | number
+    nameSingular?: boolean | number
+    namePlural?: boolean | number
+    labelSingular?: boolean | number
+    labelPlural?: boolean | number
+    description?: boolean | number
+    icon?: boolean | number
+    fields?: MarketplaceAppFieldGenqlSelection
+    __typename?: boolean | number
+    __scalar?: boolean | number
+}
+
+export interface MarketplaceAppLogicFunctionGenqlSelection{
+    name?: boolean | number
+    description?: boolean | number
+    timeoutSeconds?: boolean | number
+    __typename?: boolean | number
+    __scalar?: boolean | number
+}
+
+export interface MarketplaceAppFrontComponentGenqlSelection{
+    name?: boolean | number
+    description?: boolean | number
+    __typename?: boolean | number
+    __scalar?: boolean | number
+}
+
+export interface MarketplaceAppRoleObjectPermissionGenqlSelection{
+    objectUniversalIdentifier?: boolean | number
+    canReadObjectRecords?: boolean | number
+    canUpdateObjectRecords?: boolean | number
+    canSoftDeleteObjectRecords?: boolean | number
+    canDestroyObjectRecords?: boolean | number
+    __typename?: boolean | number
+    __scalar?: boolean | number
+}
+
+export interface MarketplaceAppRoleFieldPermissionGenqlSelection{
+    objectUniversalIdentifier?: boolean | number
+    fieldUniversalIdentifier?: boolean | number
+    canReadFieldValue?: boolean | number
+    canUpdateFieldValue?: boolean | number
+    __typename?: boolean | number
+    __scalar?: boolean | number
+}
+
+export interface MarketplaceAppDefaultRoleGenqlSelection{
+    id?: boolean | number
+    label?: boolean | number
+    description?: boolean | number
+    canReadAllObjectRecords?: boolean | number
+    canUpdateAllObjectRecords?: boolean | number
+    canSoftDeleteAllObjectRecords?: boolean | number
+    canDestroyAllObjectRecords?: boolean | number
+    canUpdateAllSettings?: boolean | number
+    canAccessAllTools?: boolean | number
+    objectPermissions?: MarketplaceAppRoleObjectPermissionGenqlSelection
+    fieldPermissions?: MarketplaceAppRoleFieldPermissionGenqlSelection
+    permissionFlags?: boolean | number
+    __typename?: boolean | number
+    __scalar?: boolean | number
+}
+
 export interface MarketplaceAppGenqlSelection{
    id?: boolean | number
    name?: boolean | number
    description?: boolean | number
    icon?: boolean | number
+    version?: boolean | number
    author?: boolean | number
    category?: boolean | number
    logo?: boolean | number
+    screenshots?: boolean | number
+    aboutDescription?: boolean | number
+    providers?: boolean | number
+    websiteUrl?: boolean | number
+    termsUrl?: boolean | number
+    objects?: MarketplaceAppObjectGenqlSelection
+    fields?: MarketplaceAppFieldGenqlSelection
+    logicFunctions?: MarketplaceAppLogicFunctionGenqlSelection
+    frontComponents?: MarketplaceAppFrontComponentGenqlSelection
+    defaultRole?: MarketplaceAppDefaultRoleGenqlSelection
    sourcePackage?: boolean | number
    isFeatured?: boolean | number
    __typename?: boolean | number
    __scalar?: boolean | number
 }

-export interface MarketplaceAppDetailGenqlSelection{
-    universalIdentifier?: boolean | number
-    id?: boolean | number
-    name?: boolean | number
-    sourceType?: boolean | number
-    sourcePackage?: boolean | number
-    latestAvailableVersion?: boolean | number
-    isListed?: boolean | number
-    isFeatured?: boolean | number
-    manifest?: boolean | number
-    __typename?: boolean | number
-    __scalar?: boolean | number
-}
-
 export interface PublicDomainGenqlSelection{
    id?: boolean | number
    domain?: boolean | number
@@ -5366,6 +5468,46 @@ export interface PostgresCredentialsGenqlSelection{
    __scalar?: boolean | number
 }

+export interface UsageBreakdownItemGenqlSelection{
+    key?: boolean | number
+    label?: boolean | number
+    creditsUsed?: boolean | number
+    __typename?: boolean | number
+    __scalar?: boolean | number
+}
+
+export interface UsageTimeSeriesGenqlSelection{
+    date?: boolean | number
+    creditsUsed?: boolean | number
+    __typename?: boolean | number
+    __scalar?: boolean | number
+}
+
+export interface UsageUserDailyGenqlSelection{
+    userWorkspaceId?: boolean | number
+    dailyUsage?: UsageTimeSeriesGenqlSelection
+    __typename?: boolean | number
+    __scalar?: boolean | number
+}
+
+export interface UsageAnalyticsGenqlSelection{
+    usageByUser?: UsageBreakdownItemGenqlSelection
+    usageByOperationType?: UsageBreakdownItemGenqlSelection
+    timeSeries?: UsageTimeSeriesGenqlSelection
+    periodStart?: boolean | number
+    periodEnd?: boolean | number
+    userDailyUsage?: UsageUserDailyGenqlSelection
+    __typename?: boolean | number
+    __scalar?: boolean | number
+}
+
+export interface LogicFunctionLogsGenqlSelection{
+    /** Execution Logs */
+    logs?: boolean | number
+    __typename?: boolean | number
+    __scalar?: boolean | number
+}
+
 export interface FrontComponentGenqlSelection{
    id?: boolean | number
    name?: boolean | number
@@ -5894,7 +6036,6 @@ export interface QueryGenqlSelection{
    findApplicationRegistrationStats?: (ApplicationRegistrationStatsGenqlSelection & { __args: {id: Scalars['String']} })
    findApplicationRegistrationVariables?: (ApplicationRegistrationVariableGenqlSelection & { __args: {applicationRegistrationId: Scalars['String']} })
    applicationRegistrationTarballUrl?: { __args: {id: Scalars['String']} }
-    getApplicationShareLink?: { __args: {id: Scalars['String']} }
    currentUser?: UserGenqlSelection
    currentWorkspace?: WorkspaceGenqlSelection
    getPublicWorkspaceDataByDomain?: (PublicWorkspaceDataGenqlSelection & { __args?: {origin?: (Scalars['String'] | null)} })
@@ -5914,15 +6055,14 @@ export interface QueryGenqlSelection{
    getAiProviders?: boolean | number
    getModelsDevProviders?: ModelsDevProviderSuggestionGenqlSelection
    getModelsDevSuggestions?: (ModelsDevModelSuggestionGenqlSelection & { __args: {providerType: Scalars['String']} })
-    getAdminAiUsageByWorkspace?: (UsageBreakdownItemGenqlSelection & { __args?: {periodStart?: (Scalars['DateTime'] | null), periodEnd?: (Scalars['DateTime'] | null)} })
-    getUsageAnalytics?: (UsageAnalyticsGenqlSelection & { __args?: {input?: (UsageAnalyticsInput | null)} })
    getPostgresCredentials?: PostgresCredentialsGenqlSelection
    findManyPublicDomains?: PublicDomainGenqlSelection
    getEmailingDomains?: EmailingDomainGenqlSelection
    findManyMarketplaceApps?: MarketplaceAppGenqlSelection
-    findMarketplaceAppDetail?: (MarketplaceAppDetailGenqlSelection & { __args: {universalIdentifier: Scalars['String']} })
+    findOneMarketplaceApp?: (MarketplaceAppGenqlSelection & { __args: {universalIdentifier: Scalars['String']} })
    findManyApplications?: ApplicationGenqlSelection
    findOneApplication?: (ApplicationGenqlSelection & { __args?: {id?: (Scalars['UUID'] | null), universalIdentifier?: (Scalars['UUID'] | null)} })
+    getUsageAnalytics?: (UsageAnalyticsGenqlSelection & { __args?: {input?: (UsageAnalyticsInput | null)} })
    __typename?: boolean | number
    __scalar?: boolean | number
 }
@@ -5957,7 +6097,7 @@ export interface LineChartDataInput {objectMetadataId: Scalars['UUID'],configura

 export interface BarChartDataInput {objectMetadataId: Scalars['UUID'],configuration: Scalars['JSON']}

-export interface UsageAnalyticsInput {periodStart?: (Scalars['DateTime'] | null),periodEnd?: (Scalars['DateTime'] | null),userWorkspaceId?: (Scalars['String'] | null),operationTypes?: (UsageOperationType[] | null)}
+export interface UsageAnalyticsInput {periodStart?: (Scalars['DateTime'] | null),periodEnd?: (Scalars['DateTime'] | null),userWorkspaceId?: (Scalars['String'] | null)}

 export interface MutationGenqlSelection{
    addQueryToEventStream?: { __args: {input: AddQuerySubscriptionInput} }
@@ -6067,7 +6207,6 @@ export interface MutationGenqlSelection{
    createViewGroup?: (ViewGroupGenqlSelection & { __args: {input: CreateViewGroupInput} })
    createManyViewGroups?: (ViewGroupGenqlSelection & { __args: {inputs: CreateViewGroupInput[]} })
    updateViewGroup?: (ViewGroupGenqlSelection & { __args: {input: UpdateViewGroupInput} })
-    updateManyViewGroups?: (ViewGroupGenqlSelection & { __args: {inputs: UpdateViewGroupInput[]} })
    deleteViewGroup?: (ViewGroupGenqlSelection & { __args: {input: DeleteViewGroupInput} })
    destroyViewGroup?: (ViewGroupGenqlSelection & { __args: {input: DestroyViewGroupInput} })
    updateMessageFolder?: (MessageFolderGenqlSelection & { __args: {input: UpdateMessageFolderInput} })
@@ -6156,7 +6295,6 @@ export interface MutationGenqlSelection{
    verifyEmailingDomain?: (EmailingDomainGenqlSelection & { __args: {id: Scalars['String']} })
    createOneAppToken?: (AppTokenGenqlSelection & { __args: {input: CreateOneAppTokenInput} })
    installMarketplaceApp?: { __args: {universalIdentifier: Scalars['String'], version?: (Scalars['String'] | null)} }
-    syncMarketplaceCatalog?: boolean | number
    installApplication?: { __args: {appRegistrationId: Scalars['String'], version?: (Scalars['String'] | null)} }
    runWorkspaceMigration?: { __args: {workspaceMigration: WorkspaceMigrationInput} }
    uninstallApplication?: { __args: {universalIdentifier: Scalars['String']} }
@@ -6389,7 +6527,7 @@ export interface CreateOneFieldMetadataInput {
 /** The record to create */
 field: CreateFieldInput}

-export interface CreateFieldInput {type: FieldMetadataType,name: Scalars['String'],label: Scalars['String'],description?: (Scalars['String'] | null),icon?: (Scalars['String'] | null),isCustom?: (Scalars['Boolean'] | null),isActive?: (Scalars['Boolean'] | null),isSystem?: (Scalars['Boolean'] | null),isUIReadOnly?: (Scalars['Boolean'] | null),isNullable?: (Scalars['Boolean'] | null),isUnique?: (Scalars['Boolean'] | null),defaultValue?: (Scalars['JSON'] | null),options?: (Scalars['JSON'] | null),settings?: (Scalars['JSON'] | null),objectMetadataId: Scalars['UUID'],isLabelSyncedWithName?: (Scalars['Boolean'] | null),isRemoteCreation?: (Scalars['Boolean'] | null),relationCreationPayload?: (Scalars['JSON'] | null),morphRelationsCreationPayload?: (Scalars['JSON'][] | null)}
+export interface CreateFieldInput {type: FieldMetadataType,name: Scalars['String'],label: Scalars['String'],description?: (Scalars['String'] | null),icon?: (Scalars['String'] | null),isCustom?: (Scalars['Boolean'] | null),isActive?: (Scalars['Boolean'] | null),isSystem?: (Scalars['Boolean'] | null),isUIReadOnly?: (Scalars['Boolean'] | null),isNullable?: (Scalars['Boolean'] | null),isUnique?: (Scalars['Boolean'] | null),defaultValue?: (Scalars['JSON'] | null),options?: (Scalars['JSON'] | null),settings?: (Scalars['JSON'] | null),isLabelSyncedWithName?: (Scalars['Boolean'] | null),objectMetadataId: Scalars['UUID'],isRemoteCreation?: (Scalars['Boolean'] | null),relationCreationPayload?: (Scalars['JSON'] | null),morphRelationsCreationPayload?: (Scalars['JSON'][] | null)}

 export interface UpdateOneFieldMetadataInput {
 /** The id of the record to update */
@@ -6397,7 +6535,7 @@ id: Scalars['UUID'],
 /** The record to update */
 update: UpdateFieldInput}

-export interface UpdateFieldInput {universalIdentifier?: (Scalars['String'] | null),name?: (Scalars['String'] | null),label?: (Scalars['String'] | null),description?: (Scalars['String'] | null),icon?: (Scalars['String'] | null),isActive?: (Scalars['Boolean'] | null),isSystem?: (Scalars['Boolean'] | null),isUIReadOnly?: (Scalars['Boolean'] | null),isNullable?: (Scalars['Boolean'] | null),isUnique?: (Scalars['Boolean'] | null),defaultValue?: (Scalars['JSON'] | null),options?: (Scalars['JSON'] | null),settings?: (Scalars['JSON'] | null),objectMetadataId?: (Scalars['UUID'] | null),isLabelSyncedWithName?: (Scalars['Boolean'] | null),morphRelationsUpdatePayload?: (Scalars['JSON'][] | null)}
+export interface UpdateFieldInput {universalIdentifier?: (Scalars['String'] | null),name?: (Scalars['String'] | null),label?: (Scalars['String'] | null),description?: (Scalars['String'] | null),icon?: (Scalars['String'] | null),isActive?: (Scalars['Boolean'] | null),isSystem?: (Scalars['Boolean'] | null),isUIReadOnly?: (Scalars['Boolean'] | null),isNullable?: (Scalars['Boolean'] | null),isUnique?: (Scalars['Boolean'] | null),defaultValue?: (Scalars['JSON'] | null),options?: (Scalars['JSON'] | null),settings?: (Scalars['JSON'] | null),isLabelSyncedWithName?: (Scalars['Boolean'] | null),morphRelationsUpdatePayload?: (Scalars['JSON'][] | null)}

 export interface DeleteOneFieldInput {
 /** The id of the field to delete. */
@@ -6451,11 +6589,11 @@ export interface UpdateSkillInput {id: Scalars['UUID'],name?: (Scalars['String']

 export interface GetAuthorizationUrlForSSOInput {identityProviderId: Scalars['UUID'],workspaceInviteHash?: (Scalars['String'] | null)}

-export interface CreateApplicationRegistrationInput {name: Scalars['String'],universalIdentifier?: (Scalars['String'] | null),oAuthRedirectUris?: (Scalars['String'][] | null),oAuthScopes?: (Scalars['String'][] | null)}
+export interface CreateApplicationRegistrationInput {name: Scalars['String'],description?: (Scalars['String'] | null),logoUrl?: (Scalars['String'] | null),author?: (Scalars['String'] | null),universalIdentifier?: (Scalars['String'] | null),oAuthRedirectUris?: (Scalars['String'][] | null),oAuthScopes?: (Scalars['String'][] | null),websiteUrl?: (Scalars['String'] | null),termsUrl?: (Scalars['String'] | null)}

 export interface UpdateApplicationRegistrationInput {id: Scalars['String'],update: UpdateApplicationRegistrationPayload}

-export interface UpdateApplicationRegistrationPayload {name?: (Scalars['String'] | null),oAuthRedirectUris?: (Scalars['String'][] | null),oAuthScopes?: (Scalars['String'][] | null),isListed?: (Scalars['Boolean'] | null)}
+export interface UpdateApplicationRegistrationPayload {name?: (Scalars['String'] | null),description?: (Scalars['String'] | null),logoUrl?: (Scalars['String'] | null),author?: (Scalars['String'] | null),oAuthRedirectUris?: (Scalars['String'][] | null),oAuthScopes?: (Scalars['String'][] | null),websiteUrl?: (Scalars['String'] | null),termsUrl?: (Scalars['String'] | null),isListed?: (Scalars['Boolean'] | null)}

 export interface CreateApplicationRegistrationVariableInput {applicationRegistrationId: Scalars['String'],key: Scalars['String'],value: Scalars['String'],description?: (Scalars['String'] | null),isSecret?: (Scalars['Boolean'] | null)}

@@ -7453,14 +7591,6 @@ export interface LogicFunctionLogsInput {applicationId?: (Scalars['UUID'] | null
    


-    const UsageBreakdownItem_possibleTypes: string[] = ['UsageBreakdownItem']
-    export const isUsageBreakdownItem = (obj?: { __typename?: any } | null): obj is UsageBreakdownItem => {
-      if (!obj?.__typename) throw new Error('__typename is missing in "isUsageBreakdownItem"')
-      return UsageBreakdownItem_possibleTypes.includes(obj.__typename)
-    }
-    
-
-
    const ConfigVariable_possibleTypes: string[] = ['ConfigVariable']
    export const isConfigVariable = (obj?: { __typename?: any } | null): obj is ConfigVariable => {
      if (!obj?.__typename) throw new Error('__typename is missing in "isConfigVariable"')
@@ -7917,14 +8047,6 @@ export interface LogicFunctionLogsInput {applicationId?: (Scalars['UUID'] | null
    


-    const LogicFunctionLogs_possibleTypes: string[] = ['LogicFunctionLogs']
-    export const isLogicFunctionLogs = (obj?: { __typename?: any } | null): obj is LogicFunctionLogs => {
-      if (!obj?.__typename) throw new Error('__typename is missing in "isLogicFunctionLogs"')
-      return LogicFunctionLogs_possibleTypes.includes(obj.__typename)
-    }
-    
-
-
    const DeleteTwoFactorAuthenticationMethod_possibleTypes: string[] = ['DeleteTwoFactorAuthenticationMethod']
    export const isDeleteTwoFactorAuthenticationMethod = (obj?: { __typename?: any } | null): obj is DeleteTwoFactorAuthenticationMethod => {
      if (!obj?.__typename) throw new Error('__typename is missing in "isDeleteTwoFactorAuthenticationMethod"')
@@ -8093,30 +8215,6 @@ export interface LogicFunctionLogsInput {applicationId?: (Scalars['UUID'] | null
    


-    const UsageTimeSeries_possibleTypes: string[] = ['UsageTimeSeries']
-    export const isUsageTimeSeries = (obj?: { __typename?: any } | null): obj is UsageTimeSeries => {
-      if (!obj?.__typename) throw new Error('__typename is missing in "isUsageTimeSeries"')
-      return UsageTimeSeries_possibleTypes.includes(obj.__typename)
-    }
-    
-
-
-    const UsageUserDaily_possibleTypes: string[] = ['UsageUserDaily']
-    export const isUsageUserDaily = (obj?: { __typename?: any } | null): obj is UsageUserDaily => {
-      if (!obj?.__typename) throw new Error('__typename is missing in "isUsageUserDaily"')
-      return UsageUserDaily_possibleTypes.includes(obj.__typename)
-    }
-    
-
-
-    const UsageAnalytics_possibleTypes: string[] = ['UsageAnalytics']
-    export const isUsageAnalytics = (obj?: { __typename?: any } | null): obj is UsageAnalytics => {
-      if (!obj?.__typename) throw new Error('__typename is missing in "isUsageAnalytics"')
-      return UsageAnalytics_possibleTypes.includes(obj.__typename)
-    }
-    
-
-
    const DevelopmentApplication_possibleTypes: string[] = ['DevelopmentApplication']
    export const isDevelopmentApplication = (obj?: { __typename?: any } | null): obj is DevelopmentApplication => {
      if (!obj?.__typename) throw new Error('__typename is missing in "isDevelopmentApplication"')
@@ -8149,18 +8247,66 @@ export interface LogicFunctionLogsInput {applicationId?: (Scalars['UUID'] | null
    


-    const MarketplaceApp_possibleTypes: string[] = ['MarketplaceApp']
-    export const isMarketplaceApp = (obj?: { __typename?: any } | null): obj is MarketplaceApp => {
-      if (!obj?.__typename) throw new Error('__typename is missing in "isMarketplaceApp"')
-      return MarketplaceApp_possibleTypes.includes(obj.__typename)
+    const MarketplaceAppField_possibleTypes: string[] = ['MarketplaceAppField']
+    export const isMarketplaceAppField = (obj?: { __typename?: any } | null): obj is MarketplaceAppField => {
+      if (!obj?.__typename) throw new Error('__typename is missing in "isMarketplaceAppField"')
+      return MarketplaceAppField_possibleTypes.includes(obj.__typename)
    }
    


-    const MarketplaceAppDetail_possibleTypes: string[] = ['MarketplaceAppDetail']
-    export const isMarketplaceAppDetail = (obj?: { __typename?: any } | null): obj is MarketplaceAppDetail => {
-      if (!obj?.__typename) throw new Error('__typename is missing in "isMarketplaceAppDetail"')
-      return MarketplaceAppDetail_possibleTypes.includes(obj.__typename)
+    const MarketplaceAppObject_possibleTypes: string[] = ['MarketplaceAppObject']
+    export const isMarketplaceAppObject = (obj?: { __typename?: any } | null): obj is MarketplaceAppObject => {
+      if (!obj?.__typename) throw new Error('__typename is missing in "isMarketplaceAppObject"')
+      return MarketplaceAppObject_possibleTypes.includes(obj.__typename)
+    }
+    
+
+
+    const MarketplaceAppLogicFunction_possibleTypes: string[] = ['MarketplaceAppLogicFunction']
+    export const isMarketplaceAppLogicFunction = (obj?: { __typename?: any } | null): obj is MarketplaceAppLogicFunction => {
+      if (!obj?.__typename) throw new Error('__typename is missing in "isMarketplaceAppLogicFunction"')
+      return MarketplaceAppLogicFunction_possibleTypes.includes(obj.__typename)
+    }
+    
+
+
+    const MarketplaceAppFrontComponent_possibleTypes: string[] = ['MarketplaceAppFrontComponent']
+    export const isMarketplaceAppFrontComponent = (obj?: { __typename?: any } | null): obj is MarketplaceAppFrontComponent => {
+      if (!obj?.__typename) throw new Error('__typename is missing in "isMarketplaceAppFrontComponent"')
+      return MarketplaceAppFrontComponent_possibleTypes.includes(obj.__typename)
+    }
+    
+
+
+    const MarketplaceAppRoleObjectPermission_possibleTypes: string[] = ['MarketplaceAppRoleObjectPermission']
+    export const isMarketplaceAppRoleObjectPermission = (obj?: { __typename?: any } | null): obj is MarketplaceAppRoleObjectPermission => {
+      if (!obj?.__typename) throw new Error('__typename is missing in "isMarketplaceAppRoleObjectPermission"')
+      return MarketplaceAppRoleObjectPermission_possibleTypes.includes(obj.__typename)
+    }
+    
+
+
+    const MarketplaceAppRoleFieldPermission_possibleTypes: string[] = ['MarketplaceAppRoleFieldPermission']
+    export const isMarketplaceAppRoleFieldPermission = (obj?: { __typename?: any } | null): obj is MarketplaceAppRoleFieldPermission => {
+      if (!obj?.__typename) throw new Error('__typename is missing in "isMarketplaceAppRoleFieldPermission"')
+      return MarketplaceAppRoleFieldPermission_possibleTypes.includes(obj.__typename)
+    }
+    
+
+
+    const MarketplaceAppDefaultRole_possibleTypes: string[] = ['MarketplaceAppDefaultRole']
+    export const isMarketplaceAppDefaultRole = (obj?: { __typename?: any } | null): obj is MarketplaceAppDefaultRole => {
+      if (!obj?.__typename) throw new Error('__typename is missing in "isMarketplaceAppDefaultRole"')
+      return MarketplaceAppDefaultRole_possibleTypes.includes(obj.__typename)
+    }
+    
+
+
+    const MarketplaceApp_possibleTypes: string[] = ['MarketplaceApp']
+    export const isMarketplaceApp = (obj?: { __typename?: any } | null): obj is MarketplaceApp => {
+      if (!obj?.__typename) throw new Error('__typename is missing in "isMarketplaceApp"')
+      return MarketplaceApp_possibleTypes.includes(obj.__typename)
    }
    

@@ -8253,6 +8399,46 @@ export interface LogicFunctionLogsInput {applicationId?: (Scalars['UUID'] | null
    


+    const UsageBreakdownItem_possibleTypes: string[] = ['UsageBreakdownItem']
+    export const isUsageBreakdownItem = (obj?: { __typename?: any } | null): obj is UsageBreakdownItem => {
+      if (!obj?.__typename) throw new Error('__typename is missing in "isUsageBreakdownItem"')
+      return UsageBreakdownItem_possibleTypes.includes(obj.__typename)
+    }
+    
+
+
+    const UsageTimeSeries_possibleTypes: string[] = ['UsageTimeSeries']
+    export const isUsageTimeSeries = (obj?: { __typename?: any } | null): obj is UsageTimeSeries => {
+      if (!obj?.__typename) throw new Error('__typename is missing in "isUsageTimeSeries"')
+      return UsageTimeSeries_possibleTypes.includes(obj.__typename)
+    }
+    
+
+
+    const UsageUserDaily_possibleTypes: string[] = ['UsageUserDaily']
+    export const isUsageUserDaily = (obj?: { __typename?: any } | null): obj is UsageUserDaily => {
+      if (!obj?.__typename) throw new Error('__typename is missing in "isUsageUserDaily"')
+      return UsageUserDaily_possibleTypes.includes(obj.__typename)
+    }
+    
+
+
+    const UsageAnalytics_possibleTypes: string[] = ['UsageAnalytics']
+    export const isUsageAnalytics = (obj?: { __typename?: any } | null): obj is UsageAnalytics => {
+      if (!obj?.__typename) throw new Error('__typename is missing in "isUsageAnalytics"')
+      return UsageAnalytics_possibleTypes.includes(obj.__typename)
+    }
+    
+
+
+    const LogicFunctionLogs_possibleTypes: string[] = ['LogicFunctionLogs']
+    export const isLogicFunctionLogs = (obj?: { __typename?: any } | null): obj is LogicFunctionLogs => {
+      if (!obj?.__typename) throw new Error('__typename is missing in "isLogicFunctionLogs"')
+      return LogicFunctionLogs_possibleTypes.includes(obj.__typename)
+    }
+    
+
+
    const FrontComponent_possibleTypes: string[] = ['FrontComponent']
    export const isFrontComponent = (obj?: { __typename?: any } | null): obj is FrontComponent => {
      if (!obj?.__typename) throw new Error('__typename is missing in "isFrontComponent"')
@@ -8947,13 +9133,20 @@ export const enumFeatureFlagKey = {
   IS_UNIQUE_INDEXES_ENABLED: 'IS_UNIQUE_INDEXES_ENABLED' as const,
   IS_JSON_FILTER_ENABLED: 'IS_JSON_FILTER_ENABLED' as const,
   IS_AI_ENABLED: 'IS_AI_ENABLED' as const,
+   IS_APPLICATION_ENABLED: 'IS_APPLICATION_ENABLED' as const,
   IS_MARKETPLACE_ENABLED: 'IS_MARKETPLACE_ENABLED' as const,
   IS_RECORD_PAGE_LAYOUT_EDITING_ENABLED: 'IS_RECORD_PAGE_LAYOUT_EDITING_ENABLED' as const,
   IS_PUBLIC_DOMAIN_ENABLED: 'IS_PUBLIC_DOMAIN_ENABLED' as const,
   IS_EMAILING_DOMAIN_ENABLED: 'IS_EMAILING_DOMAIN_ENABLED' as const,
+   IS_DASHBOARD_V2_ENABLED: 'IS_DASHBOARD_V2_ENABLED' as const,
+   IS_ATTACHMENT_MIGRATED: 'IS_ATTACHMENT_MIGRATED' as const,
+   IS_NOTE_TARGET_MIGRATED: 'IS_NOTE_TARGET_MIGRATED' as const,
+   IS_TASK_TARGET_MIGRATED: 'IS_TASK_TARGET_MIGRATED' as const,
+   IS_ROW_LEVEL_PERMISSION_PREDICATES_ENABLED: 'IS_ROW_LEVEL_PERMISSION_PREDICATES_ENABLED' as const,
   IS_JUNCTION_RELATIONS_ENABLED: 'IS_JUNCTION_RELATIONS_ENABLED' as const,
   IS_COMMAND_MENU_ITEM_ENABLED: 'IS_COMMAND_MENU_ITEM_ENABLED' as const,
   IS_NAVIGATION_MENU_ITEM_ENABLED: 'IS_NAVIGATION_MENU_ITEM_ENABLED' as const,
+   IS_DATE_TIME_WHOLE_DAY_FILTER_ENABLED: 'IS_DATE_TIME_WHOLE_DAY_FILTER_ENABLED' as const,
   IS_NAVIGATION_MENU_ITEM_EDITING_ENABLED: 'IS_NAVIGATION_MENU_ITEM_EDITING_ENABLED' as const,
   IS_DRAFT_EMAIL_ENABLED: 'IS_DRAFT_EMAIL_ENABLED' as const,
   IS_USAGE_ANALYTICS_ENABLED: 'IS_USAGE_ANALYTICS_ENABLED' as const,
@@ -8962,8 +9155,7 @@ export const enumFeatureFlagKey = {
   IS_RECORD_PAGE_LAYOUT_GLOBAL_EDITION_ENABLED: 'IS_RECORD_PAGE_LAYOUT_GLOBAL_EDITION_ENABLED' as const,
   IS_CONNECTED_ACCOUNT_MIGRATED: 'IS_CONNECTED_ACCOUNT_MIGRATED' as const,
   IS_GRAPHQL_QUERY_TIMING_ENABLED: 'IS_GRAPHQL_QUERY_TIMING_ENABLED' as const,
-   IS_RECORD_TABLE_WIDGET_ENABLED: 'IS_RECORD_TABLE_WIDGET_ENABLED' as const,
-   IS_DATASOURCE_MIGRATED: 'IS_DATASOURCE_MIGRATED' as const
+   IS_RECORD_TABLE_WIDGET_ENABLED: 'IS_RECORD_TABLE_WIDGET_ENABLED' as const
 }

 export const enumConfigSource = {
@@ -9233,7 +9425,6 @@ export const enumAllMetadataName = {
   navigationMenuItem: 'navigationMenuItem' as const,
   permissionFlag: 'permissionFlag' as const,
   objectPermission: 'objectPermission' as const,
-   fieldPermission: 'fieldPermission' as const,
   frontComponent: 'frontComponent' as const,
   webhook: 'webhook' as const
 }
@@ -9260,13 +9451,6 @@ export const enumEventLogTable = {
   USAGE_EVENT: 'USAGE_EVENT' as const
 }

-export const enumUsageOperationType = {
-   AI_CHAT_TOKEN: 'AI_CHAT_TOKEN' as const,
-   AI_WORKFLOW_TOKEN: 'AI_WORKFLOW_TOKEN' as const,
-   WORKFLOW_EXECUTION: 'WORKFLOW_EXECUTION' as const,
-   CODE_EXECUTION: 'CODE_EXECUTION' as const
-}
-
 export const enumAnalyticsType = {
   PAGEVIEW: 'PAGEVIEW' as const,
   TRACK: 'TRACK' as const
@@ -1,19 +1,6 @@
 {
-  "compileOnSave": false,
+  "extends": "../../tsconfig.base.json",
  "compilerOptions": {
-    "rootDir": ".",
-    "sourceMap": true,
-    "declaration": false,
-    "moduleResolution": "node",
-    "emitDecoratorMetadata": true,
-    "experimentalDecorators": true,
-    "importHelpers": true,
-    "target": "es2018",
-    "module": "esnext",
-    "lib": ["es2020", "dom"],
-    "skipLibCheck": true,
-    "skipDefaultLibCheck": true,
-    "resolveJsonModule": true,
    "allowJs": false,
    "esModuleInterop": false,
    "allowSyntheticDefaultImports": true,
@@ -32,11 +32,11 @@ has_schema=$(PGPASSWORD=twenty psql -h localhost -U twenty -d default -tAc \

 if [ "$has_schema" = "f" ]; then
  echo "Database appears to be empty, running initial setup..."
-  NODE_OPTIONS="--max-old-space-size=1500" node ./dist/database/scripts/setup-db.js
+  NODE_OPTIONS="--max-old-space-size=1500" node ./dist/scripts/setup-db.js
 fi

 # Always run migrations (idempotent — skips already-applied ones)
-yarn database:migrate:prod --force
+yarn database:migrate:prod

 yarn command:prod cache:flush
 yarn command:prod upgrade
@@ -38,6 +38,12 @@ RUN npx nx run twenty-server:lingui:extract && \

 RUN npx nx run twenty-server:build

+# Bundle setup-db script into a standalone JS file so the final image
+# doesn't need tsx or the TypeScript source tree at runtime.
+RUN npx esbuild packages/twenty-server/scripts/setup-db.ts \
+      --bundle --platform=node --outfile=packages/twenty-server/dist/scripts/setup-db.js \
+      --external:typeorm --external:dotenv --external:pg
+
 # Clean server build output (type declarations and compiled tests are not needed at runtime;
 # source maps are kept because twenty-infra extracts them from the image for Sentry uploads)
 RUN find /app/packages/twenty-server/dist -name '*.d.ts' -delete \
@@ -13,7 +13,8 @@ setup_and_migrate_db() {
    has_schema=$(psql -tAc "SELECT EXISTS (SELECT 1 FROM information_schema.schemata WHERE schema_name = 'core')" ${PG_DATABASE_URL})
    if [ "$has_schema" = "f" ]; then
        echo "Database appears to be empty, running migrations."
-        yarn database:init:prod
+        NODE_OPTIONS="--max-old-space-size=1500" node ./dist/scripts/setup-db.js
+        yarn database:migrate:prod
    fi

    yarn command:prod cache:flush
@@ -19,17 +19,15 @@ The SDK provides helper functions for defining your app entities. As described i
 |----------|---------|
 | `defineApplication` | Configure application metadata (required, one per app) |
 | `defineObject` | Define custom objects with fields |
-| `defineField` | Extend existing objects with additional fields or define standalone relation fields |
 | `defineLogicFunction` | Define logic functions with handlers |
 | `definePreInstallLogicFunction` | Define a pre-install logic function (one per app) |
 | `definePostInstallLogicFunction` | Define a post-install logic function (one per app) |
 | `defineFrontComponent` | Define front components for custom UI |
 | `defineRole` | Configure role permissions and object access |
+| `defineField` | Extend existing objects with additional fields |
 | `defineView` | Define saved views for objects |
 | `defineNavigationMenuItem` | Define sidebar navigation links |
 | `defineSkill` | Define AI agent skills |
-| `defineAgent` | Define AI agents |
-| `definePageLayout` | Define custom page layouts |

 These functions validate your configuration at build time and provide IDE autocompletion and type safety.

@@ -38,7 +36,7 @@ These functions validate your configuration at build time and provide IDE autoco
 Custom objects describe both schema and behavior for records in your workspace. Use `defineObject()` to define objects with built-in validation:

 ```typescript
-// src/objects/postCard.object.ts
+// src/app/postCard.object.ts
 import { defineObject, FieldType } from 'twenty-sdk';

 enum PostCardStatus {
@@ -112,7 +110,7 @@ Key points:
 - The `universalIdentifier` must be unique and stable across deployments.
 - Each field requires a `name`, `type`, `label`, and its own stable `universalIdentifier`.
 - The `fields` array is optional — you can define objects without custom fields.
- You can scaffold new objects using `yarn twenty add`, which guides you through naming, fields, and relationships.
+- You can scaffold new objects using `yarn twenty entity:add`, which guides you through naming, fields, and relationships.

 <Note>
 **Base fields are created automatically.** When you define a custom object, Twenty automatically adds standard fields
@@ -122,195 +120,6 @@ Key points:
  but this is not recommended.
 </Note>

-### Defining fields on existing objects
-
-Use `defineField()` to add fields to objects you don't own — such as standard Twenty objects (Person, Company, etc.) or objects from other apps. Unlike inline fields in `defineObject()`, standalone fields require an `objectUniversalIdentifier` to specify which object they extend:
-
-```typescript
-// src/fields/company-loyalty-tier.field.ts
-import { defineField, FieldType } from 'twenty-sdk';
-
-export default defineField({
-  universalIdentifier: 'f2a1b3c4-d5e6-7890-abcd-ef1234567890',
-  objectUniversalIdentifier: '701aecb9-eb1c-4d84-9d94-b954b231b64b', // Company object
-  name: 'loyaltyTier',
-  type: FieldType.SELECT,
-  label: 'Loyalty Tier',
-  icon: 'IconStar',
-  options: [
-    { value: 'BRONZE', label: 'Bronze', position: 0, color: 'orange' },
-    { value: 'SILVER', label: 'Silver', position: 1, color: 'gray' },
-    { value: 'GOLD', label: 'Gold', position: 2, color: 'yellow' },
-  ],
-});
-```
-
-Key points:
- `objectUniversalIdentifier` identifies the target object. For standard objects, use `STANDARD_OBJECT_UNIVERSAL_IDENTIFIERS` exported from `twenty-sdk`.
- When defining fields inline in `defineObject()`, you do **not** need `objectUniversalIdentifier` — it's inherited from the parent object.
- `defineField()` is the only way to add fields to objects you didn't create with `defineObject()`.
-
-### Relations
-
-Relations connect objects together. In Twenty, relations are always **bidirectional** — you define both sides, and each side references the other.
-
-There are two relation types:
-
-| Relation type | Description | Has foreign key? |
-|---------------|-------------|-----------------|
-| `MANY_TO_ONE` | Many records of this object point to one record of the target | Yes (`joinColumnName`) |
-| `ONE_TO_MANY` | One record of this object has many records of the target | No (inverse side) |
-
-#### How relations work
-
-Every relation requires **two fields** that reference each other:
-
-1. The **MANY_TO_ONE** side — lives on the object that holds the foreign key
-2. The **ONE_TO_MANY** side — lives on the object that owns the collection
-
-Both fields use `FieldType.RELATION` and cross-reference each other via `relationTargetFieldMetadataUniversalIdentifier`.
-
-#### Example: Post Card has many Recipients
-
-Suppose a `PostCard` can be sent to many `PostCardRecipient` records. Each recipient belongs to exactly one post card.
-
-**Step 1: Define the ONE_TO_MANY side on PostCard** (the "one" side):
-
-```typescript
-// src/fields/post-card-recipients-on-post-card.field.ts
-import { defineField, FieldType, RelationType } from 'twenty-sdk';
-import { POST_CARD_UNIVERSAL_IDENTIFIER } from '../objects/post-card.object';
-import { POST_CARD_RECIPIENT_UNIVERSAL_IDENTIFIER } from '../objects/post-card-recipient.object';
-
-// Export so the other side can reference it
-export const POST_CARD_RECIPIENTS_FIELD_ID = 'a1111111-1111-1111-1111-111111111111';
-// Import from the other side
-import { POST_CARD_FIELD_ID } from './post-card-on-post-card-recipient.field';
-
-export default defineField({
-  universalIdentifier: POST_CARD_RECIPIENTS_FIELD_ID,
-  objectUniversalIdentifier: POST_CARD_UNIVERSAL_IDENTIFIER,
-  type: FieldType.RELATION,
-  name: 'postCardRecipients',
-  label: 'Post Card Recipients',
-  icon: 'IconUsers',
-  relationTargetObjectMetadataUniversalIdentifier: POST_CARD_RECIPIENT_UNIVERSAL_IDENTIFIER,
-  relationTargetFieldMetadataUniversalIdentifier: POST_CARD_FIELD_ID,
-  universalSettings: {
-    relationType: RelationType.ONE_TO_MANY,
-  },
-});
-```
-
-**Step 2: Define the MANY_TO_ONE side on PostCardRecipient** (the "many" side — holds the foreign key):
-
-```typescript
-// src/fields/post-card-on-post-card-recipient.field.ts
-import { defineField, FieldType, RelationType, OnDeleteAction } from 'twenty-sdk';
-import { POST_CARD_UNIVERSAL_IDENTIFIER } from '../objects/post-card.object';
-import { POST_CARD_RECIPIENT_UNIVERSAL_IDENTIFIER } from '../objects/post-card-recipient.object';
-
-// Export so the other side can reference it
-export const POST_CARD_FIELD_ID = 'b2222222-2222-2222-2222-222222222222';
-// Import from the other side
-import { POST_CARD_RECIPIENTS_FIELD_ID } from './post-card-recipients-on-post-card.field';
-
-export default defineField({
-  universalIdentifier: POST_CARD_FIELD_ID,
-  objectUniversalIdentifier: POST_CARD_RECIPIENT_UNIVERSAL_IDENTIFIER,
-  type: FieldType.RELATION,
-  name: 'postCard',
-  label: 'Post Card',
-  icon: 'IconMail',
-  relationTargetObjectMetadataUniversalIdentifier: POST_CARD_UNIVERSAL_IDENTIFIER,
-  relationTargetFieldMetadataUniversalIdentifier: POST_CARD_RECIPIENTS_FIELD_ID,
-  universalSettings: {
-    relationType: RelationType.MANY_TO_ONE,
-    onDelete: OnDeleteAction.CASCADE,
-    joinColumnName: 'postCardId',
-  },
-});
-```
-
-<Note>
-**Circular imports:** Both relation fields reference each other's `universalIdentifier`. To avoid circular import issues, export your field IDs as named constants from each file, and import them in the other file. The build system resolves these at compile time.
-</Note>
-
-#### Relating to standard objects
-
-To create a relation with a built-in Twenty object (Person, Company, etc.), use `STANDARD_OBJECT_UNIVERSAL_IDENTIFIERS`:
-
-```typescript
-// src/fields/person-on-self-hosting-user.field.ts
-import {
-  defineField,
-  FieldType,
-  RelationType,
-  OnDeleteAction,
-  STANDARD_OBJECT_UNIVERSAL_IDENTIFIERS,
-} from 'twenty-sdk';
-import { SELF_HOSTING_USER_UNIVERSAL_IDENTIFIER } from '../objects/self-hosting-user.object';
-
-export const PERSON_FIELD_ID = 'c3333333-3333-3333-3333-333333333333';
-export const SELF_HOSTING_USER_REVERSE_FIELD_ID = 'd4444444-4444-4444-4444-444444444444';
-
-export default defineField({
-  universalIdentifier: PERSON_FIELD_ID,
-  objectUniversalIdentifier: SELF_HOSTING_USER_UNIVERSAL_IDENTIFIER,
-  type: FieldType.RELATION,
-  name: 'person',
-  label: 'Person',
-  description: 'Person matching with the self hosting user',
-  isNullable: true,
-  relationTargetObjectMetadataUniversalIdentifier:
-    STANDARD_OBJECT_UNIVERSAL_IDENTIFIERS.person.universalIdentifier,
-  relationTargetFieldMetadataUniversalIdentifier: SELF_HOSTING_USER_REVERSE_FIELD_ID,
-  universalSettings: {
-    relationType: RelationType.MANY_TO_ONE,
-    onDelete: OnDeleteAction.SET_NULL,
-    joinColumnName: 'personId',
-  },
-});
-```
-
-#### Relation field properties
-
-| Property | Required | Description |
-|----------|----------|-------------|
-| `type` | Yes | Must be `FieldType.RELATION` |
-| `relationTargetObjectMetadataUniversalIdentifier` | Yes | The `universalIdentifier` of the target object |
-| `relationTargetFieldMetadataUniversalIdentifier` | Yes | The `universalIdentifier` of the matching field on the target object |
-| `universalSettings.relationType` | Yes | `RelationType.MANY_TO_ONE` or `RelationType.ONE_TO_MANY` |
-| `universalSettings.onDelete` | MANY_TO_ONE only | What happens when the referenced record is deleted: `CASCADE`, `SET_NULL`, `RESTRICT`, or `NO_ACTION` |
-| `universalSettings.joinColumnName` | MANY_TO_ONE only | Database column name for the foreign key (e.g., `postCardId`) |
-
-#### Inline relation fields in defineObject
-
-You can also define relation fields directly inside `defineObject()`. In that case, omit `objectUniversalIdentifier` — it's inherited from the parent object:
-
-```typescript
-export default defineObject({
-  universalIdentifier: '...',
-  nameSingular: 'postCardRecipient',
-  // ...
-  fields: [
-    {
-      universalIdentifier: POST_CARD_FIELD_ID,
-      type: FieldType.RELATION,
-      name: 'postCard',
-      label: 'Post Card',
-      relationTargetObjectMetadataUniversalIdentifier: POST_CARD_UNIVERSAL_IDENTIFIER,
-      relationTargetFieldMetadataUniversalIdentifier: POST_CARD_RECIPIENTS_FIELD_ID,
-      universalSettings: {
-        relationType: RelationType.MANY_TO_ONE,
-        onDelete: OnDeleteAction.CASCADE,
-        joinColumnName: 'postCardId',
-      },
-    },
-    // ... other fields
-  ],
-});
-```

 ### Application config (application-config.ts)

@@ -352,29 +161,13 @@ Notes:
 - `defaultRoleUniversalIdentifier` must match the role file (see below).
 - Pre-install and post-install functions are automatically detected during the manifest build. See [Pre-install functions](#pre-install-functions) and [Post-install functions](#post-install-functions).

-#### Marketplace metadata
-
-If you plan to [publish your app](/developers/extend/apps/publishing), these optional fields control how your app appears in the marketplace:
-
-| Field | Description |
-|-------|-------------|
-| `author` | Author or company name |
-| `category` | App category for marketplace filtering |
-| `logoUrl` | Path to your app logo (relative to `./assets/`) |
-| `screenshots` | Array of screenshot paths (relative to `./assets/`) |
-| `aboutDescription` | Longer markdown description for the "About" tab |
-| `websiteUrl` | Link to your website |
-| `termsUrl` | Link to terms of service |
-| `emailSupport` | Support email address |
-| `issueReportUrl` | Link to issue tracker |
-
 #### Roles and permissions

 Applications can define roles that encapsulate permissions on your workspace's objects and actions. The field `defaultRoleUniversalIdentifier` in `application-config.ts` designates the default role used by your app's logic functions.

 - The runtime API key injected as `TWENTY_API_KEY` is derived from this default function role.
 - The typed client will be restricted to the permissions granted to that role.
- Follow least-privilege: create a dedicated role with only the permissions your functions need, then reference its universal identifier.
+- Follow least‑privilege: create a dedicated role with only the permissions your functions need, then reference its universal identifier.

 ##### Default function role (*.role.ts)

@@ -426,7 +219,7 @@ The `universalIdentifier` of this role is then referenced in `application-config
 - **application-config.ts** points to that role so your functions inherit its permissions.

 Notes:
- Start from the scaffolded role, then progressively restrict it following least-privilege.
+- Start from the scaffolded role, then progressively restrict it following least‑privilege.
 - Replace the `objectPermissions` and `fieldPermissions` with the objects/fields your functions need.
 - `permissionFlags` control access to platform-level capabilities. Keep them minimal; add only what you need.
 - See a working example in the Hello World app: [`packages/twenty-apps/hello-world/src/roles/function-role.ts`](https://github.com/twentyhq/twenty/blob/main/packages/twenty-apps/hello-world/src/roles/function-role.ts).
@@ -436,7 +229,7 @@ Notes:
 Each function file uses `defineLogicFunction()` to export a configuration with a handler and optional triggers.

 ```typescript
-// src/logic-functions/createPostCard.logic-function.ts
+// 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';
@@ -525,7 +318,7 @@ export default definePreInstallLogicFunction({
 You can also manually execute the pre-install function at any time using the CLI:

 ```bash filename="Terminal"
-yarn twenty exec --preInstall
+yarn twenty function:execute --preInstall
 ```

 Key points:
@@ -534,7 +327,7 @@ Key points:
 - Only one pre-install function is allowed per application. The manifest build will error if more than one is detected.
 - The function's `universalIdentifier` is automatically set as `preInstallLogicFunctionUniversalIdentifier` on the application manifest during the build — you do not need to reference it in `defineApplication()`.
 - The default timeout is set to 300 seconds (5 minutes) to allow for longer preparation tasks.
- Pre-install functions do not need triggers — they are invoked by the platform before installation or manually via `exec --preInstall`.
+- Pre-install functions do not need triggers — they are invoked by the platform before installation or manually via `function:execute --preInstall`.

 ### Post-install functions

@@ -562,7 +355,7 @@ export default definePostInstallLogicFunction({
 You can also manually execute the post-install function at any time using the CLI:

 ```bash filename="Terminal"
-yarn twenty exec --postInstall
+yarn twenty function:execute --postInstall
 ```

 Key points:
@@ -571,7 +364,7 @@ Key points:
 - Only one post-install function is allowed per application. The manifest build will error if more than one is detected.
 - The function's `universalIdentifier` is automatically set as `postInstallLogicFunctionUniversalIdentifier` on the application manifest during the build — you do not need to reference it in `defineApplication()`.
 - The default timeout is set to 300 seconds (5 minutes) to allow for longer setup tasks like data seeding.
- Post-install functions do not need triggers — they are invoked by the platform during installation or manually via `exec --postInstall`.
+- Post-install functions do not need triggers — they are invoked by the platform during installation or manually via `function:execute --postInstall`.

 ### Route trigger payload

@@ -619,7 +412,7 @@ The `RoutePayload` type has the following structure:
 |----------|------|-------------|
 | `headers` | `Record<string, string \| undefined>` | HTTP headers (only those listed in `forwardedRequestHeaders`) |
 | `queryStringParameters` | `Record<string, string \| undefined>` | Query string parameters (multiple values joined with commas) |
-| `pathParameters` | `Record<string, string \| undefined>` | Path parameters extracted from the route pattern (e.g., `/users/:id` -> `{ id: '123' }`) |
+| `pathParameters` | `Record<string, string \| undefined>` | Path parameters extracted from the route pattern (e.g., `/users/:id` → `{ id: '123' }`) |
 | `body` | `object \| null` | Parsed request body (JSON) |
 | `isBase64Encoded` | `boolean` | Whether the body is base64 encoded |
 | `requestContext.http.method` | `string` | HTTP method (GET, POST, PUT, PATCH, DELETE) |
@@ -665,7 +458,7 @@ const handler = async (event: RoutePayload) => {

 You can create new functions in two ways:

- **Scaffolded**: Run `yarn twenty add` and choose the option to add a new logic function. This generates a starter file with a handler and config.
+- **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
@@ -677,7 +470,7 @@ To mark a logic function as a tool, set `isTool: true` and provide a `toolInputS
 ```typescript
 // src/logic-functions/enrich-company.logic-function.ts
 import { defineLogicFunction } from 'twenty-sdk';
-import { CoreApiClient } from 'twenty-client-sdk/core';
+import { CoreApiClient } from 'twenty-sdk/generated';

 const handler = async (params: { companyName: string; domain?: string }) => {
  const client = new CoreApiClient();
@@ -765,7 +558,7 @@ Key points:

 You can create new front components in two ways:

- **Scaffolded**: Run `yarn twenty add` and choose the option to add a new front component.
+- **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
@@ -799,122 +592,46 @@ Key points:

 You can create new skills in two ways:

- **Scaffolded**: Run `yarn twenty add` and choose the option to add a new skill.
+- **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.

-### Typed API clients (`twenty-client-sdk`)
+### Generated typed clients

-The `twenty-client-sdk` package provides two typed GraphQL clients for interacting with the Twenty API from your logic functions and front components:
+Two typed clients are auto-generated by `yarn twenty dev` and stored in `node_modules/twenty-sdk/generated` based on your workspace schema:

-| Client | Import | Endpoint | Generated? |
-|--------|--------|----------|------------|
-| `CoreApiClient` | `twenty-client-sdk/core` | `/graphql` — workspace data (records, objects) | Yes, at dev/build time |
-| `MetadataApiClient` | `twenty-client-sdk/metadata` | `/metadata` — workspace config, file uploads | No, ships pre-built |
-
-#### CoreApiClient
-
-`CoreApiClient` is the main client for querying and mutating workspace data. It is **generated from your workspace schema** during `yarn twenty dev` or `yarn twenty build`, so it's fully typed to match your objects and fields.
+- **`CoreApiClient`** — queries the `/graphql` endpoint for workspace data
+- **`MetadataApiClient`** — queries the `/metadata` endpoint for workspace configuration and file uploads

 ```typescript
-import { CoreApiClient } from 'twenty-client-sdk/core';
+import { CoreApiClient, MetadataApiClient } from 'twenty-sdk/generated';

 const client = new CoreApiClient();
-
-// Query records
-const { companies } = await client.query({
-  companies: {
-    edges: {
-      node: {
-        id: true,
-        name: true,
-        domainName: true,
-      },
-    },
-  },
-});
-
-// Create a record
-const { createCompany } = await client.mutation({
-  createCompany: {
-    __args: {
-      data: {
-        name: 'Acme Corp',
-      },
-    },
-    id: true,
-    name: true,
-  },
-});
-```
-
-The client uses a selection-set syntax: pass `true` to include a field, use `__args` for arguments, and nest objects for relations. You get full autocompletion and type checking based on your workspace schema.
-
-<Note>
-**CoreApiClient is generated at dev/build time.** If you try to use it without running `yarn twenty dev` or `yarn twenty build` first, it throws an error. The generation happens automatically — the CLI introspects your workspace's GraphQL schema, generates a typed client using `@genql/cli`, writes the generated sources to `node_modules/twenty-client-sdk/dist/core/generated/`, and replaces the stubs in `node_modules/twenty-client-sdk/dist/core.mjs` and `node_modules/twenty-client-sdk/dist/core.cjs`.
-</Note>
-
-#### Using CoreSchema for type annotations
-
-`CoreSchema` provides TypeScript types matching your workspace objects, useful for typing component state or function parameters:
-
-```typescript
-import { CoreApiClient, CoreSchema } from 'twenty-client-sdk/core';
-import { useState } from 'react';
-
-const [company, setCompany] = useState<
-  Pick<CoreSchema.Company, 'id' | 'name'> | undefined
->(undefined);
-
-const client = new CoreApiClient();
-const result = await client.query({
-  company: {
-    __args: { filter: { position: { eq: 1 } } },
-    id: true,
-    name: true,
-  },
-});
-setCompany(result.company);
-```
-
-#### MetadataApiClient
-
-`MetadataApiClient` ships pre-built with the SDK (no generation required). It queries the `/metadata` endpoint for workspace configuration, applications, and file uploads:
-
-```typescript
-import { MetadataApiClient } from 'twenty-client-sdk/metadata';
+const { me } = await client.query({ me: { id: true, displayName: true } });

 const metadataClient = new MetadataApiClient();
-
-// Query workspace info
-const { currentWorkspace } = await metadataClient.query({
-  currentWorkspace: { id: true, displayName: true },
-});
-
-// List installed applications
-const { findManyApplications } = await metadataClient.query({
-  findManyApplications: {
-    id: true,
-    name: true,
-    version: true,
-  },
-});
+const { currentWorkspace } = await metadataClient.query({ currentWorkspace: { id: true } });
 ```

-#### Runtime credentials
+Both clients are re-generated automatically by `yarn twenty dev` whenever your objects or fields change.

-When your code runs on Twenty (logic functions or front components), the platform injects credentials as environment variables:
+#### Runtime credentials in logic functions

- `TWENTY_API_URL` — Base URL of the Twenty API
- `TWENTY_API_KEY` — Short-lived key scoped to your application's default function role
+When your function runs on Twenty, the platform injects credentials as environment variables before your code executes:

-You do **not** need to pass these to the clients — they read from `process.env` automatically. The API key's permissions are determined by the role referenced in `defaultRoleUniversalIdentifier` in your `application-config.ts`.
+- `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

-`MetadataApiClient` includes an `uploadFile` method for attaching files to file-type fields. It implements the [GraphQL multipart request specification](https://github.com/jaydenseric/graphql-multipart-request-spec):
+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-client-sdk/metadata';
+import { MetadataApiClient } from 'twenty-sdk/generated';
 import * as fs from 'fs';

 const metadataClient = new MetadataApiClient();
@@ -924,14 +641,25 @@ const fileBuffer = fs.readFileSync('./invoice.pdf');
 const uploadedFile = await metadataClient.uploadFile(
  fileBuffer,                                         // file contents as a Buffer
  'invoice.pdf',                                      // filename
-  'application/pdf',                                  // MIME type
-  '58a0a314-d7ea-4865-9850-7fb84e72f30b',            // field universalIdentifier
+  '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 |
@@ -940,7 +668,8 @@ console.log(uploadedFile);
 | `fieldMetadataUniversalIdentifier` | `string` | The `universalIdentifier` of the file-type field on your object |

 Key points:
- Uses the field's `universalIdentifier` (not its workspace-specific ID), so your upload code works across any workspace where your app is installed.
+- The `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
@@ -48,7 +48,7 @@ From here you can:

 ```bash filename="Terminal"
 # Add a new entity to your application (guided)
-yarn twenty add
+yarn twenty entity:add

 # Watch your application's function logs
 yarn twenty function:logs
@@ -122,7 +122,7 @@ With `--minimal`, only the core files are created (`application-config.ts`, `rol
 At a high level:

 - **package.json**: Declares the app name, version, engines (Node 24+, Yarn 4), and adds `twenty-sdk` plus a `twenty` script that delegates to the local `twenty` CLI. Run `yarn twenty help` to list all available commands.
- **.gitignore**: Ignores common artifacts such as `node_modules`, `.yarn`, `.twenty/`, `dist/`, `build/`, coverage folders, log files, and `.env*` files.
+- **.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.
@@ -165,8 +165,8 @@ export default defineObject({

 Later commands will add more files and folders:

- `yarn twenty dev` will auto-generate the typed `CoreApiClient` (for workspace data via `/graphql`) into `node_modules/twenty-client-sdk/`. The `MetadataApiClient` (for workspace configuration and file uploads via `/metadata`) ships pre-built and is available immediately. Import them from `twenty-client-sdk/core` and `twenty-client-sdk/metadata` respectively.
- `yarn twenty add` will add entity definition files under `src/` for your custom objects, functions, front components, roles, skills, and more.
+- `yarn twenty 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

@@ -12,25 +12,7 @@ Apps are currently in alpha testing. The feature is functional but still evolvin
 Once your app is [built and tested locally](/developers/extend/apps/building), you have two paths for distributing it:

 - **Publish to npm** — list your app in the Twenty marketplace for any workspace to discover and install.
- **Deploy a tarball** — upload your app directly to a specific Twenty server for internal or private use.
-
-Both paths start from the same **build** step.
-
-## Building your app
-
-The `build` command compiles your TypeScript sources, transpiles logic functions and front components, and generates a `manifest.json` that describes your app's contents:
-
-```bash filename="Terminal"
-yarn twenty build
-```
-
-The output is written to `.twenty/output/`. This directory contains everything needed for distribution: compiled code, assets, the manifest, and a copy of your `package.json`.
-
-To also create a `.tgz` tarball (used by the deploy command internally, or for manual distribution):
-
-```bash filename="Terminal"
-yarn twenty build --tarball
-```
+- **Push a tarball** — deploy your app to a specific Twenty server for internal use without making it publicly available.

 ## Publishing to npm

@@ -39,72 +21,29 @@ Publishing to npm makes your app discoverable in the Twenty marketplace. Any Twe
 ### Requirements

 - An [npm](https://www.npmjs.com) account
- The `twenty-app` keyword **must** be listed in your `package.json` `keywords` array
-
-### Adding the required keyword
-
-The Twenty marketplace discovers apps by searching the npm registry for packages with the `twenty-app` keyword. Add it to your `package.json`:
-
-```json filename="package.json"
-{
-  "name": "twenty-app-postcard-sender",
-  "version": "1.0.0",
-  "keywords": ["twenty-app"],
-  ...
-}
-```
-
-<Note>
-The marketplace searches for `keywords:twenty-app` on the npm registry. Without this keyword, your package won't appear in the marketplace even if it has the `twenty-app-` name prefix.
-</Note>
+- Your package name **must** use the `twenty-app-` prefix (e.g., `twenty-app-postcard-sender`)

 ### Steps

-1. **Build your app:**
+1. **Build your app** — the CLI compiles your TypeScript sources and generates the application manifest:

 ```bash filename="Terminal"
 yarn twenty build
 ```

-2. **Publish to npm:**
+2. **Publish to npm** — push the built package to the npm registry:

 ```bash filename="Terminal"
-yarn twenty publish
+npx twenty publish
 ```

-This runs `npm publish` from the `.twenty/output/` directory.
+### Auto-discovery

-To publish under a specific dist-tag (e.g., `beta` or `next`):
-
-```bash filename="Terminal"
-yarn twenty publish --tag beta
-```
-
-### How marketplace discovery works
-
-The Twenty server syncs its marketplace catalog from the npm registry **every hour**:
-
-1. It searches for all npm packages with the `keywords:twenty-app` keyword
-2. For each package, it fetches the `manifest.json` from the npm CDN
-3. The app's metadata (name, description, author, logo, screenshots, category) is extracted from the manifest and displayed in the marketplace
-
-After publishing, your app can take up to one hour to appear in the marketplace. To trigger the sync immediately instead of waiting for the next hourly run:
-
-```bash filename="Terminal"
-yarn twenty catalog-sync
-```
-
-To target a specific remote:
-
-```bash filename="Terminal"
-yarn twenty catalog-sync -r production
-```
-
-The metadata shown in the marketplace comes from your `defineApplication()` call in your app source code — fields like `displayName`, `description`, `author`, `category`, `logoUrl`, `screenshots`, `aboutDescription`, `websiteUrl`, and `termsUrl`.
+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:
+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
@@ -133,117 +72,48 @@ jobs:
          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
 ```

-For other CI systems (GitLab CI, CircleCI, etc.), the same three commands apply: `yarn install`, `yarn twenty build`, then `npm publish` from `.twenty/output`.
+For other CI systems (GitLab CI, CircleCI, etc.), the same three commands apply: `yarn install`, `npx twenty build`, then `npm publish` from `.twenty/output`.

 <Tip>
 **npm provenance** is optional but recommended. Publishing with `--provenance` adds a trust badge to your npm listing, letting users verify the package was built from a specific commit in a public CI pipeline. See the [npm provenance docs](https://docs.npmjs.com/generating-provenance-statements) for setup instructions.
 </Tip>

-## Deploying to a server (tarball)
+## Internal distribution

-For apps you don't want publicly available — proprietary tools, enterprise-only integrations, or experimental builds — you can deploy a tarball directly to a Twenty server.
+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.

-### Prerequisites
+### Push a tarball

-Before deploying, you need a configured remote pointing to the target server. Remotes store the server URL and authentication credentials locally in `~/.twenty/config.json`.
-
-Add a remote:
+Build your app and deploy it to a specific server in one step:

 ```bash filename="Terminal"
-yarn twenty remote add --url https://your-twenty-server.com --as production
+npx twenty publish --server <server-url>
 ```

-For a local development server:
-
-```bash filename="Terminal"
-yarn twenty remote add --local --as local
-```
-
-You can also authenticate with an API key for non-interactive environments:
-
-```bash filename="Terminal"
-yarn twenty remote add --url https://your-twenty-server.com --token <api-key> --as production
-```
-
-Manage your remotes:
-
-```bash filename="Terminal"
-yarn twenty remote list       # List all configured remotes
-yarn twenty remote switch prod # Set the default remote
-yarn twenty remote status     # Show active remote and auth status
-yarn twenty remote remove old # Remove a remote
-```
-
-### Deploying
-
-Build and upload your app to the server in one step:
-
-```bash filename="Terminal"
-yarn twenty deploy
-```
-
-This builds the app with `--tarball`, then uploads the tarball to the default remote via a GraphQL multipart upload.
-
-To deploy to a specific remote:
-
-```bash filename="Terminal"
-yarn twenty deploy -r production
-```
-
-### Sharing a deployed app
-
-Tarball apps are not listed in the public marketplace, so other workspaces on the same server won't discover them by browsing. To share a deployed app:
-
-1. Go to **Settings > Applications > Registrations** and open your app
-2. In the **Distribution** tab, click **Copy share link**
-3. Share this link with users on other workspaces — it takes them directly to the app's install page
-
-The share link uses the server's base URL (without any workspace subdomain) so it works for any workspace on the server.
+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. Run `yarn twenty deploy` (or `yarn twenty deploy -r production`)
-3. Workspaces that have the app installed will see the upgrade available in their settings
+2. Push a new tarball with `npx twenty publish --server <server-url>`
+3. Workspaces on that server will see the upgrade available in their settings

-## Installing apps
+<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>

-Once an app is published (npm) or deployed (tarball), workspaces install it through the UI:
-
-```bash filename="Terminal"
-yarn twenty install
-```
-
-Or from the **Settings > Applications** page in the Twenty UI, where both marketplace and tarball-deployed apps can be browsed and installed.
-
-## App distribution categories
+## 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 dev`. Used for building and testing. | No |
-| **Published (npm)** | Apps published to npm with the `twenty-app` keyword. Listed in the marketplace for any workspace to install. | Yes |
-| **Internal (tarball)** | Apps deployed via tarball to a specific server. Available only to workspaces on that server via a share link. | No |
+| **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>
-
-## CLI reference
-
-| Command | Description | Key flags |
-|---------|-------------|-----------|
-| `yarn twenty build` | Compile app and generate manifest | `--tarball` — also create a `.tgz` package |
-| `yarn twenty publish` | Build and publish to npm | `--tag <tag>` — npm dist-tag (e.g., `beta`, `next`) |
-| `yarn twenty deploy` | Build and upload tarball to a server | `-r, --remote <name>` — target remote |
-| `yarn twenty catalog-sync` | Trigger marketplace catalog sync on the server | `-r, --remote <name>` — target remote |
-| `yarn twenty install` | Install a deployed app on a workspace | `-r, --remote <name>` — target remote |
-| `yarn twenty dev` | Watch and sync local changes | Uses default remote |
-| `yarn twenty remote add` | Add a server connection | `--url`, `--token`, `--as`, `--local`, `--port` |
-| `yarn twenty remote list` | List configured remotes | — |
-| `yarn twenty remote switch` | Set default remote | — |
-| `yarn twenty remote status` | Show connection status | — |
-| `yarn twenty remote remove` | Remove a remote | — |
@@ -15,21 +15,19 @@ description: عرّف الكائنات، والدوال المنطقية، وم

 يوفّر SDK دوالًا مساعدة لتعريف كيانات تطبيقك. كما هو موضح في [اكتشاف الكيانات](/l/ar/developers/extend/apps/getting-started#entity-detection)، يجب استخدام `export default define<Entity>({...})` كي يتم اكتشاف كياناتك:

-| دالة                             | الغرض                                                          |
-| -------------------------------- | -------------------------------------------------------------- |
-| `defineApplication`              | تهيئة بيانات التعريف للتطبيق (مطلوب، واحد لكل تطبيق)           |
-| `defineObject`                   | تعريف كائنات مخصصة مع حقول                                     |
-| `defineField`                    | وسّع الكائنات الموجودة بحقول إضافية أو عرّف حقول علاقات مستقلة |
-| `defineLogicFunction`            | تعريف وظائف منطقية مع معالجات                                  |
-| `definePreInstallLogicFunction`  | تعريف دالة منطقية لما قبل التثبيت (واحدة لكل تطبيق)            |
-| `definePostInstallLogicFunction` | تعريف دالة منطقية لما بعد التثبيت (واحدة لكل تطبيق)            |
-| `defineFrontComponent`           | عرِّف مكوّنات أمامية لواجهة مستخدم مخصّصة                      |
-| `defineRole`                     | تهيئة صلاحيات الدور والوصول إلى الكائنات                       |
-| `defineView`                     | تعريف العروض المحفوظة للكائنات                                 |
-| `defineNavigationMenuItem`       | تعريف روابط التنقل في الشريط الجانبي                           |
-| `defineSkill`                    | عرّف مهارات وكيل الذكاء الاصطناعي                              |
-| `defineAgent`                    | عرّف وكلاء الذكاء الاصطناعي                                    |
-| `definePageLayout`               | عرّف تخطيطات صفحات مخصّصة                                      |
+| دالة                             | الغرض                                                |
+| -------------------------------- | ---------------------------------------------------- |
+| `defineApplication`              | تهيئة بيانات التعريف للتطبيق (مطلوب، واحد لكل تطبيق) |
+| `defineObject`                   | تعريف كائنات مخصصة مع حقول                           |
+| `defineLogicFunction`            | تعريف وظائف منطقية مع معالجات                        |
+| `definePreInstallLogicFunction`  | تعريف دالة منطقية لما قبل التثبيت (واحدة لكل تطبيق)  |
+| `definePostInstallLogicFunction` | تعريف دالة منطقية لما بعد التثبيت (واحدة لكل تطبيق)  |
+| `defineFrontComponent`           | عرِّف مكوّنات أمامية لواجهة مستخدم مخصّصة            |
+| `defineRole`                     | تهيئة صلاحيات الدور والوصول إلى الكائنات             |
+| `defineField`                    | وسّع الكائنات الموجودة بحقول إضافية                  |
+| `defineView`                     | تعريف العروض المحفوظة للكائنات                       |
+| `defineNavigationMenuItem`       | تعريف روابط التنقل في الشريط الجانبي                 |
+| `defineSkill`                    | عرّف مهارات وكيل الذكاء الاصطناعي                    |

 تتحقق هذه الدوال من تكوينك وقت البناء وتوفّر إكمالًا تلقائيًا في بيئة التطوير وأمان الأنواع.

@@ -38,7 +36,7 @@ description: عرّف الكائنات، والدوال المنطقية، وم
 تصف الكائنات المخصصة كلًا من المخطط والسلوك للسجلات في مساحة عملك. استخدم `defineObject()` لتعريف كائنات مع تحقق مدمج:

 ```typescript
-// src/objects/postCard.object.ts
+// src/app/postCard.object.ts
 import { defineObject, FieldType } from 'twenty-sdk';

 enum PostCardStatus {
@@ -112,7 +110,7 @@ export default defineObject({
 * `universalIdentifier` يجب أن يكون فريدًا وثابتًا عبر عمليات النشر.
 * يتطلب كل حقل `name` و`type` و`label` ومعرّف `universalIdentifier` ثابتًا خاصًا به.
 * المصفوفة `fields` اختيارية — يمكنك تعريف كائنات بدون حقول مخصصة.
-* يمكنك إنشاء كائنات جديدة باستخدام `yarn twenty add`، والذي يرشدك خلال التسمية والحقول والعلاقات.
+* يمكنك إنشاء كائنات جديدة باستخدام `yarn twenty entity:add`، والذي يرشدك خلال التسمية والحقول والعلاقات.

 <Note>
 **يتم إنشاء الحقول الأساسية تلقائيًا.** عند تعريف كائن مخصص، يضيف Twenty تلقائيًا حقولًا قياسية
@@ -122,197 +120,6 @@ export default defineObject({
 لكن هذا غير مستحسن.
 </Note>

-### تعريف الحقول على الكائنات الموجودة
-
-استخدم `defineField()` لإضافة حقول إلى كائنات لا تملكها — مثل كائنات Twenty القياسية (Person, Company, etc.) أو كائنات من تطبيقات أخرى. على خلاف الحقول المضمّنة في `defineObject()`، تتطلّب الحقول المستقلة `objectUniversalIdentifier` لتحديد الكائن الذي تقوم بتوسيعه:
-
-```typescript
-// src/fields/company-loyalty-tier.field.ts
-import { defineField, FieldType } from 'twenty-sdk';
-
-export default defineField({
-  universalIdentifier: 'f2a1b3c4-d5e6-7890-abcd-ef1234567890',
-  objectUniversalIdentifier: '701aecb9-eb1c-4d84-9d94-b954b231b64b', // Company object
-  name: 'loyaltyTier',
-  type: FieldType.SELECT,
-  label: 'Loyalty Tier',
-  icon: 'IconStar',
-  options: [
-    { value: 'BRONZE', label: 'Bronze', position: 0, color: 'orange' },
-    { value: 'SILVER', label: 'Silver', position: 1, color: 'gray' },
-    { value: 'GOLD', label: 'Gold', position: 2, color: 'yellow' },
-  ],
-});
-```
-
-النقاط الرئيسية:
-
-* `objectUniversalIdentifier` يحدّد الكائن الهدف. بالنسبة للكائنات القياسية، استخدم `STANDARD_OBJECT_UNIVERSAL_IDENTIFIERS` المُصدَّر من `twenty-sdk`.
-* عند تعريف الحقول بشكل مضمّن في `defineObject()`، **لا** تحتاج إلى `objectUniversalIdentifier` — إذ يُورَّث من الكائن الأب.
-* `defineField()` هي الطريقة الوحيدة لإضافة حقول إلى كائنات لم تُنشئها باستخدام `defineObject()`.
-
-### العلاقات
-
-تربط العلاقات الكائنات معًا. في Twenty، تكون العلاقات دائمًا **ثنائية الاتجاه** — حيث تعرّف الجانبين، ويشير كل جانب إلى الآخر.
-
-هناك نوعان من العلاقات:
-
-| نوع العلاقة   | الوصف                                                  | هل لديه مفتاح خارجي؟   |
-| ------------- | ------------------------------------------------------ | ---------------------- |
-| `MANY_TO_ONE` | تشير العديد من سجلات هذا الكائن إلى سجل واحد من الهدف  | نعم (`joinColumnName`) |
-| `ONE_TO_MANY` | يحتوي سجل واحد من هذا الكائن على العديد من سجلات الهدف | لا (الجانب العكسي)     |
-
-#### كيف تعمل العلاقات
-
-تتطلّب كل علاقة **حقلين** يشيران إلى بعضهما البعض:
-
-1. جانب **MANY_TO_ONE** — يوجد على الكائن الذي يحمل المفتاح الخارجي
-2. جانب **ONE_TO_MANY** — يوجد على الكائن الذي يملك المجموعة
-
-يستخدم كلا الحقلين `FieldType.RELATION` ويُحيل كلٌ منهما إلى الآخر عبر `relationTargetFieldMetadataUniversalIdentifier`.
-
-#### مثال: البطاقة البريدية لديها العديد من المستلمين
-
-افترض أن `PostCard` يمكن إرسالها إلى العديد من سجلات `PostCardRecipient`. ينتمي كل مستلم إلى بطاقة بريدية واحدة بالضبط.
-
-**الخطوة 1: عرّف جانب ONE_TO_MANY على PostCard** (جانب "الواحد"):
-
-```typescript
-// src/fields/post-card-recipients-on-post-card.field.ts
-import { defineField, FieldType, RelationType } from 'twenty-sdk';
-import { POST_CARD_UNIVERSAL_IDENTIFIER } from '../objects/post-card.object';
-import { POST_CARD_RECIPIENT_UNIVERSAL_IDENTIFIER } from '../objects/post-card-recipient.object';
-
-// Export so the other side can reference it
-export const POST_CARD_RECIPIENTS_FIELD_ID = 'a1111111-1111-1111-1111-111111111111';
-// Import from the other side
-import { POST_CARD_FIELD_ID } from './post-card-on-post-card-recipient.field';
-
-export default defineField({
-  universalIdentifier: POST_CARD_RECIPIENTS_FIELD_ID,
-  objectUniversalIdentifier: POST_CARD_UNIVERSAL_IDENTIFIER,
-  type: FieldType.RELATION,
-  name: 'postCardRecipients',
-  label: 'Post Card Recipients',
-  icon: 'IconUsers',
-  relationTargetObjectMetadataUniversalIdentifier: POST_CARD_RECIPIENT_UNIVERSAL_IDENTIFIER,
-  relationTargetFieldMetadataUniversalIdentifier: POST_CARD_FIELD_ID,
-  universalSettings: {
-    relationType: RelationType.ONE_TO_MANY,
-  },
-});
-```
-
-**الخطوة 2: عرّف جانب MANY_TO_ONE على PostCardRecipient** (جانب "العديد" — يحمل المفتاح الخارجي):
-
-```typescript
-// src/fields/post-card-on-post-card-recipient.field.ts
-import { defineField, FieldType, RelationType, OnDeleteAction } from 'twenty-sdk';
-import { POST_CARD_UNIVERSAL_IDENTIFIER } from '../objects/post-card.object';
-import { POST_CARD_RECIPIENT_UNIVERSAL_IDENTIFIER } from '../objects/post-card-recipient.object';
-
-// Export so the other side can reference it
-export const POST_CARD_FIELD_ID = 'b2222222-2222-2222-2222-222222222222';
-// Import from the other side
-import { POST_CARD_RECIPIENTS_FIELD_ID } from './post-card-recipients-on-post-card.field';
-
-export default defineField({
-  universalIdentifier: POST_CARD_FIELD_ID,
-  objectUniversalIdentifier: POST_CARD_RECIPIENT_UNIVERSAL_IDENTIFIER,
-  type: FieldType.RELATION,
-  name: 'postCard',
-  label: 'Post Card',
-  icon: 'IconMail',
-  relationTargetObjectMetadataUniversalIdentifier: POST_CARD_UNIVERSAL_IDENTIFIER,
-  relationTargetFieldMetadataUniversalIdentifier: POST_CARD_RECIPIENTS_FIELD_ID,
-  universalSettings: {
-    relationType: RelationType.MANY_TO_ONE,
-    onDelete: OnDeleteAction.CASCADE,
-    joinColumnName: 'postCardId',
-  },
-});
-```
-
-<Note>
-**الاستيرادات الدائرية:** كلا حقلي العلاقة يُحيل كلٌ منهما إلى `universalIdentifier` الخاص بالآخر. لتجنّب مشكلات الاستيراد الدائري، صدّر معرّفات الحقول كثوابت مسمّاة من كل ملف، واستوردها في الملف الآخر. يقوم نظام البناء بحلّها في وقت الترجمة.
-</Note>
-
-#### الربط مع الكائنات القياسية
-
-لإنشاء علاقة مع كائن Twenty مضمّن (Person, Company, etc.)، استخدم `STANDARD_OBJECT_UNIVERSAL_IDENTIFIERS`:
-
-```typescript
-// src/fields/person-on-self-hosting-user.field.ts
-import {
-  defineField,
-  FieldType,
-  RelationType,
-  OnDeleteAction,
-  STANDARD_OBJECT_UNIVERSAL_IDENTIFIERS,
-} from 'twenty-sdk';
-import { SELF_HOSTING_USER_UNIVERSAL_IDENTIFIER } from '../objects/self-hosting-user.object';
-
-export const PERSON_FIELD_ID = 'c3333333-3333-3333-3333-333333333333';
-export const SELF_HOSTING_USER_REVERSE_FIELD_ID = 'd4444444-4444-4444-4444-444444444444';
-
-export default defineField({
-  universalIdentifier: PERSON_FIELD_ID,
-  objectUniversalIdentifier: SELF_HOSTING_USER_UNIVERSAL_IDENTIFIER,
-  type: FieldType.RELATION,
-  name: 'person',
-  label: 'Person',
-  description: 'Person matching with the self hosting user',
-  isNullable: true,
-  relationTargetObjectMetadataUniversalIdentifier:
-    STANDARD_OBJECT_UNIVERSAL_IDENTIFIERS.person.universalIdentifier,
-  relationTargetFieldMetadataUniversalIdentifier: SELF_HOSTING_USER_REVERSE_FIELD_ID,
-  universalSettings: {
-    relationType: RelationType.MANY_TO_ONE,
-    onDelete: OnDeleteAction.SET_NULL,
-    joinColumnName: 'personId',
-  },
-});
-```
-
-#### خصائص حقل العلاقة
-
-| الخاصية                                           | مطلوب           | الوصف                                                                                  |
-| ------------------------------------------------- | --------------- | -------------------------------------------------------------------------------------- |
-| `type`                                            | نعم             | يجب أن يكون `FieldType.RELATION`                                                       |
-| `relationTargetObjectMetadataUniversalIdentifier` | نعم             | قيمة `universalIdentifier` للكائن الهدف                                                |
-| `relationTargetFieldMetadataUniversalIdentifier`  | نعم             | قيمة `universalIdentifier` للحقل المطابق على الكائن الهدف                              |
-| `universalSettings.relationType`                  | نعم             | `RelationType.MANY_TO_ONE` أو `RelationType.ONE_TO_MANY`                               |
-| `universalSettings.onDelete`                      | MANY_TO_ONE فقط | ماذا يحدث عند حذف السجل المشار إليه: `CASCADE`، `SET_NULL`، `RESTRICT`، أو `NO_ACTION` |
-| `universalSettings.joinColumnName`                | MANY_TO_ONE فقط | اسم عمود قاعدة البيانات للمفتاح الخارجي (مثل `postCardId`)                             |
-
-#### حقول العلاقات المضمّنة في defineObject
-
-يمكنك أيضًا تعريف حقول العلاقات مباشرةً داخل `defineObject()`. في هذه الحالة، احذف `objectUniversalIdentifier` — إذ يُورَّث من الكائن الأب:
-
-```typescript
-export default defineObject({
-  universalIdentifier: '...',
-  nameSingular: 'postCardRecipient',
-  // ...
-  fields: [
-    {
-      universalIdentifier: POST_CARD_FIELD_ID,
-      type: FieldType.RELATION,
-      name: 'postCard',
-      label: 'Post Card',
-      relationTargetObjectMetadataUniversalIdentifier: POST_CARD_UNIVERSAL_IDENTIFIER,
-      relationTargetFieldMetadataUniversalIdentifier: POST_CARD_RECIPIENTS_FIELD_ID,
-      universalSettings: {
-        relationType: RelationType.MANY_TO_ONE,
-        onDelete: OnDeleteAction.CASCADE,
-        joinColumnName: 'postCardId',
-      },
-    },
-    // ... other fields
-  ],
-});
-```
-
 ### تكوين التطبيق (application-config.ts)

 كل تطبيق لديه ملف واحد `application-config.ts` يصف:
@@ -354,22 +161,6 @@ export default defineApplication({
 * `defaultRoleUniversalIdentifier` يجب أن يطابق ملف الدور (انظر أدناه).
 * يتم اكتشاف دوال ما قبل التثبيت وما بعد التثبيت تلقائيًا أثناء إنشاء ملف البيان. راجع [دوال ما قبل التثبيت](#pre-install-functions) و[دوال ما بعد التثبيت](#post-install-functions).

-#### بيانات التعريف لسوق التطبيقات
-
-إذا كنت تخطط لـ [نشر تطبيقك](/l/ar/developers/extend/apps/publishing)، فإن هذه الحقول الاختيارية تتحكّم في كيفية ظهور تطبيقك في السوق:
-
-| الحقل              | الوصف                                                |
-| ------------------ | ---------------------------------------------------- |
-| `author`           | اسم المؤلف أو الشركة                                 |
-| `category`         | فئة التطبيق لتصفية سوق التطبيقات                     |
-| `logoUrl`          | المسار إلى شعار تطبيقك (نسبيًا إلى `./assets/`)      |
-| `screenshots`      | مصفوفة لمسارات لقطات الشاشة (نسبيًا إلى `./assets/`) |
-| `aboutDescription` | وصف ماركداون أطول لعلامة التبويب "حول"               |
-| `websiteUrl`       | رابط إلى موقعك الإلكتروني                            |
-| `termsUrl`         | رابط إلى شروط الخدمة                                 |
-| `emailSupport`     | عنوان البريد الإلكتروني للدعم                        |
-| `issueReportUrl`   | رابط إلى متتبّع المشاكل                              |
-
 #### الأدوار والصلاحيات

 يمكن للتطبيقات تعريف أدوار تُغلّف الصلاحيات على كائنات وإجراءات مساحة العمل لديك. يعين الحقل `defaultRoleUniversalIdentifier` في `application-config.ts` الدور الافتراضي الذي تستخدمه وظائف المنطق في تطبيقك.
@@ -439,7 +230,7 @@ export default defineRole({
 كل ملف وظيفة يستخدم `defineLogicFunction()` لتصدير تكوين مع معالج ومشغّلات اختيارية.

 ```typescript
-// src/logic-functions/createPostCard.logic-function.ts
+// 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';
@@ -533,7 +324,7 @@ export default definePreInstallLogicFunction({
 يمكنك أيضًا تنفيذ دالة ما قبل التثبيت يدويًا في أي وقت باستخدام CLI:

 ```bash filename="Terminal"
-yarn twenty exec --preInstall
+yarn twenty function:execute --preInstall
 ```

 النقاط الرئيسية:
@@ -543,7 +334,7 @@ yarn twenty exec --preInstall
 * يُسمح بدالة ما قبل التثبيت واحدة فقط لكل تطبيق. سيُنتج إنشاء ملف البيان خطأً إذا تم اكتشاف أكثر من واحدة.
 * يتم تعيين `universalIdentifier` للدالة تلقائيًا كـ `preInstallLogicFunctionUniversalIdentifier` في بيان التطبيق أثناء الإنشاء — لست بحاجة إلى الإشارة إليه في `defineApplication()`.
 * تم ضبط المهلة الافتراضية على 300 ثانية (5 دقائق) للسماح بمهام التحضير الأطول.
-* لا تحتاج دوال ما قبل التثبيت إلى مشغّلات — إذ يستدعيها النظام الأساسي قبل التثبيت أو يدويًا عبر `exec --preInstall`.
+* لا تحتاج دوال ما قبل التثبيت إلى مُشغِّلات — إذ يستدعيها النظام الأساسي قبل التثبيت أو يدويًا عبر `function:execute --preInstall`.

 ### دوال ما بعد التثبيت

@@ -571,7 +362,7 @@ export default definePostInstallLogicFunction({
 يمكنك أيضًا تنفيذ دالة ما بعد التثبيت يدويًا في أي وقت باستخدام CLI:

 ```bash filename="Terminal"
-yarn twenty exec --postInstall
+yarn twenty function:execute --postInstall
 ```

 النقاط الرئيسية:
@@ -581,7 +372,7 @@ yarn twenty exec --postInstall
 * يُسمح بدالة ما بعد التثبيت واحدة فقط لكل تطبيق. سيُنتج إنشاء ملف البيان خطأً إذا تم اكتشاف أكثر من واحدة.
 * يتم تعيين `universalIdentifier` للدالة تلقائيًا كـ `postInstallLogicFunctionUniversalIdentifier` في بيان التطبيق أثناء الإنشاء — لست بحاجة إلى الإشارة إليه في `defineApplication()`.
 * تم تعيين مهلة افتراضية إلى 300 ثانية (5 دقائق) للسماح بمهام الإعداد الأطول مثل تهيئة البيانات.
-* لا تحتاج دوال ما بعد التثبيت إلى مشغّلات — حيث يستدعيها النظام الأساسي أثناء التثبيت أو يدويًا عبر `exec --postInstall`.
+* لا تحتاج دوال ما بعد التثبيت إلى مُشغِّلات — حيث يستدعيها النظام الأساسي أثناء التثبيت أو يدويًا عبر `function:execute --postInstall`.

 ### حمولة مشغل المسار

@@ -625,15 +416,15 @@ const handler = async (event: RoutePayload) => {

 يحتوي نوع `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`                              | المسار الخام للطلب                                                                       |
+| الخاصية                      | النوع                                 | الوصف                                                                                   |
+| ---------------------------- | ------------------------------------- | --------------------------------------------------------------------------------------- |
+| `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

@@ -675,7 +466,7 @@ const handler = async (event: RoutePayload) => {

 يمكنك إنشاء وظائف جديدة بطريقتين:

-* **مُنشأ بالقالب**: شغّل `yarn twenty add` واختر خيار إضافة وظيفة منطقية جديدة. يُولّد هذا ملفًا مبدئيًا مع معالج وتكوين.
+* **مُنشأ بالقالب**: شغّل `yarn twenty entity:add` واختر خيار إضافة دالة منطقية جديدة. يُولّد هذا ملفًا مبدئيًا مع معالج وتكوين.
 * **يدوي**: أنشئ ملفًا جديدًا `*.logic-function.ts` واستخدم `defineLogicFunction()` مع اتباع النمط نفسه.

 ### تمييز دالة منطقية كأداة
@@ -687,7 +478,7 @@ const handler = async (event: RoutePayload) => {
 ```typescript
 // src/logic-functions/enrich-company.logic-function.ts
 import { defineLogicFunction } from 'twenty-sdk';
-import { CoreApiClient } from 'twenty-client-sdk/core';
+import { CoreApiClient } from 'twenty-sdk/generated';

 const handler = async (params: { companyName: string; domain?: string }) => {
  const client = new CoreApiClient();
@@ -776,7 +567,7 @@ export default defineFrontComponent({

 يمكنك إنشاء مكوّنات أمامية جديدة بطريقتين:

-* **مُنشأ بالقالب**: شغّل `yarn twenty add` واختر خيار إضافة مكوّن أمامي جديد.
+* **مُنشأ بالقالب**: شغّل `yarn twenty entity:add` واختر خيار إضافة مكوّن أمامي جديد.
 * **يدوي**: أنشئ ملفًا جديدًا `.tsx` واستخدم `defineFrontComponent()` مع اتباع النمط نفسه.

 ### المهارات
@@ -811,122 +602,47 @@ export default defineSkill({

 يمكنك إنشاء مهارات جديدة بطريقتين:

-* **مُنشأ بالقالب**: شغّل `yarn twenty add` واختر خيار إضافة مهارة جديدة.
+* **مُنشأ بالقالب**: شغِّل `yarn twenty entity:add` واختر خيار إضافة مهارة جديدة.
 * **يدوي**: أنشئ ملفًا جديدًا واستخدم `defineSkill()` مع اتباع النمط نفسه.

-### عملاء واجهة برمجة التطبيقات ذات أنواع ثابتة (`twenty-client-sdk`)
+### عملاء مُولَّدون مضبوطو الأنواع

-توفر حزمة `twenty-client-sdk` عميلين لـ GraphQL ذوي أنواع ثابتة للتفاعل مع واجهة Twenty البرمجية من وظائفك المنطقية ومكوّنات الواجهة الأمامية:
+يتم توليد عميلين مضبوطي الأنواع تلقائيًا بواسطة `yarn twenty dev` وتخزينهما في `node_modules/twenty-sdk/generated` استنادًا إلى مخطط مساحة العمل لديك:

-| العميل              | استيراد                      | نقطة النهاية                                        | مُولَّد؟                   |
-| ------------------- | ---------------------------- | --------------------------------------------------- | -------------------------- |
-| `CoreApiClient`     | `twenty-client-sdk/core`     | `/graphql` — بيانات مساحة العمل (السجلات، الكائنات) | نعم، في وقت التطوير/البناء |
-| `MetadataApiClient` | `twenty-client-sdk/metadata` | `/metadata` — تكوين مساحة العمل، رفع الملفات        | لا، يأتي مُجهزًا مسبقًا    |
-
-#### CoreApiClient
-
-`CoreApiClient` هو العميل الرئيسي للاستعلام وتعديل بيانات مساحة العمل. يتم توليده من مخطط مساحة العمل الخاصة بك أثناء `yarn twenty dev` أو `yarn twenty build`، لذا فهو مكتوب الأنواع بالكامل ليتوافق مع كائناتك وحقولك.
+* **`CoreApiClient`** — يُجري استعلامات إلى نقطة النهاية `/graphql` للحصول على بيانات مساحة العمل
+* **`MetadataApiClient`** — يستعلم عن نقطة النهاية `/metadata` لتكوين مساحة العمل وتحميل الملفات.

 ```typescript
-import { CoreApiClient } from 'twenty-client-sdk/core';
+import { CoreApiClient, MetadataApiClient } from 'twenty-sdk/generated';

 const client = new CoreApiClient();
-
-// Query records
-const { companies } = await client.query({
-  companies: {
-    edges: {
-      node: {
-        id: true,
-        name: true,
-        domainName: true,
-      },
-    },
-  },
-});
-
-// Create a record
-const { createCompany } = await client.mutation({
-  createCompany: {
-    __args: {
-      data: {
-        name: 'Acme Corp',
-      },
-    },
-    id: true,
-    name: true,
-  },
-});
-```
-
-يستخدم العميل صياغة مجموعة اختيار: مرِّر `true` لتضمين حقل، واستخدم `__args` للوسيطات، وعشّش الكائنات للعلاقات. ستحصل على إكمال تلقائي كامل وفحص للأنواع يعتمد على مخطط مساحة العمل لديك.
-
-<Note>
-**يتم توليد CoreApiClient في وقت التطوير/البناء.** إذا حاولت استخدامه دون تشغيل `yarn twenty dev` أو `yarn twenty build` أولًا، فسوف ينتج خطأ. تتم عملية التوليد تلقائيًا — حيث يقوم CLI بفحص مخطط GraphQL الخاص بمساحة العمل لديك، ويولّد عميلًا مكتوب الأنواع باستخدام `@genql/cli`، ويكتب المصادر المُولَّدة إلى `node_modules/twenty-client-sdk/dist/core/generated/`، ويستبدل الأجزاء الوهمية في `node_modules/twenty-client-sdk/dist/core.mjs` و`node_modules/twenty-client-sdk/dist/core.cjs`.
-</Note>
-
-#### استخدام CoreSchema للتعليقات التوضيحية للأنواع
-
-يوفّر `CoreSchema` أنواع TypeScript المطابقة لكائنات مساحة العمل لديك، وهو مفيد لتعيين أنواع حالة المكوّن أو معاملات الدوال:
-
-```typescript
-import { CoreApiClient, CoreSchema } from 'twenty-client-sdk/core';
-import { useState } from 'react';
-
-const [company, setCompany] = useState<
-  Pick<CoreSchema.Company, 'id' | 'name'> | undefined
->(undefined);
-
-const client = new CoreApiClient();
-const result = await client.query({
-  company: {
-    __args: { filter: { position: { eq: 1 } } },
-    id: true,
-    name: true,
-  },
-});
-setCompany(result.company);
-```
-
-#### MetadataApiClient
-
-يأتي `MetadataApiClient` مُجهّزًا مسبقًا مع SDK (لا حاجة للتوليد). يستعلم عن نقطة النهاية `/metadata` للحصول على تكوين مساحة العمل والتطبيقات ورفع الملفات:
-
-```typescript
-import { MetadataApiClient } from 'twenty-client-sdk/metadata';
+const { me } = await client.query({ me: { id: true, displayName: true } });

 const metadataClient = new MetadataApiClient();
-
-// Query workspace info
-const { currentWorkspace } = await metadataClient.query({
-  currentWorkspace: { id: true, displayName: true },
-});
-
-// List installed applications
-const { findManyApplications } = await metadataClient.query({
-  findManyApplications: {
-    id: true,
-    name: true,
-    version: true,
-  },
-});
+const { currentWorkspace } = await metadataClient.query({ currentWorkspace: { id: true } });
 ```

-#### بيانات الاعتماد أثناء وقت التشغيل
+يُعاد توليد كلا العميلين تلقائيًا بواسطة `yarn twenty dev` كلما تغيّرت كائناتك أو حقولك.

-عند تشغيل كودك على Twenty (وظائف منطقية أو مكوّنات أمامية)، يقوم النظام الأساسي بحقن بيانات الاعتماد كمتغيرات بيئية:
+#### بيانات الاعتماد وقت التشغيل في الدوال المنطقية

-* `TWENTY_API_URL` — عنوان URL الأساسي لواجهة Twenty البرمجية
-* `TWENTY_API_KEY` — مفتاح قصير العمر ذو نطاق يقتصر على الدور الافتراضي لوظيفة تطبيقك
+عندما تعمل دالتك على Twenty، يقوم النظام الأساسي بحقن بيانات الاعتماد كمتغيرات بيئة قبل تنفيذ كودك:

-لست **بحاجة** إلى تمرير هذه القيم إلى العملاء — فهي تُقرأ تلقائيًا من `process.env`. تُحدَّد أذونات مفتاح واجهة برمجة التطبيقات بواسطة الدور المشار إليه في `defaultRoleUniversalIdentifier` ضمن `application-config.ts`.
+* `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 متعددة الأجزاء](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-client-sdk/metadata';
+import { MetadataApiClient } from 'twenty-sdk/generated';
 import * as fs from 'fs';

 const metadataClient = new MetadataApiClient();
@@ -936,14 +652,25 @@ const fileBuffer = fs.readFileSync('./invoice.pdf');
 const uploadedFile = await metadataClient.uploadFile(
  fileBuffer,                                         // file contents as a Buffer
  'invoice.pdf',                                      // filename
-  'application/pdf',                                  // MIME type
-  '58a0a314-d7ea-4865-9850-7fb84e72f30b',            // field universalIdentifier
+  '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` | المحتوى الخام للملف                                                                |
@@ -953,7 +680,8 @@ console.log(uploadedFile);

 النقاط الرئيسية:

-* يستخدم `universalIdentifier` الخاص بالحقل (وليس معرّفه الخاص بمساحة العمل)، بحيث يعمل كود الرفع لديك عبر أي مساحة عمل مُثبَّت فيها تطبيقك.
+* تتوفر طريقة `uploadFile` على `MetadataApiClient` لأن عملية الـ mutation الخاصة بالرفع تُعالَج عبر نقطة النهاية `/metadata`.
+* تستخدم `universalIdentifier` الخاص بالحقل (وليس المعرّف الخاص بمساحة العمل)، ليعمل كود الرفع لديك عبر أي مساحة عمل مُثبَّت فيها تطبيقك — بما يتماشى مع كيفية إشارة التطبيقات إلى الحقول في كل مكان آخر.
 * العنوان `url` المُعاد هو عنوان URL موقّع يمكنك استخدامه للوصول إلى الملف المرفوع.

 ### مثال Hello World
@@ -49,7 +49,7 @@ npx create-twenty-app@latest my-app --minimal

 ```bash filename="Terminal"
 # Add a new entity to your application (guided)
-yarn twenty add
+yarn twenty entity:add

 # Watch your application's function logs
 yarn twenty function:logs
@@ -123,7 +123,7 @@ my-twenty-app/
 بشكل عام:

 * **package.json**: يصرّح باسم التطبيق والإصدار والمحرّكات (Node 24+، Yarn 4)، ويضيف `twenty-sdk` بالإضافة إلى نص برمجي `twenty` يفوِّض إلى `twenty` CLI المحلي. شغِّل `yarn twenty help` لعرض جميع الأوامر المتاحة.
-* **.gitignore**: Ignores common artifacts such as `node_modules`, `.yarn`, `.twenty/`, `dist/`, `build/`, coverage folders, log files, and `.env*` files.
+* **.gitignore**: يتجاهل العناصر الشائعة مثل `node_modules` و`.yarn` و`generated/` (عميل مضبوط الأنواع) و`dist/` و`build/` ومجلدات التغطية وملفات السجلات وملفات `.env*`.
 * **yarn.lock**، **.yarnrc.yml**، **.yarn/**: تقوم بقفل وتكوين حزمة أدوات Yarn 4 المستخدمة في المشروع.
 * **.nvmrc**: يثبّت إصدار Node.js المتوقع للمشروع.
 * **.oxlintrc.json** و **tsconfig.json**: يقدّمان إعدادات الفحص والتهيئة لـ TypeScript لمصادر TypeScript في تطبيقك.
@@ -167,8 +167,8 @@ export default defineObject({

 ستضيف الأوامر اللاحقة مزيدًا من الملفات والمجلدات:

-* `yarn twenty dev` will auto-generate the typed `CoreApiClient` (for workspace data via `/graphql`) into `node_modules/twenty-client-sdk/`. The `MetadataApiClient` (for workspace configuration and file uploads via `/metadata`) ships pre-built and is available immediately. Import them from `twenty-client-sdk/core` and `twenty-client-sdk/metadata` respectively.
-* `yarn twenty add` will add entity definition files under `src/` for your custom objects, functions, front components, roles, skills, and more.
+* سيقوم `yarn twenty dev` بتوليد عميلين API مضبوطي الأنواع تلقائيًا في `node_modules/twenty-sdk/generated`: `CoreApiClient` (لبيانات مساحة العمل عبر `/graphql`) و`MetadataApiClient` (لتكوين مساحة العمل وتحميل الملفات عبر `/metadata`).
+* `yarn twenty entity:add` سيضيف ملفات تعريف الكيانات ضمن `src/` لكائناتك المخصّصة، والوظائف، ومكوّنات الواجهة الأمامية، والأدوار، والمهارات، وغير ذلك.

 ## المصادقة

@@ -12,25 +12,7 @@ description: وزّع تطبيق Twenty الخاص بك على سوق Twenty أ
 بمجرد أن يكون تطبيقك [مبنيًا ومختبرًا محليًا](/l/ar/developers/extend/apps/building)، لديك مساران لتوزيعه:

 * **النشر على npm** — أدرج تطبيقك في سوق Twenty ليتسنى لأي مساحة عمل اكتشافه وتثبيته.
-* **نشر أرشيف tar** — ارفع تطبيقك مباشرةً إلى خادم Twenty محدد للاستخدام الداخلي أو الخاص.
-
-كلا المسارين يبدآن من نفس خطوة **build**.
-
-## بناء تطبيقك
-
-يقوم الأمر `build` بتجميع مصادر TypeScript الخاصة بك، وتحويل دوال المنطق ومكوّنات الواجهة الأمامية، وإنشاء ملف `manifest.json` يصف محتويات تطبيقك:
-
-```bash filename="Terminal"
-yarn twenty build
-```
-
-يتم حفظ المخرجات في `.twenty/output/`. This directory contains everything needed for distribution: compiled code, assets, the manifest, and a copy of your `package.json`.
-
-To also create a `.tgz` tarball (used by the deploy command internally, or for manual distribution):
-
-```bash filename="Terminal"
-yarn twenty build --tarball
-```
+* **إرسال tarball** — انشر تطبيقك إلى خادم Twenty معيّن للاستخدام الداخلي من دون جعله متاحًا للعامة.

 ## النشر على npm

@@ -39,72 +21,29 @@ yarn twenty build --tarball
 ### المتطلبات

 * حساب على [npm](https://www.npmjs.com)
-* The `twenty-app` keyword **must** be listed in your `package.json` `keywords` array
-
-### Adding the required keyword
-
-The Twenty marketplace discovers apps by searching the npm registry for packages with the `twenty-app` keyword. Add it to your `package.json`:
-
-```json filename="package.json"
-{
-  "name": "twenty-app-postcard-sender",
-  "version": "1.0.0",
-  "keywords": ["twenty-app"],
-  ...
-}
-```
-
-<Note>
-The marketplace searches for `keywords:twenty-app` on the npm registry. Without this keyword, your package won't appear in the marketplace even if it has the `twenty-app-` name prefix.
-</Note>
+* يجب أن يستخدم اسم الحزمة البادئة `twenty-app-` (مثلًا، `twenty-app-postcard-sender`)

 ### الخطوات

-1. **Build your app:**
+1. **قم ببناء تطبيقك** — تقوم أداة CLI بتجميع مصادر TypeScript الخاصة بك وإنشاء ملف بيان التطبيق:

 ```bash filename="Terminal"
 yarn twenty build
 ```

-2. **Publish to npm:**
+2. **النشر على npm** — ادفع الحزمة المبنية إلى سجل npm:

 ```bash filename="Terminal"
-yarn twenty publish
+npx twenty publish
 ```

-This runs `npm publish` from the `.twenty/output/` directory.
+### الاكتشاف التلقائي

-To publish under a specific dist-tag (e.g., `beta` or `next`):
-
-```bash filename="Terminal"
-yarn twenty publish --tag beta
-```
-
-### How marketplace discovery works
-
-The Twenty server syncs its marketplace catalog from the npm registry **every hour**:
-
-1. It searches for all npm packages with the `keywords:twenty-app` keyword
-2. For each package, it fetches the `manifest.json` from the npm CDN
-3. The app's metadata (name, description, author, logo, screenshots, category) is extracted from the manifest and displayed in the marketplace
-
-After publishing, your app can take up to one hour to appear in the marketplace. To trigger the sync immediately instead of waiting for the next hourly run:
-
-```bash filename="Terminal"
-yarn twenty catalog-sync
-```
-
-To target a specific remote:
-
-```bash filename="Terminal"
-yarn twenty catalog-sync -r production
-```
-
-The metadata shown in the marketplace comes from your `defineApplication()` call in your app source code — fields like `displayName`, `description`, `author`, `category`, `logoUrl`, `screenshots`, `aboutDescription`, `websiteUrl`, and `termsUrl`.
+تُكتشف الحِزم التي تحمل البادئة `twenty-app-` تلقائيًا بواسطة فهرس سوق Twenty. بعد نشره، سيظهر تطبيقك في السوق خلال بضع دقائق — من دون الحاجة إلى تسجيل يدوي أو موافقة يدوية.

 ### النشر عبر CI

-يتضمن المشروع المُولَّد سير عمل GitHub Actions يقوم بالنشر عند كل إصدار:
+يتضمن المشروع المُولَّد سير عمل GitHub Actions يقوم بالنشر عند كل إصدار. يشغِّل `app:build`، ثم ينفِّذ `npm publish --provenance` من مخرجات البناء:

 ```yaml filename=".github/workflows/publish.yml"
 name: Publish
@@ -133,117 +72,48 @@ jobs:
          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
 ```

-For other CI systems (GitLab CI, CircleCI, etc.), the same three commands apply: `yarn install`, `yarn twenty build`, then `npm publish` from `.twenty/output`.
+بالنسبة لأنظمة CI الأخرى (GitLab CI، CircleCI، إلخ)، تنطبق الأوامر الثلاثة نفسها: `yarn install`، ثم `npx twenty build`، ثم `npm publish` من `.twenty/output`.

 <Tip>
 **npm provenance** اختياري ولكنه موصى به. يضيف النشر باستخدام `--provenance` شارة ثقة إلى إدراجك على npm، مما يتيح للمستخدمين التحقق من أن الحزمة تم بناؤها من التزام محدد ضمن خط أنابيب CI عام. راجع [وثائق npm provenance](https://docs.npmjs.com/generating-provenance-statements) للحصول على تعليمات الإعداد.
 </Tip>

-## Deploying to a server (tarball)
+## التوزيع الداخلي

-For apps you don't want publicly available — proprietary tools, enterprise-only integrations, or experimental builds — you can deploy a tarball directly to a Twenty server.
+بالنسبة للتطبيقات التي لا تريد إتاحتها للعامة — مثل الأدوات المملوكة، أو عمليات التكامل الخاصة بالمؤسسات فقط، أو الإصدارات التجريبية — يمكنك إرسال tarball مباشرةً إلى خادم Twenty.

-### المتطلبات الأساسية
+### إرسال tarball

-Before deploying, you need a configured remote pointing to the target server. Remotes store the server URL and authentication credentials locally in `~/.twenty/config.json`.
-
-Add a remote:
+قم ببناء تطبيقك وانشره إلى خادم محدد في خطوة واحدة:

 ```bash filename="Terminal"
-yarn twenty remote add --url https://your-twenty-server.com --as production
+npx twenty publish --server <server-url>
 ```

-For a local development server:
-
-```bash filename="Terminal"
-yarn twenty remote add --local --as local
-```
-
-You can also authenticate with an API key for non-interactive environments:
-
-```bash filename="Terminal"
-yarn twenty remote add --url https://your-twenty-server.com --token <api-key> --as production
-```
-
-Manage your remotes:
-
-```bash filename="Terminal"
-yarn twenty remote list       # List all configured remotes
-yarn twenty remote switch prod # Set the default remote
-yarn twenty remote status     # Show active remote and auth status
-yarn twenty remote remove old # Remove a remote
-```
-
-### Deploying
-
-Build and upload your app to the server in one step:
-
-```bash filename="Terminal"
-yarn twenty deploy
-```
-
-This builds the app with `--tarball`, then uploads the tarball to the default remote via a GraphQL multipart upload.
-
-To deploy to a specific remote:
-
-```bash filename="Terminal"
-yarn twenty deploy -r production
-```
-
-### Sharing a deployed app
-
-Tarball apps are not listed in the public marketplace, so other workspaces on the same server won't discover them by browsing. To share a deployed app:
-
-1. Go to **Settings > Applications > Registrations** and open your app
-2. In the **Distribution** tab, click **Copy share link**
-3. Share this link with users on other workspaces — it takes them directly to the app's install page
-
-The share link uses the server's base URL (without any workspace subdomain) so it works for any workspace on the server.
+يمكن لأي مساحة عمل على ذلك الخادم بعدها تثبيت التطبيق وترقيته من صفحة الإعدادات **التطبيقات**.

 ### إدارة الإصدارات

 لطرح تحديث:

 1. ارفع قيمة الحقل `version` في ملف `package.json`
-2. Run `yarn twenty deploy` (or `yarn twenty deploy -r production`)
-3. Workspaces that have the app installed will see the upgrade available in their settings
+2. أرسل tarball جديدًا باستخدام `npx twenty publish --server <server-url>`
+3. سترى مساحات العمل على ذلك الخادم الترقية متاحة في إعداداتها

-## Installing apps
+<Note>
+التطبيقات الداخلية مقتصرة على الخادم الذي تُرسل إليه. لن تظهر في السوق العام ولا يمكن لمساحات العمل على خوادم أخرى تثبيتها.
+</Note>

-Once an app is published (npm) or deployed (tarball), workspaces install it through the UI:
-
-```bash filename="Terminal"
-yarn twenty install
-```
-
-Or from the **Settings > Applications** page in the Twenty UI, where both marketplace and tarball-deployed apps can be browsed and installed.
-
-## App distribution categories
+## فئات التطبيقات

 تُنظِّم Twenty التطبيقات في ثلاث فئات استنادًا إلى طريقة توزيعها:

-| الفئة                  | كيف يعمل                                                                                                 | مرئي في سوق Twenty؟ |
-| ---------------------- | -------------------------------------------------------------------------------------------------------- | ------------------- |
-| **التطوير**            | تطبيقات وضع التطوير المحلي التي تعمل عبر `yarn twenty dev`. تُستخدم للبناء والاختبار.                    | لا                  |
-| **Published (npm)**    | Apps published to npm with the `twenty-app` keyword. مدرجة في سوق Twenty لتتمكن أي مساحة عمل من تثبيتها. | نعم                 |
-| **Internal (tarball)** | تطبيقات منشورة عبر tarball إلى خادم محدد. Available only to workspaces on that server via a share link.  | لا                  |
+| الفئة       | كيف يعمل                                                                                             | مرئي في سوق Twenty؟ |
+| ----------- | ---------------------------------------------------------------------------------------------------- | ------------------- |
+| **التطوير** | تطبيقات وضع التطوير المحلي التي تعمل عبر `yarn twenty dev`. تُستخدم للبناء والاختبار.                | لا                  |
+| **منشور**   | تطبيقات منشورة على npm مع البادئة `twenty-app-`. مدرجة في سوق Twenty لتتمكن أي مساحة عمل من تثبيتها. | نعم                 |
+| **داخلي**   | تطبيقات منشورة عبر tarball إلى خادم محدد. متاحة فقط لمساحات العمل على ذلك الخادم.                    | لا                  |

 <Tip>
 ابدأ في وضع **التطوير** أثناء بناء تطبيقك. عندما يصبح جاهزًا، اختر **منشور** (npm) للتوزيع الواسع أو **داخلي** (tarball) للنشر الخاص.
 </Tip>
-
-## CLI reference
-
-| أمر                         | الوصف                                          | Key flags                                           |
-| --------------------------- | ---------------------------------------------- | --------------------------------------------------- |
-| `yarn twenty build`         | Compile app and generate manifest              | `--tarball` — also create a `.tgz` package          |
-| `yarn twenty publish`       | Build and publish to npm                       | `--tag <tag>` — npm dist-tag (e.g., `beta`, `next`) |
-| `yarn twenty deploy`        | Build and upload tarball to a server           | `-r, --remote <name>` — target remote               |
-| `yarn twenty catalog-sync`  | Trigger marketplace catalog sync on the server | `-r, --remote <name>` — target remote               |
-| `yarn twenty install`       | Install a deployed app on a workspace          | `-r, --remote <name>` — target remote               |
-| `yarn twenty dev`           | Watch and sync local changes                   | Uses default remote                                 |
-| `yarn twenty remote add`    | Add a server connection                        | `--url`, `--token`, `--as`, `--local`, `--port`     |
-| `yarn twenty remote list`   | List configured remotes                        | —                                                   |
-| `yarn twenty remote switch` | Set default remote                             | —                                                   |
-| `yarn twenty remote status` | Show connection status                         | —                                                   |
-| `yarn twenty remote remove` | Remove a remote                                | —                                                   |
@@ -15,21 +15,19 @@ twenty-sdk poskytuje typované stavební bloky a pomocné funkce, které použí

 SDK poskytuje pomocné funkce pro definování entit vaší aplikace. Jak je popsáno v [Detekce entit](/l/cs/developers/extend/apps/getting-started#entity-detection), musíte použít `export default define<Entity>({...})`, aby byly vaše entity detekovány:

-| Funkce                           | Účel                                                                            |
-| -------------------------------- | ------------------------------------------------------------------------------- |
-| `defineApplication`              | Nakonfigurujte metadata aplikace (povinné, jedno na aplikaci)                   |
-| `defineObject`                   | Definice vlastních objektů s poli                                               |
-| `defineField`                    | Rozšiřte existující objekty o další pole nebo definujte samostatná relační pole |
-| `defineLogicFunction`            | Definice logických funkcí s obslužnými funkcemi                                 |
-| `definePreInstallLogicFunction`  | Definujte předinstalační logickou funkci (jedna na aplikaci)                    |
-| `definePostInstallLogicFunction` | Definujte postinstalační logickou funkci (jedna na aplikaci)                    |
-| `defineFrontComponent`           | Definujte frontendové komponenty pro vlastní uživatelské rozhraní               |
-| `defineRole`                     | Konfigurace oprávnění rolí a přístupu k objektům                                |
-| `defineView`                     | Definujte uložená zobrazení pro objekty                                         |
-| `defineNavigationMenuItem`       | Definujte odkazy postranní navigace                                             |
-| `defineSkill`                    | Definujte dovednosti agenta AI                                                  |
-| `defineAgent`                    | Definujte agenty AI                                                             |
-| `definePageLayout`               | Definujte vlastní rozvržení stránek                                             |
+| Funkce                           | Účel                                                              |
+| -------------------------------- | ----------------------------------------------------------------- |
+| `defineApplication`              | Nakonfigurujte metadata aplikace (povinné, jedno na aplikaci)     |
+| `defineObject`                   | Definice vlastních objektů s poli                                 |
+| `defineLogicFunction`            | Definice logických funkcí s obslužnými funkcemi                   |
+| `definePreInstallLogicFunction`  | Definujte předinstalační logickou funkci (jedna na aplikaci)      |
+| `definePostInstallLogicFunction` | Definujte postinstalační logickou funkci (jedna na aplikaci)      |
+| `defineFrontComponent`           | Definujte frontendové komponenty pro vlastní uživatelské rozhraní |
+| `defineRole`                     | Konfigurace oprávnění rolí a přístupu k objektům                  |
+| `defineField`                    | Rozšiřte existující objekty o další pole                          |
+| `defineView`                     | Definujte uložená zobrazení pro objekty                           |
+| `defineNavigationMenuItem`       | Definujte odkazy postranní navigace                               |
+| `defineSkill`                    | Definujte dovednosti agenta AI                                    |

 Tyto funkce validují vaši konfiguraci v době sestavení a poskytují automatické doplňování v IDE a typovou bezpečnost.

@@ -38,7 +36,7 @@ Tyto funkce validují vaši konfiguraci v době sestavení a poskytují automati
 Vlastní objekty popisují jak schéma, tak chování záznamů ve vašem pracovním prostoru. K definování objektů s vestavěnou validací použijte `defineObject()`:

 ```typescript
-// src/objects/postCard.object.ts
+// src/app/postCard.object.ts
 import { defineObject, FieldType } from 'twenty-sdk';

 enum PostCardStatus {
@@ -112,7 +110,7 @@ Hlavní body:
 * Hodnota `universalIdentifier` musí být jedinečná a stabilní napříč nasazeními.
 * Každé pole vyžaduje `name`, `type`, `label` a svůj vlastní stabilní `universalIdentifier`.
 * Pole `fields` je volitelné — objekty můžete definovat i bez vlastních polí.
-* Nové objekty můžete vygenerovat pomocí `yarn twenty add`, který vás provede pojmenováním, poli a vztahy.
+* Nové objekty můžete vygenerovat pomocí `yarn twenty entity:add`, který vás provede pojmenováním, poli a vztahy.

 <Note>
 **Základní pole jsou vytvořena automaticky.** Když definujete vlastní objekt, Twenty automaticky přidá standardní pole
@@ -122,197 +120,6 @@ Výchozí pole můžete přepsat definováním pole se stejným názvem v poli `
 ale to se nedoporučuje.
 </Note>

-### Definování polí u existujících objektů
-
-Pomocí `defineField()` přidejte pole k objektům, které nevlastníte — například ke standardním objektům Twenty (Person, Company atd.). nebo k objektům z jiných aplikací. Na rozdíl od inline polí v `defineObject()` vyžadují samostatná pole `objectUniversalIdentifier` k určení, který objekt rozšiřují:
-
-```typescript
-// src/fields/company-loyalty-tier.field.ts
-import { defineField, FieldType } from 'twenty-sdk';
-
-export default defineField({
-  universalIdentifier: 'f2a1b3c4-d5e6-7890-abcd-ef1234567890',
-  objectUniversalIdentifier: '701aecb9-eb1c-4d84-9d94-b954b231b64b', // Company object
-  name: 'loyaltyTier',
-  type: FieldType.SELECT,
-  label: 'Loyalty Tier',
-  icon: 'IconStar',
-  options: [
-    { value: 'BRONZE', label: 'Bronze', position: 0, color: 'orange' },
-    { value: 'SILVER', label: 'Silver', position: 1, color: 'gray' },
-    { value: 'GOLD', label: 'Gold', position: 2, color: 'yellow' },
-  ],
-});
-```
-
-Hlavní body:
-
-* `objectUniversalIdentifier` identifikuje cílový objekt. Pro standardní objekty použijte `STANDARD_OBJECT_UNIVERSAL_IDENTIFIERS` exportovaný z `twenty-sdk`.
-* Při definování polí inline v `defineObject()` `objectUniversalIdentifier` nepotřebujete — dědí se z nadřazeného objektu.
-* `defineField()` je jediný způsob, jak přidat pole k objektům, které jste nevytvořili pomocí `defineObject()`.
-
-### Vztahy
-
-Relace propojují objekty. Ve Twenty jsou relace vždy obousměrné — definujete obě strany a každá strana odkazuje na tu druhou.
-
-Existují dva typy relací:
-
-| Typ vztahu    | Popis                                                                 | Má cizí klíč?          |
-| ------------- | --------------------------------------------------------------------- | ---------------------- |
-| `MANY_TO_ONE` | Mnoho záznamů tohoto objektu ukazuje na jeden záznam cílového objektu | Ano (`joinColumnName`) |
-| `ONE_TO_MANY` | Jeden záznam tohoto objektu má mnoho záznamů cílového objektu         | Ne (inverzní strana)   |
-
-#### Jak fungují relace
-
-Každá relace vyžaduje dvě pole, která na sebe vzájemně odkazují:
-
-1. Strana MANY_TO_ONE — je na objektu, který drží cizí klíč
-2. Strana ONE_TO_MANY — je na objektu, který vlastní kolekci
-
-Obě pole používají `FieldType.RELATION` a vzájemně se odkazují prostřednictvím `relationTargetFieldMetadataUniversalIdentifier`.
-
-#### Příklad: Pohlednice má mnoho příjemců
-
-Předpokládejme, že `PostCard` lze odeslat mnoha záznamům `PostCardRecipient`. Každý příjemce náleží přesně jedné pohlednici.
-
-**Krok 1: Definujte stranu ONE_TO_MANY na PostCard** (strana "one"):
-
-```typescript
-// src/fields/post-card-recipients-on-post-card.field.ts
-import { defineField, FieldType, RelationType } from 'twenty-sdk';
-import { POST_CARD_UNIVERSAL_IDENTIFIER } from '../objects/post-card.object';
-import { POST_CARD_RECIPIENT_UNIVERSAL_IDENTIFIER } from '../objects/post-card-recipient.object';
-
-// Export so the other side can reference it
-export const POST_CARD_RECIPIENTS_FIELD_ID = 'a1111111-1111-1111-1111-111111111111';
-// Import from the other side
-import { POST_CARD_FIELD_ID } from './post-card-on-post-card-recipient.field';
-
-export default defineField({
-  universalIdentifier: POST_CARD_RECIPIENTS_FIELD_ID,
-  objectUniversalIdentifier: POST_CARD_UNIVERSAL_IDENTIFIER,
-  type: FieldType.RELATION,
-  name: 'postCardRecipients',
-  label: 'Post Card Recipients',
-  icon: 'IconUsers',
-  relationTargetObjectMetadataUniversalIdentifier: POST_CARD_RECIPIENT_UNIVERSAL_IDENTIFIER,
-  relationTargetFieldMetadataUniversalIdentifier: POST_CARD_FIELD_ID,
-  universalSettings: {
-    relationType: RelationType.ONE_TO_MANY,
-  },
-});
-```
-
-**Krok 2: Definujte stranu MANY_TO_ONE na PostCardRecipient** (strana "many" — drží cizí klíč):
-
-```typescript
-// src/fields/post-card-on-post-card-recipient.field.ts
-import { defineField, FieldType, RelationType, OnDeleteAction } from 'twenty-sdk';
-import { POST_CARD_UNIVERSAL_IDENTIFIER } from '../objects/post-card.object';
-import { POST_CARD_RECIPIENT_UNIVERSAL_IDENTIFIER } from '../objects/post-card-recipient.object';
-
-// Export so the other side can reference it
-export const POST_CARD_FIELD_ID = 'b2222222-2222-2222-2222-222222222222';
-// Import from the other side
-import { POST_CARD_RECIPIENTS_FIELD_ID } from './post-card-recipients-on-post-card.field';
-
-export default defineField({
-  universalIdentifier: POST_CARD_FIELD_ID,
-  objectUniversalIdentifier: POST_CARD_RECIPIENT_UNIVERSAL_IDENTIFIER,
-  type: FieldType.RELATION,
-  name: 'postCard',
-  label: 'Post Card',
-  icon: 'IconMail',
-  relationTargetObjectMetadataUniversalIdentifier: POST_CARD_UNIVERSAL_IDENTIFIER,
-  relationTargetFieldMetadataUniversalIdentifier: POST_CARD_RECIPIENTS_FIELD_ID,
-  universalSettings: {
-    relationType: RelationType.MANY_TO_ONE,
-    onDelete: OnDeleteAction.CASCADE,
-    joinColumnName: 'postCardId',
-  },
-});
-```
-
-<Note>
-**Cyklické importy:** Obě relační pole odkazují na `universalIdentifier` toho druhého. Abyste předešli problémům s cyklickými importy, exportujte ID polí jako pojmenované konstanty z každého souboru a v druhém souboru je importujte. Build systém je vyřeší v době kompilace.
-</Note>
-
-#### Vazby na standardní objekty
-
-Chcete-li vytvořit relaci s vestavěným objektem Twenty (Person, Company atd.), použijte `STANDARD_OBJECT_UNIVERSAL_IDENTIFIERS`:
-
-```typescript
-// src/fields/person-on-self-hosting-user.field.ts
-import {
-  defineField,
-  FieldType,
-  RelationType,
-  OnDeleteAction,
-  STANDARD_OBJECT_UNIVERSAL_IDENTIFIERS,
-} from 'twenty-sdk';
-import { SELF_HOSTING_USER_UNIVERSAL_IDENTIFIER } from '../objects/self-hosting-user.object';
-
-export const PERSON_FIELD_ID = 'c3333333-3333-3333-3333-333333333333';
-export const SELF_HOSTING_USER_REVERSE_FIELD_ID = 'd4444444-4444-4444-4444-444444444444';
-
-export default defineField({
-  universalIdentifier: PERSON_FIELD_ID,
-  objectUniversalIdentifier: SELF_HOSTING_USER_UNIVERSAL_IDENTIFIER,
-  type: FieldType.RELATION,
-  name: 'person',
-  label: 'Person',
-  description: 'Person matching with the self hosting user',
-  isNullable: true,
-  relationTargetObjectMetadataUniversalIdentifier:
-    STANDARD_OBJECT_UNIVERSAL_IDENTIFIERS.person.universalIdentifier,
-  relationTargetFieldMetadataUniversalIdentifier: SELF_HOSTING_USER_REVERSE_FIELD_ID,
-  universalSettings: {
-    relationType: RelationType.MANY_TO_ONE,
-    onDelete: OnDeleteAction.SET_NULL,
-    joinColumnName: 'personId',
-  },
-});
-```
-
-#### Vlastnosti relačních polí
-
-| Vlastnost                                         | Povinné           | Popis                                                                                             |
-| ------------------------------------------------- | ----------------- | ------------------------------------------------------------------------------------------------- |
-| `type`                                            | Ano               | Musí být `FieldType.RELATION`                                                                     |
-| `relationTargetObjectMetadataUniversalIdentifier` | Ano               | `universalIdentifier` cílového objektu                                                            |
-| `relationTargetFieldMetadataUniversalIdentifier`  | Ano               | `universalIdentifier` odpovídajícího pole na cílovém objektu                                      |
-| `universalSettings.relationType`                  | Ano               | `RelationType.MANY_TO_ONE` nebo `RelationType.ONE_TO_MANY`                                        |
-| `universalSettings.onDelete`                      | Pouze MANY_TO_ONE | Co se stane, když je smazán odkazovaný záznam: `CASCADE`, `SET_NULL`, `RESTRICT` nebo `NO_ACTION` |
-| `universalSettings.joinColumnName`                | Pouze MANY_TO_ONE | Název databázového sloupce pro cizí klíč (např. `postCardId`)                                     |
-
-#### Vložená relační pole v defineObject
-
-Relační pole můžete také definovat přímo uvnitř `defineObject()`. V takovém případě vynechejte `objectUniversalIdentifier` — dědí se z nadřazeného objektu:
-
-```typescript
-export default defineObject({
-  universalIdentifier: '...',
-  nameSingular: 'postCardRecipient',
-  // ...
-  fields: [
-    {
-      universalIdentifier: POST_CARD_FIELD_ID,
-      type: FieldType.RELATION,
-      name: 'postCard',
-      label: 'Post Card',
-      relationTargetObjectMetadataUniversalIdentifier: POST_CARD_UNIVERSAL_IDENTIFIER,
-      relationTargetFieldMetadataUniversalIdentifier: POST_CARD_RECIPIENTS_FIELD_ID,
-      universalSettings: {
-        relationType: RelationType.MANY_TO_ONE,
-        onDelete: OnDeleteAction.CASCADE,
-        joinColumnName: 'postCardId',
-      },
-    },
-    // ... other fields
-  ],
-});
-```
-
 ### Konfigurace aplikace (application-config.ts)

 Každá aplikace má jeden soubor `application-config.ts`, který popisuje:
@@ -354,22 +161,6 @@ Poznámky:
 * `defaultRoleUniversalIdentifier` se musí shodovat se souborem role (viz níže).
 * Předinstalační a postinstalační funkce jsou při sestavování manifestu automaticky detekovány. Viz [Předinstalační funkce](#pre-install-functions) a [Postinstalační funkce](#post-install-functions).

-#### Metadata Marketplace
-
-Pokud plánujete [zveřejnit svou aplikaci](/l/cs/developers/extend/apps/publishing), tato volitelná pole určují, jak se vaše aplikace zobrazuje na Marketplace:
-
-| Pole               | Popis                                                    |
-| ------------------ | -------------------------------------------------------- |
-| `author`           | Jméno autora nebo název společnosti                      |
-| `category`         | Kategorie aplikace pro filtrování na Marketplace         |
-| `logoUrl`          | Cesta k logu vaší aplikace (relativně k `./assets/`)     |
-| `screenshots`      | Pole cest ke snímkům obrazovky (relativně k `./assets/`) |
-| `aboutDescription` | Delší popis v Markdownu pro kartu "O aplikaci"           |
-| `websiteUrl`       | Odkaz na váš web                                         |
-| `termsUrl`         | Odkaz na Podmínky služby                                 |
-| `emailSupport`     | E-mailová adresa podpory                                 |
-| `issueReportUrl`   | Odkaz na nástroj pro sledování problémů                  |
-
 #### Role a oprávnění

 Aplikace mohou definovat role, které zapouzdřují oprávnění k objektům a akcím ve vašem pracovním prostoru. Pole `defaultRoleUniversalIdentifier` v `application-config.ts` určuje výchozí roli používanou logickými funkcemi vaší aplikace.
@@ -429,7 +220,7 @@ Na `universalIdentifier` této role se poté odkazuje v `application-config.ts`

 Poznámky:

-* Začněte vygenerovanou rolí a postupně ji omezujte podle principu nejmenších oprávnění.
+* Začněte rolí vytvořenou scaffolderem a postupně ji omezujte podle principu nejmenších oprávnění.
 * Nahraďte `objectPermissions` a `fieldPermissions` objekty/poli, která vaše funkce potřebují.
 * `permissionFlags` řídí přístup k schopnostem na úrovni platformy. Držte je na minimu; přidávejte pouze to, co potřebujete.
 * Podívejte se na funkční příklad v aplikaci Hello World: [`packages/twenty-apps/hello-world/src/roles/function-role.ts`](https://github.com/twentyhq/twenty/blob/main/packages/twenty-apps/hello-world/src/roles/function-role.ts).
@@ -439,7 +230,7 @@ Poznámky:
 Každý soubor funkce používá `defineLogicFunction()` k exportu konfigurace s obslužnou funkcí (handlerem) a volitelnými spouštěči.

 ```typescript
-// src/logic-functions/createPostCard.logic-function.ts
+// 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';
@@ -533,7 +324,7 @@ export default definePreInstallLogicFunction({
 Předinstalační funkci můžete také kdykoli spustit ručně pomocí CLI:

 ```bash filename="Terminal"
-yarn twenty exec --preInstall
+yarn twenty function:execute --preInstall
 ```

 Hlavní body:
@@ -543,7 +334,7 @@ Hlavní body:
 * Na jednu aplikaci je povolena pouze jedna předinstalační funkce. Sestavení manifestu skončí chybou, pokud je zjištěna více než jedna.
 * Identifikátor `universalIdentifier` funkce se během sestavení automaticky nastaví v manifestu aplikace jako `preInstallLogicFunctionUniversalIdentifier` — není potřeba jej uvádět v `defineApplication()`.
 * Výchozí časový limit je nastaven na 300 sekund (5 minut), aby umožnil delší přípravné úlohy.
-* Předinstalační funkce nepotřebují spouštěče — platforma je vyvolává před instalací nebo je lze spustit ručně pomocí `exec --preInstall`.
+* Předinstalační funkce nepotřebují spouštěče — platforma je vyvolává před instalací nebo je lze spustit ručně pomocí `function:execute --preInstall`.

 ### Postinstalační funkce

@@ -571,7 +362,7 @@ export default definePostInstallLogicFunction({
 Postinstalační funkci můžete také kdykoli spustit ručně pomocí CLI:

 ```bash filename="Terminal"
-yarn twenty exec --postInstall
+yarn twenty function:execute --postInstall
 ```

 Hlavní body:
@@ -581,7 +372,7 @@ Hlavní body:
 * Na jednu aplikaci je povolena pouze jedna postinstalační funkce. Sestavení manifestu skončí chybou, pokud je zjištěna více než jedna.
 * Identifikátor `universalIdentifier` funkce se během sestavení automaticky nastaví v manifestu aplikace jako `postInstallLogicFunctionUniversalIdentifier` — není potřeba jej uvádět v `defineApplication()`.
 * Výchozí časový limit je nastaven na 300 sekund (5 minut), aby umožnil delší úlohy nastavení, jako je naplnění daty.
-* Postinstalační funkce nepotřebují spouštěče — jsou spouštěny platformou během instalace nebo ručně pomocí `exec --postInstall`.
+* Postinstalační funkce nepotřebují spouštěče — jsou spouštěny platformou během instalace nebo ručně pomocí `function:execute --postInstall`.

 ### Payload spouštěče trasy

@@ -625,15 +416,15 @@ const handler = async (event: RoutePayload) => {

 Typ `RoutePayload` má následující strukturu:

-| Vlastnost                    | Typ                                   | Popis                                                                              |
-| ---------------------------- | ------------------------------------- | ---------------------------------------------------------------------------------- |
-| `headers`                    | `Record<string, string \| undefined>` | Záhlaví HTTP (pouze ta uvedená v `forwardedRequestHeaders`)                        |
-| `queryStringParameters`      | `Record<string, string \| undefined>` | Parametry query stringu (více hodnot spojených čárkami)                            |
-| `pathParameters`             | `Record<string, string \| undefined>` | Parametry cesty extrahované ze vzoru trasy (např. `/users/:id` -> `{ id: '123' }`) |
-| `body`                       | `object \| null`                      | Parsované tělo požadavku (JSON)                                                    |
-| `isBase64Encoded`            | `boolean`                             | Zda je tělo kódováno base64                                                        |
-| `requestContext.http.method` | `string`                              | Metoda HTTP (GET, POST, PUT, PATCH, DELETE)                                        |
-| `requestContext.http.path`   | `string`                              | Nezpracovaná cesta požadavku                                                       |
+| Vlastnost                    | Typ                                   | Popis                                                                             |
+| ---------------------------- | ------------------------------------- | --------------------------------------------------------------------------------- |
+| `headers`                    | `Record<string, string \| undefined>` | Záhlaví HTTP (pouze ta uvedená v `forwardedRequestHeaders`)                       |
+| `queryStringParameters`      | `Record<string, string \| undefined>` | Parametry query stringu (více hodnot spojených čárkami)                           |
+| `pathParameters`             | `Record<string, string \| undefined>` | Parametry cesty extrahované ze vzoru trasy (např. `/users/:id` → `{ id: '123' }`) |
+| `body`                       | `object \| null`                      | Parsované tělo požadavku (JSON)                                                   |
+| `isBase64Encoded`            | `boolean`                             | Zda je tělo kódováno base64                                                       |
+| `requestContext.http.method` | `string`                              | Metoda HTTP (GET, POST, PUT, PATCH, DELETE)                                       |
+| `requestContext.http.path`   | `string`                              | Nezpracovaná cesta požadavku                                                      |

 ### Přeposílání záhlaví HTTP

@@ -675,7 +466,7 @@ const handler = async (event: RoutePayload) => {

 Nové funkce můžete vytvářet dvěma způsoby:

-* **Vygenerované**: Spusťte `yarn twenty add` a zvolte možnost přidat novou logickou funkci. Tím se vygeneruje startovací soubor s obslužnou funkcí a konfigurací.
+* **Vygenerované**: Spusťte `yarn twenty entity:add` a zvolte možnost přidat novou logickou funkci. Tím se vygeneruje startovací soubor s obslužnou funkcí a konfigurací.
 * **Ruční**: Vytvořte nový soubor `*.logic-function.ts` a použijte `defineLogicFunction()` podle stejného vzoru.

 ### Označení logické funkce jako nástroje
@@ -687,7 +478,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-client-sdk/core';
+import { CoreApiClient } from 'twenty-sdk/generated';

 const handler = async (params: { companyName: string; domain?: string }) => {
  const client = new CoreApiClient();
@@ -776,7 +567,7 @@ Hlavní body:

 Nové frontendové komponenty můžete vytvořit dvěma způsoby:

-* **Vygenerované**: Spusťte `yarn twenty add` a zvolte možnost přidat novou frontendovou komponentu.
+* **Vygenerované**: Spusťte `yarn twenty entity:add` a zvolte možnost přidat novou frontendovou komponentu.
 * **Ruční**: Vytvořte nový soubor `.tsx` a použijte `defineFrontComponent()`, podle stejného vzoru.

 ### Dovednosti
@@ -811,122 +602,47 @@ Hlavní body:

 Nové dovednosti můžete vytvářet dvěma způsoby:

-* **Vygenerované**: Spusťte `yarn twenty add` a zvolte možnost přidat novou dovednost.
+* **Vygenerované**: Spusťte `yarn twenty entity:add` a zvolte možnost přidat novou dovednost.
 * **Ruční**: Vytvořte nový soubor a použijte `defineSkill()` podle stejného vzoru.

-### Typovaní klienti API (`twenty-client-sdk`)
+### Generované typované klienty

-Balíček `twenty-client-sdk` poskytuje dva typované klienty GraphQL pro práci s Twenty API z vašich logických funkcí a frontendových komponent:
+Dva typovaní klienti jsou automaticky generováni pomocí `yarn twenty dev` a ukládají se do `node_modules/twenty-sdk/generated` podle schématu vašeho pracovního prostoru:

-| Klient              | Importovat                   | Koncový bod                                                      | Generováno?                    |
-| ------------------- | ---------------------------- | ---------------------------------------------------------------- | ------------------------------ |
-| `CoreApiClient`     | `twenty-client-sdk/core`     | `/graphql` — data pracovního prostoru (záznamy, objekty)         | Ano, při vývoji/sestavení      |
-| `MetadataApiClient` | `twenty-client-sdk/metadata` | `/metadata` — konfigurace pracovního prostoru, nahrávání souborů | Ne, dodává se předem sestavený |
-
-#### CoreApiClient
-
-`CoreApiClient` je hlavní klient pro dotazování a mutace dat pracovního prostoru. Generuje se z vašeho schématu pracovního prostoru během `yarn twenty dev` nebo `yarn twenty build`, takže je plně typovaný tak, aby odpovídal vašim objektům a polím.
+* **`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 } from 'twenty-client-sdk/core';
+import { CoreApiClient, MetadataApiClient } from 'twenty-sdk/generated';

 const client = new CoreApiClient();
-
-// Query records
-const { companies } = await client.query({
-  companies: {
-    edges: {
-      node: {
-        id: true,
-        name: true,
-        domainName: true,
-      },
-    },
-  },
-});
-
-// Create a record
-const { createCompany } = await client.mutation({
-  createCompany: {
-    __args: {
-      data: {
-        name: 'Acme Corp',
-      },
-    },
-    id: true,
-    name: true,
-  },
-});
-```
-
-Klient používá syntaxi výběrové sady (selection-set): předáním `true` zahrnete pole, pro argumenty použijte `__args` a pro relace vnořujte objekty. Získáte plné automatické doplňování a kontrolu typů založené na schématu vašeho pracovního prostoru.
-
-<Note>
-**CoreApiClient je generován při vývoji/sestavení.** Pokud se jej pokusíte použít bez předchozího spuštění `yarn twenty dev` nebo `yarn twenty build`, vyvolá chybu. Generování probíhá automaticky — CLI prozkoumá GraphQL schéma vašeho pracovního prostoru, vygeneruje typovaného klienta pomocí `@genql/cli`, zapíše vygenerované zdrojové soubory do `node_modules/twenty-client-sdk/dist/core/generated/` a nahradí zástupné soubory v `node_modules/twenty-client-sdk/dist/core.mjs` a `node_modules/twenty-client-sdk/dist/core.cjs`.
-</Note>
-
-#### Použití CoreSchema pro anotace typů
-
-`CoreSchema` poskytuje typy TypeScriptu odpovídající objektům vašeho pracovního prostoru; je užitečný pro typování stavu komponent nebo parametrů funkcí:
-
-```typescript
-import { CoreApiClient, CoreSchema } from 'twenty-client-sdk/core';
-import { useState } from 'react';
-
-const [company, setCompany] = useState<
-  Pick<CoreSchema.Company, 'id' | 'name'> | undefined
->(undefined);
-
-const client = new CoreApiClient();
-const result = await client.query({
-  company: {
-    __args: { filter: { position: { eq: 1 } } },
-    id: true,
-    name: true,
-  },
-});
-setCompany(result.company);
-```
-
-#### MetadataApiClient
-
-`MetadataApiClient` je součástí SDK již předem sestavený (není vyžadována žádná generace). Odesílá dotazy na endpoint `/metadata` pro konfiguraci pracovního prostoru, aplikace a nahrávání souborů:
-
-```typescript
-import { MetadataApiClient } from 'twenty-client-sdk/metadata';
+const { me } = await client.query({ me: { id: true, displayName: true } });

 const metadataClient = new MetadataApiClient();
-
-// Query workspace info
-const { currentWorkspace } = await metadataClient.query({
-  currentWorkspace: { id: true, displayName: true },
-});
-
-// List installed applications
-const { findManyApplications } = await metadataClient.query({
-  findManyApplications: {
-    id: true,
-    name: true,
-    version: true,
-  },
-});
+const { currentWorkspace } = await metadataClient.query({ currentWorkspace: { id: true } });
 ```

-#### Běhové přihlašovací údaje
+Oba klienti se automaticky znovu generují pomocí `yarn twenty dev` kdykoli se změní vaše objekty nebo pole.

-Když váš kód běží na Twenty (logické funkce nebo frontendové komponenty), platforma vloží přihlašovací údaje jako proměnné prostředí:
+#### Běhové přihlašovací údaje v logických funkcích

-* `TWENTY_API_URL` — Základní URL Twenty API
-* `TWENTY_API_KEY` — Krátkodobý klíč s rozsahem omezeným na výchozí roli funkce vaší aplikace
+Když vaše funkce běží na Twenty, platforma před spuštěním kódu vloží přihlašovací údaje jako proměnné prostředí:

-Není nutné je předávat klientům — čtou je automaticky z `process.env`. Oprávnění API klíče jsou určena rolí uvedenou v `defaultRoleUniversalIdentifier` ve vašem `application-config.ts`.
+* `TWENTY_API_URL`: Základní URL Twenty API, na které vaše aplikace cílí.
+* `TWENTY_API_KEY`: Krátkodobý klíč s rozsahem omezeným na výchozí roli funkce vaší aplikace.
+
+Poznámky:
+
+* Není nutné předávat URL ani klíč API vygenerovanému klientovi. Za běhu čte `TWENTY_API_URL` a `TWENTY_API_KEY` z process.env.
+* Oprávnění klíče API jsou určena rolí odkazovanou ve vašem `application-config.ts` prostřednictvím `defaultRoleUniversalIdentifier`. Toto je výchozí role používaná logickými funkcemi vaší aplikace.
+* Aplikace mohou definovat role podle principu nejmenších oprávnění. Udělte pouze oprávnění, která vaše funkce potřebují, a poté nastavte `defaultRoleUniversalIdentifier` na univerzální identifikátor této role.

 #### Nahrávání souborů

-`MetadataApiClient` obsahuje metodu `uploadFile` pro připojování souborů k polím typu souboru. Implementuje [specifikaci GraphQL multipart request](https://github.com/jaydenseric/graphql-multipart-request-spec):
+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).

 ```typescript
-import { MetadataApiClient } from 'twenty-client-sdk/metadata';
+import { MetadataApiClient } from 'twenty-sdk/generated';
 import * as fs from 'fs';

 const metadataClient = new MetadataApiClient();
@@ -936,14 +652,25 @@ const fileBuffer = fs.readFileSync('./invoice.pdf');
 const uploadedFile = await metadataClient.uploadFile(
  fileBuffer,                                         // file contents as a Buffer
  'invoice.pdf',                                      // filename
-  'application/pdf',                                  // MIME type
-  '58a0a314-d7ea-4865-9850-7fb84e72f30b',            // field universalIdentifier
+  'application/pdf',                                  // MIME type (defaults to 'application/octet-stream')
+  '58a0a314-d7ea-4865-9850-7fb84e72f30b',            // field universal identifier
 );

 console.log(uploadedFile);
 // { id: '...', path: '...', size: 12345, createdAt: '...', url: 'https://...' }
 ```

+Signatura metody:
+
+```typescript
+uploadFile(
+  fileBuffer: Buffer,
+  filename: string,
+  contentType: string,
+  fieldMetadataUniversalIdentifier: string,
+): Promise<{ id: string; path: string; size: number; createdAt: string; url: string }>
+```
+
 | Parametr                           | Typ      | Popis                                                                       |
 | ---------------------------------- | -------- | --------------------------------------------------------------------------- |
 | `fileBuffer`                       | `Buffer` | Surový obsah souboru                                                        |
@@ -953,7 +680,8 @@ console.log(uploadedFile);

 Hlavní body:

-* Používá `universalIdentifier` pole (nikoli jeho ID specifické pro pracovní prostor), takže váš kód pro nahrávání funguje v jakémkoli pracovním prostoru, kde je vaše aplikace nainstalována.
+* Metoda `uploadFile` je k dispozici v `MetadataApiClient`, protože mutaci nahrávání obsluhuje endpoint `/metadata`.
+* Používá `universalIdentifier` pole (nikoli jeho ID specifické pro pracovní prostor), takže váš kód pro nahrávání funguje ve všech pracovních prostorech, kde je vaše aplikace nainstalována — v souladu s tím, jak aplikace odkazují na pole všude jinde.
 * Vrácená hodnota `url` je podepsaná adresa URL, kterou můžete použít k přístupu k nahranému souboru.

 ### Příklad Hello World
@@ -49,7 +49,7 @@ Odtud můžete:

 ```bash filename="Terminal"
 # Add a new entity to your application (guided)
-yarn twenty add
+yarn twenty entity:add

 # Watch your application's function logs
 yarn twenty function:logs
@@ -123,7 +123,7 @@ S volbou `--minimal` se vytvoří pouze základní soubory (`application-config.
 V kostce:

 * **package.json**: Deklaruje název aplikace, verzi, engines (Node 24+, Yarn 4) a přidává `twenty-sdk` plus skript `twenty`, který deleguje na lokální `twenty` CLI. Spusťte `yarn twenty help` pro výpis všech dostupných příkazů.
-* **.gitignore**: Ignores common artifacts such as `node_modules`, `.yarn`, `.twenty/`, `dist/`, `build/`, coverage folders, log files, and `.env*` files.
+* **.gitignore**: Ignoruje běžné artefakty jako `node_modules`, `.yarn`, `generated/` (typovaný klient), `dist/`, `build/`, složky s coverage, logy a soubory `.env*`.
 * **yarn.lock**, **.yarnrc.yml**, **.yarn/**: Zamykají a konfigurují nástrojový řetězec Yarn 4 používaný projektem.
 * **.nvmrc**: Fixuje verzi Node.js požadovanou projektem.
 * **.oxlintrc.json** a **tsconfig.json**: Poskytují lintování a konfiguraci TypeScriptu pro zdrojové soubory vaší aplikace v TypeScriptu.
@@ -167,8 +167,8 @@ export default defineObject({

 Pozdější příkazy přidají další soubory a složky:

-* `yarn twenty dev` will auto-generate the typed `CoreApiClient` (for workspace data via `/graphql`) into `node_modules/twenty-client-sdk/`. The `MetadataApiClient` (for workspace configuration and file uploads via `/metadata`) ships pre-built and is available immediately. Import them from `twenty-client-sdk/core` and `twenty-client-sdk/metadata` respectively.
-* `yarn twenty add` will add entity definition files under `src/` for your custom objects, functions, front components, roles, skills, and more.
+* `yarn twenty 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 entity:add` přidá soubory s definicemi entit do `src/` pro vaše vlastní objekty, funkce, frontové komponenty, role, dovednosti a další.

 ## Ověření

@@ -12,25 +12,7 @@ Aplikace jsou aktuálně v alfa testování. Tato funkce je funkční, ale stál
 Jakmile je vaše aplikace [sestavena a otestována lokálně](/l/cs/developers/extend/apps/building), máte dvě cesty, jak ji distribuovat:

 * **Publish to npm** — uveďte svou aplikaci v Marketplace Twenty, aby ji mohl kterýkoli pracovní prostor objevit a nainstalovat.
-* **Nasaďte tarball** — nahrajte svou aplikaci přímo na konkrétní server Twenty pro interní nebo soukromé použití.
-
-Obě cesty začínají stejným krokem **build**.
-
-## Sestavení vaší aplikace
-
-Příkaz `build` zkompiluje vaše zdrojové soubory TypeScriptu, transpiluje logické funkce a frontendové komponenty a vygeneruje soubor `manifest.json`, který popisuje obsah vaší aplikace:
-
-```bash filename="Terminal"
-yarn twenty build
-```
-
-Výstup se zapisuje do `.twenty/output/`. This directory contains everything needed for distribution: compiled code, assets, the manifest, and a copy of your `package.json`.
-
-To also create a `.tgz` tarball (used by the deploy command internally, or for manual distribution):
-
-```bash filename="Terminal"
-yarn twenty build --tarball
-```
+* **Odeslat tarball** — nasaďte svou aplikaci na konkrétní server Twenty pro interní použití, aniž by byla veřejně dostupná.

 ## Publikování na npm

@@ -39,72 +21,29 @@ Publikování na npm zajistí, že bude vaše aplikace dohledatelná v Marketpla
 ### Požadavky

 * Účet na [npm](https://www.npmjs.com)
-* The `twenty-app` keyword **must** be listed in your `package.json` `keywords` array
-
-### Adding the required keyword
-
-The Twenty marketplace discovers apps by searching the npm registry for packages with the `twenty-app` keyword. Add it to your `package.json`:
-
-```json filename="package.json"
-{
-  "name": "twenty-app-postcard-sender",
-  "version": "1.0.0",
-  "keywords": ["twenty-app"],
-  ...
-}
-```
-
-<Note>
-The marketplace searches for `keywords:twenty-app` on the npm registry. Without this keyword, your package won't appear in the marketplace even if it has the `twenty-app-` name prefix.
-</Note>
+* Název vašeho balíčku **musí** používat předponu `twenty-app-` (např. `twenty-app-postcard-sender`)

 ### Postup

-1. **Build your app:**
+1. **Sestavte svou aplikaci** — CLI zkompiluje vaše zdrojové soubory TypeScript a vygeneruje manifest aplikace:

 ```bash filename="Terminal"
 yarn twenty build
 ```

-2. **Publish to npm:**
+2. **Publikujte na npm** — odešlete sestavený balíček do registru npm:

 ```bash filename="Terminal"
-yarn twenty publish
+npx twenty publish
 ```

-This runs `npm publish` from the `.twenty/output/` directory.
+### Automatické rozpoznání

-To publish under a specific dist-tag (e.g., `beta` or `next`):
-
-```bash filename="Terminal"
-yarn twenty publish --tag beta
-```
-
-### How marketplace discovery works
-
-The Twenty server syncs its marketplace catalog from the npm registry **every hour**:
-
-1. It searches for all npm packages with the `keywords:twenty-app` keyword
-2. For each package, it fetches the `manifest.json` from the npm CDN
-3. The app's metadata (name, description, author, logo, screenshots, category) is extracted from the manifest and displayed in the marketplace
-
-After publishing, your app can take up to one hour to appear in the marketplace. To trigger the sync immediately instead of waiting for the next hourly run:
-
-```bash filename="Terminal"
-yarn twenty catalog-sync
-```
-
-To target a specific remote:
-
-```bash filename="Terminal"
-yarn twenty catalog-sync -r production
-```
-
-The metadata shown in the marketplace comes from your `defineApplication()` call in your app source code — fields like `displayName`, `description`, `author`, `category`, `logoUrl`, `screenshots`, `aboutDescription`, `websiteUrl`, and `termsUrl`.
+Balíčky s předponou `twenty-app-` jsou automaticky rozpoznávány katalogem Marketplace Twenty. Po publikování se vaše aplikace během několika minut objeví v Marketplace — nevyžaduje žádnou ruční registraci ani schvalování.

 ### Publikování pomocí CI

-Vygenerovaný projekt obsahuje pracovní postup GitHub Actions, který publikuje při každém vydání:
+Vygenerovaný projekt obsahuje pracovní postup GitHub Actions, který publikuje při každém vydání. Spouští `app:build`, a poté `npm publish --provenance` z výstupu buildu:

 ```yaml filename=".github/workflows/publish.yml"
 name: Publish
@@ -133,117 +72,48 @@ jobs:
          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
 ```

-For other CI systems (GitLab CI, CircleCI, etc.), the same three commands apply: `yarn install`, `yarn twenty build`, then `npm publish` from `.twenty/output`.
+Pro jiné systémy CI (GitLab CI, CircleCI atd.) platí stejné tři příkazy: `yarn install`, `npx twenty build` a poté `npm publish` z `.twenty/output`.

 <Tip>
 **npm provenance** je volitelné, ale doporučené. Publikování s `--provenance` přidá k vašemu záznamu na npm odznak důvěryhodnosti a umožní uživatelům ověřit, že balíček byl sestaven z konkrétního commitu ve veřejné CI pipeline. Pokyny k nastavení najdete v [dokumentaci k npm provenance](https://docs.npmjs.com/generating-provenance-statements).
 </Tip>

-## Deploying to a server (tarball)
+## Interní distribuce

-For apps you don't want publicly available — proprietary tools, enterprise-only integrations, or experimental builds — you can deploy a tarball directly to a Twenty server.
+Pro aplikace, které nechcete zpřístupnit veřejně — proprietární nástroje, integrace pouze pro enterprise nebo experimentální buildy — můžete odeslat tarball přímo na server Twenty.

-### Předpoklady
+### Odeslat tarball

-Before deploying, you need a configured remote pointing to the target server. Remotes store the server URL and authentication credentials locally in `~/.twenty/config.json`.
-
-Add a remote:
+Sestavte svou aplikaci a nasaďte ji na konkrétní server v jednom kroku:

 ```bash filename="Terminal"
-yarn twenty remote add --url https://your-twenty-server.com --as production
+npx twenty publish --server <server-url>
 ```

-For a local development server:
-
-```bash filename="Terminal"
-yarn twenty remote add --local --as local
-```
-
-You can also authenticate with an API key for non-interactive environments:
-
-```bash filename="Terminal"
-yarn twenty remote add --url https://your-twenty-server.com --token <api-key> --as production
-```
-
-Manage your remotes:
-
-```bash filename="Terminal"
-yarn twenty remote list       # List all configured remotes
-yarn twenty remote switch prod # Set the default remote
-yarn twenty remote status     # Show active remote and auth status
-yarn twenty remote remove old # Remove a remote
-```
-
-### Deploying
-
-Build and upload your app to the server in one step:
-
-```bash filename="Terminal"
-yarn twenty deploy
-```
-
-This builds the app with `--tarball`, then uploads the tarball to the default remote via a GraphQL multipart upload.
-
-To deploy to a specific remote:
-
-```bash filename="Terminal"
-yarn twenty deploy -r production
-```
-
-### Sharing a deployed app
-
-Tarball apps are not listed in the public marketplace, so other workspaces on the same server won't discover them by browsing. To share a deployed app:
-
-1. Go to **Settings > Applications > Registrations** and open your app
-2. In the **Distribution** tab, click **Copy share link**
-3. Share this link with users on other workspaces — it takes them directly to the app's install page
-
-The share link uses the server's base URL (without any workspace subdomain) so it works for any workspace on the server.
+Jakýkoli pracovní prostor na tomto serveru pak může aplikaci instalovat a aktualizovat ze stránky nastavení **Applications**.

 ### Správa verzí

 Chcete-li vydat aktualizaci:

 1. Zvyšte hodnotu pole `version` v souboru `package.json`
-2. Run `yarn twenty deploy` (or `yarn twenty deploy -r production`)
-3. Workspaces that have the app installed will see the upgrade available in their settings
+2. Odešlete nový tarball pomocí `npx twenty publish --server <server-url>`
+3. Pracovní prostory na tomto serveru uvidí dostupnou aktualizaci ve svém nastavení

-## Installing apps
+<Note>
+Interní aplikace jsou omezené na server, na který jsou odeslány. Nezobrazí se ve veřejném Marketplace a nelze je instalovat v pracovních prostorech na jiných serverech.
+</Note>

-Once an app is published (npm) or deployed (tarball), workspaces install it through the UI:
-
-```bash filename="Terminal"
-yarn twenty install
-```
-
-Or from the **Settings > Applications** page in the Twenty UI, where both marketplace and tarball-deployed apps can be browsed and installed.
-
-## App distribution categories
+## Kategorie aplikací

 Twenty organizuje aplikace do tří kategorií podle způsobu distribuce:

-| Kategorie              | Jak to funguje                                                                                                                   | Viditelné v Marketplace? |
-| ---------------------- | -------------------------------------------------------------------------------------------------------------------------------- | ------------------------ |
-| **Vývoj**              | Aplikace v místním vývojářském režimu spuštěné přes `yarn twenty dev`. Slouží k sestavování a testování.                         | Ne                       |
-| **Published (npm)**    | Apps published to npm with the `twenty-app` keyword. Uvedeny v Marketplace, aby je mohl kterýkoli pracovní prostor nainstalovat. | Ano                      |
-| **Internal (tarball)** | Aplikace nasazené pomocí tarballu na konkrétní server. Available only to workspaces on that server via a share link.             | Ne                       |
+| Kategorie       | Jak to funguje                                                                                                                     | Viditelné v Marketplace? |
+| --------------- | ---------------------------------------------------------------------------------------------------------------------------------- | ------------------------ |
+| **Vývoj**       | Aplikace v místním vývojářském režimu spuštěné přes `yarn twenty dev`. Slouží k sestavování a testování.                           | Ne                       |
+| **Publikováno** | Aplikace publikované na npm s předponou `twenty-app-`. Uvedeny v Marketplace, aby je mohl kterýkoli pracovní prostor nainstalovat. | Ano                      |
+| **Interní**     | Aplikace nasazené pomocí tarballu na konkrétní server. Dostupné pouze pro pracovní prostory na tomto serveru.                      | Ne                       |

 <Tip>
 Začněte v režimu **Development** při sestavování své aplikace. Až bude připravena, zvolte **Published** (npm) pro širokou distribuci nebo **Internal** (tarball) pro soukromé nasazení.
 </Tip>
-
-## CLI reference
-
-| Příkaz                      | Popis                                          | Key flags                                           |
-| --------------------------- | ---------------------------------------------- | --------------------------------------------------- |
-| `yarn twenty build`         | Compile app and generate manifest              | `--tarball` — also create a `.tgz` package          |
-| `yarn twenty publish`       | Build and publish to npm                       | `--tag <tag>` — npm dist-tag (e.g., `beta`, `next`) |
-| `yarn twenty deploy`        | Build and upload tarball to a server           | `-r, --remote <name>` — target remote               |
-| `yarn twenty catalog-sync`  | Trigger marketplace catalog sync on the server | `-r, --remote <name>` — target remote               |
-| `yarn twenty install`       | Install a deployed app on a workspace          | `-r, --remote <name>` — target remote               |
-| `yarn twenty dev`           | Watch and sync local changes                   | Uses default remote                                 |
-| `yarn twenty remote add`    | Add a server connection                        | `--url`, `--token`, `--as`, `--local`, `--port`     |
-| `yarn twenty remote list`   | List configured remotes                        | —                                                   |
-| `yarn twenty remote switch` | Set default remote                             | —                                                   |
-| `yarn twenty remote status` | Show connection status                         | —                                                   |
-| `yarn twenty remote remove` | Remove a remote                                | —                                                   |
@@ -15,21 +15,19 @@ Das twenty-sdk stellt typisierte Bausteine und Hilfsfunktionen bereit, die Sie i

 Das SDK stellt Hilfsfunktionen bereit, um die Entitäten Ihrer App zu definieren. Wie in [Entitätserkennung](/l/de/developers/extend/apps/getting-started#entity-detection) beschrieben, müssen Sie `export default define<Entity>({...})` verwenden, damit Ihre Entitäten erkannt werden:

-| Funktion                         | Zweck                                                                                                    |
-| -------------------------------- | -------------------------------------------------------------------------------------------------------- |
-| `defineApplication`              | Anwendungsmetadaten konfigurieren (erforderlich, eine pro App)                                           |
-| `defineObject`                   | Benutzerdefinierte Objekte mit Feldern definieren                                                        |
-| `defineField`                    | Erweitern Sie bestehende Objekte um zusätzliche Felder oder definieren Sie eigenständige Relationsfelder |
-| `defineLogicFunction`            | Logikfunktionen mit Handlern definieren                                                                  |
-| `definePreInstallLogicFunction`  | Eine Pre-Installations-Logikfunktion definieren (eine pro App)                                           |
-| `definePostInstallLogicFunction` | Eine Post-Installations-Logikfunktion definieren (eine pro App)                                          |
-| `defineFrontComponent`           | Frontend-Komponenten für benutzerdefinierte UI definieren                                                |
-| `defineRole`                     | Rollenberechtigungen und Objektzugriff konfigurieren                                                     |
-| `defineView`                     | Gespeicherte Views für Objekte definieren                                                                |
-| `defineNavigationMenuItem`       | Seitenleisten-Navigationslinks definieren                                                                |
-| `defineSkill`                    | Skills für KI-Agenten definieren                                                                         |
-| `defineAgent`                    | KI-Agenten definieren                                                                                    |
-| `definePageLayout`               | Benutzerdefinierte Seitenlayouts definieren                                                              |
+| Funktion                         | Zweck                                                           |
+| -------------------------------- | --------------------------------------------------------------- |
+| `defineApplication`              | Anwendungsmetadaten konfigurieren (erforderlich, eine pro App)  |
+| `defineObject`                   | Benutzerdefinierte Objekte mit Feldern definieren               |
+| `defineLogicFunction`            | Logikfunktionen mit Handlern definieren                         |
+| `definePreInstallLogicFunction`  | Eine Pre-Installations-Logikfunktion definieren (eine pro App)  |
+| `definePostInstallLogicFunction` | Eine Post-Installations-Logikfunktion definieren (eine pro App) |
+| `defineFrontComponent`           | Frontend-Komponenten für benutzerdefinierte UI definieren       |
+| `defineRole`                     | Rollenberechtigungen und Objektzugriff konfigurieren            |
+| `defineField`                    | Bestehende Objekte mit zusätzlichen Feldern erweitern           |
+| `defineView`                     | Gespeicherte Views für Objekte definieren                       |
+| `defineNavigationMenuItem`       | Seitenleisten-Navigationslinks definieren                       |
+| `defineSkill`                    | Skills für KI-Agenten definieren                                |

 Diese Funktionen validieren Ihre Konfiguration zur Build-Zeit und bieten IDE-Autovervollständigung sowie Typsicherheit.

@@ -38,7 +36,7 @@ Diese Funktionen validieren Ihre Konfiguration zur Build-Zeit und bieten IDE-Aut
 Benutzerdefinierte Objekte beschreiben sowohl Schema als auch Verhalten für Datensätze in Ihrem Workspace. Verwenden Sie `defineObject()`, um Objekte mit eingebauter Validierung zu definieren:

 ```typescript
-// src/objects/postCard.object.ts
+// src/app/postCard.object.ts
 import { defineObject, FieldType } from 'twenty-sdk';

 enum PostCardStatus {
@@ -112,7 +110,7 @@ Hauptpunkte:
 * Der `universalIdentifier` muss eindeutig und über Deployments hinweg stabil sein.
 * Jedes Feld benötigt `name`, `type`, `label` und einen eigenen stabilen `universalIdentifier`.
 * Das Array `fields` ist optional — Sie können Objekte ohne benutzerdefinierte Felder definieren.
-* Sie können mit `yarn twenty add` neue Objekte erzeugen; der Assistent führt Sie durch Benennung, Felder und Beziehungen.
+* Sie können mit `yarn twenty entity:add` neue Objekte erzeugen; der Assistent führt Sie durch Benennung, Felder und Beziehungen.

 <Note>
 **Basisfelder werden automatisch erstellt.** Wenn Sie ein benutzerdefiniertes Objekt definieren, fügt Twenty automatisch Standardfelder hinzu
@@ -122,197 +120,6 @@ Sie können Standardfelder überschreiben, indem Sie in Ihrem `fields`-Array ein
 dies wird jedoch nicht empfohlen.
 </Note>

-### Felder für bestehende Objekte definieren
-
-Verwenden Sie `defineField()`, um Objekten, die Ihnen nicht gehören — etwa Standardobjekten von Twenty (Person, Company usw.) — Felder hinzuzufügen oder Objekten aus anderen Apps. Im Gegensatz zu Inline-Feldern in `defineObject()` benötigen eigenständige Felder einen `objectUniversalIdentifier`, um anzugeben, welches Objekt sie erweitern:
-
-```typescript
-// src/fields/company-loyalty-tier.field.ts
-import { defineField, FieldType } from 'twenty-sdk';
-
-export default defineField({
-  universalIdentifier: 'f2a1b3c4-d5e6-7890-abcd-ef1234567890',
-  objectUniversalIdentifier: '701aecb9-eb1c-4d84-9d94-b954b231b64b', // Company object
-  name: 'loyaltyTier',
-  type: FieldType.SELECT,
-  label: 'Loyalty Tier',
-  icon: 'IconStar',
-  options: [
-    { value: 'BRONZE', label: 'Bronze', position: 0, color: 'orange' },
-    { value: 'SILVER', label: 'Silver', position: 1, color: 'gray' },
-    { value: 'GOLD', label: 'Gold', position: 2, color: 'yellow' },
-  ],
-});
-```
-
-Hauptpunkte:
-
-* Der `objectUniversalIdentifier` identifiziert das Zielobjekt. Für Standardobjekte verwenden Sie `STANDARD_OBJECT_UNIVERSAL_IDENTIFIERS`, die aus `twenty-sdk` exportiert werden.
-* Wenn Sie Felder inline in `defineObject()` definieren, benötigen Sie `objectUniversalIdentifier` **nicht** — er wird vom übergeordneten Objekt geerbt.
-* `defineField()` ist die einzige Möglichkeit, Felder zu Objekten hinzuzufügen, die Sie nicht mit `defineObject()` erstellt haben.
-
-### Beziehungen
-
-Relationen verbinden Objekte miteinander. In Twenty sind Relationen stets **bidirektional** — Sie definieren beide Seiten, und jede Seite referenziert die andere.
-
-Es gibt zwei Relationstypen:
-
-| Beziehungstyp | Beschreibung                                                            | Fremdschlüssel vorhanden? |
-| ------------- | ----------------------------------------------------------------------- | ------------------------- |
-| `MANY_TO_ONE` | Viele Datensätze dieses Objekts verweisen auf einen Datensatz des Ziels | Ja (`joinColumnName`)     |
-| `ONE_TO_MANY` | Ein Datensatz dieses Objekts hat viele Datensätze des Ziels             | Nein (inverse Seite)      |
-
-#### Wie Relationen funktionieren
-
-Jede Relation erfordert **zwei Felder**, die sich gegenseitig referenzieren:
-
-1. Die **MANY_TO_ONE**-Seite — befindet sich auf dem Objekt, das den Fremdschlüssel hält
-2. Die **ONE_TO_MANY**-Seite — befindet sich auf dem Objekt, dem die Sammlung gehört
-
-Beide Felder verwenden `FieldType.RELATION` und verweisen über `relationTargetFieldMetadataUniversalIdentifier` gegenseitig aufeinander.
-
-#### Beispiel: Postkarte hat viele Empfänger
-
-Angenommen, eine `PostCard` kann an viele `PostCardRecipient`-Datensätze gesendet werden. Jeder Empfänger gehört genau zu einer Postkarte.
-
-**Schritt 1: Definieren Sie die ONE_TO_MANY-Seite auf PostCard** (die "eine" Seite):
-
-```typescript
-// src/fields/post-card-recipients-on-post-card.field.ts
-import { defineField, FieldType, RelationType } from 'twenty-sdk';
-import { POST_CARD_UNIVERSAL_IDENTIFIER } from '../objects/post-card.object';
-import { POST_CARD_RECIPIENT_UNIVERSAL_IDENTIFIER } from '../objects/post-card-recipient.object';
-
-// Export so the other side can reference it
-export const POST_CARD_RECIPIENTS_FIELD_ID = 'a1111111-1111-1111-1111-111111111111';
-// Import from the other side
-import { POST_CARD_FIELD_ID } from './post-card-on-post-card-recipient.field';
-
-export default defineField({
-  universalIdentifier: POST_CARD_RECIPIENTS_FIELD_ID,
-  objectUniversalIdentifier: POST_CARD_UNIVERSAL_IDENTIFIER,
-  type: FieldType.RELATION,
-  name: 'postCardRecipients',
-  label: 'Post Card Recipients',
-  icon: 'IconUsers',
-  relationTargetObjectMetadataUniversalIdentifier: POST_CARD_RECIPIENT_UNIVERSAL_IDENTIFIER,
-  relationTargetFieldMetadataUniversalIdentifier: POST_CARD_FIELD_ID,
-  universalSettings: {
-    relationType: RelationType.ONE_TO_MANY,
-  },
-});
-```
-
-**Schritt 2: Definieren Sie die MANY_TO_ONE-Seite auf PostCardRecipient** (die "viele" Seite — hält den Fremdschlüssel):
-
-```typescript
-// src/fields/post-card-on-post-card-recipient.field.ts
-import { defineField, FieldType, RelationType, OnDeleteAction } from 'twenty-sdk';
-import { POST_CARD_UNIVERSAL_IDENTIFIER } from '../objects/post-card.object';
-import { POST_CARD_RECIPIENT_UNIVERSAL_IDENTIFIER } from '../objects/post-card-recipient.object';
-
-// Export so the other side can reference it
-export const POST_CARD_FIELD_ID = 'b2222222-2222-2222-2222-222222222222';
-// Import from the other side
-import { POST_CARD_RECIPIENTS_FIELD_ID } from './post-card-recipients-on-post-card.field';
-
-export default defineField({
-  universalIdentifier: POST_CARD_FIELD_ID,
-  objectUniversalIdentifier: POST_CARD_RECIPIENT_UNIVERSAL_IDENTIFIER,
-  type: FieldType.RELATION,
-  name: 'postCard',
-  label: 'Post Card',
-  icon: 'IconMail',
-  relationTargetObjectMetadataUniversalIdentifier: POST_CARD_UNIVERSAL_IDENTIFIER,
-  relationTargetFieldMetadataUniversalIdentifier: POST_CARD_RECIPIENTS_FIELD_ID,
-  universalSettings: {
-    relationType: RelationType.MANY_TO_ONE,
-    onDelete: OnDeleteAction.CASCADE,
-    joinColumnName: 'postCardId',
-  },
-});
-```
-
-<Note>
-**Zyklische Importe:** Beide Relationsfelder referenzieren gegenseitig den `universalIdentifier` des jeweils anderen. Um Probleme mit zyklischen Importen zu vermeiden, exportieren Sie Ihre Feld-IDs als benannte Konstanten aus jeder Datei und importieren Sie sie in der jeweils anderen Datei. Das Build-System löst dies zur Kompilierzeit auf.
-</Note>
-
-#### Relationen zu Standardobjekten
-
-Um eine Relation mit einem integrierten Twenty-Objekt (Person, Company usw.) zu erstellen, verwenden Sie `STANDARD_OBJECT_UNIVERSAL_IDENTIFIERS`:
-
-```typescript
-// src/fields/person-on-self-hosting-user.field.ts
-import {
-  defineField,
-  FieldType,
-  RelationType,
-  OnDeleteAction,
-  STANDARD_OBJECT_UNIVERSAL_IDENTIFIERS,
-} from 'twenty-sdk';
-import { SELF_HOSTING_USER_UNIVERSAL_IDENTIFIER } from '../objects/self-hosting-user.object';
-
-export const PERSON_FIELD_ID = 'c3333333-3333-3333-3333-333333333333';
-export const SELF_HOSTING_USER_REVERSE_FIELD_ID = 'd4444444-4444-4444-4444-444444444444';
-
-export default defineField({
-  universalIdentifier: PERSON_FIELD_ID,
-  objectUniversalIdentifier: SELF_HOSTING_USER_UNIVERSAL_IDENTIFIER,
-  type: FieldType.RELATION,
-  name: 'person',
-  label: 'Person',
-  description: 'Person matching with the self hosting user',
-  isNullable: true,
-  relationTargetObjectMetadataUniversalIdentifier:
-    STANDARD_OBJECT_UNIVERSAL_IDENTIFIERS.person.universalIdentifier,
-  relationTargetFieldMetadataUniversalIdentifier: SELF_HOSTING_USER_REVERSE_FIELD_ID,
-  universalSettings: {
-    relationType: RelationType.MANY_TO_ONE,
-    onDelete: OnDeleteAction.SET_NULL,
-    joinColumnName: 'personId',
-  },
-});
-```
-
-#### Eigenschaften von Relationsfeldern
-
-| Eigenschaft                                       | Erforderlich        | Beschreibung                                                                                                     |
-| ------------------------------------------------- | ------------------- | ---------------------------------------------------------------------------------------------------------------- |
-| `type`                                            | Ja                  | Muss `FieldType.RELATION` sein                                                                                   |
-| `relationTargetObjectMetadataUniversalIdentifier` | Ja                  | Der `universalIdentifier` des Zielobjekts                                                                        |
-| `relationTargetFieldMetadataUniversalIdentifier`  | Ja                  | Der `universalIdentifier` des entsprechenden Felds auf dem Zielobjekt                                            |
-| `universalSettings.relationType`                  | Ja                  | `RelationType.MANY_TO_ONE` oder `RelationType.ONE_TO_MANY`                                                       |
-| `universalSettings.onDelete`                      | Nur für MANY_TO_ONE | Was passiert, wenn der referenzierte Datensatz gelöscht wird: `CASCADE`, `SET_NULL`, `RESTRICT` oder `NO_ACTION` |
-| `universalSettings.joinColumnName`                | Nur für MANY_TO_ONE | Datenbankspaltenname für den Fremdschlüssel (z. B. `postCardId`)                                                 |
-
-#### Inline-Relationsfelder in defineObject
-
-Sie können Relationsfelder auch direkt innerhalb von `defineObject()` definieren. In diesem Fall lassen Sie `objectUniversalIdentifier` weg — er wird vom übergeordneten Objekt geerbt:
-
-```typescript
-export default defineObject({
-  universalIdentifier: '...',
-  nameSingular: 'postCardRecipient',
-  // ...
-  fields: [
-    {
-      universalIdentifier: POST_CARD_FIELD_ID,
-      type: FieldType.RELATION,
-      name: 'postCard',
-      label: 'Post Card',
-      relationTargetObjectMetadataUniversalIdentifier: POST_CARD_UNIVERSAL_IDENTIFIER,
-      relationTargetFieldMetadataUniversalIdentifier: POST_CARD_RECIPIENTS_FIELD_ID,
-      universalSettings: {
-        relationType: RelationType.MANY_TO_ONE,
-        onDelete: OnDeleteAction.CASCADE,
-        joinColumnName: 'postCardId',
-      },
-    },
-    // ... other fields
-  ],
-});
-```
-
 ### Anwendungskonfiguration (application-config.ts)

 Jede App hat eine einzelne Datei `application-config.ts`, die Folgendes beschreibt:
@@ -354,22 +161,6 @@ Notizen:
 * `defaultRoleUniversalIdentifier` muss mit der Rollendatei übereinstimmen (siehe unten).
 * Pre-Installations- und Post-Installationsfunktionen werden während des Manifest-Builds automatisch erkannt. Siehe [Pre-Installationsfunktionen](#pre-install-functions) und [Post-Installationsfunktionen](#post-install-functions).

-#### Marktplatz-Metadaten
-
-Wenn Sie planen, [Ihre App zu veröffentlichen](/l/de/developers/extend/apps/publishing), steuern diese optionalen Felder, wie Ihre App im Marktplatz erscheint:
-
-| Feld               | Beschreibung                                         |
-| ------------------ | ---------------------------------------------------- |
-| `author`           | Name des Autors oder des Unternehmens                |
-| `category`         | App-Kategorie für die Filterung im Marktplatz        |
-| `logoUrl`          | Pfad zu Ihrem App-Logo (relativ zu `./assets/`)      |
-| `screenshots`      | Array von Screenshot-Pfaden (relativ zu `./assets/`) |
-| `aboutDescription` | Längere Markdown-Beschreibung für den Tab "Info"     |
-| `websiteUrl`       | Link zu Ihrer Website                                |
-| `termsUrl`         | Link zu den Nutzungsbedingungen                      |
-| `emailSupport`     | Support-E-Mail-Adresse                               |
-| `issueReportUrl`   | Link zum Issue-Tracker                               |
-
 #### Rollen und Berechtigungen

 Anwendungen können Rollen definieren, die Berechtigungen für die Objekte und Aktionen Ihres Workspaces kapseln. Das Feld `defaultRoleUniversalIdentifier` in `application-config.ts` legt die Standardrolle fest, die von den Logikfunktionen Ihrer App verwendet wird.
@@ -439,7 +230,7 @@ Notizen:
 Jede Funktionsdatei verwendet `defineLogicFunction()`, um eine Konfiguration mit einem Handler und optionalen Triggern zu exportieren.

 ```typescript
-// src/logic-functions/createPostCard.logic-function.ts
+// 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';
@@ -533,7 +324,7 @@ export default definePreInstallLogicFunction({
 Sie können die Pre-Installationsfunktion auch jederzeit manuell über die CLI ausführen:

 ```bash filename="Terminal"
-yarn twenty exec --preInstall
+yarn twenty function:execute --preInstall
 ```

 Hauptpunkte:
@@ -543,7 +334,7 @@ Hauptpunkte:
 * Pro Anwendung ist nur eine Pre-Installationsfunktion zulässig. Der Manifest-Build schlägt fehl, wenn mehr als eine erkannt wird.
 * Der `universalIdentifier` der Funktion wird während des Builds im Anwendungsmanifest automatisch als `preInstallLogicFunctionUniversalIdentifier` gesetzt — Sie müssen ihn nicht in `defineApplication()` referenzieren.
 * Das standardmäßige Timeout ist auf 300 Sekunden (5 Minuten) festgelegt, um längere Vorbereitungsvorgänge zu ermöglichen.
-* Pre-Installationsfunktionen benötigen keine Trigger — sie werden von der Plattform vor der Installation oder manuell über `exec --preInstall` aufgerufen.
+* Pre-Installationsfunktionen benötigen keine Trigger — sie werden von der Plattform vor der Installation oder manuell über `function:execute --preInstall` aufgerufen.

 ### Post-Installationsfunktionen

@@ -571,7 +362,7 @@ export default definePostInstallLogicFunction({
 Sie können die Post-Installationsfunktion auch jederzeit manuell über die CLI ausführen:

 ```bash filename="Terminal"
-yarn twenty exec --postInstall
+yarn twenty function:execute --postInstall
 ```

 Hauptpunkte:
@@ -581,7 +372,7 @@ Hauptpunkte:
 * Pro Anwendung ist nur eine Post-Installationsfunktion zulässig. Der Manifest-Build schlägt fehl, wenn mehr als eine erkannt wird.
 * Der `universalIdentifier` der Funktion wird während des Builds im Anwendungsmanifest automatisch als `postInstallLogicFunctionUniversalIdentifier` gesetzt — Sie müssen ihn nicht in `defineApplication()` referenzieren.
 * Das standardmäßige Timeout ist auf 300 Sekunden (5 Minuten) festgelegt, um längere Einrichtungsvorgänge wie Daten-Seeding zu ermöglichen.
-* Post-Installationsfunktionen benötigen keine Trigger — sie werden von der Plattform während der Installation oder manuell über `exec --postInstall` aufgerufen.
+* Post-Installationsfunktionen benötigen keine Trigger — sie werden von der Plattform während der Installation oder manuell über `function:execute --postInstall` aufgerufen.

 ### Routen-Trigger-Payload

@@ -625,15 +416,15 @@ const handler = async (event: RoutePayload) => {

 Der Typ `RoutePayload` hat die folgende Struktur:

-| Eigenschaft                  | Typ                                   | Beschreibung                                                                           |
-| ---------------------------- | ------------------------------------- | -------------------------------------------------------------------------------------- |
-| `headers`                    | `Record<string, string \| undefined>` | HTTP-Header (nur die in `forwardedRequestHeaders` aufgelisteten)                       |
-| `queryStringParameters`      | `Record<string, string \| undefined>` | Query-String-Parameter (mehrere Werte mit Kommas verbunden)                            |
-| `pathParameters`             | `Record<string, string \| undefined>` | Aus dem Routenmuster extrahierte Pfadparameter (z. B. `/users/:id` -> `{ id: '123' }`) |
-| `body`                       | `object \| null`                      | Geparster Request-Body (JSON)                                                          |
-| `isBase64Encoded`            | `boolean`                             | Gibt an, ob der Body Base64-codiert ist                                                |
-| `requestContext.http.method` | `string`                              | HTTP-Methode (GET, POST, PUT, PATCH, DELETE)                                           |
-| `requestContext.http.path`   | `string`                              | Rohpfad der Anfrage                                                                    |
+| Eigenschaft                  | Typ                                   | Beschreibung                                                                          |
+| ---------------------------- | ------------------------------------- | ------------------------------------------------------------------------------------- |
+| `headers`                    | `Record<string, string \| undefined>` | HTTP-Header (nur die in `forwardedRequestHeaders` aufgelisteten)                      |
+| `queryStringParameters`      | `Record<string, string \| undefined>` | Query-String-Parameter (mehrere Werte mit Kommas verbunden)                           |
+| `pathParameters`             | `Record<string, string \| undefined>` | Aus dem Routenmuster extrahierte Pfadparameter (z. B. `/users/:id` → `{ id: '123' }`) |
+| `body`                       | `object \| null`                      | Geparster Request-Body (JSON)                                                         |
+| `isBase64Encoded`            | `boolean`                             | Gibt an, ob der Body Base64-codiert ist                                               |
+| `requestContext.http.method` | `string`                              | HTTP-Methode (GET, POST, PUT, PATCH, DELETE)                                          |
+| `requestContext.http.path`   | `string`                              | Rohpfad der Anfrage                                                                   |

 ### Weiterleiten von HTTP-Headern

@@ -675,7 +466,7 @@ const handler = async (event: RoutePayload) => {

 Sie können neue Funktionen auf zwei Arten erstellen:

-* **Generiert**: Führen Sie `yarn twenty add` aus und wählen Sie die Option zum Hinzufügen einer neuen Logikfunktion. Dadurch wird eine Starterdatei mit Handler und Konfiguration erzeugt.
+* **Generiert**: Führen Sie `yarn twenty entity:add` aus und wählen Sie die Option zum Hinzufügen einer neuen Logikfunktion. Dadurch wird eine Starterdatei mit Handler und Konfiguration erzeugt.
 * **Manuell**: Erstellen Sie eine neue `*.logic-function.ts`-Datei und verwenden Sie `defineLogicFunction()` nach demselben Muster.

 ### Eine Logikfunktion als Tool markieren
@@ -687,7 +478,7 @@ Um eine Logikfunktion als Tool zu markieren, setzen Sie `isTool: true` und geben
 ```typescript
 // src/logic-functions/enrich-company.logic-function.ts
 import { defineLogicFunction } from 'twenty-sdk';
-import { CoreApiClient } from 'twenty-client-sdk/core';
+import { CoreApiClient } from 'twenty-sdk/generated';

 const handler = async (params: { companyName: string; domain?: string }) => {
  const client = new CoreApiClient();
@@ -776,7 +567,7 @@ Hauptpunkte:

 Sie können neue Frontend-Komponenten auf zwei Arten erstellen:

-* **Generiert**: Führen Sie `yarn twenty add` aus und wählen Sie die Option zum Hinzufügen einer neuen Frontend-Komponente.
+* **Generiert**: Führen Sie `yarn twenty entity:add` aus und wählen Sie die Option zum Hinzufügen einer neuen Frontend-Komponente.
 * **Manuell**: Erstellen Sie eine neue `.tsx`-Datei und verwenden Sie `defineFrontComponent()` nach demselben Muster.

 ### Fähigkeiten
@@ -811,122 +602,47 @@ Hauptpunkte:

 Sie können neue Skills auf zwei Arten erstellen:

-* **Generiert**: Führen Sie `yarn twenty add` aus und wählen Sie die Option zum Hinzufügen eines neuen Skills.
+* **Generiert**: Führen Sie `yarn twenty entity:add` aus und wählen Sie die Option zum Hinzufügen eines neuen Skills.
 * **Manuell**: Erstellen Sie eine neue Datei und verwenden Sie `defineSkill()` nach demselben Muster.

-### Typisierte API-Clients (`twenty-client-sdk`)
+### Generierte typisierte Clients

-Das Paket `twenty-client-sdk` stellt zwei typisierte GraphQL-Clients bereit, um aus Ihren Logikfunktionen und Frontend-Komponenten mit der Twenty-API zu interagieren:
+Zwei typisierte Clients werden von `yarn twenty dev` automatisch generiert und basierend auf Ihrem Arbeitsbereichs-Schema in `node_modules/twenty-sdk/generated` gespeichert:

-| Client              | Importieren                  | Endpunkt                                                  | Generiert?                           |
-| ------------------- | ---------------------------- | --------------------------------------------------------- | ------------------------------------ |
-| `CoreApiClient`     | `twenty-client-sdk/core`     | `/graphql` — Arbeitsbereichsdaten (Datensätze, Objekte)   | Ja, zur Entwicklungs-/Build-Zeit     |
-| `MetadataApiClient` | `twenty-client-sdk/metadata` | `/metadata` — Arbeitsbereichskonfiguration, Datei-Uploads | Nein, wird vorgefertigt ausgeliefert |
-
-#### CoreApiClient
-
-Der `CoreApiClient` ist der Haupt-Client zum Abfragen und Ändern von Arbeitsbereichsdaten. Er wird während `yarn twenty dev` oder `yarn twenty build` **aus Ihrem Arbeitsbereichsschema generiert** und ist daher vollständig typisiert, passend zu Ihren Objekten und Feldern.
+* **`CoreApiClient`** — fragt den `/graphql`-Endpunkt nach Arbeitsbereichsdaten ab
+* **`MetadataApiClient`** — ruft über den Endpunkt `/metadata` die Arbeitsbereichskonfiguration und Datei-Uploads ab.

 ```typescript
-import { CoreApiClient } from 'twenty-client-sdk/core';
+import { CoreApiClient, MetadataApiClient } from 'twenty-sdk/generated';

 const client = new CoreApiClient();
-
-// Query records
-const { companies } = await client.query({
-  companies: {
-    edges: {
-      node: {
-        id: true,
-        name: true,
-        domainName: true,
-      },
-    },
-  },
-});
-
-// Create a record
-const { createCompany } = await client.mutation({
-  createCompany: {
-    __args: {
-      data: {
-        name: 'Acme Corp',
-      },
-    },
-    id: true,
-    name: true,
-  },
-});
-```
-
-Der Client verwendet eine Selection-Set-Syntax: Übergeben Sie `true`, um ein Feld einzuschließen, verwenden Sie `__args` für Argumente, und verschachteln Sie Objekte für Relationen. Sie erhalten vollständige Autovervollständigung und Typprüfung basierend auf Ihrem Arbeitsbereichsschema.
-
-<Note>
-**Der CoreApiClient wird zur Entwicklungs-/Build-Zeit generiert.** Wenn Sie versuchen, ihn zu verwenden, ohne zuvor `yarn twenty dev` oder `yarn twenty build` ausgeführt zu haben, wird ein Fehler ausgelöst. Die Generierung erfolgt automatisch — die CLI inspiziert das GraphQL-Schema Ihres Arbeitsbereichs, erzeugt mit `@genql/cli` einen typisierten Client, schreibt die generierten Quellen nach `node_modules/twenty-client-sdk/dist/core/generated/` und ersetzt die Platzhalter in `node_modules/twenty-client-sdk/dist/core.mjs` und `node_modules/twenty-client-sdk/dist/core.cjs`.
-</Note>
-
-#### Verwendung von CoreSchema für Typannotationen
-
-`CoreSchema` stellt TypeScript-Typen bereit, die Ihren Arbeitsbereichsobjekten entsprechen; nützlich zum Typisieren von Komponentenzustand oder Funktionsparametern:
-
-```typescript
-import { CoreApiClient, CoreSchema } from 'twenty-client-sdk/core';
-import { useState } from 'react';
-
-const [company, setCompany] = useState<
-  Pick<CoreSchema.Company, 'id' | 'name'> | undefined
->(undefined);
-
-const client = new CoreApiClient();
-const result = await client.query({
-  company: {
-    __args: { filter: { position: { eq: 1 } } },
-    id: true,
-    name: true,
-  },
-});
-setCompany(result.company);
-```
-
-#### MetadataApiClient
-
-`MetadataApiClient` ist im SDK bereits vorgefertigt enthalten (keine Generierung erforderlich). Er fragt den Endpunkt `/metadata` nach Arbeitsbereichskonfiguration, Anwendungen und Datei-Uploads ab:
-
-```typescript
-import { MetadataApiClient } from 'twenty-client-sdk/metadata';
+const { me } = await client.query({ me: { id: true, displayName: true } });

 const metadataClient = new MetadataApiClient();
-
-// Query workspace info
-const { currentWorkspace } = await metadataClient.query({
-  currentWorkspace: { id: true, displayName: true },
-});
-
-// List installed applications
-const { findManyApplications } = await metadataClient.query({
-  findManyApplications: {
-    id: true,
-    name: true,
-    version: true,
-  },
-});
+const { currentWorkspace } = await metadataClient.query({ currentWorkspace: { id: true } });
 ```

-#### Laufzeit-Anmeldedaten
+Beide Clients werden von `yarn twenty dev` automatisch neu generiert, sobald sich Ihre Objekte oder Felder ändern.

-Wenn Ihr Code auf Twenty ausgeführt wird (Logikfunktionen oder Frontend-Komponenten), injiziert die Plattform Anmeldedaten als Umgebungsvariablen:
+#### Laufzeit-Anmeldedaten in Logikfunktionen

-* `TWENTY_API_URL` — Basis-URL der Twenty-API
-* `TWENTY_API_KEY` — Kurzlebiger Schlüssel, der auf die Standard-Funktionsrolle Ihrer Anwendung begrenzt ist
+Wenn Ihre Funktion auf Twenty läuft, injiziert die Plattform vor der Ausführung Ihres Codes Anmeldedaten als Umgebungsvariablen:

-Sie müssen diese **nicht** an die Clients übergeben — sie lesen automatisch aus `process.env`. Die Berechtigungen des API-Schlüssels werden durch die Rolle bestimmt, auf die in `defaultRoleUniversalIdentifier` in Ihrer `application-config.ts` verwiesen wird.
+* `TWENTY_API_URL`: Basis-URL der Twenty-API, auf die Ihre App abzielt.
+* `TWENTY_API_KEY`: Kurzlebiger Schlüssel, der auf die Standard-Funktionsrolle Ihrer Anwendung begrenzt ist.
+
+Notizen:
+
+* Sie müssen dem generierten Client weder URL noch API-Schlüssel übergeben. Er liest `TWENTY_API_URL` und `TWENTY_API_KEY` zur Laufzeit aus process.env.
+* Die Berechtigungen des API-Schlüssels werden durch die Rolle bestimmt, auf die in Ihrer `application-config.ts` über `defaultRoleUniversalIdentifier` verwiesen wird. Dies ist die Standardrolle, die von den Logikfunktionen Ihrer Anwendung verwendet wird.
+* Anwendungen können Rollen definieren, um das Least-Privilege-Prinzip einzuhalten. Gewähren Sie nur die Berechtigungen, die Ihre Funktionen benötigen, und verweisen Sie dann mit `defaultRoleUniversalIdentifier` auf den universellen Bezeichner dieser Rolle.

 #### Dateien hochladen

-Der `MetadataApiClient` enthält eine Methode `uploadFile`, um Dateien an Felder des Typs Datei anzuhängen. Sie implementiert die [GraphQL-Multipart-Request-Spezifikation](https://github.com/jaydenseric/graphql-multipart-request-spec):
+Der generierte `MetadataApiClient` enthält eine Methode `uploadFile`, um Dateien an Felder des Typs Datei in Ihren Arbeitsbereichsobjekten anzuhängen. Da Standard-GraphQL-Clients Multipart-Datei-Uploads nicht nativ unterstützen, stellt der Client diese dedizierte Methode bereit, die unter der Haube die [GraphQL-Multipart-Anfragespezifikation](https://github.com/jaydenseric/graphql-multipart-request-spec) implementiert.

 ```typescript
-import { MetadataApiClient } from 'twenty-client-sdk/metadata';
+import { MetadataApiClient } from 'twenty-sdk/generated';
 import * as fs from 'fs';

 const metadataClient = new MetadataApiClient();
@@ -936,14 +652,25 @@ const fileBuffer = fs.readFileSync('./invoice.pdf');
 const uploadedFile = await metadataClient.uploadFile(
  fileBuffer,                                         // file contents as a Buffer
  'invoice.pdf',                                      // filename
-  'application/pdf',                                  // MIME type
-  '58a0a314-d7ea-4865-9850-7fb84e72f30b',            // field universalIdentifier
+  '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://...' }
 ```

+Die Methodensignatur:
+
+```typescript
+uploadFile(
+  fileBuffer: Buffer,
+  filename: string,
+  contentType: string,
+  fieldMetadataUniversalIdentifier: string,
+): Promise<{ id: string; path: string; size: number; createdAt: string; url: string }>
+```
+
 | Parameter                          | Typ      | Beschreibung                                                                    |
 | ---------------------------------- | -------- | ------------------------------------------------------------------------------- |
 | `fileBuffer`                       | `Buffer` | Der Rohinhalt der Datei                                                         |
@@ -953,7 +680,8 @@ console.log(uploadedFile);

 Hauptpunkte:

-* Sie verwendet den `universalIdentifier` des Feldes (nicht dessen arbeitsbereichsspezifische ID), sodass Ihr Upload-Code in jedem Arbeitsbereich funktioniert, in dem Ihre App installiert ist.
+* Die Methode `uploadFile` ist auf dem `MetadataApiClient` verfügbar, weil die Upload-Mutation vom Endpunkt `/metadata` aufgelöst wird.
+* Sie verwendet den `universalIdentifier` des Feldes (nicht dessen arbeitsbereichsspezifische ID), sodass Ihr Upload-Code in jedem Arbeitsbereich funktioniert, in dem Ihre App installiert ist — im Einklang damit, wie Apps Felder überall sonst referenzieren.
 * Die zurückgegebene `url` ist eine signierte URL, mit der Sie auf die hochgeladene Datei zugreifen können.

 ### Hello-World-Beispiel
@@ -49,7 +49,7 @@ Von hier aus können Sie:

 ```bash filename="Terminal"
 # Add a new entity to your application (guided)
-yarn twenty add
+yarn twenty entity:add

 # Watch your application's function logs
 yarn twenty function:logs
@@ -123,7 +123,7 @@ Mit `--minimal` werden nur die Kerndateien erstellt (`application-config.ts`, `r
 Auf hoher Ebene:

 * **package.json**: Deklariert den App-Namen, die Version und die Engines (Node 24+, Yarn 4) und fügt `twenty-sdk` sowie ein `twenty`-Skript hinzu, das an die lokale `twenty`-CLI delegiert. Führen Sie `yarn twenty help` aus, um alle verfügbaren Befehle aufzulisten.
-* **.gitignore**: Ignores common artifacts such as `node_modules`, `.yarn`, `.twenty/`, `dist/`, `build/`, coverage folders, log files, and `.env*` files.
+* **.gitignore**: Ignoriert übliche Artefakte wie `node_modules`, `.yarn`, `generated/` (typisierter Client), `dist/`, `build/`, Coverage-Ordner, Logdateien und `.env*`-Dateien.
 * **yarn.lock**, **.yarnrc.yml**, **.yarn/**: Fixieren und konfigurieren die vom Projekt verwendete Yarn-4-Toolchain.
 * **.nvmrc**: Legt die vom Projekt erwartete Node.js-Version fest.
 * **.oxlintrc.json** und **tsconfig.json**: Stellen Linting und TypeScript-Konfiguration für die TypeScript-Quellen Ihrer App bereit.
@@ -167,8 +167,8 @@ export default defineObject({

 Spätere Befehle fügen weitere Dateien und Ordner hinzu:

-* `yarn twenty dev` will auto-generate the typed `CoreApiClient` (for workspace data via `/graphql`) into `node_modules/twenty-client-sdk/`. The `MetadataApiClient` (for workspace configuration and file uploads via `/metadata`) ships pre-built and is available immediately. Import them from `twenty-client-sdk/core` and `twenty-client-sdk/metadata` respectively.
-* `yarn twenty add` will add entity definition files under `src/` for your custom objects, functions, front components, roles, skills, and more.
+* `yarn twenty dev` generiert automatisch zwei typisierte API-Clients in `node_modules/twenty-sdk/generated`: `CoreApiClient` (für Arbeitsbereichsdaten über `/graphql`) und `MetadataApiClient` (für Arbeitsbereichskonfiguration und Datei-Uploads über `/metadata`).
+* `yarn twenty entity:add` fügt unter `src/` Entitätsdefinitionsdateien für Ihre benutzerdefinierten Objekte, Funktionen, Frontend-Komponenten, Rollen, Skills und mehr hinzu.

 ## Authentifizierung

@@ -12,25 +12,7 @@ Apps befinden sich derzeit in der Alpha-Testphase. Die Funktion ist funktionsfä
 Sobald Ihre App [lokal gebaut und getestet](/l/de/developers/extend/apps/building) wurde, haben Sie zwei Möglichkeiten, sie zu verteilen:

 * **Auf npm veröffentlichen** — führen Sie Ihre App im Twenty-Marktplatz auf, damit jeder Arbeitsbereich sie entdecken und installieren kann.
-* **Einen Tarball bereitstellen** — Laden Sie Ihre App direkt auf einen bestimmten Twenty-Server für die interne oder private Nutzung hoch.
-
-Beide Pfade beginnen mit demselben **Build**-Schritt.
-
-## Erstellen Ihrer App
-
-Der Befehl `build` kompiliert Ihre TypeScript-Quelltexte, transpiliert Logikfunktionen und Frontend-Komponenten und erzeugt eine `manifest.json`, die die Inhalte Ihrer App beschreibt:
-
-```bash filename="Terminal"
-yarn twenty build
-```
-
-Die Ausgabe wird in `.twenty/output/` geschrieben. This directory contains everything needed for distribution: compiled code, assets, the manifest, and a copy of your `package.json`.
-
-To also create a `.tgz` tarball (used by the deploy command internally, or for manual distribution):
-
-```bash filename="Terminal"
-yarn twenty build --tarball
-```
+* **Einen Tarball pushen** — stellen Sie Ihre App auf einem bestimmten Twenty-Server für die interne Nutzung bereit, ohne sie öffentlich verfügbar zu machen.

 ## Auf npm veröffentlichen

@@ -39,72 +21,29 @@ Die Veröffentlichung auf npm macht Ihre App im Twenty-Marktplatz auffindbar. Je
 ### Anforderungen

 * Ein [npm](https://www.npmjs.com)-Konto
-* The `twenty-app` keyword **must** be listed in your `package.json` `keywords` array
-
-### Adding the required keyword
-
-The Twenty marketplace discovers apps by searching the npm registry for packages with the `twenty-app` keyword. Add it to your `package.json`:
-
-```json filename="package.json"
-{
-  "name": "twenty-app-postcard-sender",
-  "version": "1.0.0",
-  "keywords": ["twenty-app"],
-  ...
-}
-```
-
-<Note>
-The marketplace searches for `keywords:twenty-app` on the npm registry. Without this keyword, your package won't appear in the marketplace even if it has the `twenty-app-` name prefix.
-</Note>
+* Ihr Paketname **muss** das Präfix `twenty-app-` verwenden (z. B. `twenty-app-postcard-sender`)

 ### Schritte

-1. **Build your app:**
+1. **App erstellen** — die CLI kompiliert Ihre TypeScript-Quellen und erzeugt das Anwendungsmanifest:

 ```bash filename="Terminal"
 yarn twenty build
 ```

-2. **Publish to npm:**
+2. **Auf npm veröffentlichen** — pushen Sie das gebaute Paket in die npm-Registry:

 ```bash filename="Terminal"
-yarn twenty publish
+npx twenty publish
 ```

-This runs `npm publish` from the `.twenty/output/` directory.
+### Automatische Erkennung

-To publish under a specific dist-tag (e.g., `beta` or `next`):
-
-```bash filename="Terminal"
-yarn twenty publish --tag beta
-```
-
-### How marketplace discovery works
-
-The Twenty server syncs its marketplace catalog from the npm registry **every hour**:
-
-1. It searches for all npm packages with the `keywords:twenty-app` keyword
-2. For each package, it fetches the `manifest.json` from the npm CDN
-3. The app's metadata (name, description, author, logo, screenshots, category) is extracted from the manifest and displayed in the marketplace
-
-After publishing, your app can take up to one hour to appear in the marketplace. To trigger the sync immediately instead of waiting for the next hourly run:
-
-```bash filename="Terminal"
-yarn twenty catalog-sync
-```
-
-To target a specific remote:
-
-```bash filename="Terminal"
-yarn twenty catalog-sync -r production
-```
-
-The metadata shown in the marketplace comes from your `defineApplication()` call in your app source code — fields like `displayName`, `description`, `author`, `category`, `logoUrl`, `screenshots`, `aboutDescription`, `websiteUrl`, and `termsUrl`.
+Pakete mit dem Präfix `twenty-app-` werden vom Twenty-Marktplatzkatalog automatisch erkannt. Nach der Veröffentlichung erscheint Ihre App innerhalb weniger Minuten im Marktplatz — keine manuelle Registrierung oder Genehmigung erforderlich.

 ### CI-Veröffentlichung

-Das vorgefertigte Projekt enthält einen GitHub-Actions-Workflow, der bei jedem Release eine Veröffentlichung durchführt:
+Das vorgefertigte Projekt enthält einen GitHub-Actions-Workflow, der bei jedem Release eine Veröffentlichung durchführt. Er führt `app:build` aus und danach `npm publish --provenance` aus dem Build-Output:

 ```yaml filename=".github/workflows/publish.yml"
 name: Publish
@@ -133,117 +72,48 @@ jobs:
          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
 ```

-For other CI systems (GitLab CI, CircleCI, etc.), the same three commands apply: `yarn install`, `yarn twenty build`, then `npm publish` from `.twenty/output`.
+Für andere CI-Systeme (GitLab CI, CircleCI usw.) gelten die gleichen drei Befehle: `yarn install`, `npx twenty build` und anschließend `npm publish` aus `.twenty/output`.

 <Tip>
 **npm-Provenance** ist optional, wird jedoch empfohlen. Das Veröffentlichen mit `--provenance` fügt Ihrem npm-Eintrag ein Vertrauensabzeichen hinzu, sodass Nutzer überprüfen können, dass das Paket aus einem bestimmten Commit in einer öffentlichen CI-Pipeline gebaut wurde. Siehe die [npm-Provenance-Dokumentation](https://docs.npmjs.com/generating-provenance-statements) für Einrichtungshinweise.
 </Tip>

-## Deploying to a server (tarball)
+## Interne Verteilung

-For apps you don't want publicly available — proprietary tools, enterprise-only integrations, or experimental builds — you can deploy a tarball directly to a Twenty server.
+Für Apps, die Sie nicht öffentlich verfügbar machen möchten — proprietäre Tools, nur für Unternehmen bestimmte Integrationen oder experimentelle Builds — können Sie einen Tarball direkt auf einen Twenty-Server pushen.

-### Voraussetzungen
+### Einen Tarball pushen

-Before deploying, you need a configured remote pointing to the target server. Remotes store the server URL and authentication credentials locally in `~/.twenty/config.json`.
-
-Add a remote:
+Erstellen Sie Ihre App und stellen Sie sie in einem Schritt auf einem bestimmten Server bereit:

 ```bash filename="Terminal"
-yarn twenty remote add --url https://your-twenty-server.com --as production
+npx twenty publish --server <server-url>
 ```

-For a local development server:
-
-```bash filename="Terminal"
-yarn twenty remote add --local --as local
-```
-
-You can also authenticate with an API key for non-interactive environments:
-
-```bash filename="Terminal"
-yarn twenty remote add --url https://your-twenty-server.com --token <api-key> --as production
-```
-
-Manage your remotes:
-
-```bash filename="Terminal"
-yarn twenty remote list       # List all configured remotes
-yarn twenty remote switch prod # Set the default remote
-yarn twenty remote status     # Show active remote and auth status
-yarn twenty remote remove old # Remove a remote
-```
-
-### Deploying
-
-Build and upload your app to the server in one step:
-
-```bash filename="Terminal"
-yarn twenty deploy
-```
-
-This builds the app with `--tarball`, then uploads the tarball to the default remote via a GraphQL multipart upload.
-
-To deploy to a specific remote:
-
-```bash filename="Terminal"
-yarn twenty deploy -r production
-```
-
-### Sharing a deployed app
-
-Tarball apps are not listed in the public marketplace, so other workspaces on the same server won't discover them by browsing. To share a deployed app:
-
-1. Go to **Settings > Applications > Registrations** and open your app
-2. In the **Distribution** tab, click **Copy share link**
-3. Share this link with users on other workspaces — it takes them directly to the app's install page
-
-The share link uses the server's base URL (without any workspace subdomain) so it works for any workspace on the server.
+Jeder Arbeitsbereich auf diesem Server kann die App anschließend über die Seite **Applications** in den Einstellungen installieren und aktualisieren.

 ### Versionsverwaltung

 So veröffentlichen Sie ein Update:

 1. Erhöhen Sie das Feld `version` in Ihrer `package.json`
-2. Run `yarn twenty deploy` (or `yarn twenty deploy -r production`)
-3. Workspaces that have the app installed will see the upgrade available in their settings
+2. Pushen Sie einen neuen Tarball mit `npx twenty publish --server <server-url>`
+3. Arbeitsbereiche auf diesem Server sehen in ihren Einstellungen, dass ein Upgrade verfügbar ist.

-## Installing apps
+<Note>
+Interne Apps sind auf den Server beschränkt, auf den sie gepusht werden. Sie erscheinen nicht im öffentlichen Marktplatz und können von Arbeitsbereichen auf anderen Servern nicht installiert werden.
+</Note>

-Once an app is published (npm) or deployed (tarball), workspaces install it through the UI:
-
-```bash filename="Terminal"
-yarn twenty install
-```
-
-Or from the **Settings > Applications** page in the Twenty UI, where both marketplace and tarball-deployed apps can be browsed and installed.
-
-## App distribution categories
+## App-Kategorien

 Twenty organisiert Apps in drei Kategorien, basierend auf ihrer Vertriebsart:

-| Kategorie              | Wie es funktioniert                                                                                                                    | Im Marktplatz sichtbar? |
-| ---------------------- | -------------------------------------------------------------------------------------------------------------------------------------- | ----------------------- |
-| **Entwicklung**        | Lokale Apps im Entwicklungsmodus, die über `yarn twenty dev` ausgeführt werden. Zum Erstellen und Testen verwendet.                    | Nein                    |
-| **Published (npm)**    | Apps published to npm with the `twenty-app` keyword. Im Marktplatz gelistet, damit jeder Arbeitsbereich sie installieren kann.         | Ja                      |
-| **Internal (tarball)** | Apps, die per Tarball auf einen bestimmten Server bereitgestellt werden. Available only to workspaces on that server via a share link. | Nein                    |
+| Kategorie          | Wie es funktioniert                                                                                                                  | Im Marktplatz sichtbar? |
+| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------ | ----------------------- |
+| **Entwicklung**    | Lokale Apps im Entwicklungsmodus, die über `yarn twenty dev` ausgeführt werden. Zum Erstellen und Testen verwendet.                  | Nein                    |
+| **Veröffentlicht** | Auf npm veröffentlichte Apps mit dem Präfix `twenty-app-`. Im Marktplatz gelistet, damit jeder Arbeitsbereich sie installieren kann. | Ja                      |
+| **Intern**         | Apps, die per Tarball auf einen bestimmten Server bereitgestellt werden. Nur für Arbeitsbereiche auf diesem Server verfügbar.        | Nein                    |

 <Tip>
 Beginnen Sie im **Entwicklungsmodus**, während Sie Ihre App erstellen. Wenn sie bereit ist, wählen Sie **Veröffentlicht** (npm) für die breite Verteilung oder **Intern** (Tarball) für die private Bereitstellung.
 </Tip>
-
-## CLI reference
-
-| Befehl                      | Beschreibung                                   | Key flags                                           |
-| --------------------------- | ---------------------------------------------- | --------------------------------------------------- |
-| `yarn twenty build`         | Compile app and generate manifest              | `--tarball` — also create a `.tgz` package          |
-| `yarn twenty publish`       | Build and publish to npm                       | `--tag <tag>` — npm dist-tag (e.g., `beta`, `next`) |
-| `yarn twenty deploy`        | Build and upload tarball to a server           | `-r, --remote <name>` — target remote               |
-| `yarn twenty catalog-sync`  | Trigger marketplace catalog sync on the server | `-r, --remote <name>` — target remote               |
-| `yarn twenty install`       | Install a deployed app on a workspace          | `-r, --remote <name>` — target remote               |
-| `yarn twenty dev`           | Watch and sync local changes                   | Uses default remote                                 |
-| `yarn twenty remote add`    | Add a server connection                        | `--url`, `--token`, `--as`, `--local`, `--port`     |
-| `yarn twenty remote list`   | List configured remotes                        | —                                                   |
-| `yarn twenty remote switch` | Set default remote                             | —                                                   |
-| `yarn twenty remote status` | Show connection status                         | —                                                   |
-| `yarn twenty remote remove` | Remove a remote                                | —                                                   |
@@ -15,21 +15,19 @@ Il pacchetto twenty-sdk fornisce blocchi tipizzati e funzioni helper da usare ne

 L'SDK fornisce funzioni helper per definire le entità della tua app. Come descritto in [Rilevamento delle entità](/l/it/developers/extend/apps/getting-started#entity-detection), devi usare `export default define<Entity>({...})` affinché le tue entità vengano rilevate:

-| Funzione                         | Scopo                                                                               |
-| -------------------------------- | ----------------------------------------------------------------------------------- |
-| `defineApplication`              | Configura i metadati dell'applicazione (obbligatorio, uno per app)                  |
-| `defineObject`                   | Definisci oggetti personalizzati con campi                                          |
-| `defineField`                    | Extend existing objects with additional fields or define standalone relation fields |
-| `defineLogicFunction`            | Definisci funzioni logiche con handler                                              |
-| `definePreInstallLogicFunction`  | Definisci una funzione logica di pre-installazione (una per app)                    |
-| `definePostInstallLogicFunction` | Definisci una funzione logica di post-installazione (una per app)                   |
-| `defineFrontComponent`           | Definisci componenti front-end per un'interfaccia utente personalizzata             |
-| `defineRole`                     | Configura i permessi dei ruoli e l'accesso agli oggetti                             |
-| `defineView`                     | Definisci viste salvate per gli oggetti                                             |
-| `defineNavigationMenuItem`       | Definisci i link di navigazione della barra laterale                                |
-| `defineSkill`                    | Definisci le competenze dell'agente IA                                              |
-| `defineAgent`                    | Define AI agents                                                                    |
-| `definePageLayout`               | Define custom page layouts                                                          |
+| Funzione                         | Scopo                                                                   |
+| -------------------------------- | ----------------------------------------------------------------------- |
+| `defineApplication`              | Configura i metadati dell'applicazione (obbligatorio, uno per app)      |
+| `defineObject`                   | Definisci oggetti personalizzati con campi                              |
+| `defineLogicFunction`            | Definisci funzioni logiche con handler                                  |
+| `definePreInstallLogicFunction`  | Definisci una funzione logica di pre-installazione (una per app)        |
+| `definePostInstallLogicFunction` | Definisci una funzione logica di post-installazione (una per app)       |
+| `defineFrontComponent`           | Definisci componenti front-end per un'interfaccia utente personalizzata |
+| `defineRole`                     | Configura i permessi dei ruoli e l'accesso agli oggetti                 |
+| `defineField`                    | Estendi gli oggetti esistenti con campi aggiuntivi                      |
+| `defineView`                     | Definisci viste salvate per gli oggetti                                 |
+| `defineNavigationMenuItem`       | Definisci i link di navigazione della barra laterale                    |
+| `defineSkill`                    | Definisci le competenze dell'agente IA                                  |

 Queste funzioni convalidano la configurazione in fase di build e offrono il completamento automatico nell'IDE e la sicurezza dei tipi.

@@ -38,7 +36,7 @@ Queste funzioni convalidano la configurazione in fase di build e offrono il comp
 Gli oggetti personalizzati descrivono sia lo schema sia il comportamento per i record nel tuo spazio di lavoro. Usa `defineObject()` per definire oggetti con convalida integrata:

 ```typescript
-// src/objects/postCard.object.ts
+// src/app/postCard.object.ts
 import { defineObject, FieldType } from 'twenty-sdk';

 enum PostCardStatus {
@@ -112,7 +110,7 @@ Punti chiave:
 * Il `universalIdentifier` deve essere univoco e stabile tra i deployment.
 * Ogni campo richiede un `name`, `type`, `label` e il proprio `universalIdentifier` stabile.
 * L'array `fields` è facoltativo: puoi definire oggetti senza campi personalizzati.
-* You can scaffold new objects using `yarn twenty add`, which guides you through naming, fields, and relationships.
+* Puoi generare nuovi oggetti con `yarn twenty entity:add`, che ti guida nella denominazione, nei campi e nelle relazioni.

 <Note>
 **I campi base vengono creati automaticamente.** Quando definisci un oggetto personalizzato, Twenty aggiunge automaticamente i campi standard
@@ -122,197 +120,6 @@ Puoi sovrascrivere i campi predefiniti definendo un campo con lo stesso nome nel
 ma non è consigliato.
 </Note>

-### Definire campi sugli oggetti esistenti
-
-Use `defineField()` to add fields to objects you don't own — such as standard Twenty objects (Person, Company, etc.) or objects from other apps. Unlike inline fields in `defineObject()`, standalone fields require an `objectUniversalIdentifier` to specify which object they extend:
-
-```typescript
-// src/fields/company-loyalty-tier.field.ts
-import { defineField, FieldType } from 'twenty-sdk';
-
-export default defineField({
-  universalIdentifier: 'f2a1b3c4-d5e6-7890-abcd-ef1234567890',
-  objectUniversalIdentifier: '701aecb9-eb1c-4d84-9d94-b954b231b64b', // Company object
-  name: 'loyaltyTier',
-  type: FieldType.SELECT,
-  label: 'Loyalty Tier',
-  icon: 'IconStar',
-  options: [
-    { value: 'BRONZE', label: 'Bronze', position: 0, color: 'orange' },
-    { value: 'SILVER', label: 'Silver', position: 1, color: 'gray' },
-    { value: 'GOLD', label: 'Gold', position: 2, color: 'yellow' },
-  ],
-});
-```
-
-Punti chiave:
-
-* `objectUniversalIdentifier` identifies the target object. For standard objects, use `STANDARD_OBJECT_UNIVERSAL_IDENTIFIERS` exported from `twenty-sdk`.
-* When defining fields inline in `defineObject()`, you do **not** need `objectUniversalIdentifier` — it's inherited from the parent object.
-* `defineField()` is the only way to add fields to objects you didn't create with `defineObject()`.
-
-### Relazioni
-
-Relations connect objects together. In Twenty, relations are always **bidirectional** — you define both sides, and each side references the other.
-
-There are two relation types:
-
-| Tipo di relazione | Descrizione                                                   | Has foreign key?       |
-| ----------------- | ------------------------------------------------------------- | ---------------------- |
-| `MANY_TO_ONE`     | Many records of this object point to one record of the target | Yes (`joinColumnName`) |
-| `ONE_TO_MANY`     | One record of this object has many records of the target      | No (inverse side)      |
-
-#### How relations work
-
-Every relation requires **two fields** that reference each other:
-
-1. The **MANY_TO_ONE** side — lives on the object that holds the foreign key
-2. The **ONE_TO_MANY** side — lives on the object that owns the collection
-
-Both fields use `FieldType.RELATION` and cross-reference each other via `relationTargetFieldMetadataUniversalIdentifier`.
-
-#### Example: Post Card has many Recipients
-
-Suppose a `PostCard` can be sent to many `PostCardRecipient` records. Each recipient belongs to exactly one post card.
-
-**Step 1: Define the ONE_TO_MANY side on PostCard** (the "one" side):
-
-```typescript
-// src/fields/post-card-recipients-on-post-card.field.ts
-import { defineField, FieldType, RelationType } from 'twenty-sdk';
-import { POST_CARD_UNIVERSAL_IDENTIFIER } from '../objects/post-card.object';
-import { POST_CARD_RECIPIENT_UNIVERSAL_IDENTIFIER } from '../objects/post-card-recipient.object';
-
-// Export so the other side can reference it
-export const POST_CARD_RECIPIENTS_FIELD_ID = 'a1111111-1111-1111-1111-111111111111';
-// Import from the other side
-import { POST_CARD_FIELD_ID } from './post-card-on-post-card-recipient.field';
-
-export default defineField({
-  universalIdentifier: POST_CARD_RECIPIENTS_FIELD_ID,
-  objectUniversalIdentifier: POST_CARD_UNIVERSAL_IDENTIFIER,
-  type: FieldType.RELATION,
-  name: 'postCardRecipients',
-  label: 'Post Card Recipients',
-  icon: 'IconUsers',
-  relationTargetObjectMetadataUniversalIdentifier: POST_CARD_RECIPIENT_UNIVERSAL_IDENTIFIER,
-  relationTargetFieldMetadataUniversalIdentifier: POST_CARD_FIELD_ID,
-  universalSettings: {
-    relationType: RelationType.ONE_TO_MANY,
-  },
-});
-```
-
-**Step 2: Define the MANY_TO_ONE side on PostCardRecipient** (the "many" side — holds the foreign key):
-
-```typescript
-// src/fields/post-card-on-post-card-recipient.field.ts
-import { defineField, FieldType, RelationType, OnDeleteAction } from 'twenty-sdk';
-import { POST_CARD_UNIVERSAL_IDENTIFIER } from '../objects/post-card.object';
-import { POST_CARD_RECIPIENT_UNIVERSAL_IDENTIFIER } from '../objects/post-card-recipient.object';
-
-// Export so the other side can reference it
-export const POST_CARD_FIELD_ID = 'b2222222-2222-2222-2222-222222222222';
-// Import from the other side
-import { POST_CARD_RECIPIENTS_FIELD_ID } from './post-card-recipients-on-post-card.field';
-
-export default defineField({
-  universalIdentifier: POST_CARD_FIELD_ID,
-  objectUniversalIdentifier: POST_CARD_RECIPIENT_UNIVERSAL_IDENTIFIER,
-  type: FieldType.RELATION,
-  name: 'postCard',
-  label: 'Post Card',
-  icon: 'IconMail',
-  relationTargetObjectMetadataUniversalIdentifier: POST_CARD_UNIVERSAL_IDENTIFIER,
-  relationTargetFieldMetadataUniversalIdentifier: POST_CARD_RECIPIENTS_FIELD_ID,
-  universalSettings: {
-    relationType: RelationType.MANY_TO_ONE,
-    onDelete: OnDeleteAction.CASCADE,
-    joinColumnName: 'postCardId',
-  },
-});
-```
-
-<Note>
-**Circular imports:** Both relation fields reference each other's `universalIdentifier`. To avoid circular import issues, export your field IDs as named constants from each file, and import them in the other file. The build system resolves these at compile time.
-</Note>
-
-#### Relating to standard objects
-
-To create a relation with a built-in Twenty object (Person, Company, etc.), use `STANDARD_OBJECT_UNIVERSAL_IDENTIFIERS`:
-
-```typescript
-// src/fields/person-on-self-hosting-user.field.ts
-import {
-  defineField,
-  FieldType,
-  RelationType,
-  OnDeleteAction,
-  STANDARD_OBJECT_UNIVERSAL_IDENTIFIERS,
-} from 'twenty-sdk';
-import { SELF_HOSTING_USER_UNIVERSAL_IDENTIFIER } from '../objects/self-hosting-user.object';
-
-export const PERSON_FIELD_ID = 'c3333333-3333-3333-3333-333333333333';
-export const SELF_HOSTING_USER_REVERSE_FIELD_ID = 'd4444444-4444-4444-4444-444444444444';
-
-export default defineField({
-  universalIdentifier: PERSON_FIELD_ID,
-  objectUniversalIdentifier: SELF_HOSTING_USER_UNIVERSAL_IDENTIFIER,
-  type: FieldType.RELATION,
-  name: 'person',
-  label: 'Person',
-  description: 'Person matching with the self hosting user',
-  isNullable: true,
-  relationTargetObjectMetadataUniversalIdentifier:
-    STANDARD_OBJECT_UNIVERSAL_IDENTIFIERS.person.universalIdentifier,
-  relationTargetFieldMetadataUniversalIdentifier: SELF_HOSTING_USER_REVERSE_FIELD_ID,
-  universalSettings: {
-    relationType: RelationType.MANY_TO_ONE,
-    onDelete: OnDeleteAction.SET_NULL,
-    joinColumnName: 'personId',
-  },
-});
-```
-
-#### Relation field properties
-
-| Proprietà                                         | Obbligatorio     | Descrizione                                                                                           |
-| ------------------------------------------------- | ---------------- | ----------------------------------------------------------------------------------------------------- |
-| `tipo`                                            | Sì               | Must be `FieldType.RELATION`                                                                          |
-| `relationTargetObjectMetadataUniversalIdentifier` | Sì               | The `universalIdentifier` of the target object                                                        |
-| `relationTargetFieldMetadataUniversalIdentifier`  | Sì               | The `universalIdentifier` of the matching field on the target object                                  |
-| `universalSettings.relationType`                  | Sì               | `RelationType.MANY_TO_ONE` or `RelationType.ONE_TO_MANY`                                              |
-| `universalSettings.onDelete`                      | MANY_TO_ONE only | What happens when the referenced record is deleted: `CASCADE`, `SET_NULL`, `RESTRICT`, or `NO_ACTION` |
-| `universalSettings.joinColumnName`                | MANY_TO_ONE only | Database column name for the foreign key (e.g., `postCardId`)                                         |
-
-#### Inline relation fields in defineObject
-
-You can also define relation fields directly inside `defineObject()`. In that case, omit `objectUniversalIdentifier` — it's inherited from the parent object:
-
-```typescript
-export default defineObject({
-  universalIdentifier: '...',
-  nameSingular: 'postCardRecipient',
-  // ...
-  fields: [
-    {
-      universalIdentifier: POST_CARD_FIELD_ID,
-      type: FieldType.RELATION,
-      name: 'postCard',
-      label: 'Post Card',
-      relationTargetObjectMetadataUniversalIdentifier: POST_CARD_UNIVERSAL_IDENTIFIER,
-      relationTargetFieldMetadataUniversalIdentifier: POST_CARD_RECIPIENTS_FIELD_ID,
-      universalSettings: {
-        relationType: RelationType.MANY_TO_ONE,
-        onDelete: OnDeleteAction.CASCADE,
-        joinColumnName: 'postCardId',
-      },
-    },
-    // ... other fields
-  ],
-});
-```
-
 ### Configurazione dell'applicazione (application-config.ts)

 Ogni app ha un singolo file `application-config.ts` che descrive:
@@ -354,29 +161,13 @@ Note:
 * `defaultRoleUniversalIdentifier` deve corrispondere al file del ruolo (vedi sotto).
 * Le funzioni di pre-installazione e post-installazione vengono rilevate automaticamente durante la build del manifesto. Vedi [Funzioni di pre-installazione](#pre-install-functions) e [Funzioni di post-installazione](#post-install-functions).

-#### Marketplace metadata
-
-If you plan to [publish your app](/l/it/developers/extend/apps/publishing), these optional fields control how your app appears in the marketplace:
-
-| Campo              | Descrizione                                         |
-| ------------------ | --------------------------------------------------- |
-| `autore`           | Author or company name                              |
-| `categoria`        | App category for marketplace filtering              |
-| `logoUrl`          | Path to your app logo (relative to `./assets/`)     |
-| `screenshots`      | Array of screenshot paths (relative to `./assets/`) |
-| `aboutDescription` | Longer markdown description for the "About" tab     |
-| `websiteUrl`       | Link to your website                                |
-| `termsUrl`         | Link to terms of service                            |
-| `emailSupport`     | Support email address                               |
-| `issueReportUrl`   | Link to issue tracker                               |
-
 #### Ruoli e permessi

 Le applicazioni possono definire ruoli che incapsulano i permessi sugli oggetti e sulle azioni del tuo spazio di lavoro. Il campo `defaultRoleUniversalIdentifier` in `application-config.ts` indica il ruolo predefinito utilizzato dalle funzioni logiche della tua app.

 * La chiave API di runtime iniettata come `TWENTY_API_KEY` è derivata da questo ruolo funzione predefinito.
 * Il client tipizzato sarà limitato ai permessi concessi a quel ruolo.
-* Follow least-privilege: create a dedicated role with only the permissions your functions need, then reference its universal identifier.
+* Segui il principio del privilegio minimo: crea un ruolo dedicato con solo i permessi necessari alle tue funzioni, quindi fai riferimento al suo identificatore universale.

 ##### Ruolo funzione predefinito (*.role.ts)

@@ -429,7 +220,7 @@ L'`universalIdentifier` di questo ruolo viene quindi referenziato in `applicatio

 Note:

-* Start from the scaffolded role, then progressively restrict it following least-privilege.
+* Parti dal ruolo generato dallo scaffolder, quindi restringilo progressivamente seguendo il principio del privilegio minimo.
 * Sostituisci `objectPermissions` e `fieldPermissions` con gli oggetti/campi di cui le tue funzioni hanno bisogno.
 * `permissionFlags` controllano l'accesso alle funzionalità a livello di piattaforma. Mantienili al minimo; aggiungi solo ciò che ti serve.
 * Vedi un esempio funzionante nell'app 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).
@@ -439,7 +230,7 @@ Note:
 Ogni file di funzione usa `defineLogicFunction()` per esportare una configurazione con un handler e trigger opzionali.

 ```typescript
-// src/logic-functions/createPostCard.logic-function.ts
+// 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';
@@ -533,7 +324,7 @@ export default definePreInstallLogicFunction({
 Puoi anche eseguire manualmente la funzione di pre-installazione in qualsiasi momento utilizzando la CLI:

 ```bash filename="Terminal"
-yarn twenty exec --preInstall
+yarn twenty function:execute --preInstall
 ```

 Punti chiave:
@@ -543,7 +334,7 @@ Punti chiave:
 * È consentita una sola funzione di pre-installazione per applicazione. La build del manifesto genererà un errore se ne viene rilevata più di una.
 * L'`universalIdentifier` della funzione viene impostato automaticamente come `preInstallLogicFunctionUniversalIdentifier` nel manifesto dell'applicazione durante la build — non è necessario farvi riferimento in `defineApplication()`.
 * Il timeout predefinito è impostato a 300 secondi (5 minuti) per consentire attività di preparazione più lunghe.
-* Pre-install functions do not need triggers — they are invoked by the platform before installation or manually via `exec --preInstall`.
+* Le funzioni di pre-installazione non necessitano di trigger — vengono invocate dalla piattaforma prima dell'installazione o manualmente tramite `function:execute --preInstall`.

 ### Funzioni post-installazione

@@ -571,7 +362,7 @@ export default definePostInstallLogicFunction({
 Puoi anche eseguire manualmente la funzione di post-installazione in qualsiasi momento utilizzando la CLI:

 ```bash filename="Terminal"
-yarn twenty exec --postInstall
+yarn twenty function:execute --postInstall
 ```

 Punti chiave:
@@ -581,7 +372,7 @@ Punti chiave:
 * È consentita una sola funzione di post-installazione per applicazione. La build del manifesto genererà un errore se ne viene rilevata più di una.
 * L'`universalIdentifier` della funzione viene impostato automaticamente come `postInstallLogicFunctionUniversalIdentifier` nel manifesto dell'applicazione durante la build — non è necessario farvi riferimento in `defineApplication()`.
 * Il timeout predefinito è impostato a 300 secondi (5 minuti) per consentire attività di configurazione più lunghe, come il popolamento dei dati.
-* Post-install functions do not need triggers — they are invoked by the platform during installation or manually via `exec --postInstall`.
+* Le funzioni di post-installazione non necessitano di trigger — vengono invocate dalla piattaforma durante l'installazione o manualmente tramite `function:execute --postInstall`.

 ### Payload del trigger di route

@@ -625,15 +416,15 @@ const handler = async (event: RoutePayload) => {

 Il tipo `RoutePayload` ha la seguente struttura:

-| Proprietà                    | Tipo                                  | Descrizione                                                                              |
-| ---------------------------- | ------------------------------------- | ---------------------------------------------------------------------------------------- |
-| `headers`                    | `Record<string, string \| undefined>` | Intestazioni HTTP (solo quelle elencate in `forwardedRequestHeaders`)                    |
-| `queryStringParameters`      | `Record<string, string \| undefined>` | Parametri della query string (valori multipli uniti da virgole)                          |
-| `pathParameters`             | `Record<string, string \| undefined>` | Path parameters extracted from the route pattern (e.g., `/users/:id` -> `{ id: '123' }`) |
-| `body`                       | `object \| null`                      | Corpo della richiesta analizzato (JSON)                                                  |
-| `isBase64Encoded`            | `boolean`                             | Indica se il corpo è codificato in base64                                                |
-| `requestContext.http.method` | `string`                              | Metodo HTTP (GET, POST, PUT, PATCH, DELETE)                                              |
-| `requestContext.http.path`   | `string`                              | Percorso della richiesta non elaborato                                                   |
+| Proprietà                    | Tipo                                  | Descrizione                                                                                     |
+| ---------------------------- | ------------------------------------- | ----------------------------------------------------------------------------------------------- |
+| `headers`                    | `Record<string, string \| undefined>` | Intestazioni HTTP (solo quelle elencate in `forwardedRequestHeaders`)                           |
+| `queryStringParameters`      | `Record<string, string \| undefined>` | Parametri della query string (valori multipli uniti da virgole)                                 |
+| `pathParameters`             | `Record<string, string \| undefined>` | Parametri di percorso estratti dal pattern della route (ad es., `/users/:id` → `{ id: '123' }`) |
+| `body`                       | `object \| null`                      | Corpo della richiesta analizzato (JSON)                                                         |
+| `isBase64Encoded`            | `boolean`                             | Indica se il corpo è codificato in base64                                                       |
+| `requestContext.http.method` | `string`                              | Metodo HTTP (GET, POST, PUT, PATCH, DELETE)                                                     |
+| `requestContext.http.path`   | `string`                              | Percorso della richiesta non elaborato                                                          |

 ### Inoltro delle intestazioni HTTP

@@ -675,7 +466,7 @@ const handler = async (event: RoutePayload) => {

 Puoi creare nuove funzioni in due modi:

-* **Scaffolded**: Run `yarn twenty add` and choose the option to add a new logic function. Questo genera un file iniziale con un handler e una configurazione.
+* **Generata dallo scaffolder**: Esegui `yarn twenty entity:add` e scegli l'opzione per aggiungere una nuova funzione logica. Questo genera un file iniziale con un handler e una configurazione.
 * **Manuale**: Crea un nuovo file `*.logic-function.ts` e usa `defineLogicFunction()`, seguendo lo stesso schema.

 ### Contrassegnare una funzione logica come strumento
@@ -687,7 +478,7 @@ Per contrassegnare una funzione logica come strumento, imposta `isTool: true` e
 ```typescript
 // src/logic-functions/enrich-company.logic-function.ts
 import { defineLogicFunction } from 'twenty-sdk';
-import { CoreApiClient } from 'twenty-client-sdk/core';
+import { CoreApiClient } from 'twenty-sdk/generated';

 const handler = async (params: { companyName: string; domain?: string }) => {
  const client = new CoreApiClient();
@@ -776,7 +567,7 @@ Punti chiave:

 Puoi creare nuovi componenti front-end in due modi:

-* **Scaffolded**: Run `yarn twenty add` and choose the option to add a new front component.
+* **Generata dallo scaffolder**: Esegui `yarn twenty entity:add` e scegli l'opzione per aggiungere un nuovo componente front-end.
 * **Manuale**: Crea un nuovo file `.tsx` e usa `defineFrontComponent()`, seguendo lo stesso schema.

 ### Abilità
@@ -811,122 +602,47 @@ Punti chiave:

 Puoi creare nuove skill in due modi:

-* **Scaffolded**: Run `yarn twenty add` and choose the option to add a new skill.
+* **Generata dallo scaffolder**: Esegui `yarn twenty entity:add` e scegli l'opzione per aggiungere una nuova skill.
 * **Manuale**: Crea un nuovo file e usa `defineSkill()`, seguendo lo stesso schema.

-### Typed API clients (`twenty-client-sdk`)
+### Client tipizzati generati

-The `twenty-client-sdk` package provides two typed GraphQL clients for interacting with the Twenty API from your logic functions and front components:
+Due client tipizzati sono generati automaticamente da `yarn twenty dev` e salvati in `node_modules/twenty-sdk/generated` in base allo schema del tuo spazio di lavoro:

-| Client              | Importa                      | Endpoint                                       | Generated?             |
-| ------------------- | ---------------------------- | ---------------------------------------------- | ---------------------- |
-| `CoreApiClient`     | `twenty-client-sdk/core`     | `/graphql` — workspace data (records, objects) | Yes, at dev/build time |
-| `MetadataApiClient` | `twenty-client-sdk/metadata` | `/metadata` — workspace config, file uploads   | No, ships pre-built    |
-
-#### CoreApiClient
-
-`CoreApiClient` is the main client for querying and mutating workspace data. It is **generated from your workspace schema** during `yarn twenty dev` or `yarn twenty build`, so it's fully typed to match your objects and fields.
+* **`CoreApiClient`** — interroga l'endpoint `/graphql` per i dati dello spazio di lavoro
+* **`MetadataApiClient`** — interroga l'endpoint `/metadata` per la configurazione dello spazio di lavoro e il caricamento dei file

 ```typescript
-import { CoreApiClient } from 'twenty-client-sdk/core';
+import { CoreApiClient, MetadataApiClient } from 'twenty-sdk/generated';

 const client = new CoreApiClient();
-
-// Query records
-const { companies } = await client.query({
-  companies: {
-    edges: {
-      node: {
-        id: true,
-        name: true,
-        domainName: true,
-      },
-    },
-  },
-});
-
-// Create a record
-const { createCompany } = await client.mutation({
-  createCompany: {
-    __args: {
-      data: {
-        name: 'Acme Corp',
-      },
-    },
-    id: true,
-    name: true,
-  },
-});
-```
-
-The client uses a selection-set syntax: pass `true` to include a field, use `__args` for arguments, and nest objects for relations. You get full autocompletion and type checking based on your workspace schema.
-
-<Note>
-**CoreApiClient is generated at dev/build time.** If you try to use it without running `yarn twenty dev` or `yarn twenty build` first, it throws an error. The generation happens automatically — the CLI introspects your workspace's GraphQL schema, generates a typed client using `@genql/cli`, writes the generated sources to `node_modules/twenty-client-sdk/dist/core/generated/`, and replaces the stubs in `node_modules/twenty-client-sdk/dist/core.mjs` and `node_modules/twenty-client-sdk/dist/core.cjs`.
-</Note>
-
-#### Using CoreSchema for type annotations
-
-`CoreSchema` provides TypeScript types matching your workspace objects, useful for typing component state or function parameters:
-
-```typescript
-import { CoreApiClient, CoreSchema } from 'twenty-client-sdk/core';
-import { useState } from 'react';
-
-const [company, setCompany] = useState<
-  Pick<CoreSchema.Company, 'id' | 'name'> | undefined
->(undefined);
-
-const client = new CoreApiClient();
-const result = await client.query({
-  company: {
-    __args: { filter: { position: { eq: 1 } } },
-    id: true,
-    name: true,
-  },
-});
-setCompany(result.company);
-```
-
-#### MetadataApiClient
-
-`MetadataApiClient` ships pre-built with the SDK (no generation required). It queries the `/metadata` endpoint for workspace configuration, applications, and file uploads:
-
-```typescript
-import { MetadataApiClient } from 'twenty-client-sdk/metadata';
+const { me } = await client.query({ me: { id: true, displayName: true } });

 const metadataClient = new MetadataApiClient();
-
-// Query workspace info
-const { currentWorkspace } = await metadataClient.query({
-  currentWorkspace: { id: true, displayName: true },
-});
-
-// List installed applications
-const { findManyApplications } = await metadataClient.query({
-  findManyApplications: {
-    id: true,
-    name: true,
-    version: true,
-  },
-});
+const { currentWorkspace } = await metadataClient.query({ currentWorkspace: { id: true } });
 ```

-#### Runtime credentials
+Entrambi i client vengono rigenerati automaticamente da `yarn twenty dev` ogni volta che i tuoi oggetti o campi cambiano.

-When your code runs on Twenty (logic functions or front components), the platform injects credentials as environment variables:
+#### Credenziali di runtime nelle funzioni logiche

-* `TWENTY_API_URL` — Base URL of the Twenty API
-* `TWENTY_API_KEY` — Short-lived key scoped to your application's default function role
+Quando la tua funzione viene eseguita su Twenty, la piattaforma inietta le credenziali come variabili d'ambiente prima dell'esecuzione del tuo codice:

-You do **not** need to pass these to the clients — they read from `process.env` automatically. The API key's permissions are determined by the role referenced in `defaultRoleUniversalIdentifier` in your `application-config.ts`.
+* `TWENTY_API_URL`: URL di base dell'API Twenty a cui punta la tua app.
+* `TWENTY_API_KEY`: Chiave a breve durata con ambito al ruolo funzione predefinito della tua applicazione.
+
+Note:
+
+* Non è necessario passare URL o chiave API al client generato. Legge `TWENTY_API_URL` e `TWENTY_API_KEY` da process.env in fase di esecuzione.
+* I permessi della chiave API sono determinati dal ruolo referenziato nel tuo `application-config.ts` tramite `defaultRoleUniversalIdentifier`. Questo è il ruolo predefinito utilizzato dalle funzioni logiche della tua applicazione.
+* Le applicazioni possono definire ruoli per seguire il principio del privilegio minimo. Concedi solo i permessi necessari alle tue funzioni, quindi punta `defaultRoleUniversalIdentifier` all'identificatore universale di quel ruolo.

 #### Caricamento dei file

-`MetadataApiClient` includes an `uploadFile` method for attaching files to file-type fields. It implements the [GraphQL multipart request specification](https://github.com/jaydenseric/graphql-multipart-request-spec):
+Il `MetadataApiClient` generato include un metodo `uploadFile` per allegare file ai campi di tipo file sugli oggetti del tuo spazio di lavoro. Poiché i client GraphQL standard non supportano nativamente il caricamento di file multipart, il client fornisce questo metodo dedicato che implementa la [specifica della richiesta GraphQL multipart](https://github.com/jaydenseric/graphql-multipart-request-spec) dietro le quinte.

 ```typescript
-import { MetadataApiClient } from 'twenty-client-sdk/metadata';
+import { MetadataApiClient } from 'twenty-sdk/generated';
 import * as fs from 'fs';

 const metadataClient = new MetadataApiClient();
@@ -936,14 +652,25 @@ const fileBuffer = fs.readFileSync('./invoice.pdf');
 const uploadedFile = await metadataClient.uploadFile(
  fileBuffer,                                         // file contents as a Buffer
  'invoice.pdf',                                      // filename
-  'application/pdf',                                  // MIME type
-  '58a0a314-d7ea-4865-9850-7fb84e72f30b',            // field universalIdentifier
+  '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://...' }
 ```

+La firma del metodo:
+
+```typescript
+uploadFile(
+  fileBuffer: Buffer,
+  filename: string,
+  contentType: string,
+  fieldMetadataUniversalIdentifier: string,
+): Promise<{ id: string; path: string; size: number; createdAt: string; url: string }>
+```
+
 | Parametro                          | Tipo     | Descrizione                                                              |
 | ---------------------------------- | -------- | ------------------------------------------------------------------------ |
 | `fileBuffer`                       | `Buffer` | Il contenuto grezzo del file                                             |
@@ -953,7 +680,8 @@ console.log(uploadedFile);

 Punti chiave:

-* Uses the field's `universalIdentifier` (not its workspace-specific ID), so your upload code works across any workspace where your app is installed.
+* Il metodo `uploadFile` è disponibile su `MetadataApiClient` perché la mutazione di upload viene risolta dall'endpoint `/metadata`.
+* Usa l'`universalIdentifier` del campo (non il suo ID specifico dello spazio di lavoro), quindi il tuo codice di upload funziona in qualsiasi spazio di lavoro in cui la tua app è installata — coerentemente con il modo in cui le app fanno riferimento ai campi altrove.
 * L'`url` restituito è un URL firmato che puoi usare per accedere al file caricato.

 ### Esempio Hello World
@@ -49,7 +49,7 @@ Da qui puoi:

 ```bash filename="Terminal"
 # Add a new entity to your application (guided)
-yarn twenty add
+yarn twenty entity:add

 # Watch your application's function logs
 yarn twenty function:logs
@@ -123,7 +123,7 @@ Con `--minimal`, vengono creati solo i file principali (`application-config.ts`,
 A livello generale:

 * **package.json**: Dichiara il nome dell'app, la versione, i motori (Node 24+, Yarn 4) e aggiunge `twenty-sdk` più uno script `twenty` che delega alla CLI locale `twenty`. Esegui `yarn twenty help` per elencare tutti i comandi disponibili.
-* **.gitignore**: Ignores common artifacts such as `node_modules`, `.yarn`, `.twenty/`, `dist/`, `build/`, coverage folders, log files, and `.env*` files.
+* **.gitignore**: Ignora i file generati comuni come `node_modules`, `.yarn`, `generated/` (client tipizzato), `dist/`, `build/`, cartelle di coverage, file di log e file `.env*`.
 * **yarn.lock**, **.yarnrc.yml**, **.yarn/**: Bloccano e configurano la toolchain Yarn 4 utilizzata dal progetto.
 * **.nvmrc**: Fissa la versione di Node.js prevista dal progetto.
 * **.oxlintrc.json** e **tsconfig.json**: Forniscono linting e configurazione TypeScript per i sorgenti TypeScript della tua app.
@@ -167,8 +167,8 @@ export default defineObject({

 Comandi successivi aggiungeranno altri file e cartelle:

-* `yarn twenty dev` will auto-generate the typed `CoreApiClient` (for workspace data via `/graphql`) into `node_modules/twenty-client-sdk/`. The `MetadataApiClient` (for workspace configuration and file uploads via `/metadata`) ships pre-built and is available immediately. Import them from `twenty-client-sdk/core` and `twenty-client-sdk/metadata` respectively.
-* `yarn twenty add` will add entity definition files under `src/` for your custom objects, functions, front components, roles, skills, and more.
+* `yarn twenty dev` genererà automaticamente due client API tipizzati in `node_modules/twenty-sdk/generated`: `CoreApiClient` (per i dati dell'area di lavoro tramite `/graphql`) e `MetadataApiClient` (per la configurazione dell'area di lavoro e il caricamento di file tramite `/metadata`).
+* `yarn twenty entity:add` aggiungerà file di definizione delle entità sotto `src/` per i tuoi oggetti, funzioni, componenti front-end, ruoli, competenze e altro ancora.

 ## Autenticazione

@@ -12,25 +12,7 @@ Le app sono attualmente in fase alfa. La funzionalità è funzionante ma ancora
 Una volta che la tua app è stata [compilata e testata localmente](/l/it/developers/extend/apps/building), hai due modalità per distribuirla:

 * **Pubblica su npm** — elenca la tua app nel marketplace di Twenty affinché qualsiasi spazio di lavoro possa scoprirla e installarla.
-* **Distribuisci un tarball** — carica la tua app direttamente su un server Twenty specifico per uso interno o privato.
-
-Entrambi i percorsi partono dalla stessa fase di **build**.
-
-## Compilazione della tua app
-
-Il comando `build` compila i tuoi sorgenti TypeScript, transpila le funzioni di logica e i componenti front-end e genera un `manifest.json` che descrive i contenuti della tua app:
-
-```bash filename="Terminal"
-yarn twenty build
-```
-
-L'output viene scritto in `.twenty/output/`. This directory contains everything needed for distribution: compiled code, assets, the manifest, and a copy of your `package.json`.
-
-To also create a `.tgz` tarball (used by the deploy command internally, or for manual distribution):
-
-```bash filename="Terminal"
-yarn twenty build --tarball
-```
+* **Esegui il push di un tarball** — distribuisci la tua app su un server Twenty specifico per uso interno senza renderla pubblicamente disponibile.

 ## Pubblicazione su npm

@@ -39,72 +21,29 @@ La pubblicazione su npm rende la tua app scopribile nel marketplace di Twenty. Q
 ### Requisiti

 * Un account [npm](https://www.npmjs.com)
-* The `twenty-app` keyword **must** be listed in your `package.json` `keywords` array
-
-### Adding the required keyword
-
-The Twenty marketplace discovers apps by searching the npm registry for packages with the `twenty-app` keyword. Add it to your `package.json`:
-
-```json filename="package.json"
-{
-  "name": "twenty-app-postcard-sender",
-  "version": "1.0.0",
-  "keywords": ["twenty-app"],
-  ...
-}
-```
-
-<Note>
-The marketplace searches for `keywords:twenty-app` on the npm registry. Without this keyword, your package won't appear in the marketplace even if it has the `twenty-app-` name prefix.
-</Note>
+* Il nome del tuo pacchetto **deve** usare il prefisso `twenty-app-` (es. `twenty-app-postcard-sender`)

 ### Passaggi

-1. **Build your app:**
+1. **Compila la tua app** — la CLI compila i tuoi sorgenti TypeScript e genera il manifest dell'applicazione:

 ```bash filename="Terminal"
 yarn twenty build
 ```

-2. **Publish to npm:**
+2. **Pubblica su npm** — esegui il push del pacchetto compilato al registro npm:

 ```bash filename="Terminal"
-yarn twenty publish
+npx twenty publish
 ```

-This runs `npm publish` from the `.twenty/output/` directory.
+### Rilevamento automatico

-To publish under a specific dist-tag (e.g., `beta` or `next`):
-
-```bash filename="Terminal"
-yarn twenty publish --tag beta
-```
-
-### How marketplace discovery works
-
-The Twenty server syncs its marketplace catalog from the npm registry **every hour**:
-
-1. It searches for all npm packages with the `keywords:twenty-app` keyword
-2. For each package, it fetches the `manifest.json` from the npm CDN
-3. The app's metadata (name, description, author, logo, screenshots, category) is extracted from the manifest and displayed in the marketplace
-
-After publishing, your app can take up to one hour to appear in the marketplace. To trigger the sync immediately instead of waiting for the next hourly run:
-
-```bash filename="Terminal"
-yarn twenty catalog-sync
-```
-
-To target a specific remote:
-
-```bash filename="Terminal"
-yarn twenty catalog-sync -r production
-```
-
-The metadata shown in the marketplace comes from your `defineApplication()` call in your app source code — fields like `displayName`, `description`, `author`, `category`, `logoUrl`, `screenshots`, `aboutDescription`, `websiteUrl`, and `termsUrl`.
+I pacchetti con il prefisso `twenty-app-` vengono rilevati automaticamente dal catalogo del marketplace di Twenty. Una volta pubblicata, la tua app compare nel marketplace entro pochi minuti — non è richiesta alcuna registrazione o approvazione manuale.

 ### Pubblicazione con CI

-Il progetto generato include un workflow di GitHub Actions che pubblica a ogni release:
+Il progetto generato include un workflow di GitHub Actions che pubblica a ogni release. Esegue `app:build`, quindi `npm publish --provenance` dall'output di build:

 ```yaml filename=".github/workflows/publish.yml"
 name: Publish
@@ -133,117 +72,48 @@ jobs:
          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
 ```

-For other CI systems (GitLab CI, CircleCI, etc.), the same three commands apply: `yarn install`, `yarn twenty build`, then `npm publish` from `.twenty/output`.
+Per altri sistemi CI (GitLab CI, CircleCI, ecc.), si applicano gli stessi tre comandi: `yarn install`, `npx twenty build`, quindi `npm publish` da `.twenty/output`.

 <Tip>
 **npm provenance** è opzionale ma consigliata. La pubblicazione con `--provenance` aggiunge un badge di attendibilità alla tua scheda npm, consentendo agli utenti di verificare che il pacchetto sia stato creato a partire da uno specifico commit in una pipeline CI pubblica. Consulta la [documentazione su npm provenance](https://docs.npmjs.com/generating-provenance-statements) per le istruzioni di configurazione.
 </Tip>

-## Deploying to a server (tarball)
+## Distribuzione interna

-For apps you don't want publicly available — proprietary tools, enterprise-only integrations, or experimental builds — you can deploy a tarball directly to a Twenty server.
+Per le app che non vuoi rendere pubbliche — strumenti proprietari, integrazioni solo per l'azienda o build sperimentali — puoi eseguire il push di un tarball direttamente su un server Twenty.

-### Prerequisiti
+### Push di un tarball

-Before deploying, you need a configured remote pointing to the target server. Remotes store the server URL and authentication credentials locally in `~/.twenty/config.json`.
-
-Add a remote:
+Compila la tua app e distribuiscila su un server specifico in un solo passaggio:

 ```bash filename="Terminal"
-yarn twenty remote add --url https://your-twenty-server.com --as production
+npx twenty publish --server <server-url>
 ```

-For a local development server:
-
-```bash filename="Terminal"
-yarn twenty remote add --local --as local
-```
-
-You can also authenticate with an API key for non-interactive environments:
-
-```bash filename="Terminal"
-yarn twenty remote add --url https://your-twenty-server.com --token <api-key> --as production
-```
-
-Manage your remotes:
-
-```bash filename="Terminal"
-yarn twenty remote list       # List all configured remotes
-yarn twenty remote switch prod # Set the default remote
-yarn twenty remote status     # Show active remote and auth status
-yarn twenty remote remove old # Remove a remote
-```
-
-### Deploying
-
-Build and upload your app to the server in one step:
-
-```bash filename="Terminal"
-yarn twenty deploy
-```
-
-This builds the app with `--tarball`, then uploads the tarball to the default remote via a GraphQL multipart upload.
-
-To deploy to a specific remote:
-
-```bash filename="Terminal"
-yarn twenty deploy -r production
-```
-
-### Sharing a deployed app
-
-Tarball apps are not listed in the public marketplace, so other workspaces on the same server won't discover them by browsing. To share a deployed app:
-
-1. Go to **Settings > Applications > Registrations** and open your app
-2. In the **Distribution** tab, click **Copy share link**
-3. Share this link with users on other workspaces — it takes them directly to the app's install page
-
-The share link uses the server's base URL (without any workspace subdomain) so it works for any workspace on the server.
+Qualsiasi spazio di lavoro su quel server può quindi installare e aggiornare l'app dalla pagina delle impostazioni **Applicazioni**.

 ### Gestione delle versioni

 Per rilasciare un aggiornamento:

 1. Incrementa il campo `version` nel tuo `package.json`
-2. Run `yarn twenty deploy` (or `yarn twenty deploy -r production`)
-3. Workspaces that have the app installed will see the upgrade available in their settings
+2. Esegui il push di un nuovo tarball con `npx twenty publish --server <server-url>`
+3. Gli spazi di lavoro su quel server vedranno l'aggiornamento disponibile nelle proprie impostazioni

-## Installing apps
+<Note>
+Le app interne sono limitate al server su cui vengono caricate. Non compariranno nel marketplace pubblico e non potranno essere installate dagli spazi di lavoro su altri server.
+</Note>

-Once an app is published (npm) or deployed (tarball), workspaces install it through the UI:
-
-```bash filename="Terminal"
-yarn twenty install
-```
-
-Or from the **Settings > Applications** page in the Twenty UI, where both marketplace and tarball-deployed apps can be browsed and installed.
-
-## App distribution categories
+## Categorie di app

 Twenty organizza le app in tre categorie in base a come vengono distribuite:

-| Categoria              | Come funziona                                                                                                                             | Visibile nel marketplace? |
-| ---------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- | ------------------------- |
-| **Sviluppo**           | App in modalità di sviluppo locale eseguite tramite `yarn twenty dev`. Usate per la compilazione e i test.                                | No                        |
-| **Published (npm)**    | Apps published to npm with the `twenty-app` keyword. Elencate nel marketplace per l'installazione da parte di qualsiasi spazio di lavoro. | Sì                        |
-| **Internal (tarball)** | App distribuite tramite tarball su un server specifico. Available only to workspaces on that server via a share link.                     | No                        |
+| Categoria      | Come funziona                                                                                                                             | Visibile nel marketplace? |
+| -------------- | ----------------------------------------------------------------------------------------------------------------------------------------- | ------------------------- |
+| **Sviluppo**   | App in modalità di sviluppo locale eseguite tramite `yarn twenty dev`. Usate per la compilazione e i test.                                | No                        |
+| **Pubblicata** | App pubblicate su npm con il prefisso `twenty-app-`. Elencate nel marketplace per l'installazione da parte di qualsiasi spazio di lavoro. | Sì                        |
+| **Interna**    | App distribuite tramite tarball su un server specifico. Disponibili solo per gli spazi di lavoro su quel server.                          | No                        |

 <Tip>
 Inizia in modalità **Sviluppo** mentre crei la tua app. Quando è pronta, scegli **Pubblicata** (npm) per un'ampia distribuzione oppure **Interna** (tarball) per una distribuzione privata.
 </Tip>
-
-## CLI reference
-
-| Comando                     | Descrizione                                    | Key flags                                           |
-| --------------------------- | ---------------------------------------------- | --------------------------------------------------- |
-| `yarn twenty build`         | Compile app and generate manifest              | `--tarball` — also create a `.tgz` package          |
-| `yarn twenty publish`       | Build and publish to npm                       | `--tag <tag>` — npm dist-tag (e.g., `beta`, `next`) |
-| `yarn twenty deploy`        | Build and upload tarball to a server           | `-r, --remote <name>` — target remote               |
-| `yarn twenty catalog-sync`  | Trigger marketplace catalog sync on the server | `-r, --remote <name>` — target remote               |
-| `yarn twenty install`       | Install a deployed app on a workspace          | `-r, --remote <name>` — target remote               |
-| `yarn twenty dev`           | Watch and sync local changes                   | Uses default remote                                 |
-| `yarn twenty remote add`    | Add a server connection                        | `--url`, `--token`, `--as`, `--local`, `--port`     |
-| `yarn twenty remote list`   | List configured remotes                        | —                                                   |
-| `yarn twenty remote switch` | Set default remote                             | —                                                   |
-| `yarn twenty remote status` | Show connection status                         | —                                                   |
-| `yarn twenty remote remove` | Remove a remote                                | —                                                   |
@@ -15,21 +15,19 @@ Biblioteca twenty-sdk oferă blocuri de bază tipizate și funcții ajutătoare

 SDK-ul oferă funcții ajutătoare pentru definirea entităților aplicației. După cum este descris în [Detectarea entităților](/l/ro/developers/extend/apps/getting-started#entity-detection), trebuie să folosiți `export default define<Entity>({...})` pentru ca entitățile să fie detectate:

-| Funcție                          | Scop                                                                                |
-| -------------------------------- | ----------------------------------------------------------------------------------- |
-| `defineApplication`              | Configurați metadatele aplicației (obligatoriu, una per aplicație)                  |
-| `defineObject`                   | Definiți obiecte personalizate cu câmpuri                                           |
-| `defineField`                    | Extend existing objects with additional fields or define standalone relation fields |
-| `defineLogicFunction`            | Definiți funcții de logică cu handleri                                              |
-| `definePreInstallLogicFunction`  | Definește o funcție logică de pre-instalare (una per aplicație)                     |
-| `definePostInstallLogicFunction` | Definește o funcție logică post-instalare (una per aplicație)                       |
-| `defineFrontComponent`           | Definiți componente Front pentru interfața de utilizator personalizată              |
-| `defineRole`                     | Configurați permisiunile rolurilor și accesul la obiecte                            |
-| `defineView`                     | Definește vizualizări salvate pentru obiecte                                        |
-| `defineNavigationMenuItem`       | Definește linkuri de navigare în bara laterală                                      |
-| `defineSkill`                    | Definiți abilități pentru agentul AI                                                |
-| `defineAgent`                    | Define AI agents                                                                    |
-| `definePageLayout`               | Define custom page layouts                                                          |
+| Funcție                          | Scop                                                                   |
+| -------------------------------- | ---------------------------------------------------------------------- |
+| `defineApplication`              | Configurați metadatele aplicației (obligatoriu, una per aplicație)     |
+| `defineObject`                   | Definiți obiecte personalizate cu câmpuri                              |
+| `defineLogicFunction`            | Definiți funcții de logică cu handleri                                 |
+| `definePreInstallLogicFunction`  | Definește o funcție logică de pre-instalare (una per aplicație)        |
+| `definePostInstallLogicFunction` | Definește o funcție logică post-instalare (una per aplicație)          |
+| `defineFrontComponent`           | Definiți componente Front pentru interfața de utilizator personalizată |
+| `defineRole`                     | Configurați permisiunile rolurilor și accesul la obiecte               |
+| `defineField`                    | Extindeți obiectele existente cu câmpuri suplimentare                  |
+| `defineView`                     | Definește vizualizări salvate pentru obiecte                           |
+| `defineNavigationMenuItem`       | Definește linkuri de navigare în bara laterală                         |
+| `defineSkill`                    | Definiți abilități pentru agentul AI                                   |

 Aceste funcții validează configurația în timpul build-ului și oferă completare automată în IDE și siguranța tipurilor.

@@ -38,7 +36,7 @@ Aceste funcții validează configurația în timpul build-ului și oferă comple
 Obiectele personalizate descriu atât schema, cât și comportamentul înregistrărilor din spațiul dvs. de lucru. Utilizați `defineObject()` pentru a defini obiecte cu validare încorporată:

 ```typescript
-// src/objects/postCard.object.ts
+// src/app/postCard.object.ts
 import { defineObject, FieldType } from 'twenty-sdk';

 enum PostCardStatus {
@@ -112,7 +110,7 @@ Puncte cheie:
 * `universalIdentifier` trebuie să fie unic și stabil între implementări.
 * Fiecare câmp necesită un `name`, un `type`, un `label` și propriul `universalIdentifier` stabil.
 * Matricea `fields` este opțională — puteți defini obiecte fără câmpuri personalizate.
-* You can scaffold new objects using `yarn twenty add`, which guides you through naming, fields, and relationships.
+* Puteți genera obiecte noi folosind `yarn twenty entity:add`, care vă ghidează prin denumire, câmpuri și relații.

 <Note>
 **Câmpurile de bază sunt create automat.** Când definiți un obiect personalizat, Twenty adaugă automat câmpuri standard
@@ -122,197 +120,6 @@ Puteți suprascrie câmpurile implicite definind un câmp cu același nume în t
 dar acest lucru nu este recomandat.
 </Note>

-### Definirea câmpurilor pe obiecte existente
-
-Use `defineField()` to add fields to objects you don't own — such as standard Twenty objects (Person, Company, etc.) or objects from other apps. Unlike inline fields in `defineObject()`, standalone fields require an `objectUniversalIdentifier` to specify which object they extend:
-
-```typescript
-// src/fields/company-loyalty-tier.field.ts
-import { defineField, FieldType } from 'twenty-sdk';
-
-export default defineField({
-  universalIdentifier: 'f2a1b3c4-d5e6-7890-abcd-ef1234567890',
-  objectUniversalIdentifier: '701aecb9-eb1c-4d84-9d94-b954b231b64b', // Company object
-  name: 'loyaltyTier',
-  type: FieldType.SELECT,
-  label: 'Loyalty Tier',
-  icon: 'IconStar',
-  options: [
-    { value: 'BRONZE', label: 'Bronze', position: 0, color: 'orange' },
-    { value: 'SILVER', label: 'Silver', position: 1, color: 'gray' },
-    { value: 'GOLD', label: 'Gold', position: 2, color: 'yellow' },
-  ],
-});
-```
-
-Puncte cheie:
-
-* `objectUniversalIdentifier` identifies the target object. For standard objects, use `STANDARD_OBJECT_UNIVERSAL_IDENTIFIERS` exported from `twenty-sdk`.
-* When defining fields inline in `defineObject()`, you do **not** need `objectUniversalIdentifier` — it's inherited from the parent object.
-* `defineField()` is the only way to add fields to objects you didn't create with `defineObject()`.
-
-### Relații
-
-Relations connect objects together. In Twenty, relations are always **bidirectional** — you define both sides, and each side references the other.
-
-There are two relation types:
-
-| Tip relație   | Descriere                                                     | Has foreign key?       |
-| ------------- | ------------------------------------------------------------- | ---------------------- |
-| `MANY_TO_ONE` | Many records of this object point to one record of the target | Yes (`joinColumnName`) |
-| `ONE_TO_MANY` | One record of this object has many records of the target      | No (inverse side)      |
-
-#### How relations work
-
-Every relation requires **two fields** that reference each other:
-
-1. The **MANY_TO_ONE** side — lives on the object that holds the foreign key
-2. The **ONE_TO_MANY** side — lives on the object that owns the collection
-
-Both fields use `FieldType.RELATION` and cross-reference each other via `relationTargetFieldMetadataUniversalIdentifier`.
-
-#### Example: Post Card has many Recipients
-
-Suppose a `PostCard` can be sent to many `PostCardRecipient` records. Each recipient belongs to exactly one post card.
-
-**Step 1: Define the ONE_TO_MANY side on PostCard** (the "one" side):
-
-```typescript
-// src/fields/post-card-recipients-on-post-card.field.ts
-import { defineField, FieldType, RelationType } from 'twenty-sdk';
-import { POST_CARD_UNIVERSAL_IDENTIFIER } from '../objects/post-card.object';
-import { POST_CARD_RECIPIENT_UNIVERSAL_IDENTIFIER } from '../objects/post-card-recipient.object';
-
-// Export so the other side can reference it
-export const POST_CARD_RECIPIENTS_FIELD_ID = 'a1111111-1111-1111-1111-111111111111';
-// Import from the other side
-import { POST_CARD_FIELD_ID } from './post-card-on-post-card-recipient.field';
-
-export default defineField({
-  universalIdentifier: POST_CARD_RECIPIENTS_FIELD_ID,
-  objectUniversalIdentifier: POST_CARD_UNIVERSAL_IDENTIFIER,
-  type: FieldType.RELATION,
-  name: 'postCardRecipients',
-  label: 'Post Card Recipients',
-  icon: 'IconUsers',
-  relationTargetObjectMetadataUniversalIdentifier: POST_CARD_RECIPIENT_UNIVERSAL_IDENTIFIER,
-  relationTargetFieldMetadataUniversalIdentifier: POST_CARD_FIELD_ID,
-  universalSettings: {
-    relationType: RelationType.ONE_TO_MANY,
-  },
-});
-```
-
-**Step 2: Define the MANY_TO_ONE side on PostCardRecipient** (the "many" side — holds the foreign key):
-
-```typescript
-// src/fields/post-card-on-post-card-recipient.field.ts
-import { defineField, FieldType, RelationType, OnDeleteAction } from 'twenty-sdk';
-import { POST_CARD_UNIVERSAL_IDENTIFIER } from '../objects/post-card.object';
-import { POST_CARD_RECIPIENT_UNIVERSAL_IDENTIFIER } from '../objects/post-card-recipient.object';
-
-// Export so the other side can reference it
-export const POST_CARD_FIELD_ID = 'b2222222-2222-2222-2222-222222222222';
-// Import from the other side
-import { POST_CARD_RECIPIENTS_FIELD_ID } from './post-card-recipients-on-post-card.field';
-
-export default defineField({
-  universalIdentifier: POST_CARD_FIELD_ID,
-  objectUniversalIdentifier: POST_CARD_RECIPIENT_UNIVERSAL_IDENTIFIER,
-  type: FieldType.RELATION,
-  name: 'postCard',
-  label: 'Post Card',
-  icon: 'IconMail',
-  relationTargetObjectMetadataUniversalIdentifier: POST_CARD_UNIVERSAL_IDENTIFIER,
-  relationTargetFieldMetadataUniversalIdentifier: POST_CARD_RECIPIENTS_FIELD_ID,
-  universalSettings: {
-    relationType: RelationType.MANY_TO_ONE,
-    onDelete: OnDeleteAction.CASCADE,
-    joinColumnName: 'postCardId',
-  },
-});
-```
-
-<Note>
-**Circular imports:** Both relation fields reference each other's `universalIdentifier`. To avoid circular import issues, export your field IDs as named constants from each file, and import them in the other file. The build system resolves these at compile time.
-</Note>
-
-#### Relating to standard objects
-
-To create a relation with a built-in Twenty object (Person, Company, etc.), use `STANDARD_OBJECT_UNIVERSAL_IDENTIFIERS`:
-
-```typescript
-// src/fields/person-on-self-hosting-user.field.ts
-import {
-  defineField,
-  FieldType,
-  RelationType,
-  OnDeleteAction,
-  STANDARD_OBJECT_UNIVERSAL_IDENTIFIERS,
-} from 'twenty-sdk';
-import { SELF_HOSTING_USER_UNIVERSAL_IDENTIFIER } from '../objects/self-hosting-user.object';
-
-export const PERSON_FIELD_ID = 'c3333333-3333-3333-3333-333333333333';
-export const SELF_HOSTING_USER_REVERSE_FIELD_ID = 'd4444444-4444-4444-4444-444444444444';
-
-export default defineField({
-  universalIdentifier: PERSON_FIELD_ID,
-  objectUniversalIdentifier: SELF_HOSTING_USER_UNIVERSAL_IDENTIFIER,
-  type: FieldType.RELATION,
-  name: 'person',
-  label: 'Person',
-  description: 'Person matching with the self hosting user',
-  isNullable: true,
-  relationTargetObjectMetadataUniversalIdentifier:
-    STANDARD_OBJECT_UNIVERSAL_IDENTIFIERS.person.universalIdentifier,
-  relationTargetFieldMetadataUniversalIdentifier: SELF_HOSTING_USER_REVERSE_FIELD_ID,
-  universalSettings: {
-    relationType: RelationType.MANY_TO_ONE,
-    onDelete: OnDeleteAction.SET_NULL,
-    joinColumnName: 'personId',
-  },
-});
-```
-
-#### Relation field properties
-
-| Proprietate                                       | Obligatoriu      | Descriere                                                                                             |
-| ------------------------------------------------- | ---------------- | ----------------------------------------------------------------------------------------------------- |
-| `tip`                                             | Da               | Must be `FieldType.RELATION`                                                                          |
-| `relationTargetObjectMetadataUniversalIdentifier` | Da               | The `universalIdentifier` of the target object                                                        |
-| `relationTargetFieldMetadataUniversalIdentifier`  | Da               | The `universalIdentifier` of the matching field on the target object                                  |
-| `universalSettings.relationType`                  | Da               | `RelationType.MANY_TO_ONE` or `RelationType.ONE_TO_MANY`                                              |
-| `universalSettings.onDelete`                      | MANY_TO_ONE only | What happens when the referenced record is deleted: `CASCADE`, `SET_NULL`, `RESTRICT`, or `NO_ACTION` |
-| `universalSettings.joinColumnName`                | MANY_TO_ONE only | Database column name for the foreign key (e.g., `postCardId`)                                         |
-
-#### Inline relation fields in defineObject
-
-You can also define relation fields directly inside `defineObject()`. In that case, omit `objectUniversalIdentifier` — it's inherited from the parent object:
-
-```typescript
-export default defineObject({
-  universalIdentifier: '...',
-  nameSingular: 'postCardRecipient',
-  // ...
-  fields: [
-    {
-      universalIdentifier: POST_CARD_FIELD_ID,
-      type: FieldType.RELATION,
-      name: 'postCard',
-      label: 'Post Card',
-      relationTargetObjectMetadataUniversalIdentifier: POST_CARD_UNIVERSAL_IDENTIFIER,
-      relationTargetFieldMetadataUniversalIdentifier: POST_CARD_RECIPIENTS_FIELD_ID,
-      universalSettings: {
-        relationType: RelationType.MANY_TO_ONE,
-        onDelete: OnDeleteAction.CASCADE,
-        joinColumnName: 'postCardId',
-      },
-    },
-    // ... other fields
-  ],
-});
-```
-
 ### Configurația aplicației (application-config.ts)

 Fiecare aplicație are un singur fișier `application-config.ts` care descrie:
@@ -354,29 +161,13 @@ Notițe:
 * `defaultRoleUniversalIdentifier` trebuie să corespundă fișierului de rol (vedeți mai jos).
 * Funcțiile de pre-instalare și post-instalare sunt detectate automat în timpul construirii manifestului. Vezi [Funcții de pre-instalare](#pre-install-functions) și [Funcții post-instalare](#post-install-functions).

-#### Marketplace metadata
-
-If you plan to [publish your app](/l/ro/developers/extend/apps/publishing), these optional fields control how your app appears in the marketplace:
-
-| Câmp               | Descriere                                           |
-| ------------------ | --------------------------------------------------- |
-| `autor`            | Author or company name                              |
-| `categorie`        | App category for marketplace filtering              |
-| `logoUrl`          | Path to your app logo (relative to `./assets/`)     |
-| `screenshots`      | Array of screenshot paths (relative to `./assets/`) |
-| `aboutDescription` | Longer markdown description for the "About" tab     |
-| `websiteUrl`       | Link to your website                                |
-| `termsUrl`         | Link to terms of service                            |
-| `emailSupport`     | Support email address                               |
-| `issueReportUrl`   | Link to issue tracker                               |
-
 #### Roluri și permisiuni

 Aplicațiile pot defini roluri care încapsulează permisiuni asupra obiectelor și acțiunilor din spațiul dvs. de lucru. Câmpul `defaultRoleUniversalIdentifier` din `application-config.ts` desemnează rolul implicit utilizat de funcțiile de logică ale aplicației.

 * Cheia API de runtime injectată ca `TWENTY_API_KEY` este derivată din acest rol implicit pentru funcții.
 * Clientul tipizat va fi restricționat la permisiunile acordate acelui rol.
-* Follow least-privilege: create a dedicated role with only the permissions your functions need, then reference its universal identifier.
+* Respectați principiul celui mai mic privilegiu: creați un rol dedicat doar cu permisiunile de care au nevoie funcțiile, apoi referiți identificatorul său universal.

 ##### Rol implicit pentru funcții (*.role.ts)

@@ -429,7 +220,7 @@ export default defineRole({

 Notițe:

-* Start from the scaffolded role, then progressively restrict it following least-privilege.
+* Porniți de la rolul generat, apoi restrângeți-l progresiv urmând principiul celui mai mic privilegiu.
 * Înlocuiți `objectPermissions` și `fieldPermissions` cu obiectele/câmpurile de care au nevoie funcțiile.
 * `permissionFlags` controlează accesul la capabilități la nivelul platformei. Mențineți-le la minimum; adăugați doar ceea ce aveți nevoie.
 * Vedeți un exemplu funcțional în aplicația 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).
@@ -439,7 +230,7 @@ Notițe:
 Fiecare fișier de funcție folosește `defineLogicFunction()` pentru a exporta o configurație cu un handler și declanșatoare opționale.

 ```typescript
-// src/logic-functions/createPostCard.logic-function.ts
+// 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';
@@ -533,7 +324,7 @@ export default definePreInstallLogicFunction({
 Poți, de asemenea, să execuți manual funcția de pre-instalare oricând folosind CLI:

 ```bash filename="Terminal"
-yarn twenty exec --preInstall
+yarn twenty function:execute --preInstall
 ```

 Puncte cheie:
@@ -543,7 +334,7 @@ Puncte cheie:
 * Este permisă o singură funcție de pre-instalare per aplicație. Construirea manifestului va genera o eroare dacă este detectată mai mult de una.
 * Proprietatea `universalIdentifier` a funcției este setată automat ca `preInstallLogicFunctionUniversalIdentifier` în manifestul aplicației în timpul build-ului — nu este nevoie să o referi în `defineApplication()`.
 * Timpul de expirare implicit este setat la 300 de secunde (5 minute) pentru a permite sarcini de pregătire mai lungi.
-* Pre-install functions do not need triggers — they are invoked by the platform before installation or manually via `exec --preInstall`.
+* Funcțiile de pre-instalare nu au nevoie de declanșatoare — sunt invocate de platformă înainte de instalare sau manual prin `function:execute --preInstall`.

 ### Funcții post-instalare

@@ -571,7 +362,7 @@ export default definePostInstallLogicFunction({
 Poți, de asemenea, să execuți manual funcția post-instalare oricând folosind CLI:

 ```bash filename="Terminal"
-yarn twenty exec --postInstall
+yarn twenty function:execute --postInstall
 ```

 Puncte cheie:
@@ -581,7 +372,7 @@ Puncte cheie:
 * Este permisă o singură funcție de post-instalare per aplicație. Construirea manifestului va genera o eroare dacă este detectată mai mult de una.
 * Proprietatea `universalIdentifier` a funcției este setată automat ca `postInstallLogicFunctionUniversalIdentifier` în manifestul aplicației în timpul build-ului — nu este nevoie să o referi în `defineApplication()`.
 * Timpul de expirare implicit este setat la 300 de secunde (5 minute) pentru a permite sarcini de configurare mai lungi, cum ar fi popularea datelor.
-* Post-install functions do not need triggers — they are invoked by the platform during installation or manually via `exec --postInstall`.
+* Funcțiile post-instalare nu au nevoie de declanșatoare — sunt invocate de platformă în timpul instalării sau manual prin `function:execute --postInstall`.

 ### Payload-ul declanșatorului de rută

@@ -625,15 +416,15 @@ const handler = async (event: RoutePayload) => {

 Tipul `RoutePayload` are următoarea structură:

-| Proprietate                  | Tip                                   | Descriere                                                                                |
-| ---------------------------- | ------------------------------------- | ---------------------------------------------------------------------------------------- |
-| `headers`                    | `Record<string, string \| undefined>` | Anteturi HTTP (doar cele listate în `forwardedRequestHeaders`)                           |
-| `queryStringParameters`      | `Record<string, string \| undefined>` | Parametri query string (valorile multiple unite cu virgule)                              |
-| `pathParameters`             | `Record<string, string \| undefined>` | Path parameters extracted from the route pattern (e.g., `/users/:id` -> `{ id: '123' }`) |
-| `body`                       | `object \| null`                      | Corpul cererii analizat (JSON)                                                           |
-| `isBase64Encoded`            | `boolean`                             | Indică dacă corpul este codificat în base64                                              |
-| `requestContext.http.method` | `string`                              | Metoda HTTP (GET, POST, PUT, PATCH, DELETE)                                              |
-| `requestContext.http.path`   | `string`                              | Calea brută a cererii                                                                    |
+| Proprietate                  | Tip                                   | Descriere                                                                            |
+| ---------------------------- | ------------------------------------- | ------------------------------------------------------------------------------------ |
+| `headers`                    | `Record<string, string \| undefined>` | Anteturi HTTP (doar cele listate în `forwardedRequestHeaders`)                       |
+| `queryStringParameters`      | `Record<string, string \| undefined>` | Parametri query string (valorile multiple unite cu virgule)                          |
+| `pathParameters`             | `Record<string, string \| undefined>` | Parametri de cale extrași din modelul rutei (de ex., `/users/:id` → `{ id: '123' }`) |
+| `body`                       | `object \| null`                      | Corpul cererii analizat (JSON)                                                       |
+| `isBase64Encoded`            | `boolean`                             | Indică dacă corpul este codificat în base64                                          |
+| `requestContext.http.method` | `string`                              | Metoda HTTP (GET, POST, PUT, PATCH, DELETE)                                          |
+| `requestContext.http.path`   | `string`                              | Calea brută a cererii                                                                |

 ### Transmiterea anteturilor HTTP

@@ -675,7 +466,7 @@ const handler = async (event: RoutePayload) => {

 Puteți crea funcții noi în două moduri:

-* **Scaffolded**: Run `yarn twenty add` and choose the option to add a new logic function. Aceasta generează un fișier inițial cu un handler și o configurație.
+* **Generat**: Rulați `yarn twenty entity:add` și alegeți opțiunea de a adăuga o funcție logică nouă. Aceasta generează un fișier inițial cu un handler și o configurație.
 * **Manual**: Creați un fișier nou `*.logic-function.ts` și folosiți `defineLogicFunction()`, urmând același model.

 ### Marcarea unei funcții logice drept instrument
@@ -687,7 +478,7 @@ Pentru a marca o funcție logică drept instrument, setați `isTool: true` și f
 ```typescript
 // src/logic-functions/enrich-company.logic-function.ts
 import { defineLogicFunction } from 'twenty-sdk';
-import { CoreApiClient } from 'twenty-client-sdk/core';
+import { CoreApiClient } from 'twenty-sdk/generated';

 const handler = async (params: { companyName: string; domain?: string }) => {
  const client = new CoreApiClient();
@@ -776,7 +567,7 @@ Puncte cheie:

 Puteți crea componente Front noi în două moduri:

-* **Scaffolded**: Run `yarn twenty add` and choose the option to add a new front component.
+* **Generat**: Rulați `yarn twenty entity:add` și alegeți opțiunea de a adăuga o componentă frontend nouă.
 * **Manual**: Creați un fișier nou `.tsx` și folosiți `defineFrontComponent()`, urmând același model.

 ### Abilități
@@ -811,122 +602,47 @@ Puncte cheie:

 Puteți crea abilități noi în două moduri:

-* **Scaffolded**: Run `yarn twenty add` and choose the option to add a new skill.
+* **Generat**: Rulați `yarn twenty entity:add` și alegeți opțiunea de a adăuga o abilitate nouă.
 * **Manual**: Creați un fișier nou și folosiți `defineSkill()`, urmând același model.

-### Typed API clients (`twenty-client-sdk`)
+### Clienți tipizați generați

-The `twenty-client-sdk` package provides two typed GraphQL clients for interacting with the Twenty API from your logic functions and front components:
+Doi clienți tipizați sunt generați automat de `yarn twenty dev` și stocați în `node_modules/twenty-sdk/generated`, pe baza schemei spațiului tău de lucru:

-| Client              | Importați                    | Endpoint                                       | Generated?             |
-| ------------------- | ---------------------------- | ---------------------------------------------- | ---------------------- |
-| `CoreApiClient`     | `twenty-client-sdk/core`     | `/graphql` — workspace data (records, objects) | Yes, at dev/build time |
-| `MetadataApiClient` | `twenty-client-sdk/metadata` | `/metadata` — workspace config, file uploads   | No, ships pre-built    |
-
-#### CoreApiClient
-
-`CoreApiClient` is the main client for querying and mutating workspace data. It is **generated from your workspace schema** during `yarn twenty dev` or `yarn twenty build`, so it's fully typed to match your objects and fields.
+* **`CoreApiClient`** — interoghează endpointul `/graphql` pentru datele spațiului de lucru
+* **`MetadataApiClient`** — interoghează endpointul `/metadata` pentru configurarea spațiului de lucru și încărcarea fișierelor

 ```typescript
-import { CoreApiClient } from 'twenty-client-sdk/core';
+import { CoreApiClient, MetadataApiClient } from 'twenty-sdk/generated';

 const client = new CoreApiClient();
-
-// Query records
-const { companies } = await client.query({
-  companies: {
-    edges: {
-      node: {
-        id: true,
-        name: true,
-        domainName: true,
-      },
-    },
-  },
-});
-
-// Create a record
-const { createCompany } = await client.mutation({
-  createCompany: {
-    __args: {
-      data: {
-        name: 'Acme Corp',
-      },
-    },
-    id: true,
-    name: true,
-  },
-});
-```
-
-The client uses a selection-set syntax: pass `true` to include a field, use `__args` for arguments, and nest objects for relations. You get full autocompletion and type checking based on your workspace schema.
-
-<Note>
-**CoreApiClient is generated at dev/build time.** If you try to use it without running `yarn twenty dev` or `yarn twenty build` first, it throws an error. The generation happens automatically — the CLI introspects your workspace's GraphQL schema, generates a typed client using `@genql/cli`, writes the generated sources to `node_modules/twenty-client-sdk/dist/core/generated/`, and replaces the stubs in `node_modules/twenty-client-sdk/dist/core.mjs` and `node_modules/twenty-client-sdk/dist/core.cjs`.
-</Note>
-
-#### Using CoreSchema for type annotations
-
-`CoreSchema` provides TypeScript types matching your workspace objects, useful for typing component state or function parameters:
-
-```typescript
-import { CoreApiClient, CoreSchema } from 'twenty-client-sdk/core';
-import { useState } from 'react';
-
-const [company, setCompany] = useState<
-  Pick<CoreSchema.Company, 'id' | 'name'> | undefined
->(undefined);
-
-const client = new CoreApiClient();
-const result = await client.query({
-  company: {
-    __args: { filter: { position: { eq: 1 } } },
-    id: true,
-    name: true,
-  },
-});
-setCompany(result.company);
-```
-
-#### MetadataApiClient
-
-`MetadataApiClient` ships pre-built with the SDK (no generation required). It queries the `/metadata` endpoint for workspace configuration, applications, and file uploads:
-
-```typescript
-import { MetadataApiClient } from 'twenty-client-sdk/metadata';
+const { me } = await client.query({ me: { id: true, displayName: true } });

 const metadataClient = new MetadataApiClient();
-
-// Query workspace info
-const { currentWorkspace } = await metadataClient.query({
-  currentWorkspace: { id: true, displayName: true },
-});
-
-// List installed applications
-const { findManyApplications } = await metadataClient.query({
-  findManyApplications: {
-    id: true,
-    name: true,
-    version: true,
-  },
-});
+const { currentWorkspace } = await metadataClient.query({ currentWorkspace: { id: true } });
 ```

-#### Runtime credentials
+Ambii clienți sunt regenerați automat de `yarn twenty dev` ori de câte ori obiectele sau câmpurile tale se schimbă.

-When your code runs on Twenty (logic functions or front components), the platform injects credentials as environment variables:
+#### Acreditări la runtime în funcțiile de logică

-* `TWENTY_API_URL` — Base URL of the Twenty API
-* `TWENTY_API_KEY` — Short-lived key scoped to your application's default function role
+Când funcția rulează pe Twenty, platforma injectează acreditări ca variabile de mediu înainte de execuția codului:

-You do **not** need to pass these to the clients — they read from `process.env` automatically. The API key's permissions are determined by the role referenced in `defaultRoleUniversalIdentifier` in your `application-config.ts`.
+* `TWENTY_API_URL`: URL-ul de bază al API-ului Twenty către care țintește aplicația.
+* `TWENTY_API_KEY`: Cheie cu durată scurtă, limitată la rolul implicit de funcție al aplicației.
+
+Notițe:
+
+* Nu trebuie să transmiteți URL-ul sau cheia API către clientul generat. Acesta citește `TWENTY_API_URL` și `TWENTY_API_KEY` din process.env la runtime.
+* Permisiunile cheii API sunt determinate de rolul referențiat în `application-config.ts` prin `defaultRoleUniversalIdentifier`. Acesta este rolul implicit folosit de funcțiile de logică ale aplicației.
+* Aplicațiile pot defini roluri pentru a urma principiul celui mai mic privilegiu. Acordați doar permisiunile de care au nevoie funcțiile, apoi setați `defaultRoleUniversalIdentifier` la identificatorul universal al acelui rol.

 #### Încărcarea fișierelor

-`MetadataApiClient` includes an `uploadFile` method for attaching files to file-type fields. It implements the [GraphQL multipart request specification](https://github.com/jaydenseric/graphql-multipart-request-spec):
+Clientul `MetadataApiClient` generat include o metodă `uploadFile` pentru atașarea fișierelor la câmpuri de tip fișier ale obiectelor din spațiul tău de lucru. Deoarece clienții GraphQL standard nu acceptă în mod nativ încărcarea fișierelor multipart, clientul oferă această metodă dedicată care implementează, sub capotă, [specificația cererilor GraphQL multipart](https://github.com/jaydenseric/graphql-multipart-request-spec).

 ```typescript
-import { MetadataApiClient } from 'twenty-client-sdk/metadata';
+import { MetadataApiClient } from 'twenty-sdk/generated';
 import * as fs from 'fs';

 const metadataClient = new MetadataApiClient();
@@ -936,14 +652,25 @@ const fileBuffer = fs.readFileSync('./invoice.pdf');
 const uploadedFile = await metadataClient.uploadFile(
  fileBuffer,                                         // file contents as a Buffer
  'invoice.pdf',                                      // filename
-  'application/pdf',                                  // MIME type
-  '58a0a314-d7ea-4865-9850-7fb84e72f30b',            // field universalIdentifier
+  '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://...' }
 ```

+Semnătura metodei:
+
+```typescript
+uploadFile(
+  fileBuffer: Buffer,
+  filename: string,
+  contentType: string,
+  fieldMetadataUniversalIdentifier: string,
+): Promise<{ id: string; path: string; size: number; createdAt: string; url: string }>
+```
+
 | Parametru                          | Tip      | Descriere                                                                                   |
 | ---------------------------------- | -------- | ------------------------------------------------------------------------------------------- |
 | `fileBuffer`                       | `Buffer` | Conținutul brut al fișierului                                                               |
@@ -953,7 +680,8 @@ console.log(uploadedFile);

 Puncte cheie:

-* Uses the field's `universalIdentifier` (not its workspace-specific ID), so your upload code works across any workspace where your app is installed.
+* Metoda `uploadFile` este disponibilă pe `MetadataApiClient` deoarece mutația de încărcare este rezolvată de endpointul `/metadata`.
+* Folosește `universalIdentifier` al câmpului (nu ID-ul specific spațiului de lucru), astfel încât codul tău de încărcare funcționează în orice spațiu de lucru în care aplicația ta este instalată — în concordanță cu modul în care aplicațiile fac referire la câmpuri în rest.
 * `url` returnat este un URL semnat pe care îl poți folosi pentru a accesa fișierul încărcat.

 ### Exemplu Hello World
@@ -49,7 +49,7 @@ De aici puteți:

 ```bash filename="Terminal"
 # Add a new entity to your application (guided)
-yarn twenty add
+yarn twenty entity:add

 # Watch your application's function logs
 yarn twenty function:logs
@@ -123,7 +123,7 @@ Cu `--minimal`, sunt create doar fișierele de bază (`application-config.ts`, `
 Pe scurt:

 * **package.json**: Declară numele aplicației, versiunea, motoarele (Node 24+, Yarn 4) și adaugă `twenty-sdk` plus un script `twenty` care deleagă către CLI-ul local `twenty`. Rulați `yarn twenty help` pentru a lista toate comenzile disponibile.
-* **.gitignore**: Ignores common artifacts such as `node_modules`, `.yarn`, `.twenty/`, `dist/`, `build/`, coverage folders, log files, and `.env*` files.
+* **.gitignore**: Ignoră artefacte comune precum `node_modules`, `.yarn`, `generated/` (client tipizat), `dist/`, `build/`, foldere de coverage, fișiere jurnal și fișiere `.env*`.
 * **yarn.lock**, **.yarnrc.yml**, **.yarn/**: Blochează și configurează lanțul de instrumente Yarn 4 folosit de proiect.
 * **.nvmrc**: Fixează versiunea Node.js așteptată de proiect.
 * **.oxlintrc.json** și **tsconfig.json**: Oferă linting și configurație TypeScript pentru fișierele TypeScript ale aplicației.
@@ -167,8 +167,8 @@ export default defineObject({

 Comenzile ulterioare vor adăuga mai multe fișiere și foldere:

-* `yarn twenty dev` will auto-generate the typed `CoreApiClient` (for workspace data via `/graphql`) into `node_modules/twenty-client-sdk/`. The `MetadataApiClient` (for workspace configuration and file uploads via `/metadata`) ships pre-built and is available immediately. Import them from `twenty-client-sdk/core` and `twenty-client-sdk/metadata` respectively.
-* `yarn twenty add` will add entity definition files under `src/` for your custom objects, functions, front components, roles, skills, and more.
+* `yarn twenty dev` va genera automat doi clienți API tipizați în `node_modules/twenty-sdk/generated`: `CoreApiClient` (pentru datele spațiului de lucru prin `/graphql`) și `MetadataApiClient` (pentru configurarea spațiului de lucru și încărcarea fișierelor prin `/metadata`).
+* `yarn twenty entity:add` va adăuga fișiere de definire a entităților în `src/` pentru obiectele, funcțiile, componentele front-end, rolurile, abilitățile și altele.

 ## Autentificare

@@ -12,25 +12,7 @@ Aplicațiile sunt în prezent în testare alfa. Caracteristica funcționează, d
 După ce aplicația ta este [construită și testată local](/l/ro/developers/extend/apps/building), ai două căi pentru distribuire:

 * **Publică pe npm** — listează aplicația ta în marketplace-ul Twenty pentru ca orice spațiu de lucru să o poată descoperi și instala.
-* **Implementați o arhivă tar** — încărcați aplicația direct pe un server Twenty anume pentru uz intern sau privat.
-
-Ambele căi pornesc din aceeași etapă de **build**.
-
-## Construirea aplicației
-
-Comanda `build` compilează sursele TypeScript, transpilează funcțiile de logică și componentele de front-end și generează un `manifest.json` care descrie conținutul aplicației:
-
-```bash filename="Terminal"
-yarn twenty build
-```
-
-Rezultatul este scris în `.twenty/output/`. This directory contains everything needed for distribution: compiled code, assets, the manifest, and a copy of your `package.json`.
-
-To also create a `.tgz` tarball (used by the deploy command internally, or for manual distribution):
-
-```bash filename="Terminal"
-yarn twenty build --tarball
-```
+* **Trimite un tarball** — implementează aplicația ta pe un server Twenty specific pentru utilizare internă, fără a o face disponibilă public.

 ## Publicarea pe npm

@@ -39,72 +21,29 @@ Publicarea pe npm face ca aplicația ta să poată fi descoperită în marketpla
 ### Cerințe

 * Un cont [npm](https://www.npmjs.com)
-* The `twenty-app` keyword **must** be listed in your `package.json` `keywords` array
-
-### Adding the required keyword
-
-The Twenty marketplace discovers apps by searching the npm registry for packages with the `twenty-app` keyword. Add it to your `package.json`:
-
-```json filename="package.json"
-{
-  "name": "twenty-app-postcard-sender",
-  "version": "1.0.0",
-  "keywords": ["twenty-app"],
-  ...
-}
-```
-
-<Note>
-The marketplace searches for `keywords:twenty-app` on the npm registry. Without this keyword, your package won't appear in the marketplace even if it has the `twenty-app-` name prefix.
-</Note>
+* Numele pachetului tău **trebuie** să folosească prefixul `twenty-app-` (de ex., `twenty-app-postcard-sender`)

 ### Pași

-1. **Build your app:**
+1. **Construiește-ți aplicația** — CLI compilează sursele TypeScript și generează manifestul aplicației:

 ```bash filename="Terminal"
 yarn twenty build
 ```

-2. **Publish to npm:**
+2. **Publică pe npm** — publică pachetul construit în registrul npm:

 ```bash filename="Terminal"
-yarn twenty publish
+npx twenty publish
 ```

-This runs `npm publish` from the `.twenty/output/` directory.
+### Descoperire automată

-To publish under a specific dist-tag (e.g., `beta` or `next`):
-
-```bash filename="Terminal"
-yarn twenty publish --tag beta
-```
-
-### How marketplace discovery works
-
-The Twenty server syncs its marketplace catalog from the npm registry **every hour**:
-
-1. It searches for all npm packages with the `keywords:twenty-app` keyword
-2. For each package, it fetches the `manifest.json` from the npm CDN
-3. The app's metadata (name, description, author, logo, screenshots, category) is extracted from the manifest and displayed in the marketplace
-
-After publishing, your app can take up to one hour to appear in the marketplace. To trigger the sync immediately instead of waiting for the next hourly run:
-
-```bash filename="Terminal"
-yarn twenty catalog-sync
-```
-
-To target a specific remote:
-
-```bash filename="Terminal"
-yarn twenty catalog-sync -r production
-```
-
-The metadata shown in the marketplace comes from your `defineApplication()` call in your app source code — fields like `displayName`, `description`, `author`, `category`, `logoUrl`, `screenshots`, `aboutDescription`, `websiteUrl`, and `termsUrl`.
+Pachetele cu prefixul `twenty-app-` sunt descoperite automat de catalogul marketplace-ului Twenty. După publicare, aplicația ta apare în marketplace în câteva minute — fără înregistrare manuală sau aprobare necesară.

 ### Publicare CI

-Proiectul generat include un workflow GitHub Actions care publică la fiecare lansare:
+Proiectul generat include un workflow GitHub Actions care publică la fiecare lansare. Acesta rulează `app:build`, apoi `npm publish --provenance` din rezultatul build-ului:

 ```yaml filename=".github/workflows/publish.yml"
 name: Publish
@@ -133,117 +72,48 @@ jobs:
          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
 ```

-For other CI systems (GitLab CI, CircleCI, etc.), the same three commands apply: `yarn install`, `yarn twenty build`, then `npm publish` from `.twenty/output`.
+Pentru alte sisteme CI (GitLab CI, CircleCI etc.), se aplică aceleași trei comenzi: `yarn install`, `npx twenty build`, apoi `npm publish` din `.twenty/output`.

 <Tip>
 **npm provenance** este opțională, dar recomandată. Publicarea cu `--provenance` adaugă un badge de încredere la listarea ta în npm, permițând utilizatorilor să verifice că pachetul a fost construit dintr-un commit specific într-un pipeline CI public. Vezi [documentația npm provenance](https://docs.npmjs.com/generating-provenance-statements) pentru instrucțiuni de configurare.
 </Tip>

-## Deploying to a server (tarball)
+## Distribuire internă

-For apps you don't want publicly available — proprietary tools, enterprise-only integrations, or experimental builds — you can deploy a tarball directly to a Twenty server.
+Pentru aplicațiile pe care nu le dorești disponibile public — instrumente proprietare, integrări doar pentru enterprise sau build-uri experimentale — poți trimite un tarball direct pe un server Twenty.

-### Cerințe
+### Trimite un tarball

-Before deploying, you need a configured remote pointing to the target server. Remotes store the server URL and authentication credentials locally in `~/.twenty/config.json`.
-
-Add a remote:
+Construiește-ți aplicația și implementeaz-o pe un server specific, într-un singur pas:

 ```bash filename="Terminal"
-yarn twenty remote add --url https://your-twenty-server.com --as production
+npx twenty publish --server <server-url>
 ```

-For a local development server:
-
-```bash filename="Terminal"
-yarn twenty remote add --local --as local
-```
-
-You can also authenticate with an API key for non-interactive environments:
-
-```bash filename="Terminal"
-yarn twenty remote add --url https://your-twenty-server.com --token <api-key> --as production
-```
-
-Manage your remotes:
-
-```bash filename="Terminal"
-yarn twenty remote list       # List all configured remotes
-yarn twenty remote switch prod # Set the default remote
-yarn twenty remote status     # Show active remote and auth status
-yarn twenty remote remove old # Remove a remote
-```
-
-### Deploying
-
-Build and upload your app to the server in one step:
-
-```bash filename="Terminal"
-yarn twenty deploy
-```
-
-This builds the app with `--tarball`, then uploads the tarball to the default remote via a GraphQL multipart upload.
-
-To deploy to a specific remote:
-
-```bash filename="Terminal"
-yarn twenty deploy -r production
-```
-
-### Sharing a deployed app
-
-Tarball apps are not listed in the public marketplace, so other workspaces on the same server won't discover them by browsing. To share a deployed app:
-
-1. Go to **Settings > Applications > Registrations** and open your app
-2. In the **Distribution** tab, click **Copy share link**
-3. Share this link with users on other workspaces — it takes them directly to the app's install page
-
-The share link uses the server's base URL (without any workspace subdomain) so it works for any workspace on the server.
+Orice spațiu de lucru de pe acel server poate apoi instala și actualiza aplicația din pagina de setări **Applications**.

 ### Gestionarea versiunilor

 Pentru a lansa o actualizare:

 1. Actualizează câmpul `version` din `package.json`
-2. Run `yarn twenty deploy` (or `yarn twenty deploy -r production`)
-3. Workspaces that have the app installed will see the upgrade available in their settings
+2. Trimite un tarball nou cu `npx twenty publish --server <server-url>`
+3. Spațiile de lucru de pe acel server vor vedea actualizarea disponibilă în setările lor

-## Installing apps
+<Note>
+Aplicațiile interne sunt limitate la serverul pe care sunt trimise. Acestea nu vor apărea în marketplace-ul public și nu pot fi instalate de spațiile de lucru de pe alte servere.
+</Note>

-Once an app is published (npm) or deployed (tarball), workspaces install it through the UI:
-
-```bash filename="Terminal"
-yarn twenty install
-```
-
-Or from the **Settings > Applications** page in the Twenty UI, where both marketplace and tarball-deployed apps can be browsed and installed.
-
-## App distribution categories
+## Categorii de aplicații

 Twenty organizează aplicațiile în trei categorii, în funcție de modul în care sunt distribuite:

-| Categorie              | Cum funcționează                                                                                                                 | Vizibilă în marketplace? |
-| ---------------------- | -------------------------------------------------------------------------------------------------------------------------------- | ------------------------ |
-| **Dezvoltare**         | Aplicații în modul de dezvoltare local, rulate prin `yarn twenty dev`. Folosite pentru construire și testare.                    | Nu                       |
-| **Published (npm)**    | Apps published to npm with the `twenty-app` keyword. Listate în marketplace pentru ca orice spațiu de lucru să le poată instala. | Da                       |
-| **Internal (tarball)** | Aplicații implementate prin tarball pe un server specific. Available only to workspaces on that server via a share link.         | Nu                       |
+| Categorie      | Cum funcționează                                                                                                                  | Vizibilă în marketplace? |
+| -------------- | --------------------------------------------------------------------------------------------------------------------------------- | ------------------------ |
+| **Dezvoltare** | Aplicații în modul de dezvoltare local, rulate prin `yarn twenty dev`. Folosite pentru construire și testare.                     | Nu                       |
+| **Publicat**   | Aplicații publicate pe npm cu prefixul `twenty-app-`. Listate în marketplace pentru ca orice spațiu de lucru să le poată instala. | Da                       |
+| **Intern**     | Aplicații implementate prin tarball pe un server specific. Disponibile doar pentru spațiile de lucru de pe acel server.           | Nu                       |

 <Tip>
 Pornește în modul **Dezvoltare** în timp ce îți construiești aplicația. Când este gata, alege **Publicat** (npm) pentru distribuire largă sau **Intern** (tarball) pentru implementare privată.
 </Tip>
-
-## CLI reference
-
-| Comandă                     | Descriere                                      | Key flags                                           |
-| --------------------------- | ---------------------------------------------- | --------------------------------------------------- |
-| `yarn twenty build`         | Compile app and generate manifest              | `--tarball` — also create a `.tgz` package          |
-| `yarn twenty publish`       | Build and publish to npm                       | `--tag <tag>` — npm dist-tag (e.g., `beta`, `next`) |
-| `yarn twenty deploy`        | Build and upload tarball to a server           | `-r, --remote <name>` — target remote               |
-| `yarn twenty catalog-sync`  | Trigger marketplace catalog sync on the server | `-r, --remote <name>` — target remote               |
-| `yarn twenty install`       | Install a deployed app on a workspace          | `-r, --remote <name>` — target remote               |
-| `yarn twenty dev`           | Watch and sync local changes                   | Uses default remote                                 |
-| `yarn twenty remote add`    | Add a server connection                        | `--url`, `--token`, `--as`, `--local`, `--port`     |
-| `yarn twenty remote list`   | List configured remotes                        | —                                                   |
-| `yarn twenty remote switch` | Set default remote                             | —                                                   |
-| `yarn twenty remote status` | Show connection status                         | —                                                   |
-| `yarn twenty remote remove` | Remove a remote                                | —                                                   |
@@ -15,21 +15,19 @@ description: Определяйте объекты, функции логики,

 SDK предоставляет вспомогательные функции для определения сущностей вашего приложения. Как описано в [Обнаружение сущностей](/l/ru/developers/extend/apps/getting-started#entity-detection), вы должны использовать `export default define<Entity>({...})`, чтобы ваши сущности были обнаружены:

-| Функция                          | Назначение                                                                          |
-| -------------------------------- | ----------------------------------------------------------------------------------- |
-| `defineApplication`              | Настройка метаданных приложения (обязательно, по одному на приложение)              |
-| `defineObject`                   | Определяет пользовательские объекты с полями                                        |
-| `defineField`                    | Extend existing objects with additional fields or define standalone relation fields |
-| `defineLogicFunction`            | Определение логических функций с обработчиками                                      |
-| `definePreInstallLogicFunction`  | Определяет предустановочную логическую функцию (по одной на приложение)             |
-| `definePostInstallLogicFunction` | Определяет послеустановочную логическую функцию (по одной на приложение)            |
-| `defineFrontComponent`           | Определение фронт-компонентов для настраиваемого интерфейса                         |
-| `defineRole`                     | Настраивает права роли и доступ к объектам                                          |
-| `defineView`                     | Определяйте сохранённые представления для объектов                                  |
-| `defineNavigationMenuItem`       | Определяйте ссылки боковой панели навигации                                         |
-| `defineSkill`                    | Определение навыков агента ИИ                                                       |
-| `defineAgent`                    | Define AI agents                                                                    |
-| `definePageLayout`               | Define custom page layouts                                                          |
+| Функция                          | Назначение                                                               |
+| -------------------------------- | ------------------------------------------------------------------------ |
+| `defineApplication`              | Настройка метаданных приложения (обязательно, по одному на приложение)   |
+| `defineObject`                   | Определяет пользовательские объекты с полями                             |
+| `defineLogicFunction`            | Определение логических функций с обработчиками                           |
+| `definePreInstallLogicFunction`  | Определяет предустановочную логическую функцию (по одной на приложение)  |
+| `definePostInstallLogicFunction` | Определяет послеустановочную логическую функцию (по одной на приложение) |
+| `defineFrontComponent`           | Определение фронт-компонентов для настраиваемого интерфейса              |
+| `defineRole`                     | Настраивает права роли и доступ к объектам                               |
+| `defineField`                    | Расширение существующих объектов дополнительными полями                  |
+| `defineView`                     | Определяйте сохранённые представления для объектов                       |
+| `defineNavigationMenuItem`       | Определяйте ссылки боковой панели навигации                              |
+| `defineSkill`                    | Определение навыков агента ИИ                                            |

 Эти функции проверяют вашу конфигурацию на этапе сборки и обеспечивают автодополнение в IDE и безопасность типов.

@@ -38,7 +36,7 @@ SDK предоставляет вспомогательные функции д
 Пользовательские объекты описывают как схему, так и поведение записей в вашем рабочем пространстве. Используйте `defineObject()` для определения объектов со встроенной валидацией:

 ```typescript
-// src/objects/postCard.object.ts
+// src/app/postCard.object.ts
 import { defineObject, FieldType } from 'twenty-sdk';

 enum PostCardStatus {
@@ -112,7 +110,7 @@ export default defineObject({
 * `universalIdentifier` должен быть уникальным и стабильным между развёртываниями.
 * Каждому полю требуются `name`, `type`, `label` и собственный стабильный `universalIdentifier`.
 * Массив `fields` необязателен — вы можете определять объекты без пользовательских полей.
-* You can scaffold new objects using `yarn twenty add`, which guides you through naming, fields, and relationships.
+* Вы можете сгенерировать новые объекты с помощью `yarn twenty entity:add`, который проведёт вас через настройку имени, полей и связей.

 <Note>
 **Базовые поля создаются автоматически.** Когда вы определяете пользовательский объект, Twenty автоматически добавляет стандартные поля,
@@ -122,197 +120,6 @@ export default defineObject({
 но это не рекомендуется.
 </Note>

-### Определение полей для существующих объектов
-
-Use `defineField()` to add fields to objects you don't own — such as standard Twenty objects (Person, Company, etc.) or objects from other apps. Unlike inline fields in `defineObject()`, standalone fields require an `objectUniversalIdentifier` to specify which object they extend:
-
-```typescript
-// src/fields/company-loyalty-tier.field.ts
-import { defineField, FieldType } from 'twenty-sdk';
-
-export default defineField({
-  universalIdentifier: 'f2a1b3c4-d5e6-7890-abcd-ef1234567890',
-  objectUniversalIdentifier: '701aecb9-eb1c-4d84-9d94-b954b231b64b', // Company object
-  name: 'loyaltyTier',
-  type: FieldType.SELECT,
-  label: 'Loyalty Tier',
-  icon: 'IconStar',
-  options: [
-    { value: 'BRONZE', label: 'Bronze', position: 0, color: 'orange' },
-    { value: 'SILVER', label: 'Silver', position: 1, color: 'gray' },
-    { value: 'GOLD', label: 'Gold', position: 2, color: 'yellow' },
-  ],
-});
-```
-
-Основные моменты:
-
-* `objectUniversalIdentifier` identifies the target object. For standard objects, use `STANDARD_OBJECT_UNIVERSAL_IDENTIFIERS` exported from `twenty-sdk`.
-* When defining fields inline in `defineObject()`, you do **not** need `objectUniversalIdentifier` — it's inherited from the parent object.
-* `defineField()` is the only way to add fields to objects you didn't create with `defineObject()`.
-
-### Связи
-
-Relations connect objects together. In Twenty, relations are always **bidirectional** — you define both sides, and each side references the other.
-
-There are two relation types:
-
-| Тип отношения | Описание                                                      | Has foreign key?       |
-| ------------- | ------------------------------------------------------------- | ---------------------- |
-| `MANY_TO_ONE` | Many records of this object point to one record of the target | Yes (`joinColumnName`) |
-| `ONE_TO_MANY` | One record of this object has many records of the target      | No (inverse side)      |
-
-#### How relations work
-
-Every relation requires **two fields** that reference each other:
-
-1. The **MANY_TO_ONE** side — lives on the object that holds the foreign key
-2. The **ONE_TO_MANY** side — lives on the object that owns the collection
-
-Both fields use `FieldType.RELATION` and cross-reference each other via `relationTargetFieldMetadataUniversalIdentifier`.
-
-#### Example: Post Card has many Recipients
-
-Suppose a `PostCard` can be sent to many `PostCardRecipient` records. Each recipient belongs to exactly one post card.
-
-**Step 1: Define the ONE_TO_MANY side on PostCard** (the "one" side):
-
-```typescript
-// src/fields/post-card-recipients-on-post-card.field.ts
-import { defineField, FieldType, RelationType } from 'twenty-sdk';
-import { POST_CARD_UNIVERSAL_IDENTIFIER } from '../objects/post-card.object';
-import { POST_CARD_RECIPIENT_UNIVERSAL_IDENTIFIER } from '../objects/post-card-recipient.object';
-
-// Export so the other side can reference it
-export const POST_CARD_RECIPIENTS_FIELD_ID = 'a1111111-1111-1111-1111-111111111111';
-// Import from the other side
-import { POST_CARD_FIELD_ID } from './post-card-on-post-card-recipient.field';
-
-export default defineField({
-  universalIdentifier: POST_CARD_RECIPIENTS_FIELD_ID,
-  objectUniversalIdentifier: POST_CARD_UNIVERSAL_IDENTIFIER,
-  type: FieldType.RELATION,
-  name: 'postCardRecipients',
-  label: 'Post Card Recipients',
-  icon: 'IconUsers',
-  relationTargetObjectMetadataUniversalIdentifier: POST_CARD_RECIPIENT_UNIVERSAL_IDENTIFIER,
-  relationTargetFieldMetadataUniversalIdentifier: POST_CARD_FIELD_ID,
-  universalSettings: {
-    relationType: RelationType.ONE_TO_MANY,
-  },
-});
-```
-
-**Step 2: Define the MANY_TO_ONE side on PostCardRecipient** (the "many" side — holds the foreign key):
-
-```typescript
-// src/fields/post-card-on-post-card-recipient.field.ts
-import { defineField, FieldType, RelationType, OnDeleteAction } from 'twenty-sdk';
-import { POST_CARD_UNIVERSAL_IDENTIFIER } from '../objects/post-card.object';
-import { POST_CARD_RECIPIENT_UNIVERSAL_IDENTIFIER } from '../objects/post-card-recipient.object';
-
-// Export so the other side can reference it
-export const POST_CARD_FIELD_ID = 'b2222222-2222-2222-2222-222222222222';
-// Import from the other side
-import { POST_CARD_RECIPIENTS_FIELD_ID } from './post-card-recipients-on-post-card.field';
-
-export default defineField({
-  universalIdentifier: POST_CARD_FIELD_ID,
-  objectUniversalIdentifier: POST_CARD_RECIPIENT_UNIVERSAL_IDENTIFIER,
-  type: FieldType.RELATION,
-  name: 'postCard',
-  label: 'Post Card',
-  icon: 'IconMail',
-  relationTargetObjectMetadataUniversalIdentifier: POST_CARD_UNIVERSAL_IDENTIFIER,
-  relationTargetFieldMetadataUniversalIdentifier: POST_CARD_RECIPIENTS_FIELD_ID,
-  universalSettings: {
-    relationType: RelationType.MANY_TO_ONE,
-    onDelete: OnDeleteAction.CASCADE,
-    joinColumnName: 'postCardId',
-  },
-});
-```
-
-<Note>
-**Circular imports:** Both relation fields reference each other's `universalIdentifier`. To avoid circular import issues, export your field IDs as named constants from each file, and import them in the other file. The build system resolves these at compile time.
-</Note>
-
-#### Relating to standard objects
-
-To create a relation with a built-in Twenty object (Person, Company, etc.), use `STANDARD_OBJECT_UNIVERSAL_IDENTIFIERS`:
-
-```typescript
-// src/fields/person-on-self-hosting-user.field.ts
-import {
-  defineField,
-  FieldType,
-  RelationType,
-  OnDeleteAction,
-  STANDARD_OBJECT_UNIVERSAL_IDENTIFIERS,
-} from 'twenty-sdk';
-import { SELF_HOSTING_USER_UNIVERSAL_IDENTIFIER } from '../objects/self-hosting-user.object';
-
-export const PERSON_FIELD_ID = 'c3333333-3333-3333-3333-333333333333';
-export const SELF_HOSTING_USER_REVERSE_FIELD_ID = 'd4444444-4444-4444-4444-444444444444';
-
-export default defineField({
-  universalIdentifier: PERSON_FIELD_ID,
-  objectUniversalIdentifier: SELF_HOSTING_USER_UNIVERSAL_IDENTIFIER,
-  type: FieldType.RELATION,
-  name: 'person',
-  label: 'Person',
-  description: 'Person matching with the self hosting user',
-  isNullable: true,
-  relationTargetObjectMetadataUniversalIdentifier:
-    STANDARD_OBJECT_UNIVERSAL_IDENTIFIERS.person.universalIdentifier,
-  relationTargetFieldMetadataUniversalIdentifier: SELF_HOSTING_USER_REVERSE_FIELD_ID,
-  universalSettings: {
-    relationType: RelationType.MANY_TO_ONE,
-    onDelete: OnDeleteAction.SET_NULL,
-    joinColumnName: 'personId',
-  },
-});
-```
-
-#### Relation field properties
-
-| Свойство                                          | Обязательно      | Описание                                                                                              |
-| ------------------------------------------------- | ---------------- | ----------------------------------------------------------------------------------------------------- |
-| `type`                                            | Да               | Must be `FieldType.RELATION`                                                                          |
-| `relationTargetObjectMetadataUniversalIdentifier` | Да               | The `universalIdentifier` of the target object                                                        |
-| `relationTargetFieldMetadataUniversalIdentifier`  | Да               | The `universalIdentifier` of the matching field on the target object                                  |
-| `universalSettings.relationType`                  | Да               | `RelationType.MANY_TO_ONE` or `RelationType.ONE_TO_MANY`                                              |
-| `universalSettings.onDelete`                      | MANY_TO_ONE only | What happens when the referenced record is deleted: `CASCADE`, `SET_NULL`, `RESTRICT`, or `NO_ACTION` |
-| `universalSettings.joinColumnName`                | MANY_TO_ONE only | Database column name for the foreign key (e.g., `postCardId`)                                         |
-
-#### Inline relation fields in defineObject
-
-You can also define relation fields directly inside `defineObject()`. In that case, omit `objectUniversalIdentifier` — it's inherited from the parent object:
-
-```typescript
-export default defineObject({
-  universalIdentifier: '...',
-  nameSingular: 'postCardRecipient',
-  // ...
-  fields: [
-    {
-      universalIdentifier: POST_CARD_FIELD_ID,
-      type: FieldType.RELATION,
-      name: 'postCard',
-      label: 'Post Card',
-      relationTargetObjectMetadataUniversalIdentifier: POST_CARD_UNIVERSAL_IDENTIFIER,
-      relationTargetFieldMetadataUniversalIdentifier: POST_CARD_RECIPIENTS_FIELD_ID,
-      universalSettings: {
-        relationType: RelationType.MANY_TO_ONE,
-        onDelete: OnDeleteAction.CASCADE,
-        joinColumnName: 'postCardId',
-      },
-    },
-    // ... other fields
-  ],
-});
-```
-
 ### Конфигурация приложения (application-config.ts)

 У каждого приложения есть единственный файл `application-config.ts`, который описывает:
@@ -354,29 +161,13 @@ export default defineApplication({
 * `defaultRoleUniversalIdentifier` должен соответствовать файлу роли (см. ниже).
 * Предустановочные и послеустановочные функции автоматически обнаруживаются во время сборки манифеста. См. [Предустановочные функции](#pre-install-functions) и [Послеустановочные функции](#post-install-functions).

-#### Marketplace metadata
-
-If you plan to [publish your app](/l/ru/developers/extend/apps/publishing), these optional fields control how your app appears in the marketplace:
-
-| Поле               | Описание                                            |
-| ------------------ | --------------------------------------------------- |
-| `author`           | Author or company name                              |
-| `category`         | App category for marketplace filtering              |
-| `logoUrl`          | Path to your app logo (relative to `./assets/`)     |
-| `screenshots`      | Array of screenshot paths (relative to `./assets/`) |
-| `aboutDescription` | Longer markdown description for the "About" tab     |
-| `websiteUrl`       | Link to your website                                |
-| `termsUrl`         | Link to terms of service                            |
-| `emailSupport`     | Support email address                               |
-| `issueReportUrl`   | Link to issue tracker                               |
-
 #### Роли и разрешения

 Приложения могут определять роли, инкапсулирующие права на объекты и действия в вашем рабочем пространстве. Поле `defaultRoleUniversalIdentifier` в `application-config.ts` обозначает роль по умолчанию, используемую логическими функциями вашего приложения.

 * Ключ API во время выполнения, подставляемый как `TWENTY_API_KEY`, получается из этой роли функции по умолчанию.
 * Типизированный клиент будет ограничен правами, предоставленными этой ролью.
-* Follow least-privilege: create a dedicated role with only the permissions your functions need, then reference its universal identifier.
+* Следуйте принципу наименьших привилегий: создайте отдельную роль только с теми правами, которые нужны вашим функциям, и укажите её универсальный идентификатор.

 ##### Роль функции по умолчанию (*.role.ts)

@@ -429,7 +220,7 @@ export default defineRole({

 Заметки:

-* Start from the scaffolded role, then progressively restrict it following least-privilege.
+* Начните со сгенерированной роли, затем постепенно ограничивайте её, следуя принципу наименьших привилегий.
 * Замените `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).
@@ -439,7 +230,7 @@ export default defineRole({
 Каждый файл функции использует `defineLogicFunction()` для экспорта конфигурации с обработчиком и необязательными триггерами.

 ```typescript
-// src/logic-functions/createPostCard.logic-function.ts
+// 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';
@@ -533,7 +324,7 @@ export default definePreInstallLogicFunction({
 Вы также можете вручную выполнить предустановочную функцию в любое время с помощью CLI:

 ```bash filename="Terminal"
-yarn twenty exec --preInstall
+yarn twenty function:execute --preInstall
 ```

 Основные моменты:
@@ -543,7 +334,7 @@ yarn twenty exec --preInstall
 * Для каждого приложения допускается только одна предустановочная функция. Сборка манифеста завершится ошибкой, если будет обнаружено более одной такой функции.
 * Параметр `universalIdentifier` функции автоматически устанавливается как `preInstallLogicFunctionUniversalIdentifier` в манифесте приложения во время сборки — вам не нужно ссылаться на него в `defineApplication()`.
 * Тайм-аут по умолчанию установлен на 300 секунд (5 минут), чтобы обеспечить выполнение более длительных задач подготовки.
-* Pre-install functions do not need triggers — they are invoked by the platform before installation or manually via `exec --preInstall`.
+* Предустановочным функциям не нужны триггеры — платформа вызывает их перед установкой или вручную через `function:execute --preInstall`.

 ### Послеустановочные функции

@@ -571,7 +362,7 @@ export default definePostInstallLogicFunction({
 Вы также можете вручную выполнить постустановочную функцию в любое время с помощью CLI:

 ```bash filename="Terminal"
-yarn twenty exec --postInstall
+yarn twenty function:execute --postInstall
 ```

 Основные моменты:
@@ -581,7 +372,7 @@ yarn twenty exec --postInstall
 * Для каждого приложения допускается только одна послеустановочная функция. Сборка манифеста завершится ошибкой, если будет обнаружено более одной такой функции.
 * Параметр `universalIdentifier` функции автоматически устанавливается как `postInstallLogicFunctionUniversalIdentifier` в манифесте приложения во время сборки — вам не нужно ссылаться на него в `defineApplication()`.
 * Тайм-аут по умолчанию установлен на 300 секунд (5 минут), чтобы позволить выполнять более длительные задачи настройки, такие как инициализация данных.
-* Post-install functions do not need triggers — they are invoked by the platform during installation or manually via `exec --postInstall`.
+* Постустановочным функциям не нужны триггеры — платформа вызывает их во время установки или вручную через `function:execute --postInstall`.

 ### Полезная нагрузка триггера маршрута

@@ -625,15 +416,15 @@ const handler = async (event: RoutePayload) => {

 Тип `RoutePayload` имеет следующую структуру:

-| Свойство                     | Тип                                   | Описание                                                                                 |
-| ---------------------------- | ------------------------------------- | ---------------------------------------------------------------------------------------- |
-| `headers`                    | `Record<string, string \| undefined>` | HTTP-заголовки (только перечисленные в `forwardedRequestHeaders`)                        |
-| `queryStringParameters`      | `Record<string, string \| undefined>` | Параметры строки запроса (несколько значений объединяются запятыми)                      |
-| `pathParameters`             | `Record<string, string \| undefined>` | Path parameters extracted from the route pattern (e.g., `/users/:id` -> `{ id: '123' }`) |
-| `body`                       | `object \| null`                      | Разобранное тело запроса (JSON)                                                          |
-| `isBase64Encoded`            | `логический тип`                      | Является ли тело закодированным в base64                                                 |
-| `requestContext.http.method` | `строка`                              | Метод HTTP (GET, POST, PUT, PATCH, DELETE)                                               |
-| `requestContext.http.path`   | `строка`                              | Необработанный путь запроса                                                              |
+| Свойство                     | Тип                                   | Описание                                                                                   |
+| ---------------------------- | ------------------------------------- | ------------------------------------------------------------------------------------------ |
+| `headers`                    | `Record<string, string \| undefined>` | HTTP-заголовки (только перечисленные в `forwardedRequestHeaders`)                          |
+| `queryStringParameters`      | `Record<string, string \| undefined>` | Параметры строки запроса (несколько значений объединяются запятыми)                        |
+| `pathParameters`             | `Record<string, string \| undefined>` | Параметры пути, извлечённые из шаблона маршрута (например, `/users/:id` → `{ id: '123' }`) |
+| `body`                       | `object \| null`                      | Разобранное тело запроса (JSON)                                                            |
+| `isBase64Encoded`            | `логический тип`                      | Является ли тело закодированным в base64                                                   |
+| `requestContext.http.method` | `строка`                              | Метод HTTP (GET, POST, PUT, PATCH, DELETE)                                                 |
+| `requestContext.http.path`   | `строка`                              | Необработанный путь запроса                                                                |

 ### Проброс HTTP-заголовков

@@ -675,7 +466,7 @@ const handler = async (event: RoutePayload) => {

 Вы можете создать новые функции двумя способами:

-* **Scaffolded**: Run `yarn twenty add` and choose the option to add a new logic function. Это создаёт стартовый файл с обработчиком и конфигурацией.
+* **Сгенерировано**: Запустите `yarn twenty entity:add` и выберите опцию добавления новой функции логики. Это создаёт стартовый файл с обработчиком и конфигурацией.
 * **Вручную**: Создайте новый файл `*.logic-function.ts` и используйте `defineLogicFunction()`, следуя тому же шаблону.

 ### Пометка логической функции как инструмента
@@ -687,7 +478,7 @@ const handler = async (event: RoutePayload) => {
 ```typescript
 // src/logic-functions/enrich-company.logic-function.ts
 import { defineLogicFunction } from 'twenty-sdk';
-import { CoreApiClient } from 'twenty-client-sdk/core';
+import { CoreApiClient } from 'twenty-sdk/generated';

 const handler = async (params: { companyName: string; domain?: string }) => {
  const client = new CoreApiClient();
@@ -776,7 +567,7 @@ export default defineFrontComponent({

 Вы можете создать новые фронт-компоненты двумя способами:

-* **Scaffolded**: Run `yarn twenty add` and choose the option to add a new front component.
+* **Сгенерировано**: Запустите `yarn twenty entity:add` и выберите опцию добавления нового фронтенд-компонента.
 * **Вручную**: Создайте новый файл `.tsx` и используйте `defineFrontComponent()`, следуя тому же шаблону.

 ### Навыки
@@ -811,122 +602,47 @@ export default defineSkill({

 Вы можете создать новые навыки двумя способами:

-* **Scaffolded**: Run `yarn twenty add` and choose the option to add a new skill.
+* **Сгенерировано**: Запустите `yarn twenty entity:add` и выберите опцию добавления нового навыка.
 * **Вручную**: Создайте новый файл и используйте `defineSkill()`, следуя тому же шаблону.

-### Typed API clients (`twenty-client-sdk`)
+### Сгенерированные типизированные клиенты

-The `twenty-client-sdk` package provides two typed GraphQL clients for interacting with the Twenty API from your logic functions and front components:
+Два типизированных клиента автоматически генерируются с помощью `yarn twenty dev` и сохраняются в `node_modules/twenty-sdk/generated` на основе схемы вашего рабочего пространства:

-| Клиент              | Импорт                       | Endpoint                                       | Generated?             |
-| ------------------- | ---------------------------- | ---------------------------------------------- | ---------------------- |
-| `CoreApiClient`     | `twenty-client-sdk/core`     | `/graphql` — workspace data (records, objects) | Yes, at dev/build time |
-| `MetadataApiClient` | `twenty-client-sdk/metadata` | `/metadata` — workspace config, file uploads   | No, ships pre-built    |
-
-#### CoreApiClient
-
-`CoreApiClient` is the main client for querying and mutating workspace data. It is **generated from your workspace schema** during `yarn twenty dev` or `yarn twenty build`, so it's fully typed to match your objects and fields.
+* **`CoreApiClient`** — выполняет запросы к конечной точке `/graphql` для получения данных рабочего пространства
+* **`MetadataApiClient`** — выполняет запросы к эндпоинту `/metadata` для получения конфигурации рабочего пространства и загрузки файлов.

 ```typescript
-import { CoreApiClient } from 'twenty-client-sdk/core';
+import { CoreApiClient, MetadataApiClient } from 'twenty-sdk/generated';

 const client = new CoreApiClient();
-
-// Query records
-const { companies } = await client.query({
-  companies: {
-    edges: {
-      node: {
-        id: true,
-        name: true,
-        domainName: true,
-      },
-    },
-  },
-});
-
-// Create a record
-const { createCompany } = await client.mutation({
-  createCompany: {
-    __args: {
-      data: {
-        name: 'Acme Corp',
-      },
-    },
-    id: true,
-    name: true,
-  },
-});
-```
-
-The client uses a selection-set syntax: pass `true` to include a field, use `__args` for arguments, and nest objects for relations. You get full autocompletion and type checking based on your workspace schema.
-
-<Note>
-**CoreApiClient is generated at dev/build time.** If you try to use it without running `yarn twenty dev` or `yarn twenty build` first, it throws an error. The generation happens automatically — the CLI introspects your workspace's GraphQL schema, generates a typed client using `@genql/cli`, writes the generated sources to `node_modules/twenty-client-sdk/dist/core/generated/`, and replaces the stubs in `node_modules/twenty-client-sdk/dist/core.mjs` and `node_modules/twenty-client-sdk/dist/core.cjs`.
-</Note>
-
-#### Using CoreSchema for type annotations
-
-`CoreSchema` provides TypeScript types matching your workspace objects, useful for typing component state or function parameters:
-
-```typescript
-import { CoreApiClient, CoreSchema } from 'twenty-client-sdk/core';
-import { useState } from 'react';
-
-const [company, setCompany] = useState<
-  Pick<CoreSchema.Company, 'id' | 'name'> | undefined
->(undefined);
-
-const client = new CoreApiClient();
-const result = await client.query({
-  company: {
-    __args: { filter: { position: { eq: 1 } } },
-    id: true,
-    name: true,
-  },
-});
-setCompany(result.company);
-```
-
-#### MetadataApiClient
-
-`MetadataApiClient` ships pre-built with the SDK (no generation required). It queries the `/metadata` endpoint for workspace configuration, applications, and file uploads:
-
-```typescript
-import { MetadataApiClient } from 'twenty-client-sdk/metadata';
+const { me } = await client.query({ me: { id: true, displayName: true } });

 const metadataClient = new MetadataApiClient();
-
-// Query workspace info
-const { currentWorkspace } = await metadataClient.query({
-  currentWorkspace: { id: true, displayName: true },
-});
-
-// List installed applications
-const { findManyApplications } = await metadataClient.query({
-  findManyApplications: {
-    id: true,
-    name: true,
-    version: true,
-  },
-});
+const { currentWorkspace } = await metadataClient.query({ currentWorkspace: { id: true } });
 ```

-#### Runtime credentials
+Оба клиента автоматически перегенерируются с помощью `yarn twenty dev` при изменении ваших объектов или полей.

-When your code runs on Twenty (logic functions or front components), the platform injects credentials as environment variables:
+#### Учётные данные времени выполнения в логических функциях

-* `TWENTY_API_URL` — Base URL of the Twenty API
-* `TWENTY_API_KEY` — Short-lived key scoped to your application's default function role
+Когда ваша функция запускается на Twenty, платформа подставляет учётные данные как переменные окружения перед выполнением вашего кода:

-You do **not** need to pass these to the clients — they read from `process.env` automatically. The API key's permissions are determined by the role referenced in `defaultRoleUniversalIdentifier` in your `application-config.ts`.
+* `TWENTY_API_URL`: Базовый URL API Twenty, на который нацелено ваше приложение.
+* `TWENTY_API_KEY`: Краткоживущий ключ, ограниченный ролью функции по умолчанию вашего приложения.
+
+Заметки:
+
+* Вам не нужно передавать URL или ключ API сгенерированному клиенту. Он читает `TWENTY_API_URL` и `TWENTY_API_KEY` из process.env во время выполнения.
+* Права ключа API определяются ролью, на которую ссылается ваш `application-config.ts` через `defaultRoleUniversalIdentifier`. Это роль по умолчанию, используемая логическими функциями вашего приложения.
+* Приложения могут определять роли, чтобы следовать принципу наименьших привилегий. Предоставляйте только те права, которые нужны вашим функциям, затем укажите в `defaultRoleUniversalIdentifier` универсальный идентификатор этой роли.

 #### Загрузка файлов

-`MetadataApiClient` includes an `uploadFile` method for attaching files to file-type fields. It implements the [GraphQL multipart request specification](https://github.com/jaydenseric/graphql-multipart-request-spec):
+Сгенерированный `MetadataApiClient` включает метод `uploadFile` для прикрепления файлов к полям типа «файл» в объектах вашего рабочего пространства. Поскольку стандартные клиенты GraphQL изначально не поддерживают многочастовую загрузку файлов, клиент предоставляет специальный метод, который под капотом реализует [спецификацию многочастных запросов GraphQL](https://github.com/jaydenseric/graphql-multipart-request-spec).

 ```typescript
-import { MetadataApiClient } from 'twenty-client-sdk/metadata';
+import { MetadataApiClient } from 'twenty-sdk/generated';
 import * as fs from 'fs';

 const metadataClient = new MetadataApiClient();
@@ -936,14 +652,25 @@ const fileBuffer = fs.readFileSync('./invoice.pdf');
 const uploadedFile = await metadataClient.uploadFile(
  fileBuffer,                                         // file contents as a Buffer
  'invoice.pdf',                                      // filename
-  'application/pdf',                                  // MIME type
-  '58a0a314-d7ea-4865-9850-7fb84e72f30b',            // field universalIdentifier
+  '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` | Необработанное содержимое файла                                          |
@@ -953,7 +680,8 @@ console.log(uploadedFile);

 Основные моменты:

-* Uses the field's `universalIdentifier` (not its workspace-specific ID), so your upload code works across any workspace where your app is installed.
+* Метод `uploadFile` доступен в `MetadataApiClient`, потому что мутация загрузки обрабатывается эндпоинтом `/metadata`.
+* Он использует `universalIdentifier` поля (а не его идентификатор, специфичный для рабочего пространства), поэтому ваш код загрузки будет работать в любом рабочем пространстве, где установлено ваше приложение — в соответствии с тем, как приложения ссылаются на поля повсюду.
 * Возвращаемый `url` — это подписанный URL, который можно использовать для доступа к загруженному файлу.

 ### Пример Hello World
@@ -49,7 +49,7 @@ npx create-twenty-app@latest my-app --minimal

 ```bash filename="Terminal"
 # Add a new entity to your application (guided)
-yarn twenty add
+yarn twenty entity:add

 # Watch your application's function logs
 yarn twenty function:logs
@@ -123,7 +123,7 @@ my-twenty-app/
 В общих чертах:

 * **package.json**: Объявляет имя приложения, версию, движки (Node 24+, Yarn 4) и добавляет `twenty-sdk`, а также скрипт `twenty`, который делегирует выполнение локальному CLI `twenty`. Выполните `yarn twenty help`, чтобы вывести список всех доступных команд.
-* **.gitignore**: Ignores common artifacts such as `node_modules`, `.yarn`, `.twenty/`, `dist/`, `build/`, coverage folders, log files, and `.env*` files.
+* **.gitignore**: Игнорирует распространённые артефакты, такие как `node_modules`, `.yarn`, `generated/` (типизированный клиент), `dist/`, `build/`, каталоги coverage, файлы журналов и файлы `.env*`.
 * **yarn.lock**, **.yarnrc.yml**, **.yarn/**: Фиксируют и настраивают используемый в проекте инструментарий Yarn 4.
 * **.nvmrc**: Фиксирует версию Node.js, ожидаемую проектом.
 * **.oxlintrc.json** и **tsconfig.json**: Обеспечивают линтинг и конфигурацию TypeScript для исходников вашего приложения на TypeScript.
@@ -167,8 +167,8 @@ export default defineObject({

 Позднее команды добавят больше файлов и папок:

-* `yarn twenty dev` will auto-generate the typed `CoreApiClient` (for workspace data via `/graphql`) into `node_modules/twenty-client-sdk/`. The `MetadataApiClient` (for workspace configuration and file uploads via `/metadata`) ships pre-built and is available immediately. Import them from `twenty-client-sdk/core` and `twenty-client-sdk/metadata` respectively.
-* `yarn twenty add` will add entity definition files under `src/` for your custom objects, functions, front components, roles, skills, and more.
+* `yarn twenty dev` автоматически сгенерирует два типизированных клиента API в `node_modules/twenty-sdk/generated`: `CoreApiClient` (для данных рабочего пространства через `/graphql`) и `MetadataApiClient` (для конфигурации рабочего пространства и загрузки файлов через `/metadata`).
+* `yarn twenty entity:add` добавит файлы определений сущностей в `src/` для ваших пользовательских объектов, функций, фронтенд-компонентов, ролей, навыков и многого другого.

 ## Аутентификация

@@ -12,25 +12,7 @@ description: Распространяйте своё приложение Twenty
 После того как ваше приложение [собрано и протестировано локально](/l/ru/developers/extend/apps/building), у вас есть два пути для его распространения:

 * **Опубликовать в npm** — разместите ваше приложение в маркетплейсе Twenty, чтобы любое рабочее пространство могло его найти и установить.
-* **Разверните tar-архив** — загрузите своё приложение напрямую на конкретный сервер Twenty для внутреннего или частного использования.
-
-Оба пути начинаются с одного и того же шага **build**.
-
-## Сборка вашего приложения
-
-Команда `build` компилирует ваши исходники TypeScript, транспилирует функции логики и фронтенд-компоненты и генерирует `manifest.json`, который описывает содержимое вашего приложения:
-
-```bash filename="Terminal"
-yarn twenty build
-```
-
-Выходные данные записываются в `.twenty/output/`. This directory contains everything needed for distribution: compiled code, assets, the manifest, and a copy of your `package.json`.
-
-To also create a `.tgz` tarball (used by the deploy command internally, or for manual distribution):
-
-```bash filename="Terminal"
-yarn twenty build --tarball
-```
+* **Отправить tarball** — разверните приложение на конкретном сервере Twenty для внутреннего использования, не делая его общедоступным.

 ## Публикация в npm

@@ -39,72 +21,29 @@ yarn twenty build --tarball
 ### Требования

 * Учётная запись [npm](https://www.npmjs.com)
-* The `twenty-app` keyword **must** be listed in your `package.json` `keywords` array
-
-### Adding the required keyword
-
-The Twenty marketplace discovers apps by searching the npm registry for packages with the `twenty-app` keyword. Add it to your `package.json`:
-
-```json filename="package.json"
-{
-  "name": "twenty-app-postcard-sender",
-  "version": "1.0.0",
-  "keywords": ["twenty-app"],
-  ...
-}
-```
-
-<Note>
-The marketplace searches for `keywords:twenty-app` on the npm registry. Without this keyword, your package won't appear in the marketplace even if it has the `twenty-app-` name prefix.
-</Note>
+* Название вашего пакета **должно** использовать префикс `twenty-app-` (например, `twenty-app-postcard-sender`)

 ### Шаги

-1. **Build your app:**
+1. **Соберите приложение** — CLI компилирует исходные файлы TypeScript и генерирует манифест приложения:

 ```bash filename="Terminal"
 yarn twenty build
 ```

-2. **Publish to npm:**
+2. **Опубликуйте в npm** — отправьте собранный пакет в реестр npm:

 ```bash filename="Terminal"
-yarn twenty publish
+npx twenty publish
 ```

-This runs `npm publish` from the `.twenty/output/` directory.
+### Автоматическое обнаружение

-To publish under a specific dist-tag (e.g., `beta` or `next`):
-
-```bash filename="Terminal"
-yarn twenty publish --tag beta
-```
-
-### How marketplace discovery works
-
-The Twenty server syncs its marketplace catalog from the npm registry **every hour**:
-
-1. It searches for all npm packages with the `keywords:twenty-app` keyword
-2. For each package, it fetches the `manifest.json` from the npm CDN
-3. The app's metadata (name, description, author, logo, screenshots, category) is extracted from the manifest and displayed in the marketplace
-
-After publishing, your app can take up to one hour to appear in the marketplace. To trigger the sync immediately instead of waiting for the next hourly run:
-
-```bash filename="Terminal"
-yarn twenty catalog-sync
-```
-
-To target a specific remote:
-
-```bash filename="Terminal"
-yarn twenty catalog-sync -r production
-```
-
-The metadata shown in the marketplace comes from your `defineApplication()` call in your app source code — fields like `displayName`, `description`, `author`, `category`, `logoUrl`, `screenshots`, `aboutDescription`, `websiteUrl`, and `termsUrl`.
+Пакеты с префиксом `twenty-app-` автоматически обнаруживаются каталогом маркетплейса Twenty. После публикации ваше приложение появится в маркетплейсе в течение нескольких минут — ручная регистрация или одобрение не требуются.

 ### Публикация через CI

-Сгенерированный шаблоном проект включает рабочий процесс GitHub Actions, который выполняет публикацию при каждом релизе:
+Сгенерированный шаблоном проект включает workflow GitHub Actions, который выполняет публикацию при каждом релизе. Он запускает `app:build`, затем `npm publish --provenance` из результатов сборки:

 ```yaml filename=".github/workflows/publish.yml"
 name: Publish
@@ -133,117 +72,48 @@ jobs:
          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
 ```

-For other CI systems (GitLab CI, CircleCI, etc.), the same three commands apply: `yarn install`, `yarn twenty build`, then `npm publish` from `.twenty/output`.
+Для других CI-систем (GitLab CI, CircleCI и др.) применимы те же три команды: `yarn install`, `npx twenty build`, затем `npm publish` из `.twenty/output`.

 <Tip>
 **npm provenance** — опционально, но рекомендуется. Публикация с флагом `--provenance` добавляет к вашему пакету в npm значок доверия, позволяя пользователям проверить, что пакет был собран из конкретного коммита в общедоступном конвейере CI. См. инструкции по настройке в [документации по npm provenance](https://docs.npmjs.com/generating-provenance-statements).
 </Tip>

-## Deploying to a server (tarball)
+## Внутреннее распространение

-For apps you don't want publicly available — proprietary tools, enterprise-only integrations, or experimental builds — you can deploy a tarball directly to a Twenty server.
+Для приложений, которые вы не хотите делать общедоступными — собственные инструменты, интеграции только для предприятия или экспериментальные сборки — вы можете отправить tarball напрямую на сервер Twenty.

-### Требования
+### Отправка tarball

-Before deploying, you need a configured remote pointing to the target server. Remotes store the server URL and authentication credentials locally in `~/.twenty/config.json`.
-
-Add a remote:
+Соберите приложение и разверните его на конкретном сервере одним шагом:

 ```bash filename="Terminal"
-yarn twenty remote add --url https://your-twenty-server.com --as production
+npx twenty publish --server <server-url>
 ```

-For a local development server:
-
-```bash filename="Terminal"
-yarn twenty remote add --local --as local
-```
-
-You can also authenticate with an API key for non-interactive environments:
-
-```bash filename="Terminal"
-yarn twenty remote add --url https://your-twenty-server.com --token <api-key> --as production
-```
-
-Manage your remotes:
-
-```bash filename="Terminal"
-yarn twenty remote list       # List all configured remotes
-yarn twenty remote switch prod # Set the default remote
-yarn twenty remote status     # Show active remote and auth status
-yarn twenty remote remove old # Remove a remote
-```
-
-### Deploying
-
-Build and upload your app to the server in one step:
-
-```bash filename="Terminal"
-yarn twenty deploy
-```
-
-This builds the app with `--tarball`, then uploads the tarball to the default remote via a GraphQL multipart upload.
-
-To deploy to a specific remote:
-
-```bash filename="Terminal"
-yarn twenty deploy -r production
-```
-
-### Sharing a deployed app
-
-Tarball apps are not listed in the public marketplace, so other workspaces on the same server won't discover them by browsing. To share a deployed app:
-
-1. Go to **Settings > Applications > Registrations** and open your app
-2. In the **Distribution** tab, click **Copy share link**
-3. Share this link with users on other workspaces — it takes them directly to the app's install page
-
-The share link uses the server's base URL (without any workspace subdomain) so it works for any workspace on the server.
+Любое рабочее пространство на этом сервере сможет установить и обновить приложение на странице настроек **Applications**.

 ### Управление версиями

 Чтобы выпустить обновление:

 1. Обновите значение поля `version` в файле `package.json`
-2. Run `yarn twenty deploy` (or `yarn twenty deploy -r production`)
-3. Workspaces that have the app installed will see the upgrade available in their settings
+2. Отправьте новый tarball командой `npx twenty publish --server <server-url>`
+3. Рабочие пространства на этом сервере увидят доступное обновление в своих настройках

-## Installing apps
+<Note>
+Внутренние приложения ограничены сервером, на который они отправлены. Они не появятся в публичном маркетплейсе и не могут быть установлены рабочими пространствами на других серверах.
+</Note>

-Once an app is published (npm) or deployed (tarball), workspaces install it through the UI:
-
-```bash filename="Terminal"
-yarn twenty install
-```
-
-Or from the **Settings > Applications** page in the Twenty UI, where both marketplace and tarball-deployed apps can be browsed and installed.
-
-## App distribution categories
+## Категории приложений

 Twenty группирует приложения в три категории в зависимости от способа их распространения:

-| Категория              | Как это работает                                                                                                                        | Отображается в маркетплейсе? |
-| ---------------------- | --------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------- |
-| **Разработка**         | Локальные приложения в режиме разработки, запущенные через `yarn twenty dev`. Используются для сборки и тестирования.                   | Нет                          |
-| **Published (npm)**    | Apps published to npm with the `twenty-app` keyword. Отображаются в маркетплейсе, доступные для установки любому рабочему пространству. | Да                           |
-| **Internal (tarball)** | Приложения, развернутые через tarball на конкретном сервере. Available only to workspaces on that server via a share link.              | Нет                          |
+| Категория        | Как это работает                                                                                                                               | Отображается в маркетплейсе? |
+| ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------- |
+| **Разработка**   | Локальные приложения в режиме разработки, запущенные через `yarn twenty dev`. Используются для сборки и тестирования.                          | Нет                          |
+| **Опубликовано** | Приложения, опубликованные в npm с префиксом `twenty-app-`. Отображаются в маркетплейсе, доступные для установки любому рабочему пространству. | Да                           |
+| **Внутренний**   | Приложения, развернутые через tarball на конкретном сервере. Доступны только рабочим пространствам на этом сервере.                            | Нет                          |

 <Tip>
 Начните в режиме **Разработка** во время создания приложения. Когда будет готово, выберите **Опубликовано** (npm) для широкого распространения или **Внутренний** (tarball) для приватного развертывания.
 </Tip>
-
-## CLI reference
-
-| Команда                     | Описание                                       | Key flags                                           |
-| --------------------------- | ---------------------------------------------- | --------------------------------------------------- |
-| `yarn twenty build`         | Compile app and generate manifest              | `--tarball` — also create a `.tgz` package          |
-| `yarn twenty publish`       | Build and publish to npm                       | `--tag <tag>` — npm dist-tag (e.g., `beta`, `next`) |
-| `yarn twenty deploy`        | Build and upload tarball to a server           | `-r, --remote <name>` — target remote               |
-| `yarn twenty catalog-sync`  | Trigger marketplace catalog sync on the server | `-r, --remote <name>` — target remote               |
-| `yarn twenty install`       | Install a deployed app on a workspace          | `-r, --remote <name>` — target remote               |
-| `yarn twenty dev`           | Watch and sync local changes                   | Uses default remote                                 |
-| `yarn twenty remote add`    | Add a server connection                        | `--url`, `--token`, `--as`, `--local`, `--port`     |
-| `yarn twenty remote list`   | List configured remotes                        | —                                                   |
-| `yarn twenty remote switch` | Set default remote                             | —                                                   |
-| `yarn twenty remote status` | Show connection status                         | —                                                   |
-| `yarn twenty remote remove` | Remove a remote                                | —                                                   |
@@ -15,21 +15,19 @@ twenty-sdk, uygulamanız içinde kullandığınız türlendirilmiş yapı taşla

 SDK, uygulama varlıklarınızı tanımlamak için yardımcı fonksiyonlar sağlar. [Varlık algılama](/l/tr/developers/extend/apps/getting-started#entity-detection) bölümünde açıklandığı gibi, varlıklarınızın algılanması için `export default define<Entity>({...})` kullanmalısınız:

-| Fonksiyon                        | Amaç                                                                                |
-| -------------------------------- | ----------------------------------------------------------------------------------- |
-| `defineApplication`              | Uygulama meta verilerini yapılandırın (zorunlu, uygulama başına bir adet)           |
-| `defineObject`                   | Alanlara sahip özel nesneler tanımlayın                                             |
-| `defineField`                    | Extend existing objects with additional fields or define standalone relation fields |
-| `defineLogicFunction`            | İşleyicilerle mantık fonksiyonları tanımlayın                                       |
-| `definePreInstallLogicFunction`  | Bir kurulum öncesi mantık işlevi tanımlayın (uygulama başına bir adet)              |
-| `definePostInstallLogicFunction` | Bir kurulum sonrası mantık işlevi tanımlayın (uygulama başına bir adet)             |
-| `defineFrontComponent`           | Özel kullanıcı arayüzü için ön uç bileşenlerini tanımlayın                          |
-| `defineRole`                     | Rol izinlerini ve nesne erişimini yapılandırın                                      |
-| `defineView`                     | Nesneler için kaydedilmiş görünümler tanımlayın                                     |
-| `defineNavigationMenuItem`       | Kenar çubuğu gezinme bağlantılarını tanımlayın                                      |
-| `defineSkill`                    | Yapay zekâ ajanı yeteneklerini tanımlayın                                           |
-| `defineAgent`                    | Define AI agents                                                                    |
-| `definePageLayout`               | Define custom page layouts                                                          |
+| Fonksiyon                        | Amaç                                                                      |
+| -------------------------------- | ------------------------------------------------------------------------- |
+| `defineApplication`              | Uygulama meta verilerini yapılandırın (zorunlu, uygulama başına bir adet) |
+| `defineObject`                   | Alanlara sahip özel nesneler tanımlayın                                   |
+| `defineLogicFunction`            | İşleyicilerle mantık fonksiyonları tanımlayın                             |
+| `definePreInstallLogicFunction`  | Bir kurulum öncesi mantık işlevi tanımlayın (uygulama başına bir adet)    |
+| `definePostInstallLogicFunction` | Bir kurulum sonrası mantık işlevi tanımlayın (uygulama başına bir adet)   |
+| `defineFrontComponent`           | Özel kullanıcı arayüzü için ön uç bileşenlerini tanımlayın                |
+| `defineRole`                     | Rol izinlerini ve nesne erişimini yapılandırın                            |
+| `defineField`                    | Mevcut nesneleri ek alanlarla genişletin                                  |
+| `defineView`                     | Nesneler için kaydedilmiş görünümler tanımlayın                           |
+| `defineNavigationMenuItem`       | Kenar çubuğu gezinme bağlantılarını tanımlayın                            |
+| `defineSkill`                    | Yapay zekâ ajanı yeteneklerini tanımlayın                                 |

 Bu fonksiyonlar, derleme zamanında yapılandırmanızı doğrular ve IDE otomatik tamamlama ile tür güvenliği sağlar.

@@ -38,7 +36,7 @@ Bu fonksiyonlar, derleme zamanında yapılandırmanızı doğrular ve IDE otomat
 Özel nesneler, çalışma alanınızdaki kayıtlar için hem şemayı hem de davranışı tanımlar. Yerleşik doğrulamayla nesneler tanımlamak için `defineObject()` kullanın:

 ```typescript
-// src/objects/postCard.object.ts
+// src/app/postCard.object.ts
 import { defineObject, FieldType } from 'twenty-sdk';

 enum PostCardStatus {
@@ -112,7 +110,7 @@ export default defineObject({
 * `universalIdentifier` dağıtımlar arasında benzersiz ve kararlı olmalıdır.
 * Her alan bir `name`, `type`, `label` ve kendi kararlı `universalIdentifier` değerini gerektirir.
 * `fields` dizisi isteğe bağlıdır — özel alanlar olmadan da nesneler tanımlayabilirsiniz.
-* You can scaffold new objects using `yarn twenty add`, which guides you through naming, fields, and relationships.
+* `yarn twenty entity:add` kullanarak, adlandırma, alanlar ve ilişkiler konusunda sizi yönlendirerek yeni nesneler oluşturabilirsiniz.

 <Note>
 **Temel alanlar otomatik olarak oluşturulur.** Özel bir nesne tanımladığınızda Twenty, standart alanları otomatik olarak ekler
@@ -122,197 +120,6 @@ Bunları `fields` dizinizde tanımlamanız gerekmez — yalnızca özel alanlar
 ancak bu önerilmez.
 </Note>

-### Mevcut nesneler üzerinde alanları tanımlama
-
-Use `defineField()` to add fields to objects you don't own — such as standard Twenty objects (Person, Company, etc.) or objects from other apps. Unlike inline fields in `defineObject()`, standalone fields require an `objectUniversalIdentifier` to specify which object they extend:
-
-```typescript
-// src/fields/company-loyalty-tier.field.ts
-import { defineField, FieldType } from 'twenty-sdk';
-
-export default defineField({
-  universalIdentifier: 'f2a1b3c4-d5e6-7890-abcd-ef1234567890',
-  objectUniversalIdentifier: '701aecb9-eb1c-4d84-9d94-b954b231b64b', // Company object
-  name: 'loyaltyTier',
-  type: FieldType.SELECT,
-  label: 'Loyalty Tier',
-  icon: 'IconStar',
-  options: [
-    { value: 'BRONZE', label: 'Bronze', position: 0, color: 'orange' },
-    { value: 'SILVER', label: 'Silver', position: 1, color: 'gray' },
-    { value: 'GOLD', label: 'Gold', position: 2, color: 'yellow' },
-  ],
-});
-```
-
-Önemli noktalar:
-
-* `objectUniversalIdentifier` identifies the target object. For standard objects, use `STANDARD_OBJECT_UNIVERSAL_IDENTIFIERS` exported from `twenty-sdk`.
-* When defining fields inline in `defineObject()`, you do **not** need `objectUniversalIdentifier` — it's inherited from the parent object.
-* `defineField()` is the only way to add fields to objects you didn't create with `defineObject()`.
-
-### İlişkiler
-
-Relations connect objects together. In Twenty, relations are always **bidirectional** — you define both sides, and each side references the other.
-
-There are two relation types:
-
-| İlişki türü   | Açıklama                                                      | Has foreign key?       |
-| ------------- | ------------------------------------------------------------- | ---------------------- |
-| `MANY_TO_ONE` | Many records of this object point to one record of the target | Yes (`joinColumnName`) |
-| `ONE_TO_MANY` | One record of this object has many records of the target      | No (inverse side)      |
-
-#### How relations work
-
-Every relation requires **two fields** that reference each other:
-
-1. The **MANY_TO_ONE** side — lives on the object that holds the foreign key
-2. The **ONE_TO_MANY** side — lives on the object that owns the collection
-
-Both fields use `FieldType.RELATION` and cross-reference each other via `relationTargetFieldMetadataUniversalIdentifier`.
-
-#### Example: Post Card has many Recipients
-
-Suppose a `PostCard` can be sent to many `PostCardRecipient` records. Each recipient belongs to exactly one post card.
-
-**Step 1: Define the ONE_TO_MANY side on PostCard** (the "one" side):
-
-```typescript
-// src/fields/post-card-recipients-on-post-card.field.ts
-import { defineField, FieldType, RelationType } from 'twenty-sdk';
-import { POST_CARD_UNIVERSAL_IDENTIFIER } from '../objects/post-card.object';
-import { POST_CARD_RECIPIENT_UNIVERSAL_IDENTIFIER } from '../objects/post-card-recipient.object';
-
-// Export so the other side can reference it
-export const POST_CARD_RECIPIENTS_FIELD_ID = 'a1111111-1111-1111-1111-111111111111';
-// Import from the other side
-import { POST_CARD_FIELD_ID } from './post-card-on-post-card-recipient.field';
-
-export default defineField({
-  universalIdentifier: POST_CARD_RECIPIENTS_FIELD_ID,
-  objectUniversalIdentifier: POST_CARD_UNIVERSAL_IDENTIFIER,
-  type: FieldType.RELATION,
-  name: 'postCardRecipients',
-  label: 'Post Card Recipients',
-  icon: 'IconUsers',
-  relationTargetObjectMetadataUniversalIdentifier: POST_CARD_RECIPIENT_UNIVERSAL_IDENTIFIER,
-  relationTargetFieldMetadataUniversalIdentifier: POST_CARD_FIELD_ID,
-  universalSettings: {
-    relationType: RelationType.ONE_TO_MANY,
-  },
-});
-```
-
-**Step 2: Define the MANY_TO_ONE side on PostCardRecipient** (the "many" side — holds the foreign key):
-
-```typescript
-// src/fields/post-card-on-post-card-recipient.field.ts
-import { defineField, FieldType, RelationType, OnDeleteAction } from 'twenty-sdk';
-import { POST_CARD_UNIVERSAL_IDENTIFIER } from '../objects/post-card.object';
-import { POST_CARD_RECIPIENT_UNIVERSAL_IDENTIFIER } from '../objects/post-card-recipient.object';
-
-// Export so the other side can reference it
-export const POST_CARD_FIELD_ID = 'b2222222-2222-2222-2222-222222222222';
-// Import from the other side
-import { POST_CARD_RECIPIENTS_FIELD_ID } from './post-card-recipients-on-post-card.field';
-
-export default defineField({
-  universalIdentifier: POST_CARD_FIELD_ID,
-  objectUniversalIdentifier: POST_CARD_RECIPIENT_UNIVERSAL_IDENTIFIER,
-  type: FieldType.RELATION,
-  name: 'postCard',
-  label: 'Post Card',
-  icon: 'IconMail',
-  relationTargetObjectMetadataUniversalIdentifier: POST_CARD_UNIVERSAL_IDENTIFIER,
-  relationTargetFieldMetadataUniversalIdentifier: POST_CARD_RECIPIENTS_FIELD_ID,
-  universalSettings: {
-    relationType: RelationType.MANY_TO_ONE,
-    onDelete: OnDeleteAction.CASCADE,
-    joinColumnName: 'postCardId',
-  },
-});
-```
-
-<Note>
-**Circular imports:** Both relation fields reference each other's `universalIdentifier`. To avoid circular import issues, export your field IDs as named constants from each file, and import them in the other file. The build system resolves these at compile time.
-</Note>
-
-#### Relating to standard objects
-
-To create a relation with a built-in Twenty object (Person, Company, etc.), use `STANDARD_OBJECT_UNIVERSAL_IDENTIFIERS`:
-
-```typescript
-// src/fields/person-on-self-hosting-user.field.ts
-import {
-  defineField,
-  FieldType,
-  RelationType,
-  OnDeleteAction,
-  STANDARD_OBJECT_UNIVERSAL_IDENTIFIERS,
-} from 'twenty-sdk';
-import { SELF_HOSTING_USER_UNIVERSAL_IDENTIFIER } from '../objects/self-hosting-user.object';
-
-export const PERSON_FIELD_ID = 'c3333333-3333-3333-3333-333333333333';
-export const SELF_HOSTING_USER_REVERSE_FIELD_ID = 'd4444444-4444-4444-4444-444444444444';
-
-export default defineField({
-  universalIdentifier: PERSON_FIELD_ID,
-  objectUniversalIdentifier: SELF_HOSTING_USER_UNIVERSAL_IDENTIFIER,
-  type: FieldType.RELATION,
-  name: 'person',
-  label: 'Person',
-  description: 'Person matching with the self hosting user',
-  isNullable: true,
-  relationTargetObjectMetadataUniversalIdentifier:
-    STANDARD_OBJECT_UNIVERSAL_IDENTIFIERS.person.universalIdentifier,
-  relationTargetFieldMetadataUniversalIdentifier: SELF_HOSTING_USER_REVERSE_FIELD_ID,
-  universalSettings: {
-    relationType: RelationType.MANY_TO_ONE,
-    onDelete: OnDeleteAction.SET_NULL,
-    joinColumnName: 'personId',
-  },
-});
-```
-
-#### Relation field properties
-
-| Özellik                                           | Zorunlu          | Açıklama                                                                                              |
-| ------------------------------------------------- | ---------------- | ----------------------------------------------------------------------------------------------------- |
-| `type`                                            | Evet             | Must be `FieldType.RELATION`                                                                          |
-| `relationTargetObjectMetadataUniversalIdentifier` | Evet             | The `universalIdentifier` of the target object                                                        |
-| `relationTargetFieldMetadataUniversalIdentifier`  | Evet             | The `universalIdentifier` of the matching field on the target object                                  |
-| `universalSettings.relationType`                  | Evet             | `RelationType.MANY_TO_ONE` or `RelationType.ONE_TO_MANY`                                              |
-| `universalSettings.onDelete`                      | MANY_TO_ONE only | What happens when the referenced record is deleted: `CASCADE`, `SET_NULL`, `RESTRICT`, or `NO_ACTION` |
-| `universalSettings.joinColumnName`                | MANY_TO_ONE only | Database column name for the foreign key (e.g., `postCardId`)                                         |
-
-#### Inline relation fields in defineObject
-
-You can also define relation fields directly inside `defineObject()`. In that case, omit `objectUniversalIdentifier` — it's inherited from the parent object:
-
-```typescript
-export default defineObject({
-  universalIdentifier: '...',
-  nameSingular: 'postCardRecipient',
-  // ...
-  fields: [
-    {
-      universalIdentifier: POST_CARD_FIELD_ID,
-      type: FieldType.RELATION,
-      name: 'postCard',
-      label: 'Post Card',
-      relationTargetObjectMetadataUniversalIdentifier: POST_CARD_UNIVERSAL_IDENTIFIER,
-      relationTargetFieldMetadataUniversalIdentifier: POST_CARD_RECIPIENTS_FIELD_ID,
-      universalSettings: {
-        relationType: RelationType.MANY_TO_ONE,
-        onDelete: OnDeleteAction.CASCADE,
-        joinColumnName: 'postCardId',
-      },
-    },
-    // ... other fields
-  ],
-});
-```
-
 ### Uygulama yapılandırması (application-config.ts)

 Her uygulamanın aşağıdakileri açıklayan tek bir `application-config.ts` dosyası vardır:
@@ -354,29 +161,13 @@ Notlar:
 * `defaultRoleUniversalIdentifier`, rol dosyasıyla eşleşmelidir (aşağıya bakın).
 * Kurulum öncesi ve kurulum sonrası işlevler, manifest oluşturma sırasında otomatik olarak algılanır. Bkz. [Kurulum öncesi işlevler](#pre-install-functions) ve [Kurulum sonrası işlevler](#post-install-functions).

-#### Marketplace metadata
-
-If you plan to [publish your app](/l/tr/developers/extend/apps/publishing), these optional fields control how your app appears in the marketplace:
-
-| Alan               | Açıklama                                            |
-| ------------------ | --------------------------------------------------- |
-| `author`           | Author or company name                              |
-| `category`         | App category for marketplace filtering              |
-| `logoUrl`          | Path to your app logo (relative to `./assets/`)     |
-| `screenshots`      | Array of screenshot paths (relative to `./assets/`) |
-| `aboutDescription` | Longer markdown description for the "About" tab     |
-| `websiteUrl`       | Link to your website                                |
-| `termsUrl`         | Link to terms of service                            |
-| `emailSupport`     | Support email address                               |
-| `issueReportUrl`   | Link to issue tracker                               |
-
 #### Roller ve izinler

 Uygulamalar, çalışma alanınızdaki nesneler ve eylemler üzerindeki izinleri kapsülleyen roller tanımlayabilir. `application-config.ts` içindeki `defaultRoleUniversalIdentifier` alanı, uygulamanızın mantık fonksiyonlarının kullandığı varsayılan rolü belirtir.

 * `TWENTY_API_KEY` olarak enjekte edilen çalışma zamanı API anahtarı bu varsayılan fonksiyon rolünden türetilir.
 * Türlendirilmiş istemci, o role tanınan izinlerle sınırlandırılır.
-* Follow least-privilege: create a dedicated role with only the permissions your functions need, then reference its universal identifier.
+* En az ayrıcalık ilkesini izleyin: Yalnızca fonksiyonlarınızın ihtiyaç duyduğu izinlere sahip özel bir rol oluşturun ve ardından evrensel tanımlayıcısına referans verin.

 ##### Varsayılan fonksiyon rolü (*.role.ts)

@@ -429,7 +220,7 @@ Bu rolün `universalIdentifier` değeri daha sonra `application-config.ts` için

 Notlar:

-* Start from the scaffolded role, then progressively restrict it following least-privilege.
+* Oluşturulan rol ile başlayın ve en az ayrıcalık ilkesini izleyerek aşamalı olarak kısıtlayın.
 * `objectPermissions` ve `fieldPermissions` değerlerini, fonksiyonlarınızın ihtiyaç duyduğu nesneler/alanlarla değiştirin.
 * `permissionFlags`, platform düzeyindeki yeteneklere erişimi kontrol eder. Minimumda tutun; yalnızca ihtiyacınız olanları ekleyin.
 * Çalışan bir örneği Hello World uygulamasında görün: [`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).
@@ -439,7 +230,7 @@ Notlar:
 Her fonksiyon dosyası, bir işleyici ve isteğe bağlı tetikleyiciler içeren bir yapılandırmayı dışa aktarmak için `defineLogicFunction()` kullanır.

 ```typescript
-// src/logic-functions/createPostCard.logic-function.ts
+// 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';
@@ -533,7 +324,7 @@ export default definePreInstallLogicFunction({
 Ayrıca kurulum öncesi işlevi istediğiniz zaman CLI kullanarak manuel olarak çalıştırabilirsiniz:

 ```bash filename="Terminal"
-yarn twenty exec --preInstall
+yarn twenty function:execute --preInstall
 ```

 Önemli noktalar:
@@ -543,7 +334,7 @@ yarn twenty exec --preInstall
 * Uygulama başına yalnızca bir kurulum öncesi işlevine izin verilir. Birden fazla tespit edilirse manifest oluşturma hataya düşer.
 * İşlevin `universalIdentifier` değeri, oluşturma sırasında uygulama manifestinde otomatik olarak `preInstallLogicFunctionUniversalIdentifier` olarak ayarlanır — `defineApplication()` içinde buna atıfta bulunmanıza gerek yoktur.
 * Varsayılan zaman aşımı, daha uzun hazırlık görevlerine izin vermek için 300 saniye (5 dakika) olarak ayarlanmıştır.
-* Pre-install functions do not need triggers — they are invoked by the platform before installation or manually via `exec --preInstall`.
+* Kurulum öncesi işlevlerin tetikleyicilere ihtiyacı yoktur — kurulumdan önce platform tarafından veya `function:execute --preInstall` aracılığıyla manuel olarak çağrılırlar.

 ### Kurulum sonrası işlevler

@@ -571,7 +362,7 @@ export default definePostInstallLogicFunction({
 Ayrıca kurulum sonrası işlevi istediğiniz zaman CLI kullanarak manuel olarak çalıştırabilirsiniz:

 ```bash filename="Terminal"
-yarn twenty exec --postInstall
+yarn twenty function:execute --postInstall
 ```

 Önemli noktalar:
@@ -581,7 +372,7 @@ yarn twenty exec --postInstall
 * Uygulama başına yalnızca bir kurulum sonrası işlevine izin verilir. Birden fazla tespit edilirse manifest oluşturma hataya düşer.
 * İşlevin `universalIdentifier` değeri, oluşturma sırasında uygulama manifestinde otomatik olarak `postInstallLogicFunctionUniversalIdentifier` olarak ayarlanır — `defineApplication()` içinde buna atıfta bulunmanıza gerek yoktur.
 * Varsayılan zaman aşımı, veri tohumlama gibi daha uzun kurulum görevlerine izin vermek için 300 saniye (5 dakika) olarak ayarlanmıştır.
-* Post-install functions do not need triggers — they are invoked by the platform during installation or manually via `exec --postInstall`.
+* Kurulum sonrası işlevlerin tetikleyicilere ihtiyacı yoktur — kurulum sırasında platform tarafından veya `function:execute --postInstall` aracılığıyla manuel olarak çağrılırlar.

 ### Rota tetikleyicisi yükü

@@ -625,15 +416,15 @@ const handler = async (event: RoutePayload) => {

 `RoutePayload` türünün yapısı şu şekildedir:

-| Özellik                      | Tür                                   | Açıklama                                                                                 |
-| ---------------------------- | ------------------------------------- | ---------------------------------------------------------------------------------------- |
-| `headers`                    | `Record<string, string \| undefined>` | HTTP başlıkları (`forwardedRequestHeaders` içinde listelenenlerle sınırlı)               |
-| `queryStringParameters`      | `Record<string, string \| undefined>` | Sorgu dizesi parametreleri (birden çok değer virgülle birleştirilir)                     |
-| `pathParameters`             | `Record<string, string \| undefined>` | Path parameters extracted from the route pattern (e.g., `/users/:id` -> `{ id: '123' }`) |
-| `body`                       | `object \| null`                      | Ayrıştırılmış istek gövdesi (JSON)                                                       |
-| `isBase64Encoded`            | `boolean`                             | Gövdenin base64 ile kodlanıp kodlanmadığı                                                |
-| `requestContext.http.method` | `string`                              | HTTP yöntemi (GET, POST, PUT, PATCH, DELETE)                                             |
-| `requestContext.http.path`   | `string`                              | Ham istek yolu                                                                           |
+| Özellik                      | Tür                                   | Açıklama                                                                           |
+| ---------------------------- | ------------------------------------- | ---------------------------------------------------------------------------------- |
+| `headers`                    | `Record<string, string \| undefined>` | HTTP başlıkları (`forwardedRequestHeaders` içinde listelenenlerle sınırlı)         |
+| `queryStringParameters`      | `Record<string, string \| undefined>` | Sorgu dizesi parametreleri (birden çok değer virgülle birleştirilir)               |
+| `pathParameters`             | `Record<string, string \| undefined>` | Rota deseninden çıkarılan yol parametreleri (örn., `/users/:id` → `{ id: '123' }`) |
+| `body`                       | `object \| null`                      | Ayrıştırılmış istek gövdesi (JSON)                                                 |
+| `isBase64Encoded`            | `boolean`                             | Gövdenin base64 ile kodlanıp kodlanmadığı                                          |
+| `requestContext.http.method` | `string`                              | HTTP yöntemi (GET, POST, PUT, PATCH, DELETE)                                       |
+| `requestContext.http.path`   | `string`                              | Ham istek yolu                                                                     |

 ### HTTP başlıklarını iletme

@@ -675,7 +466,7 @@ const handler = async (event: RoutePayload) => {

 Yeni fonksiyonları iki şekilde oluşturabilirsiniz:

-* **Scaffolded**: Run `yarn twenty add` and choose the option to add a new logic function. Bu, bir işleyici ve yapılandırma içeren bir başlangıç dosyası oluşturur.
+* **Şablondan**: `yarn twenty entity:add` çalıştırın ve yeni bir mantık fonksiyonu ekleme seçeneğini seçin. Bu, bir işleyici ve yapılandırma içeren bir başlangıç dosyası oluşturur.
 * **Manuel**: Yeni bir `*.logic-function.ts` dosyası oluşturun ve aynı deseni izleyerek `defineLogicFunction()` kullanın.

 ### Bir mantık işlevini araç olarak işaretleme
@@ -687,7 +478,7 @@ Bir mantık işlevini bir araç olarak işaretlemek için `isTool: true` olarak
 ```typescript
 // src/logic-functions/enrich-company.logic-function.ts
 import { defineLogicFunction } from 'twenty-sdk';
-import { CoreApiClient } from 'twenty-client-sdk/core';
+import { CoreApiClient } from 'twenty-sdk/generated';

 const handler = async (params: { companyName: string; domain?: string }) => {
  const client = new CoreApiClient();
@@ -776,7 +567,7 @@ export default defineFrontComponent({

 Yeni ön uç bileşenlerini iki şekilde oluşturabilirsiniz:

-* **Scaffolded**: Run `yarn twenty add` and choose the option to add a new front component.
+* **Şablondan**: `yarn twenty entity:add` çalıştırın ve yeni bir ön uç bileşeni ekleme seçeneğini seçin.
 * **Manuel**: Aynı deseni izleyerek yeni bir `.tsx` dosyası oluşturun ve `defineFrontComponent()` kullanın.

 ### Beceriler
@@ -811,122 +602,47 @@ export default defineSkill({

 Yeni yetenekleri iki şekilde oluşturabilirsiniz:

-* **Scaffolded**: Run `yarn twenty add` and choose the option to add a new skill.
+* **Şablondan**: `yarn twenty entity:add` komutunu çalıştırın ve yeni bir yetenek ekleme seçeneğini seçin.
 * **Manuel**: Yeni bir dosya oluşturun ve aynı deseni izleyerek `defineSkill()` kullanın.

-### Typed API clients (`twenty-client-sdk`)
+### Oluşturulan tiplendirilmiş istemciler

-The `twenty-client-sdk` package provides two typed GraphQL clients for interacting with the Twenty API from your logic functions and front components:
+Çalışma alanı şemanıza göre `yarn twenty dev` tarafından iki tiplendirilmiş istemci otomatik olarak oluşturulur ve `node_modules/twenty-sdk/generated` içine kaydedilir:

-| İstemci             | İçe Aktar                    | Endpoint                                       | Generated?             |
-| ------------------- | ---------------------------- | ---------------------------------------------- | ---------------------- |
-| `CoreApiClient`     | `twenty-client-sdk/core`     | `/graphql` — workspace data (records, objects) | Yes, at dev/build time |
-| `MetadataApiClient` | `twenty-client-sdk/metadata` | `/metadata` — workspace config, file uploads   | No, ships pre-built    |
-
-#### CoreApiClient
-
-`CoreApiClient` is the main client for querying and mutating workspace data. It is **generated from your workspace schema** during `yarn twenty dev` or `yarn twenty build`, so it's fully typed to match your objects and fields.
+* **`CoreApiClient`** — çalışma alanı verileri için `/graphql` uç noktasını sorgular
+* **`MetadataApiClient`** — çalışma alanı yapılandırması ve dosya yüklemeleri için `/metadata` uç noktasını sorgular.

 ```typescript
-import { CoreApiClient } from 'twenty-client-sdk/core';
+import { CoreApiClient, MetadataApiClient } from 'twenty-sdk/generated';

 const client = new CoreApiClient();
-
-// Query records
-const { companies } = await client.query({
-  companies: {
-    edges: {
-      node: {
-        id: true,
-        name: true,
-        domainName: true,
-      },
-    },
-  },
-});
-
-// Create a record
-const { createCompany } = await client.mutation({
-  createCompany: {
-    __args: {
-      data: {
-        name: 'Acme Corp',
-      },
-    },
-    id: true,
-    name: true,
-  },
-});
-```
-
-The client uses a selection-set syntax: pass `true` to include a field, use `__args` for arguments, and nest objects for relations. You get full autocompletion and type checking based on your workspace schema.
-
-<Note>
-**CoreApiClient is generated at dev/build time.** If you try to use it without running `yarn twenty dev` or `yarn twenty build` first, it throws an error. The generation happens automatically — the CLI introspects your workspace's GraphQL schema, generates a typed client using `@genql/cli`, writes the generated sources to `node_modules/twenty-client-sdk/dist/core/generated/`, and replaces the stubs in `node_modules/twenty-client-sdk/dist/core.mjs` and `node_modules/twenty-client-sdk/dist/core.cjs`.
-</Note>
-
-#### Using CoreSchema for type annotations
-
-`CoreSchema` provides TypeScript types matching your workspace objects, useful for typing component state or function parameters:
-
-```typescript
-import { CoreApiClient, CoreSchema } from 'twenty-client-sdk/core';
-import { useState } from 'react';
-
-const [company, setCompany] = useState<
-  Pick<CoreSchema.Company, 'id' | 'name'> | undefined
->(undefined);
-
-const client = new CoreApiClient();
-const result = await client.query({
-  company: {
-    __args: { filter: { position: { eq: 1 } } },
-    id: true,
-    name: true,
-  },
-});
-setCompany(result.company);
-```
-
-#### MetadataApiClient
-
-`MetadataApiClient` ships pre-built with the SDK (no generation required). It queries the `/metadata` endpoint for workspace configuration, applications, and file uploads:
-
-```typescript
-import { MetadataApiClient } from 'twenty-client-sdk/metadata';
+const { me } = await client.query({ me: { id: true, displayName: true } });

 const metadataClient = new MetadataApiClient();
-
-// Query workspace info
-const { currentWorkspace } = await metadataClient.query({
-  currentWorkspace: { id: true, displayName: true },
-});
-
-// List installed applications
-const { findManyApplications } = await metadataClient.query({
-  findManyApplications: {
-    id: true,
-    name: true,
-    version: true,
-  },
-});
+const { currentWorkspace } = await metadataClient.query({ currentWorkspace: { id: true } });
 ```

-#### Runtime credentials
+Her iki istemci de, nesneleriniz veya alanlarınız değiştiğinde, `yarn twenty dev` tarafından otomatik olarak yeniden oluşturulur.

-When your code runs on Twenty (logic functions or front components), the platform injects credentials as environment variables:
+#### Mantık fonksiyonlarında çalışma zamanı kimlik bilgileri

-* `TWENTY_API_URL` — Base URL of the Twenty API
-* `TWENTY_API_KEY` — Short-lived key scoped to your application's default function role
+Fonksiyonunuz Twenty üzerinde çalıştığında, platform kodunuz yürütülmeden önce kimlik bilgilerini ortam değişkenleri olarak enjekte eder:

-You do **not** need to pass these to the clients — they read from `process.env` automatically. The API key's permissions are determined by the role referenced in `defaultRoleUniversalIdentifier` in your `application-config.ts`.
+* `TWENTY_API_URL`: Uygulamanızın hedeflediği Twenty API'nin temel URL’si.
+* `TWENTY_API_KEY`: Uygulamanızın varsayılan fonksiyon rolü kapsamına sahip kısa ömürlü anahtar.
+
+Notlar:
+
+* Oluşturulan istemciye URL veya API anahtarı geçirmeniz gerekmez. Çalışma zamanında `TWENTY_API_URL` ve `TWENTY_API_KEY` değerlerini process.env üzerinden okur.
+* API anahtarının izinleri, `application-config.ts` içinde `defaultRoleUniversalIdentifier` aracılığıyla referans verilen role göre belirlenir. Bu, uygulamanızın mantık fonksiyonları tarafından kullanılan varsayılan roldür.
+* Uygulamalar, en az ayrıcalık ilkesini izlemek için roller tanımlayabilir. Yalnızca fonksiyonlarınızın ihtiyaç duyduğu izinleri verin ve ardından `defaultRoleUniversalIdentifier` değerini o rolün evrensel tanımlayıcısına yönlendirin.

 #### Dosya yükleme

-`MetadataApiClient` includes an `uploadFile` method for attaching files to file-type fields. It implements the [GraphQL multipart request specification](https://github.com/jaydenseric/graphql-multipart-request-spec):
+Oluşturulan `MetadataApiClient`, çalışma alanı nesnelerinizdeki dosya türündeki alanlara dosya eklemek için bir `uploadFile` yöntemi içerir. Standart GraphQL istemcileri çok parçalı dosya yüklemelerini yerel olarak desteklemediğinden, istemci arka planda [GraphQL çok parçalı istek belirtimi](https://github.com/jaydenseric/graphql-multipart-request-spec) uygulayan bu özel yöntemi sağlar.

 ```typescript
-import { MetadataApiClient } from 'twenty-client-sdk/metadata';
+import { MetadataApiClient } from 'twenty-sdk/generated';
 import * as fs from 'fs';

 const metadataClient = new MetadataApiClient();
@@ -936,14 +652,25 @@ const fileBuffer = fs.readFileSync('./invoice.pdf');
 const uploadedFile = await metadataClient.uploadFile(
  fileBuffer,                                         // file contents as a Buffer
  'invoice.pdf',                                      // filename
-  'application/pdf',                                  // MIME type
-  '58a0a314-d7ea-4865-9850-7fb84e72f30b',            // field universalIdentifier
+  '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://...' }
 ```

+Yöntem imzası:
+
+```typescript
+uploadFile(
+  fileBuffer: Buffer,
+  filename: string,
+  contentType: string,
+  fieldMetadataUniversalIdentifier: string,
+): Promise<{ id: string; path: string; size: number; createdAt: string; url: string }>
+```
+
 | Parametre                          | Tür      | Açıklama                                                                                   |
 | ---------------------------------- | -------- | ------------------------------------------------------------------------------------------ |
 | `fileBuffer`                       | `Buffer` | Dosyanın ham içeriği                                                                       |
@@ -953,7 +680,8 @@ console.log(uploadedFile);

 Önemli noktalar:

-* Uses the field's `universalIdentifier` (not its workspace-specific ID), so your upload code works across any workspace where your app is installed.
+* `uploadFile` yöntemi, yükleme mutasyonu `/metadata` uç noktası tarafından çözümlendiği için `MetadataApiClient` üzerinde mevcuttur.
+* Alan için `universalIdentifier` kullanılır (çalışma alanına özgü kimliği değil), böylece yükleme kodunuz uygulamanızın yüklü olduğu herhangi bir çalışma alanında çalışır — uygulamaların başka her yerde alanlara nasıl atıfta bulunduğuyla tutarlıdır.
 * Döndürülen `url`, yüklenen dosyaya erişmek için kullanabileceğiniz imzalı bir URL'dir.

 ### Hello World örneği
@@ -49,7 +49,7 @@ Buradan şunları yapabilirsiniz:

 ```bash filename="Terminal"
 # Add a new entity to your application (guided)
-yarn twenty add
+yarn twenty entity:add

 # Watch your application's function logs
 yarn twenty function:logs
@@ -123,7 +123,7 @@ my-twenty-app/
 Genel hatlarıyla:

 * **package.json**: Uygulama adını, sürümünü, motorları (Node 24+, Yarn 4) bildirir ve `twenty-sdk` ile yerel `twenty` CLI'sine yetki devreden bir `twenty` betiği ekler. Tüm mevcut komutları listelemek için `yarn twenty help` komutunu çalıştırın.
-* **.gitignore**: Ignores common artifacts such as `node_modules`, `.yarn`, `.twenty/`, `dist/`, `build/`, coverage folders, log files, and `.env*` files.
+* **.gitignore**: `node_modules`, `.yarn`, `generated/` (türlendirilmiş istemci), `dist/`, `build/`, kapsam klasörleri, günlük dosyaları ve `.env*` dosyaları gibi yaygın artifaktları yok sayar.
 * **yarn.lock**, **.yarnrc.yml**, **.yarn/**: Proje tarafından kullanılan Yarn 4 araç zincirini kilitler ve yapılandırır.
 * **.nvmrc**: Projenin beklediği Node.js sürümünü sabitler.
 * **.oxlintrc.json** ve **tsconfig.json**: Uygulamanızın TypeScript kaynakları için linting ve TypeScript yapılandırması sağlar.
@@ -167,8 +167,8 @@ export default defineObject({

 İlerideki komutlar daha fazla dosya ve klasör ekleyecektir:

-* `yarn twenty dev` will auto-generate the typed `CoreApiClient` (for workspace data via `/graphql`) into `node_modules/twenty-client-sdk/`. The `MetadataApiClient` (for workspace configuration and file uploads via `/metadata`) ships pre-built and is available immediately. Import them from `twenty-client-sdk/core` and `twenty-client-sdk/metadata` respectively.
-* `yarn twenty add` will add entity definition files under `src/` for your custom objects, functions, front components, roles, skills, and more.
+* `yarn twenty dev`, `node_modules/twenty-sdk/generated` içinde iki tiplendirilmiş API istemcisini otomatik olarak oluşturur: `CoreApiClient` (`/graphql` üzerinden çalışma alanı verileri için) ve `MetadataApiClient` (çalışma alanı yapılandırması ve `/metadata` üzerinden dosya yüklemeleri için).
+* `yarn twenty entity:add`, özel nesneleriniz, fonksiyonlarınız, ön bileşenleriniz, rolleriniz, yetenekleriniz ve daha fazlası için `src/` altında varlık tanım dosyaları ekler.

 ## Kimlik Doğrulama

@@ -12,25 +12,7 @@ Uygulamalar şu anda alfa testinde. Özellik işlevsel ancak hâlâ gelişmekte.
 Uygulamanız [yerelde derlenip test edildikten sonra](/l/tr/developers/extend/apps/building), dağıtım için iki yolunuz vardır:

 * **npm’ye yayımlama** — uygulamanızı Twenty pazaryerinde listeleyin; böylece herhangi bir çalışma alanı keşfedip yükleyebilir.
-* **Bir tar arşivi dağıtın** — uygulamanızı dahili veya özel kullanım için doğrudan belirli bir Twenty sunucusuna yükleyin.
-
-Her iki yol da aynı **build** adımından başlar.
-
-## Uygulamanızı derleme
-
-`build` komutu TypeScript kaynaklarınızı derler, mantık işlevlerini ve ön uç bileşenlerini transpile eder ve uygulamanızın içeriğini açıklayan bir `manifest.json` üretir:
-
-```bash filename="Terminal"
-yarn twenty build
-```
-
-Çıktı `.twenty/output/` dizinine yazılır. This directory contains everything needed for distribution: compiled code, assets, the manifest, and a copy of your `package.json`.
-
-To also create a `.tgz` tarball (used by the deploy command internally, or for manual distribution):
-
-```bash filename="Terminal"
-yarn twenty build --tarball
-```
+* **Bir tarball gönderin** — uygulamanızı herkese açık yapmadan, dahili kullanım için belirli bir Twenty sunucusuna dağıtın.

 ## npm’ye yayımlama

@@ -39,72 +21,29 @@ npm’ye yayımlamak, uygulamanızın Twenty pazaryerinde keşfedilebilir olmas
 ### Gereksinimler

 * Bir [npm](https://www.npmjs.com) hesabı
-* The `twenty-app` keyword **must** be listed in your `package.json` `keywords` array
-
-### Adding the required keyword
-
-The Twenty marketplace discovers apps by searching the npm registry for packages with the `twenty-app` keyword. Add it to your `package.json`:
-
-```json filename="package.json"
-{
-  "name": "twenty-app-postcard-sender",
-  "version": "1.0.0",
-  "keywords": ["twenty-app"],
-  ...
-}
-```
-
-<Note>
-The marketplace searches for `keywords:twenty-app` on the npm registry. Without this keyword, your package won't appear in the marketplace even if it has the `twenty-app-` name prefix.
-</Note>
+* Paket adınız **mutlaka** `twenty-app-` önekini kullanmalıdır (ör. `twenty-app-postcard-sender`)

 ### Adımlar

-1. **Build your app:**
+1. **Uygulamanızı derleyin** — CLI, TypeScript kaynaklarınızı derler ve uygulama manifestini oluşturur:

 ```bash filename="Terminal"
 yarn twenty build
 ```

-2. **Publish to npm:**
+2. **npm’ye yayımlayın** — derlenmiş paketi npm registry’ye gönderin:

 ```bash filename="Terminal"
-yarn twenty publish
+npx twenty publish
 ```

-This runs `npm publish` from the `.twenty/output/` directory.
+### Otomatik keşif

-To publish under a specific dist-tag (e.g., `beta` or `next`):
-
-```bash filename="Terminal"
-yarn twenty publish --tag beta
-```
-
-### How marketplace discovery works
-
-The Twenty server syncs its marketplace catalog from the npm registry **every hour**:
-
-1. It searches for all npm packages with the `keywords:twenty-app` keyword
-2. For each package, it fetches the `manifest.json` from the npm CDN
-3. The app's metadata (name, description, author, logo, screenshots, category) is extracted from the manifest and displayed in the marketplace
-
-After publishing, your app can take up to one hour to appear in the marketplace. To trigger the sync immediately instead of waiting for the next hourly run:
-
-```bash filename="Terminal"
-yarn twenty catalog-sync
-```
-
-To target a specific remote:
-
-```bash filename="Terminal"
-yarn twenty catalog-sync -r production
-```
-
-The metadata shown in the marketplace comes from your `defineApplication()` call in your app source code — fields like `displayName`, `description`, `author`, `category`, `logoUrl`, `screenshots`, `aboutDescription`, `websiteUrl`, and `termsUrl`.
+`twenty-app-` önekine sahip paketler, Twenty pazaryeri kataloğu tarafından otomatik olarak keşfedilir. Yayımlandıktan sonra, uygulamanız birkaç dakika içinde pazaryerinde görünür — manuel kayıt veya onay gerekmez.

 ### CI üzerinden yayımlama

-İskelet proje, her sürümde yayımlayan bir GitHub Actions iş akışını içerir:
+İskelet proje, her sürümde yayımlama yapan bir GitHub Actions iş akışını içerir. Önce `app:build` çalıştırır, ardından derleme çıktısından `npm publish --provenance` çalıştırır:

 ```yaml filename=".github/workflows/publish.yml"
 name: Publish
@@ -133,117 +72,48 @@ jobs:
          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
 ```

-For other CI systems (GitLab CI, CircleCI, etc.), the same three commands apply: `yarn install`, `yarn twenty build`, then `npm publish` from `.twenty/output`.
+Diğer CI sistemleri (GitLab CI, CircleCI, vb.) için de aynı üç komut geçerlidir: `yarn install`, `npx twenty build` ve ardından `.twenty/output` dizininden `npm publish`.

 <Tip>
 **npm provenance** isteğe bağlıdır ancak önerilir. `--provenance` ile yayımlamak, npm listenize bir güven rozeti ekler ve kullanıcıların paketin herkese açık bir CI ardışık düzenindeki belirli bir commit’ten oluşturulduğunu doğrulamasını sağlar. Kurulum talimatları için [npm provenance belgelerine](https://docs.npmjs.com/generating-provenance-statements) bakın.
 </Tip>

-## Deploying to a server (tarball)
+## Dahili dağıtım

-For apps you don't want publicly available — proprietary tools, enterprise-only integrations, or experimental builds — you can deploy a tarball directly to a Twenty server.
+Genel kullanıma açık olmasını istemediğiniz uygulamalar — sahipli araçlar, yalnızca kurumsal entegrasyonlar veya deneysel yapılar — için bir tarball’ı doğrudan bir Twenty sunucusuna gönderebilirsiniz.

-### Ön Gereksinimler
+### Bir tarball gönderin

-Before deploying, you need a configured remote pointing to the target server. Remotes store the server URL and authentication credentials locally in `~/.twenty/config.json`.
-
-Add a remote:
+Uygulamanızı derleyin ve tek adımda belirli bir sunucuya dağıtın:

 ```bash filename="Terminal"
-yarn twenty remote add --url https://your-twenty-server.com --as production
+npx twenty publish --server <server-url>
 ```

-For a local development server:
-
-```bash filename="Terminal"
-yarn twenty remote add --local --as local
-```
-
-You can also authenticate with an API key for non-interactive environments:
-
-```bash filename="Terminal"
-yarn twenty remote add --url https://your-twenty-server.com --token <api-key> --as production
-```
-
-Manage your remotes:
-
-```bash filename="Terminal"
-yarn twenty remote list       # List all configured remotes
-yarn twenty remote switch prod # Set the default remote
-yarn twenty remote status     # Show active remote and auth status
-yarn twenty remote remove old # Remove a remote
-```
-
-### Deploying
-
-Build and upload your app to the server in one step:
-
-```bash filename="Terminal"
-yarn twenty deploy
-```
-
-This builds the app with `--tarball`, then uploads the tarball to the default remote via a GraphQL multipart upload.
-
-To deploy to a specific remote:
-
-```bash filename="Terminal"
-yarn twenty deploy -r production
-```
-
-### Sharing a deployed app
-
-Tarball apps are not listed in the public marketplace, so other workspaces on the same server won't discover them by browsing. To share a deployed app:
-
-1. Go to **Settings > Applications > Registrations** and open your app
-2. In the **Distribution** tab, click **Copy share link**
-3. Share this link with users on other workspaces — it takes them directly to the app's install page
-
-The share link uses the server's base URL (without any workspace subdomain) so it works for any workspace on the server.
+Daha sonra, bu sunucudaki herhangi bir çalışma alanı uygulamayı **Applications** ayarları sayfasından yükleyip güncelleyebilir.

 ### Sürüm yönetimi

 Bir güncelleme yayımlamak için:

 1. `package.json` içindeki `version` alanını artırın
-2. Run `yarn twenty deploy` (or `yarn twenty deploy -r production`)
-3. Workspaces that have the app installed will see the upgrade available in their settings
+2. `npx twenty publish --server <server-url>` ile yeni bir tarball gönderin
+3. O sunucudaki çalışma alanları, ayarlarında kullanılabilir güncellemeyi görecektir.

-## Installing apps
+<Note>
+Dahili uygulamalar, gönderildikleri sunucu ile sınırlıdır. Genel pazaryerinde görünmezler ve diğer sunuculardaki çalışma alanları tarafından yüklenemezler.
+</Note>

-Once an app is published (npm) or deployed (tarball), workspaces install it through the UI:
-
-```bash filename="Terminal"
-yarn twenty install
-```
-
-Or from the **Settings > Applications** page in the Twenty UI, where both marketplace and tarball-deployed apps can be browsed and installed.
-
-## App distribution categories
+## Uygulama kategorileri

 Twenty, uygulamaları nasıl dağıtıldıklarına göre üç kategoriye ayırır:

-| Kategori               | Nasıl Çalışır                                                                                                                      | Pazaryerinde görünür mü? |
-| ---------------------- | ---------------------------------------------------------------------------------------------------------------------------------- | ------------------------ |
-| **Geliştirme**         | `yarn twenty dev` ile çalışan yerel geliştirme modu uygulamaları. Derleme ve test için kullanılır.                                 | Hayır                    |
-| **Published (npm)**    | Apps published to npm with the `twenty-app` keyword. Herhangi bir çalışma alanının yükleyebilmesi için pazaryerinde listelenir.    | Evet                     |
-| **Internal (tarball)** | Bir tarball aracılığıyla belirli bir sunucuya dağıtılan uygulamalar. Available only to workspaces on that server via a share link. | Hayır                    |
+| Kategori        | Nasıl Çalışır                                                                                                                       | Pazaryerinde görünür mü? |
+| --------------- | ----------------------------------------------------------------------------------------------------------------------------------- | ------------------------ |
+| **Geliştirme**  | `yarn twenty dev` ile çalışan yerel geliştirme modu uygulamaları. Derleme ve test için kullanılır.                                  | Hayır                    |
+| **Yayımlanmış** | `twenty-app-` önekiyle npm’ye yayımlanan uygulamalar. Herhangi bir çalışma alanının yükleyebilmesi için pazaryerinde listelenir.    | Evet                     |
+| **Dahili**      | Bir tarball aracılığıyla belirli bir sunucuya dağıtılan uygulamalar. Yalnızca o sunucudaki çalışma alanlarının kullanımına açıktır. | Hayır                    |

 <Tip>
 Uygulamanızı geliştirirken **Geliştirme** modunda başlayın. Hazır olduğunda, geniş dağıtım için **Yayımlanmış** (npm) ya da özel dağıtım için **Dahili** (tarball) seçeneğini tercih edin.
 </Tip>
-
-## CLI reference
-
-| Komut                       | Açıklama                                       | Key flags                                           |
-| --------------------------- | ---------------------------------------------- | --------------------------------------------------- |
-| `yarn twenty build`         | Compile app and generate manifest              | `--tarball` — also create a `.tgz` package          |
-| `yarn twenty publish`       | Build and publish to npm                       | `--tag <tag>` — npm dist-tag (e.g., `beta`, `next`) |
-| `yarn twenty deploy`        | Build and upload tarball to a server           | `-r, --remote <name>` — target remote               |
-| `yarn twenty catalog-sync`  | Trigger marketplace catalog sync on the server | `-r, --remote <name>` — target remote               |
-| `yarn twenty install`       | Install a deployed app on a workspace          | `-r, --remote <name>` — target remote               |
-| `yarn twenty dev`           | Watch and sync local changes                   | Uses default remote                                 |
-| `yarn twenty remote add`    | Add a server connection                        | `--url`, `--token`, `--as`, `--local`, `--port`     |
-| `yarn twenty remote list`   | List configured remotes                        | —                                                   |
-| `yarn twenty remote switch` | Set default remote                             | —                                                   |
-| `yarn twenty remote status` | Show connection status                         | —                                                   |
-| `yarn twenty remote remove` | Remove a remote                                | —                                                   |
@@ -15,21 +15,19 @@ twenty-sdk 提供你在应用中使用的类型化构件和辅助函数。 以

 该 SDK 提供辅助函数用于定义你的应用实体。 如 [实体检测](/l/zh/developers/extend/apps/getting-started#entity-detection) 中所述，你必须使用 `export default define<Entity>({...})` 才能让你的实体被检测到：

-| 函数                               | 目的                       |
-| -------------------------------- | ------------------------ |
-| `defineApplication`              | 配置应用元数据（必需，每个应用一个）       |
-| `defineObject`                   | 定义带字段的自定义对象              |
-| `defineField`                    | 使用附加字段扩展现有对象，或定义独立的关系字段。 |
-| `defineLogicFunction`            | 定义带处理程序的逻辑函数             |
-| `definePreInstallLogicFunction`  | 定义一个安装前逻辑函数（每个应用一个）      |
-| `definePostInstallLogicFunction` | 定义一个安装后逻辑函数（每个应用一个）      |
-| `defineFrontComponent`           | 为自定义 UI 定义前端组件           |
-| `defineRole`                     | 配置角色权限和对象访问              |
-| `defineView`                     | 为对象定义已保存的视图              |
-| `defineNavigationMenuItem`       | 定义侧边栏导航链接                |
-| `defineSkill`                    | 定义 AI 智能体技能              |
-| `defineAgent`                    | 定义 AI 智能体                |
-| `definePageLayout`               | 定义自定义页面布局                |
+| 函数                               | 目的                  |
+| -------------------------------- | ------------------- |
+| `defineApplication`              | 配置应用元数据（必需，每个应用一个）  |
+| `defineObject`                   | 定义带字段的自定义对象         |
+| `defineLogicFunction`            | 定义带处理程序的逻辑函数        |
+| `definePreInstallLogicFunction`  | 定义一个安装前逻辑函数（每个应用一个） |
+| `definePostInstallLogicFunction` | 定义一个安装后逻辑函数（每个应用一个） |
+| `defineFrontComponent`           | 为自定义 UI 定义前端组件      |
+| `defineRole`                     | 配置角色权限和对象访问         |
+| `defineField`                    | 为现有对象扩展额外字段         |
+| `defineView`                     | 为对象定义已保存的视图         |
+| `defineNavigationMenuItem`       | 定义侧边栏导航链接           |
+| `defineSkill`                    | 定义 AI 智能体技能         |

 这些函数会在构建时校验你的配置，并提供 IDE 自动补全和类型安全。

@@ -38,7 +36,7 @@ twenty-sdk 提供你在应用中使用的类型化构件和辅助函数。 以
 自定义对象同时描述工作空间中记录的架构与行为。 使用 `defineObject()` 以内置校验定义对象：

 ```typescript
-// src/objects/postCard.object.ts
+// src/app/postCard.object.ts
 import { defineObject, FieldType } from 'twenty-sdk';

 enum PostCardStatus {
@@ -112,7 +110,7 @@ export default defineObject({
 * `universalIdentifier` 必须在各次部署间保持唯一且稳定。
 * 每个字段都需要 `name`、`type`、`label` 以及其自身稳定的 `universalIdentifier`。
 * `fields` 数组是可选的——你可以定义没有自定义字段的对象。
-* 你可以使用 `yarn twenty add` 脚手架创建新对象，它会引导你完成命名、字段和关系。
+* 你可以使用 `yarn twenty entity:add` 脚手架创建新对象，它会引导你完成命名、字段和关系。

 <Note>
 **基础字段会自动创建。** 当你定义自定义对象时，Twenty 会自动添加标准字段
@@ -122,197 +120,6 @@ export default defineObject({
 但不建议这样做。
 </Note>

-### 在现有对象上定义字段
-
-使用 `defineField()` 向你不拥有的对象添加字段——例如标准的 Twenty 对象（Person、Company 等）。 或来自其他应用的对象。 与在 `defineObject()` 中的内联字段不同，独立字段需要一个 `objectUniversalIdentifier` 来指定它们要扩展的对象：
-
-```typescript
-// src/fields/company-loyalty-tier.field.ts
-import { defineField, FieldType } from 'twenty-sdk';
-
-export default defineField({
-  universalIdentifier: 'f2a1b3c4-d5e6-7890-abcd-ef1234567890',
-  objectUniversalIdentifier: '701aecb9-eb1c-4d84-9d94-b954b231b64b', // Company object
-  name: 'loyaltyTier',
-  type: FieldType.SELECT,
-  label: 'Loyalty Tier',
-  icon: 'IconStar',
-  options: [
-    { value: 'BRONZE', label: 'Bronze', position: 0, color: 'orange' },
-    { value: 'SILVER', label: 'Silver', position: 1, color: 'gray' },
-    { value: 'GOLD', label: 'Gold', position: 2, color: 'yellow' },
-  ],
-});
-```
-
-关键点：
-
-* `objectUniversalIdentifier` 用于标识目标对象。 对于标准对象，请使用从 `twenty-sdk` 导出的 `STANDARD_OBJECT_UNIVERSAL_IDENTIFIERS`。
-* 在 `defineObject()` 中以内联方式定义字段时，你不需要 `objectUniversalIdentifier`——它会从父对象继承。
-* `defineField()` 是为非通过 `defineObject()` 创建的对象添加字段的唯一方式。
-
-### 关系
-
-关系用于将对象彼此连接。 在 Twenty 中，关系始终是双向的——你需要定义两侧，每一侧都引用另一侧。
-
-关系有两种类型：
-
-| 关系类型          | 描述                  | 是否有外键？              |
-| ------------- | ------------------- | ------------------- |
-| `MANY_TO_ONE` | 该对象的多条记录指向目标对象的一条记录 | 是（`joinColumnName`） |
-| `ONE_TO_MANY` | 该对象的一条记录拥有目标对象的多条记录 | 否（反向侧）              |
-
-#### 关系如何工作
-
-每个关系都需要两个相互引用的字段：
-
-1. **MANY_TO_ONE** 侧——位于持有外键的对象上
-2. **ONE_TO_MANY** 侧——位于拥有集合的对象上
-
-两个字段都使用 `FieldType.RELATION`，并通过 `relationTargetFieldMetadataUniversalIdentifier` 相互交叉引用。
-
-#### 示例：Post Card 拥有多个收件人
-
-假设一个 `PostCard` 可以发送到多个 `PostCardRecipient` 记录。 每个收件人只隶属于一张 Post Card。
-
-**步骤 1：在 PostCard 上定义 ONE_TO_MANY 侧**（“一”侧）：
-
-```typescript
-// src/fields/post-card-recipients-on-post-card.field.ts
-import { defineField, FieldType, RelationType } from 'twenty-sdk';
-import { POST_CARD_UNIVERSAL_IDENTIFIER } from '../objects/post-card.object';
-import { POST_CARD_RECIPIENT_UNIVERSAL_IDENTIFIER } from '../objects/post-card-recipient.object';
-
-// Export so the other side can reference it
-export const POST_CARD_RECIPIENTS_FIELD_ID = 'a1111111-1111-1111-1111-111111111111';
-// Import from the other side
-import { POST_CARD_FIELD_ID } from './post-card-on-post-card-recipient.field';
-
-export default defineField({
-  universalIdentifier: POST_CARD_RECIPIENTS_FIELD_ID,
-  objectUniversalIdentifier: POST_CARD_UNIVERSAL_IDENTIFIER,
-  type: FieldType.RELATION,
-  name: 'postCardRecipients',
-  label: 'Post Card Recipients',
-  icon: 'IconUsers',
-  relationTargetObjectMetadataUniversalIdentifier: POST_CARD_RECIPIENT_UNIVERSAL_IDENTIFIER,
-  relationTargetFieldMetadataUniversalIdentifier: POST_CARD_FIELD_ID,
-  universalSettings: {
-    relationType: RelationType.ONE_TO_MANY,
-  },
-});
-```
-
-**步骤 2：在 PostCardRecipient 上定义 MANY_TO_ONE 侧**（“多”侧——持有外键）：
-
-```typescript
-// src/fields/post-card-on-post-card-recipient.field.ts
-import { defineField, FieldType, RelationType, OnDeleteAction } from 'twenty-sdk';
-import { POST_CARD_UNIVERSAL_IDENTIFIER } from '../objects/post-card.object';
-import { POST_CARD_RECIPIENT_UNIVERSAL_IDENTIFIER } from '../objects/post-card-recipient.object';
-
-// Export so the other side can reference it
-export const POST_CARD_FIELD_ID = 'b2222222-2222-2222-2222-222222222222';
-// Import from the other side
-import { POST_CARD_RECIPIENTS_FIELD_ID } from './post-card-recipients-on-post-card.field';
-
-export default defineField({
-  universalIdentifier: POST_CARD_FIELD_ID,
-  objectUniversalIdentifier: POST_CARD_RECIPIENT_UNIVERSAL_IDENTIFIER,
-  type: FieldType.RELATION,
-  name: 'postCard',
-  label: 'Post Card',
-  icon: 'IconMail',
-  relationTargetObjectMetadataUniversalIdentifier: POST_CARD_UNIVERSAL_IDENTIFIER,
-  relationTargetFieldMetadataUniversalIdentifier: POST_CARD_RECIPIENTS_FIELD_ID,
-  universalSettings: {
-    relationType: RelationType.MANY_TO_ONE,
-    onDelete: OnDeleteAction.CASCADE,
-    joinColumnName: 'postCardId',
-  },
-});
-```
-
-<Note>
-\*\*循环导入：\*\*两个关系字段相互引用彼此的 `universalIdentifier`。 为避免循环导入问题，请在各自文件中将字段 ID 作为具名常量导出，并在另一个文件中导入它们。 构建系统会在编译时解析这些引用。
-</Note>
-
-#### 与标准对象建立关系
-
-要与内置的 Twenty 对象（Person、Company 等）建立关系，请使用 `STANDARD_OBJECT_UNIVERSAL_IDENTIFIERS`：
-
-```typescript
-// src/fields/person-on-self-hosting-user.field.ts
-import {
-  defineField,
-  FieldType,
-  RelationType,
-  OnDeleteAction,
-  STANDARD_OBJECT_UNIVERSAL_IDENTIFIERS,
-} from 'twenty-sdk';
-import { SELF_HOSTING_USER_UNIVERSAL_IDENTIFIER } from '../objects/self-hosting-user.object';
-
-export const PERSON_FIELD_ID = 'c3333333-3333-3333-3333-333333333333';
-export const SELF_HOSTING_USER_REVERSE_FIELD_ID = 'd4444444-4444-4444-4444-444444444444';
-
-export default defineField({
-  universalIdentifier: PERSON_FIELD_ID,
-  objectUniversalIdentifier: SELF_HOSTING_USER_UNIVERSAL_IDENTIFIER,
-  type: FieldType.RELATION,
-  name: 'person',
-  label: 'Person',
-  description: 'Person matching with the self hosting user',
-  isNullable: true,
-  relationTargetObjectMetadataUniversalIdentifier:
-    STANDARD_OBJECT_UNIVERSAL_IDENTIFIERS.person.universalIdentifier,
-  relationTargetFieldMetadataUniversalIdentifier: SELF_HOSTING_USER_REVERSE_FIELD_ID,
-  universalSettings: {
-    relationType: RelationType.MANY_TO_ONE,
-    onDelete: OnDeleteAction.SET_NULL,
-    joinColumnName: 'personId',
-  },
-});
-```
-
-#### 关系字段属性
-
-| 属性                                                | 必填               | 描述                                                             |
-| ------------------------------------------------- | ---------------- | -------------------------------------------------------------- |
-| `类型`                                              | 是                | 必须为 `FieldType.RELATION`                                       |
-| `relationTargetObjectMetadataUniversalIdentifier` | 是                | 目标对象的 `universalIdentifier`                                    |
-| `relationTargetFieldMetadataUniversalIdentifier`  | 是                | 目标对象上匹配字段的 `universalIdentifier`                               |
-| `universalSettings.relationType`                  | 是                | `RelationType.MANY_TO_ONE` 或 `RelationType.ONE_TO_MANY`        |
-| `universalSettings.onDelete`                      | 仅适用于 MANY_TO_ONE | 当被引用的记录被删除时的处理方式：`CASCADE`、`SET_NULL`、`RESTRICT` 或 `NO_ACTION` |
-| `universalSettings.joinColumnName`                | 仅适用于 MANY_TO_ONE | 外键的数据库列名（例如，`postCardId`）                                      |
-
-#### 在 defineObject 中内联关系字段
-
-你也可以直接在 `defineObject()` 内定义关系字段。 在这种情况下，省略 `objectUniversalIdentifier`——它会从父对象继承：
-
-```typescript
-export default defineObject({
-  universalIdentifier: '...',
-  nameSingular: 'postCardRecipient',
-  // ...
-  fields: [
-    {
-      universalIdentifier: POST_CARD_FIELD_ID,
-      type: FieldType.RELATION,
-      name: 'postCard',
-      label: 'Post Card',
-      relationTargetObjectMetadataUniversalIdentifier: POST_CARD_UNIVERSAL_IDENTIFIER,
-      relationTargetFieldMetadataUniversalIdentifier: POST_CARD_RECIPIENTS_FIELD_ID,
-      universalSettings: {
-        relationType: RelationType.MANY_TO_ONE,
-        onDelete: OnDeleteAction.CASCADE,
-        joinColumnName: 'postCardId',
-      },
-    },
-    // ... other fields
-  ],
-});
-```
-
 ### 应用配置（application-config.ts）

 每个应用都有一个 `application-config.ts` 文件，用于描述：
@@ -354,29 +161,13 @@ export default defineApplication({
 * `defaultRoleUniversalIdentifier` 必须与角色文件一致（见下文）。
 * 清单构建期间会自动检测安装前和安装后函数。 参见 [安装前函数](#pre-install-functions) 和 [安装后函数](#post-install-functions)。

-#### 应用市场元数据
-
-如果你计划[发布你的应用](/l/zh/developers/extend/apps/publishing)，这些可选字段将控制你的应用在应用市场中的展示：
-
-| 字段                 | 描述                         |
-| ------------------ | -------------------------- |
-| `作者`               | 作者或公司名称                    |
-| `类别`               | 用于应用市场筛选的应用类别              |
-| `logoUrl`          | 你的应用徽标的路径（相对于 `./assets/`） |
-| `screenshots`      | 屏幕截图路径数组（相对于 `./assets/`）  |
-| `aboutDescription` | 用于“关于”选项卡的更长 Markdown 描述   |
-| `websiteUrl`       | 你的网站链接                     |
-| `termsUrl`         | 服务条款链接                     |
-| `emailSupport`     | 支持电子邮件地址                   |
-| `issueReportUrl`   | 问题跟踪器链接                    |
-
 #### 角色和权限

 应用可以定义角色，以封装对工作空间对象与操作的权限。 `application-config.ts` 中的 `defaultRoleUniversalIdentifier` 字段指定你的应用逻辑函数所使用的默认角色。

 * 作为 `TWENTY_API_KEY` 注入的运行时 API 密钥源自该默认函数角色。
 * 类型化客户端将受限于该角色授予的权限。
-* 遵循最小权限原则：创建一个仅包含你的函数所需权限的专用角色，然后引用其通用标识符。
+* 遵循最小权限原则：仅授予函数所需权限来创建一个专用角色，然后引用其通用标识符。

 ##### 默认函数角色（*.role.ts）

@@ -439,7 +230,7 @@ export default defineRole({
 每个函数文件都使用 `defineLogicFunction()` 导出包含处理程序和可选触发器的配置。

 ```typescript
-// src/logic-functions/createPostCard.logic-function.ts
+// 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';
@@ -533,7 +324,7 @@ export default definePreInstallLogicFunction({
 你也可以随时使用 CLI 手动执行安装前函数：

 ```bash filename="Terminal"
-yarn twenty exec --preInstall
+yarn twenty function:execute --preInstall
 ```

 关键点：
@@ -543,7 +334,7 @@ yarn twenty exec --preInstall
 * 每个应用仅允许一个安装前函数。 如果检测到多个，清单构建将报错。
 * 在构建期间，函数的 `universalIdentifier` 会自动设置为应用清单上的 `preInstallLogicFunctionUniversalIdentifier` —— 你无需在 `defineApplication()` 中引用它。
 * 默认超时时间设置为 300 秒（5 分钟），以便支持更长的准备任务。
-* 安装前函数不需要触发器——它们会在安装前由平台调用，或通过 `exec --preInstall` 手动调用。
+* 安装前函数不需要触发器——它们会在安装前由平台调用，或通过 `function:execute --preInstall` 手动调用。

 ### 安装后函数

@@ -571,7 +362,7 @@ export default definePostInstallLogicFunction({
 你也可以随时使用 CLI 手动执行安装后函数：

 ```bash filename="Terminal"
-yarn twenty exec --postInstall
+yarn twenty function:execute --postInstall
 ```

 关键点：
@@ -581,7 +372,7 @@ yarn twenty exec --postInstall
 * 每个应用仅允许一个安装后函数。 如果检测到多个，清单构建将报错。
 * 在构建期间，函数的 `universalIdentifier` 会自动设置为应用清单上的 `postInstallLogicFunctionUniversalIdentifier` —— 你无需在 `defineApplication()` 中引用它。
 * 默认超时时间设置为 300 秒（5 分钟），以便支持更长的设置任务，如数据填充。
-* 安装后函数不需要触发器——它们会在安装过程中由平台调用，或通过 `exec --postInstall` 手动调用。
+* 安装后函数不需要触发器——它们会在安装过程中由平台调用，或通过 `function:execute --postInstall` 手动调用。

 ### 路由触发器负载

@@ -625,15 +416,15 @@ const handler = async (event: RoutePayload) => {

 `RoutePayload` 类型具有以下结构：

-| 属性                           | 类型                                    | 描述                                                |
-| ---------------------------- | ------------------------------------- | ------------------------------------------------- |
-| `headers`                    | `Record<string, string \| undefined>` | HTTP 请求头（仅限 `forwardedRequestHeaders` 中列出的那些）     |
-| `queryStringParameters`      | `Record<string, string \| undefined>` | 查询字符串参数（多个值以逗号连接）                                 |
-| `pathParameters`             | `Record<string, string \| undefined>` | 从路由模式中提取的路径参数（例如，`/users/:id` -> `{ id: '123' }`） |
-| `body`                       | `object \| null`                      | 已解析的请求体（JSON）                                     |
-| `isBase64Encoded`            | `boolean`                             | 请求体是否为 base64 编码                                  |
-| `requestContext.http.method` | `string`                              | HTTP 方法（GET、POST、PUT、PATCH、DELETE）                |
-| `requestContext.http.path`   | `string`                              | 原始请求路径                                            |
+| 属性                           | 类型                                    | 描述                                               |
+| ---------------------------- | ------------------------------------- | ------------------------------------------------ |
+| `headers`                    | `Record<string, string \| undefined>` | HTTP 请求头（仅限 `forwardedRequestHeaders` 中列出的那些）    |
+| `queryStringParameters`      | `Record<string, string \| undefined>` | 查询字符串参数（多个值以逗号连接）                                |
+| `pathParameters`             | `Record<string, string \| undefined>` | 从路由模式中提取的路径参数（例如，`/users/:id` → `{ id: '123' }`） |
+| `body`                       | `object \| null`                      | 已解析的请求体（JSON）                                    |
+| `isBase64Encoded`            | `boolean`                             | 请求体是否为 base64 编码                                 |
+| `requestContext.http.method` | `string`                              | HTTP 方法（GET、POST、PUT、PATCH、DELETE）               |
+| `requestContext.http.path`   | `string`                              | 原始请求路径                                           |

 ### 转发 HTTP 请求头

@@ -675,7 +466,7 @@ const handler = async (event: RoutePayload) => {

 你可以通过两种方式创建新函数：

-* **脚手架生成**：运行 `yarn twenty add` 并选择添加新逻辑函数的选项。 这将生成一个包含处理程序和配置的入门文件。
+* **脚手架生成**：运行 `yarn twenty entity:add` 并选择添加新逻辑函数的选项。 这将生成一个包含处理程序和配置的入门文件。
 * **手动**：创建一个新的 `*.logic-function.ts` 文件，并使用 `defineLogicFunction()`，遵循相同的模式。

 ### 将逻辑函数标记为工具
@@ -687,7 +478,7 @@ const handler = async (event: RoutePayload) => {
 ```typescript
 // src/logic-functions/enrich-company.logic-function.ts
 import { defineLogicFunction } from 'twenty-sdk';
-import { CoreApiClient } from 'twenty-client-sdk/core';
+import { CoreApiClient } from 'twenty-sdk/generated';

 const handler = async (params: { companyName: string; domain?: string }) => {
  const client = new CoreApiClient();
@@ -776,7 +567,7 @@ export default defineFrontComponent({

 你可以通过两种方式创建新的前端组件：

-* **脚手架生成**：运行 `yarn twenty add` 并选择添加新前端组件的选项。
+* **脚手架生成**：运行 `yarn twenty entity:add` 并选择添加新前端组件的选项。
 * **手动**：创建一个新的 `.tsx` 文件，并使用 `defineFrontComponent()`，遵循相同的模式。

 ### 技能
@@ -811,122 +602,47 @@ export default defineSkill({

 你可以通过两种方式创建新技能：

-* **脚手架生成**：运行 `yarn twenty add` 并选择添加新技能的选项。
+* **脚手架生成**：运行 `yarn twenty entity:add` 并选择添加新技能的选项。
 * **手动**：创建一个新文件，并使用 `defineSkill()`，遵循相同的模式。

-### 类型化 API 客户端（`twenty-client-sdk`）
+### 生成的类型化客户端

-`twenty-client-sdk` 包提供了两个类型化的 GraphQL 客户端，供你的逻辑函数和前端组件与 Twenty API 交互：
+两个类型化客户端会由 `yarn twenty dev` 基于你的工作区架构自动生成，并存放在 `node_modules/twenty-sdk/generated`：

-| 客户端                 | 导入                           | 端点                       | 是否生成？     |
-| ------------------- | ---------------------------- | ------------------------ | --------- |
-| `CoreApiClient`     | `twenty-client-sdk/core`     | `/graphql`——工作区数据（记录、对象） | 是，在开发/构建时 |
-| `MetadataApiClient` | `twenty-client-sdk/metadata` | `/metadata`——工作区配置、文件上传  | 否，已预构建提供  |
-
-#### CoreApiClient
-
-`CoreApiClient` 是用于查询和变更工作区数据的主要客户端。 它会在执行 `yarn twenty dev` 或 `yarn twenty build` 时根据你的工作区架构生成，因此能完全类型化以匹配你的对象和字段。
+* **`CoreApiClient`** — 查询 `/graphql` 端点以获取工作区数据
+* **`MetadataApiClient`** — 查询 `/metadata` 端点以获取工作区配置并处理文件上传

 ```typescript
-import { CoreApiClient } from 'twenty-client-sdk/core';
+import { CoreApiClient, MetadataApiClient } from 'twenty-sdk/generated';

 const client = new CoreApiClient();
-
-// Query records
-const { companies } = await client.query({
-  companies: {
-    edges: {
-      node: {
-        id: true,
-        name: true,
-        domainName: true,
-      },
-    },
-  },
-});
-
-// Create a record
-const { createCompany } = await client.mutation({
-  createCompany: {
-    __args: {
-      data: {
-        name: 'Acme Corp',
-      },
-    },
-    id: true,
-    name: true,
-  },
-});
-```
-
-该客户端使用选择集语法：传入 `true` 以包含某字段，使用 `__args` 传递参数，并通过嵌套对象表示关系。 你将基于工作区架构获得完整的自动补全和类型检查。
-
-<Note>
-**CoreApiClient 在开发/构建时生成。** 如果在未先运行 `yarn twenty dev` 或 `yarn twenty build` 的情况下尝试使用它，将会抛出错误。 生成过程是自动完成的——CLI 会自省你的工作区 GraphQL 架构，使用 `@genql/cli` 生成类型化客户端，将生成的源码写入 `node_modules/twenty-client-sdk/dist/core/generated/`，并替换 `node_modules/twenty-client-sdk/dist/core.mjs` 和 `node_modules/twenty-client-sdk/dist/core.cjs` 中的存根。
-</Note>
-
-#### 使用 CoreSchema 进行类型标注
-
-`CoreSchema` 提供与工作区对象相匹配的 TypeScript 类型，可用于为组件状态或函数参数进行类型标注：
-
-```typescript
-import { CoreApiClient, CoreSchema } from 'twenty-client-sdk/core';
-import { useState } from 'react';
-
-const [company, setCompany] = useState<
-  Pick<CoreSchema.Company, 'id' | 'name'> | undefined
->(undefined);
-
-const client = new CoreApiClient();
-const result = await client.query({
-  company: {
-    __args: { filter: { position: { eq: 1 } } },
-    id: true,
-    name: true,
-  },
-});
-setCompany(result.company);
-```
-
-#### MetadataApiClient
-
-`MetadataApiClient` 随 SDK 一并提供，已预构建（无需生成）。 它会查询 `/metadata` 端点以获取工作区配置、应用以及文件上传：
-
-```typescript
-import { MetadataApiClient } from 'twenty-client-sdk/metadata';
+const { me } = await client.query({ me: { id: true, displayName: true } });

 const metadataClient = new MetadataApiClient();
-
-// Query workspace info
-const { currentWorkspace } = await metadataClient.query({
-  currentWorkspace: { id: true, displayName: true },
-});
-
-// List installed applications
-const { findManyApplications } = await metadataClient.query({
-  findManyApplications: {
-    id: true,
-    name: true,
-    version: true,
-  },
-});
+const { currentWorkspace } = await metadataClient.query({ currentWorkspace: { id: true } });
 ```

-#### 运行时凭据
+每当你的对象或字段发生变化时，`yarn twenty dev` 都会自动重新生成这两个客户端。

-当你的代码在 Twenty 上运行（逻辑函数或前端组件）时，平台会以环境变量的形式注入凭据：
+#### 逻辑函数中的运行时凭据

-* `TWENTY_API_URL`——Twenty API 的基础 URL
-* `TWENTY_API_KEY`——作用域限定于你的应用默认函数角色的短期密钥
+当你的函数在 Twenty 上运行时，平台会在代码执行前将凭据作为环境变量注入：

-你无需将这些值传递给客户端——它们会自动从 `process.env` 读取。 API 密钥的权限由你的 `application-config.ts` 中 `defaultRoleUniversalIdentifier` 引用的角色决定。
+* `TWENTY_API_URL`：你的应用所针对的 Twenty API 的基础 URL。
+* `TWENTY_API_KEY`：作用域限定于你的应用默认函数角色的短期密钥。
+
+备注:
+
+* 你无需向生成的客户端传递 URL 或 API 密钥。 它会在运行时从 process.env 读取 `TWENTY_API_URL` 和 `TWENTY_API_KEY`。
+* API 密钥的权限由 `application-config.ts` 中通过 `defaultRoleUniversalIdentifier` 引用的角色决定。 这是你的应用逻辑函数使用的默认角色。
+* 应用可以定义角色以遵循最小权限原则。 仅授予函数所需的权限，然后将 `defaultRoleUniversalIdentifier` 指向该角色的通用标识符。

 #### 上传文件

-`MetadataApiClient` 包含一个 `uploadFile` 方法，用于将文件附加到文件类型字段。 它实现了[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-client-sdk/metadata';
+import { MetadataApiClient } from 'twenty-sdk/generated';
 import * as fs from 'fs';

 const metadataClient = new MetadataApiClient();
@@ -936,14 +652,25 @@ const fileBuffer = fs.readFileSync('./invoice.pdf');
 const uploadedFile = await metadataClient.uploadFile(
  fileBuffer,                                         // file contents as a Buffer
  'invoice.pdf',                                      // filename
-  'application/pdf',                                  // MIME type
-  '58a0a314-d7ea-4865-9850-7fb84e72f30b',            // field universalIdentifier
+  '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` | 原始文件内容                                           |
@@ -953,7 +680,8 @@ console.log(uploadedFile);

 关键点：

-* 使用字段的 `universalIdentifier`（而不是其工作区特定的 ID），因此你的上传代码可在安装了你的应用的任何工作区中运行。
+* `uploadFile` 方法可在 `MetadataApiClient` 上使用，因为上传 mutation 由 `/metadata` 端点解析。
+* 它使用该字段的 `universalIdentifier`（而不是其工作区特定的 ID），因此你的上传代码可以在安装了你的应用的任何工作区中使用——这与应用在其他地方引用字段的方式保持一致。
 * 返回的 `url` 是一个签名 URL，你可以用它来访问已上传的文件。

 ### Hello World 示例
@@ -49,7 +49,7 @@ npx create-twenty-app@latest my-app --minimal

 ```bash filename="Terminal"
 # Add a new entity to your application (guided)
-yarn twenty add
+yarn twenty entity:add

 # Watch your application's function logs
 yarn twenty function:logs
@@ -123,7 +123,7 @@ my-twenty-app/
 总体来说：

 * **package.json**：声明应用名称、版本、引擎（Node 24+、Yarn 4），并添加 `twenty-sdk` 以及一个 `twenty` 脚本，该脚本会委托给本地的 `twenty` CLI。 运行 `yarn twenty help` 以列出所有可用命令。
-* **.gitignore**: Ignores common artifacts such as `node_modules`, `.yarn`, `.twenty/`, `dist/`, `build/`, coverage folders, log files, and `.env*` files.
+* **.gitignore**：忽略常见产物，如 `node_modules`、`.yarn`、`generated/`（类型化客户端）、`dist/`、`build/`、覆盖率文件夹、日志文件以及 `.env*` 文件。
 * **yarn.lock**、**.yarnrc.yml**、**.yarn/**：锁定并配置项目使用的 Yarn 4 工具链。
 * **.nvmrc**：固定项目期望的 Node.js 版本。
 * **.oxlintrc.json** 和 **tsconfig.json**：为应用的 TypeScript 源码提供 Lint 与 TypeScript 配置。
@@ -167,8 +167,8 @@ export default defineObject({

 后续命令将添加更多文件和文件夹：

-* `yarn twenty dev` will auto-generate the typed `CoreApiClient` (for workspace data via `/graphql`) into `node_modules/twenty-client-sdk/`. The `MetadataApiClient` (for workspace configuration and file uploads via `/metadata`) ships pre-built and is available immediately. Import them from `twenty-client-sdk/core` and `twenty-client-sdk/metadata` respectively.
-* `yarn twenty add` will add entity definition files under `src/` for your custom objects, functions, front components, roles, skills, and more.
+* `yarn twenty dev` 会在 `node_modules/twenty-sdk/generated` 中自动生成两个类型化 API 客户端：`CoreApiClient`（通过 `/graphql` 获取工作区数据）和 `MetadataApiClient`（通过 `/metadata` 处理工作区配置和文件上传）。
+* `yarn twenty entity:add` 会在 `src/` 下为你的自定义对象、函数、前端组件、角色、技能等添加实体定义文件。

 ## 身份验证

@@ -12,25 +12,7 @@ description: 将你的 Twenty 应用分发到应用市场，或进行内部部
 一旦你的应用已[在本地构建并完成测试](/l/zh/developers/extend/apps/building)，你可以通过两种方式进行分发：

 * **发布到 npm** — 将你的应用在 Twenty 应用市场上架，供任何工作区发现并安装。
-* **部署 tar 包** — 直接将你的应用上传到特定的 Twenty 服务器，以供内部或私有使用。
-
-两种路径都从同一个**构建**步骤开始。
-
-## 构建你的应用
-
-`build` 命令会编译你的 TypeScript 源码，转译逻辑函数和前端组件，并生成一个描述你应用内容的 `manifest.json`：
-
-```bash filename="Terminal"
-yarn twenty build
-```
-
-输出将写入 `.twenty/output/`。 This directory contains everything needed for distribution: compiled code, assets, the manifest, and a copy of your `package.json`.
-
-To also create a `.tgz` tarball (used by the deploy command internally, or for manual distribution):
-
-```bash filename="Terminal"
-yarn twenty build --tarball
-```
+* **推送 tar 包** — 将你的应用部署到特定的 Twenty 服务器供内部使用，而无需公开发布。

 ## 发布到 npm

@@ -39,72 +21,29 @@ yarn twenty build --tarball
 ### 要求

 * 一个 [npm](https://www.npmjs.com) 账户
-* The `twenty-app` keyword **must** be listed in your `package.json` `keywords` array
-
-### Adding the required keyword
-
-The Twenty marketplace discovers apps by searching the npm registry for packages with the `twenty-app` keyword. Add it to your `package.json`:
-
-```json filename="package.json"
-{
-  "name": "twenty-app-postcard-sender",
-  "version": "1.0.0",
-  "keywords": ["twenty-app"],
-  ...
-}
-```
-
-<Note>
-The marketplace searches for `keywords:twenty-app` on the npm registry. Without this keyword, your package won't appear in the marketplace even if it has the `twenty-app-` name prefix.
-</Note>
+* 你的包名**必须**使用 `twenty-app-` 前缀（例如，`twenty-app-postcard-sender`）

 ### 步骤

-1. **Build your app:**
+1. **构建你的应用** — CLI 会编译你的 TypeScript 源码并生成应用清单：

 ```bash filename="Terminal"
 yarn twenty build
 ```

-2. **Publish to npm:**
+2. **发布到 npm** — 将构建好的包推送到 npm 注册表：

 ```bash filename="Terminal"
-yarn twenty publish
+npx twenty publish
 ```

-This runs `npm publish` from the `.twenty/output/` directory.
+### 自动发现

-To publish under a specific dist-tag (e.g., `beta` or `next`):
-
-```bash filename="Terminal"
-yarn twenty publish --tag beta
-```
-
-### How marketplace discovery works
-
-The Twenty server syncs its marketplace catalog from the npm registry **every hour**:
-
-1. It searches for all npm packages with the `keywords:twenty-app` keyword
-2. For each package, it fetches the `manifest.json` from the npm CDN
-3. The app's metadata (name, description, author, logo, screenshots, category) is extracted from the manifest and displayed in the marketplace
-
-After publishing, your app can take up to one hour to appear in the marketplace. To trigger the sync immediately instead of waiting for the next hourly run:
-
-```bash filename="Terminal"
-yarn twenty catalog-sync
-```
-
-To target a specific remote:
-
-```bash filename="Terminal"
-yarn twenty catalog-sync -r production
-```
-
-The metadata shown in the marketplace comes from your `defineApplication()` call in your app source code — fields like `displayName`, `description`, `author`, `category`, `logoUrl`, `screenshots`, `aboutDescription`, `websiteUrl`, and `termsUrl`.
+Twenty 应用市场目录会自动发现带有 `twenty-app-` 前缀的包。 发布后，你的应用会在几分钟内出现在应用市场中 — 无需手动注册或审批。

 ### CI 发布

-The scaffolded project includes a GitHub Actions workflow that publishes on every release:
+脚手架项目包含一个 GitHub Actions 工作流，会在每次发版时自动发布。 它会先运行 `app:build`，然后在构建输出目录中执行 `npm publish --provenance`：

 ```yaml filename=".github/workflows/publish.yml"
 name: Publish
@@ -133,117 +72,48 @@ jobs:
          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
 ```

-For other CI systems (GitLab CI, CircleCI, etc.), the same three commands apply: `yarn install`, `yarn twenty build`, then `npm publish` from `.twenty/output`.
+对于其他 CI 系统（GitLab CI、CircleCI 等），同样适用以下三条命令：`yarn install`、`npx twenty build`，然后在 `.twenty/output` 目录下执行 `npm publish`。

 <Tip>
 **npm provenance** 可选，但建议启用。 使用 `--provenance` 发布会在你的 npm 列表中添加可信徽章，使用户可以验证该包是由公共 CI 流水线中的特定提交构建的。 有关设置说明，请参见 [npm provenance 文档](https://docs.npmjs.com/generating-provenance-statements)。
 </Tip>

-## Deploying to a server (tarball)
+## 内部分发

-For apps you don't want publicly available — proprietary tools, enterprise-only integrations, or experimental builds — you can deploy a tarball directly to a Twenty server.
+对于你不希望公开的应用 — 例如专有工具、仅供企业使用的集成或实验性构建 — 你可以将 tar 包直接推送到某台 Twenty 服务器。

-### 先决条件
+### 推送 tar 包

-Before deploying, you need a configured remote pointing to the target server. Remotes store the server URL and authentication credentials locally in `~/.twenty/config.json`.
-
-Add a remote:
+在一步中构建你的应用并将其部署到特定服务器：

 ```bash filename="Terminal"
-yarn twenty remote add --url https://your-twenty-server.com --as production
+npx twenty publish --server <server-url>
 ```

-For a local development server:
-
-```bash filename="Terminal"
-yarn twenty remote add --local --as local
-```
-
-You can also authenticate with an API key for non-interactive environments:
-
-```bash filename="Terminal"
-yarn twenty remote add --url https://your-twenty-server.com --token <api-key> --as production
-```
-
-Manage your remotes:
-
-```bash filename="Terminal"
-yarn twenty remote list       # List all configured remotes
-yarn twenty remote switch prod # Set the default remote
-yarn twenty remote status     # Show active remote and auth status
-yarn twenty remote remove old # Remove a remote
-```
-
-### Deploying
-
-Build and upload your app to the server in one step:
-
-```bash filename="Terminal"
-yarn twenty deploy
-```
-
-This builds the app with `--tarball`, then uploads the tarball to the default remote via a GraphQL multipart upload.
-
-To deploy to a specific remote:
-
-```bash filename="Terminal"
-yarn twenty deploy -r production
-```
-
-### Sharing a deployed app
-
-Tarball apps are not listed in the public marketplace, so other workspaces on the same server won't discover them by browsing. To share a deployed app:
-
-1. Go to **Settings > Applications > Registrations** and open your app
-2. In the **Distribution** tab, click **Copy share link**
-3. Share this link with users on other workspaces — it takes them directly to the app's install page
-
-The share link uses the server's base URL (without any workspace subdomain) so it works for any workspace on the server.
+该服务器上的任何工作区随后都可以在**应用程序**设置页面安装和升级该应用。

 ### 版本管理

 要发布更新：

 1. 更新 `package.json` 中的 `version` 字段
-2. Run `yarn twenty deploy` (or `yarn twenty deploy -r production`)
-3. Workspaces that have the app installed will see the upgrade available in their settings
+2. 使用 `npx twenty publish --server <server-url>` 推送新的 tar 包
+3. 该服务器上的工作区会在其设置中看到可用的升级

-## Installing apps
+<Note>
+内部应用的作用范围仅限于它们被推送到的服务器。 它们不会出现在公共应用市场中，其他服务器上的工作区也无法安装。
+</Note>

-Once an app is published (npm) or deployed (tarball), workspaces install it through the UI:
-
-```bash filename="Terminal"
-yarn twenty install
-```
-
-Or from the **Settings > Applications** page in the Twenty UI, where both marketplace and tarball-deployed apps can be browsed and installed.
-
-## App distribution categories
+## 应用类别

 Twenty 会根据分发方式将应用归为三类：

-| 类别                     | 工作原理                                                                               | 在应用市场中可见？ |
-| ---------------------- | ---------------------------------------------------------------------------------- | --------- |
-| **开发**                 | 通过 `yarn twenty dev` 运行的本地开发模式应用。 用于构建和测试。                                         | 否         |
-| **Published (npm)**    | Apps published to npm with the `twenty-app` keyword. 在应用市场上架，供任何工作区安装。             | 是         |
-| **Internal (tarball)** | 通过 tar 包部署到特定服务器的应用。 Available only to workspaces on that server via a share link. | 否         |
+| 类别      | 工作原理                                              | 在应用市场中可见？ |
+| ------- | ------------------------------------------------- | --------- |
+| **开发**  | 通过 `yarn twenty dev` 运行的本地开发模式应用。 用于构建和测试。        | 否         |
+| **已发布** | 使用 `twenty-app-` 前缀发布到 npm 的应用。 在应用市场上架，供任何工作区安装。 | 是         |
+| **内部**  | 通过 tar 包部署到特定服务器的应用。 仅对该服务器上的工作区可用。               | 否         |

 <Tip>
 在构建你的应用时，从**开发**模式开始。 准备就绪后，选择用于广泛分发的**已发布**（npm），或用于私有部署的**内部**（tar 包）。
 </Tip>
-
-## CLI reference
-
-| 命令                          | 描述                                             | Key flags                                           |
-| --------------------------- | ---------------------------------------------- | --------------------------------------------------- |
-| `yarn twenty build`         | Compile app and generate manifest              | `--tarball` — also create a `.tgz` package          |
-| `yarn twenty publish`       | Build and publish to npm                       | `--tag <tag>` — npm dist-tag (e.g., `beta`, `next`) |
-| `yarn twenty deploy`        | Build and upload tarball to a server           | `-r, --remote <name>` — target remote               |
-| `yarn twenty catalog-sync`  | Trigger marketplace catalog sync on the server | `-r, --remote <name>` — target remote               |
-| `yarn twenty install`       | Install a deployed app on a workspace          | `-r, --remote <name>` — target remote               |
-| `yarn twenty dev`           | Watch and sync local changes                   | Uses default remote                                 |
-| `yarn twenty remote add`    | Add a server connection                        | `--url`, `--token`, `--as`, `--local`, `--port`     |
-| `yarn twenty remote list`   | List configured remotes                        | —                                                   |
-| `yarn twenty remote switch` | Set default remote                             | —                                                   |
-| `yarn twenty remote status` | Show connection status                         | —                                                   |
-| `yarn twenty remote remove` | Remove a remote                                | —                                                   |
@@ -61,7 +61,7 @@ const jestConfig = {
  extensionsToTreatAsEsm: ['.ts', '.tsx'],
  coverageThreshold: {
    global: {
-      statements: 48.4,
+      statements: 48.5,
      lines: 47.0,
      functions: 39.5,
    },
--- a/Show More
+++ b/Show More