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

packages/twenty-agent-skills/references/concepts/how-apps-work.md

@@ -0,0 +1,110 @@
+# How Twenty Apps Work
+
+Use this reference to understand the Twenty application development model before creating, developing, or deploying an app. Other references cover specific workflows; this one explains the architecture behind them.
+
+## What Is A Twenty App
+
+A Twenty app is a standalone npm package that extends a Twenty instance. It is not part of the Twenty server codebase. It lives in its own directory with its own `package.json`, dependencies, and source tree. When installed on a Twenty instance, it adds objects, fields, views, page layouts, front components, logic functions, skills, agents, and more to that workspace.
+
+The app does not run as a separate server. It is built, published, and installed into a running Twenty instance. The instance loads the app's entities into its schema and renders the app's front components inside the workspace UI.
+
+## SDK Packages
+
+A Twenty app depends on two SDK packages:
+
+| Package | Purpose | Used in |
+| --- | --- | --- |
+| `twenty-sdk` | Define app entities and access front component runtime APIs | Entity definitions (`twenty-sdk/define`), front component hooks and host APIs (`twenty-sdk/front-component`) |
+| `twenty-client-sdk` | Access workspace data from front components | Core object queries (`twenty-client-sdk/core`), metadata queries (`twenty-client-sdk/metadata`) |
+
+`twenty-sdk/define` provides the registration functions: `defineApplication`, `defineObject`, `defineField`, `defineView`, `definePageLayout`, `defineFrontComponent`, `defineNavigationMenuItem`, `defineLogicFunction`, `defineRole`, and others. Every app entity is declared through one of these functions.
+
+`twenty-sdk/front-component` provides runtime APIs available inside front components: `navigate`, `enqueueSnackbar`, `openSidePanelPage`, `useSelectedRecordIds`, `getApplicationVariable`, and others.
+
+Twenty UI components (`Button`, `Chip`, `Tag`, `Status`, `Heading`, `Section`, `ThemeProvider`, icons, `themeCssVariables`) live in the `twenty-ui` package. Install `twenty-ui` from npm at the same version as `twenty-sdk` and `twenty-client-sdk` and import from its subpaths (`twenty-ui/primitives/input`, `twenty-ui/primitives/data-display`, `twenty-ui/icon`, `twenty-ui/primitives/typography`, `twenty-ui/components`, `twenty-ui/theme-constants`, and others).
+
+`twenty-client-sdk/core` provides `CoreApiClient` for querying and mutating workspace records (companies, people, custom objects). `twenty-client-sdk/metadata` provides access to workspace metadata (object definitions, field definitions).
+
+## Twenty Instances And Remotes
+
+A Twenty instance is a running Twenty server — either self-hosted or managed cloud. Each instance hosts one or more workspaces. Apps are installed per workspace.
+
+A "remote" is the local CLI's connection to a Twenty instance. It stores the server URL and an API key in `~/.twenty/config.json`. You can configure multiple remotes (e.g. `local`, `staging`, `production`) and switch between them.
+
+The API key authenticates the developer against the target workspace. It determines which workspace the app syncs to, deploys to, and reads data from during development.
+
+## Local Development Environment
+
+An app needs a running Twenty instance to develop against. There are two ways to connect:
+
+1. **Existing instance via OAuth** (default): `create-twenty-app --url <twenty-instance-url>` authenticates via OAuth on the provided Twenty server. The scaffolder opens a browser for the OAuth flow, then stores the credentials as a remote in `~/.twenty/config.json`. This is best when the developer already has a workspace with data to develop against.
+
+2. **Local instance with Docker** (fallback): `create-twenty-app` (no `--url`) starts a disposable local Twenty server on `http://localhost:2020` through Docker. The scaffolder authenticates with the local server's development API key and creates a `local` remote automatically. Use this when the developer has no Twenty instance available and wants to start fresh without affecting a shared workspace.
+
+In both cases, the result is a remote stored in `~/.twenty/config.json` that the CLI uses for all subsequent sync, deploy, and data access commands.
+
+## App Lifecycle
+
+The development loop is:
+
+```
+create → develop → sync → validate → repeat
+```
+
+1. **Create**: `npx create-twenty-app@latest <app-name>` generates the project, installs dependencies, starts a local Twenty server, and runs an initial sync. The scaffolder handles everything in one command — do not run `yarn twenty apply` after scaffolding because the sync already happened.
+
+2. **Develop**: Add or modify entities in `src/`. Objects go in `src/objects/`, front components in `src/front-components/`, logic functions in `src/logic-functions/`, page layouts in `src/page-layouts/`, and so on. Each entity file exports a `define*` call.
+
+3. **Sync**: `yarn twenty apply` builds, deploys, and installs the app on the active remote in one step. The Twenty instance updates its schema, registers new objects and fields, mounts front components, and activates logic functions. This is the primary way to get changes onto a Twenty instance during development. Sync after every meaningful change.
+
+4. **Validate**: `yarn twenty dev:typecheck` checks generated types. `yarn lint` checks local lint rules. Open the workspace in a browser to verify front components render and logic functions execute.
+
+## Sharing An App
+
+Publishing is separate from the development loop. It is used to share an app with other Twenty instances or the public marketplace:
+
+- `yarn twenty app:publish` publishes to npm for the public marketplace.
+- `yarn twenty app:publish --private --remote <name>` publishes privately to a specific Twenty instance's registry.
+
+Each publish requires a strictly higher semver version in `package.json`. See the `publish-app` skill for marketplace metadata and listing guidance.
+
+## Front Component Rendering
+
+Front components do not run as a separate frontend application. The Twenty workspace renders them inside an isolated Remote DOM container. The SDK mounts the component, provides a `ThemeProvider`, and proxies host APIs (navigation, snackbars, side panels) through `twenty-sdk/front-component`.
+
+This means:
+- Front components cannot access `document` or `window` globals directly.
+- They cannot use React portals or third-party libraries that manipulate the DOM outside their tree.
+- They import UI primitives from `twenty-ui` (installed from npm), not from external component libraries.
+- They fetch workspace data through `twenty-client-sdk/core`, not through direct API calls.
+
+## App File Structure
+
+A typical Twenty app after scaffolding:
+
+```
+my-app/
+  package.json                          # App metadata, version, dependencies
+  src/
+    application-config.ts               # defineApplication() — app identity and marketplace metadata
+    constants/
+      universal-identifiers.ts          # Stable UUIDs for all entities
+    objects/                            # defineObject, defineField, defineRelation
+    views/                              # defineView
+    roles/                              # defineRole
+    front-components/                   # defineFrontComponent (.tsx)
+    page-layouts/                       # definePageLayout
+    navigation-menu-items/              # defineNavigationMenuItem
+    logic-functions/                    # defineLogicFunction
+  public/                               # Static assets (logos, screenshots, images)
+  .github/workflows/                    # CI/CD automation (optional)
+```
+
+`application-config.ts` is the app's entry point. It calls `defineApplication()` with the app's universal identifier, display name, description, default role, and marketplace metadata. Every entity references stable UUIDs from `constants/universal-identifiers.ts`.
+
+## Key Concepts
+
+- **Universal identifiers**: Stable UUIDs assigned to every entity. They survive renames, version bumps, and resyncs. Never change a universal identifier after first sync.
+- **Remotes**: Named connections to Twenty instances. Stored in `~/.twenty/config.json`. Switch with `yarn twenty remote:use <name>`.
+- **Sync**: `yarn twenty apply` builds, deploys, and installs the app on the active remote in one step. This is the standard way to get code changes onto a Twenty instance.
+- **Publish**: `yarn twenty app:publish` packages the app for distribution to other instances or the marketplace. Requires a strictly higher semver version than the previously published version.

packages/twenty-agent-skills/references/concepts/operating-rules.md

@@ -0,0 +1,17 @@
+# Operating Rules
+
+These rules apply to every Twenty app task, in every skill and every agent harness. They exist because they have failed before.
+
+This file is the single source of truth for the cross-skill rules. Harness-specific entry points link here instead of restating them, so the rules cannot drift between distributions.
+
+1. **Bounded sync only.** Use `yarn twenty apply` to synchronize app changes. Never `yarn twenty dev` (watch mode). Watch mode leaks file handles and produces ambiguous failure output in agent sandboxes.
+
+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.
+
+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.
+
+5. **Any Twenty instance is a valid target.** The user supplies the workspace or instance URL: managed cloud, self-hosted on a custom HTTPS domain, or localhost over HTTP. Never assume or require a `twenty.com` workspace.
+
+6. **Workspace URLs and credentials stay user-local.** Never bundle workspace-specific MCP URLs in shared or committed files. Bearer tokens, API keys, and OAuth secrets belong in the user's private client config; `TWENTY_DEPLOY_API_KEY` and similar live in CI secret stores, never committed in source.

packages/twenty-agent-skills/references/design/front-component-ui.md

