@gitpagedocs/cli 0.0.9 → 0.0.10

package/content/html-doom.mjs

@@ -0,0 +1,155 @@
+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: "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",
+    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",
+    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",
+    player: "Área del juego DOOM",
+  },
+};
+
+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; }
+  #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)};
+  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 startGame() {
+    button.disabled = true;
+    status.textContent = status.dataset.loading;
+    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");
+      player.hidden = false;
+      game = window.Dos(player, {
+        url: bundleUrl,
+        pathPrefix: baseUrl + "emulators/",
+        autoStart: true,
+        mouseCapture: false,
+        theme: "dark",
+        lang: "en",
+        onEvent(event) {
+          if (event === "ci-ready") status.textContent = status.dataset.ready;
+        },
+      });
+      button.hidden = true;
+      player.focus();
+    } catch (error) {
+      stylesheet.remove();
+      script.remove();
+      status.textContent = status.dataset.error;
+      button.disabled = false;
+      console.error("DOOM player failed to load", error);
+    }
+  }
+
+  button.addEventListener("click", startGame);
+  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">
+    <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>
+  </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.10 version
+npx --yes @gitpagedocs/cli@0.0.10 --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.10 version
+npx --yes @gitpagedocs/cli@0.0.10 --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 publica 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.
+
+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.
+`,
+  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.10 version
+npx --yes @gitpagedocs/cli@0.0.10 --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 publica 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/practical-en.mjs

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

package/content/practical-es.mjs

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