@gitpagedocs/cli 0.0.8 → 0.0.9

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (15) hide show
  1. package/builders/route-builders.mjs +13 -0
  2. package/builders/version-config-builder.mjs +17 -4
  3. package/content/assets/gitpagedocs-project-guide.pdf +245 -0
  4. package/content/docs-en.mjs +645 -102
  5. package/content/docs-es.mjs +649 -90
  6. package/content/docs-pt.mjs +649 -90
  7. package/contracts/doc-versions.mjs +1 -1
  8. package/contracts/index.mjs +1 -0
  9. package/data/default-site-config.mjs +38 -0
  10. package/data/i18n-langmenu.mjs +81 -0
  11. package/data/path-mappings.mjs +13 -0
  12. package/data/route-metas.mjs +59 -2
  13. package/package.json +3 -3
  14. package/runtime/doc-path-resolver.mjs +22 -13
  15. package/runtime/output.mjs +16 -1
package/content/docs-pt.mjs CHANGED
@@ -1,4 +1,82 @@
1
1
  export const docsPt = {
2
+ pdf: `# Documentos PDF
3
+
4
+ PDF é um tipo de conteúdo próprio, junto com Markdown, HTML, código-fonte, vídeo e áudio. A prévia usa o visualizador nativo de PDF do navegador. As ações de baixar e abrir em nova aba são configuráveis de forma independente.
5
+
6
+ ## Guia do projeto em inglês
7
+
8
+ O scaffold inclui o [Guia do projeto GitPageDocs (PDF, inglês)](https://github.com/Vidigal-code/git-page-docs/blob/main/cli/content/assets/gitpagedocs-project-guide.pdf). Ele explica o projeto, pacotes, configuração, ícones, modo foco, narração, CLI, MCP e publicação. O PDF está em inglês; esta referência possui versões em português, inglês e espanhol.
9
+
10
+ A CLI copia os bytes do anexo para \`gitpagedocs/docs/versions/<versão>/en/gitpagedocs-project-guide.pdf\`. Os três caminhos de idioma do exemplo apontam para esse arquivo em inglês. Para oferecer traduções, adicione os PDFs traduzidos e altere o caminho de cada idioma.
11
+
12
+ ## Padrões do site
13
+
14
+ Adicione este bloco dentro de \`site\` em \`gitpagedocs/config.json\`:
15
+
16
+ \`\`\`json
17
+ {
18
+ "pdf": {
19
+ "enabled": true,
20
+ "previewEnabled": true,
21
+ "downloadEnabled": true,
22
+ "openInNewTabEnabled": true
23
+ }
24
+ }
25
+ \`\`\`
26
+
27
+ \`enabled\` é a chave geral do conteúdo PDF. Os demais campos controlam a prévia, o botão de download e o link de nova aba. Todo campo omitido assume \`true\`, inclusive em configurações antigas.
28
+
29
+ A precedência das ações é \`rota.pdf.<flag>\` > \`site.pdf.<flag>\` > \`true\`. Um \`true\` explícito na rota habilita aquela ação mesmo quando o padrão do site é \`false\`; \`site.pdf.enabled: false\` continua desabilitando todos os PDFs. Sem caminho para o idioma selecionado, o PDF fica indisponível; não há fallback automático de idioma.
30
+
31
+ ## Exemplo de rota e menu
32
+
33
+ Em \`gitpagedocs/docs/versions/0.0.9/config.json\`, mantenha as listas de rotas e menus no nível principal:
34
+
35
+ \`\`\`json
36
+ {
37
+ "routes-pdf": [{
38
+ "id": 23,
39
+ "title": { "en": "Project guide (English)", "pt": "Guia do projeto (inglês)", "es": "Guía del proyecto (inglés)" },
40
+ "pdf": {
41
+ "pathPdf": {
42
+ "en": "gitpagedocs/docs/versions/0.0.9/en/gitpagedocs-project-guide.pdf",
43
+ "pt": "gitpagedocs/docs/versions/0.0.9/en/gitpagedocs-project-guide.pdf",
44
+ "es": "gitpagedocs/docs/versions/0.0.9/en/gitpagedocs-project-guide.pdf"
45
+ },
46
+ "previewEnabled": true,
47
+ "downloadEnabled": true,
48
+ "openInNewTabEnabled": true
49
+ }
50
+ }],
51
+ "menus-header-pdf": [{
52
+ "id": 23,
53
+ "en": { "title": "Project guide (English)", "path-click": "page:23" },
54
+ "pt": { "title": "Guia do projeto (inglês)", "path-click": "page:23" },
55
+ "es": { "title": "Guía del proyecto (inglés)", "path-click": "page:23" }
56
+ }]
57
+ }
58
+ \`\`\`
59
+
60
+ O mapa \`pdf.pathPdf\` seleciona o arquivo do idioma atual. Use \`page:<id>\` nos destinos dos menus PDF. A mesma estrutura recursiva de \`submenus\` dos outros menus está disponível. O scaffold reserva o ID 23 para o exemplo PDF e o ID 24 para esta referência Markdown; use IDs únicos para páginas adicionais.
61
+
62
+ As flags opcionais da rota ficam dentro de \`pdf\`. Apresentação compartilhada, \`container\`, \`RouteGuide\` e autorização continuam no nível da rota. \`routeDefaults\` também atende rotas PDF. Adicione \`"pdf": 5\` em \`hierarchyPage\` e \`hierarchyMenu\` para posicionar PDFs depois do áudio; ajuste os valores conforme a ordem desejada.
63
+
64
+ ## Arquivos e publicação
65
+
66
+ Caminhos relativos à raiz do repositório que começam com \`gitpagedocs/\` são copiados para os assets públicos do visualizador ao iniciar ou compilar o Next.js. A URL respeita o subdiretório de publicação no GitHub Pages. Versione o PDF no Git e publique-o junto com a documentação gerada. Arquivos fora de \`gitpagedocs/\` devem estar em \`frontend/public/\` do visualizador ou acessíveis por uma URL HTTP(S).
67
+
68
+ Use a URL do PDF binário, não uma página HTML de prévia do repositório. Em repositórios remotos, o caminho configurado é resolvido nesse repositório. Tanto a prévia quanto o download buscam os bytes do arquivo, portanto um servidor externo precisa permitir CORS nas duas operações. O visualizador valida a assinatura PDF e cria uma URL Blob temporária com tipo \`application/pdf\` para a prévia nativa; essa URL é liberada ao trocar ou fechar o documento. A política de incorporação e os cabeçalhos de tipo/disposição do servidor de origem não controlam essa prévia Blob.
69
+
70
+ O link de nova aba abre diretamente a URL original. Seu comportamento depende do navegador e dos cabeçalhos \`Content-Type\` e \`Content-Disposition\`; uma URL raw pode baixar o arquivo em vez de exibi-lo. O link direto continua disponível se a prévia ou o download falhar, exceto quando essa ação está desabilitada.
71
+
72
+ ## Leitura e diagnóstico
73
+
74
+ - Os controles nativos de PDF, teclado, zoom e navegação entre páginas dependem do navegador. Alguns navegadores móveis abrem ou baixam o arquivo em vez de incorporá-lo.
75
+ - A prévia não converte PDF em Markdown. Modo foco, navegação por seção, cópia de Markdown e narração atuam em documentos Markdown, não no PDF incorporado.
76
+ - Desabilitar a prévia pode manter download e nova aba disponíveis. Desabilitar todas as ações deixa o PDF sem controle interativo.
77
+ - Ocultar um botão não controla acesso. PDFs hospedados publicamente continuam acessíveis pela URL. Documentos confidenciais precisam de hospedagem protegida.
78
+ - Se a prévia estiver vazia, use a ação de nova aba, confira se o caminho retorna um PDF e examine os cabeçalhos do servidor. Falhas de download são informadas na página.
79
+ `,
2
80
  index: `# Git Page Docs
3
81
 
4
82
  Git Page Docs e um runtime de documentacao multi-idioma para repositorios que possuem a pasta \`gitpagedocs/\`.
@@ -31,45 +109,63 @@ O runtime espera esta estrutura:
31
109
  - Abra **Temas e layouts** para autoria de templates.
32
110
  - Abra **Rotas autorizadas** para configurar chave, papeis e autenticacao externa.
33
111
  - Abra **FAQ** para troubleshooting.
112
+
113
+ ## Referências detalhadas
114
+
115
+ - **Referência da CLI**: instalação, todos os comandos e flags de compatibilidade.
116
+ - **Servidor MCP**: cliente, 20 tools, 7 resources e configuração de provedores.
117
+ - **Navegação e submenus**: árvores recursivas, URLs e sobrescritas dos breadcrumbs.
118
+ - **Modo foco**: copiar/baixar Markdown e navegar por seção/documento.
119
+ - **Acessibilidade e narração**: vozes do navegador, controles e interação com mídias.
120
+ - **Documentos PDF**: prévia nativa, download/nova aba e o guia incluído em inglês.
34
121
  `,
35
122
  gettingStarted: `# Primeiros passos
36
123
 
37
- Este guia leva o projeto do zero ate docs rodando.
124
+ O Git Page Docs separa os arquivos de documentação do visualizador. Instale a CLI para criar os arquivos; use o visualizador oficial, GitHub Pages ou um checkout do runtime para exibi-los.
38
125
 
39
- ## Pre-requisitos
126
+ ## Requisitos e instalação
40
127
 
41
- - Node.js 20+
42
- - npm 10+ (ou pnpm)
128
+ Use Node.js 20 ou superior. Git é necessário para publicar; GitHub CLI é necessário quando a CLI configura o Pages automaticamente.
43
129
 
44
- ## Setup local
130
+ \`\`\`bash
131
+ npm install --save-dev @gitpagedocs/cli
132
+ npx gitpagedocs --no-interactive --owner SEU_USUARIO --repo SEU_REPOSITORIO
133
+ \`\`\`
45
134
 
46
- 1. Instale dependencias:
47
- - \`npm install\`
48
- 2. Gere/atualize os artefatos de docs:
49
- - \`npm run gitpagedocs\`
50
- 3. Inicie o desenvolvimento:
51
- - \`npm run dev\`
52
- 4. Build e execucao local de producao:
53
- - \`npm run build\`
54
- - \`npm start\`
135
+ Para executar sem instalação local, use \`npx --yes @gitpagedocs/cli --no-interactive --owner SEU_USUARIO --repo SEU_REPOSITORIO\`. Para instalar globalmente, use \`npm install -g @gitpagedocs/cli\` e depois \`gitpagedocs\`. Execute na raiz do repositório.
55
136
 
56
- ## Comportamento da CLI
137
+ ## Contrato gerado
57
138
 
58
- \`npx @gitpagedocs/cli\` (ou \`npm run gitpagedocs\`) gera os artefatos na pasta oficial \`gitpagedocs/\`.
139
+ - \`gitpagedocs/config.json\`: opções do site e referências das versões.
140
+ - \`gitpagedocs/langs/{en,pt,es}.json\`: textos da interface.
141
+ - \`gitpagedocs/docs/versions/<version>/config.json\`: rotas e menus.
142
+ - \`gitpagedocs/docs/versions/<version>/{en,pt,es}/*.md\`: conteúdo; os nomes dos arquivos permanecem em inglês nos três idiomas.
143
+ - \`gitpagedocs/icon.svg\`: ícone do site.
144
+ - \`--layoutconfig\` também grava \`gitpagelayouts/\`; \`--layouts-dir\` altera essa pasta.
59
145
 
60
- - Gera somente markdown/json
61
- - Nao gera \`index.html\`
62
- - Nao gera \`index.js\`
63
- - Nao executa comandos de instalacao
146
+ O gerador escreve configuração e conteúdo; ele não instala uma aplicação Next.js no seu repositório. Executá-lo novamente regrava os arquivos do scaffold: revise o diff do Git antes de manter mudanças em documentação editada manualmente.
64
147
 
65
- ## Modo de busca por repositorio
148
+ ## Ler e publicar
66
149
 
67
- No ambiente local, o controle e por variavel:
150
+ Faça commit e push da pasta gerada e abra \`https://vidigal-code.github.io/git-page-docs/SEU_USUARIO/SEU_REPOSITORIO/\` para um repositório público. Para publicar seu próprio site, autentique com \`gh auth login\` e execute \`npx gitpagedocs pages deploy --owner SEU_USUARIO --repo SEU_REPOSITORIO\`. Isso gera arquivos, faz commit e push; acompanhe a execução do GitHub Actions. Consulte Publicação para subcaminhos e o contrato do workflow.
68
151
 
69
- - \`GITPAGEDOCS_REPOSITORY_SEARCH=true\`
70
- - \`GITPAGEDOCS_REPOSITORY_SEARCH=false\`
152
+ ## Desenvolver o visualizador localmente
71
153
 
72
- Em build de GitHub Pages (\`GITHUB_ACTIONS=true\`), a busca de repositorio fica sempre ativa.
154
+ Os comandos abaixo pertencem a um checkout do Git Page Docs, não a um repositório que contém apenas arquivos gerados:
155
+
156
+ \`\`\`bash
157
+ git clone https://github.com/Vidigal-code/git-page-docs.git
158
+ cd git-page-docs
159
+ corepack enable
160
+ pnpm install --frozen-lockfile
161
+ pnpm dev
162
+ \`\`\`
163
+
164
+ O repositório fixa o pnpm em \`packageManager\`. \`pnpm dev\` ativa a busca de repositórios; \`pnpm dev:e2e\` usa a documentação local. Para produção local, execute \`pnpm build\` e \`pnpm start\`; o script start recompila antes de iniciar. Configure \`PORT=3100\` no ambiente do processo quando a porta 3000 estiver ocupada.
165
+
166
+ ## Próximos passos
167
+
168
+ Use Configuração para idiomas, ícones, navegação, foco e narração; Funcionalidades para CLI e MCP; Temas e layouts para tokens visuais; Perguntas frequentes para diagnóstico.
73
169
  `,
74
170
  projectOverview: `# Visao geral do projeto
75
171
 
@@ -101,51 +197,9 @@ Git Page Docs e um monorepo pnpm + turborepo que transforma a pasta \`gitpagedoc
101
197
 
102
198
  Referencia completa de opcoes da CLI, chaves de configuracao e recursos do runtime.
103
199
 
104
- ## Comandos da CLI
200
+ ## Linha de comando
105
201
 
106
- | Comando | Descricao |
107
- |---------|------------|
108
- | \`npx @gitpagedocs/cli\` | Gera config e docs em \`gitpagedocs/\` |
109
- | \`npx @gitpagedocs/cli --layoutconfig\` | Tambem gera layouts/templates locais em \`gitpagelayouts/\` |
110
- | \`npx @gitpagedocs/cli --home\` | Distribuicao standalone (\`gitpagedocshome/\`) |
111
- | \`npx @gitpagedocs/cli --push --owner X --repo Y\` | Configura workflow, commit, push |
112
- | \`npx @gitpagedocs/cli --interactive\` / \`-i\` | Modo interativo com prompts (padrao em um terminal) |
113
- | \`npx @gitpagedocs/cli --no-interactive\` / \`--yes\` / \`-y\` | Nunca pergunta; usa flags e padroes |
114
- | \`gitpagedocs ai\` | Gerador interativo de documentacao com IA |
115
- | \`gitpagedocs chat [pergunta]\` | Chat de IA com streaming no terminal (REPL em TTY; resposta unica com pergunta ou stdin) |
116
- | \`gitpagedocs provider [id]\` / \`models [provider]\` | Lista provedores de IA / modelos do catalogo |
117
- | \`gitpagedocs document[:repo\\|:file\\|:folder]\` | Gera documentacao com IA |
118
- | \`gitpagedocs deploy\` / \`pages [actions\\|deploy]\` | Configura GitHub Pages via Actions + push |
119
- | \`gitpagedocs docs\` | Atualiza as regioes gerenciadas de README/CONTRIBUTING/SECURITY |
120
- | \`gitpagedocs password\` | Define a senha de acesso a documentacao (chave publica em \`site.docsAccess\`) |
121
- | \`gitpagedocs config\` / \`config clear\` | Mostra a config resolvida / apaga a config salva e o cofre de chaves |
122
- | \`gitpagedocs doctor\` / \`version\` / \`update\` | Diagnostico / versao / verificacao de atualizacao no registro |
123
- | \`gitpagedocs mcp start\` | Inicia o servidor MCP via stdio |
124
-
125
- Instale globalmente com \`npm install -g @gitpagedocs/cli\` ou rode sem instalar com \`npx @gitpagedocs/cli\`.
126
-
127
- ## Opcoes da CLI
128
-
129
- | Opcao | Descricao |
130
- |-------|-----------|
131
- | \`--owner <user>\` | Owner do GitHub |
132
- | \`--repo <repo>\` | Repositorio GitHub |
133
- | \`--path <subpath>\` | Subcaminho dos docs (ex: \`docs\`); sem ele, base path = nome do repo para CSS/JS em project sites |
134
- | \`--output <dir>\` | Diretorio de saida (padrao: \`gitpagedocs\`) |
135
- | \`--search true|false\` | Habilita/desabilita busca de repositorio (\`--home\`) |
136
- | \`--layoutconfig\` | Gera layouts locais em \`gitpagelayouts/\` |
137
- | \`--layouts-dir <dir>\` | Pasta dos layouts locais (padrao: \`gitpagelayouts\`) |
138
- | \`--push\` | Cria workflow, commit de artefatos, push |
139
- | \`--pages-actions\` | Apenas muda a fonte do GitHub Pages para GitHub Actions (igual a \`pages actions\`) |
140
- | \`--home\` | Gera \`gitpagedocshome/\` (estatico + .env + Dockerfile) |
141
-
142
- ## Saida gerada
143
-
144
- - \`gitpagedocs/config.json\` – config raiz
145
- - \`gitpagedocs/icon.svg\` – icone padrao
146
- - \`gitpagedocs/docs/versions/<ver>/config.json\` – rotas por versao
147
- - \`gitpagedocs/docs/versions/<ver>/{en,pt,es}/*.md\` – docs em markdown
148
- - \`gitpagelayouts/\` – apenas com \`--layoutconfig\` (pasta configuravel com \`--layouts-dir\`)
202
+ Consulte **Referência da CLI** para comandos, flags, exemplos e compatibilidade. Consulte **Servidor MCP** para integração com editores.
149
203
 
150
204
  ## Tipos de conteudo
151
205
 
@@ -155,6 +209,7 @@ Instale globalmente com \`npm install -g @gitpagedocs/cli\` ou rode sem instalar
155
209
  | HTML | \`routes-html\` | \`path\` local ou \`url\` externa |
156
210
  | Video | \`routes-video\` | \`video.pathVideo\`, \`video.videoType\` |
157
211
  | Audio | \`routes-audio\` | \`audio.pathAudio\`, \`audio.audioType\` |
212
+ | PDF | \`routes-pdf\` | \`pdf.pathPdf\` por idioma; prévia nativa e download |
158
213
 
159
214
  ## Visualizador de codigo fonte
160
215
 
@@ -238,6 +293,37 @@ Principais chaves:
238
293
  - \`layoutsConfigPath\`: fallback remoto para layouts
239
294
  - \`rendering\`: URL canonica publicada
240
295
 
296
+ ## Controles de idioma, tema e foco
297
+
298
+ Em \`gitpagedocs/config.json\`, adicione estas entradas a \`site.icons\` para usar React Icons no seletor de idioma, no seletor de tema e no botao de foco:
299
+
300
+ \`\`\`json
301
+ {
302
+ "site": {
303
+ "icons": {
304
+ "LanguageSelector": {
305
+ "reactIcon": true, "tag": "FiGlobe", "size": "22px",
306
+ "colorDark": "currentColor", "colorLight": "currentColor"
307
+ },
308
+ "ThemeSelector": {
309
+ "reactIcon": true, "tag": "BsSunFill", "size": "22px",
310
+ "colorDark": "currentColor", "colorLight": "currentColor"
311
+ },
312
+ "FocusMode": {
313
+ "reactIcon": true, "tag": "MdFullscreen", "size": "22px",
314
+ "colorDark": "currentColor", "colorLight": "currentColor"
315
+ },
316
+ "QuickNavigation": {
317
+ "reactIcon": true, "tag": "FiSearch", "size": "22px",
318
+ "colorDark": "currentColor", "colorLight": "currentColor"
319
+ }
320
+ }
321
+ }
322
+ }
323
+ \`\`\`
324
+
325
+ Cada controle e independente: \`reactIcon: false\` preserva a aparencia atual com texto (padrao); \`true\` mostra o icone. Personalize \`tag\`, \`size\`, \`colorDark\` e \`colorLight\` por controle; \`currentColor\` acompanha o tema ativo. Os seletores com icone mantem seus menus e nomes acessiveis. \`site.FocusMode\` continua controlando se o modo foco esta habilitado; \`site.icons.FocusMode\` altera apenas a aparencia do botao.
326
+
241
327
  ## Secao \`VersionControl\`
242
328
 
243
329
  \`VersionControl.versions\` define:
@@ -269,10 +355,11 @@ Configs de versao suportam multiplos tipos:
269
355
  - \`routes-html\`: Caminhos de paginas HTML por idioma
270
356
  - \`routes-video\`: Config de video com \`video.videoType\` (youtube, vimeo, mp4, etc.) e \`video.pathVideo\`
271
357
  - \`routes-audio\`: Config de audio com \`audio.audioType\` (youtube, mp3, etc.) e \`audio.pathAudio\`
358
+ - \`routes-pdf\`: PDF com \`pdf.pathPdf\` por idioma; consulte Documentos PDF.
272
359
  - \`authorization\` (md/html/video): guarda de acesso por chave, papeis e autenticacao externa
273
- - \`menus-header-md\`, \`menus-header-source-viewer\`, \`menus-header-html\`, \`menus-header-video\`, \`menus-header-audio\`: menus por tipo
274
- - \`hierarchyPage\`: ordem dos containers na pagina \`{ md: 0, "source-viewer": 1, html: 2, video: 3, audio: 4 }\`
275
- - \`hierarchyMenu\`: ordem das secoes do menu \`{ md: 0, "source-viewer": 1, html: 2, video: 3, audio: 4 }\`
360
+ - \`menus-header-md\`, \`menus-header-source-viewer\`, \`menus-header-html\`, \`menus-header-video\`, \`menus-header-audio\`, \`menus-header-pdf\`: menus por tipo
361
+ - \`hierarchyPage\`: ordem dos containers na pagina \`{ md: 0, "source-viewer": 1, html: 2, video: 3, audio: 4, pdf: 5 }\`
362
+ - \`hierarchyMenu\`: ordem das secoes do menu \`{ md: 0, "source-viewer": 1, html: 2, video: 3, audio: 4, pdf: 5 }\`
276
363
 
277
364
  Cada rota pode incluir \`title\`, \`description\` (por idioma), \`titleCss\`, \`titlePosition: "center"\`, \`descriptionPosition: "center"\`, \`titleIsVisible\`, \`descriptionIsVisible\`.
278
365
 
@@ -297,37 +384,84 @@ Opcoes por rota em \`routes-md\`, \`routes-html\` e \`routes-video\`:
297
384
 
298
385
  - \`GITPAGEDOCS_REPOSITORY_SEARCH\`: ativa/desativa busca remota localmente
299
386
  - \`GITHUB_ACTIONS\`: ativa comportamento especifico de GitHub Pages
387
+
388
+ ## Comportamento do site e padrões
389
+
390
+ | Chave | Padrão / finalidade |
391
+ | --- | --- |
392
+ | \`ActiveNavigation\` | true; controles comuns de anterior/próximo |
393
+ | \`FocusMode / focusMode\` | Habilitação geral (true) e controles independentes de cópia, download, seção e documento; consulte Modo foco |
394
+ | \`pdf\` | Habilitação geral, prévia, download e nova aba; todos true |
395
+ | \`nestedMenusEnabled\` | true; árvore recursiva, ou destinos em lista plana quando false |
396
+ | \`RouteGuide\` | true; breadcrumbs, com sobrescrita por padrão da versão e rota Markdown |
397
+ | \`accessibility\` | Habilitado por padrão; opções de narração na página Acessibilidade |
398
+ | \`HideThemeSelector\` | false; true oculta o seletor de tema |
399
+ | \`FooterEnabled\` | true; exibe o rodapé |
400
+ | \`FooterLinkName / FooterLinkUrl\` | Texto e destino do link do rodapé |
401
+ | \`FooterDateMode / FooterDateCustom\` | browser, year ou custom; custom usa o texto configurado |
402
+ | \`SiteHeaderName / SiteIconPath\` | Marca do cabeçalho e caminho do ícone do site |
403
+ | \`audioPlayerEnabled\` | true; controles de áudio de fundo |
404
+ | \`audioAutoPlayOnLoad\` | false; autoplay depende da política do navegador |
405
+ | \`audioLoopEnabled / audioSequentialPlayback\` | false; repetir faixa / avançar faixas nativas |
406
+ | \`audioAllowUserChoice\` | Permite escolher faixa quando a playlist tem várias entradas |
407
+ | \`audioTracks\` | Objetos com url, type e title por idioma |
408
+ | \`audioPopoverHideSource / audioPopoverShowMinutes\` | false / true; origem e duração de faixas nativas |
409
+ | \`audioPopoverSourceCustomLabel\` | Texto opcional da origem por idioma |
410
+ | \`mediaExclusivePlayback\` | true; um áudio entre narração, rádio, faixas e vídeo |
411
+ | \`AiChatEnabled / AiChatAutoLockSeconds\` | true / 30; exibe chat e bloqueia por inatividade (0 desativa temporizador) |
412
+ | \`docsAccess\` | enabled e publicKey configuram o bloqueio da documentação; arquivos públicos continuam públicos |
413
+ | \`RouteguideBrandPositionDefault / RouteguideBrandContainerTopDefault\` | center / false; posição do sumário de títulos, separado dos breadcrumbs |
414
+ | \`TocScrollMaxHeightDesktop / TocScrollMaxHeightMobile\` | Limites de rolagem do sumário; comprimentos CSS como min(65vh, 400px) |
415
+
416
+ ## Adicionar versão ou documento
417
+
418
+ Crie a pasta da versão com seu config e registre-a em \`VersionControl.versions\` com \`id\` e \`path\`. Adicione uma entrada \`routes-md\` com ID único e caminhos por idioma; acrescente destinos correspondentes no menu. Use \`routeDefaults\` para valores compartilhados pelas rotas; campos explícitos da rota prevalecem. Consulte Navegação para submenus e sobrescritas de \`RouteGuide\`.
419
+
420
+ Opções visuais são configuração pública. Nunca coloque credenciais de provedor ou chaves privadas no JSON do site. Os exemplos de Rotas autorizadas demonstram controles no cliente, não proteção de arquivos para download no servidor.
421
+
422
+ A entrada \`QuickNavigation\` controla a aparência em ícone/texto do botão Ctrl+K. O atalho de teclado e o painel de busca permanecem disponíveis.
300
423
  `,
301
- deployment: `# Publicacao
424
+ deployment: `# Publicação
425
+
426
+ Escolha o visualizador oficial para um repositório público, publique seu próprio GitHub Pages ou hospede um export estático compilado do runtime.
302
427
 
303
- Git Page Docs roda como app Next.js com dois alvos: servidor local e GitHub Pages.
428
+ ## Visualizador oficial
304
429
 
305
- ## Publicacao local
430
+ Faça commit da pasta \`gitpagedocs/\` gerada no repositório público. Abra \`https://vidigal-code.github.io/git-page-docs/OWNER/REPOSITORY/\` e escolha versão e idioma. O visualizador busca configuração e conteúdo no repositório. Essa URL não torna público um repositório privado.
306
431
 
307
- Use:
432
+ ## Seu site no GitHub Pages
308
433
 
309
- 1. \`npm run build\`
310
- 2. \`npm start\`
434
+ Requisitos: repositório Git, origin GitHub, permissão de push e GitHub CLI autenticado (\`gh auth login\`) quando a CLI configura o Pages.
311
435
 
312
- Isso sobe runtime Node + Next.js usando a pasta local \`gitpagedocs/\`.
436
+ \`\`\`bash
437
+ npx gitpagedocs pages deploy --owner OWNER --repo REPOSITORY
438
+ \`\`\`
313
439
 
314
- ## Publicacao em GitHub Pages
440
+ O fluxo confirma o destino, gera docs e \`.github/workflows/gitpagedocs-pages.yml\`, faz commit e push e solicita GitHub Actions como fonte do Pages. Para mudar apenas a fonte, use \`npx gitpagedocs pages actions\`. Para publicar em subcaminho, passe \`--path docs\`.
315
441
 
316
- Em build de GitHub Actions:
442
+ Acompanhe o GitHub Actions até o deploy terminar; a URL impressa pela CLI pode aparecer antes do fim do build remoto. Sites de projeto normalmente usam \`https://OWNER.github.io/REPOSITORY/\`; sites de usuário/organização usam a raiz do repositório \`OWNER.github.io\`.
317
443
 
318
- - \`GITHUB_ACTIONS=true\`
319
- - comportamento de export estatico e habilitado pela configuracao
320
- - pagina inicial de busca de repositorio fica ativa
444
+ ## Contrato do build
321
445
 
322
- ## Fluxo de publish do pacote
446
+ O workflow instala dependências do workspace com pnpm fixado, compila o visualizador e envia o artefato estático com as actions oficiais do Pages. O job de deploy exige \`pages: write\`, \`id-token: write\` e o ambiente \`github-pages\`.
323
447
 
324
- Para publicar no npm:
448
+ - \`GITHUB_ACTIONS=true\` ativa export estático do Next.js.
449
+ - \`GITHUB_REPOSITORY=OWNER/REPOSITORY\` determina a base do repositório.
450
+ - \`GITPAGEDOCS_REPOSITORY_SEARCH=true\` ativa o build da busca inicial.
451
+ - \`GITPAGEDOCS_BASE_PATH\` sobrescreve explicitamente a base; \`GITPAGEDOCS_PATH\` define o subcaminho dos docs.
452
+ - \`GITPAGEDOCS_DIST_DIR\` separa saídas de build/dev quando há dois servidores locais.
325
453
 
326
- - atualize versao no \`package.json\`
327
- - execute \`npm publish --access public\`
328
- - valide autenticacao com \`npm whoami\`
454
+ \`pnpm build\` sem o ambiente do Pages produz um build de produção Next.js; sozinho não valida export estático. Preserve \`.nojekyll\` ao hospedar o export no Pages.
329
455
 
330
- Se \`build:prebuilt\` for pulado no Windows, use CI para gerar artefatos prebuilt.
456
+ ## Export independente
457
+
458
+ Em um checkout do runtime com dependências instaladas, \`node cli/index.mjs --home --output gitpagedocshome --no-interactive\` compila \`frontend/\` e empacota uma distribuição estática. \`--search true\` ativa a busca inicial de repositórios. A saída inclui arquivos estáticos, README, Dockerfile e exemplo de ambiente; a pasta de destino é recriada. Um servidor estático serve os arquivos; alterar configuração de ambiente usada no build exige nova compilação.
459
+
460
+ ## Releases npm para mantenedores
461
+
462
+ O monorepo publica \`@gitpagedocs/tools\`, \`@gitpagedocs/mcp\` e \`@gitpagedocs/cli\`; raiz e frontend são privados. O \`npm-publish.yml\` atual roda em pushes para \`main\` e ignora uma versão da CLI já publicada. Usa o secret \`NPM_TOKEN\` do repositório e publica workspaces na ordem de dependência. Criar somente uma release no GitHub não é seu gatilho.
463
+
464
+ Sincronize versões e dependências internas, regenere docs/baselines, execute typecheck, lint, testes, smoke, build e Playwright e revise antes do push. Confirme as três versões no npm e o resultado do Pages. A CLI de configuração ignora \`prebuilt/\`; essa pasta não é exigida pelo workflow de publicação.
331
465
  `,
332
466
  architecture: `# Arquitetura
333
467
 
@@ -472,6 +606,411 @@ Cada template normalmente contem:
472
606
  - mantenha contraste acessivel
473
607
  - padronize escala de espaco e borda
474
608
  - ofereca variantes dark e light quando possivel
609
+
610
+ ## Escolher e personalizar
611
+
612
+ Escolha um tema pelo seletor ou configure \`site.ThemeDefault\` com seu ID exato. \`ThemeModeDefault\` define o modo inicial claro/escuro. \`HideThemeSelector\` esconde o seletor; o tema selecionado continua aplicado.
613
+
614
+ No seu repositório, execute a CLI com \`--layoutconfig\`, edite o template gerado e mantenha o ID coerente com \`layoutsConfig.json\`. O conteúdo da rota e \`site.icons\` são independentes do catálogo de temas. Use \`currentColor\` para ícones que herdam a cor do texto ou configure cores claras/escuras com contraste suficiente.
615
+
616
+ Ao contribuir no Git Page Docs, a fonte autoral é \`gitpagelayouts/v2/base.json\` com \`gitpagelayouts/v2/layouts/<id>.json\`. Execute \`pnpm layouts:sync\` para gerar templates e documentação. Edições diretas nos templates gerados podem ser substituídas pela sincronização.
617
+ `,
618
+ mcp: `# Servidor MCP
619
+
620
+ O servidor Model Context Protocol expõe 20 tools e 7 resources por **stdio**. Ele inicia como processo filho do cliente MCP. Não abre porta HTTP nem executa um daemon em segundo plano.
621
+
622
+ ## Instalar e conectar
623
+
624
+ Use Node.js 20+. Instale a CLI no projeto com \`npm install --save-dev @gitpagedocs/cli\`; ela inclui o servidor e o runtime TypeScript. A instalação global também permite \`gitpagedocs mcp start\`. Para execução avulsa, use \`npx --yes @gitpagedocs/cli mcp start\`.
625
+
626
+ No VS Code, crie \`.vscode/mcp.json\` com a configuração abaixo. A pasta de trabalho do processo é a raiz do projeto; o comando MCP não possui flags \`--root\` ou \`--cwd\`.
627
+
628
+ \`\`\`json
629
+ {
630
+ "servers": {
631
+ "gitpagedocs": {
632
+ "type": "stdio",
633
+ "command": "node",
634
+ "args": [
635
+ "\${workspaceFolder}/node_modules/@gitpagedocs/cli/index.mjs",
636
+ "mcp",
637
+ "start"
638
+ ],
639
+ "cwd": "\${workspaceFolder}"
640
+ }
641
+ }
642
+ }
643
+ \`\`\`
644
+
645
+ Abra os controles de servidor MCP do cliente, inicie GitPageDocs e liste tools/resources. Teste \`list_files\` com \`{"path":".","recursive":false}\` e leia \`project://readme\`. Essas operações não precisam de chave de provedor. Um terminal iniciado com \`mcp start\` aguarda JSON-RPC; texto comum no stdin não é um comando de chat. Em um checkout do código, a entrada direta é \`node --import tsx mcp/src/bin.ts\`, não \`index.ts\`.
646
+
647
+ ## Configurar um provedor
648
+
649
+ As chamadas de provedor leem credenciais do ambiente do processo MCP. O MCP não carrega \`.env\` nem o cofre criptografado da CLI automaticamente. Use o recurso de entrada protegida/segredos do cliente para injetar variáveis; nunca grave chaves reais em configuração versionada. Reinicie o processo MCP após alterar seu ambiente.
650
+
651
+ Selecione o provedor com \`configure_ai_provider\` ou pelo arquivo \`.gitpagedocs-mcp.json\` na raiz do projeto:
652
+
653
+ \`\`\`json
654
+ {
655
+ "provider": "ollama",
656
+ "model": "llama3"
657
+ }
658
+ \`\`\`
659
+
660
+ | Provider | Environment |
661
+ | --- | --- |
662
+ | \`openai\` | \`OPENAI_API_KEY\` |
663
+ | \`anthropic\` | \`ANTHROPIC_API_KEY / CLAUDE_API_KEY\` |
664
+ | \`gemini\` | \`GEMINI_API_KEY / GOOGLE_API_KEY\` |
665
+ | \`openrouter\` | \`OPENROUTER_API_KEY\` |
666
+ | \`ollama\` | \`OLLAMA_BASE_URL\` |
667
+ | \`azure-openai\` | \`AZURE_OPENAI_API_KEY + AZURE_OPENAI_BASE_URL\` |
668
+ | \`mistral\` | \`MISTRAL_API_KEY\` |
669
+ | \`deepseek\` | \`DEEPSEEK_API_KEY\` |
670
+ | \`cohere\` | \`COHERE_API_KEY\` |
671
+ | \`groq\` | \`GROQ_API_KEY\` |
672
+ | \`xai\` | \`XAI_API_KEY\` |
673
+ | \`together\` | \`TOGETHER_API_KEY\` |
674
+ | \`fireworks\` | \`FIREWORKS_API_KEY\` |
675
+ | \`perplexity\` | \`PERPLEXITY_API_KEY\` |
676
+
677
+ Sem seleção válida, o provedor padrão é OpenAI. Ollama não exige chave de API; o serviço local e o modelo escolhido precisam estar disponíveis. \`OLLAMA_BASE_URL\` é opcional. A URL base do Azure é a URL completa da operação de chat, incluindo deployment e versão da API quando exigidos. A lista de modelos é um catálogo distribuído, não uma verificação de disponibilidade em tempo real.
678
+
679
+ ## Referência de tools
680
+
681
+ \`?\` indica argumento opcional. Caminhos e conteúdo são strings; \`recursive\` é booleano. Os identificadores de provedor vêm do catálogo. Execute as tools pela interface de ferramentas do cliente MCP.
682
+
683
+ | Tool | Argumentos | Comportamento |
684
+ | --- | --- | --- |
685
+ | \`list_files\` | \`path?, recursive?\` | Lista arquivos (padrão: pasta atual, sem recursão) |
686
+ | \`read_file\` | \`path\` | Lê texto UTF-8 |
687
+ | \`write_file\` | \`path, content\` | Grava o arquivo inteiro; cria pastas necessárias |
688
+ | \`search_project\` | \`query, extension?\` | Busca por trecho sem distinguir maiúsculas |
689
+ | \`list_ai_providers\` | \`—\` | Consulta o catálogo de provedores |
690
+ | \`list_ai_models\` | \`provider?\` | Consulta o catálogo local de modelos |
691
+ | \`configure_ai_provider\` | \`provider, model?\` | Salva .gitpagedocs-mcp.json |
692
+ | \`ask_ai\` | \`prompt, provider?, model?, system?\` | Retorna uma resposta, sem histórico de conversa |
693
+ | \`generate_documentation\` | \`path, provider?\` | Documenta um arquivo fonte |
694
+ | \`generate_api_docs\` | \`path, provider?\` | Descreve a API de um arquivo |
695
+ | \`generate_database_docs\` | \`path, provider?\` | Descreve modelos de dados de um arquivo |
696
+ | \`analyze_source_code\` | \`path, provider?\` | Analisa um arquivo fonte |
697
+ | \`generate_readme\` | \`provider?\` | Usa a árvore e package.json |
698
+ | \`generate_architecture_docs\` | \`provider?\` | Usa a árvore do repositório |
699
+ | \`analyze_repository\` | \`provider?\` | Analisa a árvore do repositório |
700
+ | \`analyze_project\` | \`provider?\` | Analisa a árvore e package.json |
701
+ | \`generate_changelog\` | \`provider?\` | Usa até 80 commits; usa a árvore se indisponíveis |
702
+ | \`generate_release_notes\` | \`provider?\` | Usa o mesmo contexto do changelog |
703
+ | \`validate_docs\` | \`provider?\` | Pede ao provedor uma revisão do Markdown coletado |
704
+ | \`update_documentation\` | \`path, instructions?, provider?\` | Gera e grava uma região gerenciada |
705
+
706
+ \`generate_*\`, \`analyze_*\`, \`ask_ai\` e \`validate_docs\` retornam texto; não salvam automaticamente. \`validate_docs\` é uma revisão feita pelo provedor, não um verificador determinístico de links. Somente \`write_file\`, \`configure_ai_provider\` e \`update_documentation\` gravam arquivos. \`update_documentation\` preserva texto fora de \`<!-- gitpagedocs:start -->\` / \`<!-- gitpagedocs:end -->\`; acrescenta uma região quando o par válido não existe. O servidor não exibe confirmação própria; configure permissões no cliente MCP.
707
+
708
+ ## Referência de resources
709
+
710
+ | URI | Conteúdo |
711
+ | --- | --- |
712
+ | \`project://structure\` | Árvore do repositório |
713
+ | \`project://docs\` | Documentos Markdown coletados |
714
+ | \`project://config\` | Configuração resolvida e sourcePath |
715
+ | \`project://repository\` | Conteúdo de package.json |
716
+ | \`project://readme\` | README.md |
717
+ | \`project://ai/providers\` | Catálogo de provedores |
718
+ | \`project://ai/models\` | Catálogo de modelos por provedor |
719
+
720
+ ## Exemplo de uso
721
+
722
+ 1. Leia \`project://structure\` e \`project://readme\`.
723
+ 2. Execute \`list_ai_providers\` e \`list_ai_models\` para escolher provedor/modelo.
724
+ 3. Execute \`generate_api_docs\` com \`{"path":"src/index.ts"}\` e revise o texto retornado.
725
+ 4. Salve o texto aprovado com \`write_file\`, ou use \`update_documentation\` com \`{"path":"docs/api.md","instructions":"Documente a API pública em português."}\` para uma região gerenciada.
726
+
727
+ A etapa de geração envia o conteúdo selecionado do projeto ao provedor configurado.
728
+
729
+ ## Limites e diagnóstico
730
+
731
+ - Leitura de arquivos: até 512.000 bytes. Listagem: até 2.000 entradas; árvores coletadas do projeto: 400 entradas.
732
+ - Busca: até 5.000 entradas, 200 resultados e 240 caracteres por linha encontrada.
733
+ - Coleta de documentação: primeiros 40 arquivos Markdown entre até 2.000 entradas; arquivos acima de 40.000 bytes são ignorados. O contexto do provedor é limitado a 24.000 caracteres.
734
+ - A listagem ignora pastas de dependências/build como \`node_modules\`, \`.git\`, \`.next\`, \`out\`, \`dist\`, \`prebuilt\`, \`.turbo\` e \`coverage\`. Não interpreta \`.gitignore\`; arquivos como \`.env\` não são excluídos automaticamente. Execute somente em projeto confiável e selecione o conteúdo que será exposto.
735
+ - A verificação de caminhos é lexical; o processo não é um sandbox do sistema operacional nem garante isolamento de symlinks/junctions. Ler \`project://config\` pode importar configuração JavaScript/TypeScript.
736
+ - Falhas de tools incluem \`isError: true\`. Resources ausentes retornam \`Unavailable: ...\`. Consulte stderr no cliente para falhas de inicialização; stdout é reservado para JSON-RPC.
737
+ - Se as tools funcionam mas a geração falha, confira seleção do provedor, credenciais de ambiente, modelo e conectividade.
738
+ `,
739
+ cli: `# Referência da CLI
740
+
741
+ ## Comandos da CLI
742
+
743
+ | Comando | Descricao |
744
+ |---------|------------|
745
+ | \`npx @gitpagedocs/cli\` | Gera config e docs em \`gitpagedocs/\` |
746
+ | \`npx @gitpagedocs/cli --layoutconfig\` | Tambem gera layouts/templates locais em \`gitpagelayouts/\` |
747
+ | \`npx @gitpagedocs/cli --home\` | Distribuicao standalone (\`gitpagedocshome/\`) |
748
+ | \`npx @gitpagedocs/cli --push --owner X --repo Y\` | Configura workflow, commit, push |
749
+ | \`npx @gitpagedocs/cli --interactive\` / \`-i\` | Modo interativo com prompts (padrao em um terminal) |
750
+ | \`npx @gitpagedocs/cli --no-interactive\` / \`--yes\` / \`-y\` | Nunca pergunta; usa flags e padroes |
751
+ | \`gitpagedocs ai\` | Gerador interativo de documentacao com IA |
752
+ | \`gitpagedocs chat [pergunta]\` | Chat de IA com streaming no terminal (REPL em TTY; resposta unica com pergunta ou stdin) |
753
+ | \`gitpagedocs provider [id]\` / \`models [provider]\` | Lista provedores de IA / modelos do catalogo |
754
+ | \`gitpagedocs document[:repo\\|:file\\|:folder]\` | Gera documentacao com IA |
755
+ | \`gitpagedocs deploy\` / \`pages [actions\\|deploy]\` | Configura GitHub Pages via Actions + push |
756
+ | \`gitpagedocs docs\` | Atualiza as regioes gerenciadas de README/CONTRIBUTING/SECURITY |
757
+ | \`gitpagedocs password\` | Define a senha de acesso a documentacao (chave publica em \`site.docsAccess\`) |
758
+ | \`gitpagedocs config\` / \`config clear\` | Mostra a config resolvida / apaga a config salva e o cofre de chaves |
759
+ | \`gitpagedocs doctor\` / \`version\` / \`update\` | Diagnostico / versao / verificacao de atualizacao no registro |
760
+ | \`gitpagedocs mcp start\` | Inicia o servidor MCP via stdio |
761
+
762
+ Instale globalmente com \`npm install -g @gitpagedocs/cli\` ou rode sem instalar com \`npx @gitpagedocs/cli\`.
763
+
764
+ ## Opcoes da CLI
765
+
766
+ | Opcao | Descricao |
767
+ |-------|-----------|
768
+ | \`--owner <user>\` | Owner do GitHub |
769
+ | \`--repo <repo>\` | Repositorio GitHub |
770
+ | \`--path <subpath>\` | Subcaminho dos docs (ex: \`docs\`); sem ele, base path = nome do repo para CSS/JS em project sites |
771
+ | \`--output <dir>\` | Diretorio de saida (padrao: \`gitpagedocs\`) |
772
+ | \`--search <true-or-false>\` | Habilita/desabilita busca de repositorio (\`--home\`) |
773
+ | \`--layoutconfig\` | Gera layouts locais em \`gitpagelayouts/\` |
774
+ | \`--layouts-dir <dir>\` | Pasta dos layouts locais (padrao: \`gitpagelayouts\`) |
775
+ | \`--push\` | Cria workflow, commit de artefatos, push |
776
+ | \`--pages-actions\` | Apenas muda a fonte do GitHub Pages para GitHub Actions (igual a \`pages actions\`) |
777
+ | \`--home\` | Gera \`gitpagedocshome/\` (estatico + .env + Dockerfile) |
778
+
779
+ ## Saida gerada
780
+
781
+ - \`gitpagedocs/config.json\` – config raiz
782
+ - \`gitpagedocs/icon.svg\` – icone padrao
783
+ - \`gitpagedocs/docs/versions/<ver>/config.json\` – rotas por versao
784
+ - \`gitpagedocs/docs/versions/<ver>/{en,pt,es}/*.md\` – docs em markdown
785
+ - \`gitpagelayouts/\` – apenas com \`--layoutconfig\` (pasta configuravel com \`--layouts-dir\`)
786
+
787
+ ## Exemplos e limites dos comandos
788
+
789
+ \`\`\`bash
790
+ npx gitpagedocs --no-interactive --owner octocat --repo handbook
791
+ npx gitpagedocs --layoutconfig --layouts-dir assets/layouts --no-interactive
792
+ npx gitpagedocs chat "Explique este projeto" --provider ollama --model llama3
793
+ npx gitpagedocs pages deploy --owner octocat --repo handbook --path docs
794
+ npx gitpagedocs mcp start
795
+ \`\`\`
796
+
797
+ - \`init\` é um alias da geração. \`providers\` equivale a \`provider\`; \`--version\` e \`-v\` equivalem a \`version\`.
798
+ - \`document\`, \`document:repo\`, \`document:file\`, \`document:folder\` e \`--ai\` selecionam o fluxo interativo de documentação. Escolha diretórios nos prompts; esses aliases não implementam uma API separada de arquivo/pasta por argumento posicional.
799
+ - \`chat\` aceita \`--provider <id>\`, \`--model <id>\` e \`--system <prompt>\`. Com pergunta ou stdin recebe resposta única; um terminal interativo sem pergunta inicia uma conversa.
800
+ - \`--build\`, \`--serve\` e \`--full\` são flags de compatibilidade: o scaffold comum continua apenas configuração e elas não iniciam um servidor local.
801
+ - \`--home\` compila \`frontend/\` a partir de um checkout do runtime e grava o export estático com arquivos auxiliares. A pasta de saída é recriada quando diferente de \`.\`; mantenha sua documentação fonte fora dela. Instalar apenas a CLI não fornece \`frontend/\`.
802
+ - \`pages actions\` apenas configura a fonte do Pages; \`pages deploy\` e \`--push\` geram, fazem commit e push. Uma URL impressa não significa que o build remoto terminou: acompanhe o GitHub Actions.
803
+ - \`update\` consulta o npm e imprime um comando de instalação; não atualiza a CLI silenciosamente.
804
+
805
+ ## Configuração e credenciais
806
+
807
+ As opções visuais ficam em \`gitpagedocs/config.json\`. O gerador interativo/chat salva \`.gitpagedocsconfig\` e o cofre criptografado \`.gitpagedocsvault\` na pasta de configuração do usuário: \`%APPDATA%/gitpagedocs\` no Windows, \`~/Library/Application Support/gitpagedocs\` no macOS e a pasta XDG no Linux. \`config clear\` remove essas configurações e o cofre. MCP usa \`.gitpagedocs-mcp.json\` na raiz do projeto e o ambiente do processo; consulte a página MCP.
808
+
809
+ \`gitpagedocs docs\` atualiza somente regiões delimitadas por marcadores em README.md, CONTRIBUTING.md e SECURITY.md, preservando o texto ao redor. \`password\` configura o par de chaves de acesso à documentação; controles de apresentação no cliente não tornam confidenciais arquivos de um repositório público.
810
+ `,
811
+ navigation: `# Navegação e submenus
812
+
813
+ Rotas definem o conteúdo; menus definem como o leitor o encontra. Configure-os em \`gitpagedocs/docs/versions/<version>/config.json\`. Opções visuais globais ficam em \`gitpagedocs/config.json\`.
814
+
815
+ \`\`\`json
816
+ {
817
+ "site": {
818
+ "nestedMenusEnabled": true,
819
+ "RouteGuide": true
820
+ }
821
+ }
822
+ \`\`\`
823
+
824
+ ## Montar a árvore de menus
825
+
826
+ Cada entrada de \`menus-header-md\` tem \`id\` e objetos \`pt\`, \`en\`, \`es\` com \`title\` e \`path-click\` opcional. Adicione \`submenus\` com novas entradas para aninhar a árvore. O objeto de um idioma também aceita \`submenus\` localizados com título/caminho. Use uma forma de maneira consistente para não listar o mesmo filho duas vezes.
827
+
828
+ Grupos sem \`path-click\` organizam os filhos. Para um destino Markdown, use seu caminho localizado real de \`routes-md[].path\`. O alias \`page:<id>\` é registrado por rotas source-viewer, vídeo, áudio e PDF; não o use em uma página somente Markdown. O exemplo usa a versão \`0.0.8\`: troque esse trecho pela versão editada e crie os três arquivos chapter.
829
+
830
+ \`\`\`json
831
+ {
832
+ "routeDefaults": {
833
+ "RouteGuide": false
834
+ },
835
+ "routes-md": [
836
+ {
837
+ "id": 101,
838
+ "RouteGuide": true,
839
+ "path": {
840
+ "pt": "gitpagedocs/docs/versions/0.0.8/pt/chapter.md",
841
+ "en": "gitpagedocs/docs/versions/0.0.8/en/chapter.md",
842
+ "es": "gitpagedocs/docs/versions/0.0.8/es/chapter.md"
843
+ }
844
+ }
845
+ ],
846
+ "menus-header-md": [
847
+ {
848
+ "id": 900,
849
+ "pt": {
850
+ "title": "Guia"
851
+ },
852
+ "en": {
853
+ "title": "Guide"
854
+ },
855
+ "es": {
856
+ "title": "Guía"
857
+ },
858
+ "submenus": [
859
+ {
860
+ "id": 901,
861
+ "pt": {
862
+ "title": "Capítulos"
863
+ },
864
+ "en": {
865
+ "title": "Chapters"
866
+ },
867
+ "es": {
868
+ "title": "Capítulos"
869
+ },
870
+ "submenus": [
871
+ {
872
+ "id": 101,
873
+ "pt": {
874
+ "title": "Primeiro capítulo",
875
+ "path-click": "gitpagedocs/docs/versions/0.0.8/pt/chapter.md"
876
+ },
877
+ "en": {
878
+ "title": "First chapter",
879
+ "path-click": "gitpagedocs/docs/versions/0.0.8/en/chapter.md"
880
+ },
881
+ "es": {
882
+ "title": "Primer capítulo",
883
+ "path-click": "gitpagedocs/docs/versions/0.0.8/es/chapter.md"
884
+ }
885
+ }
886
+ ]
887
+ }
888
+ ]
889
+ }
890
+ ]
891
+ }
892
+ \`\`\`
893
+
894
+ ## Comportamento do aninhamento
895
+
896
+ \`site.nestedMenusEnabled: true\` exibe menus recursivos expansíveis. Você pode acrescentar \`submenus\` em qualquer nó: não há limite fixo de profundidade na aplicação. A configuração deve ser finita e adequada à memória do navegador e à usabilidade. Com \`false\`, os destinos aparecem em uma lista plana; as páginas aninhadas não são removidas.
897
+
898
+ A árvore atende à navegação lateral, aos rótulos de busca, à expansão dos pais e à trilha de navegação. Mantenha IDs estáveis e sem ambiguidade; destinos protegidos seguem as regras de autorização da página. A mesma estrutura vale para \`menus-header-source-viewer\`, \`menus-header-html\`, \`menus-header-video\`, \`menus-header-audio\` e \`menus-header-pdf\`. \`hierarchyMenu\` ordena as seções por tipo; \`hierarchyPage\` ordena os containers que compartilham o ID da página.
899
+
900
+ ## Trilha de navegação: RouteGuide
901
+
902
+ \`RouteGuide\` controla os breadcrumbs. A prioridade é \`routes-md[].RouteGuide\` da página, depois \`routeDefaults.RouteGuide\` da versão, depois \`site.RouteGuide\`, usando \`true\` como padrão final. O exemplo desliga a trilha na versão e a liga no capítulo 101. Arquivos existentes da versão \`0.0.8\` aceitam os mesmos campos.
903
+
904
+ \`RouteguideBrand\` e \`RouteguideBrandPosition\` são configurações separadas do sumário de títulos do documento; não controlam os breadcrumbs.
905
+
906
+ ## URLs e anterior/próximo
907
+
908
+ URLs versionadas usam \`/v/<version>/\`; \`?lang=pt\` escolhe o idioma e \`?id=101\` escolhe a página. \`?name=chapter\` seleciona o slug do documento. Mantenha \`VersionControl.versions[].path\` apontando para o config da versão correspondente. \`site.ActiveNavigation\` ativa anterior/próximo comum; a navegação entre documentos no modo foco possui opção própria. Consulte Modo foco para os controles de seção e documento.
909
+
910
+ Teste um menu novo pela lateral, por URL direta e em cada idioma habilitado; confirme que o destino existe e é permitido para o leitor atual.
911
+ `,
912
+ focusMode: `# Modo foco
913
+
914
+ O modo foco abre o documento Markdown atual em um diálogo de leitura. Ative-o com \`site.FocusMode\`; o controle aparece apenas para uma página Markdown real. \`site.icons.FocusMode\` muda a aparência em ícone/texto e não habilita ou desabilita o recurso.
915
+
916
+ ## Configurar os controles
917
+
918
+ Mescle este fragmento em \`gitpagedocs/config.json\`:
919
+
920
+ \`\`\`json
921
+ {
922
+ "site": {
923
+ "FocusMode": true,
924
+ "focusMode": {
925
+ "copyEnabled": true,
926
+ "downloadEnabled": true,
927
+ "sectionNavigationEnabled": true,
928
+ "documentNavigationEnabled": true
929
+ }
930
+ }
931
+ }
932
+ \`\`\`
933
+
934
+ Cada opção tem padrão \`true\`; \`false\` oculta seu controle correspondente. Com \`sectionNavigationEnabled: false\`, o modo foco exibe o documento inteiro sem paginação por seções. Configurações existentes sem o novo objeto \`focusMode\` mantêm os controles habilitados.
935
+
936
+ ## Seções e documentos
937
+
938
+ - Os controles anterior/próximo de seta simples mudam de seção no mesmo documento.
939
+ - Os controles anterior/próximo de seta dupla mudam de documento Markdown na ordem dos menus, incluindo submenus.
940
+ - Documentos sem tradução no idioma ativo, destinos sem Markdown e páginas sem permissão são ignorados.
941
+ - Trocar de documento mantém o diálogo aberto e volta à primeira seção. Contadores de seção/documento mostram a posição atual.
942
+ - \`site.ActiveNavigation\` controla a navegação comum da página; não desabilita a navegação de documentos no modo foco.
943
+
944
+ ## Copiar e baixar
945
+
946
+ Copiar e baixar usam o **Markdown original inteiro no idioma selecionado**, incluindo seções que não estão visíveis no momento. Não exportam o HTML renderizado nem apenas a seção atual.
947
+
948
+ O download conserva o nome-base Markdown do \`path\` localizado da rota; quando indisponível, o nome do arquivo é \`document.md\`. A área de transferência segue as permissões e regras de contexto seguro do navegador. Se a cópia falhar, use o download e confira o erro exibido.
949
+
950
+ ## Teclado e leitura
951
+
952
+ O diálogo possui nome acessível, gerenciamento de foco do teclado e controle de fechar. Use Tab para percorrer controles e Escape para fechar. Controles só com ícone continuam com seus nomes traduzidos acessíveis. Fechar o diálogo retorna à documentação.
953
+
954
+ A narração é configurada separadamente em Acessibilidade. Trocar documento ou idioma cancela a narração anterior, evitando continuar a leitura de conteúdo antigo.
955
+ `,
956
+ accessibility: `# Acessibilidade e narração
957
+
958
+ Os controles de acessibilidade incluem narração nativa do navegador para o documento Markdown atual. A narração usa a Web Speech API (\`speechSynthesis\`); não exige chave de API nem serviço externo de voz do GitPageDocs.
959
+
960
+ ## Configuração
961
+
962
+ Mescle estas opções em \`gitpagedocs/config.json\`:
963
+
964
+ \`\`\`json
965
+ {
966
+ "site": {
967
+ "accessibility": {
968
+ "enabled": true,
969
+ "narration": {
970
+ "enabled": true,
971
+ "defaultRate": 1,
972
+ "defaultVolume": 1
973
+ }
974
+ },
975
+ "mediaExclusivePlayback": true
976
+ }
977
+ }
978
+ \`\`\`
979
+
980
+ - \`site.accessibility.enabled\`: habilita a interface de acessibilidade.
981
+ - \`site.accessibility.narration.enabled\`: habilita a narração do documento.
982
+ - \`defaultRate\`: velocidade inicial de \`0.5\` a \`2\`, em passos de \`0.25\`; o padrão é \`1\`.
983
+ - \`defaultVolume\`: volume inicial de \`0\` (silencioso) a \`1\` (máximo), em passos de \`0.1\`; o padrão é \`1\`.
984
+ - Todos os controles de habilitação têm padrão \`true\`; opções ausentes usam os padrões distribuídos.
985
+
986
+ ## Ler um documento em voz alta
987
+
988
+ 1. Abra uma página Markdown e os controles de acessibilidade/narração.
989
+ 2. Escolha voz e idioma entre os disponibilizados pelo navegador; ajuste velocidade e volume.
990
+ 3. Inicie a leitura. Pause temporariamente, continue a fala pausada ou encerre a sessão.
991
+ 4. Para alterar opções de leitura de forma previsível, pare, ajuste os controles e inicie novamente.
992
+
993
+ A narração começa somente após sua ação; não há reprodução automática. A seleção automática de voz acompanha o idioma do documento; escolher uma voz explicitamente utiliza o idioma dessa voz. A narração não traduz o documento.
994
+
995
+ A fala usa texto legível extraído do Markdown renderizado. Scripts, estilos, conteúdo SVG e elementos ocultos para tecnologias assistivas são excluídos. Documentos longos são lidos por inteiro em blocos sucessivos. Trocar documento ou idioma, desabilitar a narração ou sair da página cancela a fala anterior.
996
+
997
+ A visualização comum e o modo foco compartilham preferências de voz, velocidade e volume enquanto a página permanece montada. As preferências não são salvas entre recarregamentos. Valores não numéricos de velocidade ou volume usam \`1\`; valores numéricos fora das faixas suportadas são limitados ao extremo mais próximo.
998
+
999
+ ## Um áudio por vez
1000
+
1001
+ Com \`site.mediaExclusivePlayback: true\` (padrão), iniciar ou continuar a narração pausa rádio, faixas de áudio e vídeos de rota. Iniciar essas mídias encerra a narração. Vídeos sem som ficam fora dessa regra. Use \`false\` quando a reprodução simultânea for intencional.
1002
+
1003
+ Essa configuração é compartilhada com a reprodução de mídia existente; não há uma segunda flag de exclusividade para narração. A página continua legível quando a narração está desabilitada.
1004
+
1005
+ ## Disponibilidade de navegador e vozes
1006
+
1007
+ O suporte a fala e as vozes dependem do navegador, do sistema operacional e das vozes instaladas ou fornecidas remotamente. A lista pode chegar depois de a página carregar. Navegadores e dispositivos diferentes podem oferecer idiomas diferentes.
1008
+
1009
+ Ausência de suporte e erros de reprodução são informados na interface. Verifique se há uma voz disponível, se o áudio do sistema está ativo e se houve interação do usuário com a página. Lista de vozes vazia não significa falha ao carregar o documento.
1010
+
1011
+ Não presuma que toda voz funciona offline: as vozes podem ser locais ou remotas. O recurso fala texto; não grava o microfone. A narração complementa a navegação por teclado e leitores de tela, sem substituí-los.
1012
+
1013
+ Consulte a [referência da Web Speech API](https://developer.mozilla.org/en-US/docs/Web/API/SpeechSynthesis) para o comportamento do navegador.
475
1014
  `,
476
1015
  faq: `# FAQ
477
1016
 
@@ -502,5 +1041,25 @@ Verifique:
502
1041
  ## Por que GitHub Pages pode se comportar diferente do local?
503
1042
 
504
1043
  Porque o build de GitHub Pages habilita pagina inicial de busca e comportamento especifico de exportacao.
1044
+
1045
+ ## Por que o ícone ainda mostra texto?
1046
+
1047
+ Defina \`site.icons.<Controle>.reactIcon\` como booleano \`true\`, com o nome exato exportado por React Icons em \`tag\`. Os controles incluem LanguageSelector, ThemeSelector, FocusMode e QuickNavigation. Campos planos \`Icon*ReactIcones\` prevalecem se os dois formatos existirem. Confira se o próprio recurso está desabilitado por opções como \`HideThemeSelector\` ou \`FocusMode\`.
1048
+
1049
+ ## Por que filhos de menus ou breadcrumbs aparecem diferentes?
1050
+
1051
+ \`nestedMenusEnabled: false\` achata os destinos intencionalmente. Confira \`submenus\`, objetos de idioma e \`path-click\`; confirme que as páginas existem e são acessíveis. Breadcrumbs usam \`RouteGuide\`, com prioridade rota > versão > site. \`RouteguideBrand\` controla o sumário de títulos.
1052
+
1053
+ ## Por que a narração fica muda ou é interrompida?
1054
+
1055
+ Confira suporte do navegador, voz disponível, idioma, volume e saída de áudio. Vozes podem carregar depois ou exigir serviço remoto. Com \`mediaExclusivePlayback: true\`, outra fonte de áudio/vídeo encerra a narração por definição. Trocar de documento cancela a fala antiga. Consulte Acessibilidade.
1056
+
1057
+ ## Por que o MCP fica aguardando ou uma tool falha?
1058
+
1059
+ \`mcp start\` aguarda um cliente MCP por stdio; não é um prompt de chat de terminal. Confira o cwd e use a entrada da CLI publicada ou \`mcp/src/bin.ts\`. Tools de arquivos/catálogo não precisam de provedor; geração exige credenciais no ambiente do processo MCP. O cofre da CLI e \`.env\` não são carregados automaticamente; inspecione \`isError\` e o stderr do cliente.
1060
+
1061
+ ## Por que a regeneração mudou minhas páginas?
1062
+
1063
+ O scaffold regrava rotas, configs e documentação gerada. Revise o Git e mantenha conteúdo específico nas fontes escolhidas. Neste repositório, edite \`cli/content/docs-{en,pt,es}.mjs\` e metadados de rotas antes de regenerar; não use as cópias geradas como única fonte.
505
1064
  `,
506
1065
  };