snapshot of https://github.com/twentyhq/twenty.git (main, 2026-09-17; blobs > 131072B omitted)

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

@@ -0,0 +1,102 @@
+---
+title: Concepts
+description: How Twenty apps work — entity model, sandboxing, and the install lifecycle.
+icon: "sitemap"
+---
+
+Twenty apps are TypeScript packages that extend your workspace with custom objects, logic, UI components, and AI capabilities. They run on the Twenty platform with full sandboxing and permission controls.
+
+## How apps work
+
+An app is a collection of **entities** declared using `defineEntity()` functions from the `twenty-sdk` package. The SDK detects these declarations via AST analysis at build time and produces a **manifest** — a complete description of what your app adds to a workspace. These functions validate your configuration at build time and provide IDE autocompletion and type safety.
+
+```
+your-app/
+├── src/
+│   ├── application-config.ts    ← defineApplication (required, one per app)
+│   ├── roles/                   ← defineRole
+│   ├── objects/                 ← defineObject
+│   ├── fields/                  ← defineField
+│   ├── logic-functions/         ← defineLogicFunction
+│   ├── front-components/        ← defineFrontComponent
+│   ├── skills/                  ← defineSkill
+│   ├── agents/                  ← defineAgent
+│   ├── views/                   ← defineView
+│   ├── navigation-menu-items/   ← defineNavigationMenuItem
+│   └── page-layouts/            ← definePageLayout
+├── public/                      ← Static assets (images, icons)
+└── package.json
+```
+
+<Note>
+  **File organization is up to you.** Entity detection is AST-based — the SDK finds `export default defineEntity(...)` calls regardless of where the file lives. The folder structure above is a convention, not a requirement.
+</Note>
+
+## Entity types
+
+| Entity | Purpose | Docs |
+|--------|---------|------|
+| **Application** | App identity, default role, variables | [Application Config](/developers/extend/apps/config/application) |
+| **Role** | Permission sets on objects and fields | [Roles & Permissions](/developers/extend/apps/config/roles) |
+| **Object** | Custom record types with fields | [Objects](/developers/extend/apps/data/objects) |
+| **Field** | Add fields to objects from other apps | [Extending Objects](/developers/extend/apps/data/extending-objects) |
+| **Relation** | Bidirectional links between objects | [Relations](/developers/extend/apps/data/relations) |
+| **Logic Function** | Server-side TypeScript with triggers | [Logic Functions](/developers/extend/apps/logic/logic-functions) |
+| **Skill** | Reusable AI agent instructions | [Skills & Agents](/developers/extend/apps/logic/skills-and-agents) |
+| **Agent** | AI assistants with custom prompts | [Skills & Agents](/developers/extend/apps/logic/skills-and-agents) |
+| **Connection Provider** | OAuth credentials for third-party APIs | [Connections](/developers/extend/apps/logic/connections) |
+| **View** | Pre-configured record list views | [Views](/developers/extend/apps/layout/views) |
+| **Navigation Menu Item** | Custom sidebar entries | [Navigation Menu Items](/developers/extend/apps/layout/navigation-menu-items) |
+| **Page Layout** | Tabs and widgets on a record's detail page | [Page Layouts](/developers/extend/apps/layout/page-layouts) |
+| **Front Component** | Sandboxed React UI inside Twenty | [Front Components](/developers/extend/apps/layout/front-components) |
+| **Shared Dependencies** | Dependencies shared by the app's front components, declared in package.json | [Shared Dependencies](/developers/extend/apps/layout/front-components#sharing-dependencies-across-front-components) |
+| **Command Menu Item** | Quick actions and Cmd+K entries | [Command Menu Items](/developers/extend/apps/layout/command-menu-items) |
+
+## Sandboxing
+
+- **Logic functions** run in isolated Node.js processes on the server. They only access data through the typed API client, which acts either as the person who triggered the run or as the app itself. See [Whose access a call uses](/developers/extend/apps/logic/logic-functions#whose-access-a-call-uses).
+- **Front components** run in Web Workers using Remote DOM — sandboxed from the main page but rendering native DOM elements (not iframes). They communicate with Twenty via a message-passing host API.
+- **Permissions** are enforced at the API level. Two runtime tokens are injected, both derived from the role declared with `defineApplicationRole()`; the default one is narrowed further to what the triggering person can do whenever someone is behind the run.
+
+## App lifecycle
+
+```
+┌─────────────────────────────────────────────────────────┐
+│ Development                                             │
+│   npx create-twenty-app → yarn twenty dev (live sync)   │
+├─────────────────────────────────────────────────────────┤
+│ Build & Deploy                                          │
+│   yarn twenty dev:build → yarn twenty app:publish        │
+├─────────────────────────────────────────────────────────┤
+│ Install flow                                            │
+│   upload → [pre-install] → metadata migration →         │
+│   generate SDK → [post-install] → … → [uninstall]       │
+├─────────────────────────────────────────────────────────┤
+│ Publish                                                 │
+│   npm publish → appears in Twenty marketplace           │
+└─────────────────────────────────────────────────────────┘
+```
+
+- **`yarn twenty dev`** — watches your source files and live-syncs changes to a connected Twenty server. The typed API client is regenerated automatically when the schema changes.
+- **`yarn twenty dev:build`** — compiles TypeScript, bundles logic functions and front components with esbuild, and produces a manifest.
+- **Pre/post-install and uninstall hooks** — optional functions that run during installation or right before removal. See [Install Hooks](/developers/extend/apps/config/install-hooks) for details.
+
+## Next steps
+
+<CardGroup cols={2}>
+  <Card title="Config" icon="screwdriver-wrench" href="/developers/extend/apps/config/overview">
+    Application identity, default role, and install and uninstall hooks.
+  </Card>
+  <Card title="Data" icon="database" href="/developers/extend/apps/data/overview">
+    Objects, fields, and bidirectional relations.
+  </Card>
+  <Card title="Logic" icon="bolt" href="/developers/extend/apps/logic/overview">
+    Logic functions, skills, agents, and OAuth connections.
+  </Card>
+  <Card title="Layout" icon="table-columns" href="/developers/extend/apps/layout/overview">
+    Views, navigation, page layouts, front components.
+  </Card>
+  <Card title="Operations" icon="rocket" href="/developers/extend/apps/operations/overview">
+    CLI, testing, remotes, CI, and publishing your app.
+  </Card>
+</CardGroup>

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

@@ -0,0 +1,87 @@
+---
+title: Local Server
+description: Manage the local Twenty Docker server — start, stop, upgrade, parallel test instance, and manual SDK setup.
+icon: "server"
+---
+
+## Managing the local server
+
+Use `yarn twenty docker:*` to control the local Twenty container:
+
+| Command | What it does |
+|---------|--------------|
+| `yarn twenty docker:start` | Start the server (pulls the image if needed) |
+| `yarn twenty docker:start 2.2.0` | Start a specific server version |
+| `yarn twenty docker:start --port 3030` | Start on a custom port |
+| `yarn twenty docker:stop` | Stop the server (preserves data) |
+| `yarn twenty docker:status` | Show URL, version, and login credentials |
+| `yarn twenty docker:logs` | Stream server logs |
+| `yarn twenty docker:reset` | Wipe data and start fresh |
+| `yarn twenty docker:upgrade` | Pull the latest `twenty-app-dev` image |
+| `yarn twenty docker:upgrade 2.2.0` | Upgrade to a specific version |
+
+Data persists across restarts in two Docker volumes (`twenty-app-dev-data` for PostgreSQL, `twenty-app-dev-storage` for files). Use `reset` to wipe everything.
+
+## Pinning the server version
+
+When no version is passed, `docker:start` resolves the version from your app's `engines.twenty` range in `package.json` — the same range the server validates against when your app is installed. It starts the newest published `twenty-app-dev` image that satisfies the range, falling back to `latest` when the field is absent or no published version matches:
+
+```json filename="package.json"
+{
+  "engines": {
+    "twenty": ">=2.2.0"
+  }
+}
+```
+
+Pass a version explicitly to override the range for a single run: `yarn twenty docker:start 2.3.0`. If a container already exists on a different version, `docker:start` upgrades it in place (recreating the container while preserving your data volumes).
+
+## Upgrading the server image
+
+`yarn twenty docker:upgrade` pulls the latest image, compares digests, and only recreates the container if anything actually changed. Volumes are preserved — only the container is replaced. If a new image was pulled and the container was running, the upgrade automatically starts a new container; run `yarn twenty docker:start` afterward to wait for it to become healthy.
+
+```bash filename="Terminal"
+yarn twenty docker:upgrade            # Latest
+yarn twenty docker:upgrade 2.2.0      # Specific version
+```
+
+Verify the running version with `yarn twenty docker:status` (it shows the `APP_VERSION` baked into the container).
+
+## Running a parallel test instance
+
+Pass `--test` to any `docker:*` command to manage a second, fully isolated instance — useful for integration tests or experiments without touching your main dev data:
+
+| Command | What it does |
+|---------|--------------|
+| `yarn twenty docker:start --test` | Start the test instance (defaults to port 2021) |
+| `yarn twenty docker:stop --test` | Stop it |
+| `yarn twenty docker:status --test` | Show its status |
+| `yarn twenty docker:logs --test` | Stream its logs |
+| `yarn twenty docker:reset --test` | Wipe its data |
+| `yarn twenty docker:upgrade --test` | Upgrade its image |
+
+The test instance has its own container (`twenty-app-dev-test`), volumes (`twenty-app-dev-test-data`, `twenty-app-dev-test-storage`), and config — it runs alongside your main instance without conflicts. Combine `--test` with `--port` to override 2021.
+
+## Manual setup (without the scaffolder)
+
+Skip the scaffolder if you're adding the SDK to an existing project:
+
+```bash filename="Terminal"
+yarn add twenty-sdk twenty-client-sdk
+```
+
+Add the script to `package.json`:
+
+```json filename="package.json"
+{
+  "scripts": {
+    "twenty": "twenty"
+  }
+}
+```
+
+You can now run `yarn twenty dev`, `yarn twenty docker:start`, and the rest.
+
+<Note>
+Don't install `twenty-sdk` globally — pin it per project so each app uses its own version.
+</Note>

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

@@ -0,0 +1,82 @@
+---
+title: Project Structure
+description: What's inside a scaffolded Twenty app — files, folders, and what each one does.
+icon: "folder-tree"
+---
+
+A new app generated by `npx create-twenty-app` looks like this:
+
+```text filename="my-twenty-app/"
+my-twenty-app/
+  package.json
+  src/
+    application-config.ts                   # Required — your app's entry point
+    default-role.ts                         # Permissions for logic functions
+    constants/
+      universal-identifiers.ts              # Auto-generated UUIDs and metadata
+    front-components/
+      main-page.tsx                         # Welcome page component
+    navigation-menu-items/
+      main-page.navigation-menu-item.ts     # Sidebar entry for the welcome page
+    page-layouts/
+      main-page.page-layout.ts              # Standalone page hosting the component
+    __tests__/
+      application-config.test.ts            # Unit test
+      global-setup.ts                       # Integration test setup (sync + uninstall)
+      schema.integration-test.ts            # Integration test against a live server
+  .github/workflows/
+    ci.yml                                  # Lint, typecheck, unit + integration tests
+    cd.yml                                  # Deploy + install on push to main
+    publish.yml                             # Publish to npm on version tags (with provenance)
+  public/
+    logo.svg                                # Static assets
+  locales/
+    en.json                                 # Source catalog; add <locale>.json files next to it
+  vitest.config.ts                          # Integration test runner config
+  vitest.unit.config.ts                     # Unit test runner config
+  tsconfig.json, tsconfig.spec.json
+  .nvmrc, .yarnrc.yml, .oxlintrc.json
+  README.md, AGENTS.md, CLAUDE.md, CHANGELOG.md, SETUP.md
+```
+
+## Key files
+
+| File / Folder | Purpose |
+|---|---|
+| `src/application-config.ts` | **Required.** The main configuration file for your app. |
+| `src/default-role.ts` | Default role controlling what your logic functions can access. |
+| `src/constants/universal-identifiers.ts` | Auto-generated UUIDs and metadata (display name, description). |
+| `src/front-components/`, `src/navigation-menu-items/`, `src/page-layouts/` | A starter welcome page: a front component rendered by a standalone page layout, reachable from the sidebar. |
+| `src/__tests__/` | A unit test plus an integration test (with its global setup) that syncs the app against a real server. |
+| `public/` | Static assets (images, fonts) served with your app. |
+| `locales/` | Translation catalogs. `en.json` is the source catalog `dev:translations-extract` fills in; the set of files here is what a sync publishes, so an empty folder declares no translations. `locales/compiled/` is written by `pull` for entries whose source strings are not in the tree yet, is published by a sync too, and is not meant to be edited by hand. |
+| `AGENTS.md` / `CLAUDE.md` | Guidance for AI coding agents working on the app. |
+| `CHANGELOG.md` / `SETUP.md` | Changelog of notable changes and setup instructions for local development. |
+
+<Note>
+**File organization is up to you.** The folders above are conventions — the SDK detects entities via AST analysis on `export default defineEntity(...)` calls regardless of where the file lives.
+</Note>
+
+## Dependencies
+
+The Twenty SDK and UI packages belong under `devDependencies`:
+
+```json filename="package.json"
+{
+  "dependencies": {},
+  "devDependencies": {
+    "twenty-client-sdk": "2.40.0",
+    "twenty-sdk": "2.40.0",
+    "twenty-ui": "2.40.0"
+  }
+}
+```
+
+The scaffolder pins `twenty-sdk`, `twenty-client-sdk`, and `twenty-ui` to its own version. Keep all three in sync when upgrading.
+
+- **`twenty-sdk`** ships the `twenty` CLI and the build/scaffolding tooling. It only runs at development and build time and is never imported by your published app's runtime.
+- **`twenty-client-sdk`** _is_ imported by your app code (`CoreApiClient`, `MetadataApiClient`, `RestApiClient`), but Twenty provides it at runtime — logic functions get it from a generated SDK layer, and front components resolve it from server-served modules. Your installed copy is only used for typechecking and the deploy-time build, so it never needs to ship in the deployed bundle.
+
+Keeping either package under `dependencies` pulls it into the installed app's runtime bundle, where it is dead weight. `twenty dev:build` emits a warning when either is still listed under `dependencies`.
+
+Add your app's own runtime dependencies (libraries your logic functions actually import at runtime) under `dependencies` as usual. Keep the tree lean: `dependencies` are installed into a runtime layer capped at 250MB unpacked, and a sync or install fails with a dependencies size error beyond that — UI libraries and dev tooling belong in `devDependencies`.

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

@@ -0,0 +1,186 @@
+---
+title: Quick Start
+icon: "rocket"
+description: Create your first Twenty app in minutes.
+---
+
+## Prerequisites
+
+- **Node.js 24.5+** — [Download](https://nodejs.org/)
+- **Yarn 4** — bundled with Node via Corepack. Enable it: `corepack enable`
+- **Docker** — [Download](https://www.docker.com/products/docker-desktop/). Needed to run a local Twenty server. Skip if you already have Twenty running elsewhere.
+
+Building a Twenty app has three phases. The scaffolder collapses them into one happy-path command, but each phase is a separate concept — when something fails, knowing which phase you're in tells you what to fix.
+
+| Phase | What you do | Tool | Result |
+|---|---|---|---|
+| **1. Scaffold** | Generate the app's source code | `npx create-twenty-app` | A TypeScript project on disk |
+| **2. Run a server** | Start a Twenty server to sync into | Docker + `yarn twenty docker:start` | A running Twenty instance |
+| **3. Sync** | Live-sync your code to the server | `yarn twenty dev` | Your changes appear in the UI |
+
+---
+
+## Phase 1 — Scaffold your project
+
+Create a new app from the template:
+
+```bash filename="Terminal"
+npx create-twenty-app@latest my-twenty-app
+```
+
+The scaffolder is non-interactive: the directory name becomes the app name. Pass `--display-name` and `--description` to customize the generated metadata (you can also edit it later in `src/constants/universal-identifiers.ts`). This generates a TypeScript project in `my-twenty-app/` with a starter `application-config.ts`, a default role, CI/CD workflows, and an integration test.
+
+**After this phase:** you have an app's source code on your machine. It isn't running yet — that's Phase 2.
+
+---
+
+## Phase 2 — Run a local Twenty server
+
+Your app needs a Twenty server to sync into. The server is a full Twenty instance — UI, GraphQL API, PostgreSQL — running locally in Docker. Your local code uploads its definitions to that server, which makes them appear in the UI.
+
+The scaffolder starts one for you: with Docker running, it pulls the `twentycrm/twenty-app-dev` image, starts it on port `2020`, and authenticates the CLI against the pre-seeded demo workspace (`tim@apple.dev`) — no sign-in required.
+
+To connect to an existing Twenty server instead, pass `--url <your-server-url>`. Remote servers authenticate with OAuth: a browser opens so you can sign in and click **Authorize**, which gives the CLI access to your workspace. (You can also opt into OAuth locally with `--authentication-method oauth` — sign in with `tim@apple.dev` / `tim@apple.dev`.)
+
+<div style={{textAlign: 'center'}}>
+  <img src="/images/docs/developers/extends/apps/login.png" alt="Twenty login screen" />
+</div>
+
+<div style={{textAlign: 'center'}}>
+  <img src="/images/docs/developers/extends/apps/authorize.png" alt="Twenty CLI authorization screen" />
+</div>
+
+Your terminal will confirm everything is set up.
+
+<div style={{textAlign: 'center'}}>
+  <img src="/images/docs/developers/extends/apps/scaffolded.png" alt="App scaffolded successfully" />
+</div>
+
+**After this phase:** you have a running Twenty server at [http://localhost:2020](http://localhost:2020) with your CLI authorized to sync to it.
+
+<Note>
+If Docker isn't installed or running, the scaffolder will tell you the right start command for your OS. Once Docker is up, you can resume with `yarn twenty docker:start` — no need to re-scaffold.
+</Note>
+
+---
+
+## Phase 3 — Sync your changes
+
+This is the inner loop you'll spend most of your time in.
+
+```bash filename="Terminal"
+cd my-twenty-app
+yarn twenty dev
+```
+
+This watches `src/`, rebuilds on every change, and syncs the result to the server. Edit a file, save, and within a few seconds the server reflects the change. You'll see a live status panel in your terminal.
+
+For more detailed output (build logs, sync requests, error traces), add `--verbose`.
+
+<div style={{textAlign: 'center'}}>
+  <img src="/images/docs/developers/extends/apps/dev.png" alt="Dev mode terminal output" />
+</div>
+
+Open [http://localhost:2020/settings/applications#developer](http://localhost:2020/settings/applications#developer). You should see your app under **Your Apps**.
+
+<div style={{textAlign: 'center'}}>
+  <img src="/images/docs/developers/extends/apps/app-in-ui-1.png" alt="Your Apps list showing My twenty app" />
+</div>
+
+Click **My twenty app** to see its **application registration** — a server-level record describing your app (name, identifier, OAuth credentials, source). One registration can be installed across multiple workspaces on the same server.
+
+<div style={{textAlign: 'center'}}>
+  <img src="/images/docs/developers/extends/apps/app-in-ui-2.png" alt="Application registration details" />
+</div>
+
+Click **View installed app** to see the workspace install. The **About** tab shows version and management options.
+
+<div style={{textAlign: 'center'}}>
+  <img src="/images/docs/developers/extends/apps/app-in-ui-3.png" alt="Installed app" />
+</div>
+
+**After this phase:** you have a live development loop. Edit any file in `src/` and it appears in the UI.
+
+### One-shot sync for CI and scripts
+
+Use `plan` and `apply` to run the same pipeline once, without a watcher:
+
+```bash filename="Terminal"
+yarn twenty plan   # preview the metadata changes without applying them
+yarn twenty apply  # show the plan, then apply it
+```
+
+| Command | Behavior | When to use |
+|---------|----------|-------------|
+| `yarn twenty dev` | Watches and re-syncs on every change. Runs until you stop it. | Interactive local development. |
+| `yarn twenty apply` | Single build + sync, exits `0` on success, `1` on failure. Asks for confirmation on destructive changes (pass `--force` to skip). | CI, pre-commit hooks, AI agents, scripted workflows. |
+| `yarn twenty plan` | Builds and prints the metadata changes **without applying them**. | Inspecting what a sync would change before committing to it. |
+
+All modes need an authenticated remote. See [Syncing & recovery](/developers/extend/apps/operations/sync-and-recovery#previewing-changes-plan) for more on `plan`.
+
+<Note>
+All three modes require your workspace to own the app's registration. The sync is refused when the `universalIdentifier` from your app config is registered to another workspace, or to no workspace yet — apps imported from the marketplace catalog start unowned and have to be claimed first. See [Registration ownership](/developers/extend/apps/operations/publishing#registration-ownership).
+</Note>
+
+<Note>
+`yarn twenty dev --once` and `yarn twenty dev --once --dry-run` are deprecated aliases for `yarn twenty apply` and `yarn twenty plan`.
+</Note>
+
+### Dev mode options
+
+| Flag | Description |
+|------|-------------|
+| `--force` | Apply destructive changes (deletes) without confirmation. |
+| `--no-delete` | Keep entities that are missing from your source instead of deleting them. Also accepted by `plan` and `apply`. |
+| `--debounceMs <ms>` | Set the file-change debounce delay in milliseconds (default: `1000`). |
+| `--verbose` / `--debug` | Show detailed build logs, sync requests, and error traces. |
+
+## What you can build
+
+Apps are composed of **entities** — each defined as a TypeScript file with a single `export default`:
+
+| Entity | What it does |
+|--------|-------------|
+| **Objects & Fields** | Custom data models (Post Card, Invoice, etc.) with typed fields |
+| **Logic functions** | Server-side TypeScript triggered by HTTP routes, cron schedules, or database events |
+| **Front components** | React components that render inside Twenty's UI (side panel, widgets, command menu) |
+| **Skills & Agents** | AI capabilities — reusable instructions and autonomous assistants |
+| **Views & Navigation** | Pre-configured list views and sidebar menu items |
+| **Page layouts** | Custom record detail pages with tabs and widgets |
+
+Full reference: [Concepts](/developers/extend/apps/getting-started/concepts).
+
+## Build with AI agent skills
+
+Official Twenty [Agent Skills](https://skills.sh/) teach coding agents the full app workflow: scaffolding, entity development, sync and deploy operations, and marketplace publishing. They install into Claude Code, Codex, Cursor, Pi, and any other harness supported by the `skills` CLI, and work against any Twenty instance, including self-hosted custom domains and localhost.
+
+```bash filename="Terminal"
+# List the available skills
+npx skills add https://github.com/twentyhq/twenty/tree/agent-skills --list
+
+# Install the scaffolding and development skills
+npx skills add https://github.com/twentyhq/twenty/tree/agent-skills --skill create-app
+npx skills add https://github.com/twentyhq/twenty/tree/agent-skills --skill develop-app
+```
+
+Each skill installs with its own reference docs. The `agent-skills` branch becomes available after the first successful publish from `main`; before that, follow the [local build instructions](https://github.com/twentyhq/twenty/tree/main/packages/twenty-agent-skills#local-development).
+
+## Next steps
+
+<CardGroup cols={2}>
+  <Card title="Config" icon="screwdriver-wrench" href="/developers/extend/apps/config/overview">
+    Application identity, default role, install and uninstall hooks, public assets.
+  </Card>
+  <Card title="Data" icon="database" href="/developers/extend/apps/data/overview">
+    Objects, fields, and bidirectional relations.
+  </Card>
+  <Card title="Logic" icon="bolt" href="/developers/extend/apps/logic/overview">
+    Logic functions, skills, agents, and OAuth connections.
+  </Card>
+  <Card title="Layout" icon="table-columns" href="/developers/extend/apps/layout/overview">
+    Views, navigation, page layouts, front components.
+  </Card>
+  <Card title="Operations" icon="rocket" href="/developers/extend/apps/operations/overview">
+    CLI, testing, remotes, CI, and publishing your app.
+  </Card>
+</CardGroup>

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

@@ -0,0 +1,64 @@
+---
+title: Scaffolding
+description: Generate entity files interactively with yarn twenty dev:add — objects, fields, views, logic functions, and more.
+icon: "wand-magic-sparkles"
+---
+
+Instead of creating entity files by hand, use the interactive scaffolder:
+
+```bash filename="Terminal"
+yarn twenty dev:add
+```
+
+It prompts you to pick an entity type and walks you through the required fields, then writes a ready-to-use file with a stable `universalIdentifier` and the correct `defineEntity()` call.
+
+You can also pass the entity type directly to skip the first prompt:
+
+```bash filename="Terminal"
+yarn twenty dev:add object
+yarn twenty dev:add logicFunction
+yarn twenty dev:add frontComponent
+```
+
+## Available entity types
+
+| Entity type | Command | Generated file |
+|-------------|---------|----------------|
+| Object | `yarn twenty dev:add object` | `src/objects/<name>.ts` |
+| Field | `yarn twenty dev:add field` | `src/fields/<name>.ts` |
+| Logic function | `yarn twenty dev:add logicFunction` | `src/logic-functions/<name>.ts` |
+| Front component | `yarn twenty dev:add frontComponent` | `src/front-components/<name>.tsx` |
+| Role | `yarn twenty dev:add role` | `src/roles/<name>.ts` |
+| Skill | `yarn twenty dev:add skill` | `src/skills/<name>.ts` |
+| Agent | `yarn twenty dev:add agent` | `src/agents/<name>.ts` |
+| View | `yarn twenty dev:add view` | `src/views/<name>.ts` |
+| Navigation menu item | `yarn twenty dev:add navigationMenuItem` | `src/navigation-menu-items/<name>.ts` |
+| Page layout | `yarn twenty dev:add pageLayout` | `src/page-layouts/<name>.ts` |
+| Page layout tab | `yarn twenty dev:add pageLayoutTab` | `src/page-layout-tabs/<name>.ts` |
+| Page layout widget | `yarn twenty dev:add pageLayoutWidget` | `src/page-layout-widgets/<name>.ts` |
+| Command menu item | `yarn twenty dev:add commandMenuItem` | `src/command-menu-items/<name>.ts` |
+| View field | `yarn twenty dev:add viewField` | `src/view-fields/<name>.ts` |
+| Connection provider | `yarn twenty dev:add connectionProvider` | `src/connection-providers/<name>.ts` |
+| Timeline activity type | `yarn twenty dev:add timelineActivityType` | `src/timeline-activity-types/<name>.ts` |
+
+## What the scaffolder generates
+
+Each entity type has its own template. For example, `yarn twenty dev:add object` asks for:
+
+1. **Name (singular)** — e.g., `invoice`
+2. **Name (plural)** — e.g., `invoices`
+3. **Label (singular)** — auto-populated from the name (e.g., `Invoice`)
+4. **Label (plural)** — auto-populated (e.g., `Invoices`)
+5. **Create a view and navigation item?** — if you answer yes, the scaffolder also generates a matching view and sidebar link for the new object.
+
+Other entity types have simpler prompts — most only ask for a name.
+
+The `field` entity type is more detailed: it asks for the field name, label, type (from a list of all available field types like `TEXT`, `NUMBER`, `SELECT`, `RELATION`, etc.), and the target object's `universalIdentifier`.
+
+## Custom output path
+
+Use the `--path` flag to place the generated file in a custom location:
+
+```bash filename="Terminal"
+yarn twenty dev:add logicFunction --path src/custom-folder
+```

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

@@ -0,0 +1,15 @@
+---
+title: Troubleshooting
+description: Common first-run issues — Docker, Node version, Yarn, dependencies.
+icon: "wrench"
+---
+
+- **Docker errors** — Make sure Docker Desktop (or the daemon) is running before `yarn twenty docker:start`. The error message will show the right start command for your OS.
+- **Wrong Node version** — Need 24.5+ (`engines.node: ^24.5.0`). Check with `node -v`.
+- **Yarn 4 missing** — Run `corepack enable`.
+- **Dependencies broken** — `rm -rf node_modules && yarn install`.
+- **Empty `yarn.lock`** — The build fails with "yarn.lock is empty" when the lockfile exists but has no content; run `yarn install` to regenerate it.
+- **`twenty-sdk` errors after upgrading to v2.8.0** — It moved from `dependencies` to `devDependencies` in v2.8.0. See [Project Structure → Dependencies](/developers/extend/apps/getting-started/project-structure#dependencies).
+- **`twenty dev:build` warns about `twenty-client-sdk` under `dependencies`** — It is provided at runtime by Twenty, so it should be moved to `devDependencies` alongside `twenty-sdk`. See [Project Structure → Dependencies](/developers/extend/apps/getting-started/project-structure#dependencies).
+
+Stuck? Ask on the [Twenty Discord](https://discord.com/channels/1130383047699738754/1130386664812982322).