Requisição 180 — Documentação dos Módulos do Core (FEAT-014, fase 2, onda 3, em paralelo)

Origem: Humano, 2026-09-25: dividir a revisão da documentação entre dois agentes. Este intake é a parte do segundo agente. A req-179 (BATCH-184) segue com o primeiro agente: bibliotecas, guias e conceitos. Lote Vinculado: BATCH-185. Status: approved. Autonomia: Nível 2. Commit e push autorizados pelo Humano. Sem deploy: a publicação no Lab é feita pelo outro agente (ver §4). Leitura obrigatória antes de começar:

• skill c2f-documentation;

• req-179.md (mapa §2.2 e regras §1);

• ai-workspace/pt-br/docs/guides/documentation.md (o contrato);

• os exemplos prontos: ai-workspace/pt-br/docs/reference/modules/menus.md (módulo) e reference/libraries/banco.md (nível de rigor esperado).

1. Premissa (Humano)

As docs atuais foram escritas por uma geração anterior de agentes, que errava muito. Parta do princípio de que toda doc legada está errada e refaça a partir do código. O código tem comentários ricos (req-xxx, DEC-xxx, o porquê das decisões): use-os, mas confirme cada afirmação lendo a implementação. Há muita coisa implementada sem documentação nenhuma, e ela também deve entrar.

2. Escopo: uma doc por módulo, em reference/modules/<id>.md, pt-br e en

menus já está feito (piloto). Não mexa nele.

3. Conteúdo de cada doc de módulo

Siga o formato de reference/modules/menus.md:

1. Frontmatter com section: reference, module: <id>, sources (todos os arquivos lidos: .php, .json, .js, .widget.php, migrations da tabela) e verified_at = git rev-parse --short HEAD no momento da conferência.

2. O que é e para que serve (1 parágrafo).

3. Como usar: o fluxo do operador no painel, com as rotas reais de resources/<idioma>/pages do JSON do módulo. Substitui o antigo "manual do usuário".

4. Referência técnica:

   • opções do switch($_GESTOR['opcao']) e do switch($_GESTOR['ajax-opcao']);

   • tabela(s) e colunas (da migration);

   • estrutura de JSONs como fields_schema;

   • widget público (marcador <!-- widgets#<id>->render(...) -->, blocos e variáveis do template);

   • templates que acompanham o módulo;

   • hooks e API (hooks.api no JSON);

   • permissões e operações (modulos_operacoes).

5. Comportamentos surpreendentes, defeitos e legado: o que o código faz de diferente do que a doc antiga dizia, funções sem chamador, riscos de segurança (SQL sem escape, visibilidade que não é controle de acesso…). Use callouts > [!WARNING]/> [!CAUTION].

6. Veja também com links relativos para .md existentes. Link quebrado aborta o build.

Escreva pt-br e en na mesma passagem, com o mesmo conteúdo e o mesmo caminho.

4. Regras de convivência com o outro agente (obrigatórias)

1. Só edite ai-workspace/{pt-br,en}/docs/reference/modules/, os arquivos legados de módulo listados em §2 e sdd/implementation/BATCH-185.md. Não edite reference/libraries/, guides/, concepts/, index.md, sdd/human-requests/CURRENT.md, sdd/implementation/BATCH-INDEX.md nem sdd/validation/VALIDATION-CHECKLIST.md: quem atualiza os índices é o outro agente. Registre tudo no BATCH-185.md.

2. Não rode c2f docs:build, project:update-all, css:rebuild nem resources:sync. O pipeline não pode rodar em paralelo, e a publicação no Lab é feita pelo outro agente.

3. Pode rodar php cli/c2f.php docs:audit (só leitura) e php cli/c2f.php docs:extract (não se aplica a módulos).

4. Git:

   • antes de cada commit, git pull --rebase origin main;

   • git add só com os seus caminhos (nunca -A, nunca .);

   • commits pequenos, por lote de 3 a 5 módulos, com a mensagem docs(modules): <ids> reescritos do codigo (BATCH-185 / req-180) e a linha Co-Authored-By do agente;

   • push após cada commit.

5. Heredoc do Git Bash corrompe barras invertidas. Para escrever ou editar arquivos, use as ferramentas de arquivo (Write/Edit), nunca cat <<EOF nem Python via heredoc.

5. Critério de aceite

1. php cli/c2f.php docs:audit --json sem nenhum item reference/modules/* com score > 0 e sem missing:reference/modules/*.

2. Os arquivos legados de §2 apagados (pt-br e en).

3. BATCH-185.md com a lista de módulos, os achados relevantes do código por módulo (defeitos, legado, divergências da doc antiga) e os hashes dos commits.

6. Ordem sugerida

Os mais usados primeiro:

• admin-paginas, publisher, publisher-pages, publisher-index, publisher-highlights, pages-index;

• forms, forms-submissions, forms-search, galleries;

• perfil-usuario, usuarios, usuarios-perfis, modulos, modulos-grupos, modulos-operacoes;

• o resto.