@gitpagedocs/cli 0.0.9 → 0.0.11

package/content/html-doom.mjs

@@ -0,0 +1,114 @@
+const JSDOS_BASE_URL = "https://v8.js-dos.com/latest/";
+const DOOM_BUNDLE_URL = "https://v8.js-dos.com/bundles/doom.jsdos";
+
+const COPY = {
+  en: {
+    title: "DOOM in an HTML container",
+    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: "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: "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",
+  },
+};
+
+const STYLE = `
+  :root { color-scheme: dark; }
+  * { box-sizing: border-box; }
+  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 [hidden] { display: none; }
+`;
+
+const SCRIPT = `
+(() => {
+  const status = document.getElementById("doom-status");
+  const player = document.getElementById("doom-player");
+  const baseUrl = ${JSON.stringify(JSDOS_BASE_URL)};
+  const bundleUrl = ${JSON.stringify(DOOM_BUNDLE_URL)};
+  let game;
+
+  function loadResource(element) {
+    return new Promise((resolve, reject) => {
+      element.addEventListener("load", resolve, { once: true });
+      element.addEventListener("error", () => reject(new Error("Player resource could not load")), { once: true });
+      document.head.append(element);
+    });
+  }
+
+  async function loadPlayer() {
+    const stylesheet = document.createElement("link");
+    stylesheet.rel = "stylesheet";
+    stylesheet.href = baseUrl + "js-dos.css";
+    const script = document.createElement("script");
+    script.src = baseUrl + "js-dos.js";
+    try {
+      await Promise.all([loadResource(stylesheet), loadResource(script)]);
+      if (typeof window.Dos !== "function") throw new Error("Player API is unavailable");
+      game = window.Dos(player, {
+        url: bundleUrl,
+        pathPrefix: baseUrl + "emulators/",
+        autoStart: false,
+        kiosk: true,
+        mouseCapture: false,
+        theme: "dark",
+        lang: "en",
+      });
+      game.setNoCloud(true);
+    } catch (error) {
+      stylesheet.remove();
+      script.remove();
+      status.textContent = status.dataset.error;
+      status.hidden = false;
+      console.error("DOOM player failed to load", error);
+    }
+  }
+
+  void loadPlayer();
+  window.addEventListener("pagehide", () => {
+    game?.stop().catch((error) => console.error("DOOM player failed to stop", error));
+  }, { once: true });
+})();
+`;
+
+function buildDoomHtml(language) {
+  const copy = COPY[language];
+  return `<!doctype html>
+<html lang="${language}">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <meta name="description" content="${copy.description}">
+  <title>${copy.title}</title>
+  <style>${STYLE}</style>
+</head>
+<body>
+  <main id="doom-example">
+    <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>
+</html>
+`;
+}
+
+export const HTML_DOOM = {
+  en: buildDoomHtml("en"),
+  pt: buildDoomHtml("pt"),
+  es: buildDoomHtml("es"),
+};

package/content/operations-en.mjs

