@gitpagedocs/cli 0.0.9 → 0.0.11

package/content/overviews-pt.mjs

@@ -0,0 +1,115 @@
+export const overviewsPt = {
+  guides: `# Guias
+
+Escolha um caminho pela documentação conforme o que precisa realizar. Esta página também é o destino do item Guias no menu: clicar no título abre o documento; a seta separada expande ou recolhe os submenus.
+
+## Escolha o próximo passo
+
+- **Configure seu site** conecta opções globais, rotas de versão, temas e navegação. Comece aqui para adaptar o scaffold ao seu repositório.
+- **Leia e explore** explica modo foco, narração do navegador, documentos PDF e HTML interativo.
+- **Automatize e integre** reúne comandos da CLI, servidor MCP e autorização de rotas.
+
+## Navegue pela seção
+
+Um item pai pode ter \`path-click\` traduzido e \`submenus\` ao mesmo tempo. Os filhos mantêm seus próprios destinos. O breadcrumb segue a mesma hierarquia: um ancestral com documento disponível pode ser aberto, e a página atual indica sua posição. Por exemplo, Guias → Configure seu site → Configuração permite voltar a qualquer introdução sem perder a estrutura do menu.
+`,
+  configureYourSite: `# Configure seu site
+
+Separe a apresentação global do conteúdo de cada versão da documentação. O arquivo raiz \`gitpagedocs/config.json\` seleciona idiomas, temas e controles de leitura. A configuração da versão define rotas, arquivos por idioma e a árvore de menus.
+
+## Configure em uma ordem prática
+
+1. Leia **Configuração** para localizar a opção desejada e seu padrão.
+2. Use **Receitas de configuração** para exemplos JSON completos e uma estrutura multilíngue inicial.
+3. Escolha **Temas e layouts** para tokens visuais e alterações de templates.
+4. Leia **Navegação e submenus** para conectar rotas, documentos dos pais, submenus e breadcrumbs.
+
+## Confira o resultado
+
+Mantenha um arquivo existente para cada idioma habilitado e destino do menu. Apenas um título não cria um documento. Dê ao pai seu próprio caminho Markdown quando precisar de uma introdução e preserve os filhos em \`submenus\`. Valide um idioma primeiro; depois confira os demais, o menu plano e um link direto para uma página aninhada. Preserve as configurações específicas do repositório ao gerar exemplos novamente.
+`,
+  readAndExplore: `# Leia e explore
+
+Escolha uma forma de leitura adequada ao documento. Markdown oferece títulos, links e sumário; PDF usa o visualizador nativo do navegador; HTML pode hospedar uma demonstração interativa confiável. Todos permanecem acessíveis pelo mesmo menu da documentação.
+
+## Opções de leitura
+
+- **Modo foco** mantém o Markdown em um diálogo com cópia/download e navegação para primeiro, anterior, próximo e último documento ou seção.
+- **Acessibilidade e narração** explica escolha de voz, controles e suporte do navegador.
+- **Documentos PDF** cobre prévia, download, nova aba e exigências de CORS na hospedagem externa.
+- **Containers HTML** explica arquivos locais, páginas hospedadas e o exemplo DOOM.
+
+## Controle a reprodução
+
+A narração começa somente quando solicitada. Mídias audíveis se coordenam com ela por \`site.mediaExclusivePlayback\`; vozes nativas e players externos dependem de seus provedores. No jogo HTML, use o controle Play do próprio player. Documentos de itens pai, como este, também participam da navegação entre documentos quando o Markdown está disponível e o acesso é permitido.
+`,
+  automateAndIntegrate: `# Automatize e integre
+
+Use automação para tarefas repetíveis, mantendo o repositório como fonte de verdade. A CLI gera arquivos de configuração e documentação. O servidor MCP oferece operações do projeto a um cliente MCP. A autorização de rotas governa a experiência de acesso no visualizador.
+
+## Escolha a interface adequada
+
+- **Referência da CLI** lista instalação, comandos, opções e operações que gravam ou publicam arquivos.
+- **Servidor MCP** descreve configuração stdio, todas as tools e resources, variáveis de provedores e limites do sistema de arquivos.
+- **Rotas autorizadas** explica chaves, roles e provedores externos de identidade.
+
+## Revise antes de publicar
+
+Mantenha credenciais no ambiente ou armazenamento apropriado, nunca na configuração gerada. Inspecione os arquivos alterados antes do commit e valide caminhos da versão e do idioma escolhidos. Arquivos estáticos públicos continuam acessíveis por suas URLs mesmo quando o menu os esconde. Comece por comandos informativos e diretórios de saída explícitos ao comparar uma geração candidata com um site existente.
+`,
+  operationsAndDevelopment: `# Operação e desenvolvimento
+
+Manter um site de documentação envolve seu conteúdo publicado e o runtime que o apresenta. Escolha abaixo o caminho relacionado à mudança: atualizar conteúdo nem sempre exige alterar o frontend, e corrigir o visualizador não deve reescrever documentos históricos sem necessidade.
+
+## Dois caminhos pelo projeto
+
+- **Publique e mantenha** reúne publicação, migração, diagnóstico e perguntas frequentes. Use para preparar uma atualização ou investigar uma falha do site publicado.
+- **Desenvolva o projeto** reúne arquitetura, contribuição/testes e referência de funcionalidades. Use para localizar a fonte correta e a fronteira de validação.
+
+## Mantenha publicações rastreáveis
+
+Registre a versão pretendida, revise os arquivos gerados e preserve documentos usados por links existentes. Valide separadamente o comportamento local e o caminho de publicação. Quando um player externo, voz do navegador ou política de hospedagem mudar, diferencie essa dependência do comportamento do repositório antes de alterar a implementação. Os guias filhos apresentam comandos e verificações para cada tarefa.
+`,
+  shipAndMaintain: `# Publique e mantenha
+
+Trate a publicação como uma mudança validada em uma versão específica. Gere e inspecione o site antes de confiar apenas no sucesso do workflow; uma página publicada ainda pode apontar para um caminho incorreto ou recurso externo indisponível.
+
+## Antes e depois da publicação
+
+1. Leia **Publicação** para execução local, caminhos do GitHub Pages e configuração do workflow.
+2. Use **Migração e compatibilidade** para comparar atualizações preservando conteúdo próprio e configurações históricas suportadas.
+3. Siga **Solução de problemas** quando documentos, PDFs, narração ou integrações variarem entre ambientes.
+4. Consulte **Perguntas frequentes** para respostas curtas sobre configurações comuns.
+
+## Verifique uma amostra útil
+
+Abra diretamente uma página Markdown aninhada, troque o idioma, siga seu breadcrumb e teste as ações de PDF habilitadas. Confirme o commit publicado e a versão do pacote. Tenha um commit recuperável para atualizações e confira a URL pública após um rollback. Não gere novamente um repositório personalizado apenas para repetir um deploy sem revisar o que será substituído.
+`,
+  developTheProject: `# Desenvolva o projeto
+
+Comece pelo módulo responsável pelo comportamento que deseja alterar. O frontend segue Feature-Sliced Design; a CLI possui os templates do scaffold; tools fornece serviços compartilhados de configuração e documentação; MCP expõe esses serviços por seu protocolo.
+
+## Localize a fonte e a fronteira de teste
+
+- **Arquitetura** mapeia pacotes, responsabilidades e fluxo de dados.
+- **Contribuição e testes** identifica templates autorais, saídas geradas e comandos de validação.
+- **Funcionalidades** oferece uma referência ampla das capacidades e configurações existentes.
+
+## Produza uma mudança revisável
+
+Descreva o comportamento observável, reproduza-o pela interface pública e atualize a fonte antes de gerar artefatos. Teste controles renderizados, configurações retornadas ou arquivos escritos, em vez de helpers privados. Revise traduções e acessibilidade ao mudar controles visíveis. Execute as verificações adequadas aos pacotes afetados e inspecione o diff gerado antes do commit. Diretórios de versões existentes devem permanecer intactos, salvo quando a mudança exige explicitamente atualizar seu conteúdo.
+`,
+  gitAndGitHub: `# Git e GitHub
+
+O controle de versão conecta arquivos da documentação, histórico de revisão e publicação. Estes exemplos apresentam práticas do repositório usadas no projeto e complementam os guias de configuração do GitPageDocs.
+
+## Comece pelo guia adequado
+
+- **Introdução ao Git** explica commits, branches e colaboração básica, com um exemplo de vídeo.
+- **GitHub Issues e Projects** mostra como registrar trabalho e organizar seu andamento.
+
+## Aplique o fluxo à documentação
+
+Mantenha mudanças relacionadas de fonte e arquivos gerados no mesmo commit revisado. Use uma branch para migrar configurações, inspecione diferenças antes de publicar e registre o commit implantado pelo Actions. Descreva um defeito com versão, idioma, URL e resultado esperado para permitir reprodução por outro colaborador. Antes de compartilhar logs ou exemplos, remova credenciais e conteúdo privado: um repositório público e seu Pages expõem os arquivos versionados.
+`,
+};

