emcp-tools-mapping/docs/08-INTEGRACOES-TERCEIROS.md

# 08 — Integrações com plugins de terceiros (ACF, Meta Box, Forms, SEO, WooCommerce)

Fonte: leitura directa do código-fonte `emcp-tools` v3.12.1 (build Free), instalado em
`emanuelalmeida.pt` (`/home/ealmeida/emanuelalmeida.pt/wp-content/plugins/emcp-tools/`),
19-08-2026. Cobre as classes que ligam o EMCP Tools a dados/estruturas geridas por outros
plugins: ACF, Meta Box, plugins de formulários (Contact Form 7 no Free) e plugins de SEO
(Slim SEO no Free), mais o inventário de integrações Pro-only que a árvore Free referencia
mas não contém (WooCommerce, 8 plugins de formulários adicionais, 6 plugins de SEO
adicionais, 2 pacotes de widgets Elementor, e a Ultimate Addons for Elementor).

Contexto arquitectural (ver `docs/00-ARQUITECTURA.md`): toda ability regista-se via
`emcp_tools_register_ability()` — nunca `wp_register_ability()` directamente —, que normaliza o
schema, envolve o `execute_callback` num veto de escrita (`emcp_tools_before_write`) e num
`normalize_result()` (garante retorno sempre objecto JSON), antes de delegar ao core. O gating
de cada grupo vem de `includes/abilities/class-ability-registrar.php` (lido na íntegra nesta
tarefa) — os excertos exactos são reproduzidos abaixo, não parafraseados.

## 0. Padrão comum às cinco integrações deste documento: o "dispatcher de dois braços"

Todas as cinco famílias (ACF, Meta Box, Forms, SEO — WooCommerce presumivelmente também,
mas Pro) seguem a MESMA forma: em vez de registar N abilities MCP individuais (uma por
operação), registam **exactamente duas** — um tool `<domínio>-read` e um tool `<domínio>-write` —
cada uma com o schema `{ operation?: string, arguments?: object }`. Chamar sem `operation`
devolve um catálogo de descoberta (`{ mode, operations: [{operation, description, ...}] }`);
chamar com `operation` despacha para um executor interno. Isto é o MESMO padrão de "compact tool
mode" que o dispatcher global de 3 tools usa ao nível do servidor inteiro (`docs/00`, §4) —
aqui aplicado ao nível de CADA integração de terceiros, mantendo o catálogo total de abilities
pequeno mesmo com dezenas de operações internas por plugin.

Duas implementações distintas deste padrão coexistem no código:

1. **ACF e Meta Box** — cada classe implementa o dispatcher "à mão" (método `dispatch()`
   privado + `operations()` que devolve o mapa nome→{mode,run,perm,desc,...}). Não há classe
   base partilhada entre ACF e Meta Box.
2. **Forms e SEO** — têm uma classe base abstracta partilhada por TODAS as integrações da
   categoria (`EMCP_Tools_Form_Integration`, `EMCP_Tools_SEO_Integration`), da qual CF7 e Slim
   SEO (Free) e os 8+6 plugins Pro (não presentes nesta árvore) herdam. A base implementa
   `register()`, `dispatch()`, o catálogo de descoberta, o schema `{operation,arguments}` e uma
   gate de confirmação genérica (`confirm: true` obrigatório em `arguments` para operações
   marcadas `confirm=>true` no mapa de operações — mecanismo de "são irreversíveis" ainda por
   usar em CF7/Slim SEO Free, mas presumivelmente usado pelos plugins Pro com delete de
   entradas/redirects).

**Nuance de segurança repetida nas 4 classes**: o `permission_callback` registado no MCP (a
"porta grossa" que decide se o tool sequer aparece/corre) é sempre uma capacidade **larga**
(`edit_posts` para leitura; para escrita varia — ver tabelas abaixo). A gate **fina e real** por
operação corre DENTRO do `dispatch()`, comparando com o `perm` específico de cada operação do
mapa `operations()`. Um utilizador pode assim ver o tool `acf-write` listado mas ser recusado
(`forbidden`) ao tentar `create-field-group` se só tiver `edit_posts` e não `manage_options`.

## 1. ACF (Advanced Custom Fields / ACF PRO)

**Ficheiro:** `includes/abilities/class-acf-abilities.php` (1627 linhas — a maior classe de
abilities do plugin). **Classe:** `EMCP_Tools_ACF_Abilities`. **Desde:** 3.2.1.

**Condição de registo** (`class-ability-registrar.php`):
```php
// ACF abilities — only when Advanced Custom Fields (free or Pro) is active.
if ( class_exists( 'EMCP_Tools_ACF_Abilities' ) && EMCP_Tools_ACF_Abilities::acf_active() ) {
	$acf = new EMCP_Tools_ACF_Abilities();
	$acf->register();
	...
}
```
`acf_active()` = `function_exists('acf_get_field_groups')` (ACF free OU Pro, qualquer versão
recente). Sem gate de licença Pro do EMCP em si — funciona com ACF free.

### 1.1 Abilities MCP registadas (2)

