Requisição 186 — Módulo `documentation`: Levar a Documentação Online para Dentro de um Módulo

Origem: Humano, 2026-09-26, depois de testar o site das docs: hoje a documentação gera muitas páginas globais (docs, docs-*) e a lógica fica espalhada entre o docs:build, o docs.config.json do projeto e recursos soltos. Pedido: um módulo documentation (id em inglês) que concentre essa lógica, com as páginas públicas pertencendo a ele, para depois criar ferramentas (atualizar a documentação pelo painel, plugins etc.). Lote Vinculado: BATCH-190. Status: approved (Humano, 2026-09-26). req-184 e req-185 concluídas.

1. Situação atual

• c2f docs:build (cli/src/Support/Docs/) lê o Markdown de ai-workspace/<idioma>/docs/ e o sdd/ do core e grava no projeto: páginas globais (resources/<idioma>/pages.json, ids docs e docs-*), publicações (publisher_pages), o menu docs-sidebar e assets/docs/llms*.txt.

• A configuração (gestor/docs.config.json), os publishers (docs-guides, docs-reference, docs-whats-new, docs-sdd), os índices e os templates (docs-article, docs-sidebar) são recursos do projeto conn2flow-site.

• As páginas não têm dono: não pertencem a nenhum módulo, então não há tela para elas nem permissões próprias.

2. Proposta

1. Módulo documentation no core (gestor/modulos/documentation/), com:

   • o manifesto documentation.json declarando os templates (docs-article, docs-sidebar, índices), os publishers e o menu que hoje são do projeto, e a configuração que hoje está em docs.config.json (idiomas, rótulos, repositório, SDD);

   • as páginas geradas passando a ter modulo = documentation;

   • uma tela administrativa mínima: estado da última geração (commit, data, número de páginas, avisos do filtro do SDD) e, numa etapa seguinte, o botão para regenerar.

2. docs:build passa a ler a configuração do módulo (com o docs.config.json do projeto como sobreposição opcional, para compatibilidade).

3. Migração das páginas e publicações existentes para o módulo, sem mudar URLs (/docs/…), e sem perder o que o pipeline preserva (user_modified).

4. Pontos de extensão para depois: hooks de antes/depois da geração, fontes extras de documentação vindas de plugins (cada plugin publicando as suas docs), restrição de acesso por perfil (visibility: restricted, já prevista no contrato).

3. Perguntas para o Humano antes do batch

1. O módulo vive no core (disponível a todo projeto que quiser publicar docs) ou só no conn2flow-site?

2. A tela administrativa entra neste batch ou fica para um segundo?

3. Regenerar pelo painel precisa rodar o pipeline (hoje só pelo CLI, com Node/Tailwind): aceitamos que o painel só agende e o CLI execute?

3.1 Respostas do Humano (2026-09-26)

1. O módulo vive só no conn2flow-site. A documentação do core é o Markdown do próprio repositório; o core não roda um site de docs.

2. A tela administrativa entra agora.

3. A regeneração é sempre no ambiente de desenvolvimento (CLI). O painel mostra o estado da última geração; não regenera. Que um usuário edite uma página de docs no painel é esperado (vale para qualquer página); diff na atualização fica para o futuro.

4. Critério de aceite

• Mesmas URLs e mesmo conteúdo publicado antes e depois da migração (comparação do HTML gerado).

• Páginas das docs com modulo = documentation no banco do Lab.

• Testes PHPUnit do docs:build lendo a configuração do módulo.