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

packages/twenty-docs/l/es/developers/extend/apps/config/application.mdx

@@ -0,0 +1,124 @@
+---
+title: Configuración de la aplicación
+description: Declara la identidad de tu aplicación, el rol predeterminado, las variables y los metadatos del marketplace con defineApplication.
+icon: rocket
+---
+
+Cada aplicación debe tener exactamente una llamada a `defineApplication`. Declara:
+
+* **Identidad** — identificador universal, nombre para mostrar, descripción.
+* **Permisos** — bajo qué rol se ejecutan sus funciones de lógica y componentes de frontend.
+* **Variables** *(opcionales)* — pares clave–valor expuestos a tu código como variables de entorno.
+* **Hooks de preinstalación / posinstalación / desinstalación** *(opcionales)* — consulta [Funciones de lógica](/l/es/developers/extend/apps/logic/logic-functions).
+
+```ts src/application-config.ts
+import { defineApplication } from 'twenty-sdk/define';
+
+export default defineApplication({
+  universalIdentifier: '39783023-bcac-41e3-b0d2-ff1944d8465d',
+  displayName: 'My Twenty App',
+  description: 'My first Twenty app',
+  applicationVariables: {
+    DEFAULT_RECIPIENT_NAME: {
+      universalIdentifier: '19e94e59-d4fe-4251-8981-b96d0a9f74de',
+      description: 'Default recipient name for postcards',
+      value: 'Jane Doe',
+      isSecret: false,
+    },
+  },
+});
+```
+
+Notas:
+
+* Los campos `universalIdentifier` son identificadores deterministas que te pertenecen. Genéralos una vez y mantenlos estables entre sincronizaciones.
+* `applicationVariables` se convierten en variables de entorno para tus funciones y componentes de frontend. En las funciones lógicas (del lado del servidor), están disponibles como `process.env.VARIABLE_NAME`. En los componentes de frontend, usa `getApplicationVariable('VARIABLE_NAME')` de `twenty-sdk/front-component`. Las variables marcadas con `isSecret: true` solo se inyectan en las funciones lógicas. Los componentes de frontend solo reciben variables no secretas.
+* El rol predeterminado se detecta automáticamente a partir del archivo de rol marcado con [`defineApplicationRole()`](/l/es/developers/extend/apps/config/roles); no necesitas hacer referencia a él desde `defineApplication()`.
+* Las funciones de preinstalación, posinstalación y desinstalación se detectan automáticamente durante la compilación del manifiesto; no necesitas referenciarlas en `defineApplication()`.
+* Pasar `defaultRoleUniversalIdentifier` explícitamente sigue siendo compatible por motivos de retrocompatibilidad, pero está en desuso en favor de `defineApplicationRole()`.
+* `serverVariables` son configuraciones y secretos con ámbito de instancia (por ejemplo, claves de API). A diferencia de `applicationVariables`, no declaran ningún valor en el manifiesto: el operador del espacio de trabajo los completa desde la configuración de la aplicación, y se inyectan en las funciones lógicas solo una vez que se han establecido.
+* Ambos tipos de variable aceptan `isDeprecated: true`. Úsala para retirar una variable en lugar de eliminarla: mantener la clave declarada conserva el valor almacenado (eliminarla destruye el valor que el operador introdujo), y la variable sigue siendo inyectada, por lo que tu código puede recurrir a ella — `process.env.NEW_API_KEY ?? process.env.API_KEY`. Una variable obsoleta desaparece de la configuración de la app una vez que no tiene ningún valor y nunca cuenta para la verificación de configuración de la app, por lo que `isDeprecated` tiene prioridad sobre `isRequired`.
+* Para mostrar una interfaz de configuración personalizada dentro de la pestaña **Settings** de la aplicación (en lugar de la sección predeterminada de configuración de variables), declara un componente de frontend con [`defineSettingsFrontComponent()`](/l/es/developers/extend/apps/layout/front-components#custom-settings-component) en su propio archivo. Solo se permite uno por aplicación. Las secciones gestionadas por el sistema (actualización automática, App URL, conexiones) siempre permanecen visibles.
+
+## Tipos de variables
+
+Tanto `applicationVariables` como `serverVariables` aceptan un `type` opcional (y, para `SELECT` / `MULTI_SELECT`, una lista de `options`). Tipos admitidos: `TEXT` (predeterminado), `BOOLEAN`, `NUMBER`, `NUMERIC`, `DATE`, `DATE_TIME`, `SELECT`, `MULTI_SELECT`, `ARRAY`, `RAW_JSON`, `RICH_TEXT`.
+
+```ts src/application-config.ts
+import { defineApplication, FieldType } from 'twenty-sdk/define';
+
+export default defineApplication({
+  // ...identity, role...
+  applicationVariables: {
+    MAX_POSTCARDS: {
+      universalIdentifier: '5f4497e4-9030-4085-85eb-2c48b8d53713',
+      description: 'Maximum postcards per batch',
+      type: FieldType.NUMBER,
+      value: 10,
+    },
+    DEFAULT_REGION: {
+      universalIdentifier: '76c5c321-b6b6-46eb-b4fc-f9f04bb04227',
+      description: 'Default shipping region',
+      type: FieldType.SELECT,
+      options: [
+        { label: 'Europe', value: 'eu' },
+        { label: 'United States', value: 'us' },
+      ],
+      value: 'eu',
+    },
+  },
+});
+```
+
+El `type` solo afecta a la **presentación y validación**: selecciona la entrada correspondiente en la interfaz de configuración del espacio de trabajo (un interruptor, campo numérico, lista desplegable, selector de fecha, editor JSON, …) y permite que la compilación valide tu configuración (por ejemplo, `SELECT` / `MULTI_SELECT` deben declarar `options` no vacías). **No** cambia cómo el valor llega a tu código.
+
+Los valores **siempre se inyectan como cadenas**; esto es inherente a las variables de entorno (`process.env.*` solo admite cadenas). Cuando se ejecuta tu función lógica, el ejecutor serializa cada valor según su `type` declarado al construir `process.env`, por lo que el formato de cadena es coherente independientemente de cómo se haya establecido el valor (valor predeterminado del manifiesto, interfaz de configuración o una versión anterior):
+
+| Tipo                                  | Cadena de `process.env`                        |
+| ------------------------------------- | ---------------------------------------------- |
+| `TEXT`, `SELECT`, `DATE`, `DATE_TIME` | el valor sin procesar (`"eu"`, `"2026-01-01"`) |
+| `BOOLEAN`                             | `"true"` / `"false"`                           |
+| `NUMBER`, `NUMERIC`                   | cadena decimal (`"10"`, `"2.5"`)               |
+| `MULTI_SELECT`, `ARRAY`               | Array JSON (`'["email","postcard"]'`)          |
+| `RAW_JSON`, `RICH_TEXT`               | Objeto JSON (`'{"retries":3}'`)                |
+
+Analiza la cadena para volver al tipo que esperas:
+
+```ts
+const maxCards = Number(process.env.MAX_POSTCARDS); // "10" -> 10
+const enabled = process.env.ENABLE_TRACKING === 'true'; // "true" -> true
+const channels = JSON.parse(process.env.ENABLED_CHANNELS ?? '[]'); // '["email"]' -> ["email"]
+const config = JSON.parse(process.env.PROVIDER_CONFIG ?? '{}'); // '{"retries":3}' -> { retries: 3 }
+```
+
+Lo mismo se aplica a los componentes de interfaz que leen valores mediante `getApplicationVariable('VARIABLE_NAME')`: el valor devuelto es una cadena; analízalo según sea necesario.
+
+## Rol de función predeterminado
+
+El rol declarado con [`defineApplicationRole()`](/l/es/developers/extend/apps/config/roles) controla a qué pueden acceder las funciones de lógica y los componentes de interfaz de la aplicación:
+
+* Los tokens en tiempo de ejecución inyectados en tus funciones de lógica se derivan de este rol. Una llamada que actúa como una persona se limita aún más a lo que esa persona puede hacer, por lo que nunca puede superar ninguno de los dos. Consulta [Qué acceso usa una llamada](/l/es/developers/extend/apps/logic/logic-functions#whose-access-a-call-uses).
+* El cliente de API tipado está restringido a los permisos otorgados a ese rol.
+* Sigue el principio de mínimo privilegio: declara solo los permisos que necesitan tus funciones.
+
+Cuando generas una nueva aplicación, la CLI crea un archivo de rol inicial en `src/roles/default-role.ts`. Consulta [Roles y permisos](/l/es/developers/extend/apps/config/roles) para obtener la referencia completa.
+
+## Metadatos del Marketplace
+
+Si planeas [publicar tu aplicación](/l/es/developers/extend/apps/operations/publishing), estos campos opcionales controlan cómo aparece en el marketplace:
+
+| Campo              | Descripción                                                                                                                            |
+| ------------------ | -------------------------------------------------------------------------------------------------------------------------------------- |
+| `author`           | Nombre del autor o de la empresa                                                                                                       |
+| `category`         | Categoría de la aplicación para el filtrado en el marketplace                                                                          |
+| `logo`             | Ruta al logotipo de tu aplicación incluido en `public/` (p. ej., `public/logo.png`)                                                    |
+| `galleryImages`    | Arreglo de rutas de imágenes de galería incluidas en `public/` (p. ej., `public/screenshot-1.png`)                                     |
+| `aboutDescription` | Descripción en Markdown más extensa para la pestaña "Acerca de". Si se omite, el marketplace utiliza el `README.md` del paquete en npm |
+| `websiteUrl`       | Enlace a tu sitio web                                                                                                                  |
+| `termsUrl`         | Enlace a los términos del servicio                                                                                                     |
+| `emailSupport`     | Dirección de correo electrónico de soporte                                                                                             |
+| `issueReportUrl`   | Enlace al rastreador de incidencias                                                                                                    |
+
+<Note>
+`logoUrl` y `screenshots` son alias obsoletos de `logo` y `galleryImages`. Las URL absolutas externas (`http://` o `https://`) no son compatibles para estos campos: se descartan con una advertencia en tiempo de compilación. En su lugar, incluye las imágenes en la carpeta `public/` de tu aplicación.
+</Note>

packages/twenty-docs/l/es/developers/extend/apps/config/install-hooks.mdx

@@ -0,0 +1,188 @@
+---
+title: Hooks de instalación
+description: "Ejecuta lógica durante el ciclo de vida de instalación, actualización o desinstalación: siembra datos, realiza copias de seguridad de registros, valida la actualización, limpia recursos externos."
+icon: wrench
+---
+
+Los hooks de instalación son funciones de lógica especiales que se ejecutan durante el ciclo de vida de la instalación, actualización o desinstalación. Comparten el mismo tiempo de ejecución del controlador que las [logic functions](/l/es/developers/extend/apps/logic/logic-functions) normales, pero se declaran con sus propias funciones de definición y están fuera del modelo de desencadenadores normal (HTTP, cron, eventos de base de datos). Los hooks de instalación reciben un `InstallPayload` (`{ previousVersion?: string; newVersion: string }` — `previousVersion` es `undefined` en una instalación nueva); el hook de desinstalación recibe un `UninstallPayload` (`{ version?: string }` — la versión que se está eliminando).
+
+Cada aplicación puede definir **como máximo un** hook de cada tipo (preinstalación, postinstalación, desinstalación). La compilación del manifiesto genera un error si se detecta más de uno de cualquier tipo.
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│ install flow                                                │
+│                                                             │
+│   upload package → [pre-install] → metadata migration →     │
+│   generate SDK → [post-install]                             │
+│                                                             │
+│                  old schema visible    new schema visible   │
+└─────────────────────────────────────────────────────────────┘
+```
+
+## De un vistazo
+
+|                  | `definePreInstallLogicFunction`                                                                                                    | `definePostInstallLogicFunction`                                                                                                                           |
+| ---------------- | ---------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Ejecuciones      | Antes de la migración de metadatos — el esquema y los datos **anteriores** siguen intactos                                         | Después de la migración y la generación del SDK — el esquema **nuevo** está en su lugar                                                                    |
+| Ejecución        | Siempre síncrona; bloquea la instalación                                                                                           | Asíncrona de forma predeterminada (en cola, 3 reintentos); modo síncrono opcional mediante `shouldRunSynchronously: true`                                  |
+| En caso de fallo | La instalación se **aborta** antes de cualquier cambio de esquema                                                                  | Asíncrono: se vuelve a intentar hasta 3 veces. Síncrono: quien realiza la llamada recibe `POST_INSTALL_ERROR` (los cambios de esquema **no** se revierten) |
+| Uso típico       | Hacer copia de seguridad o corregir datos que una migración perdería; rechazar una actualización arriesgada lanzando una excepción | Sembrar datos predeterminados, configurar el espacio de trabajo, registrar recursos externos                                                               |
+
+**Regla general:** usa post-install de forma predeterminada. Recurra a la pre-instalación solo cuando la propia migración sea destructiva y necesite interceptar el estado anterior antes de que desaparezca.
+
+| Quiere...                                                                                               | Usar                                                                      |
+| ------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------- |
+| Sembrar datos, configurar el espacio de trabajo, registrar recursos externos                            | `post-install`                                                            |
+| Trabajo de larga duración que no debería bloquear la respuesta de instalación                           | `post-install` (modo asíncrono predeterminado, con reintentos del worker) |
+| Configuración rápida de la que el cliente depende inmediatamente después de que finaliza la instalación | `post-install` con `shouldRunSynchronously: true`                         |
+| Leer o hacer copia de seguridad de datos que la próxima migración perdería                              | `pre-install`                                                             |
+| Rechazar una actualización que corrompería datos existentes                                             | `pre-install` (lanzar desde el controlador)                               |
+| Reconciliación en cada actualización                                                                    | Cualquiera de los hooks con `shouldRunOnVersionUpgrade: true`             |
+
+## Comportamiento compartido por ambos hooks
+
+* La configuración es una configuración de `defineLogicFunction` menos los ajustes de disparador, más `shouldRunOnVersionUpgrade`.
+* **Cuándo se ejecuta**: solo en instalaciones nuevas, de forma predeterminada. Configura `shouldRunOnVersionUpgrade: true` para que también se ejecute en las actualizaciones. Usa `previousVersion` / `newVersion` para ramificar según la ruta de actualización.
+* **La idempotencia es importante**: el post-install asíncrono puede reintentarse y cualquiera de los hooks se vuelve a ejecutar en las actualizaciones cuando `shouldRunOnVersionUpgrade` está activado.
+* El entorno habitual de las logic functions (`APPLICATION_ID`, `APP_ACCESS_TOKEN`, `API_URL`) se inyecta, por lo que puedes llamar a la API de Twenty con el token de tu app.
+* El hook se adjunta automáticamente al manifiesto de la aplicación en tiempo de compilación (`preInstallLogicFunction` / `postInstallLogicFunction`) — no hay nada que referenciar en [`defineApplication()`](/l/es/developers/extend/apps/config/application).
+* El `timeoutSeconds` predeterminado es 300 para permitir tareas de configuración más largas como la siembra de datos.
+* **No se ejecuta en modo de desarrollo**: `yarn twenty dev` omite el flujo de instalación y sincroniza los archivos directamente, por lo que los hooks nunca se ejecutan ahí. En su lugar, dispáralos manualmente:
+
+```bash filename="Terminal"
+yarn twenty dev:function:exec --postInstall
+yarn twenty dev:function:exec --preInstall
+```
+
+<AccordionGroup>
+<Accordion title="definePostInstallLogicFunction" description="Se ejecuta después de que se aplique la migración de metadatos del espacio de trabajo">
+
+Se ejecuta una vez que tu app ha terminado de instalarse: metadatos sincronizados, cliente SDK generado, nuevo esquema disponible para consulta. Ejemplo — sembrar un registro predeterminado en instalaciones nuevas:
+
+```ts src/logic-functions/post-install.ts
+import { definePostInstallLogicFunction, type InstallPayload } from 'twenty-sdk/define';
+import { CoreApiClient } from 'twenty-client-sdk/core';
+
+const handler = async ({ previousVersion }: InstallPayload): Promise<void> => {
+  if (previousVersion) return; // fresh installs only
+
+  const client = new CoreApiClient();
+  await client.mutation({
+    createPostCard: {
+      __args: { data: { name: 'Welcome to Postcard', content: 'Your first card!' } },
+      id: true,
+    },
+  });
+};
+
+export default definePostInstallLogicFunction({
+  universalIdentifier: 'f7a2b9c1-3d4e-5678-abcd-ef9876543210',
+  name: 'post-install',
+  description: 'Seeds a welcome post card after install.',
+  timeoutSeconds: 300,
+  shouldRunOnVersionUpgrade: false,
+  shouldRunSynchronously: false,
+  handler,
+});
+```
+
+El flag `shouldRunSynchronously` controla el modelo de ejecución:
+
+* `false` *(predeterminado)* — encolado en la cola de mensajes (`retryLimit: 3`) y ejecutado por un worker. La respuesta de instalación se devuelve tan pronto como el trabajo se pone en la cola. **Usar para trabajo de larga duración** — siembra de grandes conjuntos de datos, APIs de terceros lentas.
+* `true` — se ejecuta en línea durante el flujo de instalación. La solicitud de instalación se bloquea hasta que el handler finaliza; un error lanzado aparece como `POST_INSTALL_ERROR` para quien realiza la llamada (sin reintentos). **Usar para trabajo rápido que debe completarse antes de la respuesta.** La migración ya se ha aplicado en este punto, por lo que un fallo no revierte los cambios de esquema — solo expone el error.
+
+</Accordion>
+<Accordion title="definePreInstallLogicFunction" description="Se ejecuta antes de que se aplique la migración de metadatos del espacio de trabajo">
+
+Se ejecuta antes de la migración de metadatos, contra el esquema **anterior** — el lugar adecuado para hacer una copia de seguridad de los datos que una migración perdería o para rechazar una actualización arriesgada. Antes de ejecutarse, el servidor realiza una "sincronización simplificada" puramente aditiva que registra solo la función de pre-instalación de la versión nueva; todo lo demás — los objetos, campos y datos de la versión anterior — permanece sin cambios cuando se ejecuta tu handler.
+
+La pre-instalación siempre es **síncrona** y bloquea la instalación. Si el handler lanza una excepción, la instalación se aborta antes de cualquier cambio de esquema — el espacio de trabajo permanece en la versión anterior en un estado consistente. Esto es intencional: la pre-instalación es su última oportunidad para rechazar una actualización arriesgada.
+
+Ejemplo — copiar los valores de un campo heredado antes de que la migración lo elimine:
+
+```ts src/logic-functions/pre-install.ts
+import { definePreInstallLogicFunction, type InstallPayload } from 'twenty-sdk/define';
+import { CoreApiClient } from 'twenty-client-sdk/core';
+
+const handler = async ({ previousVersion, newVersion }: InstallPayload): Promise<void> => {
+  // Only the 1.x → 2.x upgrade drops the legacy `notes` field.
+  if (!previousVersion?.startsWith('1.') || !newVersion.startsWith('2.')) {
+    return;
+  }
+
+  const client = new CoreApiClient();
+  const { postCards } = await client.query({
+    postCards: {
+      __args: { filter: { notes: { isNot: null } } },
+      edges: { node: { id: true, notes: true } },
+    },
+  });
+
+  // Copy legacy `notes` into `description` before the migration drops the
+  // column. If this fails, the upgrade aborts and the workspace stays on v1.
+  for (const { node } of postCards.edges) {
+    await client.mutation({
+      updatePostCard: {
+        __args: { id: node.id, data: { description: node.notes } },
+        id: true,
+      },
+    });
+  }
+};
+
+export default definePreInstallLogicFunction({
+  universalIdentifier: 'a1b2c3d4-5678-90ab-cdef-1234567890ab',
+  name: 'pre-install',
+  description: 'Backs up legacy notes into description before the v2 migration.',
+  timeoutSeconds: 300,
+  shouldRunOnVersionUpgrade: true,
+  handler,
+});
+```
+
+</Accordion>
+</AccordionGroup>
+
+## Hook de desinstalación
+
+`defineUninstallLogicFunction` declara un hook que se ejecuta cuando un usuario desinstala tu aplicación. Se ejecuta **antes** de que se eliminen los metadatos, los datos y el código de la aplicación — una vez que se ejecuta la migración de eliminación ya no queda nada que ejecutar — por lo que tu controlador todavía puede consultar los objetos y registros de la aplicación. Úsalo para limpiar recursos externos: cancelar el aprovisionamiento de recursos de API, eliminar bots restantes, revocar webhooks.
+
+Notas:
+
+* El hook se ejecuta con el mejor esfuerzo posible: se ejecuta de forma sincrónica, pero si falla se registra el error y **nunca bloquea la desinstalación**; la limpieza no debe hacer que una aplicación sea imposible de eliminar.
+* Recibe `UninstallPayload` (`{ version?: string }` — la versión que se está eliminando).
+* **No** se ejecuta cuando se revierte una instalación nueva fallida: la aplicación nunca terminó de instalarse.
+* El hook no puede ejecutarse después de que la aplicación haya desaparecido, por lo que la limpieza externa que depende de datos de la aplicación (por ejemplo, IDs de bots almacenados en registros) debe realizarse aquí, no en una tarea programada externa.
+* Al igual que los hooks de instalación, **no se ejecuta en modo de desarrollo**; en su lugar, actívalo manualmente:
+
+```bash filename="Terminal"
+yarn twenty dev:function:exec --uninstall
+```
+
+```ts src/logic-functions/uninstall.ts
+import { defineUninstallLogicFunction, type UninstallPayload } from 'twenty-sdk/define';
+import { CoreApiClient } from 'twenty-client-sdk/core';
+
+const handler = async (_payload: UninstallPayload): Promise<void> => {
+  const client = new CoreApiClient();
+  const { meetingBots } = await client.query({
+    meetingBots: { edges: { node: { id: true, externalBotId: true } } },
+  });
+
+  // Delete the provider-side bots so nothing keeps recording after uninstall.
+  for (const { node } of meetingBots.edges) {
+    await fetch(`https://api.recorder.example/bots/${node.externalBotId}`, {
+      method: 'DELETE',
+      headers: { Authorization: `Bearer ${process.env.RECORDER_API_KEY}` },
+    });
+  }
+};
+
+export default defineUninstallLogicFunction({
+  universalIdentifier: 'b2c3d4e5-6789-01bc-def0-234567890abc',
+  name: 'uninstall',
+  description: 'Deletes remaining recorder bots when the app is uninstalled.',
+  timeoutSeconds: 300,
+  handler,
+});
+```

packages/twenty-docs/l/es/developers/extend/apps/config/overview.mdx

@@ -0,0 +1,56 @@
+---
+title: Resumen
+description: "Configura la propia app: su identidad, los permisos predeterminados y lo que se ejecuta en el momento de la instalación."
+icon: screwdriver-wrench
+---
+
+La **capa de configuración** de una app de Twenty es lo que describe la app *a la plataforma*: su identidad, los permisos que posee y el código que se ejecuta durante la instalación o la actualización. Estas declaraciones no añaden nuevas estructuras de datos ni comportamiento en tiempo de ejecución; le indican a Twenty *quién es la app* y *cómo configurarla*.
+
+```text
+┌────────────────────────────────────────────────────────┐
+│ Application — identity, default role, variables,       │
+│               marketplace metadata                     │
+│                                                        │
+│   ┌──────────────────────────────────────────────────┐ │
+│   │ Role — what the app's logic functions can read   │ │
+│   │ and write (referenced by Application)            │ │
+│   └──────────────────────────────────────────────────┘ │
+└────────────────────────────────────────────────────────┘
+                          │
+                          ▼  (at install / upgrade time)
+       ┌──────────────────────────────────┐
+       │ Pre-install hook                 │  before metadata migration
+       └──────────────────────────────────┘
+       ┌──────────────────────────────────┐
+       │ Post-install hook                │  after metadata migration
+       └──────────────────────────────────┘
+                          │
+                          ▼  (at uninstall time)
+       ┌──────────────────────────────────┐
+       │ Uninstall hook                   │  before app removal
+       └──────────────────────────────────┘
+```
+
+## En esta sección
+
+<CardGroup cols={2}>
+  <Card title="Configuración de la aplicación" icon="rocket" href="/l/es/developers/extend/apps/config/application">
+    `defineApplication`: identidad, rol predeterminado, variables y metadatos del marketplace.
+  </Card>
+  <Card title="Roles y permisos" icon="shield-halved" href="/l/es/developers/extend/apps/config/roles">
+    `defineRole`: declara qué pueden leer y escribir las funciones lógicas de tu app.
+  </Card>
+  <Card title="Hooks de instalación" icon="wrench" href="/l/es/developers/extend/apps/config/install-hooks">
+    `definePreInstallLogicFunction`, `definePostInstallLogicFunction` y `defineUninstallLogicFunction`: hacen copias de seguridad de los datos, cargan valores predeterminados, validan actualizaciones y limpian durante la desinstalación.
+  </Card>
+</CardGroup>
+
+## Cómo se relacionan las piezas
+
+* **Application** es el punto de entrada. Cada app tiene exactamente una llamada a `defineApplication()`, y apunta a un **Role** como su valor predeterminado.
+* El **Role** controla qué pueden leer y escribir las funciones lógicas y los componentes de interfaz de la app. Sigue el principio de privilegios mínimos: concede solo los permisos que tu código realmente necesita.
+* Los **hooks de instalación** se ejecutan durante la instalación o la actualización: el hook de preinstalación antes de la migración de metadatos (para poder rechazar una actualización arriesgada) y el hook de postinstalación después de la migración (para poder cargar datos predeterminados con el nuevo esquema). El hook de desinstalación se ejecuta justo antes de que se elimine la aplicación, por lo que puede limpiar recursos externos mientras los datos de la aplicación siguen siendo legibles.
+
+<Note>
+Los hooks de instalación comparten el entorno de ejecución de la [función lógica](/l/es/developers/extend/apps/logic/logic-functions): misma firma del handler, mismas variables de entorno, mismo cliente de API tipado, pero se declaran con sus propias funciones de definición y viven fuera del modelo de triggers habitual (HTTP, cron, eventos de base de datos).
+</Note>

packages/twenty-docs/l/es/developers/extend/apps/config/public-assets.mdx

@@ -0,0 +1,67 @@
+---
+title: Recursos públicos
+description: Distribuye archivos estáticos — imágenes, íconos, fuentes — junto con tu aplicación mediante la carpeta `public/`.
+icon: folder-open
+---
+
+La carpeta `public/` en la raíz de tu aplicación contiene archivos estáticos: imágenes, íconos, fuentes o cualquier otro recurso que tu aplicación necesite en tiempo de ejecución. Estos archivos se incluyen automáticamente en las compilaciones, se sincronizan durante el modo de desarrollo y se suben al servidor.
+
+Los archivos ubicados en `public/` son:
+
+* **De acceso público** — una vez sincronizados con el servidor, los recursos se sirven en una URL pública. No se necesita autenticación para acceder a ellos.
+* **Disponibles en componentes de frontend** — usa las URLs de los recursos para mostrar imágenes, íconos o cualquier medio dentro de tus componentes de React.
+* **Disponibles en funciones de lógica** — referencia las URLs de los recursos en correos electrónicos, respuestas de API o cualquier lógica del lado del servidor.
+* **Usados para metadatos del marketplace** — los campos `logo` y `galleryImages` en `defineApplication()` referencian archivos de esta carpeta (p. ej., `public/logo.png`). Estos se muestran en el marketplace cuando se publica tu aplicación. Las URL absolutas externas se omiten para estos campos; en su lugar, incluye las imágenes en `public/`. Cada imagen no debe superar los 10 MB.
+* **Sincronizados automáticamente en modo de desarrollo** — cuando agregas, actualizas o eliminas un archivo en `public/`, se sincroniza automáticamente con el servidor. No se necesita reiniciar.
+* **Incluidos en las compilaciones** — `yarn twenty dev:build` agrupa todos los recursos públicos en la salida de distribución.
+
+## Acceder a recursos públicos con `getPublicAssetUrl`
+
+Usa el helper `getPublicAssetUrl` de `twenty-sdk` para obtener la URL completa de un archivo en tu directorio `public/`. Funciona tanto en **funciones de lógica** como en **componentes de frontend**.
+
+**En una función de lógica:**
+
+```ts src/logic-functions/send-invoice.ts
+import { defineLogicFunction } from 'twenty-sdk/define';
+import { getPublicAssetUrl } from 'twenty-sdk/utils';
+
+const handler = async (): Promise<any> => {
+  const logoUrl = getPublicAssetUrl('logo.png');
+  const invoiceUrl = getPublicAssetUrl('templates/invoice.png');
+
+  // Fetch the file content (no auth required — public endpoint)
+  const response = await fetch(invoiceUrl);
+  const buffer = await response.arrayBuffer();
+
+  return { logoUrl, size: buffer.byteLength };
+};
+
+export default defineLogicFunction({
+  universalIdentifier: 'a1b2c3d4-...',
+  name: 'send-invoice',
+  description: 'Sends an invoice with the app logo',
+  timeoutSeconds: 10,
+  handler,
+});
+```
+
+**En un componente de frontend:**
+
+```tsx src/front-components/company-card.tsx
+import { defineFrontComponent } from 'twenty-sdk/define';
+import { getPublicAssetUrl } from 'twenty-sdk/utils';
+
+const CompanyCard = () => {
+  const logoUrl = getPublicAssetUrl('logo.png');
+
+  return <img src={logoUrl} alt="App logo" />;
+};
+
+export default defineFrontComponent({
+  universalIdentifier: '...',
+  name: 'company-card',
+  component: CompanyCard,
+});
+```
+
+El argumento `path` es relativo a la carpeta `public/` de tu aplicación. Tanto `getPublicAssetUrl('logo.png')` como `getPublicAssetUrl('public/logo.png')` resuelven a la misma URL — el prefijo `public/` se elimina automáticamente si está presente.

packages/twenty-docs/l/es/developers/extend/apps/config/roles.mdx

@@ -0,0 +1,201 @@
+---
+title: Roles y permisos
+description: Declara qué objetos y campos pueden leer y escribir las funciones de lógica y los componentes de interfaz de tu aplicación.
+icon: shield-halved
+---
+
+Un **rol** es un conjunto de permisos: qué objetos puede leer o escribir una aplicación, qué campos puede ver y qué capacidades a nivel de plataforma puede usar. Las funciones lógicas y los componentes de interfaz de cada aplicación heredan los permisos del rol marcado con `defineApplicationRole()` (consulta [El rol de función predeterminado](#the-default-function-role) más abajo).
+
+```ts src/roles/restricted-company-role.ts
+import {
+  defineRole,
+  STANDARD_OBJECT_UNIVERSAL_IDENTIFIERS,
+  SystemPermissionFlag,
+} from 'twenty-sdk/define';
+
+export default defineRole({
+  universalIdentifier: '2c80f640-2083-4803-bb49-003e38279de6',
+  label: 'My new role',
+  description: 'A role that can be used in your workspace',
+  canReadAllObjectRecords: false,
+  canUpdateAllObjectRecords: false,
+  canSoftDeleteAllObjectRecords: false,
+  canDestroyAllObjectRecords: false,
+  canUpdateAllSettings: false,
+  canBeAssignedToAgents: false,
+  canBeAssignedToUsers: false,
+  canBeAssignedToApiKeys: false,
+  objectPermissions: [
+    {
+      objectUniversalIdentifier:
+        STANDARD_OBJECT_UNIVERSAL_IDENTIFIERS.company.universalIdentifier,
+      canReadObjectRecords: true,
+      canUpdateObjectRecords: true,
+      canSoftDeleteObjectRecords: false,
+      canDestroyObjectRecords: false,
+    },
+  ],
+  fieldPermissions: [
+    {
+      objectUniversalIdentifier:
+        STANDARD_OBJECT_UNIVERSAL_IDENTIFIERS.company.universalIdentifier,
+      fieldUniversalIdentifier:
+        STANDARD_OBJECT_UNIVERSAL_IDENTIFIERS.company.fields.name
+          .universalIdentifier,
+      canReadFieldValue: false,
+      canUpdateFieldValue: false,
+    },
+  ],
+  permissionFlagUniversalIdentifiers: [SystemPermissionFlag.APPLICATIONS],
+});
+```
+
+## Seguridad a nivel de fila
+
+Los permisos de objetos y campos determinan *a qué objetos y campos* puede acceder o modificar un rol. **Los predicados de permisos a nivel de fila** van más allá y deciden *qué registros* puede ver y sobre los que puede actuar un rol; por ejemplo, un rol de autoservicio en el que cada usuario externo ve solo sus propios registros.
+
+Declara los predicados con `rowLevelPermissionPredicates` en el rol. Como el resto del manifiesto, cada predicado tiene su propio `universalIdentifier` y hace referencia a un objeto y a un campo mediante su `universalIdentifier`, a un `operand` y, de forma opcional, a un campo `workspaceMember` cuyo valor se inyecta en tiempo de consulta, de modo que puedas expresar: "la relación de propietario del registro **es** el miembro actual del espacio de trabajo":
+
+```ts src/roles/partner-role.ts
+import {
+  defineRole,
+  RowLevelPermissionPredicateOperand,
+  STANDARD_OBJECT_UNIVERSAL_IDENTIFIERS,
+} from 'twenty-sdk/define';
+
+import { ACCOUNT_OWNER_FIELD_UNIVERSAL_IDENTIFIER } from '../fields/account-owner.field';
+
+export default defineRole({
+  universalIdentifier: 'c3c1dc2e-1a08-4de5-abb7-2139b3d99343',
+  label: 'Partner',
+  description: 'External partner — sees only its own records',
+  canBeAssignedToUsers: true,
+  objectPermissions: [
+    {
+      objectUniversalIdentifier:
+        STANDARD_OBJECT_UNIVERSAL_IDENTIFIERS.company.universalIdentifier,
+      canReadObjectRecords: true,
+      canUpdateObjectRecords: true,
+    },
+  ],
+  rowLevelPermissionPredicates: [
+    {
+      universalIdentifier: 'd0f0c1a2-3b4c-4d5e-8f60-111111111111',
+      objectUniversalIdentifier:
+        STANDARD_OBJECT_UNIVERSAL_IDENTIFIERS.company.universalIdentifier,
+      fieldUniversalIdentifier: ACCOUNT_OWNER_FIELD_UNIVERSAL_IDENTIFIER,
+      operand: RowLevelPermissionPredicateOperand.IS,
+      workspaceMemberFieldUniversalIdentifier:
+        STANDARD_OBJECT_UNIVERSAL_IDENTIFIERS.workspaceMember.fields.id
+          .universalIdentifier,
+    },
+  ],
+});
+```
+
+Debido a que los predicados se envían en el manifiesto, se crean, actualizan y eliminan junto con el rol en cada instalación y actualización; no hay ningún paso posterior a la instalación independiente que mantener sincronizado.
+
+### Combinar predicados con grupos
+
+De forma predeterminada, los predicados de un rol se combinan con `AND`. Para combinar algunos de ellos con `OR` (o para anidar lógica), declara una entrada `rowLevelPermissionPredicateGroups` y haz que cada predicado apunte a ella mediante `predicateGroupUniversalIdentifier`. Este rol permite que un socio vea una Oportunidad de la que **es propietario** o de la que es el **punto de contacto**:
+
+```ts src/roles/partner-opportunities-role.ts
+import {
+  defineRole,
+  RowLevelPermissionPredicateGroupLogicalOperator,
+  RowLevelPermissionPredicateOperand,
+  STANDARD_OBJECT_UNIVERSAL_IDENTIFIERS,
+} from 'twenty-sdk/define';
+
+const OPPORTUNITY = STANDARD_OBJECT_UNIVERSAL_IDENTIFIERS.opportunity;
+const CURRENT_MEMBER =
+  STANDARD_OBJECT_UNIVERSAL_IDENTIFIERS.workspaceMember.fields.id
+    .universalIdentifier;
+
+export default defineRole({
+  universalIdentifier: 'b2a1c0d9-8e7f-4a6b-9c5d-222222222222',
+  label: 'Partner (opportunities)',
+  canBeAssignedToUsers: true,
+  objectPermissions: [
+    {
+      objectUniversalIdentifier: OPPORTUNITY.universalIdentifier,
+      canReadObjectRecords: true,
+    },
+  ],
+  rowLevelPermissionPredicateGroups: [
+    {
+      universalIdentifier: 'c3b2a1d0-9f8e-4b7a-8d6c-333333333333',
+      objectUniversalIdentifier: OPPORTUNITY.universalIdentifier,
+      logicalOperator: RowLevelPermissionPredicateGroupLogicalOperator.OR,
+    },
+  ],
+  rowLevelPermissionPredicates: [
+    {
+      universalIdentifier: 'd4c3b2a1-0e9f-4c8b-9e7d-444444444444',
+      objectUniversalIdentifier: OPPORTUNITY.universalIdentifier,
+      fieldUniversalIdentifier: OPPORTUNITY.fields.owner.universalIdentifier,
+      operand: RowLevelPermissionPredicateOperand.IS,
+      workspaceMemberFieldUniversalIdentifier: CURRENT_MEMBER,
+      predicateGroupUniversalIdentifier: 'c3b2a1d0-9f8e-4b7a-8d6c-333333333333',
+    },
+    {
+      universalIdentifier: 'e5d4c3b2-1f0e-4d9c-8f8e-555555555555',
+      objectUniversalIdentifier: OPPORTUNITY.universalIdentifier,
+      fieldUniversalIdentifier:
+        OPPORTUNITY.fields.pointOfContact.universalIdentifier,
+      operand: RowLevelPermissionPredicateOperand.IS,
+      workspaceMemberFieldUniversalIdentifier: CURRENT_MEMBER,
+      predicateGroupUniversalIdentifier: 'c3b2a1d0-9f8e-4b7a-8d6c-333333333333',
+    },
+  ],
+});
+```
+
+Notas:
+
+* Asigna a cada predicado y grupo un `universalIdentifier` estable (cualquier uuid): sirve como clave de la entidad a través de las actualizaciones, y los predicados hacen referencia a los grupos mediante él.
+* Los predicados pueden hacer referencia a objetos y campos que sean propiedad de tu aplicación o de los objetos estándar de Twenty.
+* La seguridad a nivel de fila se aplica para los espacios de trabajo en planes que la incluyen; los predicados siguen sincronizándose en otros planes, simplemente no se aplican.
+
+## El rol de función predeterminado
+
+Cuando generas una nueva aplicación, la CLI crea un archivo de rol predeterminado declarado con `defineApplicationRole()`:
+
+```ts src/roles/default-role.ts
+import { defineApplicationRole } from 'twenty-sdk/define';
+
+export const DEFAULT_ROLE_UNIVERSAL_IDENTIFIER =
+  'b648f87b-1d26-4961-b974-0908fd991061';
+
+export default defineApplicationRole({
+  universalIdentifier: DEFAULT_ROLE_UNIVERSAL_IDENTIFIER,
+  label: 'Default function role',
+  description: 'Default role for function Twenty client',
+  canReadAllObjectRecords: true,
+  canUpdateAllObjectRecords: false,
+  canSoftDeleteAllObjectRecords: false,
+  canDestroyAllObjectRecords: false,
+  canUpdateAllSettings: false,
+  canBeAssignedToAgents: false,
+  canBeAssignedToUsers: false,
+  canBeAssignedToApiKeys: false,
+  objectPermissions: [],
+  fieldPermissions: [],
+  permissionFlagUniversalIdentifiers: [],
+});
+```
+
+`defineApplicationRole()` es una envoltura ligera alrededor de `defineRole()` que marca **el** rol utilizado como predeterminado de tu aplicación en el momento de la instalación. La validación es idéntica a `defineRole`, pero la canalización de compilación conecta automáticamente su `universalIdentifier` con `defaultRoleUniversalIdentifier` del manifiesto de la aplicación, por lo que no necesitas hacer referencia a él desde [`defineApplication`](/l/es/developers/extend/apps/config/application).
+
+Notas:
+
+* Se permite exactamente **una** llamada a `defineApplicationRole(...)` por aplicación; la compilación del manifiesto fallará si encuentra más de una.
+* Usa `defineRole()` (no `defineApplicationRole()`) para cualquier rol **adicional** que distribuya tu aplicación.
+* Configurar `defaultRoleUniversalIdentifier` explícitamente en `defineApplication()` sigue siendo compatible por motivos de retrocompatibilidad, pero está en desuso en favor de `defineApplicationRole()`.
+
+## Mejores prácticas
+
+* Parte del rol generado automáticamente y luego restríngeelo progresivamente; el valor predeterminado concede un acceso amplio de lectura, lo cual rara vez es lo que quieres en producción.
+* Reemplaza `objectPermissions` y `fieldPermissions` con los objetos y campos que realmente necesitan tus funciones.
+* `permissionFlagUniversalIdentifiers` controla el acceso a capacidades a nivel de plataforma. Manténlos al mínimo.
+* Consulta un ejemplo funcional: [`examples/hello-world/src/roles/default-role.ts`](https://github.com/twentyhq/twenty/blob/main/packages/twenty-apps/examples/hello-world/src/roles/default-role.ts).