package/content/practical-en.mjs

@@ -0,0 +1,118 @@
+import { HTML_ROUTE_JSON, RECIPE_ROOT_JSON, RECIPE_VERSION_JSON } from "./configuration-examples.mjs";
+
+export const practicalEn = {
+  htmlContainers: `# HTML containers and interactive examples
+
+An HTML route displays a local document or an external web page inside an iframe. Use it for a trusted interactive demonstration that Markdown cannot express. The scaffold includes **DOOM: HTML example**, route 29. Its title and description belong to the documentation container; the HTML itself contains only the game player, without repeated headings, instructions or a custom load button. The game remains hosted by its provider; the npm package contains the HTML integration, not the game assets.
+
+## Configure a local HTML route
+
+Add this route to the version configuration's existing \`routes-html\` array. Keep other routes and give each destination a distinct ID. Create each referenced file as UTF-8 HTML, or generate the bundled example with the CLI.
+
+\`\`\`json
+${HTML_ROUTE_JSON}
+\`\`\`
+
+Add a localized item in \`menus-header-html\`. Each \`path-click\` must match its language's route path, such as \`gitpagedocs/docs/versions/0.0.11/en/doom.html\`; do not substitute \`page:29\` for this local HTML path. Menu labels do not create routes. HTML uses the same recursive \`submenus\` structure as other menus.
+
+## Size, content and external URLs
+
+\`container: "full"\` gives the content a viewport-related minimum height; a positive number sets its height in pixels. Omit it for the normal container. \`fullscreenEnabled\` controls the viewer's fullscreen action. Route title and description remain separate from any heading authored inside the HTML document.
+
+For a hosted page, use \`url: { "en": "https://example.com/demo", "pt": "https://example.com/demo", "es": "https://example.com/demo" }\` instead of \`path\`. A URL route uses iframe navigation; local HTML is loaded into \`srcDoc\`. For local content, prefer self-contained styling and explicit HTTPS asset URLs: a srcDoc document does not automatically resolve assets relative to the original file's directory.
+
+The external host can prevent framing through CSP or X-Frame-Options. Known blocked hosts receive an open-in-new-tab alternative; arbitrary hosting failures are not universally detectable. Test the actual target in the deployed site. \`blockLink: true\` sets the default target of links in local HTML to a new tab; it does not prevent navigation performed by scripts or links that set their own target.
+
+## Use and maintain the game example
+
+Select the HTML menu entry. The player SDK loads when the page opens; use its native Play control to start the game. There is no automatic game start or separate documentation load button. Network access is required. A bootstrap failure displays an error asking you to reload the page; the normal view contains only the player. Test keyboard focus, small screens, fullscreen and returning to the documentation. Third-party player availability and browser capabilities can change independently of GitPageDocs.
+
+Review HTML and dependencies before publishing. The current iframe permits scripts and same-origin content, so it is not a security boundary for arbitrary untrusted HTML. Do not put secrets in HTML, URLs or client configuration. Static hosting exposes the files independently of menu visibility or route authorization. For local development and Pages, commit the wrapper alongside its version configuration and validate the generated paths before deployment.
+`,
+  configurationRecipes: `# Configuration recipes
+
+This guide builds a small multilingual documentation site with two Markdown pages and a menu three levels deep. Start from generated configuration, review your changes and keep the original files in version control. The examples use IDs 101 and 102 so they can be distinguished from the bundled pages.
+
+## 1. Generate and inspect the scaffold
+
+The scaffold includes versions 0.0.11 and 0.0.10 in the version selector. Both contain the current examples; the package version remains 0.0.11. Their paths and version badges are generated for the selected documentation version. Older existing version folders are not deleted.
+
+Run \`npx --yes @gitpagedocs/cli@0.0.11 --no-interactive --owner YOUR_USER --repo YOUR_REPOSITORY\` in a new project directory. In this source repository, \`node cli/index.mjs\` runs the checked-out version. Generation writes configuration and documentation; it does not start the Next.js viewer.
+
+Use the following complete JSON as a minimal root-config example in \`gitpagedocs/config.json\`. For an existing site, merge the relevant fields and preserve its repository identity, deployment settings, themes and other versions.
+
+\`\`\`json
+${RECIPE_ROOT_JSON}
+\`\`\`
+
+The eight entries inherit the common icon presentation from \`icons.defaults\`. To display text for one action, add \`"reactIcon": false\` to that entry. Do not change a shared default just to alter one button. Existing flat icon fields win over compact fields, so remove or update an old conflicting field deliberately.
+
+## 2. Create the version configuration
+
+Save the next complete JSON document at the version-config path shown above. A menu category has a title and \`submenus\`; a leaf has a localized \`path-click\`. Categories do not need a route. Markdown leaves point to actual Markdown paths rather than \`page:<id>\` aliases.
+
+\`\`\`json
+${RECIPE_VERSION_JSON}
+\`\`\`
+
+Create \`start.md\` and \`next-steps.md\` in each of the version's \`en\`, \`pt\` and \`es\` folders: six files in total. Write the corresponding language in each file and save it as UTF-8. Start each page with a heading; add \`##\` sections to exercise the focus reader. The generated \`langs/\` bundles provide interface text separately from document content.
+
+## 3. Change presentation without losing destinations
+
+With \`nestedMenusEnabled: true\`, readers expand Guides → Getting started → page. Setting it to \`false\` exposes the same destinations as a flat menu. Add further \`submenus\` recursively when the content justifies it; there is no fixed configured depth limit. Keep sibling identities distinct and avoid repeating the same destination merely to make the tree deeper.
+
+Breadcrumbs use \`site.RouteGuide\`, then version \`routeDefaults.RouteGuide\`, then the individual route. The most specific explicit value wins. \`RouteguideBrand\` is the separate heading outline. Footer previous/next arrows follow available menu destinations; \`ActiveNavigation\` controls quick navigation and Ctrl+K.
+
+## 4. Add media and verify the result
+
+Use the PDF documents reference to add \`routes-pdf\` and \`menus-header-pdf\`; its \`page:23\` example points to the bundled English file. Preview, download and new-tab controls are independent of their icon appearance. External PDF files need CORS for all three actions; local repository PDFs under \`gitpagedocs/\` are staged during Next.js dev/build.
+
+Check every language, expand all menu groups and follow each leaf. Try direct page URLs, text/icon overrides, focus first/previous/next/last controls and the disabled navigation boundaries. Inspect the generated version config when a label works but a destination does not. Commit the reviewed configuration together with all referenced documents and assets.
+`,
+  contributing: `# Contributing and testing
+
+Work from the source repository when changing the runtime, CLI, shared tools or MCP server. A consuming documentation repository normally edits its own content and configuration instead. Keep a focused branch and describe the user-visible behavior and how it was verified.
+
+## Work in the owning package
+
+\`frontend/\` contains the Next.js App Router viewer and follows Feature-Sliced Design. Shared visual primitives live in \`shared\`, documentation data and schemas in \`entities\`, user capabilities in \`features\`, and the assembled reader in \`widgets\`. Keep filesystem and repository loading out of presentation components.
+
+\`cli/\` owns the scaffold, commands, data defaults and authoring templates. \`tools/\` supplies reusable configuration, documentation and service logic. \`mcp/\` exposes the shared capabilities over Model Context Protocol. A UI fix usually belongs in frontend; a scaffold default must be changed in its CLI source and regenerated.
+
+## Edit sources rather than generated copies
+
+| Change | Source of truth | Generated result |
+| --- | --- | --- |
+| Site options and language labels | \`cli/data/\` | Root config and \`gitpagedocs/langs/\` |
+| Routes and menu sections | CLI builders, route metadata, path mappings and \`menu-sections.mjs\` | Version configuration |
+| Documentation prose | \`cli/content/docs-{en,pt,es}.mjs\` and imported content modules | Versioned Markdown |
+| Managed repository documents | \`tools/src/documentation/sections.ts\` | README, CONTRIBUTING and SECURITY regions |
+| Layout definitions | \`gitpagelayouts/v2/\` | Templates and layout documentation |
+
+After CLI/content changes run \`node cli/index.mjs\`, copy \`gitpagedocs/\` into \`tools/gitpagedocs/\` without deleting historical versions, then run \`pnpm run baseline:create\`. Use \`node cli/index.mjs docs\` for managed regions and \`pnpm run layouts:sync\` for layout changes. Inspect the diff: generation must not silently replace custom material you intended to retain.
+
+## Verify behavior through public interfaces
+
+Write a failing regression before the implementation. Test the observable contract: generated configuration and files for CLI changes, tool/resource responses for MCP, rendered controls and keyboard behavior for UI, and browser interactions for navigation or media. Avoid assertions that only repeat an internal helper's algorithm.
+
+Cover success, unavailable features, malformed inputs and meaningful boundaries. Examples include a missing translation, denied route, empty PDF title, blocked popup, CORS failure, first/last navigation limits and an empty native-voice list. Use isolated temporary output folders for generators. Mock network or browser capabilities at their public boundary; keep the project's own collaborators real when practical.
+
+\`\`\`sh
+pnpm install --frozen-lockfile
+pnpm run typecheck
+pnpm run lint
+pnpm exec vitest run
+pnpm run smoke:all
+pnpm run build
+pnpm exec cross-env PORT=3100 pnpm run test:e2e
+\`\`\`
+
+The E2E configuration uses ports 3100 and 3101; leave port 3000's existing service alone. \`smoke:all\` includes CLI contracts, shared services, MCP discovery, documentation generation and \`baseline:check\`. \`pnpm run test:cov\` adds coverage. A local production build is distinct from the Pages static-export environment, which must also be verified for deployment-path changes.
+
+## Review and release
+
+Review accessibility, authorization, input validation, errors, resource cleanup and generated-file consistency. Analyze each changed source with the configured SonarQube project and the appropriate test/source scope; use the stack parser or linter for unsupported formats. Keep credentials and transient test artifacts out of commits.
+
+Publishable packages are \`@gitpagedocs/tools\`, \`@gitpagedocs/mcp\` and \`@gitpagedocs/cli\`; root and frontend are private. Synchronize versions, internal dependency ranges and lockfile entries, inspect package contents, and finish validation before pushing. The current npm workflow runs on main pushes and publishes in dependency order when the CLI version is new. Confirm npm versions and the Pages deployment afterward; a successful local build alone is not publication.
+`,
+};

