---
name: branda-menu
description: Organizacao do menu admin WordPress via Branda (branda-white-labeling) em seccoes Descomplicar standard. Computa Branda IDs a partir de slugs WP, constroi menu custom e guarda programaticamente via WP-CLI.
---

# /branda-menu - Organizar Menu Admin WordPress

Skill para organizar o menu admin sidebar de qualquer site WordPress WiP usando o Branda (branda-white-labeling).

---

## Arquitectura Branda (Referencia Interna)

### Como o Branda gere menus

O Branda usa um modulo `admin/menu.php` que intercepta o render do menu admin WordPress e substitui pela configuracao custom.

**Options `wp_options` envolvidas:**

| Option | Funcao |
|--------|--------|
| `ultimatebranding_activated_modules` | Modulos activos (precisa ter `admin/menu.php`) |
| `ub_custom_admin_menu` | Configuracao do menu custom por role |
| `ub_saved_admin_menus` | Captura do menu nativo WP (so para UI Branda) |

### Algoritmo de ID (critico)

```php
function branda_id($slug) {
    return "menu_item_" . substr(base_convert(md5($slug), 16, 32), 0, 12);
}
```

**Exemplo:** `index.php` -> `menu_item_42ho017e7jo0`

### Tipos de itens no menu

| Tipo | Campos chave | Uso |
|------|-------------|-----|
| **Section header** | `link_type: "none"`, `css_classes: "menu-highlight"` | Separador visual com titulo |
| **Custom link** | `link_type: "custom"`, `custom_url: "..."` | Link manual |
| **Native item** | `was_native: 1`, campos vazios | Item WP real |
| **Hidden item** | `is_hidden: "1"`, `was_native: 1` | Item WP escondido |

### Mecanismo de merge (parse_args_deep)

Na renderizacao, o Branda faz merge do menu configurado com o menu WP real. **Regra critica:** Incluir **todos** os itens nativos no config (visiveis ou hidden). Se faltar algum, aparece na posicao default e quebra a organizacao.

---

## Seccoes Standard Descomplicar (9)

| # | Seccao | Dashicon | Conteudo tipico |
|---|--------|----------|----------------|
| 1 | **Suporte** | dashicons-admin-tools | Link Descomplicar |
| 2 | **Admin** | dashicons-admin-generic | Painel, Utilizadores, Opcoes, Plugins, Ferramentas |
| 3 | **Conteudo** | dashicons-admin-page | Paginas, CPTs, Artigos, Multimedia, ACF |
| 4 | **Design** | dashicons-admin-appearance | Elementor, Modelos, Jeg Kit, Apresentacao |
| 5 | **Marketing** | dashicons-megaphone | FluentCRM, Fluent Forms, Rank Math, WhatsApp |
| 6 | **Idiomas** | dashicons-translation | Polylang/WPML, Loco Translate (se multilingue) |
| 7 | **Performance** | dashicons-performance | WP Fastest Cache, WebP Express |
| 8 | **Seguranca** | dashicons-shield | Wordfence, Complianz |
| 9 | **WebMaster** | dashicons-admin-settings | Branda, Code Snippets, Activity Log |

---

## Procedimento

### Passo 1: Verificar pre-requisitos

```bash
mcp__ssh-unified__ssh_execute server:"server" command:"wp plugin is-active branda-white-labeling --allow-root --path=/home/USER/SITE && echo ACTIVE || echo INACTIVE"

# Verificar modulo menu activo
mcp__ssh-unified__ssh_execute server:"server" command:"wp eval '
\$m = get_option(\"ultimatebranding_activated_modules\", array());
echo isset(\$m[\"admin/menu.php\"]) ? \"MENU MODULE ACTIVE\" : \"MENU MODULE INACTIVE\";
' --allow-root --path=/home/USER/SITE"
```