| Ability | Input schema | Descrição | `permission_callback` | readonly/destructive |
|---|---|---|---|---|
| `emcp-tools/acf-read` | `{ operation?: string, arguments?: object }` | Lê dados ACF: field groups, valores de campos, options pages, e (ACF 6.1+) CPTs/taxonomias geridos por ACF. Sem `operation` → catálogo. | `check_read_permission()` = `current_user_can('edit_posts')` | readonly=true, destructive=false, idempotent=true |
| `emcp-tools/acf-write` | `{ operation?: string, arguments?: object }` | Escreve dados ACF (valores, field groups, CPTs/taxonomias). **Escritas desligadas por omissão** (activar em Tools → Plugins → ACF). Sem `operation` → catálogo. | `check_read_permission()` — **nota**: a gate registada no MCP é a mesma de leitura; a gate real de escrita (`manage_options`/`edit_post`) corre por operação dentro de `dispatch()` | readonly=false, destructive=false, idempotent=false |

### 1.2 As 15 operações internas (via `operation` + `arguments`)

| operação | modo | `perm` (capability) | requer ACF 6.1+? | O que faz |
|---|---|---|---|---|
| `list-field-groups` | read | `check_read_permission` (`edit_posts`) | não | Lista field groups: `key, id, title, active, local, field_count`. Args opcionais: `post_id` (filtra por contexto), `search`, `active_only` (default true). |
| `get-field-group` | read | `check_read_permission` | não | Devolve um field group completo: `location` rules + árvore recursiva de campos (`sub_fields`/`layouts` até profundidade 10). Args: `{ key }` (key ou ID numérico). |
| `list-options-pages` | read | `check_read_permission` | não | Lista options pages ACF (feature PRO; vazio em ACF free). Sem args. |
| `get-fields` | read | `check_fields_permission` (`edit_post`/`manage_options` conforme alvo) | não | Lê valores de campos de um post ou options page. Args: `{ post_id }` OU `{ options_page }`; opcionais `{ fields: string[] }` (filtra), `{ include_field_objects: bool }` (envolve valor com type/label). |
| `list-post-types` | read | `check_manage_permission` (`manage_options`) | **sim** | Lista CPTs geridos por ACF (`acf-post-type` CPT interno). |
| `get-post-type` | read | `check_manage_permission` | **sim** | Devolve um CPT ACF completo por `{ key }`. |
| `list-taxonomies` | read | `check_manage_permission` | **sim** | Lista taxonomias geridas por ACF. |
| `get-taxonomy` | read | `check_manage_permission` | **sim** | Devolve uma taxonomia ACF completa por `{ key }`. |
| `update-fields` | write | `check_fields_permission` | não | Escreve valores de campos (incl. linhas repeater/flexible/gallery) num post ou options page. Args: `{ post_id\|options_page, fields: {name: value} }`. Campos de tipo PRO (repeater/flexible_content/gallery/clone) recusados se ACF não for Pro. Linhas de `flexible_content` validadas contra `acf_fc_layout` conhecido. Regista before-image no Change Ledger (`EMCP_Tools_Change_Recorder::record_acf_fields`) se essa classe existir. |
| `create-field-group` | write | `check_manage_permission` | não | Cria um field group com campos + location rules via `acf_import_field_group()` (persiste no CPT `acf-field-group`; NÃO usa `acf_add_local_field_group()`, que seria só memória). Args: `{ title, fields: [...], location?: [[...]] }`. |
| `update-field-group` | write | `check_manage_permission` | não | Edita um field group **guardado em BD**: título, location, active, position, adiciona novos campos (`add_fields`), altera settings mutáveis de campos existentes (`update_fields`). **Recusa** grupos `local` (registados por acf-json/PHP) e qualquer alteração a `name`/`type` de um campo existente (imutáveis — evitaria orfanar postmeta). Sem delete. |
| `create-acf-post-type` | write | `check_manage_permission` | **sim** | Regista um CPT via ACF (dados, sem código) usando `acf_import_post_type()`. Args: `{ post_type, title, singular?, public?, hierarchical?, show_in_rest?, supports?, has_archive?, taxonomies? }`. Slug validado contra 21 slugs reservados do WordPress (`post`, `page`, `attachment`, etc.). |
| `update-acf-post-type` | write | `check_manage_permission` | **sim** | Edita um CPT ACF existente por `{ key }`. **Slug imutável** (recusa se `post_type` no input difere do actual — orfanaria conteúdo). |
| `create-acf-taxonomy` | write | `check_manage_permission` | **sim** | Regista uma taxonomia via ACF. Args: `{ taxonomy, title, object_type: string[] (post types), singular?, hierarchical?, public?, show_in_rest? }`. |
| `update-acf-taxonomy` | write | `check_manage_permission` | **sim** | Edita uma taxonomia ACF existente por `{ key }`. **Slug imutável** (orfanaria termos). |

`cpt_tax_supported()` = `function_exists('acf_get_acf_post_types') && acf_get_acf_taxonomies && acf_import_post_type && acf_import_taxonomy` (ACF 6.1+). Operações CPT/tax são omitidas do catálogo de descoberta e recusam com `acf_cpt_tax_unsupported` se a versão for anterior.

