Skip to content

The open alternative to Salesforce, designed for AI.

Ground the scaffolded AGENTS.md in what the build enforces and fix dev:add output (#27371)

Marie693f63d7fa7e
diff --git a/packages/create-twenty-app/src/constants/template/AGENTS.md b/packages/create-twenty-app/src/constants/template/AGENTS.md
index 7629e26d549..94bf1d31580 100644
--- a/packages/create-twenty-app/src/constants/template/AGENTS.md
+++ b/packages/create-twenty-app/src/constants/template/AGENTS.md
@@ -1,70 +1,135 @@
-## Base documentation
-
-- Getting started:
- - https://docs.twenty.com/developers/extend/apps/getting-started/quick-start.md
- - https://docs.twenty.com/developers/extend/apps/getting-started/concepts.md
- - https://docs.twenty.com/developers/extend/apps/getting-started/project-structure.md
- - https://docs.twenty.com/developers/extend/apps/getting-started/local-server.md
- - https://docs.twenty.com/developers/extend/apps/getting-started/scaffolding.md
- - https://docs.twenty.com/developers/extend/apps/getting-started/troubleshooting.md
-- Config:
- - https://docs.twenty.com/developers/extend/apps/config/overview.md
- - https://docs.twenty.com/developers/extend/apps/config/application.md
- - https://docs.twenty.com/developers/extend/apps/config/roles.md
- - https://docs.twenty.com/developers/extend/apps/config/install-hooks.md
- - https://docs.twenty.com/developers/extend/apps/config/public-assets.md
-- Data:
- - https://docs.twenty.com/developers/extend/apps/data/overview.md
- - https://docs.twenty.com/developers/extend/apps/data/objects.md
- - https://docs.twenty.com/developers/extend/apps/data/extending-objects.md
- - https://docs.twenty.com/developers/extend/apps/data/relations.md
-- Logic:
- - https://docs.twenty.com/developers/extend/apps/logic/overview.md
- - https://docs.twenty.com/developers/extend/apps/logic/logic-functions.md
- - https://docs.twenty.com/developers/extend/apps/logic/skills-and-agents.md
- - https://docs.twenty.com/developers/extend/apps/logic/connections.md
-- Layout:
- - https://docs.twenty.com/developers/extend/apps/layout/overview.md
- - https://docs.twenty.com/developers/extend/apps/layout/views.md
- - https://docs.twenty.com/developers/extend/apps/layout/navigation-menu-items.md
- - https://docs.twenty.com/developers/extend/apps/layout/page-layouts.md
- - https://docs.twenty.com/developers/extend/apps/layout/front-components.md
- - https://docs.twenty.com/developers/extend/apps/layout/command-menu-items.md
-- Operations:
- - https://docs.twenty.com/developers/extend/apps/operations/overview.md
- - https://docs.twenty.com/developers/extend/apps/operations/cli.md
- - https://docs.twenty.com/developers/extend/apps/operations/testing.md
- - https://docs.twenty.com/developers/extend/apps/operations/publishing.md
-- Rich app example: https://github.com/twentyhq/twenty/tree/main/packages/twenty-apps/examples/postcard
-
-## UUID requirement
-
-- All generated UUIDs must be valid UUID v4.
-
-## Common Pitfalls
-
-- 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.
-
-## Best practice
-
-It's highly recommended to create new app entities using `yarn twenty dev:add`. These are the options:
-
-| 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` |
-| 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` |
-
-This helps automatically generate required IDs etc.
+# Working on this Twenty app
+
+This file lists the rules the Twenty build and sync enforce, so an agent gets them right the first time. Install the official agent skills for step-by-step workflows that go beyond it:
+
+```bash
+npx skills add https://github.com/twentyhq/twenty/tree/agent-skills --skill '*'
+```
+
+Skills: `create-app`, `develop-app`, `manage-app`, `publish-app`, `use-twenty-mcp`. When they are installed, follow them.
+
+## Documentation
+
+Every page below is served as Markdown when you append `.md` to its URL. The full developer index is at https://docs.twenty.com/_llms/en/developers.md.
+
+- Getting started: https://docs.twenty.com/developers/extend/apps/getting-started/ `quick-start`, `concepts`, `project-structure`, `local-server`, `scaffolding`, `troubleshooting`
+- Config: https://docs.twenty.com/developers/extend/apps/config/ `overview`, `application`, `roles`, `install-hooks`, `public-assets`
+- Data: https://docs.twenty.com/developers/extend/apps/data/ `overview`, `objects`, `extending-objects`, `relations`, `system-fields`, `timeline-activity-types`
+- Logic: https://docs.twenty.com/developers/extend/apps/logic/ `overview`, `logic-functions`, `skills-and-agents`, `connections`, `background-jobs`, `key-value-store`, `messaging-channels`, `credits`
+- Layout: https://docs.twenty.com/developers/extend/apps/layout/ `overview`, `views`, `navigation-menu-items`, `page-layouts`, `front-components`, `command-menu-items`
+- Operations: https://docs.twenty.com/developers/extend/apps/operations/ `overview`, `cli`, `sync-and-recovery`, `testing`, `translations`, `publishing`
+- End-to-end tutorial: https://docs.twenty.com/developers/extend/apps/tutorials/document-generator/overview.md
+- Example apps: https://github.com/twentyhq/twenty/tree/main/packages/twenty-apps/examples (`postcard`, `document-generator`, `media-notes`, `hello-world`). The test fixture https://github.com/twentyhq/twenty/tree/main/packages/twenty-apps/fixtures/rich-app exercises every entity type, including cron and database-event triggers, indexes, view fields and timeline activity types.
+
+## Commands
+
+| Task | Command |
+| ----------------------------------- | -------------------------------------------------------- |
+| Sync once to the active remote | `yarn twenty apply` (`--no-delete`, `--force`) |
+| Preview what a sync would change | `yarn twenty plan` (writes nothing) |
+| Typecheck against the generated SDK | `yarn twenty dev:typecheck` |
+| Lint | `yarn lint` |
+| Unit tests | `yarn test:unit` |
+| Integration tests (needs a server) | `yarn test` |
+| Run a logic function by hand | `yarn twenty dev:function:exec -n <name> -p '{"k":"v"}'` |
+| Stream logic function logs | `yarn twenty dev:function:logs` |
+| Remove the app from the workspace | `yarn twenty app:uninstall --yes` |
+| Scaffold an entity (interactive) | `yarn twenty dev:add <entityType>` (`--path <dir>`) |
+
+- Sync with `yarn twenty apply`. Do not run `yarn twenty dev` (watch mode) from an agent: it never exits and its output is ambiguous in a sandbox.
+- A sync deletes every entity your app owns that the source no longer declares. Without a TTY, a plan that destroys objects or fields stops the sync; review `yarn twenty plan`, then re-run with `--force`, or use `--no-delete` while the source is intentionally partial.
+- Run typecheck and lint once after a batch of edits, not after every file.
+- `apply` typechecks before it syncs and regenerates `twenty-client-sdk` in `node_modules`. Code that queries a brand-new object with `CoreApiClient` fails typecheck on the first apply: sync the data model first, then write the code that uses it.
+- One sync at a time per workspace. Never run several `apply`, `dev` or `app:install` in parallel.
+- Local iteration never needs a `package.json` version bump. The strictly-increasing version rule applies to `app:publish` and `app:install` only.
+- Build and sync errors name the metadata type and `universalIdentifier` of the failing entity. Search the source for that identifier instead of guessing.
+
+## Scaffolding entities
+
+Generate entities with a CLI rather than writing them by hand: it produces the file, valid identifiers and the right imports. Take the first option that works:
+
+1. **The standalone `twenty` CLI, when `command -v twenty` finds it.** Run it directly, not through `yarn`. It works with or without a terminal: with `--no-input` it never prompts and exits with code 2 when a required value is missing. It covers objects, fields, logic functions and front components. For an object, pass the three `--create-*` flags so it also generates the table view, navigation menu item and record page layout that make the object visible in the UI:
+
+ ```bash
+ twenty app add object --name invoice --name-plural invoices --create-view --create-navigation-menu-item --create-page-layout --no-input
+ twenty app add field --name amount --type NUMBER --object <object-uuid> --no-input
+ twenty app add logic-function --name send-invoice --no-input
+ twenty app add front-component --name invoice-panel --no-input
+ ```
+
+2. **`yarn twenty dev:add <entityType>`, in an interactive terminal only.** It covers every entity type, but it prompts for each value: in an agent's shell it fails at once with `User force closed the prompt`.
+3. **Neither runs, and the user is available**: ask them to run the exact `yarn twenty dev:add <entityType>` command in their own terminal. For an object, prefer this over writing four files by hand.
+4. **Otherwise, write the file by hand.** Follow the example on the matching docs page (append `.md` to its URL), or an existing file of the same kind in the app, check it against the types exported by `twenty-sdk/define`, and generate every identifier with `crypto.randomUUID()` instead of inventing one.
+
+The table below lists what `dev:add` can generate.
+
+| 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` |
+| View field | `yarn twenty dev:add viewField` | `src/view-fields/<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` |
+| Settings menu item | `yarn twenty dev:add settingsMenuItem` | `src/settings-menu-items/<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` |
+
+`dev:add object` also offers to generate the table view, the navigation menu item, the record page layout and its fields view, which is what makes the object usable. A field added to that object later is not shown on the record page until it is listed in `src/views/<name>-record-page-fields.ts`. Generated files use `fill-later` and `replace-with-existing-...` placeholders for identifiers the scaffolder cannot know; the build does not catch them, so replace every placeholder before syncing.
+
+## Rules the build and sync enforce
+
+### Entity files
+
+- An entity is any `.ts` or `.tsx` file in the project whose top-level statement is `export default defineX(...)` as a direct call. Assigning the call to a variable first, calling it through a namespace, or adding `satisfies` makes the build skip the file silently, and a skipped entity is deleted on the next sync. Folder placement is a convention, not a rule.
+- Every entity file runs in Node at build time, front components included. No browser globals at module top level.
+- Exactly one `defineApplication()` per app, and exactly one default role: either a `defineApplicationRole()` (what the scaffold ships) or a `defineRole()` referenced by `defaultRoleUniversalIdentifier` in `defineApplication()`. Never add a second one to an app that already has either. At most one pre-install hook, post-install hook, uninstall hook and health check. The scaffolded `health-check.ts` is that one health check; edit it, never add a second.
+- Object and field names match `^[a-z][a-zA-Z0-9]*$`, singular and plural differ, and neither is a reserved keyword (`user`, `workspace`, `role`, `event`, `type`, `field`, `link`, `address`, `search`, `index`, `plan`, `object`, `relation`, `currency`, `job`, ...). These fail only at sync time.
+
+### Identifiers
+
+- `universalIdentifier` must be a UUID of version 4 or higher and unique across the whole manifest, nested items included (view fields, tabs, widgets, select options, triggers, application variables).
+- Never change an identifier after the first sync: the server sees a delete plus a create, and the data goes with the delete.
+- Cross-references are always `universalIdentifier` strings, never imports of the entity. Export the identifier as a named constant and import that constant; this also avoids circular imports between the two sides of a relation. Standard objects and page layouts are in `STANDARD_OBJECT_UNIVERSAL_IDENTIFIERS` and `STANDARD_PAGE_LAYOUT_UNIVERSAL_IDENTIFIERS` from `twenty-sdk/define`.
+- Two references use names instead: a database event trigger's `eventName` uses the object's `nameSingular` (`company.created`), and a connection provider's `clientIdVariable` / `clientSecretVariable` use server variable keys.
+
+### Data model
+
+- Do not declare `id`, `createdAt`, `updatedAt`, `createdBy`, `updatedBy` or `deletedAt`: Twenty adds them. `name` is the one default field you may declare, and `dev:add object` does so to use it as the label identifier; keep that declaration and its identifier, since removing it injects a different `name` field and breaks the views that reference the old one.
+- A relation is two `FieldType.RELATION` fields that point at each other through `relationTargetFieldMetadataUniversalIdentifier`. The `MANY_TO_ONE` side must set `universalSettings.joinColumnName`. Relating to a standard object still requires declaring the reverse field on it with `defineField({ objectUniversalIdentifier })`.
+- Literal string defaults are quoted inside the string: `defaultValue: "'DRAFT'"`. Unquoted strings are reserved for `'uuid'` and `'now'`. `SELECT` option values are `UPPER_SNAKE_CASE`, and option `color` comes from the Twenty tag colors.
+- Turning an existing field into `isNullable: false` requires a non-null `defaultValue`, or the sync fails.
+
+### Layout
+
+- A usable object is object + table view + navigation menu item (`type: OBJECT`) + record page layout. A view or an object without a navigation menu item is not reachable from the sidebar. Color is set on the navigation menu item, not on `defineObject`.
+- Set `layoutMode` on every page layout tab: `VERTICAL_LIST` for record and standalone pages, `GRID` for dashboards. `CANVAS` tabs are deprecated. In a `VERTICAL_LIST` tab, order comes from the `widgets` array and `position` is deprecated; `GRID` widgets and standalone `definePageLayoutWidget()` still need an explicit `position`, or every card lands on row 0, column 0.
+- A widget must fit its width-driven container without scrolling, unless it is the single `heightBehavior: 'TAB_VIEWPORT'` widget of its tab, placed last.
+- Widgets reference app components through `frontComponentUniversalIdentifier`, not `frontComponentId`.
+
+### Front components
+
+- The file is `.tsx` and ends with `export default defineFrontComponent({ ... })` in exactly that shape; the build rewrites it.
+- Components run in a Web Worker with a sandboxed, partial `window` and `document`: DOM queries, measurements and `matchMedia` work, but `ResizeObserver`, `canvas`, `scrollIntoView` and portals into `document.body` do not, and most unsupported calls fail silently. Base layout on width, never on height. Import UI from `twenty-ui` subpaths and never `IconsProvider` or `useIcons`.
+- Read workspace data with `CoreApiClient` from `twenty-client-sdk/core`. Call third-party APIs from a logic function, not from the component. Secret application variables never reach a front component.
+- `useRecordId()` is deprecated; use `useSelectedRecordIds()` from `twenty-sdk/front-component`.
+
+### Logic functions
+
+- The handler is `(payload, context)`. The payload shape follows the trigger: `RoutePayload` for HTTP routes, `DatabaseEventPayload` (or the batch variant, up to 200 events) for database events, `{}` for cron, `{ previousVersion?, newVersion }` for install hooks.
+- HTTP routes are served under `/s/<path>`; request header names are lowercase. `timeoutSeconds` is between 1 and 900, default 300.
+- `new CoreApiClient()` authenticates from the injected environment and acts as the person who triggered the run, narrowed to the app's role; `runAs: 'application'` uses the app's own role. Never declare `TWENTY_API_URL`, `TWENTY_APP_ACCESS_TOKEN`, `TWENTY_APP_APPLICATION_ACCESS_TOKEN`, `TWENTY_API_KEY`, `TWENTY_FUNCTIONS_URL` or `APPLICATION_ID` as variables: sync rejects them.
+- Import runtime helpers from `twenty-sdk/logic-function` and `twenty-sdk/utils` (`isDefined`, `getPublicAssetUrl`). The `isDefined` exported by `twenty-sdk/define` is a conditional-availability variable and fails the build anywhere outside `conditionalAvailabilityExpression`.
+- Give tool and workflow-action functions a specific `description`: agents choose tools by it.
+
+### Dependencies
+
+- `twenty-sdk`, `twenty-client-sdk` and `twenty-ui` stay in `devDependencies`, all at the same version. `dependencies` is only for packages logic functions import at runtime; the runtime layer is capped at 250 MB unpacked.
diff --git a/packages/create-twenty-app/src/constants/template/README.md b/packages/create-twenty-app/src/constants/template/README.md
index 0b5463eb0f8..53d4dc5f1aa 100644
--- a/packages/create-twenty-app/src/constants/template/README.md
+++ b/packages/create-twenty-app/src/constants/template/README.md
@@ -31,4 +31,5 @@ Notable changes are documented in [CHANGELOG.md](CHANGELOG.md).
- [Twenty Apps documentation](https://docs.twenty.com/developers/extend/apps/getting-started/quick-start)
- [twenty-sdk CLI reference](https://www.npmjs.com/package/twenty-sdk)
+- [Agent skills for coding assistants](https://github.com/twentyhq/twenty/tree/agent-skills), and the rules in [AGENTS.md](AGENTS.md)
- [Discord](https://discord.gg/cx5n4Jzs57)
diff --git a/packages/create-twenty-app/src/constants/template/src/application-config.ts b/packages/create-twenty-app/src/constants/template/src/application-config.ts
index 088f9d1ea94..37a92560eff 100644
--- a/packages/create-twenty-app/src/constants/template/src/application-config.ts
+++ b/packages/create-twenty-app/src/constants/template/src/application-config.ts
@@ -10,4 +10,5 @@ export default defineApplication({
universalIdentifier: APPLICATION_UNIVERSAL_IDENTIFIER,
displayName: APP_DISPLAY_NAME,
description: APP_DESCRIPTION,
+ logo: 'public/logo.svg',
});
diff --git a/packages/create-twenty-app/src/constants/template/src/page-layouts/main-page.page-layout.ts b/packages/create-twenty-app/src/constants/template/src/page-layouts/main-page.page-layout.ts
index 6154377a08f..683e1a4d0a8 100644
--- a/packages/create-twenty-app/src/constants/template/src/page-layouts/main-page.page-layout.ts
+++ b/packages/create-twenty-app/src/constants/template/src/page-layouts/main-page.page-layout.ts
@@ -28,12 +28,8 @@ export default definePageLayout({
universalIdentifier: MAIN_PAGE_WIDGET_UNIVERSAL_IDENTIFIER,
title: ' ',
type: 'FRONT_COMPONENT',
- position: {
- layoutMode: PageLayoutTabLayoutMode.VERTICAL_LIST,
- index: 0,
- heightBehavior:
- PageLayoutWidgetVerticalListHeightBehavior.TAB_VIEWPORT,
- },
+ heightBehavior:
+ PageLayoutWidgetVerticalListHeightBehavior.TAB_VIEWPORT,
configuration: {
configurationType: 'FRONT_COMPONENT',
frontComponentUniversalIdentifier:
diff --git a/packages/create-twenty-app/src/create-app.command.ts b/packages/create-twenty-app/src/create-app.command.ts
index 1478982be59..9fe120d8500 100644
--- a/packages/create-twenty-app/src/create-app.command.ts
+++ b/packages/create-twenty-app/src/create-app.command.ts
@@ -155,7 +155,7 @@ export class CreateAppCommand {
syncSucceeded = await this.syncApplication(appDirectory);
if (!syncSucceeded) {
- this.logDetail('Sync failed. Run `yarn twenty dev --once` manually.');
+ this.logDetail('Sync failed. Run `yarn twenty apply` manually.');
return;
}
} else {
@@ -486,9 +486,9 @@ export class CreateAppCommand {
}
private async syncApplication(appDirectory: string): Promise<boolean> {
- this.logDetail('Running `yarn twenty dev --once`...');
+ this.logDetail('Running `yarn twenty apply`...');
return new Promise((resolve) => {
- const child = spawn('yarn', ['twenty', 'dev', '--once'], {
+ const child = spawn('yarn', ['twenty', 'apply'], {
cwd: appDirectory,
stdio: ['inherit', 'pipe', 'pipe'],
});
diff --git a/packages/twenty-agent-skills/references/concepts/operating-rules.md b/packages/twenty-agent-skills/references/concepts/operating-rules.md
index 2f930c98a05..0238df0c37f 100644
--- a/packages/twenty-agent-skills/references/concepts/operating-rules.md
+++ b/packages/twenty-agent-skills/references/concepts/operating-rules.md
@@ -8,7 +8,19 @@ This file is the single source of truth for the cross-skill rules. Harness-speci
2. **Do not run broad validation unless it is requested.** After scaffolding (`create-twenty-app`) or after the CLI generates entities, prefer the bounded command that matches the task: `yarn twenty apply` for app sync, the package's unit-test script for unit tests, and `TWENTY_API_URL=http://localhost:2021 yarn test` for the full integration suite. Integration tests must target the isolated test instance on port `2021`, not the dev instance on port `2020`, unless the user explicitly asks otherwise.
-3. **Use `yarn twenty dev:add` for new entities.** It generates correct file structure, UUIDs, SDK imports, and boilerplate. Do not hand-craft entity files unless modifying existing ones or the CLI does not support that entity type.
+3. **Generate new entities with a CLI.** A CLI produces the file structure, identifiers, SDK imports and boilerplate. Hand-craft an entity file only to modify an existing one, or when no option below can produce it. Take the first option that works:
+ 1. **The standalone `twenty` CLI, when `command -v twenty` finds it.** Run it directly, not through `yarn`. It works with or without a terminal: with `--no-input` it never prompts and exits with code 2 when a required value is missing. It covers objects, fields, logic functions and front components. For an object, pass the three `--create-*` flags so it also generates the table view, navigation menu item and record page layout that make the object visible in the UI:
+
+ ```bash
+ twenty app add object --name invoice --name-plural invoices --create-view --create-navigation-menu-item --create-page-layout --no-input
+ twenty app add field --name amount --type NUMBER --object <object-uuid> --no-input
+ twenty app add logic-function --name send-invoice --no-input
+ twenty app add front-component --name invoice-panel --no-input
+ ```
+
+ 2. **`yarn twenty dev:add <entityType>`, in an interactive terminal only.** It covers every entity type, but it prompts for each value: in an agent's shell it fails at once with `User force closed the prompt`.
+ 3. **Neither runs, and the user is available**: ask them to run the exact `yarn twenty dev:add <entityType>` command in their own terminal. For an object, prefer this over writing four files by hand.
+ 4. **Otherwise, write the file by hand.** Follow the example on the matching docs page (append `.md` to its URL), or an existing file of the same kind in the app, check it against the types exported by `twenty-sdk/define`, and generate every identifier with `crypto.randomUUID()` instead of inventing one.
4. **Confirm destructive operations.** Deploys to production, uninstalls, production remote changes, and production syncs require explicit user confirmation before execution. Treat `--remote production` as user-visible.
diff --git a/packages/twenty-agent-skills/references/develop-app/app-structure.md b/packages/twenty-agent-skills/references/develop-app/app-structure.md
index e608aa135d2..5572e4f0e71 100644
--- a/packages/twenty-agent-skills/references/develop-app/app-structure.md
+++ b/packages/twenty-agent-skills/references/develop-app/app-structure.md
@@ -39,7 +39,7 @@ Prefer the app CLI for new entities when interactive prompts are acceptable:
yarn twenty dev:add
```
-For non-interactive agent work, direct file creation is often better. Use generated CLI templates, local SDK typings, or existing app files as the source of truth for imports and config shape.
+Check first for the standalone `twenty` CLI (`command -v twenty`): `twenty app add ... --no-input` works without a terminal, and for objects the `--create-view --create-navigation-menu-item --create-page-layout` flags add the UI definitions. Rule 3 of the operating rules gives the full order of options.
Use official Twenty docs or local SDK source when exact imports, entity fields, or configuration shapes matter.
diff --git a/packages/twenty-agent-skills/references/develop-app/data-model.md b/packages/twenty-agent-skills/references/develop-app/data-model.md
index b972528f3fb..0fdbfbefb8d 100644
--- a/packages/twenty-agent-skills/references/develop-app/data-model.md
+++ b/packages/twenty-agent-skills/references/develop-app/data-model.md
@@ -93,6 +93,24 @@ Select and multi-select option `value` strings must be uppercase snake case:
For select fields, default values must be quoted string expressions like `"'PLANNED'"`, not plain strings like `'planned'`.
+### Relations
+
+A relation is two `FieldType.RELATION` fields that point at each other through `relationTargetFieldMetadataUniversalIdentifier`, one on each object. The `MANY_TO_ONE` side must set `universalSettings.joinColumnName` (the convention is `<fieldName>Id`); the build rejects a `MANY_TO_ONE` relation without one. `yarn twenty dev:add field` emits it, but the reverse `ONE_TO_MANY` field still has to be written by hand, including on a standard object such as Company:
+
+```ts
+// src/fields/company-on-contract.ts
+universalSettings: {
+ relationType: RelationType.MANY_TO_ONE,
+ onDelete: OnDeleteAction.SET_NULL,
+ joinColumnName: 'companyId',
+},
+
+// src/fields/contracts-on-company.ts
+universalSettings: { relationType: RelationType.ONE_TO_MANY },
+```
+
+Export each field's identifier as a named constant and import it from the other file, so the two sides reference each other without a circular import.
+
## Roles And Permissions
Roles should match operational responsibility, not implementation convenience.
diff --git a/packages/twenty-agent-skills/references/publish-app/prepare-for-app-store.md b/packages/twenty-agent-skills/references/publish-app/prepare-for-app-store.md
index b2ebe46b9cd..9ee05051bbb 100644
--- a/packages/twenty-agent-skills/references/publish-app/prepare-for-app-store.md
+++ b/packages/twenty-agent-skills/references/publish-app/prepare-for-app-store.md
@@ -21,15 +21,15 @@ Twenty marketplace metadata comes from `defineApplication()`:
- `description`
- `author`
- `category`
-- `logoUrl`
-- `screenshots`
+- `logo`
+- `galleryImages`
- `aboutDescription`
- `websiteUrl`
- `termsUrl`
- `emailSupport`
- `issueReportUrl`
-`logoUrl` and `screenshots` must reference files from the app `public/` folder, for example `public/logo.png` and `public/screenshot-1.png`. If `aboutDescription` is omitted, the marketplace uses the package `README.md` from npm as the About tab content.
+`logo` and `galleryImages` must reference files from the app `public/` folder, for example `public/logo.png` and `public/screenshot-1.png`. `logoUrl` and `screenshots` are deprecated aliases, and external `http(s)` URLs are dropped at build time. The default role is declared with `defineApplicationRole()` in its own file, not in `defineApplication()`. If `aboutDescription` is omitted, the marketplace uses the package `README.md` from npm as the About tab content.
Files in `public/` are public, synced in dev mode, included in builds, and served without authentication. Never put secrets, private data, customer records, real tokens, or unreleased confidential material in public assets.
@@ -172,15 +172,11 @@ export default defineApplication({
universalIdentifier: APPLICATION_UNIVERSAL_IDENTIFIER,
displayName: APP_DISPLAY_NAME,
description: APP_DESCRIPTION,
- defaultRoleUniversalIdentifier: DEFAULT_ROLE_UNIVERSAL_IDENTIFIER,
requestedCapabilities: ['microphone'],
author: 'Your Company',
category: 'Productivity',
- logoUrl: 'public/logo.png',
- screenshots: [
- 'public/screenshot-1.png',
- 'public/screenshot-2.png',
- ],
+ logo: 'public/logo.png',
+ galleryImages: ['public/screenshot-1.png', 'public/screenshot-2.png'],
websiteUrl: 'https://example.com',
termsUrl: 'https://example.com/terms',
emailSupport: '[email protected]',
@@ -205,7 +201,7 @@ yarn twenty dev:build
Then check:
-- Every `logoUrl` and `screenshots` path exists in `public/`.
+- Every `logo` and `galleryImages` path exists in `public/`.
- `README.md` setup steps match actual variables, connections, and commands.
- `package.json` has `keywords: ["twenty-app"]` when the app is intended for npm marketplace publishing.
- `defineApplication()` metadata does not reference placeholder URLs, support addresses, screenshots, or terms.
diff --git a/packages/twenty-agent-skills/scripts/validators/cross-doc-contracts.js b/packages/twenty-agent-skills/scripts/validators/cross-doc-contracts.js
index de0a779ec38..df8fdc40ccd 100644
--- a/packages/twenty-agent-skills/scripts/validators/cross-doc-contracts.js
+++ b/packages/twenty-agent-skills/scripts/validators/cross-doc-contracts.js
@@ -386,7 +386,7 @@ const assertTestingGuidance = (fail) => {
const OPERATING_RULE_HEADLINES = [
'**Bounded sync only.**',
'**Do not run broad validation unless it is requested.**',
- '**Use `yarn twenty dev:add` for new entities.**',
+ '**Generate new entities with a CLI.**',
'**Confirm destructive operations.**',
'**Any Twenty instance is a valid target.**',
'**Workspace URLs and credentials stay user-local.**',
diff --git a/packages/twenty-agent-skills/skills/develop-app/SKILL.md b/packages/twenty-agent-skills/skills/develop-app/SKILL.md
index ddafc075f49..42cffe142d7 100644
--- a/packages/twenty-agent-skills/skills/develop-app/SKILL.md
+++ b/packages/twenty-agent-skills/skills/develop-app/SKILL.md
@@ -69,15 +69,13 @@ When a front component triggers a logic function for selected records, always pr
## Adding New Entities
-Use the app CLI to add new entities. It generates the correct file structure, UUIDs, SDK imports, and boilerplate automatically:
+Use a CLI to add new entities. It generates the correct file structure, UUIDs, SDK imports, and boilerplate. Check first for the standalone CLI, which works without a terminal:
```bash
-yarn twenty dev:add
+command -v twenty && twenty app add object --name invoice --name-plural invoices --create-view --create-navigation-menu-item --create-page-layout --no-input
```
-This is the default and preferred way to create objects, fields, views, logic functions, front components, and other entities. Do not manually create entity files, explore SDK typings in `node_modules`, or generate UUIDs by hand when the CLI can do it.
-
-Only create entity files manually when modifying existing entities or when the CLI does not support the specific entity type.
+Otherwise run `yarn twenty dev:add` in an interactive terminal. The full order of options, including what to do when neither CLI can run, is rule 3 of the operating rules linked above.
## After Entity Changes
diff --git a/packages/twenty-agent-skills/skills/publish-app/SKILL.md b/packages/twenty-agent-skills/skills/publish-app/SKILL.md
index 7934afc5f48..49d899977e8 100644
--- a/packages/twenty-agent-skills/skills/publish-app/SKILL.md
+++ b/packages/twenty-agent-skills/skills/publish-app/SKILL.md
@@ -27,8 +27,8 @@ Keep the skill workflow concise:
- Inspect `package.json`, `README.md`, `src/application-config.ts`, and `public/`.
- For npm marketplace publication, ensure `package.json` has a valid bumped `version` and the `twenty-app` keyword.
-- In `defineApplication()`, verify marketplace-facing fields such as `displayName`, `description`, `author`, `category`, `logoUrl`, `screenshots`, `aboutDescription`, `websiteUrl`, `termsUrl`, `emailSupport`, and `issueReportUrl`.
-- Keep `logoUrl` and `screenshots` pointed at files in `public/`. Public assets must not contain secrets, private data, customer records, real tokens, or unreleased confidential material.
+- In `defineApplication()`, verify marketplace-facing fields such as `displayName`, `description`, `author`, `category`, `logo`, `galleryImages`, `aboutDescription`, `websiteUrl`, `termsUrl`, `emailSupport`, and `issueReportUrl`.
+- Keep `logo` and `galleryImages` pointed at files in `public/`. Public assets must not contain secrets, private data, customer records, real tokens, or unreleased confidential material.
- Remember that if `aboutDescription` is omitted, the marketplace uses the package `README.md` from npm for the About content. The About tab renders markdown text only: images and raw HTML are not rendered.
- Validate with `yarn twenty dev:build`; publish with `yarn twenty app:publish` or `yarn twenty app:publish --tag <tag>`.
diff --git a/packages/twenty-cli/src/app/add/entity-field-template.ts b/packages/twenty-cli/src/app/add/entity-field-template.ts
index 3f6872af476..acaee073385 100644
--- a/packages/twenty-cli/src/app/add/entity-field-template.ts
+++ b/packages/twenty-cli/src/app/add/entity-field-template.ts
@@ -4,7 +4,7 @@ import { printTypescriptValue } from '@/app/pull/print-typescript-value';
import {
FieldMetadataType,
type RelationOnDeleteAction,
- type RelationType,
+ RelationType,
} from 'twenty-shared/types';
export const getFieldBaseFile = ({
@@ -40,6 +40,11 @@ export const getFieldBaseFile = ({
const onDeleteSetting = hasOnDelete
? `, onDelete: OnDeleteAction.${data.onDelete}`
: '';
+ // The manifest build rejects a MANY_TO_ONE relation without a join column.
+ const joinColumnNameSetting =
+ data.relationType === RelationType.MANY_TO_ONE
+ ? `, joinColumnName: '${data.name}Id'`
+ : '';
const morphIdLine =
data.type === FieldMetadataType.MORPH_RELATION
? `\n morphId: '${randomUUID()}',`
@@ -55,7 +60,7 @@ export default defineField({
objectUniversalIdentifier: ${printTypescriptValue({ value: data.objectUniversalIdentifier })},
relationTargetObjectMetadataUniversalIdentifier: ${printTypescriptValue({ value: data.relationTargetObjectMetadataUniversalIdentifier })},
relationTargetFieldMetadataUniversalIdentifier: ${printTypescriptValue({ value: data.relationTargetFieldMetadataUniversalIdentifier })},
- universalSettings: { relationType: RelationType.${data.relationType}${onDeleteSetting} },${morphIdLine}${descriptionLine}
+ universalSettings: { relationType: RelationType.${data.relationType}${onDeleteSetting}${joinColumnNameSetting} },${morphIdLine}${descriptionLine}
});
`;
}
diff --git a/packages/twenty-docs/developers/extend/apps/getting-started/scaffolding.mdx b/packages/twenty-docs/developers/extend/apps/getting-started/scaffolding.mdx
index ca2453c9247..db73c8b3145 100644
--- a/packages/twenty-docs/developers/extend/apps/getting-started/scaffolding.mdx
+++ b/packages/twenty-docs/developers/extend/apps/getting-started/scaffolding.mdx
@@ -50,7 +50,7 @@ Each entity type has its own template. For example, `yarn twenty dev:add object`
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.
+5. **Also create a view, navigation menu item, and record page layout for this object?** — if you answer yes, the scaffolder also generates a table view, a sidebar entry, a record page layout and the fields view it displays, which is what makes the new object usable right away.
Other entity types have simpler prompts — most only ask for a name.
diff --git a/packages/twenty-sdk/src/cli/commands/dev/add.ts b/packages/twenty-sdk/src/cli/commands/dev/add.ts
index e3756965c88..2ad20316fc0 100644
--- a/packages/twenty-sdk/src/cli/commands/dev/add.ts
+++ b/packages/twenty-sdk/src/cli/commands/dev/add.ts
@@ -212,6 +212,7 @@ export class EntityAddCommand {
const file = getViewBaseFile({
name,
+ objectUniversalIdentifier: entityData.objectUniversalIdentifier,
applicationUniversalIdentifier,
});
diff --git a/packages/twenty-sdk/src/cli/utilities/entity/__tests__/get-field-base-file.spec.ts b/packages/twenty-sdk/src/cli/utilities/entity/__tests__/get-field-base-file.spec.ts
index 02e27a2b937..0ef4f67b199 100644
--- a/packages/twenty-sdk/src/cli/utilities/entity/__tests__/get-field-base-file.spec.ts
+++ b/packages/twenty-sdk/src/cli/utilities/entity/__tests__/get-field-base-file.spec.ts
@@ -1,4 +1,9 @@
import { getFieldBaseFile } from '@/cli/utilities/entity/entity-field-template';
+import {
+ FieldMetadataType,
+ RelationOnDeleteAction,
+ RelationType,
+} from 'twenty-shared/types';
describe('getFieldBaseFile', () => {
it('should render proper file using defineField', () => {
@@ -189,7 +194,44 @@ describe('getFieldBaseFile', () => {
/morphId: '[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}'/,
);
expect(result).toContain(
- 'universalSettings: { relationType: RelationType.MANY_TO_ONE }',
+ "universalSettings: { relationType: RelationType.MANY_TO_ONE, joinColumnName: 'targetId' }",
);
});
+
+ it('should derive joinColumnName from the field name for a MANY_TO_ONE relation', () => {
+ const result = getFieldBaseFile({
+ data: {
+ name: 'recipient',
+ label: 'Recipient',
+ type: FieldMetadataType.RELATION,
+ objectUniversalIdentifier: 'obj-1',
+ relationTargetObjectMetadataUniversalIdentifier: 'target-obj',
+ relationTargetFieldMetadataUniversalIdentifier: 'target-field',
+ relationType: RelationType.MANY_TO_ONE,
+ onDelete: RelationOnDeleteAction.SET_NULL,
+ },
+ name: 'recipient',
+ });
+
+ expect(result).toContain(
+ "universalSettings: { relationType: RelationType.MANY_TO_ONE, onDelete: OnDeleteAction.SET_NULL, joinColumnName: 'recipientId' }",
+ );
+ });
+
+ it('should not emit joinColumnName for a ONE_TO_MANY relation', () => {
+ const result = getFieldBaseFile({
+ data: {
+ name: 'postCards',
+ label: 'Post cards',
+ type: FieldMetadataType.RELATION,
+ objectUniversalIdentifier: 'obj-1',
+ relationTargetObjectMetadataUniversalIdentifier: 'target-obj',
+ relationTargetFieldMetadataUniversalIdentifier: 'target-field',
+ relationType: RelationType.ONE_TO_MANY,
+ },
+ name: 'postCards',
+ });
+
+ expect(result).not.toContain('joinColumnName');
+ });
});
diff --git a/packages/twenty-sdk/src/cli/utilities/entity/entity-field-template.ts b/packages/twenty-sdk/src/cli/utilities/entity/entity-field-template.ts
index dd4cf8a62c2..3e34e0746a2 100644
--- a/packages/twenty-sdk/src/cli/utilities/entity/entity-field-template.ts
+++ b/packages/twenty-sdk/src/cli/utilities/entity/entity-field-template.ts
@@ -1,7 +1,7 @@
import {
FieldMetadataType,
type RelationOnDeleteAction,
- type RelationType,
+ RelationType,
} from 'twenty-shared/types';
import { v4 } from 'uuid';
@@ -38,6 +38,11 @@ export const getFieldBaseFile = ({
const onDeleteSetting = hasOnDelete
? `, onDelete: OnDeleteAction.${data.onDelete}`
: '';
+ // The manifest build rejects a MANY_TO_ONE relation without a join column.
+ const joinColumnNameSetting =
+ data.relationType === RelationType.MANY_TO_ONE
+ ? `, joinColumnName: '${data.name}Id'`
+ : '';
const morphIdLine =
data.type === FieldMetadataType.MORPH_RELATION
? `\n morphId: '${v4()}',`
@@ -53,7 +58,7 @@ export default defineField({
objectUniversalIdentifier: '${data.objectUniversalIdentifier}',
relationTargetObjectMetadataUniversalIdentifier: '${data.relationTargetObjectMetadataUniversalIdentifier}',
relationTargetFieldMetadataUniversalIdentifier: '${data.relationTargetFieldMetadataUniversalIdentifier}',
- universalSettings: { relationType: RelationType.${data.relationType}${onDeleteSetting} },${morphIdLine}${descriptionLine}
+ universalSettings: { relationType: RelationType.${data.relationType}${onDeleteSetting}${joinColumnNameSetting} },${morphIdLine}${descriptionLine}
});
`;
}
diff --git a/packages/twenty-sdk/src/cli/utilities/error/__tests__/get-sync-error-recovery-hint.spec.ts b/packages/twenty-sdk/src/cli/utilities/error/__tests__/get-sync-error-recovery-hint.spec.ts
index e33d992f152..abc0e3c32e5 100644
--- a/packages/twenty-sdk/src/cli/utilities/error/__tests__/get-sync-error-recovery-hint.spec.ts
+++ b/packages/twenty-sdk/src/cli/utilities/error/__tests__/get-sync-error-recovery-hint.spec.ts
@@ -8,7 +8,7 @@ describe('getSyncErrorRecoveryHint', () => {
'Application "x" is not installed in workspace "y". Install it first.',
);
- expect(hint).toContain('yarn twenty dev --once');
+ expect(hint).toContain('yarn twenty apply');
expect(hint).toContain('register');
});
@@ -17,7 +17,7 @@ describe('getSyncErrorRecoveryHint', () => {
"Migration action 'create' for 'fieldMetadata' (universalIdentifier: 2020) failed",
);
- expect(hint).toContain('yarn twenty dev --once --dry-run');
+ expect(hint).toContain('yarn twenty plan');
expect(hint).toContain('yarn twenty app:uninstall -y');
});
@@ -26,7 +26,7 @@ describe('getSyncErrorRecoveryHint', () => {
'Field with same universal identifier already exists in object',
);
- expect(hint).toContain('yarn twenty dev --once --dry-run');
+ expect(hint).toContain('yarn twenty plan');
});
it('returns undefined for an unrecognized error', () => {
diff --git a/packages/twenty-sdk/src/cli/utilities/error/get-sync-error-recovery-hint.ts b/packages/twenty-sdk/src/cli/utilities/error/get-sync-error-recovery-hint.ts
index 9c595448eb7..a500ae84a06 100644
--- a/packages/twenty-sdk/src/cli/utilities/error/get-sync-error-recovery-hint.ts
+++ b/packages/twenty-sdk/src/cli/utilities/error/get-sync-error-recovery-hint.ts
@@ -4,7 +4,7 @@ export const getSyncErrorRecoveryHint = (
const normalizedMessage = (message ?? '').toLowerCase();
if (normalizedMessage.includes('not installed')) {
- return 'Hint: run `yarn twenty dev --once` to register the app in this workspace, then retry.';
+ return 'Hint: run `yarn twenty apply` to register the app in this workspace, then retry.';
}
if (
@@ -12,7 +12,7 @@ export const getSyncErrorRecoveryHint = (
normalizedMessage.includes('universalidentifier') ||
/migration action .* failed/.test(normalizedMessage)
) {
- return 'Hint: a metadata conflict was detected. Preview the plan with `yarn twenty dev --once --dry-run`; if it persists, run `yarn twenty app:uninstall -y` then sync again.';
+ return 'Hint: a metadata conflict was detected. Preview the plan with `yarn twenty plan`; if it persists, run `yarn twenty app:uninstall -y` then sync again.';
}
return undefined;