Se modulo inactivo, activar:
```bash
mcp__ssh-unified__ssh_execute server:"server" command:"wp eval '
\$m = get_option(\"ultimatebranding_activated_modules\", array());
\$m[\"admin/menu.php\"] = \"yes\";
update_option(\"ultimatebranding_activated_modules\", \$m);
echo \"Activado\";
' --allow-root --path=/home/USER/SITE"
```

### Passo 2: Extrair menu nativo

**Opcao A (preferida): mu-plugin temporario** - criar mu-plugin que captura menu no proximo page load, depois ler a captura via `wp eval`.

**Opcao B (alternativa): Chrome DevTools** - navegar ao wp-admin e executar JS para listar itens.

### Passo 3: Mapear itens para seccoes

Com a lista de itens nativos, mapear cada um para a seccao correcta.

Mapeamento completo de slugs e IDs em: `references/mapeamento-slugs.md`

### Passo 4: Construir e guardar o menu

Script PHP template completo em: `references/script-template.md`

Executar com `wp eval-file` via SSH MCP.

### Passo 5: Verificar

```bash
mcp__ssh-unified__ssh_execute server:"server" command:"wp eval '
\$m = get_option(\"ub_custom_admin_menu\");
\$items = \$m[\"administrator\"];
echo \"Total: \" . count(\$items) . \"\n\";
foreach (\$items as \$key => \$item) {
    \$hidden = !empty(\$item[\"is_hidden\"]) ? \" [HIDDEN]\" : \"\";
    \$type = !empty(\$item[\"was_native\"]) ? \"native\" : (!empty(\$item[\"link_type\"]) && \$item[\"link_type\"] == \"none\" ? \"header\" : \"custom\");
    \$title = !empty(\$item[\"title\"]) ? \$item[\"title\"] : \"(native)\";
    echo \"\$key => \$type: \$title\$hidden\n\";
}
' --allow-root --path=/home/USER/SITE"
```

Verificar visualmente no browser.

### Passo 6: Limpar

```bash
mcp__ssh-unified__ssh_execute server:"server" command:"rm -f /tmp/branda-menu-SITE.php"

mcp__ssh-unified__ssh_execute server:"server" command:"wp eval '
delete_option(\"_branda_menu_capture\");
delete_option(\"_branda_menu_captured\");
echo \"Limpo\";
' --allow-root --path=/home/USER/SITE"

mcp__ssh-unified__ssh_execute server:"server" command:"rm -f /home/USER/SITE/wp-content/mu-plugins/capture-menu.php 2>/dev/null; echo ok"
```

---

## Troubleshooting

| Problema | Causa | Solucao |
|----------|-------|---------|
| Menu nao muda apos guardar | Cache ou modulo inactivo | `wp cache flush` + verificar `admin/menu.php` activo |
| Itens nativos fora das seccoes | Item nao incluido no config | Identificar slug, computar Branda ID, adicionar ao config |
| Separadores nativos aparecem | Slugs diferentes dos standard | Verificar slugs via captura, adicionar como hidden |
| Items custom em duplicado | Existe como custom e native | Remover custom link, manter native |

**CSS fallback para separadores:**
```css
#adminmenu li.wp-menu-separator { display: none !important; }
```

---

## Checklist

- [ ] Branda activo e modulo `admin/menu.php` activo
- [ ] Menu nativo extraido (todos os itens identificados)
- [ ] Todos os itens nativos incluidos no config (visiveis ou hidden)
- [ ] 9 seccoes criadas na ordem standard
- [ ] CPTs do projecto na seccao Conteudo
- [ ] Verificado visualmente no browser
- [ ] Script temporario e capturas removidos
- [ ] Permissoes corrigidas: `chown -R USER:USER /home/USER/SITE/`

---

## References

- `references/mapeamento-slugs.md` - Mapeamento completo slug -> seccao e tabela de Branda IDs
- `references/script-template.md` - Script PHP template + adaptacoes por tipo de site