### 1.3 Decisões de design não óbvias (ACF)

- **Escrita sempre por `field_key`, nunca por `name`**: comentário no código — `update_field()` por nome falha silenciosamente em alvos que ainda não têm valor guardado para o campo. O resolvedor de campo (`resolve_field()`) tenta: (1) prefixo `field_` directo via `acf_get_field()`, (2) índice por nome/key construído a partir dos field groups aplicáveis ao alvo, (3) fallback `get_field_object()` para alvos options sem valor guardado ainda.
- **`update_field()` não confia no valor de retorno**: devolve `false` também num no-op (valor idêntico), por isso o sucesso é confirmado por uma releitura (`get_field()`) após cada escrita, não pelo booleano.
- **Índice de campos por request, invalidado após escrita**: `field_index_cache` (array associativo por `target`) evita relistar field groups a cada operação, mas é explicitamente apagado (`unset`) após `update-fields`/`create-field-group`/`update-field-group` para uma leitura subsequente no mesmo request ver o estado fresco.
- **Options pages sem lookup reverso**: ACF não tem forma de mapear um alvo `options` de volta aos seus field groups; o índice cai para (a) todo o field group com QUALQUER regra `location` de tipo `options_page`, mais (b) `get_field_objects()` para capturar campos já guardados mesmo sem regra de localização detectável.
- **Normalização de valores**: `WP_Post`/`WP_User`/`WP_Term` viram resumos compactos (`{id, title/name, ...}`); arrays de imagem/ficheiro ACF (`return_format=array`) reduzidos a `{id, url, alt, mime}` em vez do array completo (que inclui `sizes` com dezenas de entradas).
- **Sem delete, em lado nenhum**: nem field groups, nem campos, nem valores, nem CPTs/taxonomias — write-only-forward. Confirma o padrão documentado no cabeçalho do ficheiro: "there is deliberately NO delete tool".

## 2. Meta Box (metabox.io)

**Ficheiro:** `includes/abilities/class-metabox-abilities.php`. **Classe:**
`EMCP_Tools_Meta_Box_Abilities`. **Desde:** 3.4.2.

**Condição de registo:**
```php
// Meta Box abilities — only when Meta Box (free or extensions) is active.
if ( class_exists( 'EMCP_Tools_Meta_Box_Abilities' ) && EMCP_Tools_Meta_Box_Abilities::metabox_active() ) {
	$metabox = new EMCP_Tools_Meta_Box_Abilities();
	$metabox->register();
	...
}
```
`metabox_active()` = `defined('RWMB_VER') && function_exists('rwmb_get_registry')`.

### 2.1 Abilities MCP registadas (2)

| Ability | Input schema | Descrição | `permission_callback` | readonly/destructive |
|---|---|---|---|---|
| `emcp-tools/metabox-read` | `{ operation?, arguments? }` | Lê field groups Meta Box registados, as suas definições de campo, e valores de campo num post/objecto. | `check_read_permission()` = `edit_posts` | readonly=true, idempotent=true |
| `emcp-tools/metabox-write` | `{ operation?, arguments? }` | Escreve valores de campo Meta Box. **Desligado por omissão** (Tools → Plugins → Meta Box). | `check_read_permission()` — mesma nota que ACF: gate real é por operação | readonly=false, destructive=false, idempotent=false |

### 2.2 As 4 operações internas

| operação | modo | Descrição |
|---|---|---|
| `list-field-groups` | read | Lista meta boxes registados: `id, title, object_type, post_types[], field_count`. Args opcionais: `search`, `object_type`. |
| `get-field-group` | read | Um meta box completo por `{ id }`: título, object_type, post_types, árvore de campos recursiva (campos `clone`/group aninhados até profundidade 10). |
| `get-fields` | read | Lê valores via `rwmb_meta()`. Args: `{ post_id }` OU `{ object_type, object_id }`; opcionais `{ fields: string[], include_field_settings: bool }`. |
| `update-fields` | write | Escreve valores via `rwmb_set_meta()` (não devolve nada — confirmação por releitura). Args: `{ post_id\|object_type+object_id, fields: {id: value} }`. |

Ambas as operações de leitura/escrita têm o mesmo `perm`: `check_read_permission`/`check_fields_permission` — sem distinção read/write op-a-op como no ACF (só há uma operação de escrita).

### 2.3 Diferenças-chave face ao ACF