@@ -0,0 +1,70 @@
+export const operationsEn = {
+  migration: `# Migrating an existing documentation site
+
+GitPageDocs supports configurations and data from the official 0.0.1 release onward. Earlier experimental formats numbered 1.1.x are outside that compatibility contract. A package upgrade and a documentation rewrite are different operations: the generator does not automatically merge your custom pages, routes, translations or themes.
+
+## Save a recoverable starting point
+
+Record the deployed commit, CLI version and workflow revision. Run \`git status --short\`, review pending changes and save the intended source files in a dedicated commit. Keep a separate backup of untracked documentation and custom assets; never add credentials merely to complete the backup. Create a working branch with \`git switch -c docs/upgrade-0.0.10\`.
+
+For a reproducible comparison, invoke the target package explicitly:
+
+\`\`\`sh
+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
+\`\`\`
+
+The last command returns exit code 1 when differences exist; that is expected. The candidate is review material, not an automatically selected live site. Generated configuration still describes canonical \`gitpagedocs/\` paths. Do not publish the candidate as though changing the output directory also changes every runtime path.
+
+## Merge the configuration deliberately
+
+Preserve \`gitpagedocs/config.json\` site identity, deployment settings and \`VersionControl.versions\` entries. Each version points to its own \`docs/versions/<version>/config.json\`; keep those files, their document IDs, route paths and menu destinations aligned. Retain historical version directories needed by existing links. Route arrays are content, not defaults that the viewer reconstructs.
+
+Copy only the new settings you want. Version \`routeDefaults\` supplies shared route settings; an explicit route field overrides its default. Keep per-language Markdown, PDFs and \`gitpagedocs/langs/<language>.json\` bundles. The root \`site.languages\` switches available languages; enabling a language does not create translated documents.
+
+Compact \`site.icons.defaults\` shares icon values, and each named entry can override them. Existing flat \`Icon*ReactIcones\` fields take precedence over compact entries. Remove conflicting duplicates only after confirming their intended effect. Version 0.0.10 defaults LanguageSelector, ThemeSelector, FocusMode, QuickNavigation, PdfDownload, PdfOpenInNewTab, DocumentPrevious and DocumentNext to icons; set an entry's \`reactIcon: false\` to retain text.
+
+PDF opening now fetches validated bytes and opens an \`application/pdf\` Blob in a new tab. External hosting must allow CORS even when preview is disabled. Review the three PDF action switches independently, test popup permissions and preserve translated error labels. Browser PDF preferences still apply.
+
+## Validate and publish the reviewed result
+
+In this runtime repository, edit generation sources before rebuilding: builds regenerate documentation. Run \`pnpm run typecheck\`, \`pnpm run lint\`, \`pnpm exec vitest run\`, \`pnpm run smoke:all\` and \`pnpm run build\`. Run \`pnpm run test:e2e\` with \`PORT=3100\` set in your shell. A consuming repository needs its own equivalent checks.
+
+Test every retained version and language, direct links, nested menus, text/icon settings, PDF actions and authorization behavior. Check the export under the actual Pages subpath. Commit the reviewed files, then push through the existing deployment workflow. Initial \`pages deploy\` scaffolds, commits and pushes; do not rerun it casually over customized documentation.
+
+Record the deployed commit after a successful Actions run. If verification fails, revert the dedicated upgrade commit with \`git revert UPGRADE_COMMIT\`, restore the previous runtime pin when applicable, push and rerun the deployment. Confirm the public URL serves the restored version; a successful revert alone does not publish it.
+`,
+  troubleshooting: `# Troubleshooting a documentation site
+
+Start with one failing URL, its selected version and language, the expected result and the actual result. Record the deployed commit and \`gitpagedocs version\`. Run \`gitpagedocs doctor\` from the repository root to check tools and configuration discovery. Doctor does not validate every document or prove that a deployment is healthy.
+
+## Choose the failing environment
+
+- **Local only:** confirm the working directory contains \`gitpagedocs/config.json\`. Check the dev server output and its actual port. Restart after changing build-time configuration. A local file existing elsewhere on disk does not make it a public web asset.
+- **Pages only:** inspect the latest Deploy GitPageDocs Actions run and published commit. Compare failed network requests with the expected repository subpath. HTML loading while CSS or JavaScript returns 404 usually warrants checking the build path before changing content.
+- **Remote repository only:** confirm the target repository is reachable, its selected branch contains the documentation root and referenced files are committed. Repository-search mode requires \`GITPAGEDOCS_REPOSITORY_SEARCH=true\` locally. Test the same repository directly before debugging a different site's viewer.
+
+For a custom mount, inspect \`GITPAGEDOCS_PATH\`, \`GITPAGEDOCS_BASE_PATH\` and the generated workflow together. Next.js embeds the base path during the build; changing an environment variable on an already exported folder does not rewrite its bundles. After a fresh deployment, try a hard reload or private window to distinguish stale browser resources from a server-side 404.
+
+## Trace a document from configuration to bytes
+
+Follow \`VersionControl.versions[*].path\` to the version config, then the route's language-specific path. Check spelling and letter case against the tracked file; deployment hosts may distinguish case even when your workstation does not. A menu label does not create a route. Use a valid destination and check that its authorization rules allow the current reader.
+
+Confirm \`site.languages\`, the UI bundle in \`langs/\` and the document language mapping separately. PDF paths have no automatic language fallback. Preserve UTF-8 in JSON and Markdown, including \`site.name\` and accented titles. Compare actual saved text with the browser and terminal output before diagnosing an encoding bug; fonts and display contexts can also differ. English filenames are a project convention, not a restriction on accents in content. Do not remove accents to hide corrupted bytes.
+
+## Diagnose PDF and reading controls
+
+Inspect the PDF fetch status and response body. The file must begin with \`%PDF-\`; an HTML login screen or repository preview page is not a PDF even with status 200. Preview, download and new-tab opening all need CORS permission for external origins. A local download succeeding outside the browser does not prove browser access is allowed.
+
+Allow popups for the site and retry the explicit open button. The viewer opens validated Blob bytes, so attachment headers from raw hosting do not directly control that new URL. Native PDF support and browser download preferences still vary. Check site and route action switches before treating a deliberately hidden control as a loading error.
+
+For silent narration, check browser speech support, available voices, selected language, volume and system output. Voices can arrive asynchronously or depend on a remote service. Starting other audible media stops narration when \`mediaExclusivePlayback\` is enabled. Document or language navigation cancels the previous speech.
+
+## Separate access and process problems
+
+Hidden menus and client-side authorization do not protect public files on a static host. Verify confidential content's actual hosting permissions; changing UI roles cannot secure an exposed PDF URL.
+
+An MCP process waiting on \`gitpagedocs mcp start\` is normal: it speaks stdio to a client, not an interactive terminal. Confirm its working directory, executable and inherited environment. Provider credentials must exist in that process; the CLI vault and \`.env\` are not loaded automatically. Keep stdout for protocol messages, inspect stderr and tool \`isError\` results, and share diagnostic excerpts without secrets.
+`,
+};