@@ -0,0 +1,452 @@
+# When to Use
+
+Use this when the user wants to design or polish a Twenty front component UI.
+
+Examples:
+
+- Make a front component look better.
+- Create a clean layout for a front component.
+- Improve loading, empty, error, or disabled states.
+- Make a front component responsive and easier to scan.
+
+# Boundaries
+
+Do not scaffold a new app here. Use `create-app` first when the app does not exist.
+
+Do not use this reference for source files, registration, runtime imports, data access, CLI commands, or browser verification.
+
+# Design Rules
+
+Design front components as compact CRM product UI, not marketing pages. The goal is a surface that scans quickly, feels native inside Twenty, and keeps actions predictable.
+
+Use Figma measurements as evidence for the current Twenty rhythm, not as implementation literals. Source code should use Twenty primitives, component props, and `themeCssVariables` instead of hardcoded visual values.
+
+## Twenty UI Defaults
+
+Prefer Twenty UI primitives for CRM-native front component UI:
+
+- Use `Dialog.Title` from `twenty-ui/primitives/surfaces` inside `Modal` for its visible title and accessible name.
+- Use `Heading` from `twenty-ui/primitives/typography` for compact headings, or `Section.Header` from `twenty-ui/components` for a heading with a description or action.
+- Use `Callout` with a matching icon for loading, empty, error, and blocked states.
+- Use `Button` for primary and secondary actions.
+- Use `Tag`, `Status`, `Chip`, `Label`, and `Avatar` for metadata, state, people, and small summaries.
+- Use `themeCssVariables` for spacing, colors, border radius, typography, borders, icon sizing, shadows, and backgrounds.
+
+Use local inline styles for layout containers and custom data displays, but keep them aligned with Twenty tokens. Use `../develop-app/front-components.md` for exact imports and runtime rules.
+
+Use Twenty UI icons before custom SVG. Use `themeCssVariables.icon.size.md` for default row and action icons, `themeCssVariables.icon.size.sm` for quiet chevrons, and `themeCssVariables.spacing[6]` for icon-only action targets.
+
+## Token-First Implementation
+
+When turning a Figma observation into code, translate the visual target into a token:
+
+- Typography uses `themeCssVariables.font.size.*`, `themeCssVariables.font.weight.*`, and `themeCssVariables.text.lineHeight.*`.
+- Spacing uses `themeCssVariables.spacing[...]` and `themeCssVariables.betweenSiblingsGap`.
+- Radius uses `themeCssVariables.border.radius.sm` for compact controls and `themeCssVariables.border.radius.md` for cards or panels.
+- Colors use `themeCssVariables.font.color.*`, `themeCssVariables.background.*`, `themeCssVariables.border.color.*`, or component props.
+- Icons use `themeCssVariables.icon.size.*` or native Twenty UI icon sizing.
+- Borders use `themeCssVariables.border.color.*`; avoid raw border colors.
+- Shadows use `themeCssVariables.boxShadow.*`; avoid custom shadow stacks unless mirroring an existing Twenty overlay exactly.
+
+Do not create source constants named after raw visual measurements. Use semantic names that point to tokens:
+
+```tsx
+const compactControlHeight = themeCssVariables.spacing[6];
+const denseRowHeight = themeCssVariables.spacing[8];
+const panelRadius = themeCssVariables.border.radius.md;
+```
+
+Avoid source constants named after raw measurements, such as `rowHeight` or `cardRadius`, when they hide a token choice. Prefer semantic names like `denseRowHeight` and `panelRadius`.
+
+## Base Scale
+
+Use the same small scale across the whole component:
+
+- Body text: `themeCssVariables.font.size.md`, regular weight, medium line height.
+- Section titles and row titles: `themeCssVariables.font.size.md`, medium weight, medium line height.
+- Descriptions and helper text: `themeCssVariables.font.size.sm`, regular weight, medium line height.
+- Metadata labels and table headers: medium body text with `themeCssVariables.font.color.tertiary`.
+- Compact controls: use Twenty `Button` sizing or `themeCssVariables.spacing[6]` for custom control height.
+- Navigation and menu rows: use the native component when available; otherwise use the nearest theme spacing token that matches the host row rhythm.
+- Dense table, list, and input-like rows: use `themeCssVariables.spacing[8]` for custom row height.
+- Toolbars and view bars: use `themeCssVariables.spacing[10]` for custom toolbar height.
+
+Do not increase type size to create hierarchy inside compact widgets. Use weight, color, alignment, spacing, and order first.
+
+Applied example:
+
+```tsx
+const titleStyle = {
+  fontSize: themeCssVariables.font.size.md,
+  fontWeight: themeCssVariables.font.weight.medium,
+  lineHeight: themeCssVariables.text.lineHeight.md,
+  letterSpacing: 0,
+  color: themeCssVariables.font.color.primary,
+};
+
+const descriptionStyle = {
+  fontSize: themeCssVariables.font.size.sm,
+  fontWeight: themeCssVariables.font.weight.regular,
+  lineHeight: themeCssVariables.text.lineHeight.md,
+  letterSpacing: 0,
+  color: themeCssVariables.font.color.secondary,
+};
+```
+
+## Radius And Shape
+
+Use a small, consistent radius system:
+
+- Cards, popovers, notification containers, and framed panels use `themeCssVariables.border.radius.md`.
+- Buttons, chips, toolbar controls, menu hover fills, skeletons, and small fields use `themeCssVariables.border.radius.sm`.
+- Checkbox shape and target sizing should come from the native Twenty checkbox pattern when available.
+- Do not use pill or rounded radius for cards, rows, or toolbar buttons unless the existing Twenty primitive already does.
+- Do not mix several custom radii in one component. Pick the matching Twenty radius token for each element role.
+
+Applied example:
+
+```tsx
+const cardStyle = {
+  borderRadius: themeCssVariables.border.radius.md,
+  padding: themeCssVariables.spacing[2],
+  background: themeCssVariables.background.primary,
+};
+
+const toolbarButtonStyle = {
+  minHeight: themeCssVariables.spacing[6],
+  padding: `0 ${themeCssVariables.spacing[2]}`,
+  borderRadius: themeCssVariables.border.radius.sm,
+};
+```
+
+## Spacing
+
+Use the theme spacing scale instead of raw dimensions:
+
+- `themeCssVariables.betweenSiblingsGap`: tightly grouped toolbar actions or small separators.
+- `themeCssVariables.spacing[1]`: icon-to-label gaps, chip internals, compact row gaps.
+- `themeCssVariables.spacing[2]`: default card padding, row horizontal padding, toolbar padding, title-row gaps.
+- `themeCssVariables.spacing[4]`: section gaps inside larger panels or between unrelated groups.
+- `themeCssVariables.spacing[6]`: left indentation for description text that belongs to a row with a leading icon and label.
+
+Do not jump to large padding inside ordinary CRM controls. If a compact widget starts needing generous whitespace, the layout probably needs fewer sections or better grouping.
+
+Applied example:
+
+```tsx
+const titleRowStyle = {
+  display: 'flex',
+  alignItems: 'center',
+  gap: themeCssVariables.spacing[2],
+  minHeight: themeCssVariables.spacing[6],
+};
+
+const descriptionRowStyle = {
+  paddingLeft: themeCssVariables.spacing[6],
+  paddingBottom: themeCssVariables.spacing[2],
+};
+```
+
+## Information Hierarchy
+
+Make hierarchy visible without making the component loud:
+
+- Put the record, object, or task name first. Use medium body text with primary color.
+- Put the explanation second. Use small regular text with secondary color.
+- Put metadata third. Use `Tag`, `Status`, `Chip`, `Label`, `Avatar`, or tertiary text.
+- Put counters and quiet totals in light text, not primary text.
+- Use one primary action per small surface. Put secondary actions beside it or behind a menu.
+- Use color for state and meaning, not decoration.
+- Keep descriptions aligned under the title text, not under the leading icon.
+- In a card with a leading icon, use a medium icon, a standard spacing gap, then text. The description starts at the same x-position as the title text.
+- In a list or table, reserve the left edge for the most important identifier and keep it stable across every row.
+
+Good hierarchy:
+
+```tsx
+<div style={{ display: 'grid', gap: themeCssVariables.spacing[1] }}>
+  <div
+    style={{
+      display: 'flex',
+      alignItems: 'center',
+      gap: themeCssVariables.spacing[2],
+    }}
+  >
+    <Avatar name={ownerName} />
+    <span style={titleStyle}>{companyName}</span>
+    <Status color="green" text="Active" />
+  </div>
+  <span style={descriptionStyle}>Renewal due in 12 days</span>
+</div>
+```
+
+Avoid hierarchy that relies on oversized type, all caps, bright backgrounds, or extra padding. That breaks the compact CRM rhythm and makes dense data harder to scan.
+
+## Alignment
+
+Twenty UI looks precise because repeated edges line up:
+
+- Align every custom surface to the theme spacing grid.
+- Use `themeCssVariables.spacing[2]` horizontal padding for compact rows and cards.
+- Use `themeCssVariables.spacing[6]` for icon-only action targets so icons share a stable center.
+- Align row icons, avatars, labels, and actions vertically center.
+- Keep list text left-aligned. Do not center-align row content.
+- Keep toolbar context on the left and actions on the right.
+- Keep repeated rows the same x-position, width, height, and action position.
+- In menus, use a small inset from the menu edge and keep rows full width inside that inset.
+- In tables, use the table theme tokens when available, especially `themeCssVariables.table.horizontalCellPadding`.
+- Do not let a long value push action buttons out of alignment. Truncate text before actions move.
+
+Toolbar pattern:
+
+```tsx
+const toolbarStyle = {
+  minHeight: themeCssVariables.spacing[10],
+  padding: themeCssVariables.spacing[2],
+  display: 'flex',
+  alignItems: 'center',
+  justifyContent: 'space-between',
+  gap: themeCssVariables.spacing[2],
+};
+
+const toolbarActionsStyle = {
+  display: 'flex',
+  alignItems: 'center',
+  gap: themeCssVariables.betweenSiblingsGap,
+};
+```
+
+Table/list row pattern:
+
+```tsx
+const rowStyle = {
+  minHeight: themeCssVariables.spacing[8],
+  padding: `0 ${themeCssVariables.table.horizontalCellPadding}`,
+  display: 'grid',
+  gridTemplateColumns: 'minmax(0, 1fr) auto',
+  alignItems: 'center',
+  columnGap: themeCssVariables.spacing[2],
+};
+
+const cellLabelStyle = {
+  overflow: 'hidden',
+  textOverflow: 'ellipsis',
+  whiteSpace: 'nowrap',
+};
+```
+
+## Consistency
+
+Keep visual decisions repeatable:
+
+- Use the same row height token for every row in the same list.
+- Use the same action placement in loading, empty, error, and ready states.
+- Use the same radius token for the same kind of element everywhere in the component.
+- Use the same icon size token for the same role.
+- Use the same label for the same action everywhere. Do not mix "Open", "View", and "See record" for one action.
+- Use the same empty-state structure across related components: icon, short title, one sentence, one action.
+- Use the same loading skeleton geometry as the final content. Do not replace compact rows with centered spinners unless the whole panel is blocked.
+- Use Twenty tokens for color and spacing. Use raw values only for semantic data visualization that cannot be represented by existing tokens.
+
+State backgrounds should follow the existing Twenty pattern:
+
+- Default: transparent or `themeCssVariables.background.primary`.
+- Hover: `themeCssVariables.background.transparent.light` or `themeCssVariables.background.secondary`.
+- Pressed/clicked: `themeCssVariables.background.tertiary`.
+- Selected: same shape and height as the default row, with selected color treatment from the nearest Twenty primitive.
+- Disabled: same layout, lower contrast, no new decorative color.
+- Loading: same dimensions as ready content, with skeleton blocks using the compact radius token.
+
+## Cards And Panels
+
+Use cards only for individual repeated items, notifications, popovers, or genuinely framed tools. Do not put cards inside cards.
+
+Card defaults:
+
+- Radius: `themeCssVariables.border.radius.md`.
+- Padding: `themeCssVariables.spacing[2]` for compact cards.
+- Title-to-body gap: `themeCssVariables.spacing[2]` only when the body is visually separate.
+- Divider: `themeCssVariables.border.color.light` when sections need separation.
+- Shadow: prefer `themeCssVariables.boxShadow.light` or the native host surface treatment. Do not combine a strong border with a strong shadow.
+
+Overlay feedback pattern:
+
+```tsx
+const overlayFeedbackStyle = {
+  borderRadius: themeCssVariables.border.radius.md,
+  padding: `${themeCssVariables.spacing[2]} ${themeCssVariables.spacing[2]} ${themeCssVariables.spacing[1]}`,
+  display: 'flex',
+  flexDirection: 'column',
+  gap: themeCssVariables.spacing[1],
+  background: themeCssVariables.background.overlayPrimary,
+  backdropFilter: `blur(${themeCssVariables.blur.medium})`,
+  boxShadow: themeCssVariables.boxShadow.strong,
+};
+```
+
+Use overlay styling for small feedback surfaces only. Normal embedded widgets should usually use the host background, a subtle border, or no frame.
+
+## Buttons And Actions
+
+Use actions that feel like Twenty toolbar controls:
+
+- Use `Button` for actual commands.
+- Use Twenty button `size` and `variant` props before custom button styling.
+- For custom compact controls, use `themeCssVariables.spacing[6]` as the control height token.
+- Use `themeCssVariables.spacing[2]` for horizontal padding.
+- Use `themeCssVariables.spacing[1]` for icon-label gaps.
+- Use `themeCssVariables.border.radius.sm` for custom compact action radius.
+- Use medium body text for labels.
+- Use medium icons for primary actions and small icons for quiet chevrons.
+- Use `themeCssVariables.spacing[6]` for icon-only action targets.
+
+Applied example:
+
+```tsx
+<div
+  style={{
+    display: 'flex',
+    alignItems: 'center',
+    gap: themeCssVariables.betweenSiblingsGap,
+  }}
+>
+  <Button variant="secondary" size="small" title="Open record" />
+  <Button variant="secondary" size="small" title="Add note" />
+</div>
+```
+
+## Tables And Dense Lists
+
+Use table-like rhythm for CRM data:
+
+- Header and row height: use `themeCssVariables.spacing[8]` for custom dense rows.
+- Header text: medium body text with tertiary color.
+- Cell text: regular body text with primary or secondary color.
+- Cell padding: use `themeCssVariables.table.horizontalCellPadding`.
+- Icon-label gap: use `themeCssVariables.spacing[1]`.
+- Checkbox column: use `themeCssVariables.table.checkboxColumnWidth` when building table-like custom rows.
+- First data column: make it the flexible `minmax(0, 1fr)` column so names get priority and actions stay aligned.
+- Truncate long names with ellipsis. Do not wrap names in dense rows unless the row is intentionally two-line.
+
+Applied example:
+
+```tsx
+const headerCellStyle = {
+  minHeight: themeCssVariables.spacing[8],
+  padding: `0 ${themeCssVariables.table.horizontalCellPadding}`,
+  display: 'flex',
+  alignItems: 'center',
+  gap: themeCssVariables.spacing[1],
+  fontSize: themeCssVariables.font.size.md,
+  fontWeight: themeCssVariables.font.weight.medium,
+  color: themeCssVariables.font.color.tertiary,
+};
+```
+
+## Empty, Loading, Error, Disabled, Success
+
+Design the visible states before polishing the ready state:
+
+- Loading: preserve final layout dimensions with skeletons that use the same row, text, and radius tokens as the ready content.
+- Empty: use `Callout` or a compact empty block with one short title, one sentence, and one clear action.
+- Error: use `Callout` with an error icon, explain what failed, and offer retry or recovery.
+- Disabled: keep the same control size and placement. Lower contrast and explain the blocking condition if it is not obvious.
+- Success: use a small status, toast-style card, or inline confirmation. Do not redesign the whole panel for success.
+
+Loading example:
+
+```tsx
+const skeletonStyle = {
+  height: themeCssVariables.spacing[4],
+  width: '60%',
+  borderRadius: themeCssVariables.border.radius.sm,
+  background: themeCssVariables.background.transparent.light,
+};
+```
+
+Empty example:
+
+```tsx
+<Callout
+  variant="secondary"
+  title="No activity yet"
+  description="Activity will appear here once this record has timeline events."
+/>
+```
+
+## Text And Copy
+
+Make text fit in real Twenty widths:
+
+- Use sentence case.
+- Use short labels.
+- Use short button text.
+- Use one-sentence descriptions.
+- Put dynamic values in stable containers with ellipsis.
+- Never let a record name, email, URL, or amount overlap an action.
+- Prefer exact object names over generic labels. Use "Open company", not "Open item", when the object is known.
+- Keep units and counts close to the value: `12 opportunities`, `$4,200`, `3 tasks`.
+
+Text truncation pattern:
+
+```tsx
+const truncateStyle = {
+  minWidth: 0,
+  overflow: 'hidden',
+  textOverflow: 'ellipsis',
+  whiteSpace: 'nowrap',
+};
+```
+
+## Responsive Rules
+
+Front components often render in narrow widgets:
+
+- Design compact widths first.
+- Use a single column by default.
+- Move secondary actions into a menu before wrapping the whole toolbar.
+- Keep the primary action visible when space is tight.
+- Let content columns shrink with `minmax(0, 1fr)`.
+- Use ellipsis for long identifiers instead of horizontal scroll in small widgets.
+- Do not use hero-scale text, marketing sections, or wide decorative imagery in embedded CRM widgets.
+
+Narrow layout pattern:
+
+```tsx
+const compactGridStyle = {
+  display: 'grid',
+  gridTemplateColumns: 'minmax(0, 1fr) auto',
+  alignItems: 'center',
+  gap: themeCssVariables.spacing[2],
+};
+```
+
+## Quick Checks
+
+Before considering a UI done, check this list:
+
+- The component uses Twenty typography tokens, not custom text sizes.
+- Cards use the medium radius token or a smaller existing primitive radius.
+- Buttons and action controls use Twenty `Button` props or compact spacing tokens.
+- Table/list rows use a consistent row-height token.
+- Icons use `themeCssVariables.icon.size.*` or native Twenty icon sizing.
+- Spacing uses `themeCssVariables.spacing[...]` and `themeCssVariables.betweenSiblingsGap`.
+- Ready, loading, empty, error, and disabled states share the same structure.
+- Important text has a stable left edge and truncates before it overlaps actions.
+- Repeated rows have identical height, padding, icon size, action placement, and state behavior.
+- The UI uses Twenty primitives and `themeCssVariables` before custom styling.
+
+# Workflow
+
+First, identify the target front component file and the user workflow it supports.
+
+Design the visible states the user will naturally encounter: loading, empty, error, disabled, success, and the primary working state.
+
+Then apply the rules in this order:
+
+1. Set the information hierarchy: title, description, metadata, actions.
+2. Lock the structural dimensions with Twenty primitives and `themeCssVariables`.
+3. Align repeated edges and action positions.
+4. Apply Twenty primitives and tokens.
+5. Add hover, pressed, selected, loading, disabled, empty, error, and success states.
+6. Test with long names, empty values, narrow widths, and multiple records.