- **Meta Box free core não tem UI de construção de campos** — campos são declarados em PHP via o filtro `rwmb_meta_boxes`. Por isso NÃO HÁ authoring de field groups/CPT/taxonomia aqui (ao contrário do ACF) — só leitura de definições e leitura/escrita de VALORES.
- **Nomenclatura invertida face ao ACF**: no Meta Box, o `id` de um campo É a meta key (equivalente ao `name` do ACF), e `name` é o label humano (equivalente ao `label` do ACF) — nota explícita no cabeçalho do ficheiro por ser uma fonte comum de confusão ao portar lógica entre as duas integrações.
- **`applicable_fields()`**: para alvos `post`, só considera meta boxes cujo `post_types` inclui o tipo do post concreto (Meta Box permite meta boxes restritos a post types específicos); para outros `object_type`, aceita todas as meta boxes desse tipo sem mais filtragem.
- **Normalização de valor**: reconhece o formato específico de imagem/ficheiro do Meta Box — array associativo com `ID`+`url` E (`full_url` OU `path` OU `mime_type`) — distinto da assinatura ACF (`ID`+`url`+`mime_type`).
- **`resolve_target()` tem um caso de normalização subtil**: `{ object_type:'post', object_id:N }` sem `post_id` é reescrito internamente para o caminho `post_id` (garante o mesmo 404-check e gate `edit_post` que `{post_id:N}` receberia diretamente).

## 3. Forms — infra-estrutura genérica (`EMCP_Tools_Form_Integration`)

**Ficheiro:** `includes/abilities/forms/class-form-integration.php`. **Classe:** classe base
abstracta `EMCP_Tools_Form_Integration`. **Desde:** 3.5.0. Directório `forms/` no Free contém
apenas ESTE ficheiro + `class-cf7-integration.php` — nenhum outro ficheiro de plugin de
formulário existe nesta árvore (confirmado por listagem directa, secção 6).

### 3.1 Contrato abstracto

Cada integração concreta implementa:
- `id(): string` — id curto, usado para construir os nomes dos tools (`<id>-read`/`<id>-write`).
- `label(): string` — label humano.
- `is_active(): bool` — se o plugin de formulários alvo está activo.
- `operations(): array<string,array>` — mapa `nome => { mode, run, perm, desc, confirm? }`.

`is_available()` (usado pelo registrar para decidir se regista) = `is_active()` por omissão.

### 3.2 O que a base fornece a TODAS as integrações de formulários

- **`register()`** — regista os dois tools `<id>-read`/`<id>-write` com o schema partilhado
  `{ operation?, arguments? }`. Meta annotations do tool write: `readonly=false, destructive=true,
  idempotent=false` — nota: **destructive=true por omissão na base**, diferente de ACF/Meta
  Box/SEO (que marcam `destructive=false`) — reflecte que integrações Pro de formulários
  provavelmente apagam entradas/submissões, uma operação genuinamente destrutiva que CF7 (sem
  armazenamento de submissões) nunca exerce.
- **`can_read()`** = `edit_posts`; **`can_write()`** = `manage_options` — ambas as gates coarse
  registadas no MCP; a gate real corre por operação via `$op['perm']`.
- **`dispatch()`** — resolve `operation`, verifica `is_active()` (senão `plugin_inactive`, HTTP 409),
  valida a operação existe no modo certo (`unknown_operation`, HTTP 404), corre `$op['perm']`
  (`forbidden`, HTTP 403), e — **gate de confirmação genérica**: se `$op['confirm']===true`,
  exige `arguments.confirm===true` (senão `confirmation_required`, HTTP 400); o campo `confirm`
  é removido de `$args` antes de chamar o executor real (não polui o input do handler).
- **Sem mecanismo de change-ledger automático** — ao contrário da base SEO (secção 4), a base
  Forms não regista snapshots before-image; qualquer undo teria de ser implementado por
  integração concreta.

## 4. Contact Form 7 (integração Free com ficheiro dedicado)

**Ficheiro:** `includes/abilities/forms/class-cf7-integration.php`. **Classe:**
`EMCP_Tools_CF7_Integration extends EMCP_Tools_Form_Integration`. **Desde:** 3.5.0.

**Condição de registo:**
```php
if ( class_exists( 'EMCP_Tools_CF7_Integration' ) ) {
	$form_integrations[] = new EMCP_Tools_CF7_Integration();
}
... // depois, para todos os $form_integrations:
foreach ( $form_integrations as $form_integration ) {
	if ( $form_integration->is_available() ) {
		$form_integration->register();
		...
	}
}
```
`is_active()` = `class_exists('WPCF7_ContactForm') || defined('WPCF7_VERSION')`. Nenhum gate de
licença Pro do EMCP — CF7 é a ÚNICA integração de formulários incluída no build Free.

Verificado contra Contact Form 7 6.1.6 (comentário no cabeçalho do ficheiro lista a superfície
API usada: `WPCF7_ContactForm::find()`, `::get_instance()`, `->id()/->name()/->title()`,
`->scan_form_tags()`, `->prop()`, `->set_properties()+->save()`).

### 4.1 Abilities MCP registadas (2, via a base)

| Ability | Descrição gerada (`label().' Read/Write'`) | `permission_callback` |
|---|---|---|
| `emcp-tools/cf7-read` | "Contact Form 7, read operations. Call with no operation to list them." | `can_read()` = `edit_posts` |
| `emcp-tools/cf7-write` | "Contact Form 7, write operations..." | `can_write()` = `manage_options` |

### 4.2 As 7 operações internas