package/content/practical-es.mjs

@@ -0,0 +1,118 @@
+import { HTML_ROUTE_JSON, RECIPE_ROOT_JSON, RECIPE_VERSION_JSON } from "./configuration-examples.mjs";
+
+export const practicalEs = {
+  htmlContainers: `# Contenedores HTML y ejemplos interactivos
+
+Una ruta HTML muestra un documento local o una página externa dentro de un iframe. Úsala para una demostración interactiva de confianza que Markdown no puede representar. El scaffold incluye **DOOM: ejemplo HTML**, ruta 29. El título y la descripción pertenecen al contenedor de documentación; el HTML contiene solo el reproductor, sin repetir encabezados, instrucciones ni crear un botón de carga propio. El juego permanece alojado por su proveedor; el paquete npm incluye la integración HTML, no los archivos del juego.
+
+## Configura una ruta HTML local
+
+Añade esta ruta al array \`routes-html\` existente en la configuración de la versión. Conserva las demás rutas y utiliza un ID distinto para cada destino. Crea cada archivo referenciado como HTML UTF-8 o genera el ejemplo incluido mediante la CLI.
+
+\`\`\`json
+${HTML_ROUTE_JSON}
+\`\`\`
+
+Añade un elemento traducido en \`menus-header-html\`. Cada \`path-click\` debe coincidir con la ruta de su idioma, como \`gitpagedocs/docs/versions/0.0.11/es/doom.html\`; no sustituyas esta ruta HTML local por \`page:29\`. Una etiqueta de menú no crea una ruta. HTML admite la misma estructura recursiva \`submenus\` que los demás menús.
+
+## Tamaño, contenido y URLs externas
+
+\`container: "full"\` establece una altura mínima relacionada con la ventana; un número positivo fija la altura en píxeles. Omítelo para utilizar el contenedor normal. \`fullscreenEnabled\` controla la acción de pantalla completa del visor. El título y la descripción de la ruta son independientes de los encabezados escritos dentro del HTML.
+
+Para una página alojada, usa \`url: { "en": "https://example.com/demo", "pt": "https://example.com/demo", "es": "https://example.com/demo" }\` en lugar de \`path\`. Una ruta URL navega el iframe; el HTML local se carga en \`srcDoc\`. En contenido local, prefiere estilos incluidos y URLs HTTPS explícitas: srcDoc no resuelve automáticamente los recursos respecto al directorio del archivo original.
+
+El servidor externo puede impedir la incorporación mediante CSP o X-Frame-Options. Los hosts conocidos que bloquean iframe reciben una alternativa para abrir en otra pestaña; no se detectan universalmente los fallos de cualquier servidor. Prueba el destino real en el sitio publicado. \`blockLink: true\` establece otra pestaña como destino predeterminado de los enlaces del HTML local; no impide la navegación de scripts o enlaces con destino propio.
+
+## Utiliza y mantén el ejemplo del juego
+
+Selecciona la entrada HTML. El SDK del reproductor se carga al abrir la página; usa su control Play nativo para iniciar el juego. No hay inicio automático ni un botón de carga separado de la documentación. Se necesita conexión. Un fallo de inicialización muestra un error que indica recargar la página; la vista normal contiene solo el reproductor. Prueba el foco del teclado, pantallas pequeñas, pantalla completa y el regreso a la documentación. La disponibilidad del reproductor y las capacidades del navegador pueden cambiar independientemente de GitPageDocs.
+
+Revisa el HTML y sus dependencias antes de publicar. El iframe actual permite scripts y contenido del mismo origen, por lo que no es una barrera de seguridad para HTML arbitrario no confiable. No incluyas secretos en HTML, URLs ni configuración del cliente. El alojamiento estático expone los archivos independientemente de la visibilidad del menú o autorización de la ruta. En local y Pages, versiona la página junto con su configuración y valida las rutas generadas antes de publicar.
+`,
+  configurationRecipes: `# Recetas de configuración
+
+Esta guía crea un sitio pequeño en tres idiomas, con dos páginas Markdown y un menú de tres niveles. Parte de la configuración generada, revisa los cambios y conserva los archivos originales en el control de versiones. Los ejemplos utilizan los IDs 101 y 102 para distinguirlos de las páginas incluidas.
+
+## 1. Genera y revisa la estructura
+
+El scaffold incluye las versiones 0.0.11 y 0.0.10 en el selector. Ambas contienen los ejemplos actuales; la versión del paquete sigue siendo 0.0.11. Las rutas y etiquetas se generan para la versión correspondiente de la documentación. No se eliminan las carpetas existentes de versiones anteriores.
+
+Ejecuta \`npx --yes @gitpagedocs/cli@0.0.11 --no-interactive --owner TU_USUARIO --repo TU_REPOSITORIO\` en un directorio de proyecto nuevo. En este repositorio de código fuente, \`node cli/index.mjs\` ejecuta la versión del checkout. La generación escribe configuración y documentación; no inicia el visor Next.js.
+
+El siguiente JSON completo es un ejemplo mínimo de \`gitpagedocs/config.json\`. Para un sitio existente, combina los campos relevantes y conserva la identidad del repositorio, la publicación, los temas y las demás versiones.
+
+\`\`\`json
+${RECIPE_ROOT_JSON}
+\`\`\`
+
+Las ocho entradas heredan la presentación común de \`icons.defaults\`. Para mostrar texto en una acción, añade \`"reactIcon": false\` a esa entrada. No cambies un valor compartido solo para modificar un botón. Los campos planos antiguos tienen prioridad sobre los compactos; elimina o actualiza un campo conflictivo tras confirmar su intención.
+
+## 2. Crea la configuración de versión
+
+Guarda el siguiente JSON completo en la ruta del config de versión indicada arriba. Una categoría tiene título y \`submenus\`; una hoja tiene \`path-click\` localizado. Las categorías no necesitan ruta. Los destinos Markdown usan las rutas reales de los archivos, no el alias \`page:<id>\`.
+
+\`\`\`json
+${RECIPE_VERSION_JSON}
+\`\`\`
+
+Crea \`start.md\` y \`next-steps.md\` en las carpetas \`en\`, \`pt\` y \`es\` de esa versión: seis archivos en total. Escribe cada idioma y guarda como UTF-8. Inicia cada página con un título y añade secciones \`##\` para probar el modo foco. Los bundles de \`langs/\` contienen el texto de interfaz, separado del contenido de los documentos.
+
+## 3. Cambia la presentación conservando destinos
+
+Con \`nestedMenusEnabled: true\`, el lector expande Guías → Primeros pasos → página. Con \`false\`, los mismos destinos aparecen como una lista plana. Añade \`submenus\` recursivamente cuando el contenido lo justifique; no existe un límite fijo de profundidad configurado. Usa identidades distintas entre hermanos y evita repetir destinos solo para hacer más profundo el árbol.
+
+Los breadcrumbs usan \`site.RouteGuide\`, después \`routeDefaults.RouteGuide\` de la versión y finalmente la ruta individual. Gana el valor explícito más específico. \`RouteguideBrand\` controla el índice separado de encabezados. Las flechas anterior/siguiente del pie siguen los destinos disponibles; \`ActiveNavigation\` controla la navegación rápida y Ctrl+K.
+
+## 4. Añade medios y verifica
+
+Consulta Documentos PDF para añadir \`routes-pdf\` y \`menus-header-pdf\`; el ejemplo \`page:23\` apunta a la guía en inglés incluida. Vista previa, descarga y nueva pestaña son independientes de la apariencia de sus iconos. Los PDFs externos necesitan CORS para las tres acciones; los PDFs locales dentro de \`gitpagedocs/\` se preparan al ejecutar o compilar Next.js.
+
+Comprueba todos los idiomas, expande cada categoría y sigue cada hoja. Prueba URLs directas, cambios de texto/icono, primero/anterior/siguiente/último en foco y direcciones desactivadas en los extremos. Inspecciona el config de versión cuando aparece una etiqueta pero falla su destino. Haz commit de la configuración revisada junto con los documentos y anexos referenciados.
+`,
+  contributing: `# Contribución y pruebas
+
+Trabaja desde el repositorio de código fuente para cambiar el runtime, la CLI, las herramientas compartidas o MCP. Un repositorio que consume el visor normalmente edita su propio contenido y configuración. Usa una rama enfocada y describe el comportamiento visible y cómo se verificó.
+
+## Trabaja en el paquete responsable
+
+\`frontend/\` contiene el visor Next.js App Router y sigue Feature-Sliced Design. Los primitivos visuales compartidos pertenecen a \`shared\`, datos y schemas a \`entities\`, capacidades del usuario a \`features\` y la composición del lector a \`widgets\`. Mantén la carga del sistema de archivos y repositorios fuera de los componentes de presentación.
+
+\`cli/\` contiene scaffold, comandos, valores predeterminados y plantillas autorales. \`tools/\` ofrece lógica reutilizable de configuración, documentación y servicios. \`mcp/\` expone estas capacidades mediante Model Context Protocol. Una corrección visual suele pertenecer al frontend; un default del scaffold debe cambiar en su fuente CLI y regenerarse.
+
+## Edita las fuentes, no las copias generadas
+
+| Cambio | Fuente de verdad | Resultado generado |
+| --- | --- | --- |
+| Opciones del sitio y textos de idioma | \`cli/data/\` | Config raíz y \`gitpagedocs/langs/\` |
+| Rutas y secciones del menú | Builders CLI, metadatos, mapeos y \`menu-sections.mjs\` | Config de versión |
+| Documentación | \`cli/content/docs-{en,pt,es}.mjs\` y módulos importados | Markdown versionado |
+| Regiones gestionadas | \`tools/src/documentation/sections.ts\` | README, CONTRIBUTING y SECURITY |
+| Definiciones de diseños | \`gitpagelayouts/v2/\` | Plantillas y documentación de diseños |
+
+Después de cambiar CLI/contenido, ejecuta \`node cli/index.mjs\`, copia \`gitpagedocs/\` a \`tools/gitpagedocs/\` sin borrar versiones históricas y ejecuta \`pnpm run baseline:create\`. Usa \`node cli/index.mjs docs\` para regiones gestionadas y \`pnpm run layouts:sync\` para diseños. Revisa el diff: la generación no debe sustituir silenciosamente contenido personalizado que querías conservar.
+
+## Verifica interfaces públicas
+
+Escribe una regresión que falle antes de implementar. Prueba el contrato observable: configuración y archivos generados para CLI, respuestas de tools/resources para MCP, controles y teclado para UI, e interacciones reales de navegador para navegación o medios. Evita pruebas que solo repiten el algoritmo de un helper interno.
+
+Cubre éxito, funciones no disponibles, entradas inválidas y límites relevantes. Ejemplos: traducción ausente, ruta denegada, título PDF vacío, ventana bloqueada, error CORS, límites primero/último y lista vacía de voces nativas. Usa carpetas temporales aisladas para generadores. Simula red o APIs del navegador en su frontera pública; conserva colaboradores reales del proyecto cuando sea práctico.
+
+\`\`\`sh
+pnpm install --frozen-lockfile
+pnpm run typecheck
+pnpm run lint
+pnpm exec vitest run
+pnpm run smoke:all
+pnpm run build
+pnpm exec cross-env PORT=3100 pnpm run test:e2e
+\`\`\`
+
+La configuración E2E usa los puertos 3100 y 3101; conserva el servicio existente en 3000. \`smoke:all\` incluye contratos CLI, servicios compartidos, descubrimiento MCP, documentación y \`baseline:check\`. \`pnpm run test:cov\` añade cobertura. El build local de producción es distinto del entorno de exportación estática de Pages, que también debe verificarse si cambian las rutas de publicación.
+
+## Revisión y publicación
+
+Revisa accesibilidad, autorización, validación de entradas, errores, liberación de recursos y coherencia de archivos generados. Analiza cada fuente modificada en el proyecto SonarQube configurado con el alcance de prueba o producción correspondiente; usa parser/linter de la stack para formatos no compatibles. Mantén credenciales y archivos temporales fuera de commits.
+
+Los paquetes publicables son \`@gitpagedocs/tools\`, \`@gitpagedocs/mcp\` y \`@gitpagedocs/cli\`; raíz y frontend son privados. Sincroniza versiones, dependencias internas y lockfile, inspecciona los paquetes y completa las verificaciones antes del push. El workflow npm actual se ejecuta en pushes a main y pública en orden de dependencias cuando la versión CLI es nueva. Confirma npm y Pages después; un build local correcto no equivale a publicar.
+`,
+};

