@gitpagedocs/cli 0.0.10 → 0.0.11

package/content/html-doom.mjs

@@ -4,38 +4,20 @@ const DOOM_BUNDLE_URL = "https://v8.js-dos.com/bundles/doom.jsdos";
 const COPY = {
   en: {
     title: "DOOM in an HTML container",
-    description: "An interactive example with its own title, description and game area. Start DOOM below to load the external js-dos player.",
-    play: "Load DOOM",
-    loading: "Loading the player. This may take a moment…",
-    ready: "DOOM is ready. Click the game area to use the keyboard.",
-    error: "The player could not load. Check your connection and try again, or open the official game page.",
-    instructions: "Press Enter to select a menu item. Use the arrow keys to move, Ctrl to fire, Space to open doors and Esc to open the game menu.",
-    notice: "Internet access is required. The player and game load from js-dos only after you press the button. Keyboard recommended; sound follows your browser settings.",
-    source: "Open DOOM on DOS Zone",
+    description: "Play DOOM in the embedded js-dos player.",
+    error: "The player could not load. Check your connection and reload this page to try again.",
     player: "DOOM game area",
   },
   pt: {
     title: "DOOM em um container HTML",
-    description: "Um exemplo interativo com título, descrição e área de jogo próprios. Inicie o DOOM abaixo para carregar o player externo js-dos.",
-    play: "Jogar DOOM",
-    loading: "Carregando o player. Isso pode levar alguns instantes…",
-    ready: "DOOM pronto. Clique na área do jogo para usar o teclado.",
-    error: "Não foi possível carregar o player. Verifique sua conexão e tente novamente ou abra a página oficial do jogo.",
-    instructions: "Pressione Enter para selecionar uma opção. Use as setas para se mover, Ctrl para atirar, Espaço para abrir portas e Esc para abrir o menu do jogo.",
-    notice: "É necessário acesso à internet. O player e o jogo são carregados do js-dos somente depois do clique. Teclado recomendado; o som segue as configurações do navegador.",
-    source: "Abrir DOOM no DOS Zone",
+    description: "Jogue DOOM no player js-dos incorporado.",
+    error: "Não foi possível carregar o player. Verifique sua conexão e recarregue esta página para tentar novamente.",
     player: "Área do jogo DOOM",
   },
   es: {
     title: "DOOM en un contenedor HTML",
-    description: "Un ejemplo interactivo con título, descripción y área de juego propios. Inicia DOOM a continuación para cargar el reproductor externo js-dos.",
-    play: "Cargar DOOM",
-    loading: "Cargando el reproductor. Esto puede tardar un momento…",
-    ready: "DOOM está listo. Haz clic en el juego para usar el teclado.",
-    error: "No se pudo cargar el reproductor. Comprueba tu conexión e inténtalo de nuevo o abre la página oficial del juego.",
-    instructions: "Pulsa Enter para seleccionar una opción. Usa las flechas para moverte, Ctrl para disparar, Espacio para abrir puertas y Esc para abrir el menú del juego.",
-    notice: "Se necesita conexión a internet. El reproductor y el juego se cargan desde js-dos solo después de pulsar el botón. Se recomienda teclado; el sonido sigue la configuración del navegador.",
-    source: "Abrir DOOM en DOS Zone",
+    description: "Juega a DOOM en el reproductor js-dos integrado.",
+    error: "No se pudo cargar el reproductor. Comprueba tu conexión y recarga esta página para intentarlo de nuevo.",
     player: "Área del juego DOOM",
   },
 };
