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

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

@@ -0,0 +1,102 @@
+---
+title: Conceitos
+description: Como as aplicações Twenty funcionam — modelo de entidade, sandboxing e ciclo de vida da instalação.
+icon: sitemap
+---
+
+As aplicações Twenty são pacotes TypeScript que estendem seu espaço de trabalho com objetos personalizados, lógica, componentes de UI e recursos de IA. Elas são executadas na plataforma Twenty com sandboxing completo e controles de permissão.
+
+## Como as aplicações funcionam
+
+Uma aplicação é uma coleção de **entidades** declaradas usando funções `defineEntity()` do pacote `twenty-sdk`. O SDK detecta essas declarações via análise de AST no momento da compilação e produz um **manifesto** — uma descrição completa do que seu aplicativo adiciona a um espaço de trabalho. Essas funções validam sua configuração em tempo de compilação e oferecem autocompletar na IDE e segurança de tipos.
+
+```
+your-app/
+├── src/
+│   ├── application-config.ts    ← defineApplication (required, one per app)
+│   ├── roles/                   ← defineRole
+│   ├── objects/                 ← defineObject
+│   ├── fields/                  ← defineField
+│   ├── logic-functions/         ← defineLogicFunction
+│   ├── front-components/        ← defineFrontComponent
+│   ├── skills/                  ← defineSkill
+│   ├── agents/                  ← defineAgent
+│   ├── views/                   ← defineView
+│   ├── navigation-menu-items/   ← defineNavigationMenuItem
+│   └── page-layouts/            ← definePageLayout
+├── public/                      ← Static assets (images, icons)
+└── package.json
+```
+
+<Note>
+  **A organização de arquivos fica a seu critério.** A detecção de entidades é baseada em AST — o SDK encontra chamadas a `export default defineEntity(...)` independentemente de onde o arquivo esteja. A estrutura de pastas acima é uma convenção, não um requisito.
+</Note>
+
+## Tipos de entidade
+
+| Entidade                        | Finalidade                                                                                    | Documentação                                                                                                                |
+| ------------------------------- | --------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- |
+| **Aplicação**                   | Identidade da aplicação, função padrão, variáveis                                             | [Configuração da aplicação](/l/pt/developers/extend/apps/config/application)                                                     |
+| **Papel**                       | Conjuntos de permissões para objetos e campos                                                 | [Papéis e permissões](/l/pt/developers/extend/apps/config/roles)                                                                 |
+| **Objeto**                      | Tipos de registro personalizados com campos                                                   | [Objetos](/l/pt/developers/extend/apps/data/objects)                                                                             |
+| **Campo**                       | Adicionar campos a objetos de outros apps                                                     | [Extensão de objetos](/l/pt/developers/extend/apps/data/extending-objects)                                                       |
+| **Relação**                     | Links bidirecionais entre objetos                                                             | [Relações](/l/pt/developers/extend/apps/data/relations)                                                                          |
+| **Função lógica**               | TypeScript no lado do servidor com gatilhos                                                   | [Funções lógicas](/l/pt/developers/extend/apps/logic/logic-functions)                                                            |
+| **Habilidade**                  | Instruções reutilizáveis para agentes de IA                                                   | [Habilidades e Agentes](/l/pt/developers/extend/apps/logic/skills-and-agents)                                                    |
+| **Agente**                      | Assistentes de IA com prompts personalizados                                                  | [Habilidades e Agentes](/l/pt/developers/extend/apps/logic/skills-and-agents)                                                    |
+| **Provedor de conexão**         | Credenciais OAuth para APIs de terceiros                                                      | [Conexões](/l/pt/developers/extend/apps/logic/connections)                                                                       |
+| **Vista**                       | Vistas de lista de registros pré-configuradas                                                 | [Vistas](/l/pt/developers/extend/apps/layout/views)                                                                              |
+| **Item do menu de navegação**   | Entradas personalizadas na barra lateral                                                      | [Itens do menu de navegação](/l/pt/developers/extend/apps/layout/navigation-menu-items)                                          |
+| **Layout da Página**            | Abas e widgets na página de detalhes de um registro                                           | [Layouts de página](/l/pt/developers/extend/apps/layout/page-layouts)                                                            |
+| **Componente de front-end**     | UI React em sandbox dentro do Twenty                                                          | [Componentes de front-end](/l/pt/developers/extend/apps/layout/front-components)                                                 |
+| **Dependências compartilhadas** | Dependências compartilhadas pelos componentes de front-end do app, declaradas em package.json | [Dependências compartilhadas](/l/pt/developers/extend/apps/layout/front-components#sharing-dependencies-across-front-components) |
+| **Item do menu de comandos**    | Ações rápidas e entradas Cmd+K                                                                | [Itens do menu de comandos](/l/pt/developers/extend/apps/layout/command-menu-items)                                              |
+
+## Sandboxing
+
+* **Funções lógicas** são executadas em processos Node.js isolados no servidor. Eles acessam dados apenas por meio do cliente de API tipado, que atua como a pessoa que disparou a execução ou como o próprio app. Consulte [Qual acesso uma chamada usa](/l/pt/developers/extend/apps/logic/logic-functions#whose-access-a-call-uses).
+* **Componentes de front-end** executam em Web Workers usando Remote DOM — isolados da página principal, mas renderizando elementos DOM nativos (não iframes). Eles se comunicam com o Twenty por meio de uma API de host com passagem de mensagens.
+* **Permissões** são aplicadas no nível da API. Dois tokens de runtime são inseridos, ambos derivados da função declarada com `defineApplicationRole()`; o padrão é ainda mais limitado ao que a pessoa que disparou a execução pode fazer quando há alguém por trás da execução.
+
+## Ciclo de vida do aplicativo
+
+```
+┌─────────────────────────────────────────────────────────┐
+│ Development                                             │
+│   npx create-twenty-app → yarn twenty dev (live sync)   │
+├─────────────────────────────────────────────────────────┤
+│ Build & Deploy                                          │
+│   yarn twenty dev:build → yarn twenty app:publish        │
+├─────────────────────────────────────────────────────────┤
+│ Install flow                                            │
+│   upload → [pre-install] → metadata migration →         │
+│   generate SDK → [post-install] → … → [uninstall]       │
+├─────────────────────────────────────────────────────────┤
+│ Publish                                                 │
+│   npm publish → appears in Twenty marketplace           │
+└─────────────────────────────────────────────────────────┘
+```
+
+* **`yarn twenty dev`** — observa seus arquivos-fonte e sincroniza ao vivo as alterações com um servidor Twenty conectado. O cliente de API tipado é regenerado automaticamente quando o esquema muda.
+* **`yarn twenty dev:build`** — compila TypeScript, empacota funções de lógica e componentes de front-end com o esbuild e produz um manifesto.
+* **Hooks de pré/pós-instalação e desinstalação** — funções opcionais que são executadas durante a instalação ou logo antes da remoção. Veja [Hooks de instalação](/l/pt/developers/extend/apps/config/install-hooks) para detalhes.
+
+## Próximos passos
+
+<CardGroup cols={2}>
+  <Card title="Configuração" icon="screwdriver-wrench" href="/l/pt/developers/extend/apps/config/overview">
+    Identidade da aplicação, função padrão e hooks de instalação e desinstalação.
+  </Card>
+  <Card title="Dados" icon="database" href="/l/pt/developers/extend/apps/data/overview">
+    Objetos, campos e relações bidirecionais.
+  </Card>
+  <Card title="Lógica" icon="bolt" href="/l/pt/developers/extend/apps/logic/overview">
+    Funções lógicas, habilidades, agentes e conexões OAuth.
+  </Card>
+  <Card title="Layout" icon="table-columns" href="/l/pt/developers/extend/apps/layout/overview">
+    Vistas, navegação, layouts de página, componentes de front-end.
+  </Card>
+  <Card title="Operações" icon="rocket" href="/l/pt/developers/extend/apps/operations/overview">
+    CLI, testes, remotos, CI e publicação do seu aplicativo.
+  </Card>
+</CardGroup>

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

@@ -0,0 +1,87 @@
+---
+title: Servidor Local
+description: Gerencie o servidor Docker local do Twenty — iniciar, parar, atualizar, executar uma instância de teste paralela e configurar manualmente o SDK.
+icon: server
+---
+
+## Gerenciando o servidor local
+
+Use `yarn twenty docker:*` para controlar o contêiner Twenty local:
+
+| Comando                                | O que faz                                        |
+| -------------------------------------- | ------------------------------------------------ |
+| `yarn twenty docker:start`             | Inicia o servidor (baixa a imagem se necessário) |
+| `yarn twenty docker:start 2.2.0`       | Iniciar uma versão específica do servidor        |
+| `yarn twenty docker:start --port 3030` | Inicia em uma porta personalizada                |
+| `yarn twenty docker:stop`              | Interrompe o servidor (preserva os dados)        |
+| `yarn twenty docker:status`            | Mostra a URL, a versão e as credenciais de login |
+| `yarn twenty docker:logs`              | Transmite os logs do servidor                    |
+| `yarn twenty docker:reset`             | Apaga os dados e começa do zero                  |
+| `yarn twenty docker:upgrade`           | Baixa a imagem mais recente `twenty-app-dev`     |
+| `yarn twenty docker:upgrade 2.2.0`     | Atualiza para uma versão específica              |
+
+Os dados são persistidos entre reinicializações em dois volumes do Docker (`twenty-app-dev-data` para PostgreSQL, `twenty-app-dev-storage` para arquivos). Use `reset` para apagar tudo.
+
+## Fixando a versão do servidor
+
+Quando nenhuma versão é passada, `docker:start` resolve a versão a partir do intervalo `engines.twenty` do seu app em `package.json` — o mesmo intervalo que o servidor valida quando o seu app é instalado. Ele inicia a imagem mais recente publicada de `twenty-app-dev` que satisfaz o intervalo, recorrendo a `latest` quando o campo está ausente ou nenhuma versão publicada corresponde:
+
+```json filename="package.json"
+{
+  "engines": {
+    "twenty": ">=2.2.0"
+  }
+}
+```
+
+Passe uma versão explicitamente para substituir o intervalo em uma única execução: `yarn twenty docker:start 2.3.0`. Se já existir um contêiner em uma versão diferente, `docker:start` faz o upgrade dele no lugar (recriando o contêiner enquanto preserva seus volumes de dados).
+
+## Atualizando a imagem do servidor
+
+`yarn twenty docker:upgrade` baixa a imagem mais recente, compara os digests e só recria o contêiner se algo realmente tiver mudado. Os volumes são preservados — apenas o contêiner é substituído. Se uma nova imagem foi baixada e o contêiner estava em execução, a atualização inicia automaticamente um novo contêiner; execute `yarn twenty docker:start` depois para aguardar até que ele fique saudável.
+
+```bash filename="Terminal"
+yarn twenty docker:upgrade            # Latest
+yarn twenty docker:upgrade 2.2.0      # Specific version
+```
+
+Verifique a versão em execução com `yarn twenty docker:status` (ele mostra o `APP_VERSION` incorporado ao contêiner).
+
+## Executando uma instância de teste paralela
+
+Passe `--test` para qualquer comando `docker:*` para gerenciar uma segunda instância totalmente isolada — útil para testes de integração ou para experimentar sem tocar nos seus dados principais de desenvolvimento:
+
+| Comando                             | O que faz                                        |
+| ----------------------------------- | ------------------------------------------------ |
+| `yarn twenty docker:start --test`   | Inicia a instância de teste (padrão: porta 2021) |
+| `yarn twenty docker:stop --test`    | Para                                             |
+| `yarn twenty docker:status --test`  | Mostra seu status                                |
+| `yarn twenty docker:logs --test`    | Transmite seus logs                              |
+| `yarn twenty docker:reset --test`   | Apaga seus dados                                 |
+| `yarn twenty docker:upgrade --test` | Atualiza sua imagem                              |
+
+A instância de teste tem seu próprio contêiner (`twenty-app-dev-test`), volumes (`twenty-app-dev-test-data`, `twenty-app-dev-test-storage`) e configuração — ela é executada junto com sua instância principal sem conflitos. Combine `--test` com `--port` para substituir 2021.
+
+## Configuração manual (sem o gerador)
+
+Ignore o gerador se você estiver adicionando o SDK a um projeto existente:
+
+```bash filename="Terminal"
+yarn add twenty-sdk twenty-client-sdk
+```
+
+Adicione o script ao `package.json`:
+
+```json filename="package.json"
+{
+  "scripts": {
+    "twenty": "twenty"
+  }
+}
+```
+
+Agora você pode executar `yarn twenty dev`, `yarn twenty docker:start` e o restante.
+
+<Note>
+Não instale `twenty-sdk` globalmente — fixe-o por projeto, para que cada aplicativo use sua própria versão.
+</Note>

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

@@ -0,0 +1,79 @@
+---
+title: Estrutura do projeto
+description: O que há dentro de um app Twenty criado com scaffold — arquivos, pastas e o que cada um faz.
+icon: folder-tree
+---
+
+Um novo app gerado por `npx create-twenty-app` se parece com isto:
+
+```text filename="my-twenty-app/"
+my-twenty-app/
+  package.json
+  src/
+    application-config.ts                   # Required — your app's entry point
+    default-role.ts                         # Permissions for logic functions
+    constants/
+      universal-identifiers.ts              # Auto-generated UUIDs and metadata
+    front-components/
+      main-page.tsx                         # Welcome page component
+    navigation-menu-items/
+      main-page.navigation-menu-item.ts     # Sidebar entry for the welcome page
+    page-layouts/
+      main-page.page-layout.ts              # Standalone page hosting the component
+    __tests__/
+      application-config.test.ts            # Unit test
+      global-setup.ts                       # Integration test setup (sync + uninstall)
+      schema.integration-test.ts            # Integration test against a live server
+  .github/workflows/
+    ci.yml                                  # Lint, typecheck, unit + integration tests
+    cd.yml                                  # Deploy + install on push to main
+    publish.yml                             # Publish to npm on version tags (with provenance)
+  public/
+    logo.svg                                # Static assets
+  vitest.config.ts                          # Integration test runner config
+  vitest.unit.config.ts                     # Unit test runner config
+  tsconfig.json, tsconfig.spec.json
+  .nvmrc, .yarnrc.yml, .oxlintrc.json
+  README.md, AGENTS.md, CLAUDE.md, CHANGELOG.md, SETUP.md
+```
+
+## Arquivos principais
+
+| Arquivo / Pasta                                                            | Finalidade                                                                                                                          |
+| -------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
+| `src/application-config.ts`                                                | **Obrigatório.** O principal arquivo de configuração do seu aplicativo.                                                             |
+| `src/default-role.ts`                                                      | Papel padrão que controla o que suas funções de lógica podem acessar.                                                               |
+| `src/constants/universal-identifiers.ts`                                   | UUIDs gerados automaticamente e metadados (nome de exibição, descrição).                                                            |
+| `src/front-components/`, `src/navigation-menu-items/`, `src/page-layouts/` | Uma página de boas-vindas inicial: um front component renderizado por um page layout autônomo, acessível a partir da barra lateral. |
+| `src/__tests__/`                                                           | Um teste de unidade mais um teste de integração (com sua configuração global) que sincroniza o app com um servidor real.            |
+| `public/`                                                                  | Recursos estáticos (imagens, fontes) servidos com seu aplicativo.                                                                   |
+| `AGENTS.md` / `CLAUDE.md`                                                  | Orientação para agentes de codificação de IA que trabalham no app.                                                                  |
+| `CHANGELOG.md` / `SETUP.md`                                                | Registro de alterações importantes e instruções de configuração para desenvolvimento local.                                         |
+
+<Note>
+**A organização de arquivos fica a seu critério.** As pastas acima são convenções — o SDK detecta entidades por meio de análise de AST em chamadas a `export default defineEntity(...)`, independentemente de onde o arquivo esteja.
+</Note>
+
+## Dependências
+
+Ambos os pacotes Twenty SDK pertencem a `devDependencies`, não a `dependencies`:
+
+```json filename="package.json"
+{
+  "dependencies": {},
+  "devDependencies": {
+    "twenty-client-sdk": "2.20.0",
+    "twenty-sdk": "2.20.0",
+    "twenty-ui": "1.0.0-alpha.1"
+  }
+}
+```
+
+O scaffolder fixa `twenty-sdk` e `twenty-client-sdk` para a sua própria versão — mantenha os dois sincronizados ao atualizar.
+
+* **`twenty-sdk`** inclui a CLI `twenty` e as ferramentas de build/scaffolding. Ele é executado apenas durante o desenvolvimento e o build e nunca é importado pelo runtime do aplicativo publicado.
+* **`twenty-client-sdk`** *é* importado pelo código do seu aplicativo (`CoreApiClient`, `MetadataApiClient`, `RestApiClient`), mas a Twenty o fornece em tempo de execução — as funções de lógica o obtêm de uma camada SDK gerada, e os componentes de front o resolvem a partir de módulos servidos pelo servidor. A cópia instalada é usada apenas para verificação de tipos e para o build no momento do deploy, então ela nunca precisa ser incluída no bundle implantado.
+
+Manter qualquer um dos pacotes em `dependencies` o inclui no bundle de runtime do aplicativo instalado, onde ele é peso morto. `twenty dev:build` emite um aviso quando qualquer um deles ainda está listado em `dependencies`.
+
+Adicione as dependências de runtime do próprio aplicativo (bibliotecas que as suas funções de lógica realmente importam em tempo de execução) em `dependencies`, como de costume. Mantenha a árvore enxuta: `dependencies` são instaladas em uma camada de runtime limitada a 250MB descompactados, e um comando de sync ou install falha com um erro de tamanho de dependencies acima desse valor — bibliotecas de UI e ferramentas de desenvolvimento pertencem a `devDependencies`.

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

@@ -0,0 +1,166 @@
+---
+title: Início rápido
+icon: rocket
+description: Crie seu primeiro app do Twenty em minutos.
+---
+
+## Pré-requisitos
+
+* **Node.js 24.5+** — [Baixar](https://nodejs.org/)
+* **Yarn 4** — Vem com o Node.js via Corepack. Ative-o: `corepack enable`
+* **Docker** — [Baixar](https://www.docker.com/products/docker-desktop/). Necessário para executar um servidor Twenty local. Ignore se você já tiver o Twenty em execução em outro lugar.
+
+A criação de um aplicativo Twenty tem três fases. A ferramenta de scaffolding as reúne em um único comando do fluxo ideal, mas cada fase é um conceito separado — quando algo falha, saber em que fase você está indica o que corrigir.
+
+| Fase                        | O que você faz                                     | Ferramenta                          | Resultado                             |
+| --------------------------- | -------------------------------------------------- | ----------------------------------- | ------------------------------------- |
+| **1. Criar scaffolding**    | Gerar o código-fonte do aplicativo                 | `npx create-twenty-app`             | Um projeto TypeScript em disco        |
+| **2. Executar um servidor** | Iniciar um servidor Twenty para o qual sincronizar | Docker + `yarn twenty docker:start` | Uma instância Twenty em execução      |
+| **3. Sincronizar**          | Sincronize seu código em tempo real com o servidor | `yarn twenty dev`                   | Suas alterações aparecem na interface |
+
+---
+
+## Fase 1 — Fazer scaffolding do seu projeto
+
+Crie um novo aplicativo a partir do modelo:
+
+```bash filename="Terminal"
+npx create-twenty-app@latest my-twenty-app
+```
+
+O gerador não é interativo: o nome do diretório se torna o nome do app. Passe `--display-name` e `--description` para personalizar os metadados gerados (você também pode editá-los depois em `src/constants/universal-identifiers.ts`). Isso gera um projeto TypeScript em `my-twenty-app/` com um `application-config.ts` inicial, um papel padrão, fluxos de trabalho de CI/CD e um teste de integração.
+
+**Após esta fase:** você tem o código-fonte de um aplicativo na sua máquina. Ele ainda não está em execução — isso é a Fase 2.
+
+---
+
+## Fase 2 — Executar um servidor Twenty local
+
+Seu aplicativo precisa de um servidor Twenty para o qual sincronizar. O servidor é uma instância completa do Twenty — interface, API GraphQL, PostgreSQL — executando localmente no Docker. Seu código local envia suas definições para esse servidor, o que faz com que elas apareçam na interface.
+
+O scaffolder inicia uma instância para você: com o Docker em execução, ele baixa a imagem `twentycrm/twenty-app-dev`, inicia-a na porta `2020` e autentica a CLI no workspace de demonstração pré-preenchido (`tim@apple.dev`) — sem necessidade de login.
+
+Para se conectar a um servidor Twenty existente em vez disso, passe `--url \<your-server-url>`. Servidores remotos se autenticam com OAuth: um navegador é aberto para que você faça login e clique em **Authorize**, o que dá à CLI acesso ao seu workspace. (Você também pode optar por usar OAuth localmente com `--authentication-method oauth` — faça login com `tim@apple.dev` / `tim@apple.dev`.)
+
+<div style={{textAlign: 'center'}}>
+  <img src="/images/docs/developers/extends/apps/login.png" alt="Tela de login do Twenty" />
+</div>
+
+<div style={{textAlign: 'center'}}>
+  <img src="/images/docs/developers/extends/apps/authorize.png" alt="Tela de autorização da CLI do Twenty" />
+</div>
+
+Seu terminal confirmará que tudo está configurado.
+
+<div style={{textAlign: 'center'}}>
+  <img src="/images/docs/developers/extends/apps/scaffolded.png" alt="Scaffold do aplicativo criado com sucesso" />
+</div>
+
+**Após esta fase:** você tem um servidor Twenty em execução em [http://localhost:2020](http://localhost:2020) com sua CLI autorizada a sincronizar com ele.
+
+<Note>
+Se o Docker não estiver instalado ou em execução, a ferramenta de scaffolding informará o comando de inicialização correto para o seu sistema operacional. Quando o Docker estiver ativo, você pode retomar com `yarn twenty docker:start` — sem necessidade de recriar o scaffolding.
+</Note>
+
+---
+
+## Fase 3 — Sincronizar suas alterações
+
+Este é o ciclo interno no qual você passará a maior parte do tempo.
+
+```bash filename="Terminal"
+cd my-twenty-app
+yarn twenty dev
+```
+
+Isso monitora `src/`, recompila a cada alteração e sincroniza o resultado com o servidor. Edite um arquivo, salve e, em alguns segundos, o servidor refletirá a alteração. Você verá um painel de status em tempo real no seu terminal.
+
+Para uma saída mais detalhada (logs de build, solicitações de sincronização, rastros de erro), adicione `--verbose`.
+
+<div style={{textAlign: 'center'}}>
+  <img src="/images/docs/developers/extends/apps/dev.png" alt="Saída do terminal no modo de desenvolvimento" />
+</div>
+
+Abra [http://localhost:2020/settings/applications#developer](http://localhost:2020/settings/applications#developer). Você deverá ver seu aplicativo em **Your Apps**.
+
+<div style={{textAlign: 'center'}}>
+  <img src="/images/docs/developers/extends/apps/app-in-ui-1.png" alt="Lista Your Apps exibindo My twenty app" />
+</div>
+
+Clique em **My twenty app** para ver seu **registro do aplicativo** — um registro em nível de servidor que descreve seu aplicativo (nome, identificador, credenciais OAuth, origem). Um registro pode ser instalado em vários espaços de trabalho no mesmo servidor.
+
+<div style={{textAlign: 'center'}}>
+  <img src="/images/docs/developers/extends/apps/app-in-ui-2.png" alt="Detalhes do registro do aplicativo" />
+</div>
+
+Clique em **View installed app** para ver a instalação no espaço de trabalho. A aba **About** mostra a versão e as opções de gerenciamento.
+
+<div style={{textAlign: 'center'}}>
+  <img src="/images/docs/developers/extends/apps/app-in-ui-3.png" alt="Aplicação instalada" />
+</div>
+
+**Após esta fase:** você tem um ciclo de desenvolvimento em tempo real. Edite qualquer arquivo em `src/` e ele aparecerá na interface.
+
+### Sincronização única para CI e scripts
+
+Use `plan` e `apply` para executar o mesmo pipeline uma vez, sem watcher:
+
+```bash filename="Terminal"
+yarn twenty plan   # preview the metadata changes without applying them
+yarn twenty apply  # show the plan, then apply it
+```
+
+| Comando             | Comportamento                                                                                                                                                                                               | Quando usar                                                                      |
+| ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------- |
+| `yarn twenty dev`   | Monitora e ressincroniza a cada alteração. Fica em execução até você interrompê-lo.                                                                                                                         | Desenvolvimento local interativo.                                                |
+| `yarn twenty apply` | Executa uma única compilação + sincronização e, em seguida, encerra com o código `0` em caso de sucesso ou `1` em caso de falha. Pede confirmação para alterações destrutivas (passe `--force` para pular). | Scripts, CI, hooks de pre-commit, agentes de IA e fluxos de trabalho com script. |
+| `yarn twenty plan`  | Compila e imprime as alterações de metadados **sem aplicá-las**.                                                                                                                                            | Inspecionar o que uma sincronização mudaria antes de confirmá-la.                |
+
+Todos os modos precisam de um remoto autenticado. Veja [Sincronização e recuperação](/l/pt/developers/extend/apps/operations/sync-and-recovery#previewing-changes-plan) para mais detalhes sobre `plan`.
+
+<Note>
+`yarn twenty dev --once` e `yarn twenty dev --once --dry-run` são aliases obsoletos para `yarn twenty apply` e `yarn twenty plan`.
+</Note>
+
+### Opções do modo de desenvolvimento
+
+| Opção                                 | Descrição                                                                                         |
+| ------------------------------------- | ------------------------------------------------------------------------------------------------- |
+| `--force`                             | Aplicar alterações destrutivas (exclusões) sem confirmação.                                       |
+| `--debounceMs \<ms>` | Define o atraso de debounce para alterações de arquivo em milissegundos (padrão: `1000`).         |
+| `--verbose` / `--debug`               | Mostra registros detalhados de compilação, solicitações de sincronização e rastreamentos de erro. |
+
+## O que você pode criar
+
+Os aplicativos são compostos por **entidades** — cada uma definida como um arquivo TypeScript com um único `export default`:
+
+| Entidade                     | O que faz                                                                                                          |
+| ---------------------------- | ------------------------------------------------------------------------------------------------------------------ |
+| **Objetos e campos**         | Modelos de dados personalizados (Cartão postal, Fatura etc.) com campos tipados                                    |
+| **Funções lógicas**          | Funções TypeScript do lado do servidor acionadas por rotas HTTP, agendamentos do cron ou eventos de banco de dados |
+| **Componentes de front-end** | Componentes React que são renderizados na UI do Twenty (painel lateral, widgets, menu de comandos)                 |
+| **Habilidades e agentes**    | Recursos de IA — instruções reutilizáveis e assistentes autônomos                                                  |
+| **Exibições e navegação**    | Exibições de lista pré-configuradas e itens de menu da barra lateral                                               |
+| **Layouts de página**        | Páginas de detalhes de registros personalizadas com abas e widgets                                                 |
+
+Referência completa: [Conceitos](/l/pt/developers/extend/apps/getting-started/concepts).
+
+## Próximos passos
+
+<CardGroup cols={2}>
+  <Card title="Configuração" icon="screwdriver-wrench" href="/l/pt/developers/extend/apps/config/overview">
+    Identidade do aplicativo, função padrão, hooks de instalação e desinstalação, recursos públicos.
+  </Card>
+  <Card title="Data" icon="database" href="/l/pt/developers/extend/apps/data/overview">
+    Objetos, campos e relações bidirecionais.
+  </Card>
+  <Card title="Lógica" icon="bolt" href="/l/pt/developers/extend/apps/logic/overview">
+    Funções lógicas, habilidades, agentes e conexões OAuth.
+  </Card>
+  <Card title="Layout" icon="table-columns" href="/l/pt/developers/extend/apps/layout/overview">
+    Exibições, navegação, layouts de página, componentes de front-end.
+  </Card>
+  <Card title="Operações" icon="rocket" href="/l/pt/developers/extend/apps/operations/overview">
+    CLI, testes, remotos, CI e publicação do seu aplicativo.
+  </Card>
+</CardGroup>

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

@@ -0,0 +1,63 @@
+---
+title: Scaffolding
+description: Gere arquivos de entidade de forma interativa com `yarn twenty dev:add` — objetos, campos, visualizações, funções de lógica e mais.
+icon: wand-magic-sparkles
+---
+
+Em vez de criar arquivos de entidade manualmente, use o scaffolder interativo:
+
+```bash filename="Terminal"
+yarn twenty dev:add
+```
+
+Ele solicita que você escolha um tipo de entidade e orienta você pelos campos obrigatórios, depois grava um arquivo pronto para uso com um `universalIdentifier` estável e a chamada correta de `defineEntity()`.
+
+Você também pode passar o tipo de entidade diretamente para pular o primeiro prompt:
+
+```bash filename="Terminal"
+yarn twenty dev:add object
+yarn twenty dev:add logicFunction
+yarn twenty dev:add frontComponent
+```
+
+## Tipos de entidade disponíveis
+
+| Tipo de entidade                | Comando                                    | Arquivo gerado                                            |
+| ------------------------------- | ------------------------------------------ | --------------------------------------------------------- |
+| Objeto                          | `yarn twenty dev:add object`               | `src/objects/\<name>.ts`                 |
+| Campo                           | `yarn twenty dev:add field`                | `src/fields/\<name>.ts`                  |
+| Função lógica                   | `yarn twenty dev:add logicFunction`        | `src/logic-functions/\<name>.ts`         |
+| Componente de front-end         | `yarn twenty dev:add frontComponent`       | `src/front-components/\<name>.tsx`       |
+| Função                          | `yarn twenty dev:add role`                 | `src/roles/\<name>.ts`                   |
+| Habilidade                      | `yarn twenty dev:add skill`                | `src/skills/\<name>.ts`                  |
+| Agente                          | `yarn twenty dev:add agent`                | `src/agents/\<name>.ts`                  |
+| Vista                           | `yarn twenty dev:add view`                 | `src/views/\<name>.ts`                   |
+| Item do menu de navegação       | `yarn twenty dev:add navigationMenuItem`   | `src/navigation-menu-items/\<name>.ts`   |
+| Layout da página                | `yarn twenty dev:add pageLayout`           | `src/page-layouts/\<name>.ts`            |
+| Aba Layout da Página            | `yarn twenty dev:add pageLayoutTab`        | `src/page-layout-tabs/\<name>.ts`        |
+| Item do menu de comandos        | `yarn twenty dev:add commandMenuItem`      | `src/command-menu-items/\<name>.ts`      |
+| Campo da Vista                  | `yarn twenty dev:add viewField`            | `src/view-fields/\<name>.ts`             |
+| Provedor de conexão             | `yarn twenty dev:add connectionProvider`   | `src/connection-providers/\<name>.ts`    |
+| Tipo de atividade da cronologia | `yarn twenty dev:add timelineActivityType` | `src/timeline-activity-types/\<name>.ts` |
+
+## O que o scaffolder gera
+
+Cada tipo de entidade tem seu próprio modelo. Por exemplo, `yarn twenty dev:add object` solicita:
+
+1. **Nome (singular)** — por exemplo, `invoice`
+2. **Nome (plural)** — por exemplo, `invoices`
+3. **Rótulo (singular)** — preenchido automaticamente a partir do nome (por exemplo, `Invoice`)
+4. **Rótulo (plural)** — preenchido automaticamente (por exemplo, `Invoices`)
+5. **Criar uma view e um item de navegação?** — se você responder sim, o scaffolder também gera uma view correspondente e um link na barra lateral para o novo objeto.
+
+Outros tipos de entidade têm prompts mais simples — a maioria pede apenas um nome.
+
+O tipo de entidade `field` é mais detalhado: ele solicita o nome do campo, rótulo, tipo (a partir de uma lista de todos os tipos de campo disponíveis como `TEXT`, `NUMBER`, `SELECT`, `RELATION`, etc.) e o `universalIdentifier` do objeto de destino.
+
+## Caminho de saída personalizado
+
+Use a opção `--path` para colocar o arquivo gerado em um local personalizado:
+
+```bash filename="Terminal"
+yarn twenty dev:add logicFunction --path src/custom-folder
+```

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

@@ -0,0 +1,14 @@
+---
+title: Resolução de Problemas
+description: Problemas comuns na primeira execução — Docker, versão do Node, Yarn, dependências.
+icon: wrench
+---
+
+* **Erros do Docker** — Certifique-se de que o Docker Desktop (ou o daemon) esteja em execução antes de `yarn twenty docker:start`. A mensagem de erro mostrará o comando de inicialização correto para o seu sistema operacional.
+* **Versão errada do Node** — É necessário 24.5+ (`engines.node: ^24.5.0`). Verifique com `node -v`.
+* **Falta o Yarn 4** — Execute `corepack enable`.
+* **Dependências com problemas** — `rm -rf node_modules && yarn install`.
+* **Erros do `twenty-sdk` após a atualização para a v2.8.0** — Ele foi movido de `dependencies` para `devDependencies` na v2.8.0. Veja [Estrutura do projeto → Dependências](/l/pt/developers/extend/apps/getting-started/project-structure#dependencies).
+* **`twenty dev:build` emite um aviso sobre `twenty-client-sdk` em `dependencies`** — Ele é fornecido em tempo de execução pela Twenty, então deve ser movido para `devDependencies` junto com `twenty-sdk`. Veja [Estrutura do projeto → Dependências](/l/pt/developers/extend/apps/getting-started/project-structure#dependencies).
+
+Travou? Peça ajuda no [Discord da Twenty](https://discord.com/channels/1130383047699738754/1130386664812982322).