WIP¨

Improve workflow metrics with faillure reason
chore(deps): bump nodemailer from 7.0.11 to 7.0.13 (#18754 )
2026-03-20 15:25:35 +01:00 · 2026-03-19 15:30:54 +01:00 · 2026-03-19 09:22:17 +00:00 · 2026-03-19 09:11:58 +00:00 · 2026-03-19 09:10:58 +00:00 · 2026-03-19 10:10:47 +01:00
2497 changed files with 51921 additions and 52958 deletions
@@ -1,5 +1,5 @@
 .git
 .env
-node_modules
+**/node_modules
 .nx/cache
 packages/twenty-server/.env
@@ -100,7 +100,7 @@ jobs:
          create-twenty-app --version
          mkdir -p /tmp/e2e-test-workspace
          cd /tmp/e2e-test-workspace
-          create-twenty-app test-app --exhaustive --display-name "Test App" --description "E2E test app"
+          create-twenty-app test-app --exhaustive --display-name "Test App" --description "E2E test app" --skip-local-instance

      - name: Install scaffolded app dependencies
        run: |
@@ -151,22 +151,24 @@ jobs:
          SEED_API_KEY: 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIyMDIwMjAyMC1lNmI1LTQ2ODAtOGEzMi1iODIwOTczNzE1NmIiLCJ1c2VySWQiOiIyMDIwMjAyMC1lNmI1LTQ2ODAtOGEzMi1iODIwOTczNzE1NmIiLCJ3b3Jrc3BhY2VJZCI6IjIwMjAyMDIwLTFjMjUtNGQwMi1iZjI1LTZhZWNjZjdlYTQxOSIsIndvcmtzcGFjZU1lbWJlcklkIjoiMjAyMDIwMjAtNDYzZi00MzViLTgyOGMtMTA3ZTAwN2EyNzExIiwidXNlcldvcmtzcGFjZUlkIjoiMjAyMDIwMjAtMWU3Yy00M2Q5LWE1ZGItNjg1YjUwNjlkODE2IiwidHlwZSI6IkFDQ0VTUyIsImF1dGhQcm92aWRlciI6InBhc3N3b3JkIiwiaWF0IjoxNzUxMjgxNzA0LCJleHAiOjIwNjY4NTc3MDR9.HMGqCsVlOAPVUBhKSGlD1X86VoHKt4LIUtET3CGIdik'
        run: |
          cd /tmp/e2e-test-workspace/test-app
-          npx --no-install twenty auth:login --api-key $SEED_API_KEY --api-url http://localhost:3000
+          npx --no-install twenty remote add --token $SEED_API_KEY --url http://localhost:3000

      - name: Build scaffolded app
        run: |
          cd /tmp/e2e-test-workspace/test-app
-          npx --no-install twenty app:build
+          npx --no-install twenty build
          test -d .twenty/output

      - name: Execute hello-world logic function
        run: |
          cd /tmp/e2e-test-workspace/test-app
-          EXEC_OUTPUT=$(npx --no-install twenty function:execute --functionName hello-world-logic-function)
+          EXEC_OUTPUT=$(npx --no-install twenty exec --functionName hello-world-logic-function)
          echo "$EXEC_OUTPUT"
          echo "$EXEC_OUTPUT" | grep -q "Hello, World!"

      - name: Run scaffolded app integration test
+        env:
+          TWENTY_API_URL: http://localhost:3000
        run: |
          cd /tmp/e2e-test-workspace/test-app
          yarn test
@@ -10,8 +10,8 @@ permissions:
  contents: read

 concurrency:
-  group: ${{ github.workflow }}-${{ github.event_name == 'merge_group' && github.event.merge_group.base_ref || github.ref }}
-  cancel-in-progress: ${{ github.event_name != 'merge_group' }}
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: ${{ github.ref != 'refs/heads/main' }}

 jobs:
  e2e-test:
@@ -40,7 +40,8 @@ jobs:
        uses: actions/checkout@v4
        with:
          token: ${{ github.token }}
-          ref: ${{ github.event_name == 'pull_request' && github.head_ref || github.ref }}
+          repository: ${{ github.event_name == 'pull_request' && github.event.pull_request.head.repo.full_name || github.repository }}
+          ref: ${{ github.event_name == 'pull_request' && github.event.pull_request.head.sha || github.ref }}

      - name: Install dependencies
        uses: ./.github/actions/yarn-install
@@ -111,7 +112,7 @@ jobs:
        run: yarn docs:generate-paths

      - name: Commit artifacts to pull request branch
-        if: github.event_name == 'pull_request'
+        if: github.event_name == 'pull_request' && github.event.pull_request.head.repo.full_name == github.repository
        run: |
          git add packages/twenty-docs/docs.json packages/twenty-docs/navigation/navigation.template.json packages/twenty-shared/src/constants/DocumentationPaths.ts
          if git diff --staged --quiet --exit-code; then
@@ -149,4 +150,3 @@ jobs:
          fi
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-
@@ -25,8 +25,8 @@
 # Installation

 See:
-🚀 [Self-hosting](https://docs.twenty.com/developers/self-hosting/docker-compose)
-🖥️ [Local Setup](https://docs.twenty.com/developers/local-setup)
+🚀 [Self-hosting](https://docs.twenty.com/developers/self-host/capabilities/docker-compose)
+🖥️ [Local Setup](https://docs.twenty.com/developers/contribute/capabilities/local-setup)

 # Why Twenty

@@ -36,7 +36,7 @@ We built Twenty for three reasons:

 **A fresh start is required to build a better experience.** We can learn from past mistakes and craft a cohesive experience inspired by new UX patterns from tools like Notion, Airtable or Linear.

-**We believe in Open-source and community.** Hundreds of developers are already building Twenty together. Once we have plugin capabilities, a whole ecosystem will grow around it.
+**We believe in open-source and community.** Hundreds of developers are already building Twenty together. Once we have plugin capabilities, a whole ecosystem will grow around it.

 <br />

@@ -1,7 +1,7 @@
 {
  "private": true,
  "dependencies": {
-    "@apollo/client": "^3.7.17",
+    "@apollo/client": "^4.0.0",
    "@floating-ui/react": "^0.24.3",
    "@linaria/core": "^6.2.0",
    "@linaria/react": "^6.2.1",
@@ -25,47 +25,47 @@ See Twenty application documentation https://docs.twenty.com/developers/extend/c
 ## Prerequisites

 - Node.js 24+ (recommended) and Yarn 4
- A Twenty workspace and an API key (create one at https://app.twenty.com/settings/api-webhooks)
+- Docker (for the local Twenty dev server)

 ## Quick start

 ```bash
+# Scaffold a new app — the CLI will offer to start a local Twenty server
 npx create-twenty-app@latest my-twenty-app
 cd my-twenty-app

-# Get help and list all available commands
-yarn twenty help
+# The scaffolder can automatically:
+# 1. Start a local Twenty server (Docker)
+# 2. Open the browser to log in (tim@apple.dev / tim@apple.dev)
+# 3. Authenticate your app via OAuth

-# Authenticate using your API key (you'll be prompted)
-yarn twenty auth:login
-
-# Add a new entity to your application (guided)
-yarn twenty entity:add
+# Or do it manually:
+yarn twenty server start          # Start local Twenty server
+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 with the SDK — both available via `twenty-sdk/clients`)
-yarn twenty app:dev
+yarn twenty dev

 # Watch your application's function logs
-yarn twenty function:logs
+yarn twenty logs

 # Execute a function with a JSON payload
-yarn twenty function:execute -n my-function -p '{"key": "value"}'
+yarn twenty exec -n my-function -p '{"key": "value"}'

 # Execute the pre-install function
-yarn twenty function:execute --preInstall
+yarn twenty exec --preInstall

 # Execute the post-install function
-yarn twenty function:execute --postInstall
+yarn twenty exec --postInstall

 # Build the app for distribution
-yarn twenty app:build
+yarn twenty build

 # Publish the app to npm or directly to a Twenty server
-yarn twenty app:publish
+yarn twenty publish

 # Uninstall the application from the current workspace
-yarn twenty app:uninstall
+yarn twenty uninstall
 ```

 ## Scaffolding modes
@@ -107,13 +107,27 @@ npx create-twenty-app@latest my-app -m
 - `skills/example-skill.ts` — Example AI agent skill definition
 - `__tests__/app-install.integration-test.ts` — Integration test that builds, installs, and verifies the app (includes `vitest.config.ts`, `tsconfig.spec.json`, and a setup file)

+## Local server
+
+The scaffolder can start a local Twenty dev server for you (all-in-one Docker image with PostgreSQL, Redis, server, and worker). You can also manage it manually:
+
+```bash
+yarn twenty server start     # Start (pulls image if needed)
+yarn twenty server status    # Check if it's healthy
+yarn twenty server logs      # Stream logs
+yarn twenty server stop      # Stop (data is preserved)
+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`).
+
 ## Next steps

 - Run `yarn twenty help` to see all available commands.
- Use `yarn twenty auth:login` to authenticate with your Twenty workspace.
- Explore the generated project and add your first entity with `yarn twenty entity:add` (logic functions, front components, objects, roles, views, navigation menu items, skills).
- Use `yarn twenty app:dev` while you iterate — it watches, builds, and syncs changes to your workspace in real time.
- `CoreApiClient` (for workspace data via `/graphql`) is auto-generated by `yarn twenty app:dev`. `MetadataApiClient` (for workspace configuration and file uploads via `/metadata`) ships pre-built with the SDK. Both are available via `import { CoreApiClient, MetadataApiClient } from 'twenty-sdk/clients'`.
+- 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` (for workspace data via `/graphql`) 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, MetadataApiClient } from 'twenty-sdk/clients'`.

 ## Build and publish your application

@@ -121,19 +135,19 @@ Once your app is ready, build and publish it using the CLI:

 ```bash
 # Build the app (output goes to .twenty/output/)
-yarn twenty app:build
+yarn twenty build

 # Build and create a tarball (.tgz) for distribution
-yarn twenty app:build --tarball
+yarn twenty build --tarball

 # Publish to npm (requires npm login)
-yarn twenty app:publish
+yarn twenty publish

 # Publish with a dist-tag (e.g. beta, next)
-yarn twenty app:publish --tag beta
+yarn twenty publish --tag beta

-# Publish directly to a Twenty server (builds, uploads, and installs in one step)
-yarn twenty app:publish --server https://app.twenty.com
+# Deploy directly to a Twenty server (builds, uploads, and installs in one step)
+yarn twenty deploy
 ```

 ### Publish to the Twenty marketplace
@@ -153,8 +167,9 @@ Our team reviews contributions for quality, security, and reusability before mer

 ## Troubleshooting

- Auth prompts not appearing: run `yarn twenty auth:login` again and verify the API key permissions.
- Types not generated: ensure `yarn twenty app:dev` is running — it auto‑generates the typed client.
+- 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 --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.7.0",
+  "version": "0.8.0-canary.1",
  "description": "Command-line interface to create Twenty application",
  "main": "dist/cli.cjs",
  "bin": "dist/cli.cjs",
@@ -27,6 +27,10 @@ const program = new Command(packageJson.name)
    '--description <description>',
    'Application description (skips prompt)',
  )
+  .option(
+    '--skip-local-instance',
+    'Skip the local Twenty instance setup prompt',
+  )
  .helpOption('-h, --help', 'Display this help message.')
  .action(
    async (
@@ -37,6 +41,7 @@ const program = new Command(packageJson.name)
        name?: string;
        displayName?: string;
        description?: string;
+        skipLocalInstance?: boolean;
      },
    ) => {
      const modeFlags = [options?.exhaustive, options?.minimal].filter(Boolean);
@@ -72,6 +77,7 @@ const program = new Command(packageJson.name)
        name: options?.name,
        displayName: options?.displayName,
        description: options?.description,
+        skipLocalInstance: options?.skipLocalInstance,
      });
    },
  );
@@ -11,3 +11,4 @@

 - Creating an object without an index view associated. Unless this is a technical object, user will need to visualize it.
 - Creating a view without a navigationMenuItem associated. This will make the view available on the left sidebar.
+- Creating a front-end component that has a scroll instead of being responsive to its fixed widget height and width, unless it is specifically meant to be used in a canvas tab.
@@ -1,62 +1,11 @@
-This is a [Twenty](https://twenty.com) application project bootstrapped with [`create-twenty-app`](https://www.npmjs.com/package/create-twenty-app).
+This is a [Twenty](https://twenty.com) application bootstrapped with [`create-twenty-app`](https://www.npmjs.com/package/create-twenty-app).

 ## Getting Started

-First, authenticate to your workspace:
-
-```bash
-yarn twenty auth:login
-```
-
-Then, start development mode to sync your app and watch for changes:
-
-```bash
-yarn twenty app:dev
-```
-
-Open your Twenty instance and go to `/settings/applications` section to see the result.
-
-## Available Commands
-
-Run `yarn twenty help` to list all available commands. Common commands:
-
-```bash
-# Authentication
-yarn twenty auth:login     # Authenticate with Twenty
-yarn twenty auth:logout    # Remove credentials
-yarn twenty auth:status    # Check auth status
-yarn twenty auth:switch    # Switch default workspace
-yarn twenty auth:list      # List all configured workspaces
-
-# Application
-yarn twenty app:dev        # Start dev mode (watch, build, sync, and auto-generate typed client)
-yarn twenty entity:add     # Add a new entity (object, field, function, front-component, role, view, navigation-menu-item)
-yarn twenty function:logs  # Stream function logs
-yarn twenty function:execute  # Execute a function with JSON payload
-yarn twenty app:uninstall  # Uninstall app from workspace
-```
-
-## Integration Tests
-
-If your project includes the example integration test (`src/__tests__/app-install.integration-test.ts`), you can run it with:
-
-```bash
-# Make sure a Twenty server is running at http://localhost:3000
-yarn test
-```
-
-The test builds and installs the app, then verifies it appears in the applications list. Test configuration (API URL and API key) is defined in `vitest.config.ts`.
-
-## LLMs instructions
-
-Main docs and pitfalls are available in LLMS.md file.
+Run `yarn twenty help` to list all available commands.

 ## Learn More

-To learn more about Twenty applications, take a look at the following resources:
-
- [twenty-sdk](https://www.npmjs.com/package/twenty-sdk) - learn about `twenty-sdk` tool.
- [Twenty doc](https://docs.twenty.com/) - Twenty's documentation.
- Join our [Discord](https://discord.gg/cx5n4Jzs57)
-
-You can check out [the Twenty GitHub repository](https://github.com/twentyhq/twenty) - your feedback and contributions are welcome!
+- [Twenty Apps documentation](https://docs.twenty.com/developers/extend/capabilities/apps)
+- [twenty-sdk CLI reference](https://www.npmjs.com/package/twenty-sdk)
+- [Discord](https://discord.gg/cx5n4Jzs57)
@@ -1,11 +1,16 @@
 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 { isDefined } from 'twenty-shared/utils';

@@ -22,6 +27,7 @@ type CreateAppOptions = {
  name?: string;
  displayName?: string;
  description?: string;
+  skipLocalInstance?: boolean;
 };

 export class CreateAppCommand {
@@ -40,6 +46,7 @@ export class CreateAppCommand {

      await fs.ensureDir(appDirectory);

+      console.log(chalk.gray('  Scaffolding project files...'));
      await copyBaseApplicationProject({
        appName,
        appDisplayName,
@@ -48,11 +55,24 @@ export class CreateAppCommand {
        exampleOptions,
      });

+      console.log(chalk.gray('  Installing dependencies...'));
      await install(appDirectory);

+      console.log(chalk.gray('  Initializing git repository...'));
      await tryGitInit(appDirectory);

-      this.logSuccess(appDirectory);
+      let localResult: LocalInstanceResult = { running: false };
+
+      if (!options.skipLocalInstance) {
+        // Auto-detect a running server first
+        localResult = await setupLocalInstance(appDirectory);
+
+        if (localResult.running && localResult.serverUrl) {
+          await this.connectToLocal(appDirectory, localResult.serverUrl);
+        }
+      }
+
+      this.logSuccess(appDirectory, localResult);
    } catch (error) {
      console.error(
        chalk.red('Initialization failed:'),
@@ -173,22 +193,55 @@ export class CreateAppCommand {
    appDirectory: string;
    appName: string;
  }): void {
-    console.log(chalk.blue('🎯 Creating Twenty Application'));
-    console.log(chalk.gray(`📁 Directory: ${appDirectory}`));
-    console.log(chalk.gray(`📝 Name: ${appName}`));
+    console.log(chalk.blue('Creating Twenty Application'));
+    console.log(chalk.gray(`  Directory: ${appDirectory}`));
+    console.log(chalk.gray(`  Name: ${appName}`));
    console.log('');
  }

-  private logSuccess(appDirectory: string): void {
+  private async connectToLocal(
+    appDirectory: string,
+    serverUrl: string,
+  ): Promise<void> {
+    try {
+      execSync(
+        `npx nx run twenty-sdk:start -- remote add ${serverUrl} --as local`,
+        {
+          cwd: appDirectory,
+          stdio: 'inherit',
+        },
+      );
+      console.log(chalk.green('Authenticated with local Twenty instance.'));
+    } catch {
+      console.log(
+        chalk.yellow(
+          'Authentication skipped. Run `npx nx run twenty-sdk:start -- remote add --local` manually.',
+        ),
+      );
+    }
+  }
+
+  private logSuccess(
+    appDirectory: string,
+    localResult: LocalInstanceResult,
+  ): void {
    const dirName = appDirectory.split('/').reverse()[0] ?? '';

-    console.log(chalk.green('✅ Application created!'));
+    console.log(chalk.green('Application created!'));
    console.log('');
    console.log(chalk.blue('Next steps:'));
    console.log(chalk.gray(`  cd ${dirName}`));
+
+    if (!localResult.running) {
+      console.log(
+        chalk.gray(
+          '  yarn twenty remote add --local  # Authenticate with Twenty',
+        ),
+      );
+    }
+
    console.log(
-      chalk.gray('  yarn twenty auth:login  # Authenticate with Twenty'),
+      chalk.gray('  yarn twenty dev                  # Start dev mode'),
    );
-    console.log(chalk.gray('  yarn twenty app:dev     # Start dev mode'));
  }
 }
@@ -103,7 +103,6 @@ describe('scaffoldIntegrationTest', () => {

      expect(content).toContain('TWENTY_API_KEY');
      expect(content).not.toContain('TWENTY_TEST_API_KEY');
-      expect(content).toContain('TWENTY_API_URL');
      expect(content).toContain('setup-test.ts');
      expect(content).toContain('tsconfig.spec.json');
      expect(content).toContain('integration-test.ts');
@@ -474,7 +474,7 @@ const createExampleNavigationMenuItem = async ({
  const universalIdentifier = v4();

  const content = `import { defineNavigationMenuItem } from 'twenty-sdk';
-  import { EXAMPLE_VIEW_UNIVERSAL_IDENTIFIER } from 'src/views/example-view';
+import { EXAMPLE_VIEW_UNIVERSAL_IDENTIFIER } from 'src/views/example-view';

 export default defineNavigationMenuItem({
  universalIdentifier: '${universalIdentifier}',
@@ -482,6 +482,7 @@ export default defineNavigationMenuItem({
  icon: 'IconList',
  color: 'blue',
  position: 0,
+  type: 'VIEW',
  viewUniversalIdentifier: EXAMPLE_VIEW_UNIVERSAL_IDENTIFIER,
 });
 `;
@@ -609,8 +610,9 @@ const createPackageJson = async ({
  const devDependencies: Record<string, string> = {
    typescript: '^5.9.3',
    '@types/node': '^24.7.2',
-    '@types/react': '^18.2.0',
-    react: '^18.2.0',
+    '@types/react': '^19.0.0',
+    react: '^19.0.0',
+    'react-dom': '^19.0.0',
    oxlint: '^0.16.0',
    'twenty-sdk': createTwentyAppPackageJson.version,
  };
@@ -0,0 +1,101 @@
+import chalk from 'chalk';
+import { execSync } from 'node:child_process';
+import { platform } from 'node:os';
+
+const DEFAULT_PORT = 2020;
+
+// 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);
+  }
+};
+
+export type LocalInstanceResult = {
+  running: boolean;
+  serverUrl?: string;
+};
+
+export const setupLocalInstance = async (
+  appDirectory: string,
+): Promise<LocalInstanceResult> => {
+  console.log('');
+  console.log(chalk.blue('Setting up local Twenty instance...'));
+
+  if (await isServerReady(DEFAULT_PORT)) {
+    const serverUrl = `http://localhost:${DEFAULT_PORT}`;
+
+    console.log(chalk.green(`Twenty server detected on ${serverUrl}.`));
+
+    return { running: true, serverUrl };
+  }
+
+  // Delegate to `twenty server start` from the scaffolded app
+  console.log(chalk.gray('Starting local Twenty server...'));
+
+  try {
+    execSync('yarn twenty server start', {
+      cwd: appDirectory,
+      stdio: 'inherit',
+    });
+  } catch {
+    console.log(
+      chalk.yellow(
+        'Failed to start Twenty server. Run `yarn twenty server start` manually.',
+      ),
+    );
+
+    return { running: false };
+  }
+
+  console.log(chalk.gray('Waiting for Twenty to be ready...'));
+
+  const startTime = Date.now();
+  const timeoutMs = 180 * 1000;
+
+  while (Date.now() - startTime < timeoutMs) {
+    if (await isServerReady(DEFAULT_PORT)) {
+      const serverUrl = `http://localhost:${DEFAULT_PORT}`;
+
+      console.log(chalk.green(`Twenty server is running on ${serverUrl}.`));
+      console.log(
+        chalk.gray(
+          'Workspace ready — login with tim@apple.dev / tim@apple.dev',
+        ),
+      );
+
+      const openCommand = platform() === 'darwin' ? 'open' : 'xdg-open';
+
+      try {
+        execSync(`${openCommand} ${serverUrl}`, { stdio: 'ignore' });
+      } catch {
+        // Ignore if browser can't be opened
+      }
+
+      return { running: true, serverUrl };
+    }
+
+    await new Promise((resolve) => setTimeout(resolve, 2000));
+  }
+
+  console.log(
+    chalk.yellow(
+      'Twenty server did not become healthy in time. Check: yarn twenty server logs',
+    ),
+  );
+
+  return { running: false };
+};
@@ -45,7 +45,6 @@ export default defineConfig({
    include: ['src/**/*.integration-test.ts'],
    setupFiles: ['src/__tests__/setup-test.ts'],
    env: {
-      TWENTY_API_URL: 'http://localhost:3000',
      TWENTY_API_KEY:
        '${SEED_API_KEY}',
    },
@@ -94,7 +93,7 @@ import * as os from 'os';
 import * as path from 'path';
 import { beforeAll } from 'vitest';

-const TWENTY_API_URL = process.env.TWENTY_API_URL ?? 'http://localhost:3000';
+const TWENTY_API_URL = process.env.TWENTY_API_URL ?? 'http://localhost:2020';
 const TEST_CONFIG_DIR = path.join(os.tmpdir(), '.twenty-sdk-test');

 const assertServerIsReachable = async () => {
@@ -120,12 +119,13 @@ beforeAll(async () => {
  fs.mkdirSync(TEST_CONFIG_DIR, { recursive: true });

  const configFile = {
-    profiles: {
-      default: {
+    remotes: {
+      local: {
        apiUrl: process.env.TWENTY_API_URL,
        apiKey: process.env.TWENTY_API_KEY,
      },
    },
+    defaultRemote: 'local',
  };

  fs.writeFileSync(
@@ -30,7 +30,7 @@ type AnalysisResult = {
  commitments: Commitment[];
 };

-type RichTextV2Data = {
+type RichTextData = {
  markdown: string;
  blocknote: null;
 };
@@ -123,7 +123,7 @@ const createNoteInTwenty = async (
    bodyV2: {
      markdown: noteBodyMarkdown,
      blocknote: null,
-    } satisfies RichTextV2Data,
+    } satisfies RichTextData,
  };

  try {
@@ -159,7 +159,7 @@ const createTaskInTwenty = async (

  const taskData: {
    title: string;
-    bodyV2: RichTextV2Data;
+    bodyV2: RichTextData;
    dueAt?: string;
  } = {
    title: actionItem.title,
@@ -10,3 +10,4 @@

 - Creating an object without an index view associated. Unless this is a technical object, user will need to visualize it.
 - Creating a view without a navigationMenuItem associated. This will make the view available on the left sidebar.
+- Creating a front-end component that has a scroll instead of being responsive to its fixed widget height and width, unless it is specifically meant to be used in a canvas tab.
@@ -5,13 +5,13 @@ This is a [Twenty](https://twenty.com) application project bootstrapped with [`c
 First, authenticate to your workspace:

 ```bash
-yarn twenty auth:login
+yarn twenty remote add --local
 ```

 Then, start development mode to sync your app and watch for changes:

 ```bash
-yarn twenty app:dev
+yarn twenty dev
 ```

 Open your Twenty instance and go to `/settings/applications` section to see the result.
@@ -21,19 +21,19 @@ Open your Twenty instance and go to `/settings/applications` section to see the
 Run `yarn twenty help` to list all available commands. Common commands:

 ```bash
-# Authentication
-yarn twenty auth:login     # Authenticate with Twenty
-yarn twenty auth:logout    # Remove credentials
-yarn twenty auth:status    # Check auth status
-yarn twenty auth:switch    # Switch default workspace
-yarn twenty auth:list      # List all configured workspaces
+# Remotes & Authentication
+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
+yarn twenty remote remove <name>  # Remove a remote

 # Application
-yarn twenty app:dev        # Start dev mode (watch, build, sync, and auto-generate typed client)
-yarn twenty entity:add     # Add a new entity (object, field, function, front-component, role, view, navigation-menu-item)
-yarn twenty function:logs  # Stream function logs
-yarn twenty function:execute  # Execute a function with JSON payload
-yarn twenty app:uninstall  # Uninstall app from workspace
+yarn twenty dev        # Start dev mode (watch, build, sync, and auto-generate typed client)
+yarn twenty add     # Add a new entity (object, field, function, front-component, role, view, navigation-menu-item)
+yarn twenty logs  # Stream function logs
+yarn twenty exec  # Execute a function with JSON payload
+yarn twenty uninstall  # Uninstall app from workspace
 ```

 ## LLMs instructions
@@ -32,7 +32,7 @@ type AnalysisResult = {
  commitments: Commitment[];
 };

-type RichTextV2Data = {
+type RichTextData = {
  markdown: string;
  blocknote: null;
 };
@@ -362,7 +362,7 @@ const createNoteInTwenty = async (
    bodyV2: {
      markdown: noteBodyMarkdown,
      blocknote: null,
-    } satisfies RichTextV2Data,
+    } satisfies RichTextData,
  };

  try {
@@ -451,7 +451,7 @@ const createTaskInTwenty = async (

  const taskData: {
    title: string;
-    bodyV2: RichTextV2Data;
+    bodyV2: RichTextData;
    dueAt?: string;
    assigneeId?: string;
  } = {
@@ -9,9 +9,9 @@
  },
  "packageManager": "yarn@4.9.2",
  "scripts": {
-    "app:dev": "twenty app:dev",
-    "function:execute": "twenty function:execute",
-    "app:uninstall": "twenty app:uninstall",
+    "dev": "twenty dev",
+    "exec": "twenty exec",
+    "uninstall": "twenty uninstall",
    "lint": "oxlint -c .oxlintrc.json .",
    "lint:fix": "oxlint --fix -c .oxlintrc.json ."
  },
@@ -9,16 +9,16 @@
  },
  "packageManager": "yarn@4.9.2",
  "scripts": {
-    "auth:login": "twenty auth:login",
-    "auth:logout": "twenty auth:logout",
-    "auth:status": "twenty auth:status",
-    "auth:switch": "twenty auth:switch",
-    "auth:list": "twenty auth:list",
-    "app:dev": "twenty app:dev",
-    "entity:add": "twenty entity:add",
-    "function:logs": "twenty function:logs",
-    "function:execute": "twenty function:execute",
-    "app:uninstall": "twenty app:uninstall",
+    "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 ."
@@ -9,16 +9,16 @@
  },
  "packageManager": "yarn@4.9.2",
  "scripts": {
-    "auth:login": "twenty auth:login",
-    "auth:logout": "twenty auth:logout",
-    "auth:status": "twenty auth:status",
-    "auth:switch": "twenty auth:switch",
-    "auth:list": "twenty auth:list",
-    "app:dev": "twenty app:dev",
-    "entity:add": "twenty entity:add",
-    "function:logs": "twenty function:logs",
-    "function:execute": "twenty function:execute",
-    "app:uninstall": "twenty app:uninstall",
+    "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 ."
@@ -9,16 +9,16 @@
  },
  "packageManager": "yarn@4.9.2",
  "scripts": {
-    "auth:login": "twenty auth:login",
-    "auth:logout": "twenty auth:logout",
-    "auth:status": "twenty auth:status",
-    "auth:switch": "twenty auth:switch",
-    "auth:list": "twenty auth:list",
-    "app:dev": "twenty app:dev",
-    "entity:add": "twenty entity:add",
-    "function:logs": "twenty function:logs",
-    "function:execute": "twenty function:execute",
-    "app:uninstall": "twenty app:uninstall",
+    "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 ."
@@ -1,8 +1,10 @@
 import { defineNavigationMenuItem } from 'twenty-sdk';
-import { ALL_POST_CARD_RECIPIENTS_VIEW_ID } from '../views/all-post-card-recipients.view';
+import { NavigationMenuItemType } from 'twenty-shared/types';
+import { POST_CARD_RECIPIENT_UNIVERSAL_IDENTIFIER } from '../objects/post-card-recipient.object';

 export default defineNavigationMenuItem({
  universalIdentifier: 'c1a2b3c4-0003-4a7b-8c9d-0e1f2a3b4c5d',
  position: 2,
-  viewUniversalIdentifier: ALL_POST_CARD_RECIPIENTS_VIEW_ID,
+  type: NavigationMenuItemType.OBJECT,
+  targetObjectUniversalIdentifier: POST_CARD_RECIPIENT_UNIVERSAL_IDENTIFIER,
 });
@@ -1,8 +1,10 @@
 import { defineNavigationMenuItem } from 'twenty-sdk';
-import { ALL_POST_CARDS_VIEW_ID } from '../views/all-post-cards.view';
+import { NavigationMenuItemType } from 'twenty-shared/types';
+import { POST_CARD_UNIVERSAL_IDENTIFIER } from '../objects/post-card.object';

 export default defineNavigationMenuItem({
  universalIdentifier: 'c1a2b3c4-0001-4a7b-8c9d-0e1f2a3b4c5d',
  position: 0,
-  viewUniversalIdentifier: ALL_POST_CARDS_VIEW_ID,
+  type: NavigationMenuItemType.OBJECT,
+  targetObjectUniversalIdentifier: POST_CARD_UNIVERSAL_IDENTIFIER,
 });
@@ -1,8 +1,10 @@
 import { defineNavigationMenuItem } from 'twenty-sdk';
-import { ALL_RECIPIENTS_VIEW_ID } from '../views/all-recipients.view';
+import { NavigationMenuItemType } from 'twenty-shared/types';
+import { RECIPIENT_UNIVERSAL_IDENTIFIER } from '../objects/recipient.object';

 export default defineNavigationMenuItem({
  universalIdentifier: 'c1a2b3c4-0002-4a7b-8c9d-0e1f2a3b4c5d',
  position: 1,
-  viewUniversalIdentifier: ALL_RECIPIENTS_VIEW_ID,
+  type: NavigationMenuItemType.OBJECT,
+  targetObjectUniversalIdentifier: RECIPIENT_UNIVERSAL_IDENTIFIER,
 });
@@ -10,3 +10,4 @@

 - Creating an object without an index view associated. Unless this is a technical object, user will need to visualize it.
 - Creating a view without a navigationMenuItem associated. This will make the view available on the left sidebar.
+- Creating a front-end component that has a scroll instead of being responsive to its fixed widget height and width, unless it is specifically meant to be used in a canvas tab.
@@ -5,13 +5,13 @@ This is a [Twenty](https://twenty.com) application project bootstrapped with [`c
 First, authenticate to your workspace:

 ```bash
-yarn twenty auth:login
+yarn twenty remote add --local
 ```

 Then, start development mode to sync your app and watch for changes:

 ```bash
-yarn twenty app:dev
+yarn twenty dev
 ```

 Open your Twenty instance and go to `/settings/applications` section to see the result.
@@ -21,19 +21,19 @@ Open your Twenty instance and go to `/settings/applications` section to see the
 Run `yarn twenty help` to list all available commands. Common commands:

 ```bash
-# Authentication
-yarn twenty auth:login     # Authenticate with Twenty
-yarn twenty auth:logout    # Remove credentials
-yarn twenty auth:status    # Check auth status
-yarn twenty auth:switch    # Switch default workspace
-yarn twenty auth:list      # List all configured workspaces
+# Remotes & Authentication
+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
+yarn twenty remote remove <name>  # Remove a remote

 # Application
-yarn twenty app:dev        # Start dev mode (watch, build, sync, and auto-generate typed client)
-yarn twenty entity:add     # Add a new entity (object, field, function, front-component, role, view, navigation-menu-item)
-yarn twenty function:logs  # Stream function logs
-yarn twenty function:execute  # Execute a function with JSON payload
-yarn twenty app:uninstall  # Uninstall app from workspace
+yarn twenty dev        # Start dev mode (watch, build, sync, and auto-generate typed client)
+yarn twenty add     # Add a new entity (object, field, function, front-component, role, view, navigation-menu-item)
+yarn twenty logs  # Stream function logs
+yarn twenty exec  # Execute a function with JSON payload
+yarn twenty uninstall  # Uninstall app from workspace
 ```

 ## Integration Tests
@@ -29,12 +29,13 @@ beforeAll(async () => {
  fs.mkdirSync(TEST_CONFIG_DIR, { recursive: true });

  const configFile = {
-    profiles: {
-      default: {
+    remotes: {
+      local: {
        apiUrl: process.env.TWENTY_API_URL,
        apiKey: process.env.TWENTY_API_KEY,
      },
    },
+    defaultRemote: 'local',
  };

  fs.writeFileSync(
@@ -1,5 +1,6 @@
 import { defineNavigationMenuItem } from 'twenty-sdk';
-  import { EXAMPLE_VIEW_UNIVERSAL_IDENTIFIER } from 'src/views/example-view';
+import { NavigationMenuItemType } from 'twenty-shared/types';
+import { EXAMPLE_VIEW_UNIVERSAL_IDENTIFIER } from 'src/views/example-view';

 export default defineNavigationMenuItem({
  universalIdentifier: '10f90627-e9c2-44b7-9742-bed77e3d1b17',
@@ -7,5 +8,6 @@ export default defineNavigationMenuItem({
  icon: 'IconList',
  color: 'blue',
  position: 0,
+  type: NavigationMenuItemType.VIEW,
  viewUniversalIdentifier: EXAMPLE_VIEW_UNIVERSAL_IDENTIFIER,
 });
@@ -7,3 +7,4 @@

 - Creating an object without an index view associated. Unless this is a technical object, user will need to visualize it.
 - Creating a view without a navigationMenuItem associated. This will make the view available on the left sidebar.
+- Creating a front-end component that has a scroll instead of being responsive to its fixed widget height and width, unless it is specifically meant to be used in a canvas tab.
@@ -5,13 +5,13 @@ This is a [Twenty](https://twenty.com) application project bootstrapped with [`c
 First, authenticate to your workspace:

 ```bash
-yarn twenty auth:login
+yarn twenty remote add --local
 ```

 Then, start development mode to sync your app and watch for changes:

 ```bash
-yarn twenty app:dev
+yarn twenty dev
 ```

 Open your Twenty instance and go to `/settings/applications` section to see the result.
@@ -21,19 +21,19 @@ Open your Twenty instance and go to `/settings/applications` section to see the
 Run `yarn twenty help` to list all available commands. Common commands:

 ```bash
-# Authentication
-yarn twenty auth:login     # Authenticate with Twenty
-yarn twenty auth:logout    # Remove credentials
-yarn twenty auth:status    # Check auth status
-yarn twenty auth:switch    # Switch default workspace
-yarn twenty auth:list      # List all configured workspaces
+# Remotes & Authentication
+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
+yarn twenty remote remove <name>  # Remove a remote

 # Application
-yarn twenty app:dev        # Start dev mode (watch, build, sync, and auto-generate typed client)
-yarn twenty entity:add     # Add a new entity (object, field, function, front-component, role, view, navigation-menu-item)
-yarn twenty function:logs  # Stream function logs
-yarn twenty function:execute  # Execute a function with JSON payload
-yarn twenty app:uninstall  # Uninstall app from workspace
+yarn twenty dev        # Start dev mode (watch, build, sync, and auto-generate typed client)
+yarn twenty add     # Add a new entity (object, field, function, front-component, role, view, navigation-menu-item)
+yarn twenty logs  # Stream function logs
+yarn twenty exec  # Execute a function with JSON payload
+yarn twenty uninstall  # Uninstall app from workspace
 ```

 ## LLMs instructions
@@ -236,7 +236,7 @@ const handler = async (event: any) => {
    },
  });

-  // TODO: remove `as any` after running `yarn twenty app:dev` to regenerate the typed client
+  // TODO: remove `as any` after running `yarn twenty dev` to regenerate the typed client
  const updateSummary = async (markdown: string) => {
    await client.mutation({
      updateCallRecording: {
@@ -1,10 +1,12 @@
 import { CALL_RECORDING_VIEW_UNIVERSAL_IDENTIFIER } from 'src/views/call-recording-view';
 import { defineNavigationMenuItem } from 'twenty-sdk';
+import { NavigationMenuItemType } from 'twenty-shared/types';

 export default defineNavigationMenuItem({
  universalIdentifier: '5248a62d-7d2e-43a7-ba45-6e8f61876a71',
  name: 'Call recordings',
  icon: 'IconPhone',
  position: 0,
+  type: NavigationMenuItemType.VIEW,
  viewUniversalIdentifier: CALL_RECORDING_VIEW_UNIVERSAL_IDENTIFIER,
 });
@@ -81,7 +81,7 @@ export default defineObject({
    },
    {
      universalIdentifier: TRANSCRIPT_FIELD_UNIVERSAL_IDENTIFIER,
-      type: FieldType.RICH_TEXT_V2,
+      type: FieldType.RICH_TEXT,
      name: 'transcript',
      label: 'Transcript',
      description: 'Human-readable transcript of the call',
@@ -114,7 +114,7 @@ export default defineObject({
    },
    {
      universalIdentifier: SUMMARY_FIELD_UNIVERSAL_IDENTIFIER,
-      type: FieldType.RICH_TEXT_V2,
+      type: FieldType.RICH_TEXT,
      name: 'summary',
      label: 'Summary',
      description: 'AI-generated summary of the call',
@@ -16,7 +16,7 @@ Use this skill when a user asks you to summarize, analyze, or extract insights f

 ## How to Access the Data
 1. Use \`find_one_callRecording\` to fetch the call recording by its ID.
-2. Read the \`transcript\` field (RICH_TEXT_V2, markdown format) which contains the full conversation.
+2. Read the \`transcript\` field (RICH_TEXT, markdown format) which contains the full conversation.
 3. The transcript uses the format: **Speaker Name:** spoken text

 ## What to Produce
@@ -1,4 +1,5 @@
 import { defineNavigationMenuItem } from 'twenty-sdk';
+import { NavigationMenuItemType } from 'twenty-shared/types';
 import { UNIVERSAL_IDENTIFIERS } from 'src/constants/universal-identifiers.constant';

 export default defineNavigationMenuItem({
@@ -6,6 +7,7 @@ export default defineNavigationMenuItem({
  name: 'Self host user',
  icon: 'IconList',
  position: 1,
+  type: NavigationMenuItemType.VIEW,
  viewUniversalIdentifier:
    UNIVERSAL_IDENTIFIERS.views.selfHostingUserView.universalIdentifier,
 });
@@ -38,7 +38,6 @@ services:

      # EMAIL_FROM_ADDRESS: ${EMAIL_FROM_ADDRESS:-contact@yourdomain.com}
      # EMAIL_FROM_NAME: ${EMAIL_FROM_NAME:-"John from YourDomain"}
-      # EMAIL_SYSTEM_ADDRESS: ${EMAIL_SYSTEM_ADDRESS:-system@yourdomain.com}
      # EMAIL_DRIVER: ${EMAIL_DRIVER:-smtp}
      # EMAIL_SMTP_HOST: ${EMAIL_SMTP_HOST:-smtp.gmail.com}
      # EMAIL_SMTP_PORT: ${EMAIL_SMTP_PORT:-465}
@@ -92,7 +91,6 @@ services:

      # EMAIL_FROM_ADDRESS: ${EMAIL_FROM_ADDRESS:-contact@yourdomain.com}
      # EMAIL_FROM_NAME: ${EMAIL_FROM_NAME:-"John from YourDomain"}
-      # EMAIL_SYSTEM_ADDRESS: ${EMAIL_SYSTEM_ADDRESS:-system@yourdomain.com}
      # EMAIL_DRIVER: ${EMAIL_DRIVER:-smtp}
      # EMAIL_SMTP_HOST: ${EMAIL_SMTP_HOST:-smtp.gmail.com}
      # EMAIL_SMTP_PORT: ${EMAIL_SMTP_PORT:-465}
@@ -61,7 +61,6 @@
            "EMAIL_SMTP_NO_TLS": { "type": "boolean" },
            "EMAIL_FROM_ADDRESS": { "type": "string" },
            "EMAIL_FROM_NAME": { "type": "string" },
-            "EMAIL_SYSTEM_ADDRESS": { "type": "string" },
            "IS_EMAIL_VERIFICATION_REQUIRED": { "type": "boolean" },
            "EMAIL_VERIFICATION_TOKEN_EXPIRES_IN": { "type": "string" },
            "PASSWORD_RESET_TOKEN_EXPIRES_IN": { "type": "string" }
@@ -0,0 +1,130 @@
+ARG APP_VERSION
+
+# === Stage 1: Common dependencies ===
+FROM node:22-alpine AS common-deps
+
+WORKDIR /app
+
+COPY ./package.json ./yarn.lock ./.yarnrc.yml ./tsconfig.base.json ./nx.json /app/
+COPY ./.yarn/releases /app/.yarn/releases
+COPY ./.yarn/patches /app/.yarn/patches
+
+COPY ./packages/twenty-emails/package.json /app/packages/twenty-emails/
+COPY ./packages/twenty-server/package.json /app/packages/twenty-server/
+COPY ./packages/twenty-server/patches /app/packages/twenty-server/patches
+COPY ./packages/twenty-ui/package.json /app/packages/twenty-ui/
+COPY ./packages/twenty-shared/package.json /app/packages/twenty-shared/
+COPY ./packages/twenty-front/package.json /app/packages/twenty-front/
+COPY ./packages/twenty-sdk/package.json /app/packages/twenty-sdk/
+
+RUN yarn && yarn cache clean && npx nx reset
+
+# === Stage 2: Build server from source ===
+FROM common-deps AS twenty-server-build
+
+COPY ./packages/twenty-emails /app/packages/twenty-emails
+COPY ./packages/twenty-shared /app/packages/twenty-shared
+COPY ./packages/twenty-ui /app/packages/twenty-ui
+COPY ./packages/twenty-sdk /app/packages/twenty-sdk
+COPY ./packages/twenty-server /app/packages/twenty-server
+
+RUN npx nx run twenty-server:build
+RUN yarn workspaces focus --production twenty-emails twenty-shared twenty-sdk twenty-server
+
+# === Stage 3: Build frontend from source ===
+# Requires ~10GB Docker memory. To skip, pre-build on host first:
+#   npx nx build twenty-front
+# The COPY below will pick up packages/twenty-front/build/ if it exists.
+FROM common-deps AS twenty-front-build
+COPY --from=twenty-server-build /app/package.json /tmp/.build-sentinel
+
+COPY ./packages/twenty-front /app/packages/twenty-front
+COPY ./packages/twenty-ui /app/packages/twenty-ui
+COPY ./packages/twenty-shared /app/packages/twenty-shared
+COPY ./packages/twenty-sdk /app/packages/twenty-sdk
+RUN if [ -d /app/packages/twenty-front/build ]; then \
+      echo "Using pre-built frontend from host"; \
+    else \
+      NODE_OPTIONS="--max-old-space-size=8192" npx nx build twenty-front; \
+    fi
+
+# === Stage 4: s6-overlay ===
+FROM alpine:3.20 AS s6-fetch
+ARG S6_OVERLAY_VERSION=3.2.0.2
+ARG TARGETARCH
+RUN if [ "$TARGETARCH" = "arm64" ]; then echo "aarch64" > /tmp/s6arch; \
+    else echo "x86_64" > /tmp/s6arch; fi
+RUN S6_ARCH=$(cat /tmp/s6arch) && \
+    wget -O /tmp/s6-overlay-noarch.tar.xz \
+      "https://github.com/just-containers/s6-overlay/releases/download/v${S6_OVERLAY_VERSION}/s6-overlay-noarch.tar.xz" && \
+    wget -O /tmp/s6-overlay-noarch.tar.xz.sha256 \
+      "https://github.com/just-containers/s6-overlay/releases/download/v${S6_OVERLAY_VERSION}/s6-overlay-noarch.tar.xz.sha256" && \
+    wget -O /tmp/s6-overlay-arch.tar.xz \
+      "https://github.com/just-containers/s6-overlay/releases/download/v${S6_OVERLAY_VERSION}/s6-overlay-${S6_ARCH}.tar.xz" && \
+    wget -O /tmp/s6-overlay-arch.tar.xz.sha256 \
+      "https://github.com/just-containers/s6-overlay/releases/download/v${S6_OVERLAY_VERSION}/s6-overlay-${S6_ARCH}.tar.xz.sha256" && \
+    cd /tmp && \
+    NOARCH_SUM=$(awk '{print $1}' s6-overlay-noarch.tar.xz.sha256) && \
+    ARCH_SUM=$(awk '{print $1}' s6-overlay-arch.tar.xz.sha256) && \
+    echo "$NOARCH_SUM  s6-overlay-noarch.tar.xz" | sha256sum -c - && \
+    echo "$ARCH_SUM  s6-overlay-arch.tar.xz" | sha256sum -c -
+
+# === Stage 5: Final all-in-one image ===
+FROM node:22-alpine
+
+# s6-overlay
+COPY --from=s6-fetch /tmp/s6-overlay-noarch.tar.xz /tmp/
+COPY --from=s6-fetch /tmp/s6-overlay-arch.tar.xz /tmp/
+RUN tar -C / -Jxpf /tmp/s6-overlay-noarch.tar.xz \
+ && tar -C / -Jxpf /tmp/s6-overlay-arch.tar.xz \
+ && rm /tmp/s6-overlay-*.tar.xz
+
+# Infrastructure: Postgres, Redis, and utilities
+RUN apk add --no-cache \
+    postgresql16 postgresql16-contrib \
+    redis \
+    curl jq su-exec
+
+# tsx for database setup scripts
+RUN npm install -g tsx
+
+# Twenty application (both server and frontend built from source)
+COPY --from=twenty-server-build /app /app
+COPY --from=twenty-front-build /app/packages/twenty-front/build /app/packages/twenty-server/dist/front
+
+# s6 service definitions
+COPY packages/twenty-docker/twenty-app-dev/rootfs/ /
+
+# Data directories
+RUN mkdir -p /data/postgres /data/redis /app/.local-storage \
+ && chown -R postgres:postgres /data/postgres \
+ && chown 1000:1000 /data/redis /app/.local-storage
+
+ARG REACT_APP_SERVER_BASE_URL
+ARG APP_VERSION=0.0.0
+
+# Tell s6-overlay to preserve container environment variables
+ENV S6_KEEP_ENV=1
+
+# Environment defaults
+ENV PG_DATABASE_URL=postgres://twenty:twenty@localhost:5432/default \
+    SERVER_URL=http://localhost:2020 \
+    REDIS_URL=redis://localhost:6379 \
+    STORAGE_TYPE=local \
+    APP_SECRET=twenty-app-dev-secret-not-for-production \
+    REACT_APP_SERVER_BASE_URL=$REACT_APP_SERVER_BASE_URL \
+    APP_VERSION=$APP_VERSION \
+    NODE_ENV=development \
+    NODE_PORT=3000 \
+    DISABLE_DB_MIGRATIONS=true \
+    DISABLE_CRON_JOBS_REGISTRATION=true \
+    IS_BILLING_ENABLED=false \
+    SIGN_IN_PREFILLED=true
+
+EXPOSE 3000
+VOLUME ["/data/postgres", "/app/.local-storage"]
+
+LABEL org.opencontainers.image.source=https://github.com/twentyhq/twenty
+LABEL org.opencontainers.image.description="All-in-one Twenty image for local development and SDK usage. Includes PostgreSQL, Redis, server, and worker."
+
+ENTRYPOINT ["/init"]
@@ -0,0 +1 @@
+oneshot
@@ -0,0 +1 @@
+/bin/sh /etc/s6-overlay/scripts/init-db.sh
@@ -0,0 +1,13 @@
+#!/bin/sh
+# Initialize PostgreSQL data directory if empty
+if [ ! -f /data/postgres/PG_VERSION ]; then
+  echo "Initializing PostgreSQL data directory..."
+  su-exec postgres initdb -D /data/postgres --auth=trust --encoding=UTF8
+  # Allow local connections without password
+  echo "host all all 127.0.0.1/32 trust" >> /data/postgres/pg_hba.conf
+  echo "host all all ::1/128 trust" >> /data/postgres/pg_hba.conf
+fi
+
+exec su-exec postgres postgres -D /data/postgres \
+  -c listen_addresses=localhost \
+  -c unix_socket_directories=/tmp
@@ -0,0 +1 @@
+longrun
@@ -0,0 +1,6 @@
+#!/bin/sh
+exec redis-server \
+  --dir /data/redis \
+  --maxmemory-policy noeviction \
+  --bind 127.0.0.1 \
+  --protected-mode yes
@@ -0,0 +1 @@
+longrun
@@ -0,0 +1,3 @@
+#!/bin/sh
+cd /app/packages/twenty-server
+exec yarn start:prod
@@ -0,0 +1 @@
+longrun
@@ -0,0 +1,3 @@
+#!/bin/sh
+cd /app/packages/twenty-server
+exec yarn worker:prod
@@ -0,0 +1 @@
+longrun
@@ -0,0 +1,56 @@
+#!/bin/sh
+set -e
+
+# Wait for PostgreSQL to be ready (timeout after 60s)
+echo "Waiting for PostgreSQL..."
+TRIES=0
+until su-exec postgres pg_isready -h localhost; do
+  TRIES=$((TRIES + 1))
+  if [ "$TRIES" -ge 120 ]; then
+    echo "ERROR: PostgreSQL did not become ready within 60s"
+    exit 1
+  fi
+  sleep 0.5
+done
+echo "PostgreSQL is ready."
+
+# Create role if it doesn't exist
+su-exec postgres psql -h localhost -tc \
+  "SELECT 1 FROM pg_roles WHERE rolname='twenty'" | grep -q 1 \
+  || su-exec postgres psql -h localhost -c "CREATE ROLE twenty WITH LOGIN PASSWORD 'twenty' SUPERUSER"
+
+# Create database if it doesn't exist
+su-exec postgres psql -h localhost -tc \
+  "SELECT 1 FROM pg_database WHERE datname='default'" | grep -q 1 \
+  || su-exec postgres createdb -h localhost -O twenty default
+
+# Run Twenty database setup and migrations
+cd /app/packages/twenty-server
+
+has_schema=$(PGPASSWORD=twenty psql -h localhost -U twenty -d default -tAc \
+  "SELECT EXISTS (SELECT 1 FROM information_schema.schemata WHERE schema_name = 'core')")
+
+if [ "$has_schema" = "f" ]; then
+  echo "Database appears to be empty, running initial setup..."
+  NODE_OPTIONS="--max-old-space-size=1500" tsx ./scripts/setup-db.ts
+fi
+
+# Always run migrations (idempotent — skips already-applied ones)
+yarn database:migrate:prod
+
+yarn command:prod cache:flush
+yarn command:prod upgrade
+yarn command:prod cache:flush
+
+# Only seed on first boot — check if the dev workspace already exists
+has_workspace=$(PGPASSWORD=twenty psql -h localhost -U twenty -d default -tAc \
+  "SELECT EXISTS (SELECT 1 FROM core.workspace WHERE id = '20202020-1c25-4d02-bf25-6aeccf7ea419')")
+
+if [ "$has_workspace" = "f" ]; then
+  echo "Seeding app dev data..."
+  yarn command:prod workspace:seed:dev --light || true
+else
+  echo "Dev workspace already seeded, skipping."
+fi
+
+echo "Database initialization complete."
@@ -9,7 +9,7 @@ The goal here is to have a consistent codebase, which is easy to read and easy t

 For this, it's better to be a bit more verbose than to be too concise.

-Always keep in mind that people read code more often than they write it, specially on an open source project, where anyone can contribute.
+Always keep in mind that people read code more often than they write it, especially on an open source project, where anyone can contribute.

 There are a lot of rules that are not defined here, but that are automatically checked by linters.

@@ -150,7 +150,7 @@ type MyType = {

 ### Use string literals instead of enums

-[String literals](https://www.typescriptlang.org/docs/handbook/2/everyday-types.html#literal-types) are the go-to way to handle enum-like values in TypeScript. They are easier to extend with Pick and Omit, and offer a better developer experience, specially with code completion.
+[String literals](https://www.typescriptlang.org/docs/handbook/2/everyday-types.html#literal-types) are the go-to way to handle enum-like values in TypeScript. They are easier to extend with Pick and Omit, and offer a better developer experience, especially with code completion.

 You can see why TypeScript recommends avoiding enums [here](https://www.typescriptlang.org/docs/handbook/2/everyday-types.html#enums).

@@ -288,4 +288,3 @@ An Oxlint rule, `typescript/consistent-type-imports`, enforces the no-type impor
 Please note that this rule specifically addresses rare edge cases where unintentional type imports occur. TypeScript itself discourages this practice, as mentioned in the [TypeScript 3.8 release notes](https://www.typescriptlang.org/docs/handbook/release-notes/typescript-3-8.html). In most situations, you should not need to use type-only imports.

 To ensure your code complies with this rule, make sure to run Oxlint as part of your development workflow.
-
@@ -7,7 +7,7 @@ description: "The guide for contributors (or curious developers) who want to run
 ## Prerequisites

 <Tabs>
-<Tab title="Linux and MacOS">
+<Tab title="Linux and macOS">

 Before you can install and use Twenty, make sure you install the following on your computer:
 - [Git](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git)
@@ -31,7 +31,7 @@ wsl --install
 ```
 You should now see a prompt to restart your computer. If not, restart it manually.

-Upon restart, a powershell window will open and install Ubuntu. This may take up some time.
+Upon restart, a PowerShell window will open and install Ubuntu. This may take up some time.
 You'll see a prompt to create a username and password for your Ubuntu installation.

 2. Install and configure git
@@ -104,7 +104,7 @@ You should run all commands in the following steps from the root of the project.
 <Tabs>
  <Tab title="Linux">
    **Option 1 (preferred):** To provision your database locally:
-    Use the following link to install Postgresql on your Linux machine: [Postgresql Installation](https://www.postgresql.org/download/linux/)
+    Use the following link to install PostgreSQL on your Linux machine: [PostgreSQL Installation](https://www.postgresql.org/download/linux/)
    ```bash
      psql postgres -c "CREATE DATABASE \"default\";" -c "CREATE DATABASE test;"
    ```
@@ -131,7 +131,7 @@ You should run all commands in the following steps from the root of the project.
    ```

    The installer might not create the `postgres` user by default when installing
-    via Homebrew on MacOS. Instead, it creates a PostgreSQL role that matches your macOS
+    via Homebrew on macOS. Instead, it creates a PostgreSQL role that matches your macOS
    username (e.g., "john").
    To check and create the `postgres` user if necessary, follow these steps:
    ```bash
@@ -174,8 +174,8 @@ You should run all commands in the following steps from the root of the project.
  <Tab title="Windows (WSL)">
    All the following steps are to be run in the WSL terminal (within your virtual machine)

-    **Option 1:** To provision your Postgresql locally:
-    Use the following link to install Postgresql on your Linux virtual machine: [Postgresql Installation](https://www.postgresql.org/download/linux/)
+    **Option 1:** To provision your PostgreSQL locally:
+    Use the following link to install PostgreSQL on your Linux virtual machine: [PostgreSQL Installation](https://www.postgresql.org/download/linux/)
    ```bash
      psql postgres -c "CREATE DATABASE \"default\";" -c "CREATE DATABASE test;"
    ```
@@ -190,10 +190,12 @@ You should run all commands in the following steps from the root of the project.
  </Tab>
 </Tabs>

-You can now access the database at [localhost:5432](localhost:5432), with user `postgres` and password `postgres` .
+You can now access the database at `localhost:5432`.
+
+If you used the Docker option above, the default credentials are user `postgres` and password `postgres`. For native PostgreSQL installations, use the credentials and roles configured on your machine.

 ## Step 4: Set up a Redis Database (cache)
-Twenty requires a redis cache to provide the best performance
+Twenty requires a Redis cache to provide the best performance.

 <Tabs>
  <Tab title="Linux">
@@ -210,8 +212,10 @@ Twenty requires a redis cache to provide the best performance
    ```bash
    brew install redis
    ```
-    Start your redis server:
-    ```brew services start redis```
+    Start your Redis server:
+    ```bash
+    brew services start redis
+    ```

    **Option 2:** If you have docker installed:
    ```bash
@@ -229,11 +233,11 @@ Twenty requires a redis cache to provide the best performance
  </Tab>
 </Tabs>

-If you need a Client GUI, we recommend [redis insight](https://redis.io/insight/) (free version available)
+If you need a client GUI, we recommend [Redis Insight](https://redis.io/insight/) (free version available).

-## Step 5: Setup environment variables
+## Step 5: Set up environment variables

-Use environment variables or `.env` files to configure your project. More info [here](/developers/self-host/capabilities/setup)
+Use environment variables or `.env` files to configure your project. More info [here](/developers/self-host/capabilities/setup).

 Copy the `.env.example` files in `/front` and `/server`:
 ```bash
@@ -20,19 +20,51 @@ Apps let you build and manage Twenty customizations **as code**. Instead of conf
 ## Prerequisites

 - Node.js 24+ and Yarn 4
- A Twenty workspace and an API key (create one at https://app.twenty.com/settings/api-webhooks)
+- Docker (for the local Twenty dev server)

 ## Getting Started

-Create a new app using the official scaffolder, then authenticate and start developing:
+Create a new app using the official scaffolder. It can automatically start a local Twenty instance for you:

 ```bash filename="Terminal"
-# Scaffold a new app (includes all examples by default)
+# Scaffold a new app — the CLI will offer to start a local Twenty server
 npx create-twenty-app@latest my-twenty-app
 cd my-twenty-app

 # Start dev mode: automatically syncs local changes to your workspace
-yarn twenty app:dev
+yarn twenty dev
+```
+
+### Local Server Management
+
+The SDK includes commands to manage a local Twenty dev server (all-in-one Docker image with PostgreSQL, Redis, server, and worker):
+
+```bash filename="Terminal"
+# Start the local server (pulls the image if needed)
+yarn twenty server start
+
+# Check server status
+yarn twenty server status
+
+# Stream server logs
+yarn twenty server logs
+
+# Stop the server
+yarn twenty server stop
+
+# Reset all data and start fresh
+yarn twenty server reset
+```
+
+The local server comes pre-seeded with a workspace and user (`tim@apple.dev` / `tim@apple.dev`), so you can start developing immediately without any manual setup.
+
+### Authentication
+
+Connect your app to the local server using OAuth:
+
+```bash filename="Terminal"
+# Authenticate via OAuth (opens browser)
+yarn twenty remote add --local
 ```

 The scaffolder supports two modes for controlling which example files are included:
@@ -4,7 +4,7 @@ title: 1-Click w/ Docker Compose


 <Warning>
-Docker containers are for production hosting or self-hosting, for the contribution please check the [Local Setup](/developers/contribute/capabilities/local-setup).
+Docker containers are for production hosting or self-hosting. For contributing, please check the [Local Setup](/developers/contribute/capabilities/local-setup).
 </Warning>

 ## Overview
@@ -13,7 +13,7 @@ This guide provides step-by-step instructions to install and configure the Twent

 **Important:** Only modify settings explicitly mentioned in this guide. Altering other configurations may lead to issues.

-See docs [Setup Environment Variables](/developers/self-host/capabilities/setup) for advanced configuration. All environment variables must be declared in the docker-compose.yml file at the server and / or worker level depending on the variable.
+See [Setup Environment Variables](/developers/self-host/capabilities/setup) for advanced configuration. All environment variables must be declared in the `docker-compose.yml` file at the server and/or worker level, depending on the variable.

 ## System Requirements

@@ -237,4 +237,3 @@ docker compose up -d

 If you encounter any problem, check [Troubleshooting](/developers/self-host/capabilities/troubleshooting) for solutions.

-
@@ -6302,6 +6302,10 @@
      "source": "/developers/extend/capabilities/apps",
      "destination": "/developers/extend/apps/getting-started"
    },
+    {
+      "source": "/developers/extend/mcp",
+      "destination": "/user-guide/ai/capabilities/mcp"
+    },
    {
      "source": "/developers/local-setup",
      "destination": "/developers/contribute/capabilities/local-setup"
@@ -8,7 +8,7 @@ title: دليل الأسلوب

 لهذا، من الأفضل أن تكون تفصيلًا أكثر قليلاً بدلاً من أن تكون موجزًا للغاية.

-دائمًا ضع في اعتبارك أن الناس يقرؤون التعليمات البرمجية أكثر مما يكتبونها، وخاصة في المشاريع مفتوحة المصدر، حيث يمكن لأي شخص المساهمة.
+دائمًا ضع في اعتبارك أن الناس يقرؤون التعليمات البرمجية أكثر مما يكتبونها، وخاصة في مشروع مفتوح المصدر، حيث يمكن لأي شخص المساهمة.

 هناك العديد من القواعد التي لم يتم تعريفها هنا، ولكن يتم التحقق منها تلقائيًا بواسطة أدوات الفحص.

@@ -6,7 +6,7 @@ description: الدليل للمساهمين (أو المطورين الفضول
 ## المتطلبات الأساسية

 <Tabs>
-<Tab title="Linux و MacOS">
+<Tab title="Linux و macOS">

 قبل أن تتمكن من تثبيت واستخدام Twenty، تأكد من تثبيت الأمور التالية على جهاز الكمبيوتر الخاص بك:
 * [Git](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git)
@@ -103,7 +103,7 @@ cd twenty
 <Tabs>
  <Tab title="Linux">
    **الخيار 1 (المفضل):** لتوفير قاعدة بياناتك محليًا:
-    استخدم الرابط التالي لتثبيت Postgresql على جهاز Linux الخاص بك: [تثبيت Postgresql](https://www.postgresql.org/download/linux/)
+    استخدم الرابط التالي لتثبيت PostgreSQL على جهاز Linux الخاص بك: [تثبيت PostgreSQL](https://www.postgresql.org/download/linux/)
    ```bash
      psql postgres -c "CREATE DATABASE \"default\";" -c "CREATE DATABASE test;"
    ```
@@ -129,8 +129,8 @@ cd twenty
    brew services list
    ```

-    المثبت قد لا ينشئ المستخدم `postgres` افتراضيًا عند التثبيت
-    عبر Homebrew على MacOS. بدلاً من ذلك، فإنه ينشئ دور PostgreSQL يطابق
+    قد لا يقوم المُثبِّت بإنشاء المستخدم `postgres` افتراضيًا عند التثبيت
+    عبر Homebrew على macOS. بدلاً من ذلك، فإنه ينشئ دور PostgreSQL يطابق
    اسم المستخدم الخاص بك في MacOS (مثل "john").
    للتحقق وإنشاء المستخدم `postgres` إذا لزم الأمر، اتبع هذه الخطوات:
    ```bash
@@ -173,8 +173,8 @@ cd twenty
  <Tab title="ويندوز (WSL)">
    يجب أن تُنفذ جميع الخطوات التالية في تيرمينال WSL (داخل جهازك الافتراضي)

-    **الخيار 1:** لتوفير قاعدة بيانات Postgresql الخاصة بك محليًا:
-    استخدم الرابط التالي لتثبيت Postgresql على جهاز Linux الافتراضي الخاص بك: [تثبيت Postgresql](https://www.postgresql.org/download/linux/)
+    **الخيار 1:** لتوفير قاعدة بيانات PostgreSQL الخاصة بك محليًا:
+    استخدم الرابط التالي لتثبيت PostgreSQL على جهاز Linux الافتراضي الخاص بك: [تثبيت PostgreSQL](https://www.postgresql.org/download/linux/)
    ```bash
      psql postgres -c "CREATE DATABASE \"default\";" -c "CREATE DATABASE test;"
    ```
@@ -189,11 +189,13 @@ cd twenty
  </Tab>
 </Tabs>

-يمكنك الآن الوصول إلى قاعدة البيانات على [localhost:5432](localhost:5432)، مع المستخدم `postgres` وكلمة المرور `postgres`.
+يمكنك الآن الوصول إلى قاعدة البيانات على `localhost:5432`.
+
+إذا استخدمت خيار Docker أعلاه، فإن بيانات الاعتماد الافتراضية هي اسم المستخدم `postgres` وكلمة المرور `postgres`. بالنسبة لتثبيتات PostgreSQL الأصلية، استخدم بيانات الاعتماد والأدوار المُكوَّنة على جهازك.

 ## الخطوة 4: إعداد قاعدة بيانات Redis (للتخزين المؤقت)

-يتطلب Twenty مخزن بيانات Redis لتقديم أفضل أداء
+يتطلب Twenty مخزن بيانات Redis لتقديم أفضل أداء.

 <Tabs>
  <Tab title="Linux">
@@ -210,8 +212,10 @@ cd twenty
    ```bash
    brew install redis
    ```
-    ابدأ خادم redis الخاص بك:
-    `brew services start redis`
+    ابدأ تشغيل خادم Redis:
+    ```bash
+    brew services start redis
+    ```

    **الخيار 2:** إذا كنت قد قمت بتثبيت docker:
    ```bash
@@ -229,11 +233,11 @@ cd twenty
  </Tab>
 </Tabs>

-إذا كنت بحاجة إلى واجهة رسومية للعميل، نوصي بـ [redis insight](https://redis.io/insight/) (يتوفر إصدار مجاني)
+إذا كنت بحاجة إلى واجهة رسومية للعميل، نوصي بـ [Redis Insight](https://redis.io/insight/) (يتوفر إصدار مجاني).

 ## الخطوة 5: إعداد متغيرات البيئة

-استخدم متغيرات البيئة أو ملفات `.env` لتكوين مشروعك. المزيد من المعلومات [هنا](/l/ar/developers/self-host/capabilities/setup)
+استخدم متغيرات البيئة أو ملفات `.env` لتكوين مشروعك. المزيد من المعلومات [هنا](/l/ar/developers/self-host/capabilities/setup).

 انسخ ملفات `.env.example` الموجودة في `/front` و`/server`:

@@ -21,19 +21,51 @@ description: أنشئ وأدِر تخصيصات Twenty على هيئة كود.
 ## المتطلبات الأساسية

 * Node.js 24+ وYarn 4
-* مساحة عمل Twenty ومفتاح واجهة برمجة التطبيقات (أنشئ واحدًا على https://app.twenty.com/settings/api-webhooks)
+* Docker (لخادم تطوير Twenty المحلي)

 ## البدء

-أنشئ تطبيقًا جديدًا باستخدام المُهيئ الرسمي، ثم قم بالمصادقة وابدأ التطوير:
+أنشئ تطبيقًا جديدًا باستخدام المولّد الرسمي. يمكنه بدء مثيل محلي من Twenty تلقائيًا لك:

 ```bash filename="Terminal"
-# إنشاء تطبيق جديد (يتضمن جميع الأمثلة افتراضيًا)
+# إنشاء تطبيق جديد — ستعرض واجهة سطر الأوامر خيار بدء خادم Twenty محلي
 npx create-twenty-app@latest my-twenty-app
 cd my-twenty-app

 # ابدأ وضع التطوير: يُزامن التغييرات المحلية تلقائيًا مع مساحة العمل الخاصة بك
-yarn twenty app:dev
+yarn twenty dev
+```
+
+### إدارة الخادم المحلي
+
+يتضمن SDK أوامر لإدارة خادم تطوير Twenty محلي (صورة Docker متكاملة تتضمن PostgreSQL وRedis والخادم والعامل):
+
+```bash filename="Terminal"
+# ابدأ الخادم المحلي (يسحب الصورة إذا لزم الأمر)
+yarn twenty server start
+
+# تحقّق من حالة الخادم
+yarn twenty server status
+
+# بثّ سجلات الخادم
+yarn twenty server logs
+
+# أوقف الخادم
+yarn twenty server stop
+
+# أعد ضبط جميع البيانات وابدأ من جديد
+yarn twenty server reset
+```
+
+يأتي الخادم المحلي مهيأً مسبقًا بمساحة عمل ومستخدم (`tim@apple.dev` / `tim@apple.dev`)، بحيث يمكنك البدء في التطوير فورًا دون أي إعداد يدوي.
+
+### المصادقة
+
+وصّل تطبيقك بالخادم المحلي باستخدام OAuth:
+
+```bash filename="Terminal"
+# المصادقة عبر OAuth (يفتح المتصفح)
+yarn twenty remote add --local
 ```

 يدعم المُنشئ وضعين للتحكم في ملفات الأمثلة التي سيتم تضمينها:
@@ -64,6 +96,12 @@ yarn twenty function:execute --preInstall
 # نفّذ دالة ما بعد التثبيت
 yarn twenty function:execute --postInstall

+# ابنِ التطبيق للتوزيع
+yarn twenty app:build
+
+# انشر التطبيق إلى npm أو إلى خادم Twenty
+yarn twenty app:publish
+
 # أزل تثبيت التطبيق من مساحة العمل الحالية
 yarn twenty app:uninstall

@@ -1240,6 +1278,113 @@ uploadFile(

 استكشف مثالًا بسيطًا شاملًا من البداية إلى النهاية يوضح الكائنات والوظائف المنطقية والمكوّنات الأمامية ومشغّلات متعددة [هنا](https://github.com/twentyhq/twenty/tree/main/packages/twenty-apps/hello-world):

+## بناء تطبيقك
+
+بمجرد أن تطوّر تطبيقك باستخدام `app:dev`، استخدم `app:build` لإنشاء حزمة قابلة للتوزيع منه.
+
+```bash filename="Terminal"
+# ابنِ التطبيق (الإخراج يذهب إلى .twenty/output/)
+yarn twenty app:build
+
+# ابنِ وأنشئ ملف tarball (.tgz) للتوزيع
+yarn twenty app:build --tarball
+```
+
+عملية البناء:
+
+1. **يقوم بتحليل ملف البيان والتحقق من صحته** — يقرأ جميع الكيانات `defineX()` من ملفات المصدر لديك ويُتحقّق من بنية ملف البيان.
+2. **يُصرِّف دوال المنطق ومكوّنات الواجهة** — يُجمّع مصادر TypeScript إلى ملفات ESM `.mjs` باستخدام esbuild.
+3. **يولّد قيم التحقّق** — يحسب تجزئات MD5 لكل ملف مُبنًى، وتُخزَّن في ملف البيان كـ `builtHandlerChecksum` / `builtComponentChecksum`.
+4. **ينشئ عميل API مضبوط الأنواع** — يفحص مخطط GraphQL ويُنشئ عميلَي `CoreApiClient` و`MetadataApiClient` مضبوطي الأنواع.
+5. **يشغّل فحص الأنواع لـ TypeScript** — يشغّل `tsc --noEmit` لاكتشاف أخطاء الأنواع قبل النشر.
+6. **يعيد البناء باستخدام العميل المُولَّد** — يُجري مرحلة ترجمة ثانية بحيث تُدرَج أنواع العميل المُولَّد.
+7. **ينشئ أرشيف tar اختياريًا** — إذا تم تمرير `--tarball`، يشغّل `npm pack` لإنشاء ملف `.tgz` جاهز للتوزيع.
+
+مخرجات البناء في `.twenty/output/` تتضمّن:
+
+```text
+.twenty/output/
+├── manifest.json              # Manifest with checksums for all built files
+├── package.json               # Copied from app root
+├── yarn.lock                  # Copied from app root
+├── src/
+│   ├── logic-functions/       # Compiled .mjs logic function files
+│   └── front-components/      # Compiled .mjs front component files
+├── public/                    # Static assets (if any)
+└── my-app-1.0.0.tgz          # Only with --tarball flag
+```
+
+| الخيار      | الوصف                                              |
+| ----------- | -------------------------------------------------- |
+| `[appPath]` | المسار إلى دليل التطبيق (افتراضيًا: الدليل الحالي) |
+| `--tarball` | قم أيضًا بحزم المخرجات في أرشيف `.tgz`             |
+
+## نشر تطبيقك
+
+استخدم `app:publish` لتوزيع تطبيقك — إما إلى سجل npm أو مباشرةً إلى خادم Twenty.
+
+### النشر إلى npm (الإعداد الافتراضي)
+
+```bash filename="Terminal"
+# Publish to npm (requires npm login)
+yarn twenty app:publish
+
+# Publish with a dist-tag (e.g. beta, next)
+yarn twenty app:publish --tag beta
+```
+
+يقوم هذا ببناء التطبيق وتشغيل `npm publish` من دليل `.twenty/output/`. بعد ذلك يمكن تثبيت الحزمة المنشورة من سوق Twenty بواسطة أي مساحة عمل.
+
+### النشر إلى خادم Twenty
+
+```bash filename="Terminal"
+# Publish directly to a Twenty server
+yarn twenty app:publish --server https://app.twenty.com
+```
+
+يقوم هذا ببناء التطبيق مع أرشيف tar، ويرفعه إلى الخادم عبر العملية `uploadAppTarball` في GraphQL، ويبدأ التثبيت في خطوة واحدة. يكون هذا مفيدًا لعمليات النشر الخاصة أو للاختبار مقابل خادم محدّد.
+
+| الخيار            | الوصف                                                    |
+| ----------------- | -------------------------------------------------------- |
+| `[appPath]`       | المسار إلى دليل التطبيق (افتراضيًا: الدليل الحالي)       |
+| `--server <url>`  | انشر إلى خادم Twenty بدلًا من npm                        |
+| `--token <token>` | رمز المصادقة للخادم المستهدف                             |
+| `--tag <tag>`     | علامة توزيع npm (مثل `beta`، `next`) — للنشر عبر npm فقط |
+
+## تسجيل التطبيق
+
+قبل أن يمكن تثبيت تطبيق في مساحة عمل، يجب أن يكون **مسجّلًا**. التسجيل هو سجل بيانات وصفية يوضّح مصدر التطبيق وكيفية مصادقته. يُعالَج هذا تلقائيًا بواسطة CLI في معظم الحالات.
+
+### أنواع المصادر
+
+لكل تسجيل **نوع مصدر** يحدّد كيفية تحديد ملفات التطبيق أثناء التثبيت:
+
+| نوع المصدر | كيفية تحديد الملفات                                                       | حالة الاستخدام النموذجية                |
+| ---------- | ------------------------------------------------------------------------- | --------------------------------------- |
+| `LOCAL`    | تتم مزامنة الملفات في الوقت الفعلي بواسطة مُراقِب CLI — يتم تخطّي التثبيت | التطوير باستخدام `app:dev`              |
+| `NPM`      | تُجلب من سجل npm عبر الحقل `sourcePackage`                                | تطبيقات منشورة على npm                  |
+| `TARBALL`  | تُستخرَج من ملف `.tgz` مرفوع ومخزَّن على الخادم                           | تطبيقات خاصة منشورة باستخدام `--server` |
+
+### كيفية إجراء التسجيل
+
+* **`app:dev`** — ينشئ تلقائيًا تسجيلًا من نوع `LOCAL` في المرة الأولى التي تشغّل فيها وضع التطوير لمساحة عمل.
+* **`app:publish --server`** — يرفع أرشيف tar وينشئ (أو يحدّث) تسجيلًا من نوع `TARBALL`، ثم يثبّت التطبيق.
+* **سوق npm** — يتم إنشاء تسجيلات `NPM` عند مزامنة التطبيقات من سجل npm إلى كتالوج سوق Twenty.
+* **واجهة برمجة تطبيقات GraphQL** — يمكنك أيضًا إنشاء التسجيلات برمجيًا عبر العملية `createApplicationRegistration`.
+
+### التسجيل مقابل التثبيت
+
+**التسجيل** و**التثبيت** مفهومان منفصلان:
+
+* **التسجيل** (`ApplicationRegistration`) هو سجل بيانات وصفية عام يصف التطبيق: اسمه، نوع المصدر، بيانات اعتماد OAuth، وحالة إدراجه في السوق. وهو موجود بشكل مستقل عن أي مساحة عمل.
+* **التثبيت** (`Application`) هو مثيل لكل مساحة عمل. عند قيام مستخدم بتثبيت تطبيق، تقوم Twenty بحلّ الحزمة من مصدر التسجيل، وتكتب الملفات المُبنَاة إلى التخزين، وتزامن البيان التعريفي (إنشاء الكائنات والحقول ودوال المنطق، إلخ) في مساحة العمل تلك.
+
+يمكن تثبيت تسجيل واحد في العديد من مساحات العمل. تحصل كل مساحة عمل على نسختها الخاصة من ملفات التطبيق ونموذج البيانات.
+
+### بيانات اعتماد OAuth
+
+يتضمن كل تسجيل بيانات اعتماد OAuth (`oAuthClientId` و`oAuthClientSecret`) يتم إنشاؤها وقت الإنشاء. يستخدمها التطبيق لمصادقة طلبات واجهة برمجة التطبيقات بالنيابة عن المستخدمين. يُعرَض سر العميل مرةً **واحدة** عند الإنشاء — خزّنه بأمان. يمكنك تدويره لاحقًا عبر العملية `rotateApplicationRegistrationClientSecret`.
+
 ## إعداد يدوي (بدون المهيئ)

 بينما نوصي باستخدام `create-twenty-app` للحصول على أفضل تجربة للبدء، يمكنك أيضًا إعداد مشروع يدويًا. لا تثبّت CLI عالميًا. بدل ذلك، أضف `twenty-sdk` كاعتماد محلي واربط سكربتًا واحدًا في ملف package.json لديك:
@@ -3,7 +3,7 @@ title: بنقرة واحدة مع Docker Compose
 ---

 <Warning>
-الحاويات الخاصة بدوكر مخصصة للاستضافة الإنتاجية أو الاستضافة الذاتية، للتحقيق يرجى التحقق من [الإعداد المحلي](/l/ar/developers/contribute/capabilities/local-setup).
+حاويات Docker مخصصة للاستضافة في بيئة الإنتاج أو للاستضافة الذاتية. للمساهمة، يُرجى الاطلاع على [الإعداد المحلي](/l/ar/developers/contribute/capabilities/local-setup).
 </Warning>

 ## نظرة عامة
@@ -12,7 +12,7 @@ title: بنقرة واحدة مع Docker Compose

 **مهم:** عدّل الإعدادات المذكورة صراحة في هذا الدليل فقط. قد يؤدي تعديل التكوينات الأخرى إلى مشاكل.

-راجع المستندات الخاصة بـ [إعداد متغيرات البيئة](/l/ar/developers/self-host/capabilities/setup) لإعداد متقدم. يجب إعلان جميع متغيرات البيئة في الملف docker-compose.yml على مستوى الخادم و/أو العامل بناءً على المتغير.
+راجع [إعداد متغيرات البيئة](/l/ar/developers/self-host/capabilities/setup) لإعداد متقدم. يجب إعلان جميع متغيرات البيئة في ملف `docker-compose.yml` على مستوى الخادم و/أو العامل، اعتمادًا على المتغير.

 ## متطلبات النظام

@@ -0,0 +1,142 @@
+---
+title: خادم MCP
+description: اربط مساعدي الذكاء الاصطناعي بمساحة عمل Twenty الخاصة بك باستخدام بروتوكول سياق النموذج.
+---
+
+<Warning>
+MCP حاليًا في مرحلة **ألفا** وهو متاح فقط في بعض مساحات العمل. قد لا يكون مفعّلًا لمساحة عملك بعد.
+</Warning>
+
+تعرض Twenty خادم [MCP](https://modelcontextprotocol.io/) بحيث تتمكّن مساعدات الذكاء الاصطناعي — Claude Desktop وClaude Code وCursor وChatGPT وغيرها — من قراءة وكتابة بيانات نظام إدارة علاقات العملاء (CRM) لديك باستخدام اللغة الطبيعية.
+
+استخدم **عنوان URL لمساحة العمل** (عنوان URL الذي تستخدمه للوصول إلى Twenty) كنقطة نهاية MCP. على Twenty Cloud، قد يكون عنوان URL لمساحة العمل هو `https://{mycompany}.twenty.com` أو نطاق مخصص. الخادم متاح على:
+
+| البيئة                | نقطة نهاية MCP                                                                           |
+| --------------------- | ---------------------------------------------------------------------------------------- |
+| **السحابة**           | `https://{your-workspace-url}/mcp` (على سبيل المثال: `https://mycompany.twenty.com/mcp`) |
+| **الاستضافة الذاتية** | `https://{your-domain}/mcp`                                                              |
+
+## طرق المصادقة
+
+لديك طريقتان لمصادقة عميل MCP: **OAuth** (مُوصى بها) أو **مفتاح API**.
+
+### الخيار أ — OAuth (مُوصى به)
+
+باستخدام OAuth، يفتح عميل MCP لديك نافذة متصفح لتسجيل الدخول. لا يتم تخزين أي أسرار في ملفات الإعداد، ويتم تحديث الرموز المميِّزة تلقائيًا.
+
+<Note>
+يتطلب OAuth عميل MCP يدعم [مواصفة تفويض MCP](https://modelcontextprotocol.io/specification/2025-03-26/basic/authorization). تدعمه Claude Desktop وClaude Code وCursor وChatGPT.
+</Note>
+
+أضِف ما يلي إلى تهيئة عميل MCP لديك، واستبدِل `{your-workspace-url}` بمضيف مساحة العمل لديك (على سبيل المثال: `mycompany.twenty.com`):
+
+```json
+{
+  "mcpServers": {
+    "twenty": {
+      "type": "streamable-http",
+      "url": "https://{your-workspace-url}/mcp"
+    }
+  }
+}
+```
+
+هذا كل شيء — لا حاجة إلى مفتاح API. عند اتصال العميل للمرة الأولى، سيفعل ما يلي:
+
+1. اكتشاف بيانات التعريف الخاصة بـ OAuth لدى Twenty عبر `/.well-known/oauth-protected-resource` و`/.well-known/oauth-authorization-server`
+2. تسجيل نفسه كعميل OAuth عبر التسجيل الديناميكي للعميل (RFC 7591)
+3. فتح متصفحك لتفويض الوصول
+4. استلام الرموز المميِّزة والاتصال بخادم MCP
+
+تعيد الاتصالات اللاحقة استخدام الرموز المميِّزة المخزنة وتحدِّثها تلقائيًا.
+
+### الخيار ب — مفتاح API
+
+إذا كان عميل MCP لديك لا يدعم OAuth، أو كنت تفضّل بيانات اعتماد ثابتة، فمرِّر مفتاح API في ترويسة `Authorization`:
+
+```json
+{
+  "mcpServers": {
+    "twenty": {
+      "type": "streamable-http",
+      "url": "https://{your-workspace-url}/mcp",
+      "headers": {
+        "Authorization": "Bearer YOUR_API_KEY"
+      }
+    }
+  }
+}
+```
+
+<Warning>
+يمنح مفتاح API الخاص بك حق الوصول إلى بيانات مساحة العمل. أبعِده عن أنظمة التحكم في الإصدارات وملفات dotfiles المشتركة.
+</Warning>
+
+لإنشاء مفتاح API، انتقل إلى **Settings > APIs & Webhooks > + Create key**. راجع [واجهات برمجة التطبيقات](/l/ar/developers/extend/api#create-an-api-key) للتفاصيل.
+
+## البدء السريع
+
+### 1. انسخ الإعداد
+
+انتقل إلى **Settings > AI > More > MCP Server** في Twenty. اختر طريقة المصادقة (OAuth أو مفتاح API)، وانسخ مقطع JSON (سيستخدم بالفعل عنوان URL لمساحة العمل لديك)، ثم الصقه في ملف إعدادات عميل MCP لديك.
+
+| العميل             | موقع ملف الإعداد                                                                                                                                    |
+| ------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **Claude Desktop** | `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) أو `%APPDATA%\Claude\claude_desktop_config.json` (Windows)                |
+| **Claude Code**    | `~/.claude.json` (المستخدم) أو `.mcp.json` (المشروع)                                                                                                |
+| **Cursor**         | `.cursor/mcp.json` ضمن مشروعك، أو `~/.cursor/mcp.json` عالميًا                                                                                      |
+| **ChatGPT**        | فعِّل وضع المطوّر في **Settings > Apps & Connectors > Advanced settings**، ثم استخدم **Create** في **Settings > Apps & Connectors** لإضافة خادم MCP |
+
+### 2. الاتصال
+
+أعِد تشغيل عميل MCP لديك (أو أعد تحميل ملف الإعداد). إذا كنت تستخدم OAuth فسيتم توجيهك إلى Twenty لتفويض الوصول. إذا كنت تستخدم مفتاح API فسيكون الاتصال فوريًا.
+
+### 3. ابدأ باستخدامه
+
+اطلب من مساعد الذكاء الاصطناعي التفاعل مع نظام إدارة علاقات العملاء (CRM) لديك:
+
+* *"أرني أحدث 5 شركات تم إنشاؤها"*
+* *"أنشئ شخصًا جديدًا باسم Jane Doe في Acme Corp"*
+* *"اعثر على جميع الفرص المفتوحة التي تزيد قيمتها عن 10 آلاف دولار"*
+
+## الأدوات المتاحة
+
+بعد الاتصال، يوفّر خادم MCP أدوات تعكس واجهة برمجة تطبيقات Twenty (API). سير العمل الموصى به هو:
+
+1. **`get_tool_catalog`** — اكتشف جميع الأدوات المتاحة
+2. **`learn_tools`** — احصل على مخطط الإدخال لأدوات محددة
+3. **`execute_tool`** — شغّل أداة
+
+لا تحتاج إلى تذكّر أسماء الأدوات. اسأل مساعد الذكاء الاصطناعي عمّا يمكنه فعله وسيستدعي `get_tool_catalog` تلقائيًا.
+
+## الصلاحيات
+
+ترث اتصالات MCP أذونات المستخدم المُصادَق عليه (OAuth) أو الدور المُعيَّن لمفتاح API. لتقييد ما يمكن لخادم MCP القيام به:
+
+* **OAuth**: ينطبق دور المستخدم في مساحة العمل.
+* **API Key**: عيِّن دورًا لمفتاح API ضمن **Settings > Roles**. راجع [الأذونات](/l/ar/user-guide/permissions-access/capabilities/permissions).
+
+## التكوين ذاتي الاستضافة
+
+في حالات الاستضافة الذاتية، استبدِل `{your-workspace-url}` بعنوان URL الخاص بالخادم لديك. تأكّد من أن قيمة `SERVER_URL` في بيئتك تطابق عنوان URL العام لمثيل Twenty لديك — إذ يُستخدَم ذلك لإنشاء بيانات تعريف اكتشاف OAuth.
+
+```bash
+SERVER_URL=https://twenty.yourcompany.com
+```
+
+تُشتق نقطة نهاية MCP ونقاط نهاية OAuth وبيانات تعريف الاكتشاف جميعها من هذه القيمة.
+
+## استكشاف الأخطاء وإصلاحها
+
+**أخطاء "Unauthorized" أو 401**
+
+* OAuth: أعد التفويض عبر مسح الرموز المميِّزة المخزنة في عميل MCP لديك ثم أعد الاتصال.
+* API Key: تحقّق من أن المفتاح صالح ولم تنتهِ صلاحيته. أعِد توليده إذا لزم الأمر.
+
+**عملية OAuth لا تفتح متصفحًا**
+
+* تأكّد من أن عميل MCP لديك يدعم تفويض MCP. ارجع إلى طريقة مفتاح API إذا لم يكن كذلك.
+
+**انتهاء مهلة الاتصال**
+
+* تحقّق من إمكانية الوصول إلى عنوان URL لنقطة نهاية MCP من جهازك. بالنسبة لحالات الاستضافة الذاتية، تحقّق من أن الخادم يعمل وأن `SERVER_URL` مُعيَّن بشكل صحيح.
@@ -6,7 +6,7 @@ description: Der Leitfaden für Mitwirkende (oder neugierige Entwickler), die Tw
 ## Voraussetzungen

 <Tabs>
-<Tab title="Linux und MacOS">
+<Tab title="Linux und macOS">

 Bevor Sie Twenty installieren und verwenden können, stellen Sie sicher, dass Sie Folgendes auf Ihrem Computer installiert haben:
 * [Git](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git)
@@ -103,7 +103,7 @@ Alle folgenden Befehle innerhalb des Projekts sind vom Stammverzeichnis aus ausz
 <Tabs>
  <Tab title="Linux">
    **Option 1 (bevorzugt):** Um Ihre Datenbank lokal bereitzustellen:
-    Verwenden Sie den folgenden Link, um PostgreSQL auf Ihrem Linux-Rechner zu installieren: [Postgresql-Installation](https://www.postgresql.org/download/linux/)
+    Verwenden Sie den folgenden Link, um PostgreSQL auf Ihrem Linux-Rechner zu installieren: [PostgreSQL-Installation](https://www.postgresql.org/download/linux/)
    ```bash
      psql postgres -c "CREATE DATABASE \"default\";" -c "CREATE DATABASE test;"
    ```
@@ -129,8 +129,8 @@ Alle folgenden Befehle innerhalb des Projekts sind vom Stammverzeichnis aus ausz
     brew services list
    ```

-    Der Installer erstellt möglicherweise nicht standardmäßig den Benutzer `postgres`, wenn er
-    über Homebrew auf MacOS installiert wird. Stattdessen wird eine PostgreSQL-Rolle erstellt, die Ihrem macOS
+    Das Installationsprogramm erstellt den Benutzer `postgres` möglicherweise nicht standardmäßig bei der Installation
+    über Homebrew auf macOS. Stattdessen wird eine PostgreSQL-Rolle erstellt, die Ihrem macOS
    Benutzernamen (z. B. "john") entspricht.
    Um zu überprüfen und, falls erforderlich, den Benutzer `postgres` zu erstellen, führen Sie folgende Schritte aus:
    ```bash
@@ -174,7 +174,7 @@ Alle folgenden Befehle innerhalb des Projekts sind vom Stammverzeichnis aus ausz
    Alle folgenden Schritte sind im WSL-Terminal auszuführen (innerhalb Ihrer virtuellen Maschine)

    **Option 1:** Um Ihr PostgreSQL lokal bereitzustellen:
-    Verwenden Sie den folgenden Link, um PostgreSQL auf Ihrer Linux-VM zu installieren: [Postgresql-Installation](https://www.postgresql.org/download/linux/)
+    Verwenden Sie den folgenden Link, um PostgreSQL auf Ihrer Linux-VM zu installieren: [PostgreSQL-Installation](https://www.postgresql.org/download/linux/)
    ```bash
      psql postgres -c "CREATE DATABASE \"default\";" -c "CREATE DATABASE test;"
    ```
@@ -189,11 +189,13 @@ Alle folgenden Befehle innerhalb des Projekts sind vom Stammverzeichnis aus ausz
  </Tab>
 </Tabs>

-Sie können jetzt über [localhost:5432](localhost:5432) auf die Datenbank zugreifen, mit dem Benutzer `postgres` und dem Passwort `postgres`.
+Sie können nun über `localhost:5432` auf die Datenbank zugreifen.
+
+Wenn Sie die oben genannte Docker-Option verwendet haben, lauten die Standardanmeldedaten Benutzer `postgres` und Passwort `postgres`. Für native PostgreSQL-Installationen verwenden Sie die auf Ihrem Rechner konfigurierten Anmeldedaten und Rollen.

 ## Schritt 4: Einrichten einer Redis-Datenbank (Cache)

-Twenty benötigt einen Redis-Cache, um die beste Leistung zu bieten
+Twenty benötigt einen Redis-Cache, um die beste Leistung zu bieten.

 <Tabs>
  <Tab title="Linux">
@@ -211,7 +213,9 @@ Twenty benötigt einen Redis-Cache, um die beste Leistung zu bieten
    brew install redis
    ```
    Starten Sie Ihren Redis-Server:
-    `brew services start redis`
+    ```bash
+    brew services start redis
+    ```

    **Option 2:** Wenn Sie Docker installiert haben:
    ```bash
@@ -229,11 +233,11 @@ Twenty benötigt einen Redis-Cache, um die beste Leistung zu bieten
  </Tab>
 </Tabs>

-Wenn Sie eine Client-GUI benötigen, empfehlen wir [redis insight](https://redis.io/insight/) (kostenlose Version verfügbar)
+Wenn Sie eine Client-GUI benötigen, empfehlen wir [Redis Insight](https://redis.io/insight/) (kostenlose Version verfügbar).

 ## Schritt 5: Einrichten von Umgebungsvariablen

-Verwenden Sie Umgebungsvariablen oder `.env`-Dateien, um Ihr Projekt zu konfigurieren. Weitere Informationen [hier](/l/de/developers/self-host/capabilities/setup)
+Verwenden Sie Umgebungsvariablen oder `.env`-Dateien, um Ihr Projekt zu konfigurieren. Weitere Informationen [hier](/l/de/developers/self-host/capabilities/setup).

 Kopieren Sie die `.env.example`-Dateien in `/front` und `/server`:

@@ -21,19 +21,51 @@ Mit Apps können Sie Twenty-Anpassungen **als Code** erstellen und verwalten. An
 ## Voraussetzungen

 * Node.js 24+ und Yarn 4
-* Ein Twenty-Workspace und ein API-Schlüssel (unter https://app.twenty.com/settings/api-webhooks erstellen)
+* Docker (für den lokalen Twenty-Dev-Server)

 ## Erste Schritte

-Erstellen Sie mit dem offiziellen Scaffolder eine neue App, authentifizieren Sie sich und beginnen Sie mit der Entwicklung:
+Erstelle eine neue App mit dem offiziellen Scaffolder. Der Scaffolder kann für dich automatisch eine lokale Twenty-Instanz starten:

 ```bash filename="Terminal"
-# Eine neue App erstellen (enthält standardmäßig alle Beispiele)
+# Eine neue App erstellen — die CLI bietet an, einen lokalen Twenty-Server zu starten
 npx create-twenty-app@latest my-twenty-app
 cd my-twenty-app

 # Dev-Modus starten: synchronisiert lokale Änderungen automatisch mit deinem Arbeitsbereich
-yarn twenty app:dev
+yarn twenty dev
+```
+
+### Lokale Serververwaltung
+
+Das SDK enthält Befehle zur Verwaltung eines lokalen Twenty-Dev-Servers (All-in-One-Docker-Image mit PostgreSQL, Redis, Server und Worker):
+
+```bash filename="Terminal"
+# Den lokalen Server starten (lädt das Image bei Bedarf herunter)
+yarn twenty server start
+
+# Serverstatus prüfen
+yarn twenty server status
+
+# Serverprotokolle streamen
+yarn twenty server logs
+
+# Server stoppen
+yarn twenty server stop
+
+# Alle Daten zurücksetzen und neu starten
+yarn twenty server reset
+```
+
+Der lokale Server ist bereits mit einem Arbeitsbereich und einem Benutzer (`tim@apple.dev` / `tim@apple.dev`) vorbefüllt, sodass Sie ohne manuelle Einrichtung sofort mit der Entwicklung beginnen können.
+
+### Authentifizierung
+
+Verbinden Sie Ihre App mithilfe von OAuth mit dem lokalen Server:
+
+```bash filename="Terminal"
+# Authenticate via OAuth (opens browser)
+yarn twenty remote add --local
 ```

 Das Scaffolding-Tool unterstützt zwei Modi, um zu steuern, welche Beispieldateien enthalten sind:
@@ -64,11 +96,17 @@ yarn twenty function:execute --preInstall
 # Die Post-Installationsfunktion ausführen
 yarn twenty function:execute --postInstall

+# Die Anwendung für die Verteilung erstellen
+yarn twenty app:build
+
+# Die Anwendung auf npm oder einen Twenty-Server veröffentlichen
+yarn twenty app:publish
+
 # Die Anwendung aus dem aktuellen Arbeitsbereich deinstallieren
 yarn twenty app:uninstall

 # Hilfe zu Befehlen anzeigen
-yarn twenty help},{
+yarn twenty help
 ```

 Siehe auch: die CLI-Referenzseiten für [create-twenty-app](https://www.npmjs.com/package/create-twenty-app) und [twenty-sdk CLI](https://www.npmjs.com/package/twenty-sdk).
@@ -1240,6 +1278,113 @@ Hauptpunkte:

 Ein minimales End-to-End-Beispiel, das Objekte, Logikfunktionen, Frontend-Komponenten und mehrere Trigger demonstriert, finden Sie [hier](https://github.com/twentyhq/twenty/tree/main/packages/twenty-apps/hello-world):

+## Erstellen Ihrer App
+
+Sobald Sie Ihre App mit `app:dev` entwickelt haben, verwenden Sie `app:build`, um sie in ein verteilbares Paket zu kompilieren.
+
+```bash filename="Terminal"
+# Die App erstellen (Ausgabe nach .twenty/output/)
+yarn twenty app:build
+
+# Build ausführen und ein Tarball (.tgz) für die Verteilung erstellen
+yarn twenty app:build --tarball
+```
+
+Der Build-Prozess:
+
+1. **Parst und validiert das Manifest** — liest alle `defineX()`-Entitäten aus Ihren Quelldateien und validiert die Manifeststruktur.
+2. **Kompiliert Logikfunktionen und Front-Komponenten** — bündelt TypeScript-Quellcode in ESM `.mjs`-Dateien mit esbuild.
+3. **Erzeugt Checksummen** — berechnet MD5-Hashes für jede erstellte Datei, die im Manifest als `builtHandlerChecksum` / `builtComponentChecksum` gespeichert werden.
+4. **Generiert den typisierten API-Client** — führt eine Introspektion des GraphQL-Schemas durch und generiert die typisierten Clients `CoreApiClient` und `MetadataApiClient`.
+5. **Führt eine TypeScript-Typprüfung aus** — führt `tsc --noEmit` aus, um Typfehler vor der Veröffentlichung zu erkennen.
+6. **Baut mit dem generierten Client neu** — führt einen zweiten Kompiliervorgang durch, damit die generierten Client-Typen enthalten sind.
+7. **Erstellt optional einen Tarball** — wenn `--tarball` übergeben wird, wird `npm pack` ausgeführt, um eine `.tgz`-Datei zu erstellen, die für die Verteilung bereit ist.
+
+Der Build-Output in `.twenty/output/` enthält:
+
+```text
+.twenty/output/
+├── manifest.json              # Manifest with checksums for all built files
+├── package.json               # Copied from app root
+├── yarn.lock                  # Copied from app root
+├── src/
+│   ├── logic-functions/       # Compiled .mjs logic function files
+│   └── front-components/      # Compiled .mjs front component files
+├── public/                    # Static assets (if any)
+└── my-app-1.0.0.tgz          # Only with --tarball flag
+```
+
+| Option      | Beschreibung                                                   |
+| ----------- | -------------------------------------------------------------- |
+| `[appPath]` | Pfad zum App-Verzeichnis (standardmäßig aktuelles Verzeichnis) |
+| `--tarball` | Den Output zusätzlich in einen `.tgz`-Tarball packen           |
+
+## Veröffentlichen Ihrer App
+
+Verwenden Sie `app:publish`, um Ihre App zu verteilen — entweder zur npm-Registry oder direkt zu einem Twenty-Server.
+
+### Bei npm veröffentlichen (Standard)
+
+```bash filename="Terminal"
+# Publish to npm (requires npm login)
+yarn twenty app:publish
+
+# Publish with a dist-tag (e.g. beta, next)
+yarn twenty app:publish --tag beta
+```
+
+Dies baut die App und führt `npm publish` aus dem Verzeichnis `.twenty/output/` aus. Das veröffentlichte Paket kann dann von jedem Arbeitsbereich über den Twenty-Marktplatz installiert werden.
+
+### Auf einem Twenty-Server veröffentlichen
+
+```bash filename="Terminal"
+# Publish directly to a Twenty server
+yarn twenty app:publish --server https://app.twenty.com
+```
+
+Dies erstellt beim Build einen Tarball, lädt ihn über die GraphQL-Mutation `uploadAppTarball` auf den Server hoch und stößt die Installation in einem Schritt an. Dies ist nützlich für private Bereitstellungen oder Tests gegen einen bestimmten Server.
+
+| Option            | Beschreibung                                                       |
+| ----------------- | ------------------------------------------------------------------ |
+| `[appPath]`       | Pfad zum App-Verzeichnis (standardmäßig aktuelles Verzeichnis)     |
+| `--server <url>`  | Auf einen Twenty-Server anstelle von npm veröffentlichen           |
+| `--token <token>` | Authentifizierungstoken für den Zielserver                         |
+| `--tag <tag>`     | npm dist-tag (z. B. `beta`, `next`) — nur für npm-Veröffentlichung |
+
+## Anwendungsregistrierung
+
+Bevor eine App in einem Arbeitsbereich installiert werden kann, muss sie **registriert** werden. Eine Registrierung ist ein Metadatensatz, der beschreibt, woher die App stammt und wie sie authentifiziert wird. Dies wird in den meisten Fällen automatisch durch die CLI erledigt.
+
+### Quelltypen
+
+Jede Registrierung hat einen **Quelltyp**, der bestimmt, wie die Dateien der App während der Installation aufgelöst werden:
+
+| Quelltyp  | Wie Dateien aufgelöst werden                                                                   | Typischer Anwendungsfall                               |
+| --------- | ---------------------------------------------------------------------------------------------- | ------------------------------------------------------ |
+| `LOCAL`   | Dateien werden in Echtzeit vom CLI-Watcher synchronisiert — die Installation wird übersprungen | Entwicklung mit `app:dev`                              |
+| `NPM`     | Über das Feld `sourcePackage` aus der npm-Registry abgerufen                                   | Veröffentlichte Apps auf npm                           |
+| `TARBALL` | Aus einer hochgeladenen, auf dem Server gespeicherten `.tgz`-Datei extrahiert                  | Private Apps, die mit `--server` veröffentlicht wurden |
+
+### Wie die Registrierung erfolgt
+
+* **`app:dev`** — erstellt beim ersten Ausführen des Dev-Modus für einen Arbeitsbereich automatisch eine `LOCAL`-Registrierung.
+* **`app:publish --server`** — lädt einen Tarball hoch und erstellt (oder aktualisiert) eine `TARBALL`-Registrierung und installiert anschließend die App.
+* **npm-Marktplatz** — `NPM`-Registrierungen werden erstellt, wenn Apps aus der npm-Registry in den Twenty-Marktplatzkatalog synchronisiert werden.
+* **GraphQL-API** — Sie können Registrierungen auch programmgesteuert über die Mutation `createApplicationRegistration` erstellen.
+
+### Registrierung vs. Installation
+
+**Registrierung** und **Installation** sind unterschiedliche Konzepte:
+
+* Eine **Registrierung** (`ApplicationRegistration`) ist ein globaler Metadatensatz, der die App beschreibt: ihren Namen, den Quelltyp, die OAuth-Anmeldedaten und den Status der Marktplatzlistung. Sie existiert unabhängig von jedem Arbeitsbereich.
+* Eine **Installation** (`Application`) ist eine Instanz pro Arbeitsbereich. Wenn ein Benutzer eine App installiert, ermittelt Twenty das Paket aus der Quelle der Registrierung, schreibt die erstellten Dateien in den Speicher und synchronisiert das Manifest (wobei Objekte, Felder, Logikfunktionen usw. erstellt werden) in diesem Arbeitsbereich.
+
+Eine Registrierung kann in vielen Arbeitsbereichen installiert werden. Jeder Arbeitsbereich erhält seine eigene Kopie der Dateien und des Datenmodells der App.
+
+### OAuth-Anmeldedaten
+
+Jede Registrierung enthält OAuth-Anmeldedaten (`oAuthClientId` und `oAuthClientSecret`), die bei der Erstellung generiert werden. Diese werden von der App verwendet, um API-Anfragen im Namen der Benutzer zu authentifizieren. Das Client-Secret wird bei der Erstellung **einmalig** zurückgegeben — bewahren Sie es sicher auf. Sie können es später über die Mutation `rotateApplicationRegistrationClientSecret` rotieren.
+
 ## Manuelle Einrichtung (ohne Scaffolder)

 Wir empfehlen zwar `create-twenty-app` für das beste Einstiegserlebnis, Sie können ein Projekt aber auch manuell einrichten. Installieren Sie die CLI nicht global. Fügen Sie stattdessen `twenty-sdk` als lokale Abhängigkeit hinzu und binden Sie ein einzelnes Skript in Ihrer package.json ein:
@@ -3,7 +3,7 @@ title: 1-Klick mit Docker Compose
 ---

 <Warning>
-Docker-Container sind für die Produktion oder das Selbsthosten bestimmt. Für Beiträge siehe bitte das [Lokale Setup](/l/de/developers/contribute/capabilities/local-setup).
+Docker-Container sind für produktives Hosting oder Selbsthosting vorgesehen. Zum Mitwirken siehe [Lokale Einrichtung](/l/de/developers/contribute/capabilities/local-setup).
 </Warning>

 ## Überblick
@@ -12,7 +12,7 @@ Diese Anleitung enthält Schritt-für-Schritt-Anweisungen, um die Twenty-Anwendu

 **Wichtig:** Ändern Sie nur die in dieser Anleitung explizit erwähnten Einstellungen. Andere Konfigurationen zu ändern, kann zu Problemen führen.

-Siehe die Dokumentation [Umgebungsvariablen einrichten](/l/de/developers/self-host/capabilities/setup) zur erweiterten Konfiguration. Alle Umgebungsvariablen müssen in der Datei docker-compose.yml auf Server- und/oder Worker-Ebene deklariert werden, je nach Variable.
+Siehe die Dokumentation [Umgebungsvariablen einrichten](/l/de/developers/self-host/capabilities/setup) zur erweiterten Konfiguration. Alle Umgebungsvariablen müssen in der Datei `docker-compose.yml` auf Server- und/oder Worker-Ebene deklariert werden, je nach Variable.

 ## Systemanforderungen

@@ -0,0 +1,142 @@
+---
+title: MCP-Server
+description: Verbinden Sie KI-Assistenten mit Ihrem Twenty-Workspace über das Model Context Protocol.
+---
+
+<Warning>
+MCP befindet sich derzeit in **alpha** und ist nur in einigen Workspaces verfügbar. Möglicherweise ist es für Ihren Workspace noch nicht aktiviert.
+</Warning>
+
+Twenty stellt einen [MCP](https://modelcontextprotocol.io/)-Server bereit, damit KI-Assistenten — Claude Desktop, Claude Code, Cursor, ChatGPT und andere — Ihre CRM-Daten in natürlicher Sprache lesen und schreiben können.
+
+Verwenden Sie Ihre **Workspace-URL** (die URL, mit der Sie auf Twenty zugreifen) als MCP-Endpunkt. In Twenty Cloud kann Ihre Workspace-URL `https://{mycompany}.twenty.com` oder eine benutzerdefinierte Domain sein. Der Server ist verfügbar unter:
+
+| Umgebung          | MCP-Endpunkt                                                                  |
+| ----------------- | ----------------------------------------------------------------------------- |
+| **Cloud**         | `https://{your-workspace-url}/mcp` (z. B. `https://mycompany.twenty.com/mcp`) |
+| **Selbsthosting** | `https://{your-domain}/mcp`                                                   |
+
+## Authentifizierungsmethoden
+
+Sie haben zwei Möglichkeiten, Ihren MCP-Client zu authentifizieren: **OAuth** (empfohlen) oder **API-Schlüssel**.
+
+### Option A — OAuth (empfohlen)
+
+Mit OAuth öffnet Ihr MCP-Client ein Browserfenster, damit Sie sich anmelden können. Es werden keine geheimen Informationen in Konfigurationsdateien gespeichert, und Token werden automatisch erneuert.
+
+<Note>
+OAuth erfordert einen MCP-Client, der die [MCP-Autorisierungsspezifikation](https://modelcontextprotocol.io/specification/2025-03-26/basic/authorization) unterstützt. Claude Desktop, Claude Code, Cursor und ChatGPT unterstützen dies.
+</Note>
+
+Fügen Sie dies zu Ihrer MCP-Client-Konfiguration hinzu und ersetzen Sie `{your-workspace-url}` durch den Host Ihrer Workspace-URL (z. B. `mycompany.twenty.com`):
+
+```json
+{
+  "mcpServers": {
+    "twenty": {
+      "type": "streamable-http",
+      "url": "https://{your-workspace-url}/mcp"
+    }
+  }
+}
+```
+
+Das ist alles — kein API-Schlüssel erforderlich. Wenn der Client sich zum ersten Mal verbindet, wird er:
+
+1. Die OAuth-Metadaten von Twenty über `/.well-known/oauth-protected-resource` und `/.well-known/oauth-authorization-server` ermitteln
+2. Sich über die dynamische Client-Registrierung (RFC 7591) als OAuth-Client registrieren
+3. Ihren Browser öffnen, um den Zugriff zu autorisieren
+4. Token empfangen und eine Verbindung zum MCP-Server herstellen
+
+Nachfolgende Verbindungen verwenden die gespeicherten Token erneut und erneuern sie automatisch.
+
+### Option B — API-Schlüssel
+
+Wenn Ihr MCP-Client OAuth nicht unterstützt oder Sie statische Anmeldeinformationen bevorzugen, übergeben Sie einen API-Schlüssel im `Authorization`-Header:
+
+```json
+{
+  "mcpServers": {
+    "twenty": {
+      "type": "streamable-http",
+      "url": "https://{your-workspace-url}/mcp",
+      "headers": {
+        "Authorization": "Bearer YOUR_API_KEY"
+      }
+    }
+  }
+}
+```
+
+<Warning>
+Ihr API-Schlüssel gewährt Zugriff auf Workspace-Daten. Halten Sie es von der Versionskontrolle und von gemeinsam genutzten Dotfiles fern.
+</Warning>
+
+Um einen API-Schlüssel zu erstellen, gehen Sie zu **Settings > APIs & Webhooks > + Create key**. Details finden Sie unter [APIs](/l/de/developers/extend/api#create-an-api-key).
+
+## Schnellstart
+
+### 1. Konfiguration kopieren
+
+Gehen Sie in Twenty zu **Settings > AI > More > MCP Server**. Wählen Sie Ihre Authentifizierungsmethode (OAuth oder API-Schlüssel), kopieren Sie das JSON-Snippet (es verwendet bereits Ihre Workspace-URL) und fügen Sie es in die Konfigurationsdatei Ihres MCP-Clients ein.
+
+| Client             | Speicherort der Konfigurationsdatei                                                                                                                                                              |
+| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| **Claude Desktop** | `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) oder `%APPDATA%\Claude\claude_desktop_config.json` (Windows)                                                           |
+| **Claude Code**    | `~/.claude.json` (Benutzer) oder `.mcp.json` (Projekt)                                                                                                                                           |
+| **Cursor**         | `.cursor/mcp.json` in Ihrem Projekt oder `~/.cursor/mcp.json` global                                                                                                                             |
+| **ChatGPT**        | Aktivieren Sie den Entwicklermodus in **Settings > Apps & Connectors > Advanced settings** und verwenden Sie dann **Create** in **Settings > Apps & Connectors**, um den MCP-Server hinzuzufügen |
+
+### 2. Verbinden
+
+Starten Sie Ihren MCP-Client neu (oder laden Sie die Konfiguration neu). Bei Verwendung von OAuth werden Sie zu Twenty weitergeleitet, um den Zugriff zu autorisieren. Bei Verwendung eines API-Schlüssels wird die Verbindung sofort hergestellt.
+
+### 3. Jetzt loslegen
+
+Bitten Sie Ihren KI-Assistenten, mit Ihrem CRM zu interagieren:
+
+* *"Zeige mir die 5 zuletzt erstellten Unternehmen"*
+* *"Erstelle eine neue Person namens Jane Doe bei Acme Corp"*
+* *"Finde alle offenen Verkaufschancen mit einem Wert von mehr als $10k"*
+
+## Verfügbare Tools
+
+Nach der Verbindung stellt der MCP-Server Tools bereit, die die Twenty-API widerspiegeln. Der empfohlene Workflow ist:
+
+1. **`get_tool_catalog`** — alle verfügbaren Tools entdecken
+2. **`learn_tools`** — das Eingabeschema für bestimmte Tools abrufen
+3. **`execute_tool`** — ein Tool ausführen
+
+Sie müssen sich die Tool-Namen nicht merken. Fragen Sie Ihren KI-Assistenten, was er tun kann, und er ruft `get_tool_catalog` automatisch auf.
+
+## Berechtigungen
+
+MCP-Verbindungen erben die Berechtigungen des authentifizierten Benutzers (OAuth) oder die dem API-Schlüssel zugewiesene Rolle. So beschränken Sie, was der MCP-Server tun darf:
+
+* **OAuth**: Es gilt die Workspace-Rolle des Benutzers.
+* **API-Schlüssel**: Weisen Sie dem API-Schlüssel unter **Settings > Roles** eine Rolle zu. Siehe [Berechtigungen](/l/de/user-guide/permissions-access/capabilities/permissions).
+
+## Selbstgehostete Konfiguration
+
+Für selbstgehostete Instanzen ersetzen Sie `{your-workspace-url}` durch die URL Ihres Servers. Stellen Sie sicher, dass `SERVER_URL` in Ihrer Umgebung der öffentlichen URL Ihrer Twenty-Instanz entspricht — dieser Wert wird verwendet, um die OAuth-Discovery-Metadaten zu generieren.
+
+```bash
+SERVER_URL=https://twenty.yourcompany.com
+```
+
+Der MCP-Endpunkt, die OAuth-Endpunkte und die Discovery-Metadaten leiten sich alle von diesem Wert ab.
+
+## Fehlerbehebung
+
+**"Unauthorized"- oder 401-Fehler**
+
+* OAuth: Autorisieren Sie erneut, indem Sie die gespeicherten Token in Ihrem MCP-Client löschen und die Verbindung wiederherstellen.
+* API-Schlüssel: Überprüfen Sie, ob der Schlüssel gültig ist und nicht abgelaufen ist. Generieren Sie ihn bei Bedarf neu.
+
+**Der OAuth-Flow öffnet keinen Browser**
+
+* Stellen Sie sicher, dass Ihr MCP-Client MCP Authorization unterstützt. Wechseln Sie andernfalls zur API-Schlüssel-Methode.
+
+**Verbindungszeitüberschreitung**
+
+* Stellen Sie sicher, dass die MCP-Endpunkt-URL von Ihrem Rechner aus erreichbar ist. Bei selbstgehosteten Instanzen prüfen Sie, ob der Server läuft und `SERVER_URL` korrekt gesetzt ist.
@@ -6,7 +6,7 @@ description: La guida per i collaboratori (o sviluppatori curiosi) che vogliono
 ## Prerequisiti

 <Tabs>
-<Tab title="Linux e MacOS">
+<Tab title="Linux e macOS">

 Prima di poter installare e usare Twenty, assicurati di installare quanto segue sul tuo computer:
 * [Git](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git)
@@ -129,8 +129,8 @@ Dovresti eseguire tutti i comandi nei passaggi successivi dalla radice del proge
      brew services list
    ```

-    L'installatore potrebbe non creare l'utente `postgres` di default quando si installa
-    tramite Homebrew su MacOS. Invece, crea un ruolo di PostgreSQL che corrisponde al tuo nome utente macOS
+    Il programma di installazione potrebbe non creare l'utente `postgres` per impostazione predefinita quando si installa
+    tramite Homebrew su macOS. Invece, crea un ruolo di PostgreSQL che corrisponde al tuo nome utente macOS
    (es., "john").
    Per controllare e creare l'utente `postgres` se necessario, segui questi passaggi:
    ```bash
@@ -174,7 +174,7 @@ Dovresti eseguire tutti i comandi nei passaggi successivi dalla radice del proge
    Tutti i passaggi seguenti devono essere eseguiti nel terminale WSL (all'interno della tua macchina virtuale)

    **Opzione 1:** Per predisporre PostgreSQL in locale:
-    Usa il seguente link per installare PostgreSQL nella tua macchina virtuale Linux: [Installazione di PostgreSQL](https://www.postgresql.org/download/linux/)
+    Usa il seguente link per installare PostgreSQL sulla tua macchina virtuale Linux: [Installazione di PostgreSQL](https://www.postgresql.org/download/linux/)
    ```bash
      psql postgres -c "CREATE DATABASE \"default\";" -c "CREATE DATABASE test;"
    ```
@@ -189,11 +189,13 @@ Dovresti eseguire tutti i comandi nei passaggi successivi dalla radice del proge
  </Tab>
 </Tabs>

-Puoi ora accedere al database su [localhost:5432](localhost:5432), con utente `postgres` e password `postgres`.
+Ora puoi accedere al database all'indirizzo `localhost:5432`.
+
+Se hai utilizzato l'opzione Docker sopra, le credenziali predefinite sono utente `postgres` e password `postgres`. Per le installazioni native di PostgreSQL, usa le credenziali e i ruoli configurati sulla tua macchina.

 ## Passaggio 4: Configura un database Redis (cache)

-Twenty richiede una cache Redis per offrire le migliori prestazioni
+Twenty richiede una cache Redis per offrire le migliori prestazioni.

 <Tabs>
  <Tab title="Linux">
@@ -211,7 +213,9 @@ Twenty richiede una cache Redis per offrire le migliori prestazioni
    brew install redis
    ```
    Avvia il tuo server Redis:
-    `brew services start redis`
+    ```bash
+    brew services start redis
+    ```

    **Opzione 2:** Se hai Docker installato:
    ```bash
@@ -229,11 +233,11 @@ Twenty richiede una cache Redis per offrire le migliori prestazioni
  </Tab>
 </Tabs>

-Se hai bisogno di una GUI client, ti consigliamo [Redis Insight](https://redis.io/insight/) (versione gratuita disponibile)
+Se hai bisogno di una GUI client, ti consigliamo [Redis Insight](https://redis.io/insight/) (versione gratuita disponibile).

 ## Passaggio 5: Configura le variabili d'ambiente

-Usa variabili d'ambiente o file `.env` per configurare il tuo progetto. Maggiori informazioni [qui](/l/it/developers/self-host/capabilities/setup)
+Usa variabili d'ambiente o file `.env` per configurare il tuo progetto. Maggiori informazioni [qui](/l/it/developers/self-host/capabilities/setup).

 Copia i file `.env.example` in `/front` e `/server`:

@@ -21,19 +21,51 @@ Le app ti consentono di creare e gestire le personalizzazioni di Twenty **come c
 ## Prerequisiti

 * Node.js 24+ e Yarn 4
-* Uno spazio di lavoro Twenty e una chiave API (creane una su https://app.twenty.com/settings/api-webhooks)
+* Docker (per il server di sviluppo locale di Twenty)

 ## Per iniziare

-Crea una nuova app utilizzando lo scaffolder ufficiale, quindi autenticati e inizia a sviluppare:
+Crea una nuova app utilizzando lo scaffolder ufficiale. Può avviare automaticamente un'istanza locale di Twenty per te:

 ```bash filename="Terminal"
-# Crea lo scaffold di una nuova app (include tutti gli esempi per impostazione predefinita)
+# Crea lo scaffold di una nuova app — la CLI offrirà di avviare un server locale di Twenty
 npx create-twenty-app@latest my-twenty-app
 cd my-twenty-app

 # Avvia la modalità di sviluppo: sincronizza automaticamente le modifiche locali con il tuo workspace
-yarn twenty app:dev
+yarn twenty dev
+```
+
+### Gestione del server locale
+
+L'SDK include comandi per gestire un server di sviluppo locale di Twenty (immagine Docker all-in-one con PostgreSQL, Redis, server e worker):
+
+```bash filename="Terminal"
+# Avvia il server locale (scarica l'immagine se necessario)
+yarn twenty server start
+
+# Verifica lo stato del server
+yarn twenty server status
+
+# Segui i log del server
+yarn twenty server logs
+
+# Arresta il server
+yarn twenty server stop
+
+# Reimposta tutti i dati e riparti da zero
+yarn twenty server reset
+```
+
+Il server locale è preconfigurato con uno spazio di lavoro e un utente (`tim@apple.dev` / `tim@apple.dev`), così puoi iniziare a sviluppare immediatamente senza alcuna configurazione manuale.
+
+### Autenticazione
+
+Collega la tua app al server locale tramite OAuth:
+
+```bash filename="Terminal"
+# Autenticati tramite OAuth (apre il browser)
+yarn twenty remote add --local
 ```

 Lo strumento di scaffolding supporta due modalità per controllare quali file di esempio vengono inclusi:
@@ -64,6 +96,12 @@ yarn twenty function:execute --preInstall
 # Esegui la funzione post-installazione
 yarn twenty function:execute --postInstall

+# Compila l'app per la distribuzione
+yarn twenty app:build
+
+# Pubblica l'app su npm o su un server Twenty
+yarn twenty app:publish
+
 # Disinstalla l'applicazione dallo spazio di lavoro corrente
 yarn twenty app:uninstall

@@ -1240,6 +1278,113 @@ Punti chiave:

 Esplora un esempio minimale end-to-end che dimostra oggetti, funzioni logiche, componenti front-end e trigger multipli [qui](https://github.com/twentyhq/twenty/tree/main/packages/twenty-apps/hello-world):

+## Compilazione della tua app
+
+Una volta che hai sviluppato la tua app con `app:dev`, usa `app:build` per compilarla in un pacchetto distribuibile.
+
+```bash filename="Terminal"
+# Compila l'app (l'output va in .twenty/output/)
+yarn twenty app:build
+
+# Compila e crea un tarball (.tgz) per la distribuzione
+yarn twenty app:build --tarball
+```
+
+Il processo di compilazione:
+
+1. **Analizza e convalida il manifest** — legge tutte le entità `defineX()` dai tuoi file sorgente e convalida la struttura del manifest.
+2. **Compila le funzioni di logica e i componenti front-end** — raggruppa i sorgenti TypeScript in file ESM `.mjs` usando esbuild.
+3. **Genera i checksum** — calcola gli hash MD5 per ogni file compilato, memorizzati nel manifest come `builtHandlerChecksum` / `builtComponentChecksum`.
+4. **Genera il client API tipizzato** — esegue l'analisi dello schema GraphQL e genera i client tipizzati `CoreApiClient` e `MetadataApiClient`.
+5. **Esegue un controllo dei tipi di TypeScript** — esegue `tsc --noEmit` per intercettare gli errori di tipo prima della pubblicazione.
+6. **Ricompila con il client generato** — esegue una seconda passata di compilazione in modo da includere i tipi del client generato.
+7. **Crea facoltativamente un tarball** — se viene passato `--tarball`, esegue `npm pack` per creare un file `.tgz` pronto per la distribuzione.
+
+L'output della build in `.twenty/output/` contiene:
+
+```text
+.twenty/output/
+├── manifest.json              # Manifest con checksum per tutti i file compilati
+├── package.json               # Copiato dalla radice dell'app
+├── yarn.lock                  # Copiato dalla radice dell'app
+├── src/
+│   ├── logic-functions/       # File .mjs compilati delle funzioni logiche
+│   └── front-components/      # File .mjs compilati dei componenti front-end
+├── public/                    # Asset statici (se presenti)
+└── my-app-1.0.0.tgz          # Solo con il flag --tarball
+```
+
+| Opzione     | Descrizione                                                         |
+| ----------- | ------------------------------------------------------------------- |
+| `[appPath]` | Percorso della directory dell'app (predefinito: directory corrente) |
+| `--tarball` | Imballa anche l'output in un tarball `.tgz`                         |
+
+## Pubblicazione della tua app
+
+Usa `app:publish` per distribuire la tua app — al registro npm oppure direttamente a un server Twenty.
+
+### Pubblica su npm (predefinito)
+
+```bash filename="Terminal"
+# Pubblica su npm (richiede l'accesso a npm)
+yarn twenty app:publish
+
+# Pubblica con un dist-tag (ad es. beta, next)
+yarn twenty app:publish --tag beta
+```
+
+Questo compila l'app ed esegue `npm publish` dalla directory `.twenty/output/`. Il pacchetto pubblicato può quindi essere installato dal marketplace di Twenty da qualsiasi area di lavoro.
+
+### Pubblica su un server Twenty
+
+```bash filename="Terminal"
+# Pubblica direttamente su un server Twenty
+yarn twenty app:publish --server https://app.twenty.com
+```
+
+Questo compila l'app con un tarball, lo carica sul server tramite la mutation GraphQL `uploadAppTarball` e avvia l'installazione in un unico passaggio. Questo è utile per distribuzioni private o per effettuare test su un server specifico.
+
+| Opzione           | Descrizione                                                                |
+| ----------------- | -------------------------------------------------------------------------- |
+| `[appPath]`       | Percorso della directory dell'app (predefinito: directory corrente)        |
+| `--server <url>`  | Pubblica su un server Twenty invece di npm                                 |
+| `--token <token>` | Token di autenticazione per il server di destinazione                      |
+| `--tag <tag>`     | dist-tag di npm (ad es. `beta`, `next`) — solo per la pubblicazione su npm |
+
+## Registrazione dell'applicazione
+
+Prima che un'app possa essere installata in un'area di lavoro, deve essere **registrata**. Una registrazione è un record di metadati che descrive l'origine dell'app e come autenticarla. Nella maggior parte dei casi questo è gestito automaticamente dalla CLI.
+
+### Tipi di origine
+
+Ogni registrazione ha un **tipo di origine** che determina come vengono risolti i file dell'app durante l'installazione:
+
+| Tipo di origine | Come vengono risolti i file                                                                    | Caso d'uso tipico                     |
+| --------------- | ---------------------------------------------------------------------------------------------- | ------------------------------------- |
+| `LOCAL`         | I file sono sincronizzati in tempo reale dal watcher della CLI — l'installazione viene saltata | Sviluppo con `app:dev`                |
+| `NPM`           | Recuperati dal registro npm tramite il campo `sourcePackage`                                   | App pubblicate su npm                 |
+| `TARBALL`       | Estratti da un file `.tgz` caricato e archiviato sul server                                    | App private pubblicate con `--server` |
+
+### Come avviene la registrazione
+
+* **`app:dev`** — crea automaticamente una registrazione `LOCAL` la prima volta che esegui la modalità di sviluppo su un'area di lavoro.
+* **`app:publish --server`** — carica un tarball e crea (o aggiorna) una registrazione `TARBALL`, quindi installa l'app.
+* **Marketplace npm** — le registrazioni `NPM` vengono create quando le app vengono sincronizzate dal registro npm nel catalogo del marketplace di Twenty.
+* **GraphQL API** — puoi anche creare registrazioni in modo programmatico tramite la mutation `createApplicationRegistration`.
+
+### Registrazione vs installazione
+
+**Registrazione** e **installazione** sono concetti distinti:
+
+* Una **registrazione** (`ApplicationRegistration`) è un record di metadati globale che descrive l'app: il suo nome, il tipo di origine, le credenziali OAuth e lo stato di pubblicazione nel marketplace. Esiste indipendentemente da qualsiasi area di lavoro.
+* Un'**installazione** (`Application`) è un'istanza per area di lavoro. Quando un utente installa un'app, Twenty risolve il pacchetto dalla sorgente della registrazione, scrive i file compilati nell'archiviazione e sincronizza il manifest (creando oggetti, campi, funzioni logiche, ecc.) in quell'area di lavoro.
+
+Una registrazione può essere installata in molte aree di lavoro. Ogni area di lavoro ottiene la propria copia dei file dell'app e del modello di dati.
+
+### Credenziali OAuth
+
+Ogni registrazione include credenziali OAuth (`oAuthClientId` e `oAuthClientSecret`) generate al momento della creazione. Queste vengono utilizzate dall'app per autenticare le richieste API per conto degli utenti. Il client secret viene restituito **una sola volta** alla creazione — conservalo in modo sicuro. Puoi ruotarlo in seguito tramite la mutation `rotateApplicationRegistrationClientSecret`.
+
 ## Configurazione manuale (senza lo scaffolder)

 Sebbene consigliamo di utilizzare `create-twenty-app` per la migliore esperienza iniziale, puoi anche configurare un progetto manualmente. Non installare la CLI globalmente. Invece, aggiungi `twenty-sdk` come dipendenza locale e collega un unico script nel tuo package.json:
@@ -3,7 +3,7 @@ title: 1-Click con Docker Compose
 ---

 <Warning>
-I container Docker sono per hosting in produzione o auto-hosting, per il contributo consulta il [Setup Locale](/l/it/developers/contribute/capabilities/local-setup).
+I container Docker sono destinati all'hosting in produzione o al self-hosting. Per contribuire, consulta [Configurazione locale](/l/it/developers/contribute/capabilities/local-setup).
 </Warning>

 ## Panoramica
@@ -12,7 +12,7 @@ Questa guida fornisce istruzioni passo passo per installare e configurare l'appl

 **Importante:** Modifica solo le impostazioni esplicitamente menzionate in questa guida. Modificare altre configurazioni potrebbe portare a problemi.

-Consulta i documenti [Configurazione delle Variabili di Ambiente](/l/it/developers/self-host/capabilities/setup) per configurazioni avanzate. Tutte le variabili di ambiente devono essere dichiarate nel file docker-compose.yml a livello di server e/o di worker a seconda della variabile.
+Consulta [Configurazione delle variabili di ambiente](/l/it/developers/self-host/capabilities/setup) per configurazioni avanzate. Tutte le variabili di ambiente devono essere dichiarate nel file `docker-compose.yml` a livello di server e/o di worker, a seconda della variabile.

 ## Requisiti di Sistema

@@ -0,0 +1,142 @@
+---
+title: Server MCP
+description: Collega gli assistenti AI al tuo spazio di lavoro di Twenty utilizzando il Model Context Protocol.
+---
+
+<Warning>
+MCP è attualmente in **alpha** ed è disponibile solo su alcuni spazi di lavoro. Potrebbe non essere ancora abilitato per il tuo spazio di lavoro.
+</Warning>
+
+Twenty espone un server [MCP](https://modelcontextprotocol.io/) affinché gli assistenti AI — Claude Desktop, Claude Code, Cursor, ChatGPT e altri — possano leggere e scrivere i dati del tuo CRM in linguaggio naturale.
+
+Usa l'**URL dello spazio di lavoro** (l'URL che usi per accedere a Twenty) come endpoint MCP. Su Twenty Cloud, l'URL del tuo spazio di lavoro potrebbe essere `https://{mycompany}.twenty.com` oppure un dominio personalizzato. Il server è disponibile all'indirizzo:
+
+| Ambiente          | Endpoint MCP                                                                   |
+| ----------------- | ------------------------------------------------------------------------------ |
+| **Cloud**         | `https://{your-workspace-url}/mcp` (ad es. `https://mycompany.twenty.com/mcp`) |
+| **Auto-ospitato** | `https://{your-domain}/mcp`                                                    |
+
+## Metodi di autenticazione
+
+Hai due modi per autenticare il tuo client MCP: **OAuth** (consigliato) o **API Key**.
+
+### Opzione A — OAuth (Consigliato)
+
+Con OAuth, il tuo client MCP apre una finestra del browser per effettuare l'accesso. Nessun segreto viene archiviato nei file di configurazione e i token si rinnovano automaticamente.
+
+<Note>
+OAuth richiede un client MCP che supporti la [specifica MCP Authorization](https://modelcontextprotocol.io/specification/2025-03-26/basic/authorization). Claude Desktop, Claude Code, Cursor e ChatGPT lo supportano.
+</Note>
+
+Aggiungi questo alla configurazione del tuo client MCP, sostituendo `{your-workspace-url}` con l'host del tuo spazio di lavoro (ad es. `mycompany.twenty.com`):
+
+```json
+{
+  "mcpServers": {
+    "twenty": {
+      "type": "streamable-http",
+      "url": "https://{your-workspace-url}/mcp"
+    }
+  }
+}
+```
+
+È tutto — non è necessaria alcuna chiave API. Quando il client si connette per la prima volta, eseguirà:
+
+1. Scoprire i metadati OAuth di Twenty tramite `/.well-known/oauth-protected-resource` e `/.well-known/oauth-authorization-server`
+2. Registrarsi come client OAuth tramite registrazione dinamica del client (RFC 7591)
+3. Aprire il browser per autorizzare l'accesso
+4. Ricevere i token e connettersi al server MCP
+
+Le connessioni successive riutilizzano i token memorizzati e li rinnovano automaticamente.
+
+### Opzione B — Chiave API
+
+Se il tuo client MCP non supporta OAuth, o preferisci credenziali statiche, passa una chiave API nell'header `Authorization`:
+
+```json
+{
+  "mcpServers": {
+    "twenty": {
+      "type": "streamable-http",
+      "url": "https://{your-workspace-url}/mcp",
+      "headers": {
+        "Authorization": "Bearer YOUR_API_KEY"
+      }
+    }
+  }
+}
+```
+
+<Warning>
+La tua chiave API concede l'accesso ai dati dello spazio di lavoro. Mantienila fuori dal controllo versione e dai dotfile condivisi.
+</Warning>
+
+Per creare una chiave API, vai su **Impostazioni > API e Webhook > + Crea chiave**. Vedi [API](/l/it/developers/extend/api#create-an-api-key) per i dettagli.
+
+## Avvio rapido
+
+### 1. Copia la configurazione
+
+Vai su **Impostazioni > AI > Altro > MCP Server** in Twenty. Scegli il metodo di autenticazione (OAuth o Chiave API), copia lo snippet JSON (userà già l'URL del tuo spazio di lavoro) e incollalo nel file di configurazione del tuo client MCP.
+
+| Client             | Percorso del file di configurazione                                                                                                                                                     |
+| ------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **Claude Desktop** | `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) o `%APPDATA%\Claude\claude_desktop_config.json` (Windows)                                                     |
+| **Claude Code**    | `~/.claude.json` (utente) o `.mcp.json` (progetto)                                                                                                                                      |
+| **Cursor**         | `.cursor/mcp.json` nel tuo progetto, oppure `~/.cursor/mcp.json` globalmente                                                                                                            |
+| **ChatGPT**        | Attiva la Modalità sviluppatore in **Impostazioni > App e Connettori > Impostazioni avanzate**, quindi usa **Crea** in **Impostazioni > App e Connettori** per aggiungere il server MCP |
+
+### 2. Connetti
+
+Riavvia il tuo client MCP (o ricarica la configurazione). Se usi OAuth verrai reindirizzato a Twenty per autorizzare l'accesso. Se usi una chiave API la connessione è immediata.
+
+### 3. Inizia a usarlo
+
+Chiedi al tuo assistente AI di interagire con il tuo CRM:
+
+* *"Mostrami le 5 aziende create più di recente"*
+* *"Crea una nuova persona di nome Jane Doe presso Acme Corp"*
+* *"Trova tutte le opportunità aperte di valore superiore a $10k"*
+
+## Strumenti disponibili
+
+Una volta connesso, il server MCP espone strumenti che rispecchiano l'API di Twenty. Il flusso di lavoro consigliato è:
+
+1. **`get_tool_catalog`** — scoprire tutti gli strumenti disponibili
+2. **`learn_tools`** — ottenere lo schema di input per strumenti specifici
+3. **`execute_tool`** — eseguire uno strumento
+
+Non è necessario ricordare i nomi degli strumenti. Chiedi al tuo assistente AI cosa può fare e chiamerà `get_tool_catalog` automaticamente.
+
+## Permessi
+
+Le connessioni MCP ereditano le autorizzazioni dell'utente autenticato (OAuth) o il ruolo assegnato alla chiave API. Per limitare ciò che il server MCP può fare:
+
+* **OAuth**: si applica il ruolo dell'utente nello spazio di lavoro.
+* **Chiave API**: assegna un ruolo alla chiave API in **Impostazioni > Ruoli**. Vedi [Autorizzazioni](/l/it/user-guide/permissions-access/capabilities/permissions).
+
+## Configurazione self-hosted
+
+Per le istanze self-hosted, sostituisci `{your-workspace-url}` con l'URL del tuo server. Assicurati che `SERVER_URL` nel tuo ambiente corrisponda all'URL pubblico della tua istanza Twenty — viene utilizzato per generare i metadati di discovery OAuth.
+
+```bash
+SERVER_URL=https://twenty.yourcompany.com
+```
+
+L'endpoint MCP, gli endpoint OAuth e i metadati di discovery derivano tutti da questo valore.
+
+## Risoluzione dei problemi
+
+**Errori "Unauthorized" o 401**
+
+* OAuth: esegui nuovamente l'autorizzazione eliminando i token memorizzati nel tuo client MCP e riconnettiti.
+* Chiave API: verifica che la chiave sia valida e non sia scaduta. Rigenerala se necessario.
+
+**Il flusso OAuth non apre il browser**
+
+* Assicurati che il tuo client MCP supporti MCP Authorization. In caso contrario, ricorri al metodo con Chiave API.
+
+**Timeout di connessione**
+
+* Verifica che l'URL dell'endpoint MCP sia raggiungibile dalla tua macchina. Per le istanze self-hosted, controlla che il server sia in esecuzione e che `SERVER_URL` sia impostato correttamente.
@@ -6,7 +6,7 @@ description: O guia para contribuidores (ou desenvolvedores curiosos) que deseja
 ## Pré-requisitos

 <Tabs>
-<Tab title="Linux e MacOS">
+<Tab title="Linux e macOS">

 Antes de instalar e usar o Twenty, certifique-se de instalar o seguinte em seu computador:
 * [Git](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git)
@@ -30,7 +30,7 @@ wsl --install
 ```
 Você deve agora ver um aviso para reiniciar o computador. Caso contrário, reinicie-o manualmente.

-Ao reiniciar, uma janela do powershell será aberta e instalará o Ubuntu. Isso pode levar algum tempo.
+Ao reiniciar, uma janela do PowerShell será aberta e instalará o Ubuntu. Isso pode levar algum tempo.
 Você verá uma solicitação para criar um nome de usuário e senha para sua instalação do Ubuntu.

 2. Instalar e configurar o git
@@ -102,8 +102,8 @@ Você deve executar todos os comandos nas etapas seguintes a partir da raiz do p

 <Tabs>
  <Tab title="Linux">
-    **Opção 1 (preferencial):** Para prover seu banco de dados localmente:
-    Use o seguinte link para instalar o Postgresql na sua máquina Linux: [Instalação do Postgresql](https://www.postgresql.org/download/linux/)
+    **Opção 1 (preferencial):** Para provisionar seu banco de dados localmente:
+    Use o seguinte link para instalar o PostgreSQL na sua máquina Linux: [Instalação do PostgreSQL](https://www.postgresql.org/download/linux/)
    ```bash
      psql postgres -c "CREATE DATABASE \"default\";" -c "CREATE DATABASE test;"
    ```
@@ -130,7 +130,7 @@ Você deve executar todos os comandos nas etapas seguintes a partir da raiz do p
    ```

    O instalador pode não criar o usuário `postgres` por padrão ao instalar
-    via Homebrew no MacOS. Em vez disso, ele cria uma função PostgreSQL que corresponde ao seu nome de usuário do macOS
+    via Homebrew no macOS. Em vez disso, ele cria uma função PostgreSQL que corresponde ao seu nome de usuário do macOS
    (por exemplo, "john").
    Para verificar e criar o usuário `postgres`, se necessário, siga estas etapas:
    ```bash
@@ -173,8 +173,8 @@ Você deve executar todos os comandos nas etapas seguintes a partir da raiz do p
  <Tab title="Windows (WSL)">
    Todos os passos a seguir devem ser executados no terminal WSL (dentro da sua máquina virtual)

-    **Opção 1:** Para provisionar seu Postgresql localmente:
-    Use o seguinte link para instalar o Postgresql em sua máquina virtual Linux: [Instalação do Postgresql](https://www.postgresql.org/download/linux/)
+    **Opção 1:** Para provisionar seu PostgreSQL localmente:
+    Use o seguinte link para instalar o PostgreSQL na sua máquina virtual Linux: [Instalação do PostgreSQL](https://www.postgresql.org/download/linux/)
    ```bash
      psql postgres -c "CREATE DATABASE \"default\";" -c "CREATE DATABASE test;"
    ```
@@ -189,11 +189,13 @@ Você deve executar todos os comandos nas etapas seguintes a partir da raiz do p
  </Tab>
 </Tabs>

-Você pode agora acessar o banco de dados em [localhost:5432](localhost:5432), com o usuário `postgres` e senha `postgres`.
+Agora você pode acessar o banco de dados em `localhost:5432`.
+
+Se você usou a opção do Docker acima, as credenciais padrão são usuário `postgres` e senha `postgres`. Para instalações nativas do PostgreSQL, use as credenciais e os papéis configurados na sua máquina.

 ## Passo 4: Configurar um Banco de Dados Redis (cache)

-O Twenty requer um cache redis para oferecer o melhor desempenho
+O Twenty requer um cache Redis para oferecer o melhor desempenho.

 <Tabs>
  <Tab title="Linux">
@@ -210,8 +212,10 @@ O Twenty requer um cache redis para oferecer o melhor desempenho
    ```bash
    brew install redis
    ```
-    Inicie seu servidor redis:
-    `brew services start redis`
+    Inicie o servidor Redis:
+    ```bash
+    brew services start redis
+    ```

    **Opção 2:** Se você tem o docker instalado:
    ```bash
@@ -229,11 +233,11 @@ O Twenty requer um cache redis para oferecer o melhor desempenho
  </Tab>
 </Tabs>

-Se precisar de uma GUI de Cliente, recomendamos o [redis insight](https://redis.io/insight/) (versão gratuita disponível)
+Se você precisar de uma GUI de cliente, recomendamos o [Redis Insight](https://redis.io/insight/) (versão gratuita disponível).

 ## Passo 5: Configurar variáveis de ambiente

-Use variáveis de ambiente ou arquivos `.env` para configurar seu projeto. Mais informações [aqui](/l/pt/developers/self-host/capabilities/setup)
+Use variáveis de ambiente ou arquivos `.env` para configurar seu projeto. Mais informações [aqui](/l/pt/developers/self-host/capabilities/setup).

 Copie os arquivos `.env.example` em `/front` e `/server`:

@@ -21,19 +21,51 @@ Os aplicativos permitem criar e gerenciar personalizações do Twenty **como có
 ## Pré-requisitos

 * Node.js 24+ e Yarn 4
-* Um espaço de trabalho do Twenty e uma chave de API (crie uma em https://app.twenty.com/settings/api-webhooks)
+* Docker (para o servidor de desenvolvimento local do Twenty)

 ## Primeiros passos

-Crie um novo aplicativo usando o gerador oficial, depois autentique-se e comece a desenvolver:
+Crie um novo app usando o gerador oficial de estrutura. Ele pode iniciar automaticamente uma instância local do Twenty para você:

 ```bash filename="Terminal"
-# Criar a estrutura de um novo app (inclui todos os exemplos por padrão)
+# Criar a estrutura de um novo app — a CLI oferecerá iniciar um servidor local do Twenty
 npx create-twenty-app@latest my-twenty-app
 cd my-twenty-app

 # Iniciar modo de desenvolvimento: sincroniza automaticamente as alterações locais com seu workspace
-yarn twenty app:dev
+yarn twenty dev
+```
+
+### Gerenciamento do Servidor Local
+
+O SDK inclui comandos para gerenciar um servidor de desenvolvimento local do Twenty (imagem Docker all-in-one com PostgreSQL, Redis, servidor e worker):
+
+```bash filename="Terminal"
+# Iniciar o servidor local (faz pull da imagem se necessário)
+yarn twenty server start
+
+# Verificar o status do servidor
+yarn twenty server status
+
+# Transmitir os logs do servidor
+yarn twenty server logs
+
+# Parar o servidor
+yarn twenty server stop
+
+# Redefinir todos os dados e começar do zero
+yarn twenty server reset
+```
+
+O servidor local já vem pré-configurado com um espaço de trabalho e um usuário (`tim@apple.dev` / `tim@apple.dev`), para que você possa começar a desenvolver imediatamente, sem qualquer configuração manual.
+
+### Autenticação
+
+Conecte seu aplicativo ao servidor local usando OAuth:
+
+```bash filename="Terminal"
+# Authenticate via OAuth (opens browser)
+yarn twenty remote add --local
 ```

 O gerador de estrutura oferece suporte a dois modos para controlar quais arquivos de exemplo são incluídos:
@@ -49,25 +81,31 @@ npx create-twenty-app@latest my-app --minimal
 A partir daqui você pode:

 ```bash filename="Terminal"
-# Add a new entity to your application (guided)
+# Adicionar uma nova entidade à sua aplicação (assistido)
 yarn twenty entity:add

-# Watch your application's function logs
+# Acompanhar os logs das funções da sua aplicação
 yarn twenty function:logs

-# Execute a function by name
+# Executar uma função pelo nome
 yarn twenty function:execute -n my-function -p '{"name": "test"}'

-# Execute the pre-install function
+# Executar a função de pré-instalação
 yarn twenty function:execute --preInstall

-# Execute the post-install function
+# Executar a função de pós-instalação
 yarn twenty function:execute --postInstall

-# Uninstall the application from the current workspace
+# Compilar a aplicação para distribuição
+yarn twenty app:build
+
+# Publicar a aplicação no npm ou em um servidor Twenty
+yarn twenty app:publish
+
+# Desinstalar a aplicação do espaço de trabalho atual
 yarn twenty app:uninstall

-# Display commands' help
+# Exibir a ajuda dos comandos
 yarn twenty help
 ```

@@ -1241,6 +1279,113 @@ Pontos-chave:

 Explore um exemplo mínimo de ponta a ponta que demonstra objetos, funções de lógica, componentes de front-end e vários gatilhos [aqui](https://github.com/twentyhq/twenty/tree/main/packages/twenty-apps/hello-world):

+## Compilando seu app
+
+Depois de desenvolver seu app com `app:dev`, use `app:build` para compilá-lo em um pacote distribuível.
+
+```bash filename="Terminal"
+# Compilar o app (a saída vai para .twenty/output/)
+yarn twenty app:build
+
+# Compilar e criar um tarball (.tgz) para distribuição
+yarn twenty app:build --tarball
+```
+
+O processo de build:
+
+1. **Analisa e valida o manifesto** — lê todas as entidades `defineX()` dos seus arquivos de código-fonte e valida a estrutura do manifesto.
+2. **Compila funções de lógica e componentes de front-end** — empacota o código-fonte TypeScript em arquivos ESM `.mjs` usando o esbuild.
+3. **Gera checksums** — calcula hashes MD5 para cada arquivo gerado, armazenados no manifesto como `builtHandlerChecksum` / `builtComponentChecksum`.
+4. **Gera o cliente de API tipado** — inspeciona o esquema GraphQL e gera clientes tipados `CoreApiClient` e `MetadataApiClient`.
+5. **Executa uma verificação de tipos do TypeScript** — executa `tsc --noEmit` para detectar erros de tipo antes da publicação.
+6. **Reconstrói com o cliente gerado** — realiza uma segunda passagem de compilação para que os tipos do cliente gerado sejam incluídos.
+7. **Opcionalmente cria um tarball** — se `--tarball` for passado, executa `npm pack` para criar um arquivo `.tgz` pronto para distribuição.
+
+A saída da compilação em `.twenty/output/` contém:
+
+```text
+.twenty/output/
+├── manifest.json              # Manifesto com somas de verificação para todos os arquivos compilados
+├── package.json               # Copiado da raiz do aplicativo
+├── yarn.lock                  # Copiado da raiz do aplicativo
+├── src/
+│   ├── logic-functions/       # Arquivos .mjs compilados de funções de lógica
+│   └── front-components/      # Arquivos .mjs compilados de componentes de front-end
+├── public/                    # Recursos estáticos (se houver)
+└── my-app-1.0.0.tgz          # Apenas com a opção --tarball
+```
+
+| Opção       | Descrição                                                 |
+| ----------- | --------------------------------------------------------- |
+| `[appPath]` | Caminho para o diretório do app (padrão: diretório atual) |
+| `--tarball` | Também empacota a saída em um tarball `.tgz`              |
+
+## Publicando seu app
+
+Use `app:publish` para distribuir seu app — ou para o registro do npm ou diretamente para um servidor Twenty.
+
+### Publicar no npm (padrão)
+
+```bash filename="Terminal"
+# Publish to npm (requires npm login)
+yarn twenty app:publish
+
+# Publish with a dist-tag (e.g. beta, next)
+yarn twenty app:publish --tag beta
+```
+
+Isso compila o app e executa `npm publish` a partir do diretório `.twenty/output/`. O pacote publicado pode então ser instalado no marketplace da Twenty por qualquer espaço de trabalho.
+
+### Publicar em um servidor Twenty
+
+```bash filename="Terminal"
+# Publish directly to a Twenty server
+yarn twenty app:publish --server https://app.twenty.com
+```
+
+Isso compila o app com um tarball, faz o upload para o servidor via a mutação GraphQL `uploadAppTarball` e aciona a instalação em uma única etapa. Isso é útil para implantações privadas ou para testar em um servidor específico.
+
+| Opção             | Descrição                                                             |
+| ----------------- | --------------------------------------------------------------------- |
+| `[appPath]`       | Caminho para o diretório do app (padrão: diretório atual)             |
+| `--server <url>`  | Publicar em um servidor Twenty em vez de no npm                       |
+| `--token <token>` | Token de autenticação para o servidor de destino                      |
+| `--tag <tag>`     | dist-tag do npm (ex.: `beta`, `next`) — apenas para publicação no npm |
+
+## Registro de aplicação
+
+Antes que um app possa ser instalado em um espaço de trabalho, ele precisa ser **registrado**. Um registro é um registro de metadados que descreve de onde o app vem e como autenticá-lo. Isso é tratado automaticamente pela CLI na maioria dos casos.
+
+### Tipos de origem
+
+Cada registro tem um **tipo de origem** que determina como os arquivos do app são resolvidos durante a instalação:
+
+| Tipo de origem | Como os arquivos são resolvidos                                                             | Caso de uso típico                      |
+| -------------- | ------------------------------------------------------------------------------------------- | --------------------------------------- |
+| `LOCAL`        | Os arquivos são sincronizados em tempo real pelo observador da CLI — a instalação é omitida | Desenvolvimento com `app:dev`           |
+| `NPM`          | Obtidos do registro npm por meio do campo `sourcePackage`                                   | Apps publicados no npm                  |
+| `TARBALL`      | Extraídos de um arquivo `.tgz` enviado e armazenado no servidor                             | Apps privados publicados com `--server` |
+
+### Como o registro acontece
+
+* **`app:dev`** — cria automaticamente um registro `LOCAL` na primeira vez que você executa o modo de desenvolvimento em um espaço de trabalho.
+* **`app:publish --server`** — faz o upload de um tarball e cria (ou atualiza) um registro `TARBALL`, e em seguida instala o app.
+* **marketplace do npm** — registros `NPM` são criados quando apps são sincronizados do registro npm para o catálogo do marketplace da Twenty.
+* **API GraphQL** — você também pode criar registros programaticamente por meio da mutação `createApplicationRegistration`.
+
+### Registro vs instalação
+
+**Registro** e **instalação** são conceitos distintos:
+
+* Um **registro** (`ApplicationRegistration`) é um registro global de metadados que descreve o app: seu nome, tipo de origem, credenciais OAuth e status de listagem no marketplace. Ele existe independentemente de qualquer espaço de trabalho.
+* Uma **instalação** (`Application`) é uma instância por espaço de trabalho. Quando um usuário instala um app, a Twenty resolve o pacote a partir da origem do registro, grava os arquivos compilados no armazenamento e sincroniza o manifesto (criando objetos, campos, funções de lógica etc.). naquele espaço de trabalho.
+
+Um registro pode ser instalado em muitos espaços de trabalho. Cada espaço de trabalho recebe sua própria cópia dos arquivos e do modelo de dados do app.
+
+### Credenciais OAuth
+
+Cada registro inclui credenciais OAuth (`oAuthClientId` e `oAuthClientSecret`) geradas no momento da criação. Elas são usadas pelo app para autenticar requisições de API em nome dos usuários. O segredo do cliente é retornado **uma única vez** na criação — armazene-o com segurança. Você pode rotacioná-lo posteriormente por meio da mutação `rotateApplicationRegistrationClientSecret`.
+
 ## Configuração manual (sem o gerador)

 Embora recomendemos usar `create-twenty-app` para a melhor experiência inicial, você também pode configurar um projeto manualmente. Não instale a CLI globalmente. Em vez disso, adicione `twenty-sdk` como uma dependência local e configure um único script no seu package.json:
@@ -3,7 +3,7 @@ title: 1-Clique c/ Docker Compose
 ---

 <Warning>
-Contêineres Docker são para hospedagem de produção ou auto-hospedagem, para contribuições, por favor, verifique o [Setup Local](/l/pt/developers/contribute/capabilities/local-setup).
+Os contêineres Docker são para hospedagem em produção ou auto-hospedagem. Para contribuir, consulte a [Configuração local](/l/pt/developers/contribute/capabilities/local-setup).
 </Warning>

 ## Visão geral
@@ -12,7 +12,7 @@ Este guia fornece instruções passo a passo para instalar e configurar o aplica

 **Importante:** Modifique apenas as configurações explicitamente mencionadas neste guia. Alterar outras configurações pode levar a problemas.

-Veja a documentação [Configurar Variáveis de Ambiente](/l/pt/developers/self-host/capabilities/setup) para configuração avançada. Todas as variáveis de ambiente devem ser declaradas no arquivo docker-compose.yml no nível do servidor e/ou trabalhador, dependendo da variável.
+Consulte [Configurar Variáveis de Ambiente](/l/pt/developers/self-host/capabilities/setup) para configuração avançada. Todas as variáveis de ambiente devem ser declaradas no arquivo `docker-compose.yml` no nível do servidor e/ou do trabalhador, dependendo da variável.

 ## Requisitos do Sistema

@@ -0,0 +1,142 @@
+---
+title: Servidor MCP
+description: Conecte assistentes de IA ao seu espaço de trabalho do Twenty usando o Model Context Protocol.
+---
+
+<Warning>
+O MCP está atualmente em **alfa** e está disponível apenas em alguns espaços de trabalho. O MCP pode ainda não estar ativado no seu espaço de trabalho.
+</Warning>
+
+O Twenty expõe um servidor [MCP](https://modelcontextprotocol.io/) para que assistentes de IA — Claude Desktop, Claude Code, Cursor, ChatGPT e outros — possam ler e escrever seus dados de CRM por meio de linguagem natural.
+
+Use o **URL do espaço de trabalho** (o URL que você usa para acessar o Twenty) como o endpoint do MCP. Na Twenty Cloud, o URL do seu espaço de trabalho pode ser `https://{mycompany}.twenty.com` ou um domínio personalizado. O servidor está disponível em:
+
+| Ambiente           | Endpoint do MCP                                                                      |
+| ------------------ | ------------------------------------------------------------------------------------ |
+| **Nuvem**          | `https://{your-workspace-url}/mcp` (por exemplo, `https://mycompany.twenty.com/mcp`) |
+| **Auto-hospedado** | `https://{your-domain}/mcp`                                                          |
+
+## Métodos de autenticação
+
+Você tem duas maneiras de autenticar seu cliente MCP: **OAuth** (recomendado) ou **Chave de API**.
+
+### Opção A — OAuth (recomendado)
+
+Com o OAuth, seu cliente MCP abre uma janela do navegador para você fazer login. Nenhum segredo é armazenado em arquivos de configuração, e os tokens são atualizados automaticamente.
+
+<Note>
+O OAuth requer um cliente MCP que ofereça suporte à [especificação de Autorização MCP](https://modelcontextprotocol.io/specification/2025-03-26/basic/authorization). Claude Desktop, Claude Code, Cursor e ChatGPT oferecem suporte.
+</Note>
+
+Adicione isto à configuração do seu cliente MCP, substituindo `{your-workspace-url}` pelo host do seu espaço de trabalho (por exemplo, `mycompany.twenty.com`):
+
+```json
+{
+  "mcpServers": {
+    "twenty": {
+      "type": "streamable-http",
+      "url": "https://{your-workspace-url}/mcp"
+    }
+  }
+}
+```
+
+É isso — nenhuma chave de API é necessária. Quando o cliente se conectar pela primeira vez, ele irá:
+
+1. Descobrir os metadados de OAuth do Twenty por meio de `/.well-known/oauth-protected-resource` e `/.well-known/oauth-authorization-server`
+2. Registrar-se como um cliente OAuth por meio de registro dinâmico de cliente (RFC 7591)
+3. Abrir seu navegador para autorizar o acesso
+4. Receber tokens e conectar-se ao servidor MCP
+
+Conexões subsequentes reutilizam os tokens armazenados e os atualizam automaticamente.
+
+### Opção B — Chave de API
+
+Se o seu cliente MCP não oferecer suporte a OAuth, ou se você preferir credenciais estáticas, passe uma chave de API no cabeçalho `Authorization`:
+
+```json
+{
+  "mcpServers": {
+    "twenty": {
+      "type": "streamable-http",
+      "url": "https://{your-workspace-url}/mcp",
+      "headers": {
+        "Authorization": "Bearer YOUR_API_KEY"
+      }
+    }
+  }
+}
+```
+
+<Warning>
+Sua chave de API concede acesso aos dados do espaço de trabalho. Mantenha-a fora do controle de versão e de dotfiles compartilhados.
+</Warning>
+
+Para criar uma chave de API, vá em **Settings > APIs & Webhooks > + Create key**. Veja [APIs](/l/pt/developers/extend/api#create-an-api-key) para detalhes.
+
+## Início rápido
+
+### 1. Copie a configuração
+
+Vá até **Settings > AI > More > MCP Server** no Twenty. Escolha seu método de autenticação (OAuth ou Chave de API), copie o trecho de JSON (ele já usará o URL do seu espaço de trabalho) e cole-o no arquivo de configuração do seu cliente MCP.
+
+| Cliente            | Local do arquivo de configuração                                                                                                                                                   |
+| ------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **Claude Desktop** | `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) ou `%APPDATA%\Claude\claude_desktop_config.json` (Windows)                                               |
+| **Claude Code**    | `~/.claude.json` (usuário) ou `.mcp.json` (projeto)                                                                                                                                |
+| **Cursor**         | `.cursor/mcp.json` no seu projeto, ou `~/.cursor/mcp.json` globalmente                                                                                                             |
+| **ChatGPT**        | Ative o Modo Desenvolvedor em **Settings > Apps & Connectors > Advanced settings** e, em seguida, use **Create** em **Settings > Apps & Connectors** para adicionar o servidor MCP |
+
+### 2. Conectar
+
+Reinicie seu cliente MCP (ou recarregue a configuração). Se estiver usando OAuth, você será redirecionado ao Twenty para autorizar o acesso. Se estiver usando uma chave de API, a conexão é imediata.
+
+### 3. Comece a usá-lo
+
+Peça ao seu assistente de IA para interagir com seu CRM:
+
+* *"Mostre-me as 5 empresas criadas mais recentemente"*
+* *"Crie uma nova pessoa chamada Jane Doe na Acme Corp"*
+* *"Encontre todas as oportunidades em aberto com valor superior a $10k"*
+
+## Ferramentas disponíveis
+
+Depois de conectado, o servidor MCP expõe ferramentas que refletem a API do Twenty. O fluxo de trabalho recomendado é:
+
+1. **`get_tool_catalog`** — descobrir todas as ferramentas disponíveis
+2. **`learn_tools`** — obter o esquema de entrada para ferramentas específicas
+3. **`execute_tool`** — executar uma ferramenta
+
+Você não precisa se lembrar dos nomes das ferramentas. Pergunte ao seu assistente de IA o que ele pode fazer e ele chamará `get_tool_catalog` automaticamente.
+
+## Permissões
+
+As conexões MCP herdam as permissões do usuário autenticado (OAuth) ou da função atribuída à chave de API. Para restringir o que o servidor MCP pode fazer:
+
+* **OAuth**: Aplica-se à função do espaço de trabalho do usuário.
+* **Chave de API**: Atribua uma função à chave de API em **Settings > Roles**. Veja [Permissões](/l/pt/user-guide/permissions-access/capabilities/permissions).
+
+## Configuração auto-hospedada
+
+Para instâncias auto-hospedadas, substitua `{your-workspace-url}` pelo URL do seu servidor. Certifique-se de que `SERVER_URL` no seu ambiente corresponda ao URL público da sua instância do Twenty — isso é usado para gerar os metadados de descoberta do OAuth.
+
+```bash
+SERVER_URL=https://twenty.yourcompany.com
+```
+
+O endpoint do MCP, os endpoints de OAuth e os metadados de descoberta derivam todos desse valor.
+
+## Resolução de Problemas
+
+**Erros "Unauthorized" ou 401**
+
+* OAuth: autorize novamente limpando os tokens armazenados no seu cliente MCP e reconectando.
+* Chave de API: verifique se a chave é válida e não expirou. Gere-a novamente, se necessário.
+
+**O fluxo do OAuth não abre um navegador**
+
+* Garanta que seu cliente MCP ofereça suporte à Autorização MCP. Se não oferecer, utilize o método de Chave de API.
+
+**Tempo limite de conexão**
+
+* Confirme que o URL do endpoint MCP é acessível a partir da sua máquina. Para instâncias auto-hospedadas, verifique se o servidor está em execução e se `SERVER_URL` está definido corretamente.
@@ -6,7 +6,7 @@ description: Ghidul pentru contribuitori (sau dezvoltatori curioși) care doresc
 ## Cerințe

 <Tabs>
-<Tab title="Linux și MacOS">
+<Tab title="Linux și macOS">

 Înainte de a instala și utiliza Twenty, asigurați-vă că instalați următoarele pe computerul dvs.:
 * [Git](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git)
@@ -129,8 +129,8 @@ Trebuie să rulați toate comenzile în pașii următori de la rădăcina proiec
      brew services list
    ```

-    Instalatorul s-ar putea să nu creeze implicit utilizatorul `postgres` atunci când instalați
-    prin Homebrew pe MacOS. În schimb, creează un rol PostgreSQL care se potrivește cu numele de utilizator al
+    Instalatorul s-ar putea să nu creeze implicit utilizatorul `postgres` la instalarea
+    prin Homebrew pe macOS. În schimb, creează un rol PostgreSQL care se potrivește cu numele de utilizator al
    macOS-ului dvs. (de ex., "john").
    Pentru a verifica și crea utilizatorul `postgres` dacă este necesar, urmați acești pași:
    ```bash
@@ -189,11 +189,13 @@ Trebuie să rulați toate comenzile în pașii următori de la rădăcina proiec
  </Tab>
 </Tabs>

-Acum puteți accesa baza de date la [localhost:5432](localhost:5432), cu utilizator `postgres` și parolă `postgres`.
+Acum puteți accesa baza de date la `localhost:5432`.
+
+Dacă ați folosit opțiunea Docker de mai sus, datele implicite de autentificare sunt utilizatorul `postgres` și parola `postgres`. Pentru instalările native PostgreSQL, folosiți datele de autentificare și rolurile configurate pe mașina dvs.

 ## Pasul 4: Configurați o bază de date Redis (cache)

-Twenty necesită un cache Redis pentru a oferi cea mai bună performanță
+Twenty necesită un cache Redis pentru a oferi cea mai bună performanță.

 <Tabs>
  <Tab title="Linux">
@@ -211,7 +213,9 @@ Twenty necesită un cache Redis pentru a oferi cea mai bună performanță
    brew install redis
    ```
    Porniți serverul Redis:
-    `brew services start redis`
+    ```bash
+    brew services start redis
+    ```

    **Opțiunea 2:** Dacă aveți docker instalat:
    ```bash
@@ -229,11 +233,11 @@ Twenty necesită un cache Redis pentru a oferi cea mai bună performanță
  </Tab>
 </Tabs>

-Dacă aveți nevoie de o interfață grafică pentru client, vă recomandăm [Redis Insight](https://redis.io/insight/) (versiune gratuită disponibilă)
+Dacă aveți nevoie de o interfață grafică pentru client, vă recomandăm [Redis Insight](https://redis.io/insight/) (versiune gratuită disponibilă).

 ## Pasul 5: Configurați variabilele de mediu

-Utilizați variabile de mediu sau fișiere `.env` pentru a configura proiectul dvs. Mai multe informații [aici](/l/ro/developers/self-host/capabilities/setup)
+Utilizați variabile de mediu sau fișiere `.env` pentru a configura proiectul dvs. Mai multe informații [aici](/l/ro/developers/self-host/capabilities/setup).

 Copiați fișierele `.env.example` din `/front` și `/server`:

@@ -21,19 +21,51 @@ Aplicațiile vă permit să construiți și să gestionați personalizările Twe
 ## Cerințe

 * Node.js 24+ și Yarn 4
-* Un spațiu de lucru Twenty și o cheie API (creați una la https://app.twenty.com/settings/api-webhooks)
+* Docker (pentru serverul local de dezvoltare Twenty)

 ## Începeți

-Creați o aplicație nouă folosind generatorul oficial, apoi autentificați-vă și începeți să dezvoltați:
+Creează o aplicație nouă folosind generatorul oficial. Poate porni automat o instanță Twenty locală pentru tine:

 ```bash filename="Terminal"
-# Creează scheletul unei aplicații noi (include toate exemplele în mod implicit)
+# Creează scheletul unei aplicații noi — CLI-ul îți va oferi opțiunea de a porni un server Twenty local
 npx create-twenty-app@latest my-twenty-app
 cd my-twenty-app

 # Pornește modul de dezvoltare: sincronizează automat modificările locale cu spațiul tău de lucru
-yarn twenty app:dev
+yarn twenty dev
+```
+
+### Gestionarea serverului local
+
+SDK-ul include comenzi pentru a gestiona un server local de dezvoltare Twenty (imagine Docker all-in-one cu PostgreSQL, Redis, server și worker):
+
+```bash filename="Terminal"
+# Pornește serverul local (descarcă imaginea dacă este necesar)
+yarn twenty server start
+
+# Verifică starea serverului
+yarn twenty server status
+
+# Afișează în timp real jurnalele serverului
+yarn twenty server logs
+
+# Oprește serverul
+yarn twenty server stop
+
+# Resetează toate datele și pornește de la zero
+yarn twenty server reset
+```
+
+Serverul local vine preconfigurat cu un spațiu de lucru și un utilizator (`tim@apple.dev` / `tim@apple.dev`), astfel încât să poți începe să dezvolți imediat, fără nicio configurare manuală.
+
+### Autentificare
+
+Conectează-ți aplicația la serverul local folosind OAuth:
+
+```bash filename="Terminal"
+# Autentifică-te prin OAuth (se deschide browserul)
+yarn twenty remote add --local
 ```

 Generatorul de schelet acceptă două moduri pentru a controla ce fișiere de exemplu sunt incluse:
@@ -49,26 +81,32 @@ npx create-twenty-app@latest my-app --minimal
 De aici puteți:

 ```bash filename="Terminal"
-# Adaugă o entitate nouă în aplicația ta (ghidat)
+# Add a new entity to your application (guided)
 yarn twenty entity:add

-# Urmărește jurnalele funcțiilor aplicației tale
+# Watch your application's function logs
 yarn twenty function:logs

-# Execută o funcție după nume
+# Execute a function by name
 yarn twenty function:execute -n my-function -p '{"name": "test"}'

-# Execută funcția de pre-instalare
+# Execute the pre-install function
 yarn twenty function:execute --preInstall

-# Execută funcția post-instalare
+# Execute the post-install function
 yarn twenty function:execute --postInstall

-# Dezinstalează aplicația din spațiul de lucru curent
+# Build the app for distribution
+yarn twenty app:build
+
+# Publish the app to npm or a Twenty server
+yarn twenty app:publish
+
+# Uninstall the application from the current workspace
 yarn twenty app:uninstall

-# Afișează ajutorul pentru comenzi
-yarn twenty help},{
+# Display commands' help
+yarn twenty help
 ```

 Consultați și: paginile de referință CLI pentru [create-twenty-app](https://www.npmjs.com/package/create-twenty-app) și [twenty-sdk CLI](https://www.npmjs.com/package/twenty-sdk).
@@ -1240,6 +1278,113 @@ Puncte cheie:

 Explorați un exemplu minim, cap la cap, care demonstrează obiecte, funcții de logică, componente Front și declanșatoare multiple [aici](https://github.com/twentyhq/twenty/tree/main/packages/twenty-apps/hello-world):

+## Building your app
+
+Once you've developed your app with `app:dev`, use `app:build` to compile it into a distributable package.
+
+```bash filename="Terminal"
+# Build the app (output goes to .twenty/output/)
+yarn twenty app:build
+
+# Build and create a tarball (.tgz) for distribution
+yarn twenty app:build --tarball
+```
+
+The build process:
+
+1. **Parses and validates the manifest** — reads all `defineX()` entities from your source files and validates the manifest structure.
+2. **Compiles logic functions and front components** — bundles TypeScript sources into ESM `.mjs` files using esbuild.
+3. **Generates checksums** — computes MD5 hashes for each built file, stored in the manifest as `builtHandlerChecksum` / `builtComponentChecksum`.
+4. **Generează clientul API tipizat** — examinează schema GraphQL și generează clienți tipizați `CoreApiClient` și `MetadataApiClient`.
+5. **Rulează o verificare a tipurilor TypeScript** — rulează `tsc --noEmit` pentru a detecta erorile de tip înainte de publicare.
+6. **Reconstruiește cu clientul generat** — efectuează o a doua trecere de compilare astfel încât tipurile clientului generat să fie incluse.
+7. **Creează opțional un tarball** — dacă se trece `--tarball`, rulează `npm pack` pentru a crea un fișier `.tgz` gata pentru distribuire.
+
+Rezultatul build-ului din `.twenty/output/` conține:
+
+```text
+.twenty/output/
+├── manifest.json              # Manifest cu sume de control pentru toate fișierele generate
+├── package.json               # Copiat din rădăcina aplicației
+├── yarn.lock                  # Copiat din rădăcina aplicației
+├── src/
+│   ├── logic-functions/       # Fișiere .mjs de funcții de logică compilate
+│   └── front-components/      # Fișiere .mjs de componente front-end compilate
+├── public/                    # Resurse statice (dacă există)
+└── my-app-1.0.0.tgz          # Doar cu opțiunea --tarball
+```
+
+| Opțiune     | Descriere                                                      |
+| ----------- | -------------------------------------------------------------- |
+| `[appPath]` | Calea către directorul aplicației (implicit directorul curent) |
+| `--tarball` | De asemenea, împachetează rezultatul într-un tarball `.tgz`    |
+
+## Publicarea aplicației
+
+Folosește `app:publish` pentru a distribui aplicația — fie în registrul npm, fie direct pe un server Twenty.
+
+### Publicare pe npm (implicit)
+
+```bash filename="Terminal"
+# Publicare pe npm (necesită autentificare npm)
+yarn twenty app:publish
+
+# Publicare cu un dist-tag (de ex. beta, next)
+yarn twenty app:publish --tag beta
+```
+
+Aceasta construiește aplicația și rulează `npm publish` din directorul `.twenty/output/`. Pachetul publicat poate fi apoi instalat din marketplace-ul Twenty de către orice spațiu de lucru.
+
+### Publicare pe un server Twenty
+
+```bash filename="Terminal"
+# Publicare direct pe un server Twenty
+yarn twenty app:publish --server https://app.twenty.com
+```
+
+Aceasta construiește aplicația cu un tarball, o încarcă pe server prin mutația GraphQL `uploadAppTarball` și declanșează instalarea într-un singur pas. Acest lucru este util pentru implementări private sau pentru testare pe un server specific.
+
+| Opțiune           | Descriere                                                            |
+| ----------------- | -------------------------------------------------------------------- |
+| `[appPath]`       | Calea către directorul aplicației (implicit directorul curent)       |
+| `--server <url>`  | Publică pe un server Twenty în loc de npm                            |
+| `--token <token>` | Jeton de autentificare pentru serverul țintă                         |
+| `--tag <tag>`     | npm dist-tag (de ex. `beta`, `next`) — doar pentru publicarea pe npm |
+
+## Înregistrarea aplicației
+
+Înainte ca o aplicație să poată fi instalată într-un spațiu de lucru, aceasta trebuie să fie **înregistrată**. O înregistrare este o înregistrare de metadate care descrie de unde provine aplicația și cum se autentifică. Acest lucru este gestionat automat de CLI în cele mai multe cazuri.
+
+### Tipuri de sursă
+
+Fiecare înregistrare are un **tip de sursă** care determină modul în care fișierele aplicației sunt preluate în timpul instalării:
+
+| Tip de sursă | Cum sunt preluate fișierele                                                              | Caz de utilizare tipic                    |
+| ------------ | ---------------------------------------------------------------------------------------- | ----------------------------------------- |
+| `LOCAL`      | Fișierele sunt sincronizate în timp real de către watcher-ul CLI — instalarea este omisă | Dezvoltare cu `app:dev`                   |
+| `NPM`        | Obținute din registrul npm prin câmpul `sourcePackage`                                   | Aplicații publicate pe npm                |
+| `TARBALL`    | Extrase dintr-un fișier `.tgz` încărcat, stocat pe server                                | Aplicații private publicate cu `--server` |
+
+### Cum are loc înregistrarea
+
+* **`app:dev`** — creează automat o înregistrare `LOCAL` prima dată când rulezi modul de dezvoltare pentru un spațiu de lucru.
+* **`app:publish --server`** — încarcă un tarball și creează (sau actualizează) o înregistrare `TARBALL`, apoi instalează aplicația.
+* **marketplace-ul npm** — înregistrările `NPM` sunt create când aplicațiile sunt sincronizate din registrul npm în catalogul marketplace-ului Twenty.
+* **API GraphQL** — poți de asemenea să creezi înregistrări programatic prin mutația `createApplicationRegistration`.
+
+### Înregistrare vs instalare
+
+**Înregistrarea** și **instalarea** sunt concepte separate:
+
+* O **înregistrare** (`ApplicationRegistration`) este o înregistrare globală de metadate care descrie aplicația: numele ei, tipul de sursă, acreditările OAuth și statutul listării în marketplace. Există independent de orice spațiu de lucru.
+* O **instalare** (`Application`) este o instanță per spațiu de lucru. Când un utilizator instalează o aplicație, Twenty rezolvă pachetul din sursa înregistrării, scrie fișierele compilate în stocare și sincronizează manifestul (creând obiecte, câmpuri, funcții de logică etc.) în acel spațiu de lucru.
+
+O singură înregistrare poate fi instalată în multe spații de lucru. Fiecare spațiu de lucru primește propria copie a fișierelor și a modelului de date al aplicației.
+
+### Acreditări OAuth
+
+Fiecare înregistrare include acreditări OAuth (`oAuthClientId` și `oAuthClientSecret`) generate la momentul creării. Acestea sunt folosite de aplicație pentru a autentifica cererile API în numele utilizatorilor. Secretul clientului este returnat **o singură dată** la creare — păstrează-l în siguranță. Îl poți roti ulterior prin mutația `rotateApplicationRegistrationClientSecret`.
+
 ## Configurare manuală (fără generator)

 Deși recomandăm utilizarea `create-twenty-app` pentru cea mai bună experiență de început, puteți configura și un proiect manual. Nu instalați CLI-ul global. În schimb, adăugați `twenty-sdk` ca dependență locală și conectați un singur script în package.json-ul dvs.:
@@ -3,7 +3,7 @@ title: 1-Click cu Docker Compose
 ---

 <Warning>
-Containerele Docker sunt pentru găzduire în producție sau auto-găzduire; pentru a contribui, consultați [Configurare locală](/l/ro/developers/contribute/capabilities/local-setup).
+Containerele Docker sunt destinate găzduirii în producție sau auto-găzduirii. Pentru a contribui, consultați [Configurarea locală](/l/ro/developers/contribute/capabilities/local-setup).
 </Warning>

 ## Prezentare generală
@@ -12,7 +12,7 @@ Acest ghid oferă instrucțiuni pas cu pas pentru a instala și configura aplica

 **Important:** Modificați numai setările menționate explicit în acest ghid. Modificarea altor configurații poate duce la probleme.

-Consultați documentația [Setup Environment Variables](/l/ro/developers/self-host/capabilities/setup) pentru configurare avansată. Toate variabilele de mediu trebuie declarate în fișierul docker-compose.yml la nivel de server și/sau de lucru, în funcție de variabilă.
+Consultați [Setup Environment Variables](/l/ro/developers/self-host/capabilities/setup) pentru configurare avansată. Toate variabilele de mediu trebuie declarate în fișierul `docker-compose.yml` la nivel de server și/sau de lucru, în funcție de variabilă.

 ## Cerințe de Sistem

@@ -0,0 +1,142 @@
+---
+title: Server MCP
+description: Conectați asistenți AI la spațiul dvs. de lucru Twenty folosind Model Context Protocol.
+---
+
+<Warning>
+MCP este în prezent în **alpha** și este disponibil doar în unele spații de lucru. Este posibil să nu fie activat încă pentru spațiul dvs. de lucru.
+</Warning>
+
+Twenty expune un server [MCP](https://modelcontextprotocol.io/) astfel încât asistenții AI — Claude Desktop, Claude Code, Cursor, ChatGPT și alții — să poată citi și scrie datele tale din CRM prin limbaj natural.
+
+Folosește **URL-ul spațiului de lucru** (URL-ul pe care îl folosești pentru a accesa Twenty) drept punct final MCP. Pe Twenty Cloud, URL-ul spațiului tău de lucru poate fi `https://{mycompany}.twenty.com` sau un domeniu personalizat. Serverul este disponibil la:
+
+| Mediu                | Punct final MCP                                                                |
+| -------------------- | ------------------------------------------------------------------------------ |
+| **Cloud**            | `https://{your-workspace-url}/mcp` (de ex. `https://mycompany.twenty.com/mcp`) |
+| **Găzduire proprie** | `https://{your-domain}/mcp`                                                    |
+
+## Metode de autentificare
+
+Ai două moduri de a-ți autentifica clientul MCP: **OAuth** (recomandat) sau **Cheie API**.
+
+### Opțiunea A — OAuth (Recomandat)
+
+Cu OAuth, clientul tău MCP deschide o fereastră de browser pentru a te autentifica. Nicio informație secretă nu este stocată în fișierele de configurare, iar tokenurile se reîmprospătează automat.
+
+<Note>
+OAuth necesită un client MCP care suportă [specificația MCP Authorization](https://modelcontextprotocol.io/specification/2025-03-26/basic/authorization). Claude Desktop, Claude Code, Cursor și ChatGPT o suportă.
+</Note>
+
+Adaugă asta în configurația clientului tău MCP, înlocuind `{your-workspace-url}` cu gazda spațiului tău de lucru (de ex. `mycompany.twenty.com`):
+
+```json
+{
+  "mcpServers": {
+    "twenty": {
+      "type": "streamable-http",
+      "url": "https://{your-workspace-url}/mcp"
+    }
+  }
+}
+```
+
+Atât — nu este necesară nicio cheie API. Când clientul se conectează pentru prima dată, acesta va:
+
+1. Va descoperi metadatele OAuth ale Twenty prin `/.well-known/oauth-protected-resource` și `/.well-known/oauth-authorization-server`
+2. Se va înregistra ca un client OAuth prin înregistrare dinamică a clientului (RFC 7591)
+3. Îți va deschide browserul pentru a autoriza accesul
+4. Va primi tokenurile și se va conecta la serverul MCP
+
+Conexiunile ulterioare reutilizează tokenurile stocate și le reîmprospătează automat.
+
+### Opțiunea B — Cheie API
+
+Dacă clientul tău MCP nu suportă OAuth sau preferi acreditări statice, furnizează o cheie API în antetul `Authorization`:
+
+```json
+{
+  "mcpServers": {
+    "twenty": {
+      "type": "streamable-http",
+      "url": "https://{your-workspace-url}/mcp",
+      "headers": {
+        "Authorization": "Bearer YOUR_API_KEY"
+      }
+    }
+  }
+}
+```
+
+<Warning>
+Cheia ta API oferă acces la datele spațiului de lucru. Ține-o în afara controlului versiunilor și a dotfiles partajate.
+</Warning>
+
+Pentru a crea o cheie API, mergi la **Settings > APIs & Webhooks > + Create key**. Vezi [API-uri](/l/ro/developers/extend/api#create-an-api-key) pentru detalii.
+
+## Pornire rapidă
+
+### 1. Copiază configurația
+
+Mergi la **Settings > AI > More > MCP Server** în Twenty. Alege metoda de autentificare (OAuth sau Cheie API), copiază fragmentul JSON (va folosi deja URL-ul spațiului tău de lucru) și lipește-l în fișierul de configurare al clientului tău MCP.
+
+| Client             | Locația fișierului de configurare                                                                                                                                                       |
+| ------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **Claude Desktop** | `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) sau `%APPDATA%\Claude\claude_desktop_config.json` (Windows)                                                   |
+| **Claude Code**    | `~/.claude.json` (utilizator) sau `.mcp.json` (proiect)                                                                                                                                 |
+| **Cursor**         | `.cursor/mcp.json` în proiectul tău sau `~/.cursor/mcp.json` global                                                                                                                     |
+| **ChatGPT**        | Activează Modul pentru dezvoltatori în **Settings > Apps & Connectors > Advanced settings**, apoi folosește **Create** în **Settings > Apps & Connectors** pentru a adăuga serverul MCP |
+
+### 2. Conectează-te
+
+Repornește clientul tău MCP (sau reîncarcă configurația). Dacă folosești OAuth, vei fi redirecționat către Twenty pentru a autoriza accesul. Dacă folosești o cheie API, conexiunea este imediată.
+
+### 3. Începe să-l folosești
+
+Roagă-ți asistentul AI să interacționeze cu CRM-ul tău:
+
+* *"Arată-mi cele 5 companii create cel mai recent"*
+* *"Creează o persoană nouă numită Jane Doe la Acme Corp"*
+* *"Găsește toate oportunitățile deschise cu o valoare mai mare de $10k"*
+
+## Instrumente disponibile
+
+După conectare, serverul MCP expune instrumente care oglindesc API-ul Twenty. Fluxul de lucru recomandat este:
+
+1. **`get_tool_catalog`** — descoperă toate instrumentele disponibile
+2. **`learn_tools`** — obține schema de intrare pentru instrumente specifice
+3. **`execute_tool`** — rulează un instrument
+
+Nu este nevoie să reții numele instrumentelor. Întreabă-ți asistentul AI ce poate face și va apela `get_tool_catalog` automat.
+
+## Permisiuni
+
+Conexiunile MCP moștenesc permisiunile utilizatorului autentificat (OAuth) sau rolul atribuit cheii API. Pentru a restricționa ce poate face serverul MCP:
+
+* **OAuth**: Se aplică rolul utilizatorului din spațiul de lucru.
+* **Cheie API**: Atribuie un rol cheii API în **Settings > Roles**. Vezi [Permisiuni](/l/ro/user-guide/permissions-access/capabilities/permissions).
+
+## Configurație pentru auto-găzduire
+
+Pentru instanțele auto-găzduite, înlocuiește `{your-workspace-url}` cu URL-ul serverului tău. Asigură-te că `SERVER_URL` din mediul tău corespunde URL-ului public al instanței tale Twenty — acesta este folosit pentru a genera metadatele de descoperire OAuth.
+
+```bash
+SERVER_URL=https://twenty.yourcompany.com
+```
+
+Punctul final MCP, punctele finale OAuth și metadatele de descoperire derivă toate din această valoare.
+
+## Depanare
+
+**Erori "Unauthorized" sau 401**
+
+* OAuth: reautorizează ștergând tokenurile stocate din clientul tău MCP și reconectează-te.
+* Cheie API: verifică dacă cheia este validă și nu a expirat. Regenereaz-o dacă este necesar.
+
+**Fluxul OAuth nu deschide un browser**
+
+* Asigură-te că clientul tău MCP suportă MCP Authorization. Dacă nu, revino la metoda cu Cheie API.
+
+**Timeout de conexiune**
+
+* Confirmă că URL-ul punctului final MCP este accesibil de pe calculatorul tău. Pentru instanțele auto-găzduite, verifică faptul că serverul rulează și că `SERVER_URL` este setat corect.
@@ -8,7 +8,7 @@ title: Руководство по стилю

 Для этого лучше быть немного более многословными, чем слишком краткими.

-Всегда держите в голове, что код читают чаще, чем пишут, особенно в проекте с открытым исходным кодом, где к нему может присоединиться кто угодно.
+Всегда помните, что код читают чаще, чем пишут, особенно в проекте с открытым исходным кодом, в который может внести вклад кто угодно.

 Существует много правил, которые здесь не описаны, но автоматически проверяются линтерами.

@@ -150,7 +150,7 @@ type MyType = {

 ### Используйте строковые литералы вместо перечислений.

-[Строковые литералы](https://www.typescriptlang.org/docs/handbook/2/everyday-types.html#literal-types) - это основной способ обработки значений, напоминающих перечисление, в TypeScript. Они легче расширяются с помощью Pick и Omit и обеспечивают лучшее взаимодействие с разработчиком, особенно с автозаполнением кода.
+[Строковые литералы](https://www.typescriptlang.org/docs/handbook/2/everyday-types.html#literal-types) - это основной способ обработки значений, напоминающих перечисление, в TypeScript. Их проще расширять с помощью Pick и Omit, и они обеспечивают более удобную работу разработчика, особенно благодаря автодополнению кода.

 Вы можете увидеть, почему TypeScript рекомендует избегать перечислений [здесь](https://www.typescriptlang.org/docs/handbook/2/everyday-types.html#enums).

@@ -6,7 +6,7 @@ description: Руководство для участников (или любо
 ## Требования

 <Tabs>
-<Tab title="Linux и MacOS">
+<Tab title="Linux и macOS">

 Прежде чем установить и использовать Twenty, убедитесь, что у вас установлено следующее:
 * [Git](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git)
@@ -30,7 +30,7 @@ wsl --install
 ```
 Теперь должно появиться приглашение на перезагрузку компьютера. Если нет, перезагрузите его вручную.

-После перезагрузки откроется окно PowerShell и установит Ubuntu. Это может занять некоторое время.
+После перезагрузки откроется окно PowerShell и начнётся установка Ubuntu. Это может занять некоторое время.
 Появится запрос на создание имени пользователя и пароля для вашей установки Ubuntu.

 2. Установите и настройте git
@@ -102,8 +102,8 @@ cd twenty

 <Tabs>
  <Tab title="Linux">
-    **Опция 1 (предпочтительно):** Чтобы настроить вашу базу данных локально:
-    Используйте следующую ссылку для установки Postgresql на вашу Linux машину: [Установка Postgresql](https://www.postgresql.org/download/linux/)
+    **Опция 1 (предпочтительно):** Чтобы настроить базу данных локально:
+    Используйте следующую ссылку для установки PostgreSQL на компьютер с Linux: [Установка PostgreSQL](https://www.postgresql.org/download/linux/)
    ```bash
    psql postgres -c "CREATE DATABASE \"default\";" -c "CREATE DATABASE test;"
    ```
@@ -130,7 +130,7 @@ cd twenty
    ```

    Установщик может не создать пользователя `postgres` по умолчанию при установке
-    через Homebrew на MacOS. Вместо этого он создает роль PostgreSQL, которая совпадает с вашим именем пользователя в MacOS
+    через Homebrew на macOS. Вместо этого он создает роль PostgreSQL, которая совпадает с вашим именем пользователя в MacOS
    например, "john".
    Чтобы проверить и создать пользователя `postgres`, при необходимости выполните следующие шаги:
    ```bash
@@ -173,8 +173,8 @@ cd twenty
  <Tab title="Windows (WSL)">
    Все последующие шаги следует выполнять в терминале WSL (внутри вашей виртуальной машины)

-    **Опция 1:** Чтобы настроить вашу базу данных Postgresql локально:
-    Используйте следующую ссылку для установки Postgresql на вашу Linux виртуальную машину: [Установка Postgresql](https://www.postgresql.org/download/linux/)
+    **Опция 1:** Чтобы настроить PostgreSQL локально:
+    Используйте следующую ссылку для установки PostgreSQL на виртуальную машину с Linux: [Установка PostgreSQL](https://www.postgresql.org/download/linux/)
    ```bash
    psql postgres -c "CREATE DATABASE \"default\";" -c "CREATE DATABASE test;"
    ```
@@ -189,11 +189,13 @@ cd twenty
  </Tab>
 </Tabs>

-Теперь вы можете получить доступ к базе данных по адресу [localhost:5432](localhost:5432), с пользователем `postgres` и паролем `postgres`.
+Теперь вы можете получить доступ к базе данных по адресу `localhost:5432`.
+
+Если вы использовали вариант с Docker выше, учетные данные по умолчанию: пользователь `postgres` и пароль `postgres`. Для нативных установок PostgreSQL используйте учетные данные и роли, настроенные на вашей машине.

 ## Шаг 4: Настройка базы данных Redis (кэш)

-Twenty требует кэша Redis для обеспечения наилучшей производительности
+Twenty требует кэша Redis для обеспечения наилучшей производительности.

 <Tabs>
  <Tab title="Linux">
@@ -210,8 +212,10 @@ Twenty требует кэша Redis для обеспечения наилуч
    ```bash
    brew install redis
    ```
-    Запустите сервер redis:
-    `brew services start redis`
+    Запустите сервер Redis:
+    ```bash
+    brew services start redis
+    ```

    **Опция 2:** Если у вас установлен docker:
    ```bash
@@ -229,11 +233,11 @@ Twenty требует кэша Redis для обеспечения наилуч
  </Tab>
 </Tabs>

-Если вам нужен графический интерфейс клиента, мы рекомендуем [redis insight](https://redis.io/insight/) (доступна бесплатная версия)
+Если вам нужен графический интерфейс клиента, мы рекомендуем [Redis Insight](https://redis.io/insight/) (доступна бесплатная версия).

 ## Шаг 5: Настройка переменных окружения

-Используйте переменные окружения или файлы `.env` для настройки вашего проекта. Подробнее [здесь](/l/ru/developers/self-host/capabilities/setup)
+Используйте переменные окружения или файлы `.env` для настройки вашего проекта. Подробнее [здесь](/l/ru/developers/self-host/capabilities/setup).

 Скопируйте `.env.example` файлы в `/front` и `/server`:

@@ -21,19 +21,51 @@ description: Создавайте и управляйте настройками
 ## Требования

 * Node.js 24+ и Yarn 4
-* Рабочее пространство Twenty и ключ API (создайте его на https://app.twenty.com/settings/api-webhooks)
+* Docker (для локального сервера разработки Twenty)

 ## Начало работы

-Создайте новое приложение с помощью официального генератора, затем выполните аутентификацию и начните разработку:
+Создайте новое приложение с помощью официального генератора каркаса. Он может автоматически запустить локальный экземпляр Twenty:

 ```bash filename="Terminal"
-# Создать каркас нового приложения (по умолчанию включает все примеры)
+# Создать каркас нового приложения — CLI предложит запустить локальный сервер Twenty
 npx create-twenty-app@latest my-twenty-app
 cd my-twenty-app

 # Запустить режим разработки: автоматически синхронизирует локальные изменения с вашим рабочим пространством
-yarn twenty app:dev
+yarn twenty dev
+```
+
+### Управление локальным сервером
+
+SDK включает команды для управления локальным сервером разработки Twenty (универсальный образ Docker с PostgreSQL, Redis, сервером и воркером):
+
+```bash filename="Terminal"
+# Запустить локальный сервер (при необходимости будет загружен образ)
+yarn twenty server start
+
+# Проверить статус сервера
+yarn twenty server status
+
+# Просмотр логов сервера в реальном времени
+yarn twenty server logs
+
+# Остановить сервер
+yarn twenty server stop
+
+# Сбросить все данные и начать с нуля
+yarn twenty server reset
+```
+
+Локальный сервер уже содержит рабочее пространство и пользователя (`tim@apple.dev` / `tim@apple.dev`), так что вы можете сразу начать разработку без какой-либо ручной настройки.
+
+### Аутентификация
+
+Подключите своё приложение к локальному серверу с помощью OAuth:
+
+```bash filename="Terminal"
+# Authenticate via OAuth (opens browser)
+yarn twenty remote add --local
 ```

 Генератор каркаса поддерживает два режима для управления тем, какие файлы-примеры включаются:
@@ -64,6 +96,12 @@ yarn twenty function:execute --preInstall
 # Выполнить послеустановочную функцию
 yarn twenty function:execute --postInstall

+# Собрать приложение для распространения
+yarn twenty app:build
+
+# Опубликовать приложение в npm или на сервер Twenty
+yarn twenty app:publish
+
 # Удалить приложение из текущего рабочего пространства
 yarn twenty app:uninstall

@@ -1240,6 +1278,113 @@ uploadFile(

 Ознакомьтесь с минимальным сквозным примером, демонстрирующим объекты, логические функции, фронт-компоненты и несколько триггеров, [здесь](https://github.com/twentyhq/twenty/tree/main/packages/twenty-apps/hello-world):

+## Сборка вашего приложения
+
+После того как вы разработали приложение с помощью `app:dev`, используйте `app:build`, чтобы скомпилировать его в распространяемый пакет.
+
+```bash filename="Terminal"
+# Собрать приложение (результат сохраняется в .twenty/output/)
+yarn twenty app:build
+
+# Собрать и создать tarball (.tgz) для распространения
+yarn twenty app:build --tarball
+```
+
+Процесс сборки:
+
+1. **Разбирает и проверяет манифест** — читает все сущности `defineX()` из ваших исходных файлов и проверяет структуру манифеста.
+2. **Компилирует логические функции и фронтенд-компоненты** — упаковывает исходники TypeScript в ESM-файлы `.mjs` с помощью esbuild.
+3. **Генерирует контрольные суммы** — вычисляет хэши MD5 для каждого собранного файла, сохраняемые в манифесте как `builtHandlerChecksum` / `builtComponentChecksum`.
+4. **Генерирует типизированный клиент API** — проводит интроспекцию схемы GraphQL и генерирует типизированные клиенты `CoreApiClient` и `MetadataApiClient`.
+5. **Запускает проверку типов TypeScript** — выполняет `tsc --noEmit`, чтобы обнаружить ошибки типов перед публикацией.
+6. **Пересобирает со сгенерированным клиентом** — выполняет второй проход компиляции, чтобы включить сгенерированные типы клиента.
+7. **Опционально создаёт tar-архив** — если передан `--tarball`, выполняет `npm pack` для создания файла `.tgz`, готового к распространению.
+
+Результат сборки в `.twenty/output/` содержит:
+
+```text
+.twenty/output/
+├── manifest.json              # Manifest with checksums for all built files
+├── package.json               # Copied from app root
+├── yarn.lock                  # Copied from app root
+├── src/
+│   ├── logic-functions/       # Compiled .mjs logic function files
+│   └── front-components/      # Compiled .mjs front component files
+├── public/                    # Static assets (if any)
+└── my-app-1.0.0.tgz          # Only with --tarball flag
+```
+
+| Вариант     | Описание                                                    |
+| ----------- | ----------------------------------------------------------- |
+| `[appPath]` | Путь к каталогу приложения (по умолчанию — текущий каталог) |
+| `--tarball` | Также упаковать результат в tar-архив `.tgz`                |
+
+## Публикация вашего приложения
+
+Используйте `app:publish` для распространения вашего приложения — либо в реестр npm, либо напрямую на сервер Twenty.
+
+### Публикация в npm (по умолчанию)
+
+```bash filename="Terminal"
+# Publish to npm (requires npm login)
+yarn twenty app:publish
+
+# Publish with a dist-tag (e.g. beta, next)
+yarn twenty app:publish --tag beta
+```
+
+Это собирает приложение и выполняет `npm publish` из каталога `.twenty/output/`. Опубликованный пакет затем может быть установлен из маркетплейса Twenty любым рабочим пространством.
+
+### Публикация на сервер Twenty
+
+```bash filename="Terminal"
+# Publish directly to a Twenty server
+yarn twenty app:publish --server https://app.twenty.com
+```
+
+Это собирает приложение с tar-архивом, загружает его на сервер через мутацию GraphQL `uploadAppTarball` и запускает установку в один шаг. Это полезно для приватных развёртываний или тестирования на конкретном сервере.
+
+| Вариант           | Описание                                                              |
+| ----------------- | --------------------------------------------------------------------- |
+| `[appPath]`       | Путь к каталогу приложения (по умолчанию — текущий каталог)           |
+| `--server <url>`  | Публиковать на сервер Twenty вместо npm                               |
+| `--token <token>` | Токен аутентификации для целевого сервера                             |
+| `--tag <tag>`     | dist-тег npm (например, `beta`, `next`) — только для публикации в npm |
+
+## Регистрация приложения
+
+Прежде чем приложение можно будет установить в рабочем пространстве, его необходимо **зарегистрировать**. Регистрация — это запись метаданных, описывающая, откуда берётся приложение и как его аутентифицировать. В большинстве случаев это делает CLI автоматически.
+
+### Типы источников
+
+У каждой регистрации есть **тип источника**, который определяет, как файлы приложения будут получены при установке:
+
+| Тип источника | Как получаются файлы                                                                | Типичный сценарий использования                   |
+| ------------- | ----------------------------------------------------------------------------------- | ------------------------------------------------- |
+| `LOCAL`       | Файлы синхронизируются в реальном времени наблюдателем CLI — установка пропускается | Разработка с `app:dev`                            |
+| `NPM`         | Получается из реестра npm через поле `sourcePackage`                                | Опубликованные приложения в npm                   |
+| `TARBALL`     | Извлекается из загруженного файла `.tgz`, хранящегося на сервере                    | Приватные приложения, опубликованные с `--server` |
+
+### Как происходит регистрация
+
+* **`app:dev`** — автоматически создаёт регистрацию `LOCAL` при первом запуске режима разработки для рабочего пространства.
+* **`app:publish --server`** — загружает tar-архив и создаёт (или обновляет) регистрацию `TARBALL`, затем устанавливает приложение.
+* **маркетплейс npm** — регистрации `NPM` создаются, когда приложения синхронизируются из реестра npm в каталог маркетплейса Twenty.
+* **GraphQL API** — вы также можете создавать регистрации программно через мутацию `createApplicationRegistration`.
+
+### Регистрация и установка
+
+**Регистрация** и **установка** — это разные понятия:
+
+* **Регистрация** (`ApplicationRegistration`) — это глобальная запись метаданных, описывающая приложение: его имя, тип источника, учётные данные OAuth и статус публикации в маркетплейсе. Она существует независимо от какого-либо рабочего пространства.
+* **Установка** (`Application`) — это экземпляр для каждого рабочего пространства. Когда пользователь устанавливает приложение, Twenty получает пакет из источника, указанного в регистрации, записывает собранные файлы в хранилище и синхронизирует манифест (создавая объекты, поля, логические функции и т. д.) в этом рабочем пространстве.
+
+Одну и ту же регистрацию можно установить во многих рабочих пространствах. Каждое рабочее пространство получает свою собственную копию файлов приложения и модели данных.
+
+### Учётные данные OAuth
+
+Каждая регистрация включает учётные данные OAuth (`oAuthClientId` и `oAuthClientSecret`), сгенерированные при создании. Они используются приложением для аутентификации запросов к API от имени пользователей. Секрет клиента возвращается **один раз** при создании — храните его в надёжном месте. Позже вы можете сменить его через мутацию `rotateApplicationRegistrationClientSecret`.
+
 ## Ручная настройка (без генератора)

 Хотя мы рекомендуем использовать `create-twenty-app` для наилучшего старта, вы также можете настроить проект вручную. Не устанавливайте CLI глобально. Вместо этого добавьте `twenty-sdk` как локальную зависимость и настройте один скрипт в вашем package.json:
@@ -3,7 +3,7 @@ title: В один клик с Docker Compose
 ---

 <Warning>
-Контейнеры Docker предназначены для продакшен-размещения или самостоятельного хостинга; для участия в разработке ознакомьтесь с разделом [Локальная установка](/l/ru/developers/contribute/capabilities/local-setup).
+Контейнеры Docker предназначены для продакшен-хостинга или саморазмещения. Для участия в разработке см. [Локальная настройка](/l/ru/developers/contribute/capabilities/local-setup).
 </Warning>

 ## Обзор
@@ -12,7 +12,7 @@ title: В один клик с Docker Compose

 **Важно:** изменяйте только те настройки, которые явно упоминаются в этом руководстве. Изменение других конфигураций может привести к проблемам.

-См. документацию [Настройка переменных окружения](/l/ru/developers/self-host/capabilities/setup) для расширенной конфигурации. Все переменные окружения должны быть задекларированы в файле docker-compose.yml на уровне сервера и / или рабочего потока в зависимости от переменной.
+См. [Настройка переменных окружения](/l/ru/developers/self-host/capabilities/setup) для расширенной конфигурации. Все переменные окружения должны быть задекларированы в файле `docker-compose.yml` на уровне сервера и/или воркера, в зависимости от переменной.

 ## Системные требования

@@ -0,0 +1,142 @@
+---
+title: Сервер MCP
+description: Подключайте ИИ-ассистентов к вашему рабочему пространству Twenty с помощью протокола Model Context Protocol.
+---
+
+<Warning>
+В настоящее время MCP находится на стадии **alpha** и доступен только в некоторых рабочих пространствах. В вашем рабочем пространстве он может быть ещё не включён.
+</Warning>
+
+Twenty предоставляет сервер [MCP](https://modelcontextprotocol.io/), чтобы ИИ-ассистенты — Claude Desktop, Claude Code, Cursor, ChatGPT и другие — могли читать и записывать ваши данные CRM на естественном языке.
+
+Используйте **URL рабочей области** (URL, который вы используете для доступа к Twenty) в качестве конечной точки MCP. В Twenty Cloud URL вашей рабочей области может быть `https://{mycompany}.twenty.com` или собственный домен. Сервер доступен по адресу:
+
+| Среда                       | Конечная точка MCP                                                                |
+| --------------------------- | --------------------------------------------------------------------------------- |
+| **Облако**                  | `https://{your-workspace-url}/mcp` (например, `https://mycompany.twenty.com/mcp`) |
+| **Самостоятельный хостинг** | `https://{your-domain}/mcp`                                                       |
+
+## Методы аутентификации
+
+Есть два способа аутентифицировать ваш MCP-клиент: **OAuth** (рекомендуется) или **API Key**.
+
+### Вариант A — OAuth (рекомендуется)
+
+При использовании OAuth ваш MCP-клиент откроет окно браузера для входа в систему. Секреты не хранятся в файлах конфигурации, а токены обновляются автоматически.
+
+<Note>
+Для OAuth требуется MCP-клиент, поддерживающий [спецификацию авторизации MCP](https://modelcontextprotocol.io/specification/2025-03-26/basic/authorization). Её поддерживают Claude Desktop, Claude Code, Cursor и ChatGPT.
+</Note>
+
+Добавьте это в конфигурацию вашего MCP-клиента, заменив `{your-workspace-url}` на хост вашей рабочей области (например, `mycompany.twenty.com`):
+
+```json
+{
+  "mcpServers": {
+    "twenty": {
+      "type": "streamable-http",
+      "url": "https://{your-workspace-url}/mcp"
+    }
+  }
+}
+```
+
+Вот и всё — ключ API не требуется. При первом подключении клиент выполнит:
+
+1. Обнаружит метаданные OAuth Twenty через `/.well-known/oauth-protected-resource` и `/.well-known/oauth-authorization-server`
+2. Зарегистрирует себя как OAuth-клиент через динамическую регистрацию клиентов (RFC 7591)
+3. Откроет браузер для авторизации доступа
+4. Получит токены и подключится к серверу MCP
+
+При последующих подключениях используются сохранённые токены, которые автоматически обновляются.
+
+### Вариант B — ключ API
+
+Если ваш MCP-клиент не поддерживает OAuth или вы предпочитаете статические учётные данные, передайте ключ API в заголовке `Authorization`:
+
+```json
+{
+  "mcpServers": {
+    "twenty": {
+      "type": "streamable-http",
+      "url": "https://{your-workspace-url}/mcp",
+      "headers": {
+        "Authorization": "Bearer YOUR_API_KEY"
+      }
+    }
+  }
+}
+```
+
+<Warning>
+Ваш ключ API предоставляет доступ к данным рабочей области. Не храните его в системе контроля версий и общих dotfiles.
+</Warning>
+
+Чтобы создать ключ API, перейдите в **Settings > APIs & Webhooks > + Create key**. См. [API](/l/ru/developers/extend/api#create-an-api-key) для подробностей.
+
+## Быстрый старт
+
+### 1. Скопируйте конфигурацию
+
+Перейдите в **Settings > AI > More > MCP Server** в Twenty. Выберите метод аутентификации (OAuth или ключ API), скопируйте фрагмент JSON (в нём уже будет использован URL вашей рабочей области) и вставьте его в файл конфигурации вашего MCP-клиента.
+
+| Клиент             | Расположение файла конфигурации                                                                                                                                                |
+| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| **Claude Desktop** | `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) или `%APPDATA%\Claude\claude_desktop_config.json` (Windows)                                          |
+| **Claude Code**    | `~/.claude.json` (пользователь) или `.mcp.json` (проект)                                                                                                                       |
+| **Cursor**         | `.cursor/mcp.json` в вашем проекте или `~/.cursor/mcp.json` глобально                                                                                                          |
+| **ChatGPT**        | Включите режим разработчика в **Settings > Apps & Connectors > Advanced settings**, затем используйте **Create** в **Settings > Apps & Connectors**, чтобы добавить сервер MCP |
+
+### 2. Подключение
+
+Перезапустите ваш MCP-клиент (или перезагрузите конфигурацию). Если используется OAuth, вы будете перенаправлены в Twenty для авторизации доступа. Если используется ключ API, подключение произойдёт сразу.
+
+### 3. Начните использовать
+
+Попросите вашего ИИ-ассистента взаимодействовать с вашей CRM:
+
+* *"Покажи мне 5 последних созданных компаний"*
+* *"Создай новый контакт по имени Jane Doe в компании Acme Corp"*
+* *"Найди все открытые сделки стоимостью более $10 000"*
+
+## Доступные инструменты
+
+После подключения сервер MCP предоставляет инструменты, отражающие API Twenty. Рекомендуемый рабочий процесс:
+
+1. **`get_tool_catalog`** — получить список всех доступных инструментов
+2. **`learn_tools`** — получить схему входных данных для конкретных инструментов
+3. **`execute_tool`** — запустить инструмент
+
+Вам не нужно запоминать названия инструментов. Спросите у вашего ИИ-ассистента, что он умеет, и он автоматически вызовет `get_tool_catalog`.
+
+## Разрешения
+
+Подключения MCP наследуют разрешения аутентифицированного пользователя (OAuth) или роль, назначенную ключу API. Чтобы ограничить действия, доступные серверу MCP:
+
+* **OAuth**: Применяется роль пользователя в рабочей области.
+* **API Key**: Назначьте ключу API роль в **Settings > Roles**. См. [Разрешения](/l/ru/user-guide/permissions-access/capabilities/permissions).
+
+## Конфигурация для самостоятельного хостинга
+
+Для экземпляров с самостоятельным хостингом замените `{your-workspace-url}` на URL вашего сервера. Убедитесь, что значение `SERVER_URL` в вашей среде соответствует публичному URL экземпляра Twenty — оно используется для генерации метаданных обнаружения OAuth.
+
+```bash
+SERVER_URL=https://twenty.yourcompany.com
+```
+
+Конечная точка MCP, конечные точки OAuth и метаданные обнаружения формируются на основе этого значения.
+
+## Устранение неполадок
+
+**Ошибки "Unauthorized" или 401**
+
+* OAuth: повторно авторизуйтесь, очистив сохранённые токены в вашем MCP-клиенте и переподключившись.
+* API Key: убедитесь, что ключ действителен и не истёк. При необходимости сгенерируйте его заново.
+
+**Процесс OAuth не открывает браузер**
+
+* Убедитесь, что ваш MCP-клиент поддерживает MCP Authorization. Если нет — используйте метод с ключом API.
+
+**Тайм-аут подключения**
+
+* Убедитесь, что URL конечной точки MCP доступен с вашего компьютера. Для экземпляров с самостоятельным хостингом проверьте, что сервер запущен и значение `SERVER_URL` установлено корректно.
@@ -149,7 +149,7 @@ type MyType = {

 ### enum'lar yerine string literal'leri kullanın

-[String literalleri](https://www.typescriptlang.org/docs/handbook/2/everyday-types.html#literal-types), TypeScript'te enum benzeri değerleri yönetmek için en iyi yöntemdir. Pick ve Omit ile genişletilmesi daha kolay olur ve özellikle kod tamamlama ile daha iyi bir geliştirici deneyimi sunarlar.
+[String literalleri](https://www.typescriptlang.org/docs/handbook/2/everyday-types.html#literal-types), TypeScript'te enum benzeri değerleri yönetmek için en iyi yöntemdir. Pick ve Omit ile genişletilmeleri daha kolaydır ve özellikle kod tamamlama ile daha iyi bir geliştirici deneyimi sunarlar.

 TypeScript, enum'ların neden kaçınılması gereken bir seçenek olduğunu [burada](https://www.typescriptlang.org/docs/handbook/2/everyday-types.html#enums) açıklamaktadır.

@@ -6,7 +6,7 @@ description: Twenty'i yerel olarak çalıştırmak isteyen katkıda bulunanlar (
 ## Ön Gereksinimler

 <Tabs>
-<Tab title="Linux ve MacOS">
+<Tab title="Linux ve macOS">

 Twenty'i yüklemeden ve kullanmadan önce bilgisayarınıza aşağıdakileri yüklediğinizden emin olun:
 * [Git](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git)
@@ -30,7 +30,7 @@ wsl --install
 ```
 Şimdi bilgisayarınızı yeniden başlatmanız gerektiğine dair bir uyarı göreceksiniz. Eğer görmüyorsanız, manuel olarak yeniden başlatın.

-Yeniden başladıktan sonra bir powershell penceresi açılacak ve Ubuntu yüklenecek. Bu biraz zaman alabilir.
+Yeniden başlatıldığında bir PowerShell penceresi açılacak ve Ubuntu yüklenecek. Bu biraz zaman alabilir.
 Ubuntu kurulumunuz için bir kullanıcı adı ve şifre oluşturmanız gerektiğine dair bir uyarı göreceksiniz.

 2. git'i Yükleyin ve Yapılandırın
@@ -102,8 +102,8 @@ Sonraki adımlardaki tüm komutları projenin kök dizininden çalıştırmalıs

 <Tabs>
  <Tab title="Linux">
-    **Seçenek 1 (tercih edilen):** Veritabanınızı yerel olarak kurmak için:
-    Linux makinenize Postgresql yüklemek için şu bağlantıyı kullanın: [Postgresql Kurulumu](https://www.postgresql.org/download/linux/)
+    **Seçenek 1 (tercih edilen):** Veritabanınızı yerel olarak hazırlamak için:
+    Linux makinenize PostgreSQL yüklemek için aşağıdaki bağlantıyı kullanın: [PostgreSQL Kurulumu](https://www.postgresql.org/download/linux/)
    ```bash
      psql postgres -c "CREATE DATABASE \"default\";" -c "CREATE DATABASE test;"
    ```
@@ -129,7 +129,8 @@ Sonraki adımlardaki tüm komutları projenin kök dizininden çalıştırmalıs
      brew services list
    ```

-    Yükleyici, MacOS'ta Homebrew ile yüklenirken varsayılan olarak `postgres` kullanıcısını oluşturmayabilir. Bunun yerine, macOS kullanıcı adınıza (ör. "john") uygun bir PostgreSQL rolü oluşturur.
+    Yükleyici, macOS'ta Homebrew aracılığıyla yüklenirken
+    varsayılan olarak `postgres` kullanıcısını oluşturmayabilir. Bunun yerine, macOS kullanıcı adınıza (ör. "john") uygun bir PostgreSQL rolü oluşturur.
    Gerekiyorsa `postgres` kullanıcısını kontrol etmek ve oluşturtmak için şu adımları izleyin:
    ```bash
      # PostgreSQL'e Bağlan
@@ -171,8 +172,8 @@ Sonraki adımlardaki tüm komutları projenin kök dizininden çalıştırmalıs
  <Tab title="Windows (WSL)">
    Aşağıdaki tüm adımlar WSL terminalinde (sanallaştırma makineniz içinde) çalıştırılmalıdır.

-    **Seçenek 1:** Postgresql'i yerel olarak sağlamak için:
-    Linux sanal makinenize Postgresql yüklemek için şu bağlantıyı kullanın: [Postgresql Kurulumu](https://www.postgresql.org/download/linux/)
+    **Seçenek 1:** PostgreSQL'i yerel olarak hazırlamak için:
+    Linux sanal makinenize PostgreSQL yüklemek için aşağıdaki bağlantıyı kullanın: [PostgreSQL Kurulumu](https://www.postgresql.org/download/linux/)
    ```bash
      psql postgres -c "CREATE DATABASE \"default\";" -c "CREATE DATABASE test;"
    ```
@@ -187,11 +188,13 @@ Sonraki adımlardaki tüm komutları projenin kök dizininden çalıştırmalıs
  </Tab>
 </Tabs>

-Veritabanına [localhost:5432](localhost:5432) adresinden, kullanıcı `postgres` ve şifre `postgres` ile şimdi erişebilirsiniz.
+Artık veritabanına `localhost:5432` üzerinden erişebilirsiniz.
+
+Yukarıdaki Docker seçeneğini kullandıysanız, varsayılan kimlik bilgileri kullanıcı adı `postgres` ve parola `postgres` şeklindedir. Yerel PostgreSQL kurulumları için, makinenizde yapılandırılmış kimlik bilgilerini ve rolleri kullanın.

 ## Adım 4: Redis Veritabanı (önbellek) Kurun

-Twenty, en iyi performansı sağlamak için bir redis önbelleğe ihtiyaç duyar
+Twenty, en iyi performansı sağlamak için bir Redis önbelleği gerektirir.

 <Tabs>
  <Tab title="Linux">
@@ -209,7 +212,9 @@ Twenty, en iyi performansı sağlamak için bir redis önbelleğe ihtiyaç duyar
    brew install redis
    ```
    Redis sunucunuzu başlatın:
-    `brew services start redis`
+    ```bash
+    brew services start redis
+    ```

    **Seçenek 2:** Eğer docker yüklüyse:
    ```bash
@@ -227,11 +232,11 @@ Twenty, en iyi performansı sağlamak için bir redis önbelleğe ihtiyaç duyar
  </Tab>
 </Tabs>

-Bir İstemci GUI'ye ihtiyacınız varsa, [redis insight](https://redis.io/insight/) (ücretsiz sürüm mevcut) öneriyoruz.
+Bir istemci GUI'ye ihtiyacınız varsa, [Redis Insight](https://redis.io/insight/) (ücretsiz sürüm mevcut) öneriyoruz.

-## Adım 5: Çevresel değişkenleri ayarlayın
+## Adım 5: Ortam değişkenlerini ayarlayın

-Projenizi yapılandırmak için çevresel değişkenler veya `.env` dosyaları kullanın. Daha fazla bilgi [burada](/l/tr/developers/self-host/capabilities/setup)
+Projenizi yapılandırmak için çevresel değişkenler veya `.env` dosyaları kullanın. Daha fazla bilgi [burada](/l/tr/developers/self-host/capabilities/setup).

 `.env.example` dosyalarını `/front` ve `/server` içine kopyalayın:

@@ -21,19 +21,51 @@ Uygulamalar, Twenty özelleştirmelerini **kod olarak** oluşturup yönetmenizi
 ## Ön Gereksinimler

 * Node.js 24+ ve Yarn 4
-* Bir Twenty çalışma alanı ve bir API anahtarı (https://app.twenty.com/settings/api-webhooks adresinde oluşturun)
+* Docker (yerel Twenty geliştirme sunucusu için)

 ## Başlarken

-Resmi scaffolder aracını kullanarak yeni bir uygulama oluşturun, ardından kimlik doğrulaması yapıp geliştirmeye başlayın:
+Resmi iskelet oluşturucusunu kullanarak yeni bir uygulama oluşturun. Sizin için otomatik olarak yerel bir Twenty örneğini başlatabilir:

 ```bash filename="Terminal"
-# Yeni bir uygulamanın iskeletini oluşturun (varsayılan olarak tüm örnekleri içerir)
+# Yeni bir uygulamanın iskeletini oluşturun — CLI yerel bir Twenty sunucusunu başlatmayı önerecektir
 npx create-twenty-app@latest my-twenty-app
 cd my-twenty-app

-# Geliştirme modunu başlatın: yerel değişiklikleri otomatik olarak çalışma alanınızla senkronize eder
-yarn twenty app:dev
+# Geliştirme modunu başlatın: yerel değişiklikleri çalışma alanınızla otomatik olarak senkronize eder
+yarn twenty dev
+```
+
+### Yerel Sunucu Yönetimi
+
+SDK, yerel bir Twenty geliştirme sunucusunu yönetmek için komutlar içerir (PostgreSQL, Redis, sunucu ve worker içeren hepsi bir arada Docker imajı):
+
+```bash filename="Terminal"
+# Yerel sunucuyu başlatın (gerekirse imajı indirir)
+yarn twenty server start
+
+# Sunucu durumunu kontrol edin
+yarn twenty server status
+
+# Sunucu günlüklerini akış olarak görüntüleyin
+yarn twenty server logs
+
+# Sunucuyu durdurun
+yarn twenty server stop
+
+# Tüm verileri sıfırlayın ve temiz bir başlangıç yapın
+yarn twenty server reset
+```
+
+Yerel sunucu, bir çalışma alanı ve kullanıcıyla (`tim@apple.dev` / `tim@apple.dev`) önceden yapılandırılmış olarak gelir; böylece herhangi bir manuel kurulum gerektirmeden hemen geliştirmeye başlayabilirsiniz.
+
+### Kimlik Doğrulama
+
+Uygulamanızı OAuth kullanarak yerel sunucuya bağlayın:
+
+```bash filename="Terminal"
+# Authenticate via OAuth (opens browser)
+yarn twenty remote add --local
 ```

 İskelet oluşturucu, hangi örnek dosyaların dahil edileceğini kontrol etmek için iki modu destekler:
@@ -64,6 +96,12 @@ yarn twenty function:execute --preInstall
 # Execute the post-install function
 yarn twenty function:execute --postInstall

+# Build the app for distribution
+yarn twenty app:build
+
+# Publish the app to npm or a Twenty server
+yarn twenty app:publish
+
 # Uninstall the application from the current workspace
 yarn twenty app:uninstall

@@ -1240,6 +1278,113 @@ uploadFile(

 Nesneleri, mantık fonksiyonlarını, ön uç bileşenlerini ve birden çok tetikleyiciyi gösteren minimal, uçtan uca bir örneği [buradan](https://github.com/twentyhq/twenty/tree/main/packages/twenty-apps/hello-world) inceleyin:

+## Uygulamanızı derleme
+
+Uygulamanızı `app:dev` ile geliştirdikten sonra, `app:build` kullanarak onu dağıtılabilir bir pakete derleyin.
+
+```bash filename="Terminal"
+# Build the app (output goes to .twenty/output/)
+yarn twenty app:build
+
+# Build and create a tarball (.tgz) for distribution
+yarn twenty app:build --tarball
+```
+
+Derleme süreci:
+
+1. **Manifesti ayrıştırır ve doğrular** — kaynak dosyalarınızdaki tüm `defineX()` varlıklarını okur ve manifest yapısını doğrular.
+2. **Mantık işlevlerini ve ön bileşenleri derler** — TypeScript kaynaklarını esbuild kullanarak ESM `.mjs` dosyalarına paketler.
+3. **Sağlama toplamları üretir** — her bir oluşturulan dosya için MD5 karmalarını hesaplar ve manifestte `builtHandlerChecksum` / `builtComponentChecksum` olarak saklar.
+4. **Tipli API istemcisini oluşturur** — GraphQL şemasını inceleyip tipli `CoreApiClient` ve `MetadataApiClient` istemcilerini üretir.
+5. **TypeScript tip denetimi çalıştırır** — yayımlamadan önce tip hatalarını yakalamak için `tsc --noEmit` çalıştırır.
+6. **Oluşturulan istemciyle yeniden derler** — oluşturulan istemci tiplerinin dahil edilmesi için ikinci bir derleme geçişi yapar.
+7. **İsteğe bağlı olarak bir tarball oluşturur** — `--tarball` iletilirse, dağıtıma hazır bir `.tgz` dosyası oluşturmak için `npm pack` çalıştırır.
+
+`.twenty/output/` içindeki derleme çıktısı şunları içerir:
+
+```text
+.twenty/output/
+├── manifest.json              # Manifest with checksums for all built files
+├── package.json               # Copied from app root
+├── yarn.lock                  # Copied from app root
+├── src/
+│   ├── logic-functions/       # Compiled .mjs logic function files
+│   └── front-components/      # Compiled .mjs front component files
+├── public/                    # Static assets (if any)
+└── my-app-1.0.0.tgz          # Only with --tarball flag
+```
+
+| Seçenek     | Açıklama                                                  |
+| ----------- | --------------------------------------------------------- |
+| `[appPath]` | Uygulama dizininin yolu (varsayılan olarak geçerli dizin) |
+| `--tarball` | Çıktıyı ayrıca bir `.tgz` tarball olarak paketler         |
+
+## Uygulamanızı yayımlama
+
+Uygulamanızı dağıtmak için `app:publish` komutunu kullanın — npm kayıt defterine ya da doğrudan bir Twenty sunucusuna yayımlayın.
+
+### npm'ye yayımlama (varsayılan)
+
+```bash filename="Terminal"
+# Publish to npm (requires npm login)
+yarn twenty app:publish
+
+# Publish with a dist-tag (e.g. beta, next)
+yarn twenty app:publish --tag beta
+```
+
+Bu, uygulamayı derler ve `.twenty/output/` dizininden `npm publish` çalıştırır. Yayımlanan paket daha sonra Twenty pazar yerinden herhangi bir çalışma alanı tarafından kurulabilir.
+
+### Bir Twenty sunucusuna yayımlama
+
+```bash filename="Terminal"
+# Publish directly to a Twenty server
+yarn twenty app:publish --server https://app.twenty.com
+```
+
+Bu, uygulamayı bir tarball ile derler, `uploadAppTarball` GraphQL mutasyonu aracılığıyla sunucuya yükler ve tek adımda kurulumu tetikler. Bu, özel dağıtımlar veya belirli bir sunucuya karşı test yapmak için kullanışlıdır.
+
+| Seçenek           | Açıklama                                                         |
+| ----------------- | ---------------------------------------------------------------- |
+| `[appPath]`       | Uygulama dizininin yolu (varsayılan olarak geçerli dizin)        |
+| `--server <url>`  | npm yerine bir Twenty sunucusuna yayımlar                        |
+| `--token <token>` | Hedef sunucu için kimlik doğrulama belirteci                     |
+| `--tag <tag>`     | npm dist-tag (örn. `beta`, `next`) — yalnızca npm yayımlama için |
+
+## Uygulama kaydı
+
+Bir uygulama bir çalışma alanına kurulmadan önce kaydedilmelidir. Kayıt, uygulamanın nereden geldiğini ve nasıl kimlik doğrulanacağını açıklayan bir meta veri kaydıdır. Bu, çoğu durumda CLI tarafından otomatik olarak gerçekleştirilir.
+
+### Kaynak türleri
+
+Her kaydın, kurulum sırasında uygulamanın dosyalarının nasıl çözümleneceğini belirleyen bir kaynak türü vardır:
+
+| Kaynak türü | Dosyaların nasıl çözümlendiği                                                       | Tipik kullanım durumu                      |
+| ----------- | ----------------------------------------------------------------------------------- | ------------------------------------------ |
+| `LOCAL`     | Dosyalar, CLI izleyici tarafından gerçek zamanlı olarak eşitlenir — kurulum atlanır | `app:dev` ile geliştirme                   |
+| `NPM`       | `sourcePackage` alanı aracılığıyla npm kayıt defterinden alınır                     | npm'de yayımlanan uygulamalar              |
+| `TARBALL`   | Sunucuda depolanan, yüklenmiş bir `.tgz` dosyasından çıkarılır                      | `--server` ile yayımlanan özel uygulamalar |
+
+### Kayıt nasıl gerçekleşir
+
+* **`app:dev`** — bir çalışma alanına karşı geliştirme modunu ilk kez çalıştırdığınızda otomatik olarak bir `LOCAL` kaydı oluşturur.
+* **`app:publish --server`** — bir tarball yükler ve bir `TARBALL` kaydı oluşturur (veya günceller), ardından uygulamayı kurar.
+* **npm pazar yeri** — uygulamalar npm kayıt defterinden Twenty pazar yeri kataloğuna eşitlendiğinde `NPM` kayıtları oluşturulur.
+* **GraphQL API** — `createApplicationRegistration` mutasyonu aracılığıyla programatik olarak da kayıtlar oluşturabilirsiniz.
+
+### Kayıt ve kurulum
+
+**Kayıt** ve **kurulum** ayrı kavramlardır:
+
+* Bir kayıt (`ApplicationRegistration`), uygulamayı tanımlayan genel bir meta veri kaydıdır: adı, kaynak türü, OAuth kimlik bilgileri ve pazar yeri listeleme durumu. Herhangi bir çalışma alanından bağımsız olarak var olur.
+* Bir kurulum (`Application`), çalışma alanı başına bir örnektir. Bir kullanıcı bir uygulamayı kurduğunda, Twenty paketi kaydın kaynağından çözümler, derlenen dosyaları depolamaya yazar ve manifesti (nesneler, alanlar, mantık işlevleri vb. oluşturarak) eşitler o çalışma alanında.
+
+Bir kayıt birçok çalışma alanına kurulabilir. Her çalışma alanı, uygulamanın dosyalarının ve veri modelinin kendi kopyasını alır.
+
+### OAuth kimlik bilgileri
+
+Her kayıt, oluşturma sırasında üretilen OAuth kimlik bilgilerini (`oAuthClientId` ve `oAuthClientSecret`) içerir. Bunlar, kullanıcılar adına API isteklerini kimlik doğrulamak için uygulama tarafından kullanılır. İstemci gizli anahtarı oluşturma sırasında yalnızca bir kez sağlanır — onu güvenli bir şekilde saklayın. Bunu daha sonra `rotateApplicationRegistrationClientSecret` mutasyonu aracılığıyla yenileyebilirsiniz.
+
 ## Manuel kurulum (scaffolder olmadan)

 En iyi başlangıç deneyimi için `create-twenty-app` kullanmanızı önersek de, bir projeyi manuel olarak da kurabilirsiniz. CLI'yi global olarak kurmayın. Bunun yerine `twenty-sdk`'yi yerel bir bağımlılık olarak ekleyin ve package.json içinde tek bir betik tanımlayın:
@@ -3,7 +3,7 @@ title: 1-Tıklama ile Docker Compose
 ---

 <Warning>
-Docker konteynerleri, üretim ortamında veya kendi sunucunuzda barındırma içindir; katkıda bulunmak için [Yerel Kurulum](/l/tr/developers/contribute/capabilities/local-setup) sayfasına bakın.
+Docker kapsayıcıları, üretim ortamında barındırma veya kendi kendine barındırma içindir. Katkıda bulunmak için lütfen [Yerel Kurulum](/l/tr/developers/contribute/capabilities/local-setup) bölümüne bakın.
 </Warning>

 ## Genel Bakış
@@ -12,7 +12,7 @@ Bu kılavuz, Docker Compose kullanarak Twenty uygulamasını kurmak ve yapıland

 **Önemli:** Yalnızca bu kılavuzda açıkça belirtilen ayarları değiştirin. Diğer yapılandırmaları değiştirmek sorunlara yol açabilir.

-İleri düzey yapılandırma için belgelerdeki [Ortam Değişkenlerini Ayarlama](/l/tr/developers/self-host/capabilities/setup) bölümüne bakın. Tüm ortam değişkenleri, sunucu ve / veya işçi düzeyine bağlı olarak docker-compose.yml dosyasında ilan edilmelidir.
+İleri düzey yapılandırma için [Ortam Değişkenlerini Ayarlama](/l/tr/developers/self-host/capabilities/setup) bölümüne bakın. Tüm ortam değişkenleri, değişkene bağlı olarak sunucu ve/veya işçi düzeyinde `docker-compose.yml` dosyasında tanımlanmalıdır.

 ## Sistem Gereksinimleri

@@ -0,0 +1,142 @@
+---
+title: MCP Sunucusu
+description: Model Context Protocol kullanarak yapay zeka asistanlarını Twenty çalışma alanınıza bağlayın.
+---
+
+<Warning>
+MCP şu anda **alfa** aşamasındadır ve yalnızca bazı çalışma alanlarında kullanılabilir. Çalışma alanınızda henüz etkinleştirilmemiş olabilir.
+</Warning>
+
+Twenty, yapay zeka asistanlarının — Claude Desktop, Claude Code, Cursor, ChatGPT ve diğerlerinin — doğal dil aracılığıyla CRM verilerinizi okuması ve yazması için bir [MCP](https://modelcontextprotocol.io/) sunucusu sunar.
+
+MCP uç noktası olarak **çalışma alanı URL'nizi** (Twenty'ye erişmek için kullandığınız URL) kullanın. Twenty Cloud'da, çalışma alanı URL'niz `https://{mycompany}.twenty.com` ya da özel bir alan adı olabilir. Sunucu şu adreste kullanılabilir:
+
+| Ortam                        | MCP Uç Noktası                                                               |
+| ---------------------------- | ---------------------------------------------------------------------------- |
+| **Bulut**                    | `https://{your-workspace-url}/mcp` (örn. `https://mycompany.twenty.com/mcp`) |
+| **Kendi Kendine Barındırma** | `https://{your-domain}/mcp`                                                  |
+
+## Kimlik Doğrulama Yöntemleri
+
+MCP istemcinizi kimlik doğrulamak için iki yolunuz var: **OAuth** (önerilir) veya **API Anahtarı**.
+
+### Seçenek A — OAuth (Önerilir)
+
+OAuth ile, MCP istemciniz oturum açmanız için bir tarayıcı penceresi açar. Gizli bilgiler yapılandırma dosyalarında saklanmaz ve belirteçler otomatik olarak yenilenir.
+
+<Note>
+OAuth, [MCP Yetkilendirme belirtimi](https://modelcontextprotocol.io/specification/2025-03-26/basic/authorization)ni destekleyen bir MCP istemcisi gerektirir. Claude Desktop, Claude Code, Cursor ve ChatGPT bunu destekler.
+</Note>
+
+Bunu MCP istemci yapılandırmanıza ekleyin; `{your-workspace-url}` öğesini çalışma alanınızın ana makine adıyla değiştirin (örn. `mycompany.twenty.com`):
+
+```json
+{
+  "mcpServers": {
+    "twenty": {
+      "type": "streamable-http",
+      "url": "https://{your-workspace-url}/mcp"
+    }
+  }
+}
+```
+
+Hepsi bu — API anahtarı gerekmez. İstemci ilk kez bağlandığında şunları yapacaktır:
+
+1. Twenty'nin OAuth üst verilerini `/.well-known/oauth-protected-resource` ve `/.well-known/oauth-authorization-server` üzerinden keşfeder
+2. Dinamik istemci kaydı (RFC 7591) yoluyla kendisini bir OAuth istemcisi olarak kaydeder
+3. Erişimi yetkilendirmek için tarayıcınızı açar
+4. Belirteçleri alır ve MCP sunucusuna bağlanır
+
+Sonraki bağlantılar, depolanan belirteçleri yeniden kullanır ve bunları otomatik olarak yeniler.
+
+### Seçenek B — API Anahtarı
+
+MCP istemciniz OAuth'u desteklemiyorsa veya statik kimlik bilgilerini tercih ediyorsanız, `Authorization` üstbilgisinde bir API anahtarı gönderin:
+
+```json
+{
+  "mcpServers": {
+    "twenty": {
+      "type": "streamable-http",
+      "url": "https://{your-workspace-url}/mcp",
+      "headers": {
+        "Authorization": "Bearer YOUR_API_KEY"
+      }
+    }
+  }
+}
+```
+
+<Warning>
+API anahtarınız çalışma alanı verilerine erişim sağlar. Sürüm kontrolünün ve paylaşılan dotfile'ların dışında tutun.
+</Warning>
+
+Bir API anahtarı oluşturmak için **Settings > APIs & Webhooks > + Create key** bölümüne gidin. Ayrıntılar için [API'ler](/l/tr/developers/extend/api#create-an-api-key) bölümüne bakın.
+
+## Hızlı Başlangıç
+
+### 1. Yapılandırmayı kopyalayın
+
+Twenty içinde **Settings > AI > More > MCP Server** bölümüne gidin. Kimlik doğrulama yöntemini (OAuth veya API Anahtarı) seçin, JSON parçacığını kopyalayın (çalışma alanı URL'nizi zaten kullanacaktır) ve MCP istemcinizin yapılandırma dosyasına yapıştırın.
+
+| İstemci            | Yapılandırma dosyasının konumu                                                                                                                                                                   |
+| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| **Claude Desktop** | `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) veya `%APPDATA%\Claude\claude_desktop_config.json` (Windows)                                                           |
+| **Claude Code**    | `~/.claude.json` (kullanıcı) veya `.mcp.json` (proje)                                                                                                                                            |
+| **Cursor**         | Projenizde `.cursor/mcp.json` veya genel olarak `~/.cursor/mcp.json`                                                                                                                             |
+| **ChatGPT**        | Developer Mode'u **Settings > Apps & Connectors > Advanced settings** içinde açın, ardından MCP sunucusunu eklemek için **Settings > Apps & Connectors** içindeki **Create** seçeneğini kullanın |
+
+### 2. Bağlan
+
+MCP istemcinizi yeniden başlatın (veya yapılandırmayı yeniden yükleyin). OAuth kullanıyorsanız, erişimi yetkilendirmek için Twenty'ye yönlendirileceksiniz. API anahtarı kullanıyorsanız, bağlantı anında kurulur.
+
+### 3. Kullanmaya başlayın
+
+Yapay zeka asistanınızdan CRM'inizle etkileşime geçmesini isteyin:
+
+* *"Bana en son oluşturulan 5 şirketi göster"*
+* *"Acme Corp'ta Jane Doe adlı yeni bir kişi oluştur"*
+* *"10.000 $'dan fazla değere sahip tüm açık fırsatları bul"*
+
+## Kullanılabilir Araçlar
+
+Bağlandıktan sonra, MCP sunucusu Twenty API'sini yansıtan araçlar sunar. Önerilen iş akışı:
+
+1. **`get_tool_catalog`** — mevcut tüm araçları keşfedin
+2. **`learn_tools`** — belirli araçların girdi şemasını alın
+3. **`execute_tool`** — bir aracı çalıştırın
+
+Araç adlarını hatırlamanıza gerek yok. Yapay zeka asistanınıza neler yapabileceğini sorun; `get_tool_catalog` çağrısını otomatik olarak yapacaktır.
+
+## İzinler
+
+MCP bağlantıları, kimliği doğrulanmış kullanıcının (OAuth) izinlerini veya API anahtarına atanan rolü devralır. MCP sunucusunun neler yapabileceğini kısıtlamak için:
+
+* **OAuth**: Kullanıcının çalışma alanı rolü geçerlidir.
+* **API Anahtarı**: **Settings > Roles** altında API anahtarına bir rol atayın. Bkz. [İzinler](/l/tr/user-guide/permissions-access/capabilities/permissions).
+
+## Öz Barındırmalı Yapılandırma
+
+Öz barındırmalı kurulumlarda `{your-workspace-url}` değerini sunucunuzun URL'siyle değiştirin. Ortamınızdaki `SERVER_URL` değerinin Twenty örneğinizin genel URL'siyle eşleştiğinden emin olun — bu, OAuth keşif üst verilerini oluşturmak için kullanılır.
+
+```bash
+SERVER_URL=https://twenty.yourcompany.com
+```
+
+MCP uç noktası, OAuth uç noktaları ve keşif üst verilerinin tümü bu değerden türetilir.
+
+## Sorun Giderme
+
+**"Unauthorized" veya 401 hataları**
+
+* OAuth: MCP istemcinizde depolanan belirteçleri temizleyip yeniden bağlanarak yeniden yetkilendirin.
+* API Anahtarı: anahtarın geçerli olduğunu ve süresinin dolmadığını doğrulayın. Gerekirse yeniden oluşturun.
+
+**OAuth akışı bir tarayıcı açmıyor**
+
+* MCP istemcinizin MCP Yetkilendirmeyi desteklediğinden emin olun. Desteklemiyorsa API Anahtarı yöntemine geri dönün.
+
+**Bağlantı zaman aşımı**
+
+* MCP uç noktası URL'sine makinenizden erişilebildiğini doğrulayın. Öz barındırmalı kurulumlar için, sunucunun çalıştığını ve `SERVER_URL` değerinin doğru ayarlandığını kontrol edin.
@@ -6,7 +6,7 @@ description: 本指南适用于希望在本地运行 Twenty 的贡献者或好
 ## 先决条件

 <Tabs>
-<Tab title="Linux 和 MacOS">
+<Tab title="Linux 和 macOS">

 在安装和使用 Twenty 之前，请确保在您的计算机上安装以下内容：
 * [Git](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git)
@@ -30,7 +30,7 @@ wsl --install
 ```
 现在您应该看到一个提示，要求您重启计算机。 如果没有，请手动重启。

-重启后，一个 powershell 窗口将打开并安装 Ubuntu。 这可能需要一些时间。
+重启后，将打开一个 PowerShell 窗口并安装 Ubuntu。 这可能需要一些时间。
 您将看到一个提示，要求为您的 Ubuntu 安装创建用户名和密码。

 2. 安装和配置 git
@@ -102,8 +102,8 @@ cd twenty

 <Tabs>
  <Tab title="Linux">
-    \*\*选项 1（推荐）：\*\*在本地供应您的数据库：
-    使用以下链接在 Linux 机器上安装 Postgresql：[Postgresql 安装](https://www.postgresql.org/download/linux/)
+    \*\*选项 1（首选）：\*\*要在本地预配您的数据库：
+    使用以下链接在 Linux 机器上安装 PostgreSQL：[PostgreSQL 安装](https://www.postgresql.org/download/linux/)
    ```bash
      psql postgres -c "CREATE DATABASE \"default\";" -c "CREATE DATABASE test;"
    ```
@@ -129,7 +129,8 @@ cd twenty
      brew services list
    ```

-    安装器在通过 Homebrew 安装时可能不会默认创建 `postgres` 用户。 相反，它会创建一个与您的 macOS 用户名（例如，“john”）匹配的 PostgreSQL 角色。
+    在 macOS 上通过 Homebrew 安装时
+    安装程序可能不会默认创建 `postgres` 用户。 相反，它会创建一个与您的 macOS 用户名（例如，“john”）匹配的 PostgreSQL 角色。
    按照以下步骤检查并在必要时创建 `postgres` 用户：
    ```bash
      # Connect to PostgreSQL
@@ -171,8 +172,8 @@ cd twenty
  <Tab title="Windows (WSL)">
    以下所有步骤应在 WSL 终端（在您的虚拟机内）中运行

-    \*\*选项 1：\*\*在本地提供您的 Postgresql：
-    使用以下链接在 Linux 虚拟机上安装 Postgresql：[Postgresql 安装](https://www.postgresql.org/download/linux/)
+    \*\*选项 1：\*\*要在本地预配您的 PostgreSQL：
+    使用以下链接在 Linux 虚拟机上安装 PostgreSQL：[PostgreSQL 安装](https://www.postgresql.org/download/linux/)
    ```bash
      psql postgres -c "CREATE DATABASE \"default\";" -c "CREATE DATABASE test;"
    ```
@@ -187,11 +188,13 @@ cd twenty
  </Tab>
 </Tabs>

-您现在可以在 [localhost:5432](localhost:5432) 访问数据库，用户名 `postgres`，密码 `postgres`。
+您现在可以通过 `localhost:5432` 访问数据库。
+
+如果您使用了上面的 Docker 选项，默认凭据为用户 `postgres`、密码 `postgres`。 对于原生 PostgreSQL 安装，请使用在您的机器上已配置的凭据和角色。

 ## 步骤 4：设置 Redis 数据库（缓存）

-Twenty 需要 Redis 缓存来提供最佳性能
+Twenty 需要 Redis 缓存来提供最佳性能。

 <Tabs>
  <Tab title="Linux">
@@ -208,8 +211,10 @@ Twenty 需要 Redis 缓存来提供最佳性能
    ```bash
    brew install redis
    ```
-    启动您的 redis server：
-    `brew services start redis`
+    启动您的 Redis 服务器：
+    ```bash
+    brew services start redis
+    ```

    \*\*选项 2：\*\*如果您已安装 docker：
    ```bash
@@ -227,11 +232,11 @@ Twenty 需要 Redis 缓存来提供最佳性能
  </Tab>
 </Tabs>

-如果您需要客户端 GUI，我们推荐 [redis insight](https://redis.io/insight/)（提供免费版）
+如果您需要客户端 GUI，我们推荐 [Redis Insight](https://redis.io/insight/)（提供免费版本）。

 ## 步骤 5：设置环境变量

-使用环境变量或 `.env` 文件配置您的项目。 更多信息请参见 [此处](/l/zh/developers/self-host/capabilities/setup)
+使用环境变量或 `.env` 文件配置您的项目。 更多信息请参见 [此处](/l/zh/developers/self-host/capabilities/setup).

 复制 `/front` 和 `/server` 目录中的 `.env.example` 文件：

@@ -21,19 +21,51 @@ description: 以代码的形式构建并管理 Twenty 自定义项。
 ## 先决条件

 * Node.js 24+ 和 Yarn 4
-* 一个 Twenty 工作空间和一个 API 密钥（在 https://app.twenty.com/settings/api-webhooks 创建）
+* Docker (用于本地 Twenty 开发服务器)

 ## 开始使用

-使用官方脚手架创建一个新应用，然后进行身份验证并开始开发：
+使用官方脚手架创建一个新应用。 它可以为你自动启动一个本地 Twenty 实例：

 ```bash filename="Terminal"
-# 创建一个新应用脚手架（默认包含所有示例）
+# Scaffold a new app — the CLI will offer to start a local Twenty server
 npx create-twenty-app@latest my-twenty-app
 cd my-twenty-app

-# 启动开发模式：会将本地更改自动同步到你的工作区
-yarn twenty app:dev
+# Start dev mode: automatically syncs local changes to your workspace
+yarn twenty dev
+```
+
+### 本地服务器管理
+
+该 SDK 包含用于管理本地 Twenty 开发服务器的命令（该服务器是一体化 Docker 镜像，内含 PostgreSQL、Redis、服务器和工作进程）：
+
+```bash filename="Terminal"
+# Start the local server (pulls the image if needed)
+yarn twenty server start
+
+# Check server status
+yarn twenty server status
+
+# Stream server logs
+yarn twenty server logs
+
+# Stop the server
+yarn twenty server stop
+
+# Reset all data and start fresh
+yarn twenty server reset
+```
+
+本地服务器预置了一个工作区和用户 (`tim@apple.dev` / `tim@apple.dev`)，因此你可以无需任何手动设置即可立即开始开发。
+
+### 身份验证
+
+使用 OAuth 将你的应用连接到本地服务器：
+
+```bash filename="Terminal"
+# 通过 OAuth 进行身份验证 (将打开浏览器)
+yarn twenty remote add --local
 ```

 脚手架工具支持两种模式，用于控制包含哪些示例文件：
@@ -49,25 +81,31 @@ npx create-twenty-app@latest my-app --minimal
 从这里您可以：

 ```bash filename="Terminal"
-# 向你的应用添加一个新实体（引导式）
+# Add a new entity to your application (guided)
 yarn twenty entity:add

-# 监听你的应用函数日志
+# Watch your application's function logs
 yarn twenty function:logs

-# 按名称执行一个函数
+# Execute a function by name
 yarn twenty function:execute -n my-function -p '{"name": "test"}'

-# 执行安装前函数
+# Execute the pre-install function
 yarn twenty function:execute --preInstall

-# 执行安装后函数
+# Execute the post-install function
 yarn twenty function:execute --postInstall

-# 从当前工作区卸载该应用
+# Build the app for distribution
+yarn twenty app:build
+
+# Publish the app to npm or a Twenty server
+yarn twenty app:publish
+
+# Uninstall the application from the current workspace
 yarn twenty app:uninstall

-# 显示命令帮助
+# Display commands' help
 yarn twenty help
 ```

@@ -1240,6 +1278,113 @@ uploadFile(

 在[此处](https://github.com/twentyhq/twenty/tree/main/packages/twenty-apps/hello-world)查看一个最小的端到端示例，展示对象、逻辑函数、前端组件和多种触发器：

+## Building your app
+
+Once you've developed your app with `app:dev`, use `app:build` to compile it into a distributable package.
+
+```bash filename="Terminal"
+# Build the app (output goes to .twenty/output/)
+yarn twenty app:build
+
+# Build and create a tarball (.tgz) for distribution
+yarn twenty app:build --tarball
+```
+
+The build process:
+
+1. **Parses and validates the manifest** — reads all `defineX()` entities from your source files and validates the manifest structure.
+2. **Compiles logic functions and front components** — bundles TypeScript sources into ESM `.mjs` files using esbuild.
+3. **Generates checksums** — computes MD5 hashes for each built file, stored in the manifest as `builtHandlerChecksum` / `builtComponentChecksum`.
+4. **生成类型化的 API 客户端** — 对 GraphQL 架构进行自省，并生成带类型的 `CoreApiClient` 和 `MetadataApiClient` 客户端。
+5. **运行 TypeScript 类型检查** — 运行 `tsc --noEmit` 以在发布前捕获类型错误。
+6. **使用生成的客户端重新构建** — 执行第二次编译，以便包含生成的客户端类型。
+7. **可选地创建一个 tar 包** — 如果传入 `--tarball`，则运行 `npm pack` 以创建用于分发的 `.tgz` 文件。
+
+`.twenty/output/` 中的构建产物包含：
+
+```text
+.twenty/output/
+├── manifest.json              # Manifest with checksums for all built files
+├── package.json               # Copied from app root
+├── yarn.lock                  # Copied from app root
+├── src/
+│   ├── logic-functions/       # Compiled .mjs logic function files
+│   └── front-components/      # Compiled .mjs front component files
+├── public/                    # Static assets (if any)
+└── my-app-1.0.0.tgz          # Only with --tarball flag
+```
+
+| 选项          | 描述                      |
+| ----------- | ----------------------- |
+| `[appPath]` | 应用目录的路径（默认为当前目录）        |
+| `--tarball` | 同时将输出打包为一个 `.tgz` tar 包 |
+
+## 发布你的应用
+
+使用 `app:publish` 分发你的应用 — 可以发布到 npm 注册表，或直接发布到 Twenty 服务器。
+
+### 发布到 npm（默认）
+
+```bash filename="Terminal"
+# Publish to npm (requires npm login)
+yarn twenty app:publish
+
+# Publish with a dist-tag (e.g. beta, next)
+yarn twenty app:publish --tag beta
+```
+
+这会构建应用，并在 `.twenty/output/` 目录下运行 `npm publish`。 发布后的软件包可由任何工作区从 Twenty 市场进行安装。
+
+### 发布到 Twenty 服务器
+
+```bash filename="Terminal"
+# Publish directly to a Twenty server
+yarn twenty app:publish --server https://app.twenty.com
+```
+
+这会以 tar 包方式构建应用，通过 `uploadAppTarball` GraphQL 变更将其上传到服务器，并在一步中触发安装。 这对于私有部署或针对特定服务器进行测试非常有用。
+
+| 选项                | 描述                                         |
+| ----------------- | ------------------------------------------ |
+| `[appPath]`       | 应用目录的路径（默认为当前目录）                           |
+| `--server <url>`  | 发布到 Twenty 服务器（而非 npm）                     |
+| `--token <token>` | 目标服务器的身份验证令牌                               |
+| `--tag <tag>`     | npm dist-tag（例如 `beta`、`next`）— 仅用于发布到 npm |
+
+## 应用注册
+
+在应用安装到工作区之前，必须先进行**注册**。 注册是一条元数据记录，用于描述应用的来源以及如何对其进行身份验证。 在大多数情况下，CLI 会自动处理这一流程。
+
+### 来源类型
+
+每个注册都有一个**来源类型**，用于决定安装期间如何解析应用的文件：
+
+| 来源类型      | 文件的解析方式                          | 典型用例                  |
+| --------- | -------------------------------- | --------------------- |
+| `LOCAL`   | 文件由 CLI 监听器实时同步——跳过安装步骤          | 使用 `app:dev` 进行开发     |
+| `NPM`     | 通过 `sourcePackage` 字段从 npm 注册表获取 | 在 npm 上发布的应用          |
+| `TARBALL` | 从存储在服务器上的已上传 `.tgz` 文件中解压获得      | 使用 `--server` 发布的私有应用 |
+
+### 注册如何进行
+
+* **`app:dev`** — 第一次针对某个工作区运行开发模式时，会自动创建一个 `LOCAL` 注册。
+* **`app:publish --server`** — 上传一个 tar 包并创建（或更新）一个 `TARBALL` 注册，然后安装应用。
+* **npm 市场** — 当应用从 npm 注册表同步到 Twenty 市场目录时，会创建 `NPM` 注册。
+* **GraphQL API** — 你也可以通过 `createApplicationRegistration` 变更以编程方式创建注册。
+
+### 注册与安装
+
+**注册** 与 **安装** 是两个独立的概念：
+
+* **注册**（`ApplicationRegistration`）是一条全局元数据记录，用于描述应用：其名称、来源类型、OAuth 凭据以及在市场中的上架状态。 它独立于任何工作区存在。
+* **安装**（`Application`）是一个按工作区划分的实例。 当用户安装一个应用时，Twenty 会根据注册的来源解析软件包，将构建生成的文件写入存储，并同步清单（创建对象、字段、逻辑函数等） 到该工作区中。
+
+一个注册可以安装到多个工作区。 每个工作区都会获得应用文件和数据模型的独立副本。
+
+### OAuth 凭据
+
+每个注册都包含在创建时生成的 OAuth 凭据（`oAuthClientId` 和 `oAuthClientSecret`）。 应用使用这些凭据代表用户对 API 请求进行身份验证。 客户端密钥在创建时只会返回**一次**——请妥善保管。 你可以稍后通过 `rotateApplicationRegistrationClientSecret` 变更来轮换它。
+
 ## 手动设置（不使用脚手架）

 虽然我们建议使用 `create-twenty-app` 以获得最佳的上手体验，但你也可以手动设置项目。 不要全局安装 CLI。 相反，请将 `twenty-sdk` 添加为本地依赖，并在你的 package.json 中配置一个脚本：
@@ -3,7 +3,7 @@ title: 1-点击使用Docker Compose
 ---

 <Warning>
-Docker容器用于生产托管或自托管，关于贡献，请查看[本地设置](/l/zh/developers/contribute/capabilities/local-setup)。
+Docker 容器适用于生产环境托管或自托管。 如需参与贡献，请查看[本地设置](/l/zh/developers/contribute/capabilities/local-setup)。
 </Warning>

 ## 概览
@@ -12,7 +12,7 @@ Docker容器用于生产托管或自托管，关于贡献，请查看[本地设

 **重要:** 仅修改本指南中明确提到的设置。 更改其他配置可能会导致问题。

-请参阅文档[设置环境变量](/l/zh/developers/self-host/capabilities/setup)获取高级配置。 所有环境变量必须在docker-compose.yml文件中根据变量声明在服务器和/或工作器级别。
+有关高级配置，请参阅[设置环境变量](/l/zh/developers/self-host/capabilities/setup)。 所有环境变量必须在 `docker-compose.yml` 文件中声明，具体在服务器和/或 worker 层级，取决于变量。

 ## 系统要求

--- a/Show More
+++ b/Show More