# Manifesto do plugin

Um plugin se descreve inteiro por um objeto: o `PluginManifest`. Ele declara o que o plugin é — navegação, rotas, widgets, dados, permissões — e o runtime faz o resto. Plugins declaram; o core resolve. Esta página é o tour pelos campos; a referência exaustiva está em [referência do manifesto do plugin](/pt-BR/docs/referencia/plugin-manifest).

## O núcleo obrigatório

Quatro campos identificam qualquer plugin, mais os dois seams que dão a ele um lugar na UI:

```ts
{
  id: 'fidelidade',
  name: 'Fidelidade',
  icon: 'Puzzle',
  version: '0.1.0',
  navigation: [
    { section: 'main', position: 50, label: 'Fidelidade', route: '/fidelidade', icon: 'Puzzle' },
  ],
  routes: [{ path: '/fidelidade', component: Page }],
}
```

- **`id`** — identificador único do plugin.
- **`name`** / **`icon`** / **`version`** — rótulo, ícone e versão.
- **`navigation`** — os itens de menu (veja [Rotas e navegação](/pt-BR/docs/apps/rotas-e-navegacao)).
- **`routes`** — o mapeamento `path → componente`.

Um componente sempre pode ser dado **direto** (`component`) ou por **id de registry** (`componentId`) — exatamente um dos dois.

## Os seams de extensão

Além do núcleo, o manifesto tem uma família de campos opcionais — cada um é um "seam" pelo qual o plugin estende a plataforma sem tocar em nenhum outro plugin:

| Seam | O que declara |
| --- | --- |
| `settings` | Abas na tela de configurações do plugin. |
| `widgets` | Componentes injetados em zonas nomeadas do shell (`WidgetZone`). |
| `dashboardWidgets` | KPIs, gráficos e tabelas que o plugin contribui ao dashboard. |
| `events` | Eventos que o plugin emite no bus (`agenda.booking.confirmed`, …). |
| `aiTools` | Ferramentas que um agente de IA pode chamar (modo `read` ou `persist`). |
| `capabilities` | As capacidades declaradas do plugin (para introspecção). |
| `entities` | Entidades de dados que o plugin registra para CRUD. |
| `permissions` / `declaredFeatures` | Features e ações para o controle de acesso. |
| `connectors` | Conectores para provedores externos (o plugin como addon de outro). |
| `migrations` | O SQL das tabelas que o plugin possui (convenção `plg_`), cada uma com `tenant_id` + RLS. |
| `diagnostics` | Pré-requisitos de backend que o `fayz doctor` verifica (RPCs, views, tabelas, env). |
| `onboarding` | Um fluxo de primeiro uso. |
| `locales` | Traduções (`en`, `pt-BR`, …). |

Você declara só o que usa. Um plugin mínimo — como o gerado pelo incubator — traz `id`, `name`, `icon`, `version`, `navigation` e `routes`, e nada mais.

## `apiVersion`: o contrato tem versão

O campo opcional `apiVersion` fixa a versão do contrato de plugin que o manifesto foi escrito para. O runtime **recusa** um plugin construído para um contrato mais novo do que ele suporta — é o mecanismo que impede um plugin de uma geração futura de rodar meio quebrado numa plataforma antiga. Omitir significa "compatível/legado".

## Por que declarativo

O manifesto ser dado (e não código imperativo) é o que dá as três propriedades que sustentam a plataforma:

- **Introspecção** — a plataforma sabe exatamente o que um plugin contribui sem executá-lo; é assim que o `fayz doctor` verifica pré-requisitos e o editor monta seletores.
- **Simetria** — um plugin app-local e um oficial usam o mesmo tipo, então promover um é empacotar, não reescrever.
- **Segurança de upgrade** — os seams são um contrato versionado; a implementação por trás deles pode mudar livremente.

---

Próximo: as convenções que mantêm um plugin bem-comportado em [Padrões](/pt-BR/docs/plugins-proprios/padroes).