packages/twenty-agent-skills/references/develop-app/app-structure.md

@@ -0,0 +1,114 @@
+# App Structure
+
+Use this reference when creating or modifying files inside an existing Twenty app.
+
+Use `../manage-app/cli-and-sync.md` for CLI command behavior, remotes, authentication, sync troubleshooting, build, deploy, logs, and CI/CD.
+
+## App Checks
+
+Before changing app entities, confirm the current directory is a Twenty app:
+
+```bash
+test -f package.json
+test -f src/application-config.ts
+```
+
+If this fails, do not edit from the wrong folder. Check the current path and nearby app roots:
+
+```bash
+pwd
+find . -maxdepth 3 -name package.json -o -path '*/src/application-config.ts'
+```
+
+Move to the matching app root before continuing. If no app exists, use `create-app`. If the folder exists but tooling, dependencies, remotes, authentication, sync, or builds are broken, use `manage-app` before changing app entities.
+
+Inspect the app shape:
+
+```bash
+sed -n '1,220p' package.json
+sed -n '1,220p' src/application-config.ts
+find src -maxdepth 3 -type f | sort
+find public -maxdepth 2 -type f | sort
+```
+
+## Entity Creation
+
+Prefer the app CLI for new entities when interactive prompts are acceptable:
+
+```bash
+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.
+
+Use official Twenty docs or local SDK source when exact imports, entity fields, or configuration shapes matter.
+
+## Source Layout
+
+Add these alongside the scaffolded `src/{fields,objects,logic-functions,front-components,page-layouts,navigation-menu-items,constants}/` as needed:
+
+- `src/utils/` — pure helpers as `<name>.util.ts`, kept flat.
+- `src/types/` — one PascalCase type per file.
+- `src/<service>-client/` — wrappers around external SDKs or HTTP clients. One folder per service, matching Twenty's `*-client` convention (`redis-client/`, `sdk-client/`, ...).
+- Tests as `*.spec.ts` in sibling `__tests__/` folders next to the code they cover.
+
+Filenames are kebab-case; conventional suffixes are `.util.ts`, `.dto.ts`, `.service.ts`, `.spec.ts` — matching the Twenty backend.
+
+### One Export Per File
+
+Every helper, type, and client file exports exactly one thing. The rule counts exports, not declarations — there are no exceptions for `utils/`, `types/`, or `<service>-client/`.
+
+- Never put multiple function exports in the same file. One function per file, each with its own sibling spec.
+- A file must never export more than one thing. A local (non-exported) type used only by the util may live in the same file, but the moment a type is exported or reused elsewhere it moves to `src/types/<name>.ts` while the util stays in `src/utils/<name>.util.ts`.
+
+```ts
+// ❌ Bad — src/utils/parse-company.util.ts exports a type and a util
+export type ParsedCompany = { id: string; name: string };
+export const parseCompany = (raw: RawCompany): ParsedCompany => { /* ... */ };
+
+// ✅ Good — src/utils/parse-company.util.ts (one export; the type is local)
+type ParsedCompany = { id: string; name: string };
+
+export const parseCompany = (raw: RawCompany): ParsedCompany => { /* ... */ };
+
+// ✅ Good — when the type is shared, split it
+// src/types/parsed-company.ts (one PascalCase type)
+export type ParsedCompany = { id: string; name: string };
+
+// src/utils/parse-company.util.ts (one util)
+import { type ParsedCompany } from 'src/types/parsed-company';
+
+export const parseCompany = (raw: RawCompany): ParsedCompany => { /* ... */ };
+```
+
+Entity files are consistent with this rule: front components, logic functions, and post-install hooks use a single `export default define...()`, which is one export.
+
+Files inside `src/types/` use plain `<name>.ts` (one PascalCase type per file) — no `.type.ts` suffix. Files inside `src/<service>-client/` also use plain `<name>.ts`; the folder name carries the suffix, so do not repeat it on the file.
+
+When field definitions differ only by `objectUniversalIdentifier` and label, replace them with a factory in `src/fields/field-factories.ts`.
+
+Read secrets through the application-config helper, not raw `process.env`.
+
+## Boundaries
+
+- Do not scaffold a new app from this workflow. Use `create-app` first when the app does not exist.
+- Do not guess generated entity shapes when the CLI or docs can provide them.
+- Keep app changes scoped to the requested feature and its required registrations.
+
+## Validation Checklist
+
+Once all edits for the change are complete, run lint and typecheck once at the end (not after each individual edit), then sync the app to verify the definitions are valid:
+
+```bash
+yarn twenty dev:typecheck
+yarn lint
+yarn twenty apply
+```
+
+`yarn twenty dev:typecheck` checks generated app types and `yarn lint` checks local lint rules. `yarn twenty apply` then builds the app and pushes entity definitions to the active remote; if any definition is invalid, the sync reports the error. Run all three a single time once every edit is done, not repeatedly after each step.
+
+When the user explicitly asks to run tests, follow `tests.md`: unit tests may use the package's unit-test script, and the full suite must run with `TWENTY_API_URL=http://localhost:2021` against the isolated test instance.
+
+Switch to `manage-app` and use `../manage-app/cli-and-sync.md` for sync or remote troubleshooting.
+
+Tests are not part of sync validation but should cover `src/utils/` helpers and post-install hook idempotency. See `tests.md`.

packages/twenty-agent-skills/references/develop-app/data-model.md

@@ -0,0 +1,108 @@
+# Data Model
+
+Use this reference for Twenty app objects, fields, relations, roles, and permissions.
+
+## Objects And Fields
+
+Objects and fields define the records users will create, view, search, and automate. Model the user's workflow first, then add the smallest set of fields that makes the workflow usable.
+
+When adding or modifying data model entities:
+
+- Prefer generated app entity patterns from `yarn twenty dev:add`.
+- Use clear object and field names that map to user-facing language.
+- Add relations only when users need to navigate or report across records.
+- Avoid duplicating data that already exists on core Twenty objects.
+- Keep field types specific enough to support filtering, views, and automation.
+
+### Usable Object Pattern
+
+When the user asks for a new object and does not explicitly restrict the request to schema only, make the object usable in the app by pairing data model work with the minimum layout/navigation surfaces:
+
+- Object file in `src/objects/<name>.ts`
+- Table view in `src/views/all-<plural>.ts`
+- Object navigation item in `src/navigation-menu-items/<name>.ts`
+- Record page layout in `src/page-layouts/<name>-record-page-layout.ts`
+- Fields-widget view for the record page in `src/views/<name>-record-page-fields.ts`
+
+Use `layout.md` for view, navigation, and page layout details.
+
+Objects support `icon`, but object color is not defined on `defineObject()`. Put color on the object navigation item:
+
+```ts
+import {
+  defineNavigationMenuItem,
+  NavigationMenuItemType,
+} from 'twenty-sdk/define';
+
+export default defineNavigationMenuItem({
+  universalIdentifier: '<uuid>',
+  name: '<name>',
+  icon: '<IconName>',
+  color: '<color>',
+  position: 0,
+  type: NavigationMenuItemType.OBJECT,
+  targetObjectUniversalIdentifier: '<object-uuid>',
+});
+```
+
+### Minimal Object Example
+
+```ts
+import { defineObject, FieldType } from 'twenty-sdk/define';
+
+export const OBJECT_UNIVERSAL_IDENTIFIER = '<uuid>';
+export const NAME_FIELD_UNIVERSAL_IDENTIFIER = '<uuid>';
+
+export default defineObject({
+  universalIdentifier: OBJECT_UNIVERSAL_IDENTIFIER,
+  nameSingular: '<name>',
+  namePlural: '<names>',
+  labelSingular: '<Name>',
+  labelPlural: '<Names>',
+  icon: '<IconName>',
+  labelIdentifierFieldMetadataUniversalIdentifier:
+    NAME_FIELD_UNIVERSAL_IDENTIFIER,
+  fields: [
+    {
+      universalIdentifier: NAME_FIELD_UNIVERSAL_IDENTIFIER,
+      type: FieldType.TEXT,
+      name: 'name',
+      label: 'Name',
+      icon: 'IconAbc',
+    },
+  ],
+});
+```
+
+### Select Fields
+
+Select and multi-select option `value` strings must be uppercase snake case:
+
+```ts
+{
+  type: FieldType.SELECT,
+  name: 'status',
+  label: 'Status',
+  defaultValue: "'PLANNED'",
+  options: [
+    { position: 0, label: 'Planned', value: 'PLANNED', color: 'sky' },
+    { position: 1, label: 'In build', value: 'IN_BUILD', color: 'orange' },
+  ],
+}
+```
+
+For select fields, default values must be quoted string expressions like `"'PLANNED'"`, not plain strings like `'planned'`.
+
+## Roles And Permissions
+
+Roles should match operational responsibility, not implementation convenience.
+
+When adding permissions:
+
+- Grant the smallest useful scope.
+- Keep sensitive objects and fields out of broad roles.
+- Check whether the app introduces side effects through logic functions before granting write access.
+
+## Verification
+
+After data model changes, run the app and verify the objects, fields, and roles appear where the user will manage or use them.

packages/twenty-agent-skills/references/develop-app/front-components.md

