feat(wordpress): nova skill mcp-webp-express + doc MCP webpx na skill webp-express

Skill mcp-webp-express: MCP dedicado (webpx) para WebP Express multi-site
via WP-CLI/SSH, mesmo padrao mcp-wpfc. webp-express/SKILL.md: nova seccao
14 documentando o MCP construido e testado ao vivo em emanuelalmeida.pt.

wordpress/skills/mcp-webp-express/SKILL.md

@@ -0,0 +1,92 @@
+---
+name: mcp-webp-express
+description: MCP dedicado multi-site (node stdio, ligação `webpx` em ~/.omp/agent/mcp.json) para gerir o WebP Express em qualquer site do bundle Descomplicar® via WP-CLI/SSH — estado do plugin, ficheiro de config completo (modo de operação, qualidade jpeg/png, stack de conversores), conversão em massa, flush de webps. Site é um parâmetro em cada tool, não uma ligação fixa. Usar quando "converter webp via mcp", "webpx mcp", "config webp express mcp", "conversores webp mcp", "flush webp mcp", "convert webp mcp".
+layer: wiki
+---
+
+# /mcp-webp-express — MCP dedicado multi-site ao WebP Express
+
+Projecto em `/media/ealmeida/Dados/Dev/mcp-webp-express/` (TypeScript, SDK MCP oficial, stdio).
+Mesmo padrão do `mcp-wpfc`/`mcp-element-pack`: sem código PHP novo no WordPress, cada tool executa
+`wp option get`, leitura/escrita directa no ficheiro de config, ou
+`wp webp-express convert|flushwebp` via `ssh server` sobre o WP-CLI já instalado. `site` é um
+parâmetro em cada tool, não uma ligação fixa — WebP Express está activo nos 8 sites reais do
+bundle.
+
+**Relação com a skill `webp-express`:** essa skill é a fonte de conhecimento (mapeamento completo
+de todas as chaves do ficheiro de config, modos de operação, conversores, redirection rules,
+alter-html, web-service, gotchas de produção — §1-13). Esta skill é o "como executar" — qual tool
+chamar para cada operação. Consultar `webp-express` para entender uma definição; usar as tools
+abaixo para lê-la/escrevê-la.
+
+## Âmbito
+
+Config, stack de conversores, conversão em massa e limpeza do WebP Express. Não cobre:
+activação/desactivação do próprio plugin (`emcp-tools activate-plugin`/`deactivate-plugin`),
+optimização/compressão genérica de imagem (nenhum plugin equivalente no bundle hoje), Cloudflare
+Polish (fora de âmbito — Polish está `off` no plano Free, ver §13 da skill `webp-express`).
+
+## Sites conhecidos
+
+Chamar `webpx_list_sites` para a lista actual com path e nota de estado. Aliases verificados ao
+vivo 19-08-2026, todos com WebP Express v0.25.15 activo: `descomplicar`/`emanuelalmeida`
+(`operation-mode: cdn-friendly`), `starter`/`ccv`/`care`/`ecommerce-demo`/`e-commerce`/`ecommerce`
+(`operation-mode: varied-image-responses`). Também aceita um path absoluto directamente
+(`/home/ealmeida/<site>`) para sites fora desta lista, sem exigir rebuild do MCP.
+
+## Tools (9)
+
+| Tool | Read-only | Uso |
+|---|---|---|
+| `webpx_list_sites` | sim | Aliases conhecidos, path WP, nota de estado |
+| `webpx_get_status` | sim | Plugin instalado/activo/versão + `webp-express-state` resumido — chamar sempre antes de forçar `converter` em `webpx_convert` |
+| `webpx_get_state` | sim | `webp-express-state` em bruto: `workingConverterIds`, `configured`, regras `.htaccess` gravadas |
+| `webpx_get_config` / `webpx_set_config` | sim/não | Ficheiro `config.<hash>.json` completo — merge raso; recusa chaves de diagnóstico só-leitura; avisa quando a chave exige re-save manual em wp-admin para regenerar `.htaccess` |
+| `webpx_get_converters` / `webpx_set_converter_options` | sim/não | `converters[]` — opções por conversor + reordenação (`position`). Nunca toca em `working` |
+| `webpx_convert` | não | `wp webp-express convert [<location>] [flags]` — sem `location`, dry preview |
+| `webpx_flushwebp` | não | `wp webp-express flushwebp [--only-png]` — apaga `.webp` gerados, nunca originais registados |
+
+Todas as tools exigem `site` como primeiro parâmetro.
+
+## Segurança
+
+- `webpx_set_config` recusa gravar as chaves de diagnóstico
+  (`environment-when-config-was-saved`, `base-htaccess-on-these-capability-tests`,
+  `document-root`, `paths-used-in-htaccess`) — snapshots de ambiente gravados pelo próprio plugin,
+  nunca destinados a edição manual.
+- Escrita no ficheiro de config preserva owner:group:permissões originais capturados via `stat`
+  antes de sobrescrever — a ligação SSH corre como root; sem isto o ficheiro ficaria `root:root`
+  e o wp-admin desse site deixaria de conseguir gravar as próprias definições.
+- Valor viaja sempre em base64 sobre stdin, nunca interpolado no comando SSH remoto.
+
+**Gotcha de formato (mesma classe do já documentado em `mcp-wpfc`):** `webp-express-state` é uma
+STRING JSON dentro de um wp_option (`json_encode()` gravado directamente), não um array WP-CLI
+tipado — `wp option get webp-express-state --format=json` devolve JSON duplamente codificado.
+`getState()` descodifica uma segunda vez. Ao contrário do WPFC, aqui a CONFIG principal nem
+sequer é um wp_option — vive num ficheiro com hash no nome (`webp-express-config-hash` resolve o
+caminho, nunca hardcoded).
+
+**Gotcha de SDK:** `structuredContent` do resultado de uma tool MCP tem de ser um objecto — nunca
+um array. Passar um array (ex. `converters[]`) causa `MCP error -32602: expected record, received
+array`. `jsonResult()` só anexa `structuredContent` quando os dados são um objecto simples.
+
+## Verificação
+
+Construído e testado ponta-a-ponta contra produção (`emanuelalmeida.pt`) 19-08-2026: leitura
+completa da config e da stack de conversores; escrita+releitura+reversão de `enable-logging`
+(`false→true→false`) e de `gd.skip-pngs` via `webpx_set_converter_options`
+(`false→true→false`), ambas confirmadas por `stat` a manter `ealmeida:ealmeida 644` antes/depois;
+bloqueio confirmado ao tentar gravar `document-root`; `webpx_convert` em dry preview (0 ficheiros
+por converter, config já estável). `webpx_flushwebp` e `webpx_convert` com `location`/`reconvert`
+reais não foram exercidos contra produção — mesmo código-caminho (`runSsh` + construção de
+comando) já validado via `convert` em dry-run.
+
+## Skills relacionadas
+
+- `webp-express` — mapeamento completo de todas as chaves de config, modos de operação,
+  conversores, qualidade/encoding, redirection rules, alter-html, web-service, decision tree de
+  comandos WP-CLI equivalentes.
+- `mcp-wpfc` — MCP irmão para WP Fastest Cache, mesmo padrão arquitectural; primeira ocorrência
+  documentada do gotcha de JSON duplamente codificado.
+- `wp-font-perf` — cobre WebP em `background-image` CSS, que o WebP Express não converte (fora do
+  âmbito deste MCP e dessa skill de origem).