@@ -43,26 +25,17 @@ const COPY = {
 const STYLE = `
   :root { color-scheme: dark; }
   * { box-sizing: border-box; }
-  body { margin: 0; background: #101018; color: #f4f4f7; }
-  #doom-example { max-width: 1100px; margin: auto; padding: clamp(20px, 4vw, 40px); font-family: system-ui, sans-serif; line-height: 1.6; }
-  #doom-example h1 { margin: 0 0 12px; color: #fff; font-size: clamp(26px, 4vw, 38px); line-height: 1.2; font-weight: 750; }
-  #doom-example p { margin: 12px 0; }
-  #doom-example output { display: block; margin: 12px 0; }
-  #doom-example .description { max-width: 75ch; color: #d7d7e4; }
-  #doom-example .controls { display: flex; flex-wrap: wrap; align-items: center; gap: 12px; margin: 24px 0 12px; }
-  #doom-example button { border: 1px solid #fc946d; border-radius: 10px; background: #f69c76; color: #20130e; padding: 12px 22px; font: inherit; font-weight: 700; cursor: pointer; }
-  #doom-example button:hover { background: #ffb494; }
-  #doom-example button:disabled { cursor: wait; opacity: 0.7; }
-  #doom-example a { color: #b8caff; text-decoration: underline; text-underline-offset: 3px; }
+  html, body, #doom-example, #doom-player { width: 100%; height: 100%; margin: 0; }
+  body { background: #000; color: #f4f4f7; }
+  #doom-example { position: relative; font-family: system-ui, sans-serif; }
+  #doom-player { min-height: 360px; }
+  #doom-status { position: absolute; inset: 0; z-index: 1; padding: 24px; background: #101018; line-height: 1.6; }
   #doom-example :focus-visible { outline: 3px solid #b8caff; outline-offset: 4px; }
-  #doom-example .notice { color: #b9b9cb; font-size: 0.9rem; }
-  #doom-example #doom-player { width: 100%; height: clamp(360px, 65vw, 640px); margin-top: 20px; border: 1px solid #383847; border-radius: 12px; overflow: hidden; background: #000; }
   #doom-example [hidden] { display: none; }
 `;
 
 const SCRIPT = `
 (() => {
-  const button = document.getElementById("doom-load");
   const status = document.getElementById("doom-status");
   const player = document.getElementById("doom-player");
   const baseUrl = ${JSON.stringify(JSDOS_BASE_URL)};
@@ -77,9 +50,7 @@ const SCRIPT = `
     });
   }
 