| operação | modo | `perm` (capability CF7 real) | Descrição |
|---|---|---|---|
| `list-forms` | read | `wpcf7_read_contact_forms` (≈`edit_posts`) | Lista todos os formulários CF7: `id, title, slug, field_count`. |
| `get-form` | read | idem | Um formulário completo por `{ form_id }`: `fields[], mail, mail_2, messages, additional_settings`. |
| `list-notifications` | read | idem | Os dois templates de email (`mail`, `mail_2`) por `{ form_id }`. |
| `get-settings` | read | idem | `messages` + `additional_settings` por `{ form_id }`. |
| `update-notification` | write | `wpcf7_edit_contact_forms` (≈`publish_pages`) | Actualiza um template de email por merge (não substitui): `{ form_id, notification: "mail"\|"mail_2", mail: {subject?, sender?, recipient?, body?, additional_headers?, attachments?, use_html?, active?} }`. |
| `update-messages` | write | idem | Actualiza mensagens de validação/resposta por merge: `{ form_id, messages: {key: value} }`. |
| `update-form-settings` | write | idem | Substitui por completo o bloco Additional Settings: `{ form_id, additional_settings: string }`. |

**Nota**: os `perm` reais aqui são MAIS finos que a gate coarse da base (`can_write()=manage_options`)
— usam as capacidades nativas do CF7 (`wpcf7_edit_contact_forms`), que por omissão mapeiam para
`publish_pages`, não `manage_options`. Um editor sem `manage_options` mas com `publish_pages` é
assim recusado pela gate coarse do MCP (`can_write`) ANTES sequer de chegar à gate fina do CF7 —
uma limitação prática: a capability CF7 nativa nunca é realmente exercida nesta implementação
porque a gate MCP é mais restritiva.

**CF7 não guarda submissões** (sem addon Flamingo/DB próprio) — por isso não há operações de
"entries" (ao contrário do que os 8 plugins Pro de formulários presumivelmente expõem, dado
todos guardarem submissões nativamente).

## 5. SEO — infra-estrutura genérica (`EMCP_Tools_SEO_Integration`)

**Ficheiro:** `includes/abilities/seo/class-seo-integration.php`. **Classe:** base abstracta
`EMCP_Tools_SEO_Integration`. **Desde:** 3.5.0. Directório `seo/` no Free contém apenas ESTE
ficheiro + `class-slimseo-integration.php`.

Distinção documentada no cabeçalho: isto é **diferente** do toolkit Pro SEO & Accessibility
(`audit-page-seo`/`generate-meta-tags`, ver doc 01/02), que ANALISA e GERA em vez de
ler/escrever os dados que um plugin de SEO já guarda.

### 5.1 Contrato abstracto

Mesma forma que Forms: `id()`, `label()`, `is_active()`, `operations()`. Diferenças de
comportamento da base face a Forms:

- **`can_read()`** = `edit_posts`; **`can_write()`** = `edit_posts` (não `manage_options` —
  escrever SEO de um post é uma operação de editor normal, não administrativa).
- **Meta annotations do tool write**: `readonly=false, destructive=false, idempotent=false` —
  ao contrário de Forms, aqui `destructive=false` por omissão (escritas de metadados SEO nunca
  apagam dados irrecuperáveis por si mesmas).
- **Change-ledger automático (feature exclusiva da base SEO, ausente em Forms/ACF/Meta Box)**:
  para qualquer operação de modo `write` cujos `arguments` incluam `post_id` ou `term_id`, a base
  chama `recordable_meta_keys($object)` (que cada integração concreta sobrepõe — devolve as meta
  keys que ela escreve para esse tipo de objecto; vazio por omissão = sem registo automático),
  tira um `snapshot_meta()` (before-image dessas keys) ANTES de correr o executor, e — se o
  resultado não for `WP_Error` e `EMCP_Tools_Change_Log` existir — grava uma entrada
  `{domain:'seo', action:'update', target:'<id>:<object>:<obj_id>', rollback:{type:'meta-before-image', object, id, before}}`.
  Isto dá rollback automático a TODAS as integrações SEO que declarem as suas meta keys, sem cada
  uma ter de implementar a lógica de undo.

### 5.2 Abilities MCP e a mesma gate de confirmação

A `dispatch()` reutiliza a MESMA forma de Forms: catálogo sem `operation`, `plugin_inactive`
(409) se `is_active()` falhar, `unknown_operation` (404), `forbidden` (403) por `$op['perm']`,
`confirmation_required` (400) se `$op['confirm']===true` e `arguments.confirm` não for `true`.

## 6. Slim SEO (integração Free com ficheiro dedicado)

**Ficheiro:** `includes/abilities/seo/class-slimseo-integration.php`. **Classe:**
`EMCP_Tools_SlimSEO_Integration extends EMCP_Tools_SEO_Integration`. **Desde:** 3.5.0.