@@ -0,0 +1,120 @@
+# Front Components
+
+Use this reference for Twenty app front component source files, registration, data access, Twenty UI imports, runtime imports, and browser verification.
+
+Use `layout.md` for placing a front component in a page layout. Use `standalone-pages.md` for full-page custom UI rendered through a front component widget. Use `../design/front-component-ui.md` for visual design, spacing, states, and polish. Use `app-structure.md` for the develop-app validation checklist and `../manage-app/cli-and-sync.md` for command behavior or troubleshooting.
+
+## Source And Registration
+
+By convention, keep front components under `src/front-components/`, often as `<name>.front-component.tsx`.
+
+Register the component with `defineFrontComponent`:
+
+```tsx
+import { defineFrontComponent } from 'twenty-sdk/define';
+
+const MyFrontComponent = () => {
+  return <div />;
+};
+
+export default defineFrontComponent({
+  universalIdentifier: '<front-component-uuid>',
+  name: '<front-component-name>',
+  description: '<short description>',
+  component: MyFrontComponent,
+});
+```
+
+Do not import or call `react-dom/client` in the component source. The SDK renderer mounts front components.
+
+## Runtime Imports
+
+Keep imports narrow:
+
+- Use `twenty-sdk/front-component` for front component hooks and host APIs.
+- Use `twenty-client-sdk/core` or `twenty-client-sdk/metadata` for data access.
+- Install `twenty-ui` from npm at the same version as `twenty-sdk` and `twenty-client-sdk` and import Twenty UI components, icons, and theme tokens from its subpaths (`twenty-ui/primitives/input`, `twenty-ui/primitives/data-display`, `twenty-ui/icon`, `twenty-ui/primitives/typography`, `twenty-ui/theme-constants`, and others) before adding external UI libraries.
+
+The front component renderer provides a Twenty `ThemeProvider` around the remote root. For isolated examples or local story-style verification, wrapping the component in `ThemeProvider` from `twenty-ui/theme-constants` is also acceptable.
+
+The canonical Twenty UI front component example is `packages/twenty-front-component-renderer/src/__stories__/showcase/twenty-ui-example.front-component.tsx`. It imports `Button` from `twenty-ui/primitives/input`; `Chip`, `Status`, and `Tag` from `twenty-ui/primitives/data-display`; `Section` from `twenty-ui/components`; and `ThemeProvider` from `twenty-ui/theme-constants`.
+
+Read theme tokens with the `useTheme()` hook from `twenty-ui/theme-constants` inside the component body. The same tokens are also exported as the `themeCssVariables` constant, but the SDK mocks `twenty-ui` during manifest extraction, so a module-level constant that dereferences `themeCssVariables` can fail before the component renders — prefer `useTheme()`.
+
+Prefer Twenty UI icons from `twenty-ui/icon` when one exists. Use inline SVG only for app-specific marks or icons that are not available from `twenty-ui/icon`.
+
+## Record Context And Data
+
+For record-page components, read selection from front component context:
+
+- Use `useSelectedRecordIds()` for single, bulk, or empty selection; derive one id only when the array length is 1.
+
+Use the generated or core Twenty client for reads and writes. Keep loading, empty, error, disabled, and saving states explicit so runtime failures are visible and recoverable.
+
+## Headless Actions And DRY Helpers
+
+Headless front components should be thin action shells. The component file should mostly read SDK hooks, return the `Command` helper, and delegate reusable behavior to helpers.
+
+Common headless action flow:
+
+1. Read selected record IDs.
+2. Load the selected records.
+3. Build a payload for one logic-function call.
+4. Execute the logic function.
+5. Parse the result summary.
+6. Show a snackbar.
+7. Let `Command` unmount the component.
+
+Do not duplicate this orchestration across sibling front components. When two components share command execution flow, extract it before copying:
+
+- Pure helpers go in `src/utils/<name>.util.ts`.
+- Front-component runtime helpers go in `src/front-components/utils/<name>.util.ts`.
+- Payload builders, result parsers, selected-record validators, and summary formatters should be small testable functions with sibling specs.
+
+Each extracted helper and type lives in its own file: one export per file. A local, non-exported type may stay with the util, but an exported type moves to its own file. See `app-structure.md`.
+
+Prefer configuration-driven helpers when creating parallel actions for people, companies, tasks, or other objects. Each front component should provide only object-specific configuration, such as the front component universal identifier, logic function universal identifier, record query, payload builder, labels, and snackbar copy.
+
+## Bulk Logic Function Calls
+
+When a front component triggers a logic function for selected records, always prefer a bulk payload shape unless the user explicitly says the logic function is only for one record. The front component should call the logic function once with all selected records, not loop and execute the same logic function once per record.
+
+Default payload shape:
+
+```ts
+{
+  records: Array<{
+    id: string;
+    // object-specific fields used by the logic function
+  }>;
+}
+```
+
+Inside `records`, prefer `id` for the Twenty record ID because the array name already establishes record context. Do not add flat `recordId` payloads unless the user explicitly asks for a single-record action.
+
+Logic functions that return per-record outcomes should mirror the same naming:
+
+```ts
+{
+  ok: boolean;
+  enrichedCount: number;
+  noMatchCount: number;
+  failedCount: number;
+  results: Array<{
+    id: string;
+    status: 'ENRICHED' | 'NO_MATCH' | 'FAILED';
+    error?: string;
+  }>;
+}
+```
+
+If an existing logic function accepts only a flat record ID, prefer upgrading it to accept `records` and remove the old flat input unless the user explicitly asks to preserve it.
+
+## Runtime Verification
+
+A clean typecheck and sync is not runtime verification. After the standard validation in `app-structure.md`, open the relevant Twenty surface and confirm:
+
+- The widget mounts without a `FrontComponent error` in the widget body or toast.
+- The component renders loading, empty, and error states correctly.
+- The main user action works against a real record.
+- The page still renders after a hard refresh.

packages/twenty-agent-skills/references/develop-app/layout.md

@@ -0,0 +1,50 @@
+# Layout
+
+Use this reference for Twenty app views, navigation, page layouts, page layout tabs, and front component registration. Use `standalone-pages.md` when a page layout is meant to host a full-page custom UI.
+
+## Views And Navigation
+
+Views and navigation define the first-run experience. Add only the surfaces users need to understand and operate the app.
+
+When changing views:
+
+- Put the most common workflow first.
+- Use concise names that match the data model.
+- Keep list, board, and detail surfaces consistent with existing Twenty patterns.
+- Avoid creating navigation entries for low-frequency admin tasks unless users need repeated access.
+
+## Page Layouts
+
+Page layouts should make the record's current state and next action easy to scan.
+
+When adding layouts or tabs:
+
+- Group related fields and components.
+- Keep important record status visible without scrolling when possible.
+- Place front components where they support the surrounding record context.
+- Include empty and loading behavior for front components shown on record pages.
+
+## Front Component Widgets
+
+When adding an app-defined front component to a record page layout, use the component's universal identifier in the widget configuration:
+
+```ts
+{
+  universalIdentifier: '<widget-uuid>',
+  title: '<Widget title>',
+  type: 'FRONT_COMPONENT',
+  objectUniversalIdentifier: '<object-uuid>',
+  configuration: {
+    configurationType: 'FRONT_COMPONENT',
+    frontComponentUniversalIdentifier: '<front-component-uuid>',
+  },
+}
+```
+
+Use `frontComponentUniversalIdentifier` for app-defined front components. A `frontComponentId` is not the same value and will not link the widget to the app component correctly.
+
+## Verification
+
+Run the app and inspect the user path from navigation to view to record detail. The route should be discoverable without relying on implementation knowledge.
+
+For front component implementation and runtime verification after placement, use `front-components.md`.

packages/twenty-agent-skills/references/develop-app/logic.md

@@ -0,0 +1,111 @@
+# Logic
+
+Use this reference for Twenty app logic functions, skills, agents, and connection providers.
+
+## Logic Functions
+
+A logic function file should contain trigger registration, input validation, the call out to the work, and the writes back — nothing else. Everything else lives next to it (see `app-structure.md`):
+
+- External API calls → `src/<service>-client/<name>.ts`.
+- Response parsing and mapping → `src/utils/<name>.util.ts`.
+- Response and DTO types → `src/types/<name>.ts`.
+- Shared structure across object types → one mapper factory parameterized by object kind, not parallel functions.
+
+Kebab-case filenames, one export per file. Response/DTO types go in `src/types/<name>.ts` and parsing/mapping helpers in `src/utils/<name>.util.ts` — never export both a type and a util from the same file (a local, non-exported type may stay with the util), and never put multiple function exports in one file. See `app-structure.md`.
+
+Other rules:
+
+- Validate required fields before writes or remote calls.
+- Prefer bulk inputs for record actions. If a logic function can be triggered from selected records, the canonical input should be `records: Array<{ id: string; ...fields }>` unless the user explicitly says the function is only for one record.
+- Use `id` inside a `records` array for the Twenty record ID. Do not add `recordId`, object-specific IDs such as `companyId`, or flat single-record payloads unless the user explicitly requests a single-record contract.
+- Return a bulk summary with per-record results for multi-record actions, including counts for success, no match, and failed records.
+- Prefer idempotent behavior for jobs and repeated invocations.
+- Read secrets through the application-config helper, not raw `process.env`.
+- Do not hide customer-impacting side effects behind UI-only actions.
+
+Soft cap: a `*.logic-function.ts` or `*.post-install.ts` file over 200 lines is a refactor signal.
+
+## Bulk Record Actions
+
+Bulk is the default logic-function contract for actions that may run from front component selection. The front component should gather selected records and invoke the function once. Do not make the front component loop over selected records and execute the same logic function repeatedly unless there is an explicit single-record requirement.
+
+Preferred input:
+
+```ts
+type BulkInput<TRecord extends { id: string }> = {
+  records: TRecord[];
+};
+```
+
+Preferred output:
+
+```ts
+type BulkResult = {
+  ok: boolean;
+  enrichedCount: number;
+  noMatchCount: number;
+  failedCount: number;
+  results: Array<{
+    id: string;
+    status: 'ENRICHED' | 'NO_MATCH' | 'FAILED';
+    pdlId?: string;
+    error?: string;
+  }>;
+};
+```
+
+For existing single-record functions that are being upgraded to selected-record actions, replace the old flat input with `records: Array<{ id: string; ...fields }>` unless the user explicitly asks for backward compatibility.
+
+Extract and test:
+
+- input normalization for the canonical bulk shape;
+- per-record validation;
+- external API payload mapping;
+- per-record result mapping;
+- summary count aggregation;
+- error message normalization.
+
+## Skills And Agents
+
+Skills and agents should describe when they apply, what context they need, and what output is expected.
+
+When adding AI behavior:
+
+- Make trigger rules concrete.
+- Keep instructions grounded in available app data and tools.
+- State when the agent should ask for missing workspace or record context.
+- Avoid exposing raw IDs, timestamps, or nested API output to end users when a readable answer is possible.
+
+## Connection Providers
+
+For third-party connections:
+
+- Keep secrets out of source and public assets.
+- Document required OAuth or API setup in the app README or listing.
+- Verify failure states for expired or missing credentials.
+
+## Post-Install Hooks
+
+Use `definePostInstallLogicFunction` for records that must exist on install — default workflows, views, roles, or seeded reference data. Do not implement this as runtime first-run code.
+
+Post-install hook files live alongside other logic functions (typically `src/logic-functions/<name>.post-install.ts`). Kebab-case filename, one export per file.
+
+Hooks must be idempotent: find by stable identifier before creating, update if it exists, never duplicate. Treat a not-found from a single-record query as "needs create."
+
+Do not write fields Twenty computes elsewhere (workflow `statuses` is computed from version status — see `workflows.md`).
+
+Dev sync skips install hooks. Invoke locally:
+
+```bash
+yarn twenty dev:function:exec
+```
+
+Run again after rebuilding to verify idempotency.
+
+## Uninstall Hook
+
+Use `defineUninstallLogicFunction` for best-effort cleanup of external resources when the app is uninstalled (deprovision API resources, delete remaining bots, revoke webhooks). Failures are logged and never block the uninstall.
+
+Uninstall hook files live alongside other logic functions (typically `src/logic-functions/uninstall.ts`). Kebab-case filename, one export per file.
+
+The hook runs before the app's metadata, data, and code are removed, so handlers can still query the app's objects and records. Handlers receive `UninstallPayload` (`{ version?: string }`).

packages/twenty-agent-skills/references/develop-app/standalone-pages.md

