The open alternative to Salesforce, designed for AI.
TypeScript crmcrm-systemcustomergood-first-issuegraphqlhacktoberfestjavascriptmarketingmonoreponestjsopen-sourcepostgresqlreactreactjssalestypescriptweb
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.mdindex 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.mdindex 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.tsindex 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.tsindex 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.tsindex 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.mdindex 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-speci2. **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.mdindex 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.mdindex 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 PermissionsRoles 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.mdindex 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:buildThen 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.jsindex 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.mdindex 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 Changesdiff --git a/packages/twenty-agent-skills/skills/publish-app/SKILL.md b/packages/twenty-agent-skills/skills/publish-app/SKILL.mdindex 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.tsindex 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.mdxindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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;