**Condição de registo:**
```php
if ( class_exists( 'EMCP_Tools_SlimSEO_Integration' ) ) {
	$seo_integrations[] = new EMCP_Tools_SlimSEO_Integration();
}
... // depois, para todos os $seo_integrations, mesma forma que Forms:
foreach ( $seo_integrations as $seo_integration ) {
	if ( $seo_integration->is_available() ) { $seo_integration->register(); ... }
}
```
`is_active()` = `defined('SLIM_SEO_VER')`. Slim SEO é a ÚNICA integração de SEO incluída no build
Free. Armazenamento confirmado ao vivo (comentário "Verified live" no cabeçalho): um único array
meta `slim_seo` por post/termo (chaves: `title, description, canonical, noindex, nofollow,
facebook_image, twitter_image`), mais uma option `slim_seo` para as definições do site.

### 6.1 Abilities MCP registadas (2, via a base)

| Ability | `permission_callback` |
|---|---|
| `emcp-tools/slimseo-read` | `can_read()` = `edit_posts` |
| `emcp-tools/slimseo-write` | `can_write()` = `edit_posts` |

### 6.2 As 5 operações internas

| operação | modo | `perm` | Descrição |
|---|---|---|---|
| `get-post-seo` | read | `edit_posts` | Metadados SEO de um post por `{ post_id }`: `title, description, canonical, noindex, nofollow, og_image, twitter_image` (view unificada — ver mapeamento abaixo). |
| `get-term-seo` | read | `edit_posts` | Idem para `{ term_id }`. |
| `get-settings` | read | `manage_options` | Definições SEO do site (a option `slim_seo`). |
| `update-post-seo` | write | `edit_posts` | Actualiza por merge campo-a-campo: `{ post_id, title?, description?, canonical?, noindex?, nofollow?, og_image?, twitter_image? }`. |
| `update-term-seo` | write | `edit_posts` | Idem para `{ term_id, ... }`. |

`recordable_meta_keys()` sobreposto para devolver `['slim_seo']` (a única meta key, para
qualquer `$object`) — activa o registo automático no Change Ledger da base para AMBAS as
operações de escrita.

### 6.3 Camada de mapeamento field↔meta-key

A classe mantém um `map(): array<string,string>` que traduz o vocabulário unificado do EMCP
(`title, description, canonical, noindex, nofollow, og_image, twitter_image`) para as chaves
reais do array `slim_seo` do plugin (`title, description, canonical, noindex, nofollow,
**facebook_image**, twitter_image` — nota: só `og_image`→`facebook_image` difere). `read_view()`
e `apply()` usam este mapa nos dois sentidos; `noindex`/`nofollow` são forçados a booleano
(`!empty()`), o resto passa por `(string)` quando escalar.

## 7. WooCommerce e demais integrações Pro-only — não presentes neste build

O `class-ability-registrar.php` referencia 18 classes de integração via `class_exists()` que
**não existem em nenhum ficheiro desta árvore Free** — confirmado por listagem directa de
`includes/abilities/` (topo), `includes/abilities/forms/`, `includes/abilities/seo/`, e
`includes/` (topo, todas as subpastas), sem grep recursivo disponível nesta sessão (as
ferramentas `glob`/`grep` não recursam paths `ssh://`; a confirmação foi feita listando cada
directório candidato e comparando os nomes de ficheiro presentes contra os nomes de classe
referenciados). Nenhum destes ficheiros existe nesta instalação — não há schemas nem
comportamento a documentar; só a metadata de gating, copiada verbatim do registrar.

| Classe (referência no registrar) | Plugin de terceiros integrado | Condição de gating exacta (copiada do registrar) |
|---|---|---|
| `EMCP_Tools_Woo_Integration` | WooCommerce | `class_exists( 'EMCP_Tools_Woo_Integration' ) && EMCP_Tools_Woo_Integration::woo_active()` — comentário no código: "WooCommerce abilities (Pro) — only when WooCommerce is active." |
| `EMCP_Tools_WPForms_Integration` | WPForms | `function_exists('emcp_tools_fs') && emcp_tools_fs()->can_use_premium_code()` (licença Pro) **E** `class_exists($classe)` **E** depois `$integration->is_available()` (= `is_active()`, plugin alvo activo) — comentário: "CF7 is free; the five [sic, na prática oito] entry-storing plugins are Pro. Each registers only when its plugin is active." |
| `EMCP_Tools_GravityForms_Integration` | Gravity Forms | idem (mesmo loop, mesma tripla gate: licença Pro + ficheiro presente + plugin activo) |
| `EMCP_Tools_FluentForms_Integration` | Fluent Forms | idem |
| `EMCP_Tools_NinjaForms_Integration` | Ninja Forms | idem |
| `EMCP_Tools_Formidable_Integration` | Formidable Forms | idem |
| `EMCP_Tools_MetForm_Integration` | MetForm | idem |
| `EMCP_Tools_SureForms_Integration` | SureForms | idem |
| `EMCP_Tools_Forminator_Integration` | Forminator | idem |
| `EMCP_Tools_Yoast_Integration` | Yoast SEO | `function_exists('emcp_tools_fs') && emcp_tools_fs()->can_use_premium_code()` **E** `class_exists($classe)` **E** `$integration->is_available()` — comentário: "Slim SEO is free; the other 6 are Pro. Each registers only when its SEO plugin is active." |
| `EMCP_Tools_RankMath_Integration` | Rank Math | idem |
| `EMCP_Tools_AIOSEO_Integration` | All in One SEO | idem |
| `EMCP_Tools_SeoPress_Integration` | SEOPress | idem |
| `EMCP_Tools_SEOFramework_Integration` | The SEO Framework | idem |
| `EMCP_Tools_SureRank_Integration` | SureRank | idem |
| `EMCP_Tools_EssentialAddons_Integration` | Essential Addons for Elementor | Só `class_exists( 'EMCP_Tools_EssentialAddons_Integration' )` **E** `$addon_pack->is_available()` — **sem** o gate explícito `emcp_tools_fs()->can_use_premium_code()` no laço (ao contrário de Forms/SEO); comentário: "Elementor addon widget packs (Pro). Each pack contributes ONE read tool for discovery + curation; widgets are placed with the generic add-free-widget tool, so there is deliberately no write tool here." O ficheiro simplesmente não existe fora do build Pro, logo `class_exists()` é sempre falso no Free independentemente de licença. |
| `EMCP_Tools_PremiumAddons_Integration` | Premium Addons for Elementor | idem (mesmo laço, mesma ausência de gate de licença explícito no registrar) |
| `EMCP_Tools_UAE_Integration` | Ultimate Addons for Elementor (anteriormente Header Footer Elementor) | `class_exists( 'EMCP_Tools_UAE_Integration' )` **E** `$emcp_uae->is_available()` — comentário: "Ultimate Addons for Elementor (Pro)... Both a widget pack AND a data plugin, so unlike the pure packs it keeps the house read/write dispatcher pair: discovery + templates on read, templates on write." |