wordpress/skills/webp-express/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: webp-express
-description: Gestão do plugin WebP Express (conversão automática de imagens para WebP) via WP-CLI e ficheiro de config em servidores CWP. Cobre localizar o ficheiro de config com hash variável, modos de operação (CDN friendly, Varied image responses, No conversion, Tweaked), reconversão em massa via `wp webp-express convert`, flush de webps, conversores disponíveis (imagemagick/imagick/gd vs cwebp/vips/ffmpeg/graphicsmagick/wpc/ewww) e as respectivas opções próprias, estrutura JSON completa do ficheiro de configuração (qualidade/encoding/near-lossless/alpha-quality por tipo de imagem, cache-control, alter HTML, redirection rules, web service), regras `.htaccess` e a fronteira com o Cloudflare. Usar quando "webp express", "converter imagens webp", "webp nao funciona", "reconverter imagens", "flush webp", "conversor imagemagick gd", "operation mode webp", "cdn friendly webp", "webp quality", "near lossless", "alter html webp", "cache control webp", "web service webp express".
+description: Gestão do plugin WebP Express (conversão automática de imagens para WebP) via WP-CLI e ficheiro de config em servidores CWP. Cobre localizar o ficheiro de config com hash variável, modos de operação (CDN friendly, Varied image responses, No conversion, Tweaked), reconversão em massa via `wp webp-express convert`, flush de webps, conversores disponíveis (imagemagick/imagick/gd vs cwebp/vips/ffmpeg/graphicsmagick/wpc/ewww) e as respectivas opções próprias, estrutura JSON completa do ficheiro de configuração (qualidade/encoding/near-lossless/alpha-quality por tipo de imagem, cache-control, alter HTML, redirection rules, web service), regras `.htaccess`, a fronteira com o Cloudflare, e o MCP `webpx` construído para gestão programática multi-site (§14). Usar quando "webp express", "converter imagens webp", "webp nao funciona", "reconverter imagens", "flush webp", "conversor imagemagick gd", "operation mode webp", "cdn friendly webp", "webp quality", "near lossless", "alter html webp", "cache control webp", "web service webp express", "mcp webp express", "webpx".
 ---
 
 # /webp-express — Conversão de imagens para WebP via WP-CLI
