# Manifesto do plugin — referência

A referência completa do `PluginManifest` — cada campo que um plugin pode declarar e o que o runtime faz com ele. Para a introdução conceitual, veja [Manifesto do plugin](/pt-BR/docs/plugins-proprios/manifesto).

O tipo canônico vive em `@fayz-ai/core` (`PluginManifest`). Um plugin — oficial ou app-local — é sempre uma factory que devolve este objeto.

## Campos de identidade

| Campo | Tipo | Obrigatório | Descrição |
| --- | --- | --- | --- |
| `id` | `string` | sim | Identificador único do plugin. |
| `name` | `string` | sim | Nome exibido. |
| `icon` | `string` | sim | Nome do ícone. |
| `version` | `string` | sim | Versão do plugin (semver). |
| `apiVersion` | `number` | não | Versão do contrato de plugin. O runtime recusa um plugin construído para um contrato mais novo do que suporta. Omitir = legado/compatível. |
| `description` | `string` | não | Descrição curta. |
| `scope` | `PluginScope` | não | `core` · `vertical` · `universal` · `addon` · `tenant`. |
| `verticalId` | `VerticalId` | não | `beauty` · `food` · `health` · `services` · `retail` · `education` · (custom). |
| `scaffolds` | `ScaffoldType[]` | não | Scaffolds que o plugin suporta. Omitir = universal. |
| `defaultEnabled` | `boolean` | não | Se já vem ligado. |
| `dependencies` | `string[]` | não | Ids de outros plugins de que depende. |
| `tenantId` | `string` | não | Vincula o plugin a um tenant específico (instâncias por tenant). |
| `schema` | `string` | não | Schema de banco em que as tabelas do plugin vivem. |

## UI e navegação

| Campo | Tipo | Obrigatório | Descrição |
| --- | --- | --- | --- |
| `navigation` | `PluginNavigationEntry[]` | sim | Itens de menu. Cada um: `section` (`main`/`secondary`/`settings`), `position`, `label`, `route`, `icon?`, `badge?`, `permission?`. |
| `routes` | `PluginRouteDefinition[]` | sim | Rotas. Cada uma: `path`, `component` **ou** `componentId`, `guard?` (`authenticated`/`role`/`public`/`share-token`), `roles?`, `permission?`, `fullBleed?`. |
| `settings` | `PluginSettingsTab[]` | não | Abas na tela de configurações. `id`, `label`, `component`/`componentId`, `order?`, `permission?`. |
| `widgets` | `PluginWidgetDefinition[]` | não | Componentes injetados em zonas do shell. `id`, `zone` (`WidgetZone`), `component`/`componentId`, `order?`, `visibility?`. |
| `dashboardWidgets` | `DashboardWidgetDef[]` | não | KPIs/gráficos/tabelas contribuídos ao dashboard. `id`, `title`, `kind` (`kpi`/`chart`/`table`/`onboarding`/`custom`), `span?`, `surfaces?`. |
| `onboarding` | `PluginOnboarding` | não | Fluxo de primeiro uso. `component`/`componentId`, `title?`, `description?`. |

> **Componente por valor ou por id:** em toda parte (rotas, abas, widgets), você fornece **ou** `component` (o componente React direto) **ou** `componentId` (um id resolvido pelo registry) — exatamente um.

## Comportamento e integração

| Campo | Tipo | Descrição |
| --- | --- | --- |
| `events` | `PluginEventDefinition[]` | Eventos que o plugin emite no bus. `name` namespaced (`agenda.booking.confirmed`), `description?`, `payloadSchema?`. |
| `capabilities` | `PluginCapability[]` | Capacidades declaradas. `id`, `label`, `kind?` (`page`/`widget`/`data`/`integration`). |
| `aiTools` | `PluginAITool[]` | Ferramentas para um agente de IA. `id`, `name`, `description`, `mode` (`read`/`persist`), `parameters?`, `permission?`, `suggestions?`. |
| `connectors` | `ConnectorDefinition[]` | Conectores para provedores externos (o plugin como addon de um host). Veja o catálogo de [Integrações](/pt-BR/docs/plugins/integracoes). |
| `registries` | `PluginRegistryDef[]` | Entidades registradas com `seedData`/`mockData` e display (`table`/`cards`/`tree`). |

## Dados, permissões e diagnóstico

| Campo | Tipo | Descrição |
| --- | --- | --- |
| `entities` | `string[]` | Entidades de dados que o plugin registra. |
| `permissions` | `string[]` | Permissões que o plugin usa. |
| `declaredFeatures` | `FeatureDeclaration[]` | Features declaradas para o controle de acesso. |
| `migrations` | `PluginMigration[]` | O SQL das tabelas do plugin. Cada uma: `id`, `version`, `sql`, `description?`. |
| `diagnostics` | `PluginDiagnostic[]` | Pré-requisitos de backend verificados pelo `fayz doctor`. `requires` (`rpcs`/`views`/`tables`/`migrations`/`env`), `level?` (`error`/`warn`/`info`). |
| `locales` | `Record<string, Record<string, string>>` | Traduções por idioma. |

## Exemplo mínimo

O plugin gerado pelo incubator — o menor manifesto válido e útil:

```ts
import type { PluginManifest } from '@fayz-ai/core'

export function createFidelidadePlugin(): PluginManifest {
  const Page = () => /* ... */ null
  return {
    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 }],
  }
}
```

## Exemplo com seams

O mesmo plugin declarando dados, permissões e um diagnóstico:

```ts
return {
  id: 'fidelidade',
  name: 'Fidelidade',
  icon: 'Puzzle',
  version: '0.1.0',
  apiVersion: 1,
  navigation: [{ section: 'main', position: 50, label: 'Fidelidade', route: '/fidelidade', icon: 'Award' }],
  routes: [{ path: '/fidelidade', component: Page }],
  permissions: ['fidelidade:read', 'fidelidade:write'],
  migrations: [{ id: 'fidelidade-0001', version: '0.1.0', sql: 'create table fid_points (...)' }],
  diagnostics: [
    { id: 'fid-tables', requires: { tables: ['fid_points'] }, level: 'warn' },
  ],
  locales: {
    'pt-BR': { 'fidelidade.title': 'Fidelidade' },
    en: { 'fidelidade.title': 'Loyalty' },
  },
}
```

---

Próximo: a ferramenta que valida tudo isso em [CLI](/pt-BR/docs/referencia/cli).