**Nota adicional confirmada pelo registrar** (fora do escopo directo desta tarefa mas
adjacente): outras integrações de "Themes-tab" também Pro-only e ausentes desta árvore —
`EMCP_Tools_GeneratePress_Integration`, `EMCP_Tools_GenerateBlocks_Integration`,
`EMCP_Tools_Blocksy_Blocks_Integration`, `EMCP_Tools_Blocksy_Extensions_Integration` — todas só
`class_exists()` + `is_available()`, sem gate de licença explícito no laço (mesmo padrão de
EssentialAddons/PremiumAddons/UAE). Não fazem parte do escopo pedido (ACF/MetaBox/Forms/SEO/Woo)
mas são citadas aqui por confirmarem o padrão: **todas** as integrações Pro deste plugin usam
`class_exists()` simples como gate primário — a distinção Free/Pro é feita por PRESENÇA DE
FICHEIRO (a pasta `emcp-pro/` inclui-os, `emcp-tools/` não), não por uma verificação de licença
em runtime dentro de cada laço de registo individual (excepto forms/SEO, que adicionam
explicitamente `emcp_tools_fs()->can_use_premium_code()` como segunda camada — provavelmente
porque esses 14 ficheiros de facto existem no zip Pro mas o acesso à FUNCIONALIDADE ainda
depende de licença activa, ao contrário dos addon-packs/UAE, que talvez sejam gratuitos dentro do
próprio Pro sem sub-gate de licença adicional).

## 8. Blueprint para réplica

**Copiar quase 1:1:**
- **O padrão de dispatcher de dois braços** (`<domínio>-read`/`<domínio>-write`, catálogo sem
  `operation`, despacho por `operation`+`arguments`) — é a peça que mantém o catálogo total de
  tools pequeno com dezenas de integrações possíveis. Vale a pena ter DUAS variantes conforme a
  complexidade: dispatcher "à mão" para integrações com estado rico e reaproveitamento pesado
  (ACF, Meta Box — cada uma tem a sua própria noção de "target"/"field index"), e uma classe base
  abstracta partilhada para famílias homogéneas de integrações simples-mas-numerosas (Forms, SEO)
  onde cada concreta só define `operations()` + os `run` callables.
- **A gate de confirmação genérica da base** (`confirm: true` obrigatório em `arguments` para
  operações marcadas `confirm=>true`) — mecanismo barato e reutilizável para qualquer operação
  irreversível futura (delete de entrada de formulário, delete de redirect, etc.), sem cada
  integração ter de reimplementar a checagem.
- **O change-ledger automático da base SEO** (`recordable_meta_keys()` + snapshot before-image +
  `EMCP_Tools_Change_Log::record()`) é o exemplo mais elegante deste documento: dá rollback
  automático a qualquer integração que declare as suas meta keys, com ZERO código extra por
  integração concreta. **Recomendação forte**: subir este padrão para a base Forms também (hoje
  ausente lá) e generalizar para ACF/Meta Box (hoje cada uma implementa o seu próprio snapshot
  ad-hoc — ACF via `EMCP_Tools_Change_Recorder::record_acf_fields`, Meta Box sem qualquer
  registo). Um único mecanismo de "snapshot de meta keys antes de escrever" partilhado por TODAS
  as integrações de terceiros pouparia manutenção e cobriria o gap do Meta Box.
