Requisição 185 — Ajustes de Navegação e Referência nas Docs Online (FEAT-014, retorno do Humano)

Origem: Humano, 2026-09-26, testando o site das docs no Lab ([REDACTED]). Delegado a um agente em paralelo, enquanto o agente da req-179 fecha as bibliotecas e revisa as req-182/183/184. Lote Vinculado: BATCH-189. Status: approved. Autonomia: Nível 2. Commit e push autorizados pelo Humano. Sem pipeline (ver §3). Leitura obrigatória antes de começar:

• skill c2f-documentation;

• cli/src/Support/Docs/DocsBuilder.php, PhpFunctionExtractor.php, LibraryReference.php, cli/src/Commands/DocsExtractCommand.php e os testes tests/Unit/PHP/DocsBuildReq178Test.php, DocsToolingReq177Test.php, DocsSddReq184Test.php;

• no repositório conn2flow-site (branch feat/req-055): gestor/docs.config.json e os templates gestor/resources/{pt-br,en}/templates/docs-article/ e docs-sidebar/;

• sdd/implementation/documentacao/batch-050-documentacao-online-docs.md (no site): o histórico da navegação lateral;

• entradas FEAT-014 em sdd/MEMORIA-ENGENHARIA-EXECUCAO.md (armadilhas do builder: @[[…]]@, Tailwind lendo o HTML cru, mockup do menu).

1. Os ajustes pedidos

1. Menu lateral centralizado no item atual. Hoje, ao abrir uma página (ex.: Módulos → Usuários), o menu começa com a rolagem em 0 e o item atual pode ficar fora da tela. Ao carregar, depois de abrir o grupo da página atual, role o contêiner do menu ([data-docs-scroll] no docs-article) para que o link com aria-current="page" fique centralizado na vertical. Sem animação na carga; não role a página inteira, só o contêiner.

2. Anterior/próximo com o rótulo do menu. Os cartões de navegação no fim do artigo ainda mostram o título longo ("Biblioteca sitemap.php", "Biblioteca plugins.php"). Devem mostrar o mesmo rótulo do menu lateral: o nome do módulo (tabela modulos) para docs com module:, senão o label: do frontmatter, senão o título. Há um método para isso no builder (menuLabel()); use-o em navHtml().

3. Descrição das funções no bloco "Funções". O bloco gerado pelo c2f docs:extract mostra assinatura e link para a linha. Acrescente, por função:

   • o que ela faz: o resumo do docblock (primeira frase ou primeiro parágrafo);

   • o que cada parâmetro representa: a descrição de cada @param, inclusive as chaves documentadas como @param tipo $params['chave'] descrição (hoje ignoradas para o tipo, com razão);

   • o que devolve: a descrição do @return.

   O formato é livre, mas legível no site e no Markdown (por exemplo, a assinatura como hoje e, abaixo, o resumo e uma sublista de parâmetros). Função sem docblock fica só com a assinatura. Depois, regenere os blocos com php cli/c2f.php docs:extract --all (só reescreve o bloco entre <!-- c2f:extract:start/end -->; o texto das docs não pode mudar) e confira com docs:extract --all --check.

4. Remover "Editar esta página no GitHub". Tire o link do rodapé de verificação (verificationHtml()) e a chave edit de docs.config.json. O selo "Verificado contra o código no commit …" e a lista de fontes continuam.

2. Testes

• PHPUnit cobrindo: rótulo do menu nos cartões anterior/próximo; ausência do link de edição; extrator com resumo, descrição de parâmetros (inclusive chaves $params['x']) e retorno; bloco sem docblock inalterado.

• O JS do ajuste 1 não tem teste automatizado no projeto: descreva no batch como foi conferido (ver §3).

• Suítes das docs verdes (DocsBuildReq178Test, DocsToolingReq177Test, DocsSddReq184Test).

3. Regras de convivência (obrigatórias)

1. Só edite cli/src/Support/Docs/, cli/src/Commands/Docs*Command.php, os testes das docs, os blocos gerados em ai-workspace/{pt-br,en}/docs/reference/libraries/*.md (só pelo docs:extract), gestor/docs.config.json e os templates docs-article/docs-sidebar do conn2flow-site, e sdd/implementation/BATCH-189.md. Os índices (BATCH-INDEX.md, CURRENT.md) são do agente da req-179.

2. O agente da req-184 também mexe em cli/src/Support/Docs/. Antes de começar e antes de cada commit: git fetch e, se houver commits novos, git pull --rebase com a sua árvore limpa. Não reescreva o que ele fez (fonte SDD, filtro de conteúdo sensível).

3. Não rode c2f docs:build sem --dry-run, project:update-all, css:rebuild nem resources:sync: a publicação no Lab é do agente da req-184. Para conferir o ajuste 1, use docs:build --project=[REDACTED] --dry-run e leia o HTML planejado; a conferência visual final entra na publicação da req-184.

4. Git: git add só com os seus caminhos (nunca -A nem .); commits com feat(docs): ... (BATCH-189 / req-185) e a linha Co-Authored-By; push após cada commit. O conn2flow-site é na branch feat/req-055.

5. Heredoc do Git Bash corrompe barras invertidas e aspas. Use Write/Edit ou um script salvo em arquivo.

4. Critério de aceite

1. Os quatro ajustes implementados, com os testes de §2 passando.

2. docs:extract --all --check com exit 0 e docs:audit --json sem erros.

3. BATCH-189.md com o que mudou, os commits e a evidência.