emcp-tools-mapping/docs/03-WORDPRESS-CORE-TEMAS.md

03 — WordPress core (conteúdo/media/settings/plugins/temas/users/menus) e integrações de temas/frameworks de blocos

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. Ver docs/00-ARQUITECTURA.md para o contrato emcp_tools_register_ability() e o padrão de arranque; este documento assume esse contexto e não o repete.

Este grupo cobre duas famílias distintas de abilities:

1. WordPress core puro (content, media, settings, plugins, themes, users, nav menus) — sempre activas, sem dependência de Elementor nem de nenhum framework de terceiros.
2. Integrações de temas/frameworks de blocos (Astra, Spectra, Kadence, Kadence Blocks) — o padrão "Themes tab" de dois dispatchers (<id>-read/<id>-write) por integração, cada uma condicional à presença do tema/plugin correspondente. Free tem 5 integrações concretas (Active Theme + Astra + Spectra + Kadence + Kadence Blocks); GeneratePress/GenerateBlocks/ Blocksy são referenciadas no registrar mas não existem como ficheiros no build Free (ver §16).

1. EMCP_Tools_Content_Abilities — includes/abilities/class-content-abilities.php

Condição de registo: sempre-on (register_groups() linha ~158, sem guarda). Deliberadamente agnóstico ao Elementor — opera sobre post_content (HTML clássico ou markup de blocos Gutenberg) e nunca toca em _elementor_data.

8 tools. check_read_permission=edit_posts; check_create_permission=edit_posts (mesmo cap que ler — mimetiza o core WP, onde publicar é gated à parte); check_edit_permission=edit_posts

• edit_post por-post quando há post_id; check_delete_permission=delete_posts + delete_post por-post.

Tool	Input (resumo)	O que faz	Permission	RO/Destr.
list-post-types	public_only?:bool (default true)	Lista post types registados (nome, label, hierárquico, supports, taxonomias); filtra internos (revision, nav_menu_item, wp_template, etc.) quando public_only.	check_read_permission	RO
list-taxonomies	post_type?, include_terms?:bool, terms_limit?:int (≤500, default 100)	Lista taxonomias (opcionalmente filtradas por post type), com termos embutidos opcionais.	check_read_permission	RO
create-post	post_type?(default post), title, content, excerpt, status?(enum draft/publish/pending/private/future), slug?, author?, date?, parent?, menu_order?, comment_status?, terms?:{tax:ids[]}, meta?:{}, featured_image?:{id|url}|null	wp_insert_post(). Recusa post types internos/inexistentes; publish exige publish_posts; author diferente do actual exige edit_others_posts; meta protegida (_-prefix ou is_protected_meta) é sempre recusada salvo allowlist via filtro emcp_tools_content_allowed_protected_meta. featured_image.url faz sideload via EMCP_Tools_Url_Guard::safe_download() (SSRF-guarded, bloqueia hosts privados/loopback/metadata cloud e revalida cada redirect). Regista change (EMCP_Tools_Change_Recorder::record_post_create).	check_create_permission	write, não-destr.
get-post	post_id	Serialização completa: title/slug/status/content/excerpt/datas/parent/menu_order/comment_status/permalink/edit_link/author/terms/meta(filtrada)/featured_image/is_elementor (flag _elementor_edit_mode==='builder').	check_read_permission	RO
update-post	post_id, campos parciais iguais ao create + terms_mode?(replace/append)	Update parcial via wp_update_post(). Captura before-image (campos + meta + terms) para rollback via Change_Recorder::record_post_fields. Se o slug muda num post publicado, captura o URL antigo e sugere um redirect (with_redirect_suggestion → EMCP_Tools_Redirect_Abilities::push_suggestion, só quando EMCP_Tools_Redirect_Module::is_enabled()).	check_edit_permission	write, não-destr.
delete-post	post_id, force?:bool	force=false (default): wp_trash_post(). force=true: snapshot completo (Change_Recorder::snapshot_post) antes de wp_delete_post($id,true) (reversível). Ambos os caminhos sugerem redirect para o URL morto.	check_delete_permission	write, destrutivo
list-posts	post_type?(str|array), status?(str|array), search?, taxonomy?:{tax:terms[]}(AND), author?, parent?, per_page?(≤100), page?, orderby?, order?	WP_Query paginado, linhas compactas (sem body de conteúdo — usar get-post para isso).	check_read_permission	RO
set-post-terms	post_id, taxonomy, terms:(int|string)[], mode?(replace/append/remove), create_missing?:bool(default true)	wp_set_object_terms/wp_remove_object_terms. Quando create_missing=false, resolve nomes para IDs existentes via get_term_by(name→slug) e descarta os que não existem (não cria).	check_edit_permission	write, não-destr.

Detalhe de implementação notável: apply_write_extras() é o método partilhado usado por create-post/update-post para aplicar terms/meta/featured_image — inclui o comentário explícito no código sobre porquê carrega wp-admin/includes/{file,media,image}.php on-demand: essas funções (media_handle_sideload) não estão carregadas em pedidos REST/WP-CLI (que é onde o servidor MCP corre).

2. EMCP_Tools_Media_Library_Abilities — includes/abilities/class-media-library-abilities.php