@@ -0,0 +1,461 @@
+# Standalone Pages
+
+Use this reference when a Twenty app needs a full-page custom UI: an operational console, map, canvas, planner, status wall, or other page-sized tool.
+
+For general page layout and navigation entities, use `layout.md`. For front component source, runtime imports, hooks, data access, and browser verification, use `front-components.md`. For visual polish and Twenty UI component choices, use `../design/front-component-ui.md`. For CLI and deployment command details, use `../manage-app/cli-and-sync.md`.
+
+This reference owns only the standalone-page assembly pattern and full-page behavior. It repeats small code fragments where they are needed to show how the pieces connect, but leaves general API behavior to the linked references.
+
+## Mental Model
+
+A standalone page is not a raw page body component. In the current local app pattern, custom page content should be rendered through a `FRONT_COMPONENT` widget inside a `STANDALONE_PAGE` page layout. There does not appear to be a separate public "page body component" API for app-defined standalone pages.
+
+The current model is:
+
+1. Define stable universal identifiers.
+2. Register the page experience with `defineFrontComponent`.
+3. Place that front component in a `definePageLayout` with `type: 'STANDALONE_PAGE'`.
+4. Surface the page with `defineNavigationMenuItem` using `NavigationMenuItemType.PAGE_LAYOUT`.
+5. Sync or install the app.
+6. Twenty resolves the sidebar item to the `/page/:pageLayoutId` route and renders the front component widget inside the page layout.
+
+Use these surfaces for different jobs:
+
+| Surface | Use it for | Primary app entity |
+| --- | --- | --- |
+| Standalone page | A full workspace page that is not tied to one record | `STANDALONE_PAGE` + `PAGE_LAYOUT` navigation item + `FRONT_COMPONENT` widget |
+| Record page layout | Tabs and widgets for one object record | `RECORD_PAGE` page layout or page layout tab |
+| Dashboard | Metric and report composition from built-in widgets | `DASHBOARD` page layout |
+| Command or side panel | Short actions, focused forms, one selected record, or background commands | `defineFrontComponent` plus command menu item |
+
+## Removing The Scaffolded Placeholder
+
+Every freshly scaffolded app contains three placeholder files that wire a "Welcome" sidebar item to a generic landing page:
+
+- `src/front-components/main-page.tsx`
+- `src/page-layouts/main-page.page-layout.ts`
+- `src/navigation-menu-items/main-page.navigation-menu-item.ts`
+
+If the app has no user-facing page — for example, it only extends standard objects, declares logic functions, or seeds workflows — delete all three files before the first deploy. Leaving them in ships a dead sidebar item.
+
+## Quickstart
+
+Use this minimal file set:
+
+- `src/constants/universal-identifiers.ts`
+- `src/front-components/<name>.front-component.tsx`
+- `src/page-layouts/<name>.page-layout.ts`
+- `src/navigation-menu-items/<name>.navigation-menu-item.ts`
+
+Start with a tiny component that proves the route works before building the full page.
+
+```ts src/constants/universal-identifiers.ts
+export const MISSION_CONTROL_FRONT_COMPONENT_UNIVERSAL_IDENTIFIER =
+  'a0a1c4f0-f23a-4c59-93c5-92146d64b110';
+
+export const MISSION_CONTROL_PAGE_LAYOUT_UNIVERSAL_IDENTIFIER =
+  '63d4970d-6c54-49c8-9c15-52d7cb00fb7a';
+```
+
+```tsx src/front-components/mission-control.front-component.tsx
+import { defineFrontComponent } from 'twenty-sdk/define';
+
+import {
+  MISSION_CONTROL_FRONT_COMPONENT_UNIVERSAL_IDENTIFIER,
+} from '../constants/universal-identifiers';
+
+const MissionControl = () => {
+  return (
+    <main
+      style={{
+        boxSizing: 'border-box',
+        display: 'grid',
+        minHeight: '100%',
+        padding: 24,
+        placeItems: 'center',
+        width: '100%',
+      }}
+    >
+      <h1 style={{ margin: 0 }}>Mission Control</h1>
+    </main>
+  );
+};
+
+export default defineFrontComponent({
+  universalIdentifier: MISSION_CONTROL_FRONT_COMPONENT_UNIVERSAL_IDENTIFIER,
+  name: 'mission-control',
+  description: 'Standalone mission control page.',
+  component: MissionControl,
+});
+```
+
+```ts src/page-layouts/mission-control.page-layout.ts
+import {
+  definePageLayout,
+  PageLayoutTabLayoutMode,
+} from 'twenty-sdk/define';
+
+import {
+  MISSION_CONTROL_FRONT_COMPONENT_UNIVERSAL_IDENTIFIER,
+  MISSION_CONTROL_PAGE_LAYOUT_UNIVERSAL_IDENTIFIER,
+} from '../constants/universal-identifiers';
+
+export default definePageLayout({
+  universalIdentifier: MISSION_CONTROL_PAGE_LAYOUT_UNIVERSAL_IDENTIFIER,
+  name: 'Mission Control',
+  type: 'STANDALONE_PAGE',
+  tabs: [
+    {
+      universalIdentifier: 'e6963ad3-e5fa-41c7-83e1-4fc2ca5de9a8',
+      title: 'Mission Control',
+      position: 0,
+      icon: 'IconRocket',
+      layoutMode: PageLayoutTabLayoutMode.VERTICAL_LIST,
+      widgets: [
+        {
+          universalIdentifier: '18ce05bb-ee3c-4332-80a7-f8fb84f7f70a',
+          title: 'Mission Control',
+          type: 'FRONT_COMPONENT',
+          heightBehavior: 'TAB_VIEWPORT',
+          configuration: {
+            configurationType: 'FRONT_COMPONENT',
+            frontComponentUniversalIdentifier:
+              MISSION_CONTROL_FRONT_COMPONENT_UNIVERSAL_IDENTIFIER,
+          },
+        },
+      ],
+    },
+  ],
+});
+```
+
+```ts src/navigation-menu-items/mission-control.navigation-menu-item.ts
+import {
+  defineNavigationMenuItem,
+  NavigationMenuItemType,
+} from 'twenty-sdk/define';
+
+import {
+  MISSION_CONTROL_PAGE_LAYOUT_UNIVERSAL_IDENTIFIER,
+} from '../constants/universal-identifiers';
+
+export default defineNavigationMenuItem({
+  universalIdentifier: '61d44a63-16e8-4fbe-bccb-9c220d44fdb9',
+  name: 'Mission Control',
+  icon: 'IconRocket',
+  color: 'blue',
+  position: 50,
+  type: NavigationMenuItemType.PAGE_LAYOUT,
+  pageLayoutUniversalIdentifier:
+    MISSION_CONTROL_PAGE_LAYOUT_UNIVERSAL_IDENTIFIER,
+});
+```
+
+Use a `VERTICAL_LIST` tab and give its single widget `TAB_VIEWPORT` height behavior for a page-sized surface. The widget owns internal scrolling while the tab owns its viewport.
+
+After the tiny page renders, replace the component body with a full-screen structure:
+
+```tsx
+const MissionControl = () => {
+  return (
+    <main
+      style={{
+        boxSizing: 'border-box',
+        display: 'grid',
+        gap: 16,
+        gridTemplateRows: 'auto minmax(0, 1fr)',
+        height: '100%',
+        minHeight: '100%',
+        overflow: 'hidden',
+        padding: 16,
+        width: '100%',
+      }}
+    >
+      <header style={{ display: 'flex', justifyContent: 'space-between' }}>
+        <h1 style={{ margin: 0 }}>Mission Control</h1>
+        <button type="button">Refresh</button>
+      </header>
+
+      <section
+        style={{
+          display: 'grid',
+          gridTemplateColumns: '280px minmax(0, 1fr)',
+          minHeight: 0,
+          overflow: 'hidden',
+        }}
+      >
+        <aside style={{ minHeight: 0, overflow: 'auto' }}>Filters</aside>
+        <div style={{ minHeight: 0, overflow: 'auto' }}>Workspace data</div>
+      </section>
+    </main>
+  );
+};
+```
+
+## API Reference
+
+This section only calls out the fields that matter for standalone pages. Use `layout.md` and `front-components.md` for broader entity guidance.
+
+`definePageLayout` owns the standalone route target:
+
+- Use `type: 'STANDALONE_PAGE'`.
+- Do not set `objectUniversalIdentifier`; standalone pages are not record scoped.
+- Define at least one tab. Use one tab unless the page needs real top-level modes.
+- Use `PageLayoutTabLayoutMode.VERTICAL_LIST`; widgets inherit the tab's layout mode and follow their order in the `widgets` array. Put the `FRONT_COMPONENT` last and set its top-level `heightBehavior` to `'TAB_VIEWPORT'`.
+- Use a `FRONT_COMPONENT` widget with `configurationType: 'FRONT_COMPONENT'` and `frontComponentUniversalIdentifier`.
+
+`defineFrontComponent` owns the actual page experience:
+
+- Register a visible component with `component`, `name`, `description`, and a stable `universalIdentifier`.
+- Use `twenty-sdk/front-component` for runtime hooks, host navigation, snackbars, application variables, and side panel actions.
+- Use `twenty-client-sdk/core` for workspace records when the page is data driven.
+- Use `getPublicAssetUrl` from `twenty-sdk/define` for app-bundled images or static files.
+
+`defineNavigationMenuItem` owns sidebar reachability:
+
+- Use `type: NavigationMenuItemType.PAGE_LAYOUT`.
+- Set `pageLayoutUniversalIdentifier` to the standalone page layout universal identifier.
+- Set a clear `name`, `icon`, `color`, and `position`.
+- Use `folderUniversalIdentifier` only when the page belongs under an existing app folder.
+
+Public assets and non-secret application variables make standalone pages richer without hardcoding environment data:
+
+```tsx
+import { defineFrontComponent, getPublicAssetUrl } from 'twenty-sdk/define';
+import { getApplicationVariable } from 'twenty-sdk/front-component';
+
+const logoUrl = getPublicAssetUrl('mission-control-logo.png');
+
+const MissionBrand = () => {
+  const label = getApplicationVariable('MISSION_LABEL') ?? 'Mission Control';
+
+  return <img src={logoUrl} alt={label} />;
+};
+```
+
+## Full-Page Layout Guidance
+
+The front component only fills the page if every layer inside the widget has deterministic sizing. Start the root at `height: '100%'`, `minHeight: '100%'`, `width: '100%'`, and `boxSizing: 'border-box'`.
+
+Use `minmax(0, 1fr)` and `minHeight: 0` for scrollable grid or flex children. Without these constraints, inner tables, maps, and canvases can force the page taller than the widget or collapse into a zero-height area.
+
+Prefer one immersive tool surface over a dashboard made of many small cards. If the page is a mission tracker, map, editor, kanban, planner, or cockpit, make the front component own the composition and use internal panels only where they support the workflow.
+
+Assume the available area changes with Twenty chrome, the left sidebar, side panel state, tab list, and smaller screens. Use responsive CSS inside the front component:
+
+- Collapse side filters above or below the main surface on narrow widths.
+- Keep map, canvas, table, and timeline containers at `minHeight: 0`.
+- Make only intentional regions scroll.
+- Keep loading, empty, and error states inside the same sized root so the page never goes blank while data changes.
+
+Avoid hidden overflow traps. `overflow: 'hidden'` is useful for map and canvas roots, but pair it with explicit scroll containers for lists and diagnostics.
+
+## Data And Interactivity
+
+Fetch live workspace records from the front component when the page reflects workspace state:
+
+Use `front-components.md` for general client/runtime rules. In standalone pages, the key additions are visible full-page loading, empty, and error states, plus navigation from the standalone surface back into Twenty records.
+
+```tsx
+import { useEffect, useState } from 'react';
+import { CoreApiClient, type CoreSchema } from 'twenty-client-sdk/core';
+import { defineFrontComponent } from 'twenty-sdk/define';
+import {
+  AppPath,
+  enqueueSnackbar,
+  navigate,
+} from 'twenty-sdk/front-component';
+
+type CompanySummary = Pick<CoreSchema.Company, 'id' | 'name'>;
+
+const CompaniesStandalonePage = () => {
+  const [companies, setCompanies] = useState<CompanySummary[]>([]);
+  const [loading, setLoading] = useState(true);
+  const [error, setError] = useState<string | null>(null);
+
+  useEffect(() => {
+    let cancelled = false;
+
+    const loadCompanies = async () => {
+      try {
+        setLoading(true);
+        setError(null);
+
+        const client = new CoreApiClient();
+        const result = await client.query({
+          companies: {
+            edges: {
+              node: {
+                id: true,
+                name: true,
+              },
+            },
+          },
+        });
+
+        if (!cancelled) {
+          setCompanies(result.companies.edges.map((edge) => edge.node));
+        }
+      } catch (err) {
+        const message =
+          err instanceof Error ? err.message : 'Failed to load companies';
+
+        if (!cancelled) {
+          setError(message);
+          enqueueSnackbar({ message, variant: 'error' });
+        }
+      } finally {
+        if (!cancelled) {
+          setLoading(false);
+        }
+      }
+    };
+
+    loadCompanies();
+
+    return () => {
+      cancelled = true;
+    };
+  }, []);
+
+  if (loading) return <div style={{ padding: 24 }}>Loading companies...</div>;
+  if (error) return <div style={{ padding: 24 }}>{error}</div>;
+  if (companies.length === 0) {
+    return <div style={{ padding: 24 }}>No companies yet.</div>;
+  }
+
+  return (
+    <div style={{ display: 'grid', gap: 8, padding: 24 }}>
+      {companies.map((company) => (
+        <button
+          key={company.id}
+          type="button"
+          onClick={() =>
+            navigate(AppPath.RecordShowPage, {
+              objectNameSingular: 'company',
+              objectRecordId: company.id,
+            })
+          }
+        >
+          {company.name}
+        </button>
+      ))}
+    </div>
+  );
+};
+
+export default defineFrontComponent({
+  universalIdentifier: '5aa8c51f-72a4-4929-a6ab-2d4ea9d2a6df',
+  name: 'companies-standalone-page',
+  description: 'Lists companies and opens related records.',
+  component: CompaniesStandalonePage,
+});
+```
+
+Always model these states:
+
+- Loading: show progress in the same page shell that the loaded view uses.
+- Empty: explain what is missing and offer the next action if one exists.
+- Error: show the message and keep a retry path visible.
+- Auth refresh: token failures can happen during development or long-lived sessions; surface the failure instead of returning `null`.
+- Demo data: label fake data clearly and keep the switch to live data obvious.
+
+Use `navigate` for full-page routes and `openSidePanelPage` for focused side-panel workflows. Prefer navigating to the record route when the user is leaving the standalone experience to inspect a real record.
+
+## Debugging
+
+For a black screen, check the simplest causes first:
+
+- Component runtime exception: open the browser console and look for a front component error, React error, or Remote DOM unsupported operation.
+- Missing data fallback: temporarily replace the component with the tiny "Mission Control" component from this reference.
+- Token or fetch failure: log the caught error, confirm `CoreApiClient` generation, and show an error state.
+- Public asset failure: verify `getPublicAssetUrl(...)` output in the network tab and render without the asset.
+- CSS layer covering content: remove absolute overlays, `zIndex`, and full-screen backgrounds until text is visible.
+- Zero-height container: add visible borders and confirm `height: '100%'`, `minHeight: '100%'`, `minHeight: 0`, and the widget's `TAB_VIEWPORT` position.
+- Unsupported browser or Remote DOM behavior: remove unusual DOM APIs, portals, global document access, and third-party components until the minimal UI renders.
+- Stale deployed app version: confirm the installed app version is the one you just synced or deployed.
+
+Console checks:
+
+```tsx
+console.info('Standalone page mounted');
+console.info('Companies loaded', companies.length);
+```
+
+Installed-app checks:
+
+- Confirm the app appears in Twenty settings or the application developer view.
+- Confirm the sidebar item appears with the expected icon and label.
+- Confirm clicking the sidebar item opens `/page/:pageLayoutId`.
+- Confirm the page still renders after a hard refresh.
+
+Known-good component test:
+
+```tsx
+const KnownGoodStandalonePage = () => (
+  <main style={{ minHeight: '100%', padding: 24 }}>
+    <h1>Standalone page runtime is working</h1>
+  </main>
+);
+```
+
+If this renders but the full page does not, the issue is inside the full component. If this does not render, inspect the layout, navigation, sync, installation, and front component registration.
+
+## Deployment And Verification
+
+Use bounded apply for deployment and verification. Use `../manage-app/cli-and-sync.md` for exact command behavior, remote setup, verbose troubleshooting, deploys, and logs.
+
+```bash
+yarn twenty apply
+```
+
+Install and update flow:
+
+- During development, sync against the active remote and confirm the app appears as installed in the target workspace.
+- For an already installed app, sync or deploy the updated version, then reopen the sidebar route and hard refresh the page.
+- For packaged deploys, bump `package.json` before publishing an update to a workspace that already has the app installed.
+
+Versioning expectations:
+
+- Dev sync updates the active remote during development.
+- Deploying a packaged update requires a strictly higher `package.json` version than the installed version.
+- Users may need to update or reinstall the app depending on how the target workspace receives application updates.
+
+Acceptance checks:
+
+- Sidebar item appears in the expected section or folder.
+- Sidebar item opens the standalone page route.
+- The front component renders visible content.
+- The component fills the widget/page area at desktop size.
+- Data loads from live workspace records or a clearly labeled demo source.
+- Loading, empty, and error fallbacks are visible and nonblank.
+- Record navigation or side panel interactions work.
+- Desktop and smaller-screen screenshots are nonblank and do not show overlapping controls.
+
+## Examples
+
+Minimal standalone page:
+
+- One front component.
+- One `STANDALONE_PAGE` page layout.
+- One `PAGE_LAYOUT` navigation item.
+- One `FRONT_COMPONENT` widget with `TAB_VIEWPORT` height behavior.
+
+Full-screen operational page:
+
+- Root grid with header and `minmax(0, 1fr)` body.
+- Left filter panel, central work surface, optional right inspector.
+- Loading, empty, error, and retry UI inside the same shell.
+
+Data-driven page that opens related records:
+
+- Fetch records with `CoreApiClient`.
+- Render a list, table, timeline, or map.
+- Use `navigate(AppPath.RecordShowPage, { objectNameSingular, objectRecordId })` for record drill-in.
+
+Immersive canvas or map-style page, such as a Space X Mission Tracking page:
+
+- Keep the map/canvas as the main full-height surface.
+- Put filters, mission status, and selected mission details in internal panels.
+- Use public assets for mission patches or map overlays.
+- Avoid composing the page as dashboard cards unless the user is primarily comparing metrics.