- **Escrita sempre por identificador estável** (ACF: sempre por `field_key`, nunca por `name`) —
  é uma lição de bug real ("silently fails on targets that have no stored value yet"), replicar
  esta disciplina em qualquer integração própria que tenha um par nome-humano/chave-estável.
- **Imutabilidade de slug/tipo em updates** (ACF post-type/taxonomy slug; CF7 sem rename de
  formulário) — recusar explicitamente mudanças que orfanariam dados existentes é barato e evita
  uma classe inteira de bugs de integridade referencial silenciosa.

**Simplificar:**
- **O gate duplo de licença Pro em Forms/SEO** (`can_use_premium_code()` + `class_exists()` +
  `is_available()`) é redundante para uma réplica que não tem modelo de negócio Free/Pro — uma
  reescrita própria só precisa da terceira camada (`is_active()`/plugin alvo instalado).
- **A normalização de valores por tipo de objecto WP** (`WP_Post`/`WP_User`/`WP_Term` →
  resumos compactos) está duplicada quase verbatim entre ACF e Meta Box (`normalize_value()`
  em cada classe, com pequenas variações de forma de imagem/ficheiro). Vale a pena extrair um
  helper único partilhado (`EMCP_Tools_Value_Normalizer::normalize($value)`) parametrizável por
  "assinatura de imagem/ficheiro" (ACF: `ID+url+mime_type`; Meta Box: `ID+url` + uma de
  `full_url`/`path`/`mime_type`) em vez de reimplementar a árvore recursiva duas vezes.

**Deixar de fora (ou adiar bastante):**
- **CPT/taxonomia "managed by ACF"** (ACF 6.1+) é uma feature de nicho (a maioria dos sites
  regista CPTs por código, não pela UI do ACF) — só vale a pena replicar se o público-alvo da
  réplica usar isto activamente. É também a parte mais frágil (7 das 15 operações ACF, gate por
  versão, slugs reservados) — maior superfície de manutenção por unidade de valor entregue.
- **Options pages ACF** — feature exclusivamente Pro do plugin de terceiros; sem ACF Pro
  instalado esta parte do código é sempre um array vazio. Só vale a pena manter o "stub" que
  devolve `{pro: false, pages: []}` graciosamente, não investir em lógica adicional.

**Risco/gotcha não óbvio encontrado no código (citação directa):**
- `class-ability-registrar.php`, comentário no `try/catch` de `register_all()`: "Ability
  registration runs on every admin page load and every REST request, so an exception here is a
  site-wide fatal: wp-admin becomes unreachable... (issue #100, where a host malware scanner had
  quarantined one of our class files, leaving `require_once` satisfied but the class undeclared).
  No single tool group is worth locking an admin out of their own site." — **implicação directa
  para as 5 integrações deste documento**: cada bloco de registo (ACF, Meta Box, cada form/SEO
  integration) corre dentro deste `try/catch` amplo a nível de `register_groups()`; um erro fatal
  ao construir QUALQUER uma destas classes (ex. uma versão incompatível de ACF que remova uma
  função que o código assume existir) não derruba o site — simplesmente essa família de tools
  fica ausente do catálogo, silenciosamente, com log via `error_log`. Uma réplica DEVE envolver o
  registo de cada grupo de integração de terceiros no mesmo tipo de guarda — nunca deixar uma
  dependência externa instável poder tirar o wp-admin do ar.
- ACF `execute_update_fields()`: comentário explícito sobre a armadilha de escrever por `name`
  em vez de `key` — já citado acima, mas vale reforçar como o exemplo mais concreto de "testámos
  em produção e partiu" que este documento encontrou.
- Meta Box `resolve_target()`: a normalização silenciosa de `{object_type:'post', object_id:N}`
  para o caminho `post_id` é subtil — sem ela, alguém podia contornar o `edit_post` gate passando
  o post por `object_type`+`object_id` em vez de `post_id` directo (dois caminhos de input para o
  mesmo alvo, só um gated correctamente, se não fosse esta normalização).

## Fonte

Leitura directa (19-08-2026) de:
`includes/abilities/class-acf-abilities.php` (1627 linhas, completo),
`includes/abilities/class-metabox-abilities.php` (completo),
`includes/abilities/forms/class-form-integration.php` (completo),
`includes/abilities/forms/class-cf7-integration.php` (completo),
`includes/abilities/seo/class-seo-integration.php` (completo),
`includes/abilities/seo/class-slimseo-integration.php` (completo),
`includes/abilities/class-ability-registrar.php` (completo, 480+ linhas — todo o `register_groups()`).
Listagem directa (não grep recursivo, indisponível para paths `ssh://` nesta sessão) dos
directórios `includes/abilities/`, `includes/abilities/forms/`, `includes/abilities/seo/` e
`includes/` (topo, todas as subpastas) para confirmar a AUSÊNCIA física de qualquer ficheiro das
18 classes Pro-only listadas na secção 7. Cruzado com `docs/00-ARQUITECTURA.md` (mesma sessão de
documentação) para o contrato de `emcp_tools_register_ability()` e o padrão de dispatcher de
compact tool mode ao nível do servidor.