# Instruções para trabalhar no PostGate

## Regra principal: seguir o código existente

Antes de implementar ou alterar qualquer funcionalidade, leia o código do plugin para entender sua arquitetura, responsabilidades e convenções. Não comece por uma solução própria e procure justificá-la depois. Reutilizar a estrutura existente é obrigatório; não cabe ao usuário encontrar e cobrar inconsistências em cada revisão.

Antes de editar:

1. Localize e leia a implementação existente mais próxima do comportamento solicitado.
2. Leia o fluxo completo relacionado: inicialização, classes responsáveis, hooks, API, interface, persistência, assets e testes aplicáveis.
3. Verifique o restante da arquitetura do plugin para identificar componentes e mecanismos que já resolvem o problema. Uma busca por nomes ou a leitura de um arquivo isolado não substitui essa análise.
4. Identifique onde a mudança deve entrar e implemente a menor extensão coerente com esse padrão.

Não crie classes, endpoints, hooks, abstrações, dependências ou pipelines paralelos quando os existentes atendem à necessidade. Uma exceção exige uma limitação concreta demonstrada no código; preferência pessoal, conveniência ou riscos hipotéticos não são justificativas. Explique a limitação e a necessidade da exceção antes de introduzi-la, sem criar etapas de aprovação desnecessárias.

## Responsabilidades existentes

- **Settings:** registrar opções, sanitização e comportamento de configurações em `includes/admin/class-settings.php` (`PostGate_Settings`). Usar o endpoint nativo `/wp/v2/settings` e os hooks existentes de Settings na interface. Não criar um endpoint próprio apenas para salvar configurações. Registrar cada opção separadamente, com nomes literais, na ordem das abas da interface. Para credenciais, seguir o padrão do Webhook Signing Secret de Payments: leitura e atualização administrativa pelo endpoint nativo, campo mostrar/ocultar e valor vazio para remover. Não criar tratamento write-only ou exclusão especial sem requisito explícito.
- **Assets:** registrar e enfileirar CSS/JS em `includes/core/class-assets-loader.php` (`PostGate_Assets_Loader`). Não espalhar enqueues por classes de funcionalidades ou templates.
- **Perfil:** integrar funcionalidades do perfil em `includes/admin/class-user-profile.php` (`PostGate_User_Profile`).
- **Dependências PHP:** declarar no `composer.json` e `composer.lock` da raiz, usando o `vendor/` existente. Não criar outro Composer, autoloader ou árvore de dependências para uma funcionalidade.
- **Fontes CSS/JS:** manter código editável em `src/`, seguindo a organização existente. Gerar os arquivos distribuídos pelo pipeline de build. Não escrever fontes diretamente em `assets/`. Bundles destinados a `assets/vendor/` devem ter seu próprio subdiretório, sem arquivos soltos.
- **Build e deploy:** usar os scripts centralizados do `package.json`. Conferir `.gitignore`, `.distignore`, enqueues e validação de assets ao adicionar um bundle. Não duplicar listas de builds no workflow.

## Padrões da interface de Settings

Leia as abas existentes e reutilize seus componentes, hooks de consulta, cache, notificações e persistência.

- Usar salvamento automático com o comportamento existente de debounce/blur; não adicionar botão de salvar.
- Usar `SettingsLoadingSkeleton` durante o carregamento inicial; não substituir por texto de loading.
- Exibir opções dependentes de um toggle somente quando ele estiver ativo.
- Reutilizar `SettingsCard`, `Toggle`, campos, tooltips e demais componentes compartilhados.
- Manter espaçamento, alinhamento, dimensões e estados visuais consistentes com as outras abas.

## Estilo e revisão

Seguir o estilo dos arquivos e métodos equivalentes: nomes, assinaturas, arrays, indentação, docblocks, comentários, traduções, validações e tratamento de erros. Separar blocos lógicos com uma linha em branco. Não introduzir outro estilo nem reformatar código não relacionado à tarefa.

Docblocks de métodos devem conter uma descrição principal, seguida de um parágrafo adicional que explique o comportamento, e depois as tags nesta ordem: `@since`, `@param` (quando houver parâmetros) e `@return`. Manter as tags consecutivas. A explicação adicional deve documentar o funcionamento real, sem apenas repetir a descrição principal; padronizar docblocks não significa apenas ajustar linhas em branco.

Antes de concluir, compare o diff com as implementações usadas como referência. Remova duplicações e complexidade sem necessidade demonstrada. Execute as verificações pertinentes e informe com precisão o que foi testado e o que continua pendente.

Não copie uma falha de segurança conhecida apenas para manter consistência: corrija o problema dentro da estrutura existente e explique a razão concreta.

## Preservação do acesso

Autenticação identifica o usuário WordPress; não concede, transfere, recria ou revoga grants. Reutilizar os handlers existentes para autorização, pedidos e retomada do checkout. Preservar IDs de usuários, vínculos Stripe e acesso existente ao modificar autenticação ou configurações.