packages/twenty-agent-skills/references/develop-app/tests.md

@@ -0,0 +1,46 @@
+# Tests
+
+Tests use the `*.spec.ts` extension and live in sibling `__tests__/` folders next to the code they cover, matching Twenty backend conventions. Write them where `yarn twenty apply` does not validate correctness.
+
+Always write a test file for every util or function. Whenever you create or modify a file in `src/utils/` (or any other testable function file), you MUST create or update its sibling `__tests__/<name>.spec.ts`. A util or function without a spec file is incomplete.
+
+## File Organization
+
+Write one spec file per util or function source file. Each testable source file gets a dedicated sibling `__tests__/<name>.spec.ts` whose name mirrors the source file. Do not combine multiple utils or functions into a single spec file.
+
+```
+src/utils/parse-foo.util.ts
+src/utils/__tests__/parse-foo.util.spec.ts
+src/utils/map-bar.util.ts
+src/utils/__tests__/map-bar.util.spec.ts
+```
+
+## What To Test
+
+- Parsers in `src/utils/` — every branch of foreign API shape handling, including missing fields and empty responses.
+- Mappers in `src/utils/` — foreign-to-Twenty mapping, including the "no match" case.
+- Front-component helpers in `src/front-components/utils/` — selected-record validation, payload builders, logic-function result parsing, summary aggregation, and snackbar message formatting.
+- Bulk logic-function normalization — the canonical `records: Array<{ id: string; ...fields }>` shape, including empty arrays and records missing `id`.
+- Post-install hooks — at minimum, idempotency: run twice, assert state is identical.
+- Side effects (billing, external state) — assert they fire only on the conditions the code claims.
+
+## What To Skip
+
+- Entity definitions (`*.field.ts`, `*.object.ts`) — sync validates these.
+- Front component rendering shells — verify in the browser. Extracted helper functions are not rendering shells and must be unit-tested.
+
+## Running Tests
+
+Integration tests build, deploy, install, and uninstall the app on whatever server `TWENTY_API_URL` points to. The scaffold defaults to the dev instance (`http://localhost:2020`), so running them there adds and then removes the app from the workspace you sync to with `yarn twenty apply`. Always run them against the isolated test instance instead — a separate container, database, and port (`2021`) that does not affect your running dev instance:
+
+```bash
+# Start the isolated test instance (once).
+yarn twenty docker:start --test
+
+# Run integration tests against it.
+TWENTY_API_URL=http://localhost:2021 yarn test
+```
+
+The seeded default `TWENTY_API_KEY` works for both instances, so only the URL needs overriding. This mirrors CI, which spawns the same isolated instance via the `spawn-twenty-app-dev-test` action.
+
+When the user asks you to run tests, do run them. First start or verify the isolated test instance, then run the test command with `TWENTY_API_URL=http://localhost:2021`. Do not run integration tests against `http://localhost:2020` unless the user explicitly asks to target the dev instance. If only unit tests are requested, use the package's unit-test script and no `TWENTY_API_URL` override is needed.

packages/twenty-agent-skills/references/develop-app/workflows.md

@@ -0,0 +1,47 @@
+# Workflows
+
+Use when the app needs to ship a manual workflow on install, or when a logic function should be invocable from the workflow builder.
+
+See `logic.md` for post-install hooks. See `app-structure.md` for source layout.
+
+## Mental Model
+
+Twenty workflows are workspace records, not app entities — no `define*` primitive. Ship them via `definePostInstallLogicFunction` and the workspace API.
+
+A workflow is a `Workflow` plus at least one `WorkflowVersion`. Creating a `Workflow` auto-creates its draft `v1`; never create a `WorkflowVersion` directly.
+
+## Manual Record Trigger
+
+- Trigger type: manual record selection.
+- The selected record is the trigger payload — no wrapping `record` field.
+- Reference fields with `{{trigger.<field>}}`. Do not use `{{trigger.record.<field>}}`.
+
+## Lifecycle
+
+Always: create → configure draft → activate. Never publish a draft directly.
+
+1. Find or create the `Workflow` by stable name or slug. `createWorkflow` produces the draft `v1`.
+2. Set the trigger on the draft via `updateWorkflowVersion`.
+3. Add steps via the workflow-step mutations. `createWorkflowVersionStep` returns a `stepsDiff`, not the step — read the diff for the new step id, then call `updateWorkflowVersionStep` with the full payload.
+4. Activate via `activateWorkflowVersion`.
+
+Forbidden:
+
+- Do not write `Workflow.statuses` — it is computed from the active version's status.
+- Do not create `WorkflowVersion` rows directly.
+
+## Idempotency
+
+Find by deterministic name or slug before creating. Single-record queries throw on absence in some Twenty versions — treat not-found as "needs create."
+
+## Permissions
+
+Seeders need workflow settings permissions on the app role. Grant via `defineRole`. If a typed mutation is rejected from the app context, fix the role — falling back to raw GraphQL signals the wrong scope.
+
+## Invoking Locally
+
+```bash
+yarn twenty dev:function:exec
+```
+
+`yarn twenty apply` skips install hooks. Run it again after rebuilding to verify idempotency.

packages/twenty-agent-skills/references/manage-app/cli-and-sync.md

@@ -0,0 +1,172 @@
+# CLI And Sync
+
+Use this reference for Twenty app CLI command behavior, remotes, authentication, sync, validation commands, build, deploy, logs, function execution, and CI/CD troubleshooting.
+
+Use `../develop-app/app-structure.md` only for app file layout and post-entity-edit validation checklists.
+
+## App Checks
+
+Before running operational commands, confirm the current directory is a Twenty app and inspect the active scripts and remotes:
+
+```bash
+test -f package.json
+test -f src/application-config.ts
+sed -n '1,220p' package.json
+yarn twenty remote:list
+```
+
+Treat deploys, uninstalls, production remote changes, and production syncs as externally visible actions. Ask for explicit confirmation before running them when the target is production or user data could be affected.
+
+## Validation Commands
+
+Use these commands to validate an app after changes:
+
+```bash
+yarn twenty dev:typecheck
+yarn lint
+```
+
+If the app is already installed on the active remote, preview and then apply
+the metadata changes:
+
+```bash
+yarn twenty plan
+yarn twenty apply
+```
+
+`yarn twenty dev:typecheck` checks generated app types and TypeScript compatibility. `yarn lint` checks local lint rules. `yarn twenty plan` previews metadata changes, and `yarn twenty apply` performs a bounded build/sync against the active remote.
+
+`yarn twenty plan` is read-only and requires the app to already be installed
+on the active remote. For a first sync, run `yarn twenty apply`; it registers
+the app before synchronizing it. `create-twenty-app` normally performs this
+initial sync, so a successfully scaffolded app does not need an extra apply.
+Use the first-sync path when the scaffold sync failed, or when the app was
+created or copied without being installed on this remote.
+
+If a validation command fails because of entity definitions, switch to `develop-app` for the fix. If it fails because of remotes, authentication, build tooling, sync, logs, deploys, or CI/CD, stay in `manage-app`.
+
+## Remotes
+
+A remote is a Twenty server that the app can sync or deploy to. Credentials are stored locally in `~/.twenty/config.json`.
+
+Common commands:
+
+```bash
+# Add a remote interactively.
+yarn twenty remote:add
+
+# Connect to a local Twenty server.
+yarn twenty remote:add --local
+
+# Add a remote non-interactively.
+yarn twenty remote:add --url https://your-twenty-server.com --api-key $TWENTY_API_KEY --as production
+
+# List configured remotes.
+yarn twenty remote:list
+
+# Switch the active remote.
+yarn twenty remote:use <name>
+```
+
+When the user says "prod", "production", or "workspace de prod", identify the target remote before syncing or deploying. If it is missing, add it with `--as production` or the user-provided name.
+
+## Development Sync
+
+Use the bounded apply command to synchronize app changes with the active remote:
+
+```bash
+yarn twenty apply
+```
+
+Do not use bare `yarn twenty dev` (watch mode). Run `yarn twenty apply` each time changes need to be synced.
+
+Apply requires an authenticated remote. If authentication fails, re-add or switch the remote before retrying.
+
+Use verbose apply for bounded troubleshooting:
+
+```bash
+yarn twenty apply --verbose
+```
+
+## Troubleshooting
+
+Start by identifying which layer is failing:
+
+- Remote/authentication.
+- Dev sync or apply.
+- Build/package generation.
+- Deploy/upload/install.
+- Runtime function execution.
+- CI/CD environment or secrets.
+
+Collect the minimum useful context before changing configuration:
+
+```bash
+sed -n '1,220p' package.json
+sed -n '1,220p' src/application-config.ts
+yarn twenty remote:list
+yarn twenty apply --verbose
+```
+
+For remote or authentication issues:
+
+- Check that the active remote is the intended workspace or server.
+- Re-run `yarn twenty remote:add --local` for local app-dev servers.
+- Re-run `yarn twenty remote:add --url <url> --as <name>` for remote servers.
+- Avoid overwriting a production remote until the target URL is confirmed.
+
+For sync issues:
+
+- Prefer `yarn twenty apply --verbose` to get a bounded failure.
+- Check generated type or schema errors before editing app entities.
+- If the app depends on a changed data model, use `develop-app` to fix the entity definitions.
+
+## Build, Deploy, Logs, And Exec
+
+Build before deploy when the user asks for release readiness or when debugging packaging issues:
+
+```bash
+yarn twenty dev:build
+```
+
+Publish an app to npm, or publish privately to a configured Twenty server registry:
+
+```bash
+yarn twenty app:publish
+yarn twenty app:publish --private --remote production
+yarn twenty app:install --remote production
+```
+
+Before deploying an update, check that `package.json` has a strictly higher semver `version` than the currently deployed version. Re-deploying the same version is rejected. After a private publish, install the deployed version with `yarn twenty app:install` when the target workspace should use it.
+
+Use function logs when debugging runtime behavior on the connected server:
+
+```bash
+yarn twenty dev:function:logs
+yarn twenty dev:function:logs -n <function-name>
+```
+
+Run a logic function manually when testing behavior without its trigger:
+
+```bash
+yarn twenty dev:function:exec -n <function-name>
+yarn twenty dev:function:exec -n <function-name> -p '{"key":"value"}'
+```
+
+Uninstall only after confirmation:
+
+```bash
+yarn twenty app:uninstall
+yarn twenty app:uninstall --yes
+```
+
+Integration tests install and uninstall the app on their target server, so run them against the isolated test instance (`yarn twenty docker:start --test`, port `2021`) rather than the dev instance — see `../develop-app/tests.md`.
+
+## CI/CD
+
+Apps generated with `create-twenty-app` can use GitHub Actions for CI and CD. For deployment automation, check the app's `.github/workflows/` files and configure:
+
+- `TWENTY_DEPLOY_URL`
+- `TWENTY_DEPLOY_API_KEY`
+
+Do not put API keys in source files. Use the repository or CI secret store.