package/content/practical-pt.mjs

@@ -0,0 +1,118 @@
+import { HTML_ROUTE_JSON, RECIPE_ROOT_JSON, RECIPE_VERSION_JSON } from "./configuration-examples.mjs";
+
+export const practicalPt = {
+  htmlContainers: `# Containers HTML e exemplos interativos
+
+Uma rota HTML exibe um documento local ou uma página externa dentro de um iframe. Use-a para uma demonstração interativa confiável que o Markdown não consegue representar. O scaffold inclui **DOOM: exemplo HTML**, rota 29. O título e a descrição pertencem ao container da documentação; o HTML contém somente o player, sem repetir títulos, instruções ou criar um botão próprio de carregamento. O jogo continua hospedado pelo provedor; o pacote npm inclui a integração HTML, não os arquivos do jogo.
+
+## Configure uma rota HTML local
+
+Adicione esta rota ao array \`routes-html\` existente na configuração da versão. Preserve as demais rotas e use um ID distinto para cada destino. Crie cada arquivo referenciado como HTML UTF-8 ou gere o exemplo incluído pela CLI.
+
+\`\`\`json
+${HTML_ROUTE_JSON}
+\`\`\`
+
+Adicione um item traduzido em \`menus-header-html\`. Cada \`path-click\` deve corresponder ao caminho da rota no mesmo idioma, como \`gitpagedocs/docs/versions/0.0.11/pt/doom.html\`; não substitua esse caminho HTML local por \`page:29\`. Um rótulo de menu não cria uma rota. HTML aceita a mesma estrutura recursiva \`submenus\` dos outros menus.
+
+## Dimensões, conteúdo e URLs externas
+
+\`container: "full"\` aplica uma altura mínima relacionada à janela; um número positivo define a altura em pixels. Omita-o para usar o container normal. \`fullscreenEnabled\` controla a ação de tela cheia do visualizador. Título e descrição da rota são independentes dos títulos escritos dentro do próprio HTML.
+
+Para uma página hospedada, use \`url: { "en": "https://example.com/demo", "pt": "https://example.com/demo", "es": "https://example.com/demo" }\` no lugar de \`path\`. Uma rota URL navega o iframe; o HTML local é carregado em \`srcDoc\`. No conteúdo local, prefira estilos incluídos no documento e URLs HTTPS explícitas: srcDoc não resolve automaticamente os recursos relativos ao diretório do arquivo original.
+
+O servidor externo pode impedir incorporação por CSP ou X-Frame-Options. Hosts conhecidos que bloqueiam iframe recebem uma alternativa para abrir em nova aba; falhas de qualquer servidor não são detectadas universalmente. Teste o destino real no site publicado. \`blockLink: true\` define nova aba como destino padrão dos links no HTML local; não impede navegação feita por scripts ou links com destino próprio.
+
+## Use e mantenha o exemplo do jogo
+
+Escolha o item HTML no menu. O SDK do player carrega quando a página abre; use o controle Play nativo para iniciar o jogo. Não há início automático nem botão de carregamento separado da documentação. É necessária conexão. Uma falha de inicialização exibe um erro que orienta recarregar a página; a visualização normal contém apenas o player. Teste foco de teclado, telas pequenas, tela cheia e retorno à documentação. Disponibilidade do player e recursos do navegador podem mudar independentemente do GitPageDocs.
+
+Revise o HTML e suas dependências antes de publicar. O iframe atual permite scripts e conteúdo de mesma origem, portanto não funciona como barreira de segurança para HTML arbitrário não confiável. Não inclua segredos em HTML, URLs ou configuração do cliente. A hospedagem estática expõe os arquivos independentemente da visibilidade do menu ou autorização da rota. No ambiente local e no Pages, versione a página com a configuração correspondente e valide os caminhos gerados antes da publicação.
+`,
+  configurationRecipes: `# Receitas de configuração
+
+Este guia monta um site pequeno em três idiomas, com duas páginas Markdown e menu com três níveis. Comece pela configuração gerada, revise as mudanças e mantenha os arquivos originais no controle de versão. Os exemplos usam os IDs 101 e 102 para distingui-los das páginas incluídas no scaffold.
+
+## 1. Gere e confira a estrutura
+
+O scaffold inclui as versões 0.0.11 e 0.0.10 no seletor. Ambas contêm os exemplos atuais; a versão do pacote continua sendo 0.0.11. Caminhos e rótulos de versão são gerados para a versão correspondente da documentação. Pastas existentes de versões anteriores não são apagadas.
+
+Execute \`npx --yes @gitpagedocs/cli@0.0.11 --no-interactive --owner SEU_USUARIO --repo SEU_REPOSITORIO\` em um diretório de projeto novo. Neste repositório de código-fonte, \`node cli/index.mjs\` executa a versão do checkout. A geração grava configuração e documentação; ela não inicia o visualizador Next.js.
+
+O JSON completo abaixo é um exemplo mínimo de \`gitpagedocs/config.json\`. Em um site existente, mescle os campos relevantes e preserve a identidade do repositório, opções de publicação, temas e demais versões.
+
+\`\`\`json
+${RECIPE_ROOT_JSON}
+\`\`\`
+
+As oito entradas herdam a apresentação comum de \`icons.defaults\`. Para mostrar texto em uma ação, acrescente \`"reactIcon": false\` à entrada correspondente. Não altere um default compartilhado apenas para mudar um botão. Campos planos antigos de ícones prevalecem sobre os compactos; remova ou atualize um campo conflitante somente depois de confirmar sua intenção.
+
+## 2. Crie a configuração da versão
+
+Salve o próximo JSON completo no caminho do config da versão indicado acima. Uma categoria de menu tem título e \`submenus\`; uma folha tem \`path-click\` localizado. Categorias não precisam de rota. Destinos Markdown apontam para os caminhos reais dos arquivos, sem usar o alias \`page:<id>\`.
+
+\`\`\`json
+${RECIPE_VERSION_JSON}
+\`\`\`
+
+Crie \`start.md\` e \`next-steps.md\` nas pastas \`en\`, \`pt\` e \`es\` dessa versão: seis arquivos ao todo. Escreva no idioma correspondente e salve em UTF-8. Comece cada página com um título e acrescente seções \`##\` para testar o modo foco. Os bundles gerados em \`langs/\` contêm os textos da interface, separados do conteúdo dos documentos.
+
+## 3. Mude a apresentação sem perder destinos
+
+Com \`nestedMenusEnabled: true\`, o leitor expande Guias → Primeiros passos → página. Com \`false\`, os mesmos destinos aparecem em uma lista plana. Acrescente \`submenus\` recursivamente quando a organização do conteúdo justificar; não há limite fixo de profundidade configurado. Mantenha identidades distintas entre irmãos e evite repetir destinos apenas para aumentar a árvore.
+
+Breadcrumbs usam \`site.RouteGuide\`, depois \`routeDefaults.RouteGuide\` da versão e por último a rota individual. O valor explícito mais específico prevalece. \`RouteguideBrand\` é o índice separado de títulos. As setas Voltar/Próximo do rodapé seguem os destinos disponíveis; \`ActiveNavigation\` controla a navegação rápida e Ctrl+K.
+
+## 4. Inclua mídia e valide
+
+Consulte Documentos PDF para adicionar \`routes-pdf\` e \`menus-header-pdf\`; o exemplo \`page:23\` aponta para o guia em inglês incluído. Prévia, download e nova aba são independentes da aparência dos ícones. PDFs externos precisam permitir CORS nas três ações; PDFs locais dentro de \`gitpagedocs/\` são preparados ao executar ou compilar o Next.js.
+
+Confira todos os idiomas, expanda cada categoria e percorra as folhas. Teste URLs diretas, alterações entre texto e ícone, primeiro/anterior/próximo/último no foco e direções desabilitadas nas extremidades. Inspecione o config da versão quando o rótulo aparece mas o destino falha. Faça commit da configuração revisada junto com os documentos e anexos referenciados.
+`,
+  contributing: `# Contribuição e testes
+
+Use o repositório de código-fonte para alterar o runtime, a CLI, as ferramentas compartilhadas ou o MCP. Um repositório que apenas consome o visualizador normalmente edita seu próprio conteúdo e configuração. Trabalhe em uma branch focada e descreva o comportamento visível ao usuário e sua validação.
+
+## Altere o pacote responsável
+
+\`frontend/\` contém o visualizador Next.js App Router e segue Feature-Sliced Design. Primitivos visuais compartilhados ficam em \`shared\`, dados e schemas de documentação em \`entities\`, recursos do usuário em \`features\` e a composição do leitor em \`widgets\`. Mantenha carregamento de arquivos e repositórios fora dos componentes de apresentação.
+
+\`cli/\` é responsável pelo scaffold, comandos, defaults e templates autorais. \`tools/\` fornece lógica reutilizável de configuração, documentação e serviços. \`mcp/\` expõe essas capacidades pelo Model Context Protocol. Uma correção visual normalmente pertence ao frontend; um default do scaffold deve mudar na fonte da CLI e ser regenerado.
+
+## Edite as fontes, não as cópias geradas
+
+| Mudança | Fonte de verdade | Resultado gerado |
+| --- | --- | --- |
+| Opções do site e textos de idioma | \`cli/data/\` | Config raiz e \`gitpagedocs/langs/\` |
+| Rotas e seções do menu | Builders da CLI, metadados, mapeamentos e \`menu-sections.mjs\` | Config da versão |
+| Textos da documentação | \`cli/content/docs-{en,pt,es}.mjs\` e módulos importados | Markdown versionado |
+| Regiões gerenciadas | \`tools/src/documentation/sections.ts\` | README, CONTRIBUTING e SECURITY |
+| Definições de layouts | \`gitpagelayouts/v2/\` | Templates e documentação de layouts |
+
+Após alterar CLI/conteúdo, execute \`node cli/index.mjs\`, copie \`gitpagedocs/\` para \`tools/gitpagedocs/\` sem excluir versões históricas e execute \`pnpm run baseline:create\`. Use \`node cli/index.mjs docs\` nas regiões gerenciadas e \`pnpm run layouts:sync\` para layouts. Revise o diff: a geração não deve substituir silenciosamente material customizado que você queria manter.
+
+## Teste pelas interfaces públicas
+
+Escreva uma regressão que falha antes de implementar. Teste o contrato observável: configuração e arquivos gerados na CLI, respostas de tools/resources no MCP, controles e teclado na UI, interações reais do navegador em navegação e mídia. Evite testes que apenas repetem o algoritmo de um helper interno.
+
+Cubra sucesso, recursos indisponíveis, entradas inválidas e limites relevantes. Exemplos: tradução ausente, rota negada, título PDF vazio, pop-up bloqueado, falha CORS, limites primeiro/último e lista vazia de vozes nativas. Use pastas temporárias isoladas para geradores. Simule rede ou APIs do navegador na fronteira pública; mantenha colaboradores do projeto reais quando possível.
+
+\`\`\`sh
+pnpm install --frozen-lockfile
+pnpm run typecheck
+pnpm run lint
+pnpm exec vitest run
+pnpm run smoke:all
+pnpm run build
+pnpm exec cross-env PORT=3100 pnpm run test:e2e
+\`\`\`
+
+A configuração E2E usa as portas 3100 e 3101; preserve o serviço existente na 3000. \`smoke:all\` inclui contratos da CLI, serviços compartilhados, descoberta MCP, documentação e \`baseline:check\`. \`pnpm run test:cov\` acrescenta cobertura. O build local de produção é diferente do ambiente de exportação estática do Pages, que também deve ser validado quando caminhos de publicação mudam.
+
+## Revise e publique
+
+Revise acessibilidade, autorização, validação de entrada, erros, liberação de recursos e consistência dos arquivos gerados. Análise cada fonte alterada no projeto SonarQube configurado com o escopo correto de teste ou produção; use parser/linter da stack nos formatos sem suporte. Não inclua credenciais ou artefatos temporários nos commits.
+
+Os pacotes publicáveis são \`@gitpagedocs/tools\`, \`@gitpagedocs/mcp\` e \`@gitpagedocs/cli\`; raiz e frontend são privados. Sincronize versões, dependências internas e lockfile, inspecione os pacotes e conclua a validação antes do push. O workflow npm atual roda em pushes para main e pública em ordem de dependência quando a versão da CLI é nova. Confirme npm e Pages depois; um build local verde não equivale à publicação.
+`,
+};

