--- name: solnet-docs description: > Use este skill para qualquer tarefa de documentação no repositório portal-documentacao-solnet da Hetosoft: criar novos documentos, atualizar documentação existente, ou auditar conformidade de docs com as regras do projeto. Acione sempre que o usuário mencionar "Criar documentação", "Documentar a tela X", "Atualizar documentação de X", "Auditar documentação", "Revisar docs do módulo Y", ou qualquer pedido para escrever, editar ou verificar documentação do Sol.NET ERP. Use proativamente sempre que arquivos .md no portal-documentacao-solnet precisarem ser criados ou alterados — mesmo que o usuário não diga "skill" explicitamente. --- # 📚 Sol.NET Docs Skill Este skill orquestra o ciclo completo de documentação do portal Sol.NET ERP (`hetosoft/portal-documentacao-solnet`). O `CLAUDE.md` na raiz do repositório é a fonte de verdade para convenções de nomenclatura, estilo e estrutura — leia-o sempre que precisar confirmar uma regra. Este skill foca no **workflow**: quais passos executar, em qual ordem, e como tomar decisões. Para o procedimento de lookup de códigos de tela, leia `references/screen_lookup.md`. Para a navegação, leia `references/navegacao_nav_yaml.md` — o sidebar é declarado em `nav.yaml` na raiz. --- ## 🏛️ Convenções deste repositório Este repositório é uma aplicação ASP.NET (`src/PortalDocs/`) que renderiza Markdown em tempo de execução. As regras de conteúdo e estrutura: - **Sidebar é o `nav.yaml`.** A navegação é definida em `nav.yaml` na raiz — uma única fonte de verdade (ver `references/navegacao_nav_yaml.md`). Para adicionar página, edite o YAML. - **Conteúdo separado por audiência.** Há duas raízes: `public/` (acesso anônimo) e `internal/` (só após login). Páginas que falam de instalação, manipulação de DLL, infra técnica ou contêm credenciais vão em `internal/`. Páginas para operador final vão em `public/`. - **Front-matter manda.** Adicione `audience: internal` no front-matter de arquivos restritos. `src/PortalDocs/Services/MarkdownLoader.cs:52` filtra por esse campo independentemente da pasta — pasta é convenção, front-matter é regra. - **Rotas seguem o caminho do arquivo, sem `.md`** (`/Financeiro/documentacao_quitacao` etc.). Não há `permalink: pretty` nem trailing slash obrigatório. - **Sitemap** (`/sitemap.xml`) é gerado automaticamente a partir de `public/`. Páginas em `internal/` ficam fora — não precisa ajustar nada manualmente. - **Nome dos branches:** `docs/` (ASCII, sem acentos). - **PRs e commits em português.** --- ## ⚠️ Telas com acesso restrito — regra obrigatória Sempre que um documento **mencionar alterações** nas telas **`Cadastro de Empresas`** ou **`Cadastro de Tipos de Movimento`** — independentemente do modo (Criar, Atualizar ou Auditar) — inclua imediatamente após a instrução de alteração a seguinte nota de aviso: ```markdown > ⚠️ **Acesso de suporte necessário:** alterações no `Cadastro de Empresas` requerem permissão de acesso de suporte. Entre em contato com o suporte Hetosoft antes de realizar qualquer modificação nesta tela. ``` Adapte o nome da tela na nota conforme o contexto (`Cadastro de Empresas` ou `Cadastro de Tipos de Movimento`). **Onde inserir:** logo após a sentença ou passo que descreve a alteração, nunca no início ou final do documento de forma genérica. O leitor deve encontrar o aviso exatamente quando está prestes a realizar a ação. **Quando NÃO inserir:** se o documento apenas *consulta* ou *visualiza* dados nessas telas, sem instruir o usuário a modificar nada, a nota não é necessária. Esta regra se aplica também ao modo Auditar: se um documento existente menciona alterações nessas telas sem a nota de aviso, adicione-a automaticamente como parte da correção. --- ## 💬 Mensagens de tela — regra obrigatória Mensagens de validação, avisos e perguntas que a tela exibe são **conteúdo de alto valor** para o suporte (o atendente cola a mensagem e quer a causa). Ao documentá-las — numa FAQ, num passo, ou num **índice de mensagens** (ver "Arquétipos de documento"): - **Cite o texto EXATO da tela**, como o usuário vê. No `.dfm` ele aparece codificado (`'Peso Divergente'`, `'Usu'#225'rio'`); decodifique os literais `#NNN` antes de citar. - **Nunca** cite string de **log**, mensagem de exceção interna, ou nome de variável/constante. Distinga o **diálogo que o usuário vê** da linha de log que só o desenvolvedor vê. - **Harvest antes de minerar:** se a mensagem já está numa doc curada do portal (FAQ, doc de tela), reaproveite o texto de lá. Só vá ao `.pas` quando a doc não cobrir. - Se um módulo **não tem mensagens catalogáveis** (as docs não citam nenhuma e o source seria a única fonte), **sinalize** em vez de inventar — nem todo módulo precisa de índice de mensagens. --- ## 🔬 Profundidade de uma doc de tela — regra obrigatória Documentar uma tela é **esgotar o que o usuário pode fazer nela**, não só listar campos. Toda doc de tela/feature deve extrair e documentar — **quando existirem** — os itens abaixo. Cada afirmação segue a regra de inferência (fonte direta no `.dfm`/`.pas`/banco) e o vocabulário do suporte (sem jargão Delphi). Se um item não existe na tela, pule-o; não invente. - **Sub-abas do formulário** — documente cada sub-aba específica da tela (`## 🧭 Sub-abas do formulário`). **NÃO** documente o invólucro universal `Visualizar`/`Cadastrar` (ver `CLAUDE.md`). - **Botões, um a um** — para cada botão de ação, cite o **Caption real** (`.dfm`) e descreva **o que ele faz** (rastreie o `OnClick` no `.pas`). Não agrupe "Inserir / Atualizar / Deletar" sem dizer o efeito de cada um quando há diferença relevante (ex.: "Deletar Todos" vs "Deletar Selecionados"). - **Menus de contexto (botão direito)** — liste os itens do `TPopupMenu` da tela/grade e o que cada um faz (rastreie o `OnClick`). Itens triviais de grade (`Salvar`, `Ajustes`, `Ir no Produto`) podem ser citados de forma breve; itens de **ação** (`Aprovar`, `Visualizar Pedidos`, `Clonar Registro`, `Criar Cotação`…) devem ter o efeito descrito. - **Ações de teclado nas grades/campos** — documente teclas com handler **validado** no `.pas` (`OnKeyDown`/`OnKeyPress`: `VK_RETURN`, `VK_DELETE`, `#13`…) e o que cada uma faz. Vale a regra de atalhos do `CLAUDE.md`: **só** cite a tecla se localizou o handler, e **escope** a tecla à grade/campo onde ela vale (ex.: "nas grades da aba Resultado"). - **Comportamentos contraintuitivos** — destaque com `> ⚠️ **Atenção**` qualquer ação cujo efeito surpreende (ex.: o mesmo gesto — duplo-clique — **aprova** numa grade e **remove** em outra). É o que mais gera chamado de suporte. - **Mensagens de validação** — texto exato, decodificado (ver regra «💬 Mensagens de tela»). - **Funções da tela** — se a tela tem lista de **Funções** (`ID_FUNCOES`), cite cada função pela `DESCRICAO` **real da tabela `FUNCOES`** (não pelo nome do procedimento Delphi) e descreva o que faz. - **Origem e destino cruzados** — diga **de onde os dados podem vir** e **para onde vão**: outras telas que alimentam esta (ex.: itens trazidos por um botão "Criar X" de outra tela) e o que esta tela gera (ex.: gera Pedido/Movimento/Cotação). Garanta o **cross-link bidirecional** (ver «Passo 6»). - **Campos e valores via banco** — para campos com valor codificado (combos, status), confirme os valores **gravados** no banco antes de listar (ver «Consulta ao banco» no `CLAUDE.md` e `references/consulta_banco.md`). **Ordem visual do combo ≠ valor gravado** (cheque `AHS_ItemsID`/`AHS_Values`). > **Referência viva desta profundidade:** a doc de **Cotação** (`public/Compras/documentacao_cotacao.md`) — aba "Preço por Fornecedor" botão a botão, ações das grades da aba Resultado (com o aviso de duplo-clique), funções citadas pela `DESCRICAO`, e a origem dos produtos via "Criar Cotação" do `Pedido de Compra`. Espelhe esse nível de detalhe. --- ## 🔗 Links e rotas — regra obrigatória O renderizador resolve cada link relativo contra a **pasta física** do arquivo e o reescreve como **rota absoluta** sem `.md` (`Financeiro/documentacao_quitacao.md` → `/Financeiro/documentacao_quitacao`). Consequências práticas: - **Índice de pasta:** linke a **forma de pasta** (`PDV/` → `/PDV`), não `PDV/README.md` (→ `/PDV/README`, rota duplicada não-canônica). Para o índice da própria pasta a partir de um irmão, use `./`. - **Não atravesse audiências:** nunca linke de um arquivo em `public/` para um em `internal/` (nem o contrário). O loader procura em `public/` **antes** de `internal/` — mesmo nome nos dois faz o público **sombrear** o interno, e um link `../../public/...` vira rota inexistente. Linke pela rota lógica (`/PDV/documentacao_operacao`), que o loader resolve para a audiência certa. - **Âncoras** são geradas pelo Markdig (minúsculas, hífens, emoji removido). Acentos podem ser transliterados — **não confie de cabeça**: renderize e confira o `id` real, ou linke em nível de página. Snake_case ⇒ links **não** têm `%20`. --- ## 🎯 Audiência: escreva para o suporte Todo documento criado ou editado por este skill é destinado à **equipe de suporte** — pessoas não técnicas que leem como usuários finais. O objetivo é que o suporte consiga: - Entender uma funcionalidade sem precisar ligar para o analista - Descobrir como usar uma ferramenta nova por conta própria - Navegar até qualquer tela usando apenas a pesquisa F1 (nunca caminhos de menu) Se algo confundiria um atendente de suporte que nunca viu o código-fonte, reescreva. Sem jargão técnico, sem termos Delphi, sem referências a desenvolvimento. --- ## 🗣️ Princípio: investigar primeiro, perguntar para corroborar Antes de qualquer pergunta sobre como a funcionalidade funciona, esgote as fontes de verdade disponíveis — `.dfm` (Caption real, **não** o nome do componente), `.pas` (handlers, `AHS_ClientDataSetCampo`, validações de `uFrmHeranca`), tabela do banco (schema, valores codificados, exemplos reais — ver `references/consulta_banco.md`), issues e PRs no `ProjetosSol.NET`. As perguntas ao usuário entram em dois momentos: - **Durante** a investigação, quando uma pista é ambígua e bloqueia o próximo passo (ex.: dois componentes com Caption parecido, combo codificado sem `AHS_ItemsID`/`AHS_Values` visível, regra de validação cujo motivo de negócio não está no código). - **Depois** dela, num bloco curto de confirmação no Checkpoint de entendimento (ver passos dos modos), para corroborar inferências que ainda não são fortes e para pegar contexto de negócio que só o usuário tem — motivação da feature, casos reais que o suporte vê, edge cases observados em campo. Não substitua a investigação por perguntas — pergunte o que a investigação não pode responder. ### Quando a inferência é forte o suficiente para ir direto pra doc Uma afirmação só entra na documentação sem pergunta de confirmação quando há **premissas suficientes** sustentando-a. Classifique as fontes: - **Fontes diretas** (afirmam o fato): `Caption` real do `.dfm`; coluna do banco com tipo, `NOT NULL`, `CHECK` ou FK; handler no `.pas` (`KeyDown`, `OnClick`, `AHS_ClientDataSetCampo`, validações em `uFrmHeranca`); enunciado de issue ou PR já mergeado; contexto que o próprio usuário forneceu nesta sessão. - **Fontes indiretas / heurísticas** (sugerem, não provam): nome do componente; `Hint` do `.dfm` (pode estar obsoleto — componente duplicado com Caption novo); ordem visual de um combo (≠ valor gravado, ver `AHS_ItemsID`/`AHS_Values`); intuição de UI; "óbvio pelo nome do campo". **Inferência forte** = pelo menos uma fonte direta + uma segunda fonte (direta ou heurística) concordando, **ou** uma fonte direta inequívoca para um fato simples (tamanho de campo, `NOT NULL`, valor de combo). **Inferência fraca** = só fontes heurísticas, **ou** uma única fonte direta para um ponto crítico (regra de negócio, valor codificado, comportamento condicional, motivação por trás de uma validação). Inferência fraca **não vai para a doc sem pergunta de confirmação ao usuário**. --- ## 🔀 Identificando o modo Leia a mensagem do usuário e classifique: | Modo | O usuário diz algo como | |------|-------------------------| | **Criar** | "Criar documentação para X", "Documentar a tela X", "Novo módulo Y", "Preciso de docs sobre X" | | **Atualizar** | "Atualizar documentação de X", "A tela X mudou", "Adicionar seção sobre Y na doc de Z" | | **Auditar** | "Auditar documentação", "Revisar conformidade", "Verificar docs do módulo X", "Tem algo errado nas docs?" | Se o pedido for ambíguo, pergunte antes de criar qualquer arquivo. --- ## 📐 Arquétipos de documento O template clássico (`🎯 Visão Geral → 🔧 Seções → 💡 Exemplos → ❓ FAQ`) é de **doc de tela/feature**. O portal tem outros arquétipos, com estrutura própria — **não os force no template de tela**. Em particular, as regras "FAQ ≥ 5 perguntas" e "abre com `# 📄 [Título]`" valem **só para doc de tela/feature**. | Arquétipo | Quando | Estrutura típica | |---|---|---| | **Doc de tela / feature** | Documentar uma tela ou funcionalidade | `🎯 Visão Geral` → seções funcionais → `💡 Exemplos` → `❓ FAQ` (≥ 5) → rodapé | | **Índice de mensagens** (`indice_mensagens.md`) | Catálogo de mensagens de um módulo | `🎯 Visão Geral` (índice, não fonte) → tabelas `Mensagem · Onde aparece · Causa · Detalhes` por categoria → `🔗 Páginas-fonte`. Sem FAQ. Ver regra de **Mensagens de tela**. | | **Trilha** (`Trilhas/` ou `PrimeirosPassos/`) | Guiar uma tarefa (operacional) ou um papel (onboarding) de ponta a ponta | Encadeia docs existentes **sem duplicar**: objetivo → etapas (cada uma: o que fazer + o que você sabe ao terminar) → checklist → próximos passos. Operacionais têm diagrama + "quando dá errado". | | **Glossário** (`glossario.md`) | Vocabulário | Verbetes `### Termo` + definição curta + `**Onde aparece:**`. Os termos viram tooltip inline automaticamente — enriquecer o glossário acende mais termos nas docs. | | **Hub / índice de módulo** (`README.md`) | Porta de entrada de uma pasta | Tabela de documentos + "por onde começar". Sem FAQ. | Antes de escrever, **identifique o arquétipo** e siga a estrutura dele (espelhe um arquivo vizinho do mesmo tipo). --- ## ✨ Modo: CRIAR ### Passo 1 — Coletar entradas Pergunte em **uma única mensagem** (não uma por vez): 1. **Módulo**: Em qual pasta? (`Financeiro/`, `Fiscal/`, `Movimentacao/`, `RH/`, `Agronomico/`, `SelfCheckout/`, ou novo) 2. **Tema**: Nome da funcionalidade ou tela (ex: "Cashback PDV", "Receituário Agronômico") 3. **Fonte do conteúdo**: De onde vem o conteúdo? - Descrição verbal (usuário explica no chat) - Issue do GitHub: peça o número da issue em `hetosoft/ProjetosSol.NET` ou `hetosoft/portal-documentacao-solnet` - PRs do GitHub: peça o(s) número(s) de PR em `hetosoft/ProjetosSol.NET` - Combinação + imagens/screenshots que o usuário vai colar 4. **Subtema existente**: Já existem arquivos sobre esse tema na pasta do módulo? (define se é necessário criar subgrupo no sidebar) Se o conteúdo vier de issues ou PRs, busque-os via GitHub MCP antes de continuar. ### Passo 2 — Validar códigos de tela **Antes de escrever qualquer linha da documentação**, consulte o `ID_FORMULARIO` de cada tela que será referenciada. Veja `references/screen_lookup.md` para o procedimento exato. **Nunca invente ou suponha um código.** ### Passo 3 — Decidir estrutura de arquivos **Módulo novo** (pasta não existe): - Criar `/README.md`, `/documentacao_.md`, `/guia_rapido.md`, `/faq.md` - Adicionar novo grupo no sidebar e link no portal `README.md` **Novo tema dentro de módulo existente** (sem arquivos para este tema): - Criar `/documentacao_.md`, `/guia_rapido_.md`, `/faq_.md` - Atualizar `README.md` do módulo - Atualizar `nav.yaml` (pode exigir subgrupo aninhado — veja `references/navegacao_nav_yaml.md`) **Tema existente, arquivo(s) faltando** (preencher lacuna): - Criar apenas o(s) arquivo(s) ausentes - Atualizar `README.md` do módulo e sidebar Quando a granularidade for ambígua (tema que poderia ser subtópico ou módulo separado), apresente duas opções com recomendação e peça confirmação antes de criar qualquer arquivo. ### Passo 4 — Checkpoint de entendimento (antes de escrever) Depois da investigação (Passo 2) e da decisão de estrutura (Passo 3), e **antes** de começar a escrever qualquer arquivo, resuma para o usuário numa única mensagem: - **Escopo** — quais arquivos serão criados e o que cada um cobre - **Telas envolvidas** — nome + `ID_FORMULARIO` confirmado para cada uma - **Estrutura do documento principal** — lista dos títulos `##` que pretende usar - **Campos / regras de negócio principais** — bullets curtos resumindo o que você entendeu da funcionalidade a partir da investigação - **Pontos ainda incertos** — inferências fracas (ver princípio acima) listadas como perguntas objetivas Pare e espere o "pode escrever" (ou correções). Só prossiga para o Passo 5 quando o usuário aprovar. Esse checkpoint é o que evita reescrever doc inteiro depois de uma virada de premissa. ### Passo 5 — Escrever os documentos Identifique o **arquétipo** (ver "📐 Arquétipos de documento") e siga a estrutura dele. Para **doc de tela/feature**, aplique a **«🔬 Profundidade de uma doc de tela»** (botões um a um, menus de contexto, teclas validadas, comportamentos contraintuitivos, funções e origem/destino cruzados) e use o template do `CLAUDE.md` (`## Document Style`): ``` # 📄 [Título] - Sol.NET ## 🎯 Visão Geral [Descrição clara do propósito — o que é, para que serve] ### Principais Características: - ✅ Característica 1 - ✅ Característica 2 --- ## 🔧 [Seções Funcionais] [Conteúdo detalhado — como usar, passo a passo] --- ## 💡 Exemplos Práticos [Cenários reais que o suporte encontraria no dia a dia] --- ## ❓ FAQ / Problemas Comuns [Mínimo 5 perguntas, organizadas por categoria se >8] --- **Última atualização**: [Mês de Ano] **Versão**: [X.X] **Público-alvo**: [Usuários do Sol.NET / Equipe de Suporte / Administradores] ``` **Versionamento**: Novos documentos começam em `1.0`. Sempre informe a versão sugerida e peça confirmação ao usuário antes de commitar. **Guia Rápido**: formato de checklist — o que clicar, o que confirmar, em qual ordem. Pense nele como um cartão de referência que o suporte consulta durante o atendimento. **FAQ** (doc de tela/feature; índices, glossário, trilhas e hubs **não** têm FAQ): mínimo 5 perguntas. Para >8, organize por categoria com cabeçalho `### Categoria`. Formato de cada entrada: ```markdown ### ❓ Pergunta que o usuário realmente faria? Resposta prática e direta. Se há mais de um passo, use lista numerada. ``` ### Passo 6 — Atualizar infraestrutura Após escrever os documentos, atualize a infraestrutura. As duas primeiras são **sempre**; as demais são **condicionais** — avalie cada uma a cada doc nova (uma página fora desses índices fica órfã ou invisível para quem chega por outro caminho). **Sempre:** 1. **`nav.yaml`** (raiz do repo): adicione as entradas. Itens vão em `sidebar:` (público) ou `internal:` (restrito). Estrutura hierárquica com `label`, `icon`, `href` e `items:` aninhados — siga o padrão dos vizinhos. Para subgrupos aninhados (>2 arquivos por subtema), espelhe `Fiscal`, `Movimentação` e `Produtos` (ver `references/navegacao_nav_yaml.md`). 2. **`README.md` do módulo** (`public//README.md` ou `internal//README.md`): adicione os links no índice, no padrão das seções existentes. **Condicional (avalie e atualize quando se aplicar):** 3. **`public/quero.md`** (índice por tarefa): se a doc resolve uma tarefa de usuário ("Quero…") sem entrada ainda, adicione uma no formato das existentes (pergunta em 1ª pessoa → link + código). 4. **`public/glossario.md`** — **sempre que a doc introduz um termo ou conceito de domínio** (uma entidade, um tipo de documento, um verbo da operação), crie o verbete: `### Termo` (com âncora explícita `{#termo}` quando tiver acento) + definição curta + linha `**Onde aparece:**` com os links de tela + código. **Adicione o termo ao índice alfabético** no topo do glossário. Os termos viram **tooltip inline** em todas as docs — cada verbete novo acende o termo em todo o portal. **Não deixe um conceito novo sem verbete.** 5. **Cross-links bidirecionais**: se a doc cita outra (e vice-versa), garanta o link nos dois sentidos — inclusive a partir das docs de telas que **disparam ou contêm** a funcionalidade. 6. **`/indice_mensagens.md`**: se a tela gera mensagens catalogáveis, registre-as. Só existe hoje em Financeiro, Fiscal, Movimentação e PDV (ver regra «Mensagens de tela»). 7. **Trilhas**: quando a doc nova **fecha (ou completa) um fluxo operacional de ponta a ponta** (`Movimentacao/Trilhas/`) ou um **perfil de onboarding** (`PrimeirosPassos/`), **crie a trilha** encadeando as docs existentes sem duplicá-las (objetivo → etapas → checklist → próximos passos; operacionais ganham diagrama + "quando dá errado") e atualize o `README.md`/índice de trilhas. Se o tema só **encaixa** num fluxo já documentado, adicione um link leve na trilha existente em vez de criar uma nova. 8. **Portal `README.md`** (raiz da audiência): só se for **módulo novo** ou adição estruturalmente significativa (tabela «O ecossistema»). 9. **Rodapé do portal** (`public/README.md`, linha `📅 Última atualização: de · 📦 Versão X.Y`): atualize sempre o mês/ano. A `📦 Versão` só sobe em mudança estrutural (módulo novo, reorganização) — proponha o número e confirme com o usuário. > **Não mexer** sem motivo: `sitemap` (auto-gerado de `public/`), `privacidade.md`, `visao_geral_sol_net.md` (só se mudar o modelo das 3 dimensões). ### Passo 7 — Commit e PR > **Antes de commitar, rode a Validação local** (seção «✅ Validação local», abaixo) e reporte o resultado no corpo do PR. Crie uma branch com nome `docs/` (letras minúsculas, hífens, apenas ASCII, sem acentos). Exemplo: tema "Cashback PDV" → branch `docs/cashback-pdv`. Commit de todos os arquivos em um único commit com mensagem em português: ``` docs: cria documentação de [tema] no módulo [Módulo] ``` Abra PR de `docs/` → `main` em `hetosoft/portal-documentacao-solnet`. Título e corpo do PR em português. O corpo deve listar: - O que foi criado (lista de arquivos) - Códigos de tela referenciados - Fontes usadas (números de PR/issue, se aplicável) --- ## ✏️ Modo: ATUALIZAR ### Passo 1 — Identificar escopo Pergunte: 1. Qual(is) arquivo(s) precisam de atualização? 2. O que mudou? (descrição verbal, número(s) de PR, número(s) de issue) Busque o conteúdo do GitHub via MCP se forem fornecidos números de PR ou issue. ### Passo 2 — Validar novas referências de tela Se a atualização introduz telas novas, valide seus códigos (veja `references/screen_lookup.md`). ### Passo 3 — Checkpoint de entendimento (antes de aplicar mudanças) Após investigar (Passo 2) e **antes de tocar nos arquivos**, resuma para o usuário numa única mensagem: - **Arquivos que vou alterar** e o que muda em cada um - **O que entendi do que mudou na funcionalidade** (bullets curtos derivados da investigação) - **Versão sugerida** para cada doc filho (incremento menor `1.0 → 1.1` ou maior `1.x → 2.0`) e justificativa - **Pontos ainda incertos** — inferências fracas que precisam de confirmação Pare e espere o "pode aplicar" (ou correções) antes de seguir para o Passo 4. ### Passo 4 — Aplicar mudanças - Adicione às seções existentes em vez de criar seções paralelas - Ao detalhar comportamento de tela, aplique a **«🔬 Profundidade de uma doc de tela»** (botões, menus de contexto, teclas validadas, comportamentos contraintuitivos, funções, origem/destino cruzados) - Preserve o vocabulário de emojis e a formatação do arquivo existente - Atualize o rodapé de metadados do doc alterado: - `**Última atualização**`: mês e ano atual - `**Versão**`: aplique o incremento confirmado no Passo 3 - **`nav.yaml`** (raiz): se o título visível mudou, atualize o `label` correspondente; se o arquivo foi renomeado, atualize o `href`; se removido, remova a entrada. - **Rodapé do portal** (`public/README.md`, linha `📅 Última atualização: de · 📦 Versão X.Y`): sempre que a versão de um doc filho é bumpada, atualize o mês/ano do portal para o atual. A `📦 Versão` do portal só sobe em mudanças estruturalmente significativas — proponha o novo número e peça confirmação ao usuário. ### Passo 5 — Commit e PR > **Antes de commitar, rode a Validação local** (seção «✅ Validação local», abaixo) e reporte o resultado no corpo do PR. Branch: `docs/` (mesma convenção do modo Criar). Commit: ``` docs: atualiza documentação de [tema] no módulo [Módulo] ``` PR → `main`. Descreva o que mudou e por quê, referenciando o PR/issue de origem se houver. --- ## 🔍 Modo: AUDITAR ### Passo 1 — Definir escopo Se o usuário especificou um módulo ou arquivo, audite apenas aquele. Caso contrário, audite o repositório inteiro. ### Passo 2 — Verificar cada arquivo contra estas regras Para cada arquivo `.md` (pule `CLAUDE.md`, `README.md` raiz, `teste_mermaid.md`): | Regra | O que verificar | |-------|-----------------| | Sem caminhos de menu | Nenhum texto com padrão `Menu >` ou `> Submenu` | | Referências de tela | Toda tela mencionada inclui código (`código NNN` ou `(código NNN)`) | | Atalhos de teclado | Somente `F1` é permitido sem validação; qualquer outro (`F4`, `F5`, `Ctrl+X`) é violação | | Nomenclatura de arquivos | Todos os `.md` são snake_case, apenas ASCII | | Links internos | Sem `%20` em links relativos | | Estrutura de emoji | Documento abre com `# 📄`, tem `## 🎯 Visão Geral`, termina com rodapé de metadados | | Idioma | Sem inglês, espanhol ou jargão de desenvolvimento | | Público-alvo | Sem referências ao código-fonte, termos Delphi, ou detalhes de implementação | | Nota de acesso restrito | Toda instrução de alteração em `Cadastro de Empresas` ou `Cadastro de Tipos de Movimento` tem a nota de aviso de acesso de suporte imediatamente após | | `nav.yaml` | Todo `.md` publicado (exceto `README.md` da raiz de cada audiência, `HOSPEDAGEM_LOCAL.md` e arquivos internos do skill) tem entrada correspondente em `nav.yaml` | | Audiência correta | Páginas com instalação/credenciais/DLLs/operação interna ficam em `internal/` com `audience: internal` no front-matter; páginas para usuário final ficam em `public/` | | Profundidade da doc de tela | A doc esgota botões (um a um), menus de contexto, teclas validadas, comportamentos contraintuitivos (`⚠️`), funções e origem/destino cruzados (ver «🔬 Profundidade de uma doc de tela»). Doc rasa que só lista campos é violação. | | Glossário | Termos/conceitos de domínio citados pela doc têm verbete em `glossario.md` (e entrada no índice alfabético) | ### Passo 3 — Corrigir e documentar Corrija todos os problemas encontrados. Para cada correção, registre uma linha explicando o que foi alterado e por quê — isso vira o corpo do PR. Para atalhos não validados: remova o atalho e substitua pelo padrão genérico do `CLAUDE.md`: - *"Acesse a tela `X` (código `NNN` na pesquisa F1)"* - *"Use o botão equivalente na tela"* ### Passo 4 — Commit e PR > **Antes de commitar, rode a Validação local** (seção «✅ Validação local», abaixo) — em especial, confirme que os links/âncoras corrigidos resolvem. Branch: `docs/auditoria-` (ou `docs/auditoria-geral` para o repositório inteiro). Commit: ``` docs: correções de conformidade — auditoria [módulo/geral] ``` PR → `main`. Corpo: tabela com cada problema encontrado e como foi corrigido. --- ## ✅ Validação local (antes do commit) Documentação no portal é **renderizada e navegada** — um doc que "compila" não é um doc que funciona. Antes de commitar, valide o que mexeu: 1. **Suba a app** (`dotnet run --project src/PortalDocs`) e abra as páginas novas/alteradas. 2. **Rotas:** cada página nova responde **200** na sua rota (`//`); página interna exige login (**302 → `/login`** para anônimo). 3. **Links:** todos os links da página resolvem (sem 404). Confira em especial os de índice (forma de pasta) e que **nenhum** atravessa `public/`↔`internal/`. 4. **Âncoras:** se linkou `arquivo.md#secao`, confirme que o `id` existe no HTML renderizado (acentos podem mudar). 5. **Mermaid:** todo diagrama novo valida em https://mermaid.live/ (falha em silêncio no portal). 6. **`nav.yaml`:** parseia e a página aparece no menu — `uv run --with pyyaml python -c "import yaml;yaml.safe_load(open('nav.yaml',encoding='utf-8'))"`. 7. **Interativo** (se mexeu em componente/JS): teste no **navegador real** — clicar, recarregar, navegar — não confie só no HTTP 200. --- ## 📁 Arquivos de referência Leia estes arquivos quando precisar de detalhes específicos: - **`references/screen_lookup.md`** — Procedimento exato para buscar códigos de tela via GitHub MCP, incluindo fallback de PAT e o que fazer quando o acesso falha - **`references/navegacao_nav_yaml.md`** — Estrutura do `nav.yaml`: blocos `header` / `sidebar` / `internal`, forma dos itens, subgrupos aninhados e o grupo de topo «Por onde começar». - **`references/consulta_banco.md`** — Como consultar o banco do Sol.NET (schema, valores codificados de combos/status, exemplos reais) para nutrir a doc, validar código de tela e conferir valores gravados.