packages/twenty-agent-skills/references/publish-app/prepare-for-app-store.md

@@ -0,0 +1,212 @@
+# Prepare App Listing
+
+Use this reference for the publish-facing documentation and visuals of a Twenty app. It complements `create-app`; read this when the app is ready for packaging, marketplace listing, npm publishing, private sharing, or user-facing review.
+
+## When To Use
+
+Use this when the user asks to:
+
+- Write or improve a Twenty app `README.md`.
+- Prepare npm package content or Twenty marketplace copy.
+- Add or audit `defineApplication()` marketplace metadata.
+- Create, select, capture, or validate app logo and screenshots.
+- Decide what belongs in `public/` for marketplace, front components, or logic functions.
+- Make the app understandable to admins, workspace members, and reviewers before publish/deploy.
+
+## Source Rules
+
+Twenty marketplace metadata comes from `defineApplication()`:
+
+- `displayName`
+- `description`
+- `author`
+- `category`
+- `logoUrl`
+- `screenshots`
+- `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.
+
+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.
+
+## README Workflow
+
+Before writing, inspect the app:
+
+```bash
+sed -n '1,220p' package.json
+sed -n '1,220p' src/application-config.ts
+find src -maxdepth 3 -type f | sort
+find public -maxdepth 2 -type f | sort
+```
+
+Read app entities to understand the actual product surface:
+
+- Objects and fields define the data model users will see.
+- Views, navigation, and page layouts define the first-run experience.
+- Logic functions explain automation and side effects.
+- Front components explain UI surfaces and interactions.
+- Skills and agents explain AI behavior.
+- Connection providers explain third-party OAuth setup.
+- Roles explain permission scope and data access.
+
+Write the README for the person installing or evaluating the app, not for the original implementer.
+
+## README Shape
+
+Use this structure unless the app already has a stronger local convention:
+
+```markdown
+# App Display Name
+
+One-sentence summary of what the app adds to Twenty.
+
+## What It Does
+
+- Concrete user-facing capability.
+- Concrete user-facing capability.
+- Concrete user-facing capability.
+
+## What It Adds To Twenty
+
+- Objects:
+- Fields:
+- Views and navigation:
+- Page layouts:
+- Front components:
+- Logic functions:
+- Skills and agents:
+- Connections:
+
+## Requirements
+
+- Twenty server/version requirement, if any.
+- Third-party account or OAuth app requirements, if any.
+- Required server variables or application variables.
+
+## Setup
+
+1. Install or deploy the app.
+2. Configure required variables.
+3. Add any required connections.
+4. Open the relevant Twenty view or app settings page.
+
+## Usage
+
+Short workflow with concrete user actions and expected result.
+
+## Development
+
+Commands for local setup, dev sync, tests, build, deploy, and publish.
+
+## Permissions And Data
+
+What the app reads, writes, updates, deletes, and sends to third-party services.
+
+## Support
+
+Support email, issue tracker, docs, terms, or website links.
+```
+
+Keep the README accurate and specific. Do not claim the app supports an entity, workflow, permission, integration, or marketplace capability unless it exists in code.
+
+## Copy Guidelines
+
+Use plain product language:
+
+- Lead with the workspace outcome, not the implementation.
+- Name the Twenty objects and views users will actually interact with.
+- Explain setup variables by their exact names.
+- Distinguish server admin setup from workspace member usage.
+- For OAuth connections, mention the provider redirect URI: `<SERVER_URL>/auth/apps/callback`.
+- Document permissions in terms of user risk: read, create, update, soft delete, destroy, third-party send.
+
+Avoid:
+
+- Marketing filler.
+- Claims about security, compliance, uptime, or certification that are not backed by the app.
+- Screenshots or examples containing real customer data.
+- API keys, OAuth secrets, tokens, or private server URLs.
+
+## Visual Assets
+
+Put marketplace and runtime visuals in `public/`:
+
+```text
+public/
+  logo.png
+  screenshot-1.png
+  screenshot-2.png
+  screenshot-3.png
+```
+
+Use stable, descriptive filenames. Prefer PNG for marketplace visuals. Keep source files only if the project already keeps editable artwork.
+
+Logo guidance:
+
+- Make it legible at small sizes.
+- Use simple geometry or product-specific symbolism.
+- Avoid text-heavy logos unless the brand requires it.
+- Do not use the Twenty logo as the app logo unless the app is officially owned by Twenty and the user intends that.
+
+Screenshot guidance:
+
+- Capture real app surfaces after `yarn twenty apply` or watch-mode sync.
+- Prefer the most useful user paths: app listing/about page, object index view, record page layout, front component surface, connection settings, or AI skill/agent behavior.
+- Use seeded or synthetic data only.
+- Hide browser chrome unless it helps explain setup.
+- Do not fake product screenshots with generated images. Use generated visuals for logos, diagrams, empty-state art, or concept assets only.
+
+When a visual is generated or edited, store the final bitmap in `public/` and reference it from `defineApplication()`. If the image appears in README markdown, include useful alt text.
+
+## Application Metadata
+
+Update `src/application-config.ts` with marketplace metadata when publishing:
+
+```ts
+export default defineApplication({
+  universalIdentifier: APPLICATION_UNIVERSAL_IDENTIFIER,
+  displayName: APP_DISPLAY_NAME,
+  description: APP_DESCRIPTION,
+  defaultRoleUniversalIdentifier: DEFAULT_ROLE_UNIVERSAL_IDENTIFIER,
+  author: 'Your Company',
+  category: 'Productivity',
+  logoUrl: 'public/logo.png',
+  screenshots: [
+    'public/screenshot-1.png',
+    'public/screenshot-2.png',
+  ],
+  websiteUrl: 'https://example.com',
+  termsUrl: 'https://example.com/terms',
+  emailSupport: 'support@example.com',
+  issueReportUrl: 'https://github.com/org/app/issues',
+});
+```
+
+Only set `aboutDescription` when the marketplace About tab should differ from the npm README. Otherwise keep one source of truth in `README.md`. The About tab renders markdown text only: images and raw HTML (badges, `<div>` blocks) are not rendered, so keep the marketplace-facing content in plain markdown.
+
+If the app requires a specific Twenty server version, set `engines.twenty` in `package.json`. If publishing to npm, add the `twenty-app` keyword.
+
+## Validation
+
+Before considering README and visuals done:
+
+```bash
+yarn twenty apply
+yarn twenty dev:build
+```
+
+Then check:
+
+- Every `logoUrl` and `screenshots` 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.
+- Screenshots are current, readable, and free of secrets or real personal data.
+- Public assets render where they are used by front components, logic functions, README, or marketplace metadata.
+
+If visual verification matters, run the app in a browser and capture fresh screenshots instead of relying on stale files.

packages/twenty-agent-skills/references/use-twenty-mcp/result-formatting.md

@@ -0,0 +1,186 @@
+# Retrieve Workspace Data
+
+## Overview
+
+Retrieve the Twenty records needed to answer the user's question, then present them as a useful answer, not as raw API output. Always translate technical fields, timestamps, IDs, and nested structures into readable summaries that help the user scan, compare, and act.
+
+## Retrieval Workflow
+
+Resolve the intended workspace before selecting a Twenty MCP server:
+
+- If the user names a workspace, host, MCP server, or URL, use only the matching Twenty MCP namespace or server.
+- If multiple Twenty MCP namespaces or configured servers are available and the intended workspace is ambiguous, ask one concise clarifying question before retrieving data.
+- If exactly one Twenty MCP namespace is available and the user did not specify a workspace, use it and mention which workspace or server was used when reporting results.
+- If a configured server exists but the matching MCP tools are not visible in the current thread, use the MCP setup troubleshooting workflow in `setup.md` instead of falling back to a different workspace.
+- Before querying workspace data, confirm the callable Twenty MCP namespace or server name corresponds to the intended workspace whenever there is any ambiguity.
+
+Use the selected connected Twenty MCP server when it is available:
+
+```text
+learn_tools -> execute_tool
+```
+
+- Discover object, field, filter, and sort names before querying.
+- Retrieve only answer, ordering, and disambiguation fields.
+- For "latest", "most recent", or "recent" requests, show the timestamp used for sorting.
+- Limit broad lists and state how many records are shown.
+- Ask one clarifying question only when tools cannot supply required context.
+- If no Twenty MCP tools are available, use the setup workflow in `setup.md`; do not invent workspace data.
+
+## Workspace Origin
+
+Record links need a workspace origin, such as `https://example.twenty.com` or `http://workspace.localhost:3001`.
+
+- If the user provides the workspace URL, use that origin after removing any trailing `/mcp`.
+- If the selected MCP server URL is visible, derive the origin from it by removing the trailing `/mcp`.
+- If the selected MCP server is configured locally but the URL is not in context, inspect that exact server configuration before formatting linked records.
+- If the origin is still unknown, do not invent a hostname. Explain that direct record links need the workspace URL.
+
+## Response Shape
+
+Start with the answer or count, then show the records in the clearest compact shape:
+
+- For one record, use a short labelled summary.
+- For two to ten comparable records, use a Markdown table.
+- For larger sets, show the most relevant rows first, mention the total, and offer the next useful filter or page only when needed.
+- For nested records, summarize the important nested values instead of dumping JSON.
+- When comparing records across workspaces, prefer one combined table with a `Workspace` column if it improves scanning. Use separate sections only when each workspace needs different columns.
+
+Use English labels and prose. Keep user-provided names, record values, emails, URLs, and proper nouns unchanged.
+
+## Record Links
+
+Link records back to their original Twenty context whenever the workspace origin and record identity are known.
+
+- Build record links with the Twenty show-page path: `/object/:objectNameSingular/:objectRecordId`.
+- For absolute links, combine the workspace origin with that path: `{workspaceOrigin}/object/{objectNameSingular}/{recordId}`.
+- Preserve the workspace scheme and port for local workspaces, for example `http://workspace.localhost:3001/object/person/record-id`.
+- Use `recordReferences` from MCP responses when available to get `objectNameSingular`, `recordId`, and `displayName`.
+- If `recordReferences` is missing, use the record's `id` and the object name from the tool that returned it.
+- If `recordReferences` and workspace origin are both available, the first record-name column or record heading MUST link the display name. Do not output unlinked record names in that case.
+- Prefer linking the record display name in tables and summaries instead of adding a raw ID column.
+- When showing records from multiple workspaces, generate links with each record's own workspace origin.
+- If the workspace origin is unknown, do not invent a hostname. Add a compact `Record` column with the object name and record ID, or say that direct links need the workspace URL.
+
+## Visual Identifiers
+
+Add a small visual identifier next to records when it improves scanning and the source data provides one.
+
+- Twenty AI chat currently renders Markdown with `react-markdown` and `remark-gfm`, without raw HTML rendering. Do not rely on HTML such as `<img width="16" height="16">`.
+- Use standard Markdown image syntax only: `![alt](image-url)`.
+- The current Twenty AI chat image CSS preserves intrinsic image size with `height: auto` and only caps `max-width`. Do not place full-size photos or large avatars in tables unless the image URL is already a small thumbnail.
+- Prefer the record's own `avatarUrl`, logo, or image field when present and non-empty.
+- For People, show the person's avatar or profile image only when the URL is known to be a small thumbnail. If there is no suitable image, keep the linked name and do not generate fake headshots.
+- For Companies, Workspaces, domains, or records mainly identified by an email/domain, prefer a small favicon or logo when the record provides a safe public website, domain, or avatar URL.
+- Derive a domain from `emails.primaryEmail`, `website`, `domainName`, or equivalent fields only for display or favicon lookup; never expose private internal domains as external image requests.
+- If image sizing is not reliable, use a text `Domain`, `Company`, or `Source` column instead of an image.
+- Always include readable text next to the image. Never make an image the only record label.
+- If no trustworthy image or favicon source is available, omit the image instead of showing a broken placeholder.
+- Avoid adding images to very large result sets unless the user asks for a visual scan.
+- Avoid stacking multiple visual tokens before a record name, such as favicon plus emoji plus linked text. Redundant icons make table alignment harder to scan.
+
+## Dates And Times
+
+Never expose ISO/RFC3339 timestamps as the main date display.
+
+- Parse common technical formats such as `2026-05-05T09:43:18.123Z`, `2026-05-05T09:43:18+02:00`, Unix seconds, and Unix milliseconds.
+- Convert instants with `Z` or an explicit offset to the user's timezone when known. If timezone is unknown, keep the source timezone or ask only when it changes the meaning.
+- Preserve date-only values as dates. Do not shift date-only values across timezones.
+- Display absolute dates. Use relative words such as "today", "yesterday", or "last week" only as a supplement when helpful.
+- Include the year unless it is truly redundant in a small same-year table.
+- Show seconds and milliseconds only when they matter for debugging, audit logs, or ordering events with near-identical times.
+
+Examples:
+
+- Timestamp: `2026-05-05T09:43:18.123Z` -> `May 5, 2026, 11:43 AM`
+- Date-only value: `2026-05-05` -> `May 5, 2026`
+
+If the exact raw timestamp is relevant, put it after the readable value:
+
+```text
+Created: May 5, 2026, 11:43 AM (raw: 2026-05-05T09:43:18.123Z)
+```
+
+## Field Labels
+
+Convert raw field names into user-facing labels:
+
+- `createdAt` -> `Created`
+- `updatedAt` -> `Last updated`
+- `deletedAt` -> `Deleted`
+- `createdBy` -> `Created by`
+- `workspaceMemberId` -> `Workspace member`
+- `opportunityStage` -> `Opportunity stage`
+
+Prefer the label users see in Twenty when it is available from metadata. Otherwise, split camelCase, snake_case, and kebab-case into normal words.
+
+## Value Formatting
+
+Format values by meaning:
+
+- Empty or null: `Not set`, or omit if the field is irrelevant.
+- Booleans: `Yes` / `No`.
+- Money: include currency and grouping, for example `EUR 12,450` or `USD 12,450` based on the record currency.
+- Percentages: use `%`, round only enough to stay meaningful.
+- URLs and emails: make them clickable Markdown links when useful.
+- IDs and UUIDs: hide by default unless the user asks for identifiers, deduplication, debugging, or exact references.
+- Arrays: show the count and the most important names, not the full serialized array.
+
+## Record Ordering
+
+When the user asks for "latest", "recent", or "last records":
+
+- State which date field was used when it is not obvious, for example `sorted by Last updated`.
+- Prefer `updatedAt` for "recent activity" and `createdAt` for "newest records" unless the user's wording or object semantics points to another date.
+- Display the chosen date column in readable form.
+- If multiple records share the same date, keep a deterministic secondary order such as name or ID.
+
+## Table Alignment
+
+Make tables easy to scan before making them visually decorative.
+
+- Use Markdown alignment markers intentionally: text columns left-aligned (`:---`), numeric money/count columns right-aligned (`---:`), and short status columns centered only when that actually improves scanning (`:---:`).
+- Keep record names on a stable left edge. If rows have favicons, avatars, or logos, prefer a dedicated narrow `Icon`, `Logo`, or `Avatar` column followed by a linked record-name column.
+- If the table is compact and the image is known to be consistently small, it is acceptable to put `![alt](url) [Name](record-url)` in one cell. Do not also add emoji or extra symbols before the name.
+- Keep fixed-format fields such as `Created`, `Updated`, `Amount`, and `Source` to the right of variable-width fields such as `Name`, `Company`, `Person`, and `Domain`.
+- Use a consistent date format within a table so rows line up visually, for example `May 5, 2026, 11:43 AM` or `May 5, 11:43`.
+- Prefer natural links over extra link columns: link the record name to Twenty, and link the domain or email only when that external destination is useful.
+- Avoid raw ID columns in normal user-facing tables. IDs are long, visually dominant, and destroy alignment unless the user asks for them.
+
+## Markdown Patterns
+
+Use a compact table for comparable records:
+
+```markdown
+I found 5 recent opportunities, sorted by last updated date.
+
+| Logo | Name | Stage | Amount | Last updated |
+| :---: | :--- | :--- | ---: | :--- |
+| ![Acme icon](https://example.com/favicon.ico) | [Acme renewal](https://example.twenty.com/object/opportunity/record-id-1) | Negotiation | EUR 12,450 | May 5, 2026, 11:43 AM |
+| ![Globex icon](https://globex.example/favicon.ico) | [Globex expansion](https://example.twenty.com/object/opportunity/record-id-2) | Discovery | EUR 8,000 | May 4, 2026, 4:10 PM |
+```
+
+For recent companies with `recordReferences`, link the company name:
+
+```markdown
+I found 5 recent companies, sorted by Created.
+
+| Company | Domain | Created |
+| :--- | :--- | :--- |
+| [Acme](https://workspace.example/object/company/00000000-0000-0000-0000-000000000001) | [acme.example](https://acme.example) | May 5, 2026, 11:43 AM |
+```
+
+Use a labelled block for one important record:
+
+```markdown
+**[Acme renewal](https://example.twenty.com/object/opportunity/record-id-1)**
+
+- Stage: Negotiation
+- Amount: EUR 12,450
+- Next action: Not set
+- Last updated: May 5, 2026, 11:43 AM
+```
+
+## Raw Data Exceptions
+
+Show raw JSON, raw timestamps, internal IDs, or full nested objects only when the user asks for debugging, export, exact API payloads, schema inspection, or reproducible commands. Even then, put a readable summary before the raw block.