@@ -621,6 +621,59 @@ ratio alto no cache do Cloudflare independentemente do plano.
 
 ---
 
+## 14. MCP `webpx` — gestão programática (construído 19-08-2026)
+
+Existe um MCP dedicado (`mcp-webp-express`, registado como `webpx` em
+`~/.omp/agent/mcp.json`) que expõe as operações deste documento como tools,
+multi-site (todos os 8 aliases do bundle Descomplicar, mesmo padrão do
+`wpfc`/`mcp-element-pack`): `spawn("ssh", ...)`, valor em base64 sobre
+stdin, sem ledger/rollback (fora do âmbito — ver `emcp-tools` para mudanças
+que precisem disso).
+
+**Diferença chave vs os outros MCPs da frota:** a config deste plugin vive
+num ficheiro com hash no nome (§1), não numa `wp_option` — o MCP resolve o
+hash via `webp-express-config-hash` em cada chamada (nunca hardcoded) e
+preserva owner:group:permissões do ficheiro ao escrever (a ligação SSH
+corre como root; sem isto o wp-admin do site deixaria de conseguir gravar
+as próprias definições). `webp-express-state` também exigiu tratamento
+especial: o plugin grava-a como STRING JSON, não como array — um
+`--format=json` ingénuo devolve JSON duas vezes codificado.
+
+### Tools (9)
+
+- `webpx_list_sites` — sites conhecidos.
+- `webpx_get_status` / `webpx_get_state` — plugin instalado/activo/versão +
+  `webp-express-state` (workingConverterIds, configured, htaccess-rules-
+  saved-at-some-point).
+- `webpx_get_config` / `webpx_set_config` — ficheiro `config.<hash>.json`
+  completo (§6).
+- `webpx_get_converters` / `webpx_set_converter_options` — stack de
+  conversores (§4), opções por conversor + reordenação.
+- `webpx_convert` — `wp webp-express convert` (§3).
+- `webpx_flushwebp` — `wp webp-express flushwebp` (§3).
+
+### Guarda-corpos
+
+- `webpx_set_config` recusa gravar as chaves de diagnóstico só-leitura de
+  §6 (`environment-when-config-was-saved`,
+  `base-htaccess-on-these-capability-tests`, `document-root`,
+  `paths-used-in-htaccess`).
+- `webpx_set_config` devolve um aviso explícito quando a chave alterada só
+  tem efeito via `.htaccess` (operation-mode, scope, image-types,
+  destination-*, redirection rules) — regenerar essas regras continua a
+  exigir abrir wp-admin → Save uma vez (§12), sem equivalente WP-CLI.
+
+**Testado ao vivo em `emanuelalmeida.pt` (19-08-2026):** leitura completa
+da config, escrita+leitura de volta com `enable-logging` (revertido),
+escrita+leitura de volta de `gd.skip-pngs` via `webpx_set_converter_options`
+(revertido), bloqueio confirmado ao tentar gravar `document-root`, `convert`
+em modo preview (0 ficheiros por converter, config já estável). Owner:group
+do ficheiro de config confirmado `ealmeida:ealmeida 644` antes e depois da
+escrita. `webpx_flushwebp` e `convert` com `location`/`reconvert` reais não
+foram exercidos contra produção (mesmo padrão de comando já validado via
+`convert` em dry-run — risco desnecessário para a validação).
+
+
 ## Erros comuns
 
 | Sintoma | Causa | Solução |