package/content/operations-es.mjs

@@ -0,0 +1,70 @@
+export const operationsEs = {
+  migration: `# Migrar una documentación existente
+
+GitPageDocs mantiene compatibilidad con configuraciones y datos desde la versión oficial 0.0.1. Los formatos experimentales anteriores, numerados 1.1.x, quedan fuera de ese contrato. Actualizar el paquete y reescribir la documentación son operaciones distintas: el generador no combina automáticamente páginas, rutas, traducciones ni temas personalizados.
+
+## Guarda un punto de recuperación
+
+Anota el commit publicado, la versión de la CLI y la revisión del workflow. Ejecuta \`git status --short\`, revisa los cambios pendientes y guarda los archivos de origen deseados en un commit específico. Conserva otra copia de los documentos y recursos personalizados todavía sin seguimiento; no añadas credenciales para completar la copia. Crea una rama con \`git switch -c docs/upgrade-0.0.10\`.
+
+Para comparar de forma reproducible, indica el paquete exacto:
+
+\`\`\`sh
+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
+\`\`\`
+
+El último comando devuelve código 1 cuando encuentra diferencias; es normal. La carpeta candidata sirve para revisar y no se convierte automáticamente en el sitio activo. La configuración generada sigue describiendo rutas canónicas en \`gitpagedocs/\`. Cambiar la carpeta de salida no equivale a modificar todas las rutas utilizadas por el visor.
+
+## Combina la configuración deliberadamente
+
+Conserva la identidad del sitio, las opciones de despliegue y las entradas de \`VersionControl.versions\` en \`gitpagedocs/config.json\`. Cada versión apunta a su propio \`docs/versions/<version>/config.json\`; mantén coherentes los archivos, identificadores de documentos, rutas y destinos de menús. Conserva las versiones históricas necesarias para los enlaces existentes. Los arrays de rutas son contenido, no valores predeterminados reconstruidos por el visor.
+
+Copia solamente las opciones nuevas que necesites. El \`routeDefaults\` de cada versión proporciona opciones comunes; un campo explícito de una ruta prevalece sobre ese valor. Conserva Markdown, PDF y los paquetes \`gitpagedocs/langs/<idioma>.json\` de cada idioma. La opción \`site.languages\` habilita idiomas en la interfaz, pero no traduce los documentos.
+
+El formato compacto \`site.icons.defaults\` comparte valores entre iconos, y cada entrada puede sobrescribirlos. Los campos planos \`Icon*ReactIcones\` existentes tienen prioridad sobre las entradas compactas. Elimina duplicados contradictorios después de comprobar el resultado deseado. En 0.0.10, LanguageSelector, ThemeSelector, FocusMode, QuickNavigation, PdfDownload, PdfOpenInNewTab, DocumentPrevious y DocumentNext usan iconos por defecto; configura \`reactIcon: false\` en una entrada para conservar texto.
+
+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 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 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 pública el sitio.
+`,
+  troubleshooting: `# Diagnosticar problemas de documentación
+
+Empieza con una URL que falla, su versión e idioma, el resultado esperado y el observado. Registra el commit publicado y la salida de \`gitpagedocs version\`. Ejecuta \`gitpagedocs doctor\` desde la raíz del repositorio para comprobar herramientas y descubrimiento de configuración. Doctor no valida cada documento ni demuestra que el despliegue funcione correctamente.
+
+## Identifica el entorno afectado
+
+- **Solo local:** confirma que el directorio actual contiene \`gitpagedocs/config.json\`. Revisa la salida del servidor y su puerto real. Reinicia después de modificar opciones usadas durante el build. Un archivo situado en otra carpeta del equipo no se convierte en un recurso web público.
+- **Solo Pages:** inspecciona la última ejecución de Deploy GitPageDocs en Actions y el commit publicado. Compara las peticiones fallidas con la subruta esperada del repositorio. Si el HTML carga, pero CSS o JavaScript devuelven 404, comprueba primero la ruta del build.
+- **Solo repositorio remoto:** confirma que el repositorio sea accesible, que su rama contenga la documentación y que los archivos estén enviados a Git. Localmente, buscar repositorios requiere \`GITPAGEDOCS_REPOSITORY_SEARCH=true\`. Prueba el mismo repositorio directamente antes de investigar otro visor.
+
+Para publicar bajo una subcarpeta, revisa conjuntamente \`GITPAGEDOCS_PATH\`, \`GITPAGEDOCS_BASE_PATH\` y el workflow generado. Next.js incorpora la ruta base durante el build; cambiar una variable después de exportar no reescribe los bundles. Tras publicar otra vez, recarga completamente o prueba una ventana privada para distinguir recursos antiguos del navegador de un 404 del servidor.
+
+## Sigue la configuración hasta el archivo
+
+Sigue \`VersionControl.versions[*].path\` hasta la configuración de versión y después la ruta del idioma seleccionado. Compara escritura y mayúsculas con el archivo rastreado; el servidor puede distinguir mayúsculas aunque tu equipo no lo haga. Un título de menú no crea una ruta. Comprueba el destino y que sus reglas permitan el acceso al lector actual.
+
+Verifica por separado \`site.languages\`, el paquete de interfaz en \`langs/\` y el mapa de idiomas del documento. Los PDF no tienen un idioma alternativo automático. Conserva UTF-8 en JSON y Markdown, incluyendo \`site.name\` y títulos acentuados. Compara el texto guardado con el navegador y el terminal antes de diagnosticar un problema de codificación; las fuentes y los contextos de visualización también pueden diferir. Los nombres ingleses de archivos son una convención, no una prohibición de tildes en el contenido. No elimines acentos para ocultar bytes dañados.
+
+## Investiga PDF y controles de lectura
+
+Inspecciona el estado de la petición PDF y el cuerpo recibido. El archivo debe comenzar con \`%PDF-\`; una página HTML de acceso o vista del repositorio no es PDF, incluso con estado 200. Vista previa, descarga y nueva pestaña necesitan permiso CORS para orígenes externos. Descargar fuera del navegador no demuestra que el navegador tenga acceso.
+
+Permite ventanas emergentes para el sitio y vuelve a pulsar el botón de apertura. El visor abre bytes validados mediante Blob; las cabeceras de descarga del alojamiento original no controlan directamente esa URL nueva. El soporte nativo y las preferencias del navegador varían. Revisa las opciones del sitio y de la ruta antes de considerar un control desactivado como un fallo de carga.
+
+Si la narración no suena, comprueba soporte de voz, voces disponibles, idioma, volumen y salida de audio. Las voces pueden aparecer después de cargar o depender de un servicio remoto. Otra fuente audible interrumpe la narración cuando \`mediaExclusivePlayback\` está habilitado. Cambiar de documento o idioma cancela la lectura anterior.
+
+## Separa acceso y procesos
+
+Ocultar menús y autorizar en el navegador no protege archivos públicos en alojamiento estático. Comprueba los permisos reales del alojamiento confidencial; cambiar roles visuales no protege una URL PDF expuesta.
+
+Que \`gitpagedocs mcp start\` espere es normal: habla por stdio con un cliente, no con un terminal interactivo. Comprueba directorio, ejecutable y entorno heredado. Las credenciales deben existir en ese proceso; el almacén de la CLI y \`.env\` no se cargan automáticamente. Reserva stdout al protocolo, revisa stderr y resultados \`isError\`, y comparte diagnósticos sin secretos.
+`,
+};