packages/twenty-agent-skills/references/use-twenty-mcp/setup.md

@@ -0,0 +1,158 @@
+# Set Up Twenty MCP
+
+## Overview
+
+Use this reference to configure a workspace-specific Twenty MCP endpoint. The skill must not assume a fixed workspace domain; collect the user's workspace URL first, normalize it to an MCP URL, then configure and authenticate the MCP client of the agent in use.
+
+Self-hosted instances are first-class targets. Any Twenty workspace works: managed cloud, self-hosted on a custom domain, or a local instance over HTTP. Never require a `twenty.com` workspace.
+
+## Required User Input
+
+Ask for the workspace URL or host if it is missing. Do not invent or reuse a private default domain.
+
+Accept any of these forms:
+
+```text
+myworkspace.twenty.com
+myworkspace.customdomain.com
+myworkspace.localhost:3001
+https://myworkspace.twenty.com
+https://myworkspace.customdomain.com/mcp
+http://myworkspace.localhost:3001/mcp
+```
+
+Optional inputs:
+
+- MCP server name. Default to a workspace-derived name in the form `twenty-<host-without-tld>`, for example `acme.example.com` becomes `twenty-acme-example`.
+- Whether to force CLI OAuth login immediately. Default to no when the agent opens OAuth on its own after the MCP server is added. Only force login if the automatic OAuth window does not appear.
+
+## URL Normalization
+
+Normalize workspace input as follows:
+
+- If the input already starts with `http://` or `https://`, preserve that scheme.
+- If the input has no scheme and is `localhost`, `127.x.x.x`, `[::1]`, `*.localhost`, or `*.localhost:<port>`, use `http://`.
+- If the input has no scheme and is any other host, use `https://`.
+- Strip any trailing `/` before looking at the path, so `https://acme.example.com/` and `https://acme.example.com/mcp/` normalize the same as their unslashed forms.
+- If the final URL does not end with `/mcp`, append `/mcp`.
+
+Examples:
+
+```text
+myworkspace.twenty.com       -> https://myworkspace.twenty.com/mcp       name: twenty-myworkspace
+acme.example.com             -> https://acme.example.com/mcp             name: twenty-acme-example
+myworkspace.customdomain.com -> https://myworkspace.customdomain.com/mcp name: twenty-myworkspace-customdomain
+myworkspace.localhost:3001   -> http://myworkspace.localhost:3001/mcp   name: twenty-myworkspace-localhost-3001
+https://acme.example.com/    -> https://acme.example.com/mcp             name: twenty-acme-example
+https://acme.example.com/mcp/ -> https://acme.example.com/mcp            name: twenty-acme-example
+```
+
+A trailing slash that survives normalization produces `//mcp` or `/mcp//mcp`, neither of which is the registered endpoint.
+
+## Setup Per Agent
+
+The Twenty MCP server uses streamable HTTP transport with OAuth authentication. Configure it with the agent the user is actually running.
+
+### Codex
+
+```bash
+codex mcp add twenty-myworkspace --url https://myworkspace.twenty.com/mcp
+codex mcp login twenty-myworkspace
+```
+
+For a local instance:
+
+```bash
+codex mcp add twenty-local --url http://myworkspace.localhost:3001/mcp
+codex mcp login twenty-local
+```
+
+OAuth guards specific to this client:
+
+- Do not pass `--login` to `codex mcp add`. It is deprecated.
+- Codex can open OAuth on its own when it sees the new MCP server. Run `codex mcp login <server-name>` only if that window does not appear.
+- Do not manually run `open <authorization-url>` for an OAuth URL printed by `codex mcp add` unless the user confirms no browser tab opened. Opening the same authorization URL twice creates two callback tabs with the same `state` and different one-time `code` values.
+
+The Twenty marketplace plugin for this client bundles a `setup-mcp.sh` helper that automates URL normalization, server naming, and this add-then-login sequence.
+
+### Claude Code
+
+```bash
+claude mcp add --transport http twenty-myworkspace https://myworkspace.twenty.com/mcp
+```
+
+For a local instance:
+
+```bash
+claude mcp add --transport http twenty-local http://myworkspace.localhost:3001/mcp
+```
+
+Claude Code prompts for OAuth when the server is first used. `/mcp` inside a session shows connection and authentication status, and re-runs the OAuth flow on demand.
+
+### Cursor
+
+Add the server to `.cursor/mcp.json` in the project, or `~/.cursor/mcp.json` for every project:
+
+```json
+{
+  "mcpServers": {
+    "twenty-myworkspace": {
+      "url": "https://myworkspace.twenty.com/mcp"
+    }
+  }
+}
+```
+
+Cursor opens the OAuth flow when the server is enabled in its MCP settings.
+
+### Other MCP Clients
+
+Any client that supports streamable HTTP MCP servers with OAuth works. Configure a server entry pointing at the normalized MCP URL:
+
+```json
+{
+  "mcpServers": {
+    "twenty-myworkspace": {
+      "url": "https://myworkspace.twenty.com/mcp"
+    }
+  }
+}
+```
+
+If the client cannot do OAuth, configure bearer headers in the user's private MCP client config only, never in shared or committed files.
+
+## Validation
+
+After setup, verify the server is available with the client's own inspection command (`codex mcp get <server-name>`, `claude mcp list`, or the equivalent), or by listing available tools in a fresh session.
+
+When connected, use the Twenty MCP discovery flow:
+
+```text
+learn_tools -> execute_tool
+```
+
+## Troubleshooting
+
+### Debugging Workflow
+
+Use this workflow when the user reports missing tools, unexpected workspace data, authentication failures, or suspects the agent queried the wrong Twenty workspace.
+
+1. Identify the intended workspace URL or host from the user's request, using Required User Input when it is missing.
+2. Normalize the intended workspace to its MCP URL with the URL Normalization rules above.
+3. Inspect the configured Twenty MCP servers and compare their URLs to the intended normalized URL (`codex mcp list`, `claude mcp list`, or the client's MCP config file).
+4. If no configured server points at the intended MCP URL, configure one with a workspace-specific name using the per-agent setup above.
+5. If the server exists but authentication fails, or MCP startup reports `Auth required`, run the client's OAuth login for that exact server.
+6. If the configured server is correct and authenticated but its tools are not visible in the current session, explain that the session may have loaded tools before the server was added or authenticated. Ask the user to reload the agent or start a new session so it picks up the updated MCP config.
+7. Before querying workspace data, confirm the callable Twenty MCP namespace or tool name corresponds to the intended server. If only a different Twenty server is callable, do not use it as a fallback unless the user explicitly asks.
+8. When reporting results, state which workspace URL or MCP server was used if there was any ambiguity.
+
+### Common Failure Modes
+
+- If OAuth fails for a self-hosted workspace, check that `SERVER_URL` matches the public workspace origin. OAuth metadata and MCP URLs derive from that value.
+- If a local workspace fails over HTTPS, use `http://` explicitly per the localhost normalization rule.
+- If the server name already exists, replace that entry with the new URL, or pick a different name to keep several workspaces side by side.
+
+### Safety Rules
+
+- Do not put API keys in skill files. Prefer OAuth login. If an MCP client does not support OAuth, configure bearer headers only in the user's private MCP client config.
+- Do not inspect or manually extract OAuth tokens as a workaround.