# BitSocial — playbook de diagnóstico

## Investigar porque uma publicação falhou

1. Encontrar o schedule pelo nome do post (`bs_list_schedules({search: "Post ID: 60261"})`) ou
   pelo id se já conhecido.
2. `bs_get_schedule({schedule_id})` — confirmar `status` (`completed`/`missed`/…), `config.accounts`
   (que contas estavam alvo) e `config.templates` (que tipo de conteúdo cada plataforma ia usar,
   ex. `postingType: "isLinkCard"` para Pinterest).
3. `bs_list_logs({schedule_id})` — uma linha por plataforma tentada; `status: 0` é falha,
   `details.response.error_msg` tem a razão devolvida pela API da plataforma.
4. Cruzar com `bs_list_accounts({platform})` para confirmar que a conta ainda está `active` — uma
   conta desligada não é a causa de uma falha já registada em log (o log só existe se a tentativa
   chegou a correr), mas explica ausência de tentativa nenhuma.

## Falha recorrente conhecida: Pinterest sem imagem

`"Must have image for create pin in Pinterest."` é o erro mais comum em produção (39 ocorrências
em 60 dias, confirmado com `bs_get_failure_summary({days: 60})`). Causa: o `postingType` do
template Pinterest (`bs_get_social_templates`) está como `isLinkCard`
(`"isLinkCard": false` no exemplo real — nome do campo enganador, o efectivo é o `postingType`)
mas o post de origem não tem imagem destacada elegível para a Pinterest API. Não é um bug do
MCP nem do plugin — é um requisito da API do Pinterest (todo pin precisa de imagem). Diagnóstico
correcto: confirmar se o post WordPress em causa tem featured image antes de o auto-post disparar;
o MCP não cobre a correcção (isso é conteúdo/publicação, fora do âmbito de `mcp-bit-social`).

## Ver o que está configurado para disparar auto-post

`bs_get_auto_post_settings` — confirma `isEnabled`, que `postType`s (ex.: `["post", "podcast"]`) e
taxonomias disparam publicação automática, atraso (`postDelay`) e que contas/grupos são alvo por
omissão. Cruzar com `bs_get_social_templates` para ver o formato de conteúdo por plataforma.

## Pausar uma conta sem a desligar (perder OAuth)

`bs_set_account_status({account_id, status: "inactive"})` — sai da rotação de auto-post e "Share
Now" imediatamente (mirror de `AccountController::updateStatus`), sem apagar a ligação OAuth
(`accounts.details` continua intacto). Reactivar com o mesmo tool e `status: "active"`.
Não confundir com apagar a conta (não coberto por este MCP — fazer via wp-admin se necessário,
apagar tem cascade sobre `groups_accounts` e pode invalidar schedules já criados que a referenciam).

## Saúde geral rápida

`bs_get_plugin_status` (versões/licença) + `bs_get_analytics` (contas activas, schedules activos,
publicações OK/falhadas) — dois tools, sem argumentos, para um snapshot inicial antes de investigar
mais fundo.

## Fora do âmbito deste MCP (fazer via wp-admin)

- Repetir uma publicação falhada (`RetryController` faz um pedido HTTP real à plataforma social —
  lógica de negócio, não um `UPDATE` SQL).
- Mudar o estado de um schedule directamente (`ScheduleController::updateStatus` tem checks
  condicionais de `COMPLETED`/`repeat` que não são um simples `UPDATE status=…`).
- Ligar uma conta social nova (fluxo OAuth) ou criar uma custom app.
- Editar o conteúdo/template de publicação por plataforma.