package/content/operations-pt.mjs

@@ -0,0 +1,70 @@
+export const operationsPt = {
+  migration: `# Migrar uma documentação existente
+
+O GitPageDocs oferece compatibilidade com configurações e dados desde a versão oficial 0.0.1. Os formatos experimentais anteriores, numerados 1.1.x, estão fora desse contrato. Atualizar o pacote e reescrever a documentação são operações diferentes: o gerador não combina automaticamente suas páginas, rotas, traduções ou temas personalizados.
+
+## Salve um ponto de recuperação
+
+Anote o commit publicado, a versão da CLI e a revisão do workflow. Execute \`git status --short\`, revise alterações pendentes e salve os arquivos de origem desejados em um commit específico. Guarde também uma cópia dos documentos e recursos personalizados ainda não rastreados; não adicione credenciais apenas para completar o backup. Crie uma branch com \`git switch -c docs/upgrade-0.0.10\`.
+
+Para uma comparação reproduzível, invoque explicitamente o pacote desejado:
+
+\`\`\`sh
+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
+\`\`\`
+
+O último comando retorna código 1 quando existem diferenças; isso é esperado. A pasta candidata serve para revisão e não se torna o site ativo automaticamente. As configurações geradas ainda descrevem caminhos canônicos em \`gitpagedocs/\`. Alterar a pasta de saída não significa reescrever todos os caminhos usados pelo visualizador.
+
+## Combine as configurações com cuidado
+
+Preserve a identidade do site, as opções de publicação e as entradas de \`VersionControl.versions\` em \`gitpagedocs/config.json\`. Cada versão aponta para seu próprio \`docs/versions/<version>/config.json\`; mantenha os arquivos, IDs de documentos, caminhos de rotas e destinos de menus consistentes. Conserve as versões históricas necessárias aos links existentes. Arrays de rotas são conteúdo e não padrões reconstruídos pelo visualizador.
+
+Copie somente as novas opções desejadas. O \`routeDefaults\` da versão fornece configurações comuns; um campo explícito na rota prevalece sobre esse padrão. Preserve Markdown, PDFs e os pacotes \`gitpagedocs/langs/<idioma>.json\` de cada idioma. A opção \`site.languages\` habilita idiomas na interface, mas não cria traduções dos documentos.
+
+O formato compacto \`site.icons.defaults\` compartilha valores entre ícones, e cada entrada pode sobrescrevê-los. Campos planos \`Icon*ReactIcones\` existentes prevalecem sobre as entradas compactas. Remova duplicatas conflitantes apenas depois de confirmar o efeito desejado. Na versão 0.0.10, LanguageSelector, ThemeSelector, FocusMode, QuickNavigation, PdfDownload, PdfOpenInNewTab, DocumentPrevious e DocumentNext usam ícones por padrão; defina \`reactIcon: false\` na entrada para manter texto.
+
+A abertura de PDF agora busca bytes validados e abre um Blob \`application/pdf\` em nova guia. Servidores externos precisam permitir CORS mesmo com a prévia desativada. Revise separadamente as três ações de PDF, teste a permissão de popups e preserve as mensagens traduzidas. As preferências do navegador para PDFs continuam valendo.
+
+## Valide e publique o resultado revisado
+
+Neste repositório de runtime, altere as fontes de geração antes de compilar: o build gera a documentação novamente. Execute \`pnpm run typecheck\`, \`pnpm run lint\`, \`pnpm exec vitest run\`, \`pnpm run smoke:all\` e \`pnpm run build\`. Execute \`pnpm run test:e2e\` com \`PORT=3100\` definido no shell. Um repositório consumidor precisa de verificações equivalentes próprias.
+
+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 pública o site.
+`,
+  troubleshooting: `# Diagnosticar problemas na documentação
+
+Comece com uma URL que falha, a versão e o idioma selecionados, o resultado esperado e o observado. Registre o commit publicado e a saída de \`gitpagedocs version\`. Execute \`gitpagedocs doctor\` na raiz do repositório para verificar ferramentas e descoberta da configuração. O doctor não valida cada documento nem comprova o funcionamento da publicação.
+
+## Identifique o ambiente afetado
+
+- **Somente local:** confirme que o diretório atual contém \`gitpagedocs/config.json\`. Confira a saída do servidor e a porta utilizada. Reinicie após mudar configurações usadas no build. Um arquivo presente em outra pasta do computador não se torna um recurso web público.
+- **Somente Pages:** confira a execução mais recente de Deploy GitPageDocs no Actions e o commit publicado. Compare requisições que falham com o subcaminho esperado do repositório. Se o HTML abre, mas CSS ou JavaScript retornam 404, verifique o caminho do build antes de alterar o conteúdo.
+- **Somente repositório remoto:** confirme o acesso ao repositório, a pasta de documentação na branch consultada e os arquivos enviados ao Git. Localmente, a busca de repositórios exige \`GITPAGEDOCS_REPOSITORY_SEARCH=true\`. Teste o mesmo repositório diretamente antes de investigar outro visualizador.
+
+Para publicação em subpasta, confira \`GITPAGEDOCS_PATH\`, \`GITPAGEDOCS_BASE_PATH\` e o workflow gerado em conjunto. O Next.js incorpora o caminho base durante o build; mudar uma variável depois da exportação não reescreve os bundles. Após publicar novamente, faça uma recarga completa ou use uma janela privada para distinguir cache antigo de um 404 do servidor.
+
+## Siga a configuração até o arquivo
+
+Siga \`VersionControl.versions[*].path\` até a configuração da versão e depois o caminho da rota no idioma escolhido. Compare a grafia e as letras maiúsculas com o arquivo rastreado; o servidor pode diferenciar maiúsculas mesmo quando sua máquina não diferencia. Um título de menu não cria uma rota. Verifique o destino e se a autorização permite acesso ao leitor atual.
+
+Confira separadamente \`site.languages\`, o pacote da interface em \`langs/\` e o mapa de idiomas do documento. PDFs não têm fallback automático de idioma. Preserve UTF-8 no JSON e no Markdown, incluindo \`site.name\` e títulos acentuados. Compare o texto salvo com o navegador e o terminal antes de diagnosticar um defeito de codificação; fontes e contextos de exibição também podem diferir. Nomes de arquivos em inglês são convenção, não uma restrição aos acentos no conteúdo. Não remova acentos para esconder bytes corrompidos.
+
+## Investigue PDFs e controles de leitura
+
+Confira o status da requisição e o corpo retornado pelo PDF. O arquivo deve começar com \`%PDF-\`; uma tela HTML de login ou prévia do repositório não é PDF, mesmo com status 200. Prévia, download e nova guia exigem permissão CORS para origens externas. Baixar fora do navegador não comprova que o navegador tenha acesso.
+
+Permita popups para o site e tente novamente o botão de abertura. O visualizador abre bytes validados em Blob; os cabeçalhos de download da hospedagem original não controlam diretamente essa nova URL. O suporte nativo e as preferências de download variam. Confira as opções do site e da rota antes de tratar um controle desativado como erro de carga.
+
+Para narração silenciosa, confira suporte de fala, vozes disponíveis, idioma, volume e saída de áudio. As vozes podem chegar depois da carga ou depender de um serviço remoto. Outra mídia audível interrompe a narração quando \`mediaExclusivePlayback\` está habilitado. Trocar documento ou idioma cancela a fala anterior.
+
+## Separe acesso e processos
+
+Menus ocultos e autorização no navegador não protegem arquivos públicos em hospedagem estática. Verifique as permissões reais da hospedagem confidencial; alterar perfis na interface não protege uma URL de PDF exposta.
+
+O processo \`gitpagedocs mcp start\` aguardando é normal: ele conversa por stdio com um cliente, não com um terminal interativo. Confira diretório, executável e ambiente herdado. As credenciais devem existir nesse processo; o cofre da CLI e o \`.env\` não são carregados automaticamente. Reserve stdout ao protocolo, consulte stderr e resultados \`isError\`, compartilhando diagnósticos sem segredos.
+`,
+};

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.
+`,
+};