-  async function startGame() {
-    button.disabled = true;
-    status.textContent = status.dataset.loading;
+  async function loadPlayer() {
     const stylesheet = document.createElement("link");
     stylesheet.rel = "stylesheet";
     stylesheet.href = baseUrl + "js-dos.css";
@@ -88,30 +59,26 @@ const SCRIPT = `
     try {
       await Promise.all([loadResource(stylesheet), loadResource(script)]);
       if (typeof window.Dos !== "function") throw new Error("Player API is unavailable");
-      player.hidden = false;
       game = window.Dos(player, {
         url: bundleUrl,
         pathPrefix: baseUrl + "emulators/",
-        autoStart: true,
+        autoStart: false,
+        kiosk: true,
         mouseCapture: false,
         theme: "dark",
         lang: "en",
-        onEvent(event) {
-          if (event === "ci-ready") status.textContent = status.dataset.ready;
-        },
       });
-      button.hidden = true;
-      player.focus();
+      game.setNoCloud(true);
     } catch (error) {
       stylesheet.remove();
       script.remove();
       status.textContent = status.dataset.error;
-      button.disabled = false;
+      status.hidden = false;
       console.error("DOOM player failed to load", error);
     }
   }
 
-  button.addEventListener("click", startGame);
+  void loadPlayer();
   window.addEventListener("pagehide", () => {
     game?.stop().catch((error) => console.error("DOOM player failed to stop", error));
   }, { once: true });
@@ -131,16 +98,8 @@ function buildDoomHtml(language) {
 </head>
 <body>
   <main id="doom-example">
-    <h1>${copy.title}</h1>
-    <p class="description">${copy.description}</p>
-    <div class="controls">
-      <button id="doom-load" type="button">${copy.play}</button>
-      <a href="https://dos.zone/doom-dec-1993/" target="_blank" rel="noopener noreferrer">${copy.source}</a>
-    </div>
-    <output id="doom-status" data-loading="${copy.loading}" data-ready="${copy.ready}" data-error="${copy.error}"></output>
-    <div id="doom-player" tabindex="-1" aria-label="${copy.player}" hidden></div>
-    <p>${copy.instructions}</p>
-    <p class="notice">${copy.notice}</p>
+    <output id="doom-status" data-error="${copy.error}" hidden></output>
+    <div id="doom-player" tabindex="-1" aria-label="${copy.player}"></div>
   </main>
   <script>${SCRIPT}</script>
 </body>

package/content/operations-en.mjs

@@ -10,8 +10,8 @@ Record the deployed commit, CLI version and workflow revision. Run \`git status
 For a reproducible comparison, invoke the target package explicitly:
 
 \`\`\`sh
-npx --yes @gitpagedocs/cli@0.0.10 version
-npx --yes @gitpagedocs/cli@0.0.10 --no-interactive --owner YOUR_USER --repo YOUR_REPOSITORY --output gitpagedocs-candidate
+npx --yes @gitpagedocs/cli@0.0.11 version
+npx --yes @gitpagedocs/cli@0.0.11 --no-interactive --owner YOUR_USER --repo YOUR_REPOSITORY --output gitpagedocs-candidate
 git diff --no-index -- gitpagedocs gitpagedocs-candidate
 \`\`\`
 

package/content/operations-es.mjs

@@ -10,8 +10,8 @@ Anota el commit publicado, la versión de la CLI y la revisión del workflow. Ej
 Para comparar de forma reproducible, indica el paquete exacto:
 
 \`\`\`sh
-npx --yes @gitpagedocs/cli@0.0.10 version
-npx --yes @gitpagedocs/cli@0.0.10 --no-interactive --owner TU_USUARIO --repo TU_REPOSITORIO --output gitpagedocs-candidate
+npx --yes @gitpagedocs/cli@0.0.11 version
+npx --yes @gitpagedocs/cli@0.0.11 --no-interactive --owner TU_USUARIO --repo TU_REPOSITORIO --output gitpagedocs-candidate
 git diff --no-index -- gitpagedocs gitpagedocs-candidate
 \`\`\`
 
@@ -27,13 +27,13 @@ El formato compacto \`site.icons.defaults\` comparte valores entre iconos, y cad
 
 La apertura de PDF ahora obtiene bytes validados y abre un Blob \`application/pdf\` en otra pestaña. Los servidores externos deben permitir CORS incluso con la vista previa desactivada. Revisa las tres acciones por separado, comprueba el permiso de ventanas emergentes y conserva los errores traducidos. Las preferencias de PDF del navegador siguen aplicándose.
 
-## Valida y publica el resultado revisado
+## Valida y pública el resultado revisado
 
-En este repositorio del runtime, cambia las fuentes de generación antes de compilar: el build vuelve a generar la documentación. Ejecuta \`pnpm run typecheck\`, \`pnpm run lint\`, \`pnpm exec vitest run\`, \`pnpm run smoke:all\` y \`pnpm run build\`. Ejecuta \`pnpm run test:e2e\` con \`PORT=3100\` establecido en el shell. Un repositorio consumidor necesita sus propias comprobaciones equivalentes.
+En este repositorio del runtime, cambia las fuentes de generación antes de compilar: el build vuelve a generar la documentación. Ejecuta \`pnpm run typecheck\`, \`pnpm run lint\`, \`pnpm exec vitest run\`, \`pnpm run smoke:all\` y \`pnpm run build\`. Ejecuta \`pnpm run test:e2e\` con \`PORT=3100\` establecido en el shell. Un repositorio consumidor necesita sus propias comprobaciónes equivalentes.
 
 Prueba todas las versiones e idiomas conservados, enlaces directos, menús anidados, iconos/texto, acciones PDF y autorización. Comprueba la exportación bajo la subruta real de Pages. Crea el commit revisado y envíalo mediante el workflow existente. El comando inicial \`pages deploy\` genera archivos, crea un commit y hace push; no lo repitas sin revisar sobre documentación personalizada.
 
-Registra el commit publicado cuando Actions termine correctamente. Si falla la comprobación, revierte el commit específico con \`git revert COMMIT_DE_ACTUALIZACION\`, restaura la versión anterior del runtime cuando corresponda, envía y ejecuta de nuevo el despliegue. Confirma el contenido restaurado en la URL pública; revertir por sí solo no publica el sitio.
+Registra el commit publicado cuando Actions termine correctamente. Si falla la comprobación, revierte el commit específico con \`git revert COMMIT_DE_ACTUALIZACION\`, restaura la versión anterior del runtime cuando corresponda, envía y ejecuta de nuevo el despliegue. Confirma el contenido restaurado en la URL pública; revertir por sí solo no pública el sitio.
 `,
   troubleshooting: `# Diagnosticar problemas de documentación
 

package/content/operations-pt.mjs

@@ -10,8 +10,8 @@ Anote o commit publicado, a versão da CLI e a revisão do workflow. Execute \`g
 Para uma comparação reproduzível, invoque explicitamente o pacote desejado:
 
 \`\`\`sh
-npx --yes @gitpagedocs/cli@0.0.10 version
-npx --yes @gitpagedocs/cli@0.0.10 --no-interactive --owner SEU_USUARIO --repo SEU_REPOSITORIO --output gitpagedocs-candidate
+npx --yes @gitpagedocs/cli@0.0.11 version
+npx --yes @gitpagedocs/cli@0.0.11 --no-interactive --owner SEU_USUARIO --repo SEU_REPOSITORIO --output gitpagedocs-candidate
 git diff --no-index -- gitpagedocs gitpagedocs-candidate
 \`\`\`
 
@@ -33,7 +33,7 @@ Neste repositório de runtime, altere as fontes de geração antes de compilar:
 
 Teste todas as versões e idiomas preservados, links diretos, menus aninhados, ícones/texto, ações de PDF e autorização. Confira a exportação no subcaminho real do Pages. Faça commit dos arquivos revisados e envie pelo workflow existente. O comando inicial \`pages deploy\` gera arquivos, cria commit e faz push; não o repita sem revisão sobre documentação personalizada.
 
-Registre o commit publicado após o sucesso no Actions. Se a verificação falhar, reverta o commit específico com \`git revert COMMIT_DA_ATUALIZACAO\`, restaure a versão anterior do runtime quando aplicável, envie e execute a publicação novamente. Confirme o conteúdo restaurado na URL pública; o revert sozinho não publica o site.
+Registre o commit publicado após o sucesso no Actions. Se a verificação falhar, reverta o commit específico com \`git revert COMMIT_DA_ATUALIZACAO\`, restaure a versão anterior do runtime quando aplicável, envie e execute a publicação novamente. Confirme o conteúdo restaurado na URL pública; o revert sozinho não pública o site.
 `,
   troubleshooting: `# Diagnosticar problemas na documentação
 

package/content/overviews-en.mjs

@@ -0,0 +1,115 @@
+export const overviewsEn = {
+  guides: `# Guides
+
+Choose a route through the documentation according to what you need to accomplish. This page is also the destination of the Guides menu item: selecting its title opens this document, while its separate arrow expands or collapses the submenus.
+
+## Choose your next step
+
+- **Configure your site** connects root settings, version routes, themes and navigation. Start here when adapting the generated scaffold to your repository.
+- **Read and explore** explains focus mode, browser narration, PDF documents and interactive HTML.
+- **Automate and integrate** covers CLI commands, the MCP server and route authorization.
+
+## Move through a section
+
+Parent entries can contain both a localized \`path-click\` and \`submenus\`. Their children keep their own destinations. The breadcrumb follows the same hierarchy: an ancestor with an available document is clickable, and the current page marks your position. For example, Guides → Configure your site → Configuration lets you return to either overview without losing the menu structure.
+`,
+  configureYourSite: `# Configure your site
+
+Separate site-wide presentation from the content of a documentation version. The root \`gitpagedocs/config.json\` selects languages, themes and reading controls. The version configuration defines routes, their language-specific files and the menu tree.
+
+## Configure in a practical order
+
+1. Read **Configuration** to locate the setting you need and its default.
+2. Use **Configuration recipes** for complete JSON examples and a multilingual starter structure.
+3. Choose **Themes and layouts** for visual tokens and template changes.
+4. Read **Navigation and nested menus** to connect routes, parent documents, submenus and breadcrumbs.
+
+## Check the result
+
+Keep an existing file for every enabled language and menu destination. A title alone does not create a document. Give a parent its own Markdown path when it needs an introduction, and keep its children in \`submenus\`. Validate one language first, then check the others, the flat-menu setting and a direct link to a nested page. Preserve repository-specific configuration when regenerating examples.
+`,
+  readAndExplore: `# Read and explore
+
+Choose a reading surface that matches the document. Markdown supports headings, links and the table of contents; PDF uses the browser's native viewer; HTML can host a trusted interactive demonstration. All remain reachable through the same documentation menu.
+
+## Reading options
+
+- **Focus mode** keeps Markdown in a dialog with copy/download and first, previous, next and last navigation for documents and sections.
+- **Accessibility and narration** explains voice selection, playback controls and browser support.
+- **PDF documents** covers previews, downloads, opening a new tab and external-host CORS requirements.
+- **HTML containers** explains local files, hosted pages and the DOOM example.
+
+## Keep control of playback
+
+Narration starts only when requested. Audible media coordinates with narration through \`site.mediaExclusivePlayback\`; native browser voices and external players depend on their providers. For the HTML game, use its own Play control. Parent documents such as this one also participate in document navigation when their Markdown is available and access is allowed.
+`,
+  automateAndIntegrate: `# Automate and integrate
+
+Use automation for repeatable tasks, with the repository as the source of truth. The CLI generates configuration and documentation files. The MCP server exposes project operations to an MCP client. Route authorization governs the viewer's access experience.
+
+## Select the appropriate interface
+
+- **CLI reference** lists installation, commands, flags and which operations write or publish files.
+- **MCP server** describes stdio setup, every tool and resource, provider variables and filesystem boundaries.
+- **Authorized routes** explains keys, roles and external identity providers.
+
+## Review before publishing
+
+Keep credentials in the intended environment or credential storage, never in generated configuration. Inspect changed files before committing and validate paths for the selected version and language. Public static files remain accessible from their hosting URLs even when the menu hides them. Start with informational commands and explicit output directories when comparing a generated candidate with an existing site.
+`,
+  operationsAndDevelopment: `# Operations and development
+
+Maintaining a documentation site involves both its published content and the runtime that displays it. Choose the branch below that matches the change; a content update does not always require changing the frontend, and a viewer fix should not rewrite historical documents unnecessarily.
+
+## Two paths through the project
+
+- **Ship and maintain** groups deployment, migration, troubleshooting and frequently asked questions. Use it to prepare an upgrade or investigate a published-site failure.
+- **Develop the project** groups architecture, contributing/testing and feature references. Use it to locate the correct source module and its validation boundary.
+
+## Keep releases traceable
+
+Record the intended version, review generated changes and preserve documents used by existing links. Validate local behavior and the deployed base path separately. When an external player, browser voice or hosting policy changes, distinguish that dependency from repository behavior before modifying the implementation. The child guides provide the concrete commands and checks for each task.
+`,
+  shipAndMaintain: `# Ship and maintain
+
+Treat publication as a verified change to a specific version. Build and inspect the site before relying on a successful workflow status; a deployed page can still reference the wrong path or an unavailable external resource.
+
+## Before and after deployment
+
+1. Read **Deployment** for local runtime, GitHub Pages paths and workflow setup.
+2. Use **Migration and compatibility** to compare an upgrade while preserving custom content and supported historical configuration.
+3. Follow **Troubleshooting** when a document, PDF, narration control or integration behaves differently across environments.
+4. Check **FAQ** for concise answers to common configuration questions.
+
+## Verify a useful sample
+
+Open a nested Markdown page directly, switch languages, follow its breadcrumb and test enabled PDF actions. Confirm the deployed commit and package version. Keep a recoverable commit for upgrades and verify the public URL after a rollback. Do not regenerate a customized repository merely to retry a failed deployment without first reviewing what the generator will replace.
+`,
+  developTheProject: `# Develop the project
+
+Start with the module that owns the behavior you want to change. The frontend uses Feature-Sliced Design; the CLI owns scaffold templates; shared tools provide configuration and documentation services; the MCP package exposes those services through its protocol.
+
+## Locate the source and test boundary
+
+- **Architecture** maps packages, responsibilities and data flow.
+- **Contributing and testing** identifies authoritative templates, generated outputs and the validation commands.
+- **Functionalities** provides a broad reference for existing capabilities and configuration.
+
+## Make a reviewable change
+
+Describe the observable behavior, reproduce it through a public interface and update the source before regenerating artifacts. Keep tests about rendered controls, returned configuration or written files instead of private helpers. Review translations and accessibility when changing a user-facing control. Run the checks appropriate to the affected packages, then inspect the generated diff before committing. Existing version directories should remain intact unless the change explicitly requires updating their content.
+`,
+  gitAndGitHub: `# Git and GitHub
+
+Version control connects the documentation files, review history and deployment workflow. These examples introduce the repository practices used throughout the project; they complement the GitPageDocs configuration guides rather than replace them.
+
+## Start with the appropriate guide
+
+- **Introduction to Git** explains commits, branches and the basic collaboration model, with an accompanying video example.
+- **GitHub Issues and Projects** shows how to record work and organize its progress.
+
+## Apply the workflow to documentation
+
+Keep related source and generated changes together in a reviewed commit. Use a branch for a configuration migration, inspect differences before publishing and record the commit deployed by Actions. Describe a documentation defect with its version, language, URL and expected result so another contributor can reproduce it. Before sharing logs or examples, remove credentials and private content; a public repository and its Pages site expose committed files.
+`,
+};

package/content/overviews-es.mjs

@@ -0,0 +1,115 @@
+export const overviewsEs = {
+  guides: `# Guías
+
+Elige un recorrido por la documentación según lo que necesites hacer. Esta página también es el destino del elemento Guías: pulsar su título abre el documento; la flecha separada expande o contrae los submenús.
+
+## Elige el siguiente paso
+
+- **Configura tu sitio** conecta ajustes globales, rutas de versión, temas y navegación. Empieza aquí para adaptar el scaffold a tu repositorio.
+- **Lee y explora** explica modo foco, narración del navegador, documentos PDF y HTML interactivo.
+- **Automatiza e integra** reúne comandos CLI, servidor MCP y autorización de rutas.
+
+## Recorre una sección
+
+Un elemento padre puede tener \`path-click\` traducido y \`submenus\` a la vez. Sus hijos conservan destinos propios. El breadcrumb sigue la misma jerarquía: un ancestro con documento disponible es navegable y la página actual indica tu posición. Por ejemplo, Guías → Configura tu sitio → Configuración permite volver a cualquier introducción sin perder la estructura del menú.
+`,
+  configureYourSite: `# Configura tu sitio
+
+Separa la presentación global del contenido de cada versión. El archivo raíz \`gitpagedocs/config.json\` selecciona idiomas, temas y controles de lectura. La configuración de la versión define rutas, archivos por idioma y el árbol de menús.
+
+## Configura en un orden práctico
+
+1. Lee **Configuración** para localizar el ajuste y su valor predeterminado.
+2. Usa **Recetas de configuración** para ejemplos JSON completos y una estructura multilingüe inicial.
+3. Elige **Temas y diseños** para tokens visuales y cambios de plantillas.
+4. Lee **Navegación y submenús** para conectar rutas, documentos de los padres, submenús y breadcrumbs.
+
+## Comprueba el resultado
+
+Mantén un archivo existente para cada idioma habilitado y destino. Un título por sí solo no crea un documento. Asigna al padre su propia ruta Markdown cuando necesite una introducción y conserva sus hijos en \`submenus\`. Valida primero un idioma; después comprueba los demás, el menú plano y un enlace directo a una página anidada. Conserva los ajustes propios del repositorio al regenerar ejemplos.
+`,
+  readAndExplore: `# Lee y explora
+
+Elige una forma de lectura adecuada al documento. Markdown ofrece encabezados, enlaces e índice; PDF utiliza el visor nativo; HTML puede alojar una demostración interactiva de confianza. Todos siguen accesibles desde el mismo menú.
+
+## Opciones de lectura
+
+- **Modo foco** mantiene Markdown en un diálogo con copia/descarga y navegación al primer, anterior, siguiente y último documento o sección.
+- **Accesibilidad y narración** explica voces, controles y compatibilidad del navegador.
+- **Documentos PDF** cubre vista previa, descarga, nueva pestaña y requisitos CORS del alojamiento externo.
+- **Contenedores HTML** explica archivos locales, páginas alojadas y el ejemplo DOOM.
+
+## Controla la reproducción
+
+La narración comienza solo cuando se solicita. El contenido audible se coordina mediante \`site.mediaExclusivePlayback\`; voces nativas y reproductores externos dependen de sus proveedores. En el juego HTML, usa el control Play del reproductor. Los documentos de elementos padre, como este, también participan en la navegación entre documentos cuando su Markdown está disponible y el acceso está permitido.
+`,
+  automateAndIntegrate: `# Automatiza e integra
+
+Usa automatización para tareas repetibles, manteniendo el repositorio como fuente de verdad. La CLI genera configuración y documentación. El servidor MCP ofrece operaciones del proyecto a un cliente MCP. La autorización de rutas gobierna la experiencia de acceso del visor.
+
+## Elige la interfaz adecuada
+
+- **Referencia de la CLI** enumera instalación, comandos, opciones y operaciones que escriben o publican archivos.
+- **Servidor MCP** describe stdio, todas las tools y resources, variables de proveedores y límites del sistema de archivos.
+- **Rutas autorizadas** explica claves, roles y proveedores externos de identidad.
+
+## Revisa antes de publicar
+
+Mantén credenciales en el entorno o almacenamiento apropiado, nunca en configuración generada. Inspecciona los cambios antes del commit y valida rutas de la versión e idioma elegidos. Los archivos estáticos públicos siguen accesibles por sus URLs aunque el menú los oculte. Empieza por comandos informativos y directorios de salida explícitos al comparar una generación candidata con un sitio existente.
+`,
+  operationsAndDevelopment: `# Operación y desarrollo
+
+Mantener un sitio de documentación implica su contenido publicado y el runtime que lo muestra. Elige el recorrido relacionado con el cambio: actualizar contenido no siempre requiere modificar el frontend, y corregir el visor no debería reescribir documentos históricos sin necesidad.
+
+## Dos recorridos por el proyecto
+
+- **Pública y mantén** agrupa publicación, migración, diagnóstico y preguntas frecuentes. Úsalo para preparar una actualización o investigar un fallo publicado.
+- **Desarrolla el proyecto** agrupa arquitectura, contribución/pruebas y funcionalidades. Úsalo para localizar la fuente y la frontera de validación.
+
+## Mantén publicaciones rastreables
+
+Registra la versión prevista, revisa archivos generados y conserva documentos usados por enlaces existentes. Valida por separado el comportamiento local y la ruta publicada. Cuando cambie un reproductor externo, una voz o una política de alojamiento, distingue esa dependencia del comportamiento del repositorio antes de modificar la implementación. Las guías hijas ofrecen comandos y comprobaciónes concretos para cada tarea.
+`,
+  shipAndMaintain: `# Pública y mantén
+
+Trata la publicación como un cambio validado de una versión concreta. Genera e inspecciona el sitio antes de confiar únicamente en el éxito del workflow: una página publicada aún puede apuntar a una ruta incorrecta o a un recurso externo no disponible.
+
+## Antes y después de publicar
+
+1. Lee **Publicación** para ejecución local, rutas de GitHub Pages y configuración del workflow.
+2. Usa **Migración y compatibilidad** para comparar actualizaciones conservando contenido propio y configuración histórica compatible.
+3. Sigue **Solución de problemas** cuando documentos, PDF, narración o integraciones varíen entre entornos.
+4. Consulta **Preguntas frecuentes** para respuestas breves sobre ajustes habituales.
+
+## Verifica una muestra útil
+
+Abre directamente una página Markdown anidada, cambia el idioma, sigue su breadcrumb y prueba las acciones PDF habilitadas. Confirma el commit publicado y la versión del paquete. Conserva un commit recuperable para actualizaciones y verifica la URL pública después de un rollback. No regeneres un repositorio personalizado solo para repetir un despliegue sin revisar qué se sustituirá.
+`,
+  developTheProject: `# Desarrolla el proyecto
+
+Empieza por el módulo responsable del comportamiento que quieres cambiar. El frontend sigue Feature-Sliced Design; la CLI contiene las plantillas del scaffold; tools proporciona servicios compartidos de configuración y documentación; MCP expone esos servicios mediante su protocolo.
+
+## Localiza la fuente y la frontera de prueba
+
+- **Arquitectura** describe paquetes, responsabilidades y flujo de datos.
+- **Contribución y pruebas** identifica plantillas fuente, salidas generadas y comandos de validación.
+- **Funcionalidades** ofrece una referencia amplia de capacidades y ajustes existentes.
+
+## Produce un cambio revisable
+
+Describe el comportamiento observable, reprodúcelo mediante la interfaz pública y actualiza la fuente antes de generar artefactos. Prueba controles renderizados, configuraciones devueltas o archivos escritos, en lugar de helpers privados. Revisa traducciones y accesibilidad al cambiar controles visibles. Ejecuta las comprobaciónes de los paquetes afectados e inspecciona el diff generado antes del commit. Conserva directorios de versiones existentes salvo que el cambio requiera explícitamente actualizar su contenido.
+`,
+  gitAndGitHub: `# Git y GitHub
+
+El control de versiones conecta archivos de documentación, historial de revisión y despliegue. Estos ejemplos presentan prácticas del repositorio usadas en el proyecto y complementan las guías de configuración de GitPageDocs.
+
+## Empieza por la guía adecuada
+
+- **Introducción a Git** explica commits, branches y colaboración básica, con un ejemplo de vídeo.
+- **GitHub Issues y Projects** muestra cómo registrar trabajo y organizar su avance.
+
+## Aplica el flujo a la documentación
+
+Mantén cambios relacionados de fuente y archivos generados en el mismo commit revisado. Usa una branch para migrar configuración, inspecciona diferencias antes de publicar y registra el commit desplegado por Actions. Describe un defecto con versión, idioma, URL y resultado esperado para que otro colaborador pueda reproducirlo. Antes de compartir logs o ejemplos, elimina credenciales y contenido privado: un repositorio público y su sitio Pages exponen los archivos versionados.
+`,
+};

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

@@ -3,7 +3,7 @@ import { HTML_ROUTE_JSON, RECIPE_ROOT_JSON, RECIPE_VERSION_JSON } from "./config
 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, with a localized title, description and a button that loads the external game player only when the visitor chooses to play. The game remains hosted by its provider; the npm package contains the HTML wrapper, not the game assets.
+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
 
@@ -13,7 +13,7 @@ Add this route to the version configuration's existing \`routes-html\` array. Ke
 ${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.10/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.
+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
 
@@ -25,7 +25,7 @@ The external host can prevent framing through CSP or X-Frame-Options. Known bloc
 
 ## Use and maintain the game example
 
-Select the HTML menu entry, read the provider notice and press the localized load button. Network access is needed; then follow the player's own start and keyboard controls. The wrapper includes a direct provider link if embedding fails. Test keyboard focus, small screens, fullscreen and returning to the documentation. Third-party player availability and browser capabilities can change independently of GitPageDocs.
+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.
 `,
@@ -35,7 +35,9 @@ This guide builds a small multilingual documentation site with two Markdown page
 
 ## 1. Generate and inspect the scaffold
 
-Run \`npx --yes @gitpagedocs/cli@0.0.10 --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.
+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.