Condição: sempre-on (linha ~143). Nasceu para preencher a lacuna que as tools de stock-image não cobrem: encontrar as fotos próprias do cliente já na Media Library (issue #25 do repo upstream). Recebe EMCP_Tools_Data no construtor (data-access layer partilhada — mesma classe usada por várias famílias de abilities de conteúdo Elementor, não específica de media).

5 tools.

Tool	Input (resumo)	O que faz	Permission	RO/Destr.
list-media	search?, mime_type?(default image; aceita "any"), page?, per_page?(≤100), orderby?(date/title), order?	WP_Query sobre attachment. O search do WP_Query cobre title/caption/description mas não alt text (vive em postmeta) — por isso resolve IDs por texto e por alt em duas queries ids-only e faz a união via post__in, sem filtros globais de query.	check_read_permission (edit_posts)	RO
get-media	id	Detalhe completo de 1 attachment: todos os tamanhos de imagem registados (url+dimensões via wp_get_attachment_image_src por tamanho), mime, filesize, alt, caption, descrição, autor, post_parent, metadata bruta.	check_read_permission	RO
upload-media	filename, data(base64, aceita prefixo data:...;base64,), alt?, title?, caption?, description?, post_id?, convert_webp?:bool	Companheira de sideload-image: sideload-image busca um URL que o SERVIDOR alcança; upload-media recebe bytes RAW do CLIENTE (útil quando o utilizador quer enviar um ficheiro do seu próprio computador). Decodifica base64 (limite UPLOAD_MAX_BYTES=32MB, filtrável via emcp_tools_upload_media_max_bytes), escreve para wp_tempnam(), valida tipo com wp_check_filetype_and_ext() contra get_allowed_mime_types() (bloqueia executáveis mesmo que um filtro afrouxe depois), entrega a media_handle_sideload(). Suporta convert_webp:false via filtro emcp_tools_optimize_attachment (idêntico a sideload-image).	check_upload_permission (upload_files)	write, não-destr.
update-media	id, title?, alt?, caption?, description?	Update parcial. description mapeia para post_content e não é sanitize_text_field (permitiria HTML legítimo — wp_update_post já aplica wp_filter_post_kses para quem não tem unfiltered_html). Captura before-image para rollback.	check_edit_permission (por-attachment)	write, não-destr.
delete-media	id, confirm:true(obrigatório), force?:bool	Destrutivo e efectivamente permanente: WordPress ignora a Trash para media a menos que MEDIA_TRASH esteja definido — o próprio schema avisa disto na descrição. Snapshot completo antes de apagar (post + meta + cópia trashed de todos os ficheiros) via Change_Recorder::snapshot_attachment, só quando não vai para trash.	check_delete_permission (por-attachment)	write, destrutivo

3. EMCP_Tools_Settings_Abilities — includes/abilities/class-settings-abilities.php

Condição: sempre-on (linha ~224). Nome deliberadamente distinto de EMCP_Tools_Settings_Validator (que valida settings de widgets Elementor — classe não relacionada).

Decisão de design central: NÃO expõe get_option/update_option arbitrário. Só a allowlist tipada e curada em allowlist() — 32 chaves cobrindo os 6 ecrãs de Settings do core (General/Reading/Writing/Discussion/Media/Permalinks). Cada entrada tem {group, label, type (string|int|bool|enum), writable, options?, min?, max?, pattern?}. Notavelmente ausentes da allowlist: siteurl/home (lock-out do site), users_can_register/default_role (escalada de registo). admin_email está presente mas writable=false (só leitura).

2 tools, ambas check_manage_permission = manage_options.

Tool	Input	O que faz	RO/Destr.
get-settings	group?(enum dos 6 ecrãs), keys?:string[]	Sem args devolve as 32; filtra por grupo/chaves. Cada linha inclui value (coagido ao tipo declarado), writable, e options[] quando é enum — duplica como discovery para update-settings.	RO
update-settings	settings:{key:value}	Escreve só chaves allowlisted+writable; tudo o resto (chave desconhecida, read-only, valor inválido) cai em skipped[] com motivo — uma chave má nunca aborta o batch. Coerção por tipo com clamp min/max (int), regex pattern (string, ex. permalink_structure), validação de enum. Se qualquer permalink_structure/category_base/tag_base mudar, chama flush_rewrite_rules(false) automaticamente e reporta rewrite_flushed. Regista before-map para rollback.	write, não-destr. (idempotente)

4. EMCP_Tools_Plugin_Abilities — includes/abilities/class-plugin-abilities.php

Condição: sempre-on (linha ~229). 7 tools: 2 leitura (sempre activas) + 5 mutação (instalação/activação/desactivação/update/delete), todas construídas sobre APIs core (Plugin_Upgrader, plugins_api, activate_plugin/deactivate_plugins/delete_plugins) e guardadas por EMCP_Tools_Package_Guard (classe partilhada com theme-abilities — ver comentário do ficheiro: "as 5 tools de mutação vêm desligadas por omissão, o admin liga-as na tab Tools").

Tool	Input	O que faz	Permission	RO/Destr.
list-plugins	status?(all/active/inactive)	get_plugins() + get_site_transient('update_plugins') para flag de update disponível; inclui is_protected (via Package_Guard::is_protected_plugin).	activate_plugins	RO
search-plugins	search, per_page?(≤50)	plugins_api('query_plugins', …) — pesquisa no directório wordpress.org.	install_plugins	RO
install-plugin	slug, activate?:bool	plugins_api('plugin_information') → Plugin_Upgrader::install(). Fonte sempre wordpress.org — URLs arbitrários nunca são aceites (explicitamente afirmado na descrição da tool).	install_plugins	write, não-destr.
activate-plugin	plugin(file ou slug de pasta)	activate_plugin(). Resolve referência via resolve_plugin_file() (tenta como file exacto, depois como slug de pasta).	activate_plugins	write, idempotente
deactivate-plugin	plugin	deactivate_plugins(). Recusa plugins protegidos (EMCP Tools e Elementor nunca podem ser desactivados via MCP — protege contra o agente cortar o próprio ramo em que está sentado).	activate_plugins	write, idempotente
update-plugin	plugin	wp_update_plugins() refresca transient; se não há update pendente devolve up_to_date:true sem chamar o upgrader. Recusa plugins protegidos (mesma lista de deactivate).	update_plugins	write, não-destr.
delete-plugin	plugin	delete_plugins(). Recusa protegidos E recusa qualquer plugin activo (obriga a desactivar primeiro).	delete_plugins	write, destrutivo

5. EMCP_Tools_Theme_Abilities — includes/abilities/class-theme-abilities.php

Condição: sempre-on (linha ~233). Espelho exacto do padrão de plugin-abilities mas para temas (Theme_Upgrader, themes_api, switch_theme/delete_theme), mesmas 5+1 = 6 tools (sem search+install+switch+update+delete+list = 6, plugins tem 7 porque tem activate+deactivate separados; temas só têm switch-theme).

Tool	Input	O que faz	Permission	RO/Destr.
list-themes	(nenhum)	wp_get_themes() + get_site_transient('update_themes'); inclui parent (para child themes) e is_active.	switch_themes	RO
search-themes	search, per_page?(≤50)	themes_api('query_themes', …) sobre wordpress.org.	install_themes	RO
install-theme	slug, activate?:bool	themes_api('theme_information') → Theme_Upgrader::install(). Fonte sempre wordpress.org.	install_themes	write, não-destr.
switch-theme	stylesheet	switch_theme(). Recusa temas com $theme->errors() (load errors).	switch_themes	write, idempotente
update-theme	stylesheet	wp_update_themes() refresca transient; up_to_date:true sem upgrade se nada pendente.	update_themes	write, não-destr.
delete-theme	stylesheet	delete_theme(). Recusa o tema activo e o parent do tema activo (Package_Guard::active_theme_stylesheets()).	delete_themes	write, destrutivo

6. EMCP_Tools_User_Abilities — includes/abilities/class-user-abilities.php

Condição: sempre-on (linha ~238). O comentário de cabeçalho do ficheiro resume a filosofia: "the security boundary is the design" — sem tool de delete, sem tool de mudança de role, password sempre auto-gerada e nunca devolvida.

4 tools. Guarda de privilégio central: protected_caps() = {manage_options, promote_users, delete_users, edit_users, manage_network}. user_has_admin_caps($id) verifica se um utilizador tem QUALQUER uma destas caps (via user_can) — se sim, é intocável por update-user. role_has_admin_caps($role) faz o mesmo a nível de role, para bloquear create-user de atribuir uma role admin-grade.

Tool	Input	O que faz	Permission	RO/Destr.
list-users	role?, search?, per_page?(≤100), page?, orderby?(registered/display_name/ID), order?	WP_User_Query. Linhas compactas (id, username, display_name, email, roles, registered, post_count) — nunca password/auth.	list_users	RO
get-user	id	Detalhe: username/email/display_name/first_name/last_name/nickname/url/description/roles/registered/post_count + flag is_admin (= user_has_admin_caps, sinaliza que update-user vai recusar).	list_users	RO
create-user	username, email, role?(default subscriber), first_name?, last_name?, display_name?, url?, description?	Password gerada com wp_generate_password(24, true, true) (nunca devolvida). Envia email de "definir password" via wp_send_new_user_notifications($id, 'user'). Recusa role inexistente ou admin-grade. Anti-enumeração: erros existing_user_login/existing_user_email são normalizados para uma mensagem genérica ("that username or email is not available") para que a tool não sirva para enumerar contas existentes.	create_users	write, não-destr.
update-user	id, email?, first_name?, last_name?, display_name?, nickname?, url?, description?	Recusa se o alvo tem admin-caps. Constrói o update só a partir dos campos permitidos — role/password nunca são sequer lidos do input, logo nunca podem mudar aqui (não é uma verificação em runtime, é ausência estrutural do campo). Captura before-image para rollback.	edit_users	write, não-destr.

7. EMCP_Tools_Nav_Menu_Abilities — includes/abilities/class-nav-menu-abilities.php

Condição: sempre-on (linha ~243). Padrão de dois dispatchers (menu-read/menu-write), o mesmo padrão que as integrações de tema (§9-13) e as abilities ACF/SEO/forms (doc 08) usam: cada tool aceita {operation, arguments}; chamar sem operation devolve o catálogo de operações disponíveis (nome + descrição) — auto-descoberta sem precisar de schemas JSON per-operation separados. Ambos os dispatchers usam a mesma permissão: edit_theme_options.

13 operações no total:

Operação	Modo	Argumentos	O que faz
list-menus	read	{}	Todos os menus: id, name, slug, item count, locations atribuídas.
get-menu	read	{menu: id|slug|name}	Um menu + a sua árvore de items aninhada (build_item_tree, construída a partir da lista flat via menu_item_parent).
list-locations	read	{}	Locations de menu registadas pelo tema + qual menu (se algum) está atribuído a cada uma.
render	read	{menu|location, depth?, container?, container_class?, menu_class?, menu_id?}	wp_nav_menu(['echo'=>false]) → devolve HTML. Útil para embutir num header custom.
create-menu	write	{name}	wp_create_nav_menu().
rename-menu	write	{menu, name}	wp_update_nav_menu_object().
delete-menu	write	{menu}	wp_delete_nav_menu().
assign-location	write	{menu, location}	set_theme_mod('nav_menu_locations', …). Valida que a location está registada pelo tema.
unassign-location	write	{location}	Remove a atribuição de uma location.
add-item	write	{menu, type, object_id?, object?, url?, title?, parent?, position?, target?, classes?, description?, xfn?}	wp_update_nav_menu_item(). resolve_item_type() valida type (custom/page/post/CPT/category/taxonomy) contra objectos reais existentes — nunca cria um item apontando para um post/termo inexistente. Items custom exigem url+title.
update-item	write	{item, title?, url?, parent?, position?, target?, classes?, description?, xfn?}	Update parcial que preserva todos os campos não especificados (merge_existing_item() lê o item actual via wp_setup_nav_menu_item() antes de mesclar as mudanças — evita a armadilha comum de wp_update_nav_menu_item de apagar campos omitidos).
delete-item	write	{item}	wp_delete_post($id, true) (items de menu são posts nav_menu_item).
reorder-items	write	{menu, items: [{id, parent?, position}]}	Reordena/reparenta múltiplos items numa chamada, preservando os restantes campos de cada um (reutiliza merge_existing_item). Ignora silenciosamente items inválidos/de outro menu/com parent inválido, e conta só os efectivamente actualizados.

Validações estruturais notáveis: validate_parent() garante que um parent proposto é um item de menu real e pertence ao mesmo menu (não permite cruzar menus). resolve_item_type() faz a mesma validação de existência para add-item que set-post-terms faz para termos — nunca cria referências soltas.

8. EMCP_Tools_Image_Resize_Abilities — includes/abilities/class-image-resize-abilities.php

Condição: condicional dupla (registrar linha ~149) — só regista quando class_exists( 'EMCP_Tools_Image_Resize_Abilities' ) E class_exists( 'EMCP_Tools_Image_Optimization_Module' ) E EMCP_Tools_Image_Optimization_Module::module_is_active(). Ou seja: depende do módulo "Image Optimization" (um dos 9 módulos opcionais documentados no doc 10) estar activo — reutiliza a maquinaria de backup+compressão+WebP desse módulo (EMCP_Tools_Image_Resizer::resize(), classe do módulo, não desta ability).

1 tool: resize-media. attachment_id, width?, height? (pelo menos um dos dois; escala mantendo aspect ratio), crop?:bool (hard-crop exacto width×height, requer ambos). Permissão: edit_post($attachment_id) se especificado, senão upload_files. O ID do attachment e as suas URLs mantêm-se os mesmos (resize in-place), o original é feito backup (reversível), e todos os sub-tamanhos + WebP são regenerados. Se o cap de dimensão máxima do módulo for menor que o alvo pedido, o cap aplica-se silenciosamente.

9. EMCP_Tools_Theme_Integration (abstract) — includes/abilities/class-theme-integration.php

Serviço de suporte, não regista abilities por si — é a classe base abstracta para todas as integrações de tema/framework (§10-13 + os Pro-only do §16). Implementa o padrão "dois dispatchers" de forma genérica e reutilizável.

Contrato abstracto que cada subclasse implementa: id() (usado para construir os nomes das tools emcp-tools/<id>-read/-write), label(), is_available() (gate de disponibilidade — tema activo ou plugin activo), operations() (o mapa name => {mode, run, perm, desc}).

A base fornece:

• register() — regista os dois dispatchers via emcp_tools_register_ability(). Ambos usam o mesmo dispatch_schema() genérico ({operation?, arguments?}).
• can_read()/can_write() — gate grosseiro da tool (edit_theme_options por omissão); cada subclasse pode sobrepor (Spectra e Kadence Blocks sobrepõem para edit_posts, porque constroem conteúdo, não opções de tema — ver §12/§13).
• dispatch() — resolve a operação pelo nome; se operation vazio devolve o catálogo de descoberta; valida que o modo (read/write) bate; corre a permissão específica da operação ($op['perm']) — nunca confia só no gate grosseiro do tool, cada operação individual re-verifica. Um erro 404 unknown_operation ou 403 forbidden tem status no WP_Error data.
• capabilities() — descritor normalizado (supports_patterns, supports_preview, styles_model: none/uniqueid/styles-object/attributes) que um agente lê para saber, sem hard-coding por-framework, se este pack tem uma rota de inserção "editor-válida" (patterns) ou preview, e como o pack se auto-estiliza. Default {false, false, 'none'}; cada subclasse sobrepõe.

Blueprint chave: este é o padrão a copiar quase 1:1 numa réplica própria — uma classe base abstracta de ~250 linhas que qualquer integração de tema/plugin de terceiros herda, ganhando discovery + dispatch + permission-per-operation de graça. Adicionar um framework novo (ex. GeneratePress) é só escrever a subclasse concreta com operations().

10. EMCP_Tools_Active_Theme_Integration — includes/abilities/class-active-theme-integration.php

id()='theme'. is_available() = sempre true (funciona com qualquer tema activo — é o pack agnóstico-de-framework). Descrição do ficheiro: "Building pages reuses the Gutenberg/Elementor tools; this integration supplies the context the agent reasons over."

4 operações:

Operação	Modo	Argumentos	O que faz
get-theme-context	read	{}	Identidade + capacidades do tema activo: stylesheet/parent, is_child, framework detectado (contra KNOWN_FRAMEWORKS = {astra, kadence, generatepress, oceanwp, blocksy, neve, hello-elementor}), is_block_theme (wp_is_block_theme()), nome/versão, template_dir, theme supports probed (PROBED_SUPPORTS: post-thumbnails, custom-logo, editor-styles, wp-block-styles, align-wide, responsive-embeds, custom-background, html5), menu locations registadas, has_child (Child_Theme_Builder::child_exists()). "Call this first" — é o ponto de entrada de contexto antes de qualquer outra operação de tema.
get-mods	read	{}	Todos os theme_mods do tema activo (estado do customizer).
set-mods	write	{values: {key: value}}	set_theme_mod() por chave, salvo REFUSED_MODS = {nav_menu_locations, sidebars_widgets, custom_css_post_id} — mods estruturais recusados (esses domínios têm as suas próprias tools: nav-menu, widgets não têm tool própria, custom CSS é módulo separado).
create-child-theme	write, perm=can_manage_theme (switch_themes+edit_theme_options)	{confirm:true}(obrigatório)	Delega para EMCP_Tools_Child_Theme_Builder::create() (§14). Exige confirm:true porque muda o tema activo E liga escrita de ficheiros.

11. EMCP_Tools_Astra_Integration — includes/abilities/class-astra-integration.php

id()='astra'. is_available() = 'astra' === get_template(). Lê/escreve a única option astra-settings sobre uma allowlist curada de 17 chaves (ALLOWLIST const), agrupadas em colors/typography/layout/header-footer — a mesma forma genérica get/update que EMCP_Tools_Settings_Abilities usa para o core WordPress (§3), aplicada ao option próprio do Astra. Allowlist explicitamente marcada como "verified against Astra 4.13.4 on the dev site".

2 operações: get-settings ({group?, keys?}) e update-settings ({values:{key:value}}, chaves não-allowlisted em skipped[]). read_value() prefere o resolver nativo astra_get_option() quando disponível (respeita o default do tema quando a option está ausente); senão cai no valor bruto da option. Detalhe de invalidação de cache notável: Astra só refresca o seu CSS dinâmico em cache no hook customize_save_after, não numa escrita simples de option — por isso execute_update_settings() chama explicitamente astra_clear_all_assets_cache() após qualquer update, senão as mudanças ficariam invisíveis até o próximo save do Customizer.

12. EMCP_Tools_Spectra_Integration — includes/abilities/class-spectra-integration.php

id()='spectra'. is_available() = EMCP_Tools_Spectra_Catalog::is_active(). Sobrepõe can_read()/can_write() para edit_posts (constrói conteúdo, não opções de tema). capabilities(): {supports_patterns:false, supports_preview:false, styles_model:'attributes'}.

3 operações — o padrão discover→inspect→act espelhando o catálogo de widgets Elementor:

Operação	Modo	Argumentos	O que faz
list-blocks	read	{category?, search?}	Catálogo compacto (via Spectra_Catalog::blocks_index()).
get-block-schema	read	{name?|names?[], full?}	Atributos reais + defaults (Spectra_Catalog::real_attributes()) + markup de exemplo gerado. Reporta também shared_attributes (ver §12.1) e um note quando trunca à DEFAULT_CAP=30.
add-block	write	{post_id, block, attributes?, position?}	Constrói o array de bloco parseado (build_block()), insere-o via EMCP_Tools_Block_Tree::insert() (serviço partilhado com Gutenberg — doc 02) na árvore existente do post, serializa de volta com serialize_block(), grava com wp_update_post. Gera block_id via EMCP_Tools_Id_Generator::generate().

12.1 EMCP_Tools_Spectra_Catalog — includes/blocks-catalog/class-spectra-catalog.php

Serviço de suporte (não regista abilities). Nada é adivinhado — as duas metades vêm do próprio Spectra:

• Lista de blocos — UAGB_Block_Module::get_blocks_info() (a própria API pública do Spectra).
• Atributos por bloco — lidos directamente do ficheiro fonte do Spectra includes/blocks/<slug>/attributes.php (via require, não introspecção de registry) — porque Spectra não regista todos os atributos no WP_Block_Type_Registry core.

STRUCTURE const documenta hints estruturais que não podem vir de attributes.php: quais blocos precisam de innerBlocks template (uagb/buttons→uagb/buttons-child, etc., 8 pares documentados) e quais são dinâmicos/server-rendered (post-grid, post-carousel, google-map, forms, etc. — add-block emite markup self-closing para estes).

SHARED_ATTRS é o achado mais interessante desta classe: documenta atributos nativos e reais do uagb/container que são registados via um helper partilhado (UAGB_Block_Helper) em vez de chaves literais em attributes.php — por isso não aparecem em real_attributes(), mas existem e são editáveis (background image/video com overlay, border-radius por canto, box-shadow). O comentário no código é explícito: "so they DO NOT appear in real_attributes()/get-block-schema, yet they are real, editable attributes an agent should use instead of a core/html workaround" — inclui até a gotcha exacta de que o overlay em gradiente vem de gradientValue, não de gradientOverlayColor1/2 como seria intuitivo.

13. EMCP_Tools_Kadence_Integration (theme settings) — includes/abilities/class-kadence-integration.php

id()='kadence'. is_available() = 'kadence' === get_template(). Lê/escreve theme_mods do Kadence (não uma option única como Astra) sobre uma allowlist de 16 chaves agrupadas em palette/colors/typography/layout/buttons/header-footer. Cada entrada da allowlist carrega um shape (string descritiva da forma do objecto esperado) — porque, ao contrário de Astra, os valores de Kadence são objectos estruturados, não escalares (ex. link_color = { highlight: "palette1", "highlight-alt": "palette2", style: "standard" }), e referenciam uma paleta global de 9 slots (palette1..palette9) definida em global_palette.

2 operações: get-settings/update-settings, mesma forma que Astra. read_value() prefere \Kadence\kadence()->option($key) (resolver nativo com theme_mod+default embutido). Sem invalidação de cache explícita — comentário do ficheiro nota que "Kadence renders dynamic CSS inline per request, so there is no cache to invalidate" (contraste directo com o gotcha do Astra em §11).

14. EMCP_Tools_Kadence_Blocks_Integration — includes/abilities/class-kadence-blocks-integration.php

id()='kadence-blocks'. is_available() = EMCP_Tools_Kadence_Blocks_Catalog::is_active(). Independente do tema activo (tal como Spectra — Kadence Blocks é um plugin, não amarrado ao tema Kadence). can_read()/can_write() = edit_posts. capabilities(): {supports_patterns:true, supports_preview:true, styles_model:'uniqueid'}.

5 operações — a mais rica das integrações de tema, porque acrescenta acesso à Kadence Prebuilt Library (patterns prontos) por cima do padrão discover→inspect→act:

Operação	Modo	Argumentos	O que faz
list-blocks	read	{category?, search?}	Catálogo curado dos 32 blocos top-level (via Kadence_Blocks_Catalog).
get-block-schema	read	{name?|names?[], full?}	Atributos reais do WP_Block_Type_Registry (Kadence, ao contrário do Spectra, regista schemas completos com defaults no core registry — não precisa de ler ficheiro fonte). Inclui inner_blocks hint para containers, content_attributes para campos RichText/HTML-source, e um editor_note fixo (ver abaixo).
add-block	write	{post_id, block, attributes?, position?}	Gera uniqueID (chave CSS por-bloco do Kadence), escafolda inner blocks de container conforme STRUCTURE, renderiza campos RichText directamente no HTML guardado (não no JSON de atributos — ver render_source_fields() abaixo).
list-patterns	read	{category?, search?, include_pro?, categories?:bool}	Lista patterns da Kadence Design Library (cache local em uploads/kadence_blocks_library/). categories:true devolve só os nomes de categoria.
insert-pattern	write	{post_id, pattern, position?, localize_images?:bool}	Insere markup canónico de um pattern (busca via Kadence_Blocks_Prebuilt_Library_REST_Controller::get_pattern_content — o próprio controller REST do Kadence, chamado internamente sem HTTP). localize_images:true transfere as imagens do pattern para a Media Library via o próprio process_pattern do Kadence (requer upload_files).

Nota de robustez notável em add-block: o output devolve sempre um note explícito — "Kadence blocks use a static JS save(), so a headlessly-inserted block renders correctly on the front end but the block editor may show 'Attempt recovery' on this block — one click regenerates valid markup and preserves the content." Isto é honestidade de design: blocos Kadence construídos à mão (não via pattern) não batem byte-a-byte com o save() estático do JS do bloco, então o editor Gutenberg vai reclamar (recuperável, sem perda de dados) — só o caminho insert-pattern (markup canónico do próprio Kadence) evita esse aviso.

render_source_fields() é o mecanismo mais complexo desta classe: para cada atributo que o registry marca como source: html|rich-text (ex. o content do Advanced Heading), renderiza o valor directamente em HTML dentro do bloco serializado usando o selector real registado por esse atributo (tag+classe), em vez de o guardar no JSON de attrs — porque é assim que WordPress lê esses valores de volta (parseados do HTML, não do JSON). Trata o caso especial "Advanced Heading" (selector_element()): a sua tag vem de htmlTag (h1-h6/p/div/span), e a classe CSS correcta é kt-adv-heading{uniqueID} — não o que o selector bruto do registry sugeriria.

14.1 EMCP_Tools_Kadence_Blocks_Catalog — includes/blocks-catalog/class-kadence-blocks-catalog.php

Serviço de suporte. Diferente do Spectra: ambas as metades (lista + atributos) vêm do WP_Block_Type_Registry core — Kadence regista schemas de atributos completos com defaults, não precisa de ler ficheiro fonte. TOP_LEVEL const lista os 32 slugs "placeable" (exclui blocos filho/estruturais como column-child, singlebtn, listitem, table-row, que são inseridos via STRUCTURE). TITLES/CATEGORY/HIGHLIGHT/STRUCTURE são curadoria manual (explicitamente "live-verified on Kadence Blocks 3.7.9" contra uma spec própria referenciada no comentário).

STRUCTURE['kadence/rowlayout'] tem uma gotcha documentada no comentário: colLayout tem de ser não-vazio ("equal") ou o editor mostra o picker "Select Your Layout" do Kadence em vez das colunas — "the frontend renders regardless" mas a experiência de edição fica quebrada sem isto.

14.2 EMCP_Tools_Kadence_Pattern_Library — includes/blocks-catalog/class-kadence-pattern-library.php

Serviço de suporte. Lê o cache local de metadados (uploads/kadence_blocks_library/*.json, distingue o ficheiro de metadata do de preview-HTML pela presença de slug+name nas entradas) e delega a obtenção do markup real ao controller REST do próprio Kadence (Kadence_Blocks_Prebuilt_Library_REST_Controller), invocado internamente (constrói um WP_REST_Request e chama o método directamente — sem round-trip HTTP). Nota explícita no cabeçalho do ficheiro: se a cache local estiver vazia, o utilizador precisa de abrir a Kadence Design Library uma vez no editor de blocos para a popular — a tool list-patterns devolve esse aviso quando detecta catálogo vazio.

15. EMCP_Tools_Child_Theme_Builder — includes/class-child-theme-builder.php

Serviço de suporte, usado por Active_Theme_Integration::execute_create_child_theme (§10). Deliberadamente conservador, três garantias explícitas no comentário de cabeçalho:

1. Só cria um child do parent actualmente activo — nunca toca noutro tema.
2. Recusa quando o tema activo já é um child (is_active_a_child()) — nunca cria um "neto" (grandchild).
3. Idempotente — um child existente é apenas activado (switch_theme), nunca sobrescrito.

create(): cria a pasta (wp_mkdir_p), gera style.css mínimo (cabeçalho Theme Name/Template/ Version/Description) e functions.php mínimo (enfileira o style.css do parent via wp_enqueue_scripts), depois switch_theme($slug). Escreve via $wp_filesystem->put_contents() quando inicializado, senão file_put_contents() directo — o mesmo padrão dual usado pelas Filesystem tools (doc 07). Devolve {child, parent, directory, activated, created}.

É o enabler estrutural para edição de ficheiros de tema pelo agente: depois de criar o child, o agente edita style.css/functions.php/templates via as tools de Filesystem (ABSPATH-confined, gated por edit_files, com backup e audit-log — doc 07), nunca directamente aqui.

16. Pro-only confirmados ausentes: GeneratePress, GenerateBlocks, Blocksy

class-ability-registrar.php linhas 342-355 referencia 4 classes adicionais de integração de tema, seguindo o comentário explícito no código: "GeneratePress + GenerateBlocks (Pro; classes only present when Pro loaded)" e "Blocksy (Pro): blocks + Companion extensions."

if ( class_exists( 'EMCP_Tools_GeneratePress_Integration' ) ) { … }
if ( class_exists( 'EMCP_Tools_GenerateBlocks_Integration' ) ) { … }
if ( class_exists( 'EMCP_Tools_Blocksy_Blocks_Integration' ) ) { … }
if ( class_exists( 'EMCP_Tools_Blocksy_Extensions_Integration' ) ) { … }

Confirmado por listagem directa do directório includes/abilities/ neste build Free (19-08-2026, 48 ficheiros class-*.php listados): nenhum ficheiro class-generatepress-integration.php, class-generateblocks-integration.php, class-blocksy-blocks-integration.php ou class-blocksy-extensions-integration.php existe. As 4 classes são referenciadas apenas pelo class_exists() gate — em produção Free, este gate é sempre false; as 4 integrações só passam a existir (ficheiro + classe) quando o build Pro (emcp-pro/) está instalado e activo.

Cada uma seguiria, por analogia estrutural às 5 integrações Free já lidas (§10-14), o mesmo padrão herdado de EMCP_Tools_Theme_Integration (§9):

Classe (Pro-only, código não acessível)	Gating no registrar	Padrão inferido por analogia (não confirmado)
EMCP_Tools_GeneratePress_Integration	class_exists()	id()='generatepress' provavelmente; is_available() provavelmente 'generatepress' === get_template() — tema settings via GP Premium/GenerateBlocks options, seguindo o molde Astra/Kadence (§11/§13).
EMCP_Tools_GenerateBlocks_Integration	class_exists()	Pack de blocos GenerateBlocks (catálogo + add-block), seguindo o molde Spectra/Kadence Blocks (§12/§14) — seria o "blocks/builder" companion do GeneratePress.
EMCP_Tools_Blocksy_Blocks_Integration	class_exists()	Pack de blocos Blocksy (a Blocksy tem os seus próprios blocos Gutenberg nativos).
EMCP_Tools_Blocksy_Extensions_Integration	class_exists()	Gestão de "Extensions" do Blocksy (o painel de extensões modulares do tema — ex. Content Blocks, Custom Fonts, Ecommerce, etc.), provavelmente um dispatcher settings-like análogo ao Astra.

Não inventar schemas nem comportamento além desta inferência estrutural — sem acesso ao código fonte destas 4 classes, este é o limite do que se pode documentar com honestidade.

Blueprint para réplica

Copiar quase 1:1:

• EMCP_Tools_Theme_Integration (abstract, §9) — o padrão de 2 dispatchers + discovery + permission-per-operation é genérico, pequeno (~250 linhas), e escala bem para qualquer novo framework/plugin de terceiros. É o único ponto de extensão que vale a pena manter exactamente como está numa réplica.
• EMCP_Tools_Settings_Abilities (§3) e o padrão allowlist tipada — a decisão de nunca expor get_option/update_option cru é a protecção certa; a allowlist com {type, writable, min, max, pattern, options} é suficientemente expressiva sem ser um mini-JSON-Schema paralelo. Reutilizar esta forma para settings de qualquer plugin de terceiros (Astra/Kadence já o fazem).
• Guarda de privilégio de User_Abilities (§6) — protected_caps() + user_has_admin_caps/ role_has_admin_caps é uma barreira de segurança simples e correcta (nenhuma tool de delete, role/password nunca lidos do input de update). Copiar tal e qual.
• Package_Guard (referenciado por Plugin/Theme abilities, §4/§5) — lista de protecção (nunca desactivar/apagar/actualizar o próprio plugin nem o Elementor) é um padrão de auto-preservação que qualquer plugin MCP-serving precisa de replicar (senão o agente pode cortar o próprio ramo em que está sentado).
• Child_Theme_Builder (§15) — as 3 garantias conservadoras (só o parent activo, nunca um grandchild, idempotente) são exactamente as invariantes certas para este tipo de operação.

Simplificar:

• Kadence Blocks render_source_fields()/selector_element() (§14) — é código correcto mas bastante intrincado (resolve selectors CSS de volta para tag+classe HTML por heurística). Numa réplica que não precise de suportar Kadence Blocks especificamente, este é o tipo de complexidade a NÃO reinventar — só vale a pena se formos mesmo integrar Kadence Blocks.
• Spectra_Catalog::real_attributes() a fazer require de um ficheiro fonte de outro plugin (§12.1) é frágil a mudanças de versão do Spectra (o caminho do ficheiro é hard-coded); preferir, quando possível, ler do WP_Block_Type_Registry (como Kadence faz) em vez de abrir ficheiros fonte de terceiros directamente — só recorrer a isto quando o plugin de terceiros não regista todos os atributos no registry core (razão pela qual o Spectra precisou desta técnica).

Deixar de fora (a menos que haja procura real de clientes):

• As 4 integrações Pro-only (§16) — só valem a pena reimplementar quando houver um cliente concreto a usar GeneratePress/GenerateBlocks/Blocksy. Sem acesso ao código nem à base de utilizadores, seria trabalho especulativo.
• Plugin_Abilities/Theme_Abilities install/update/delete completos (§4/§5) — install/delete arbitrário de plugins/temas via MCP é uma superfície de risco elevada (mesmo restrita a wordpress.org); para um clone interno de uso próprio da Descomplicar, ponderar reduzir a read-only (list/search) + activate/deactivate, deixando install/update/delete fora do MCP por preferir esse fluxo pelo wp-admin/WP-CLI directamente.

Riscos/gotchas não óbvios encontrados no código (citações):

• Astra: cache de CSS dinâmico só invalida em customize_save_after, não numa escrita de option simples — sem a chamada explícita a astra_clear_all_assets_cache(), updates via MCP ficariam invisíveis até o próximo save do Customizer (§11).
• Spectra: overlay de imagem de fundo em gradiente vem de gradientValue, não de gradientOverlayColor1/2 como seria intuitivo — documentado explicitamente no SHARED_ATTRS do próprio código (§12.1).
• Kadence Blocks rowlayout: colLayout vazio faz o editor mostrar um picker de layout em vez das colunas — "the frontend renders regardless" mas a experiência de edição fica quebrada; fix é forçar colLayout: 'equal' como default quando o caller não o especifica (§14.1).
• Kadence Blocks construídos à mão (não via pattern) disparam "Attempt recovery" no editor porque não batem byte-a-byte com o save() estático JS — o front-end renderiza correctamente na mesma; só insert-pattern (markup canónico do próprio Kadence) evita o aviso (§14).
• upload-media/create-post (featured_image sideload): as funções de sideload (media_handle_sideload e dependências) vivem em wp-admin/includes/* que não está carregado em pedidos REST/WP-CLI — têm de ser require_once'd on-demand a cada chamada (§1, §2).
• create-user: erros de conta existente são normalizados para uma mensagem genérica precisamente para impedir que a tool sirva de oráculo de enumeração de contas (§6).

Fonte

Leitura directa (19-08-2026) de: includes/abilities/class-content-abilities.php, includes/abilities/class-media-library-abilities.php, includes/abilities/class-settings-abilities.php, includes/abilities/class-plugin-abilities.php, includes/abilities/class-theme-abilities.php, includes/abilities/class-user-abilities.php, includes/abilities/class-nav-menu-abilities.php, includes/abilities/class-image-resize-abilities.php, includes/abilities/class-theme-integration.php, includes/abilities/class-active-theme-integration.php, includes/abilities/class-astra-integration.php, includes/abilities/class-spectra-integration.php, includes/abilities/class-kadence-integration.php, includes/abilities/class-kadence-blocks-integration.php, includes/blocks-catalog/class-kadence-blocks-catalog.php, includes/blocks-catalog/class-kadence-pattern-library.php, includes/blocks-catalog/class-spectra-catalog.php, includes/class-child-theme-builder.php; grep de includes/abilities/class-ability-registrar.php (linhas 135-165, 220-250, 320-380) para as condições de registo exactas e a confirmação da lista de 4 classes Pro-only referenciadas mas não implementadas; listagem directa de includes/abilities/ (48 ficheiros) para confirmar a ausência física dos ficheiros GeneratePress/GenerateBlocks/Blocksy neste build Free. Cruzado com docs/00-ARQUITECTURA.md (mesma sessão) para o contrato emcp_tools_register_ability().