package/contracts/doc-versions.mjs

@@ -1,3 +1,3 @@
-export const PACKAGE_VERSION = "0.0.9";
+export const PACKAGE_VERSION = "0.0.11";
 
-export const DOC_VERSIONS = [PACKAGE_VERSION];
+export const DOC_VERSIONS = [PACKAGE_VERSION, "0.0.10"];

package/data/composed-pages.mjs

@@ -0,0 +1,25 @@
+export const COMPOSED_PAGE_ID = 39;
+
+export const COMPOSED_PAGE_MENU = {
+  id: COMPOSED_PAGE_ID,
+  pathClick: `page:${COMPOSED_PAGE_ID}`,
+  titles: { en: "Multiple content blocks", pt: "Múltiplos blocos de conteúdo", es: "Múltiples bloques de contenido" },
+};
+
+export const COMPOSED_PAGES = [{
+  id: COMPOSED_PAGE_ID,
+  blocks: [
+    { id: "getting-started", type: "md", routeId: 1 },
+    { id: "project-overview", type: "md", routeId: 2 },
+    { id: "html-guide", type: "md", routeId: 30 },
+    { id: "doom-first", type: "html", routeId: 29 },
+    { id: "doom-second", type: "html", routeId: 29 },
+    { id: "video-first", type: "video", routeId: 11 },
+    { id: "video-second", type: "video", routeId: 11 },
+    { id: "audio-first", type: "audio", routeId: 12 },
+    { id: "audio-second", type: "audio", routeId: 12 },
+    { id: "pdf-first", type: "pdf", routeId: 23 },
+    { id: "pdf-second", type: "pdf", routeId: 23 },
+    { id: "pdf-third", type: "pdf", routeId: 23 },
+  ],
+}];