@gitpagedocs/cli 0.0.11 → 0.0.13

package/README.md

@@ -28,7 +28,8 @@ npx @gitpagedocs/cli
 | `gitpagedocs provider [id]` · `models [provider]` | List AI providers / catalog models |
 | `gitpagedocs document[:repo\|:file\|:folder]` | Generate documentation with AI in the gitpagedocs pattern |
 | `gitpagedocs password` | Set a documentation access password (writes the public key to `config.json`, prints the private key) |
-| `gitpagedocs deploy` / `pages [actions\|deploy]` | Configure GitHub Pages via Actions + push |
+| `gitpagedocs deploy` / `pages deploy` | Configure GitHub Pages via Actions, generate, commit and push |
+| `gitpagedocs pages actions` | Switch the repository's Pages source to GitHub Actions; no generation or push |
 | `gitpagedocs docs` | Refresh managed regions of README/CONTRIBUTING/SECURITY |
 | `gitpagedocs config clear` | Delete the stored `.gitpagedocsconfig` **and** the encrypted key vault `.gitpagedocsvault` (wipes saved AI credentials) |
 | `gitpagedocs doctor` · `version` · `update` | Diagnostics / version / registry update check |
@@ -36,6 +37,24 @@ npx @gitpagedocs/cli
 
 The AI-CLI implementation lives in `cli/ai/` (relocated from the frontend so the published package is self-contained).
 
+## Generated documentation and themes
+
+Version 0.0.13 registers documentation versions 0.0.13, 0.0.12, 0.0.11, 0.0.10 and 0.0.9, newest first, with English, Portuguese and Spanish pages. Existing older folders are preserved. Source content lives in `content/`; defaults and UI labels live in `data/`; edit these sources before regeneration. The published package includes the English PDF guide and the local HTML integration for the externally hosted DOOM player.
+
+The scaffold demonstrates parent Markdown destinations with recursive submenus and navigable breadcrumbs, PDF routes/actions, and a page with ordered, repeated Markdown/HTML/video/audio/PDF blocks. Route titles and descriptions have independent placement settings. Focus mode provides source actions and eight document/section navigation controls; browser narration is configured separately. See the generated configuration, content-blocks, focus, accessibility and HTML/PDF guides for complete examples.
+
+`gitpagedocs --layoutconfig` ships all 124 themes: 64 original themes, 20 standalone animated presets and 20 additional dark/light parallax pairs. New presets originate in `gitpagelayouts/v2/` and are compiled into package-local data by `pnpm run layouts:sync`; a standalone CLI installation does not need the source repository to emit them. Customize backgrounds through `site.backgroundEffects`, including global/per-theme settings, colors, density, speed and parallax. The master switch disables backgrounds; `overrides.accessibility.showPauseButton: false` hides only the pause control.
+
+`site.icons.VersionSelector` and `BackgroundAnimationPause`/`BackgroundAnimationResume` use the same `reactIcon`, `tag`, `size`, `colorDark` and `colorLight` contract as other controls. Pause/resume appears in the navigation menu beside its lock; a manual pause persists across theme and menu changes. `reactIcon: false` selects localized text independently for each control.
+
+The [MCP reference](../mcp/README.md) documents installation, client configuration, all 20 tools and seven resources. MCP runs over stdio and reads provider credentials from its environment; it does not automatically unlock the CLI vault.
+
+## Packaging and release
+
+Root and frontend workspaces are private. The public packages are `@gitpagedocs/tools`, `@gitpagedocs/mcp` and `@gitpagedocs/cli`; their versions, internal ranges and lockfile must agree. The npm workflow checks a new CLI version, installs with a frozen lockfile, runs typecheck and contract self-tests, then publishes the workspaces. GitHub Pages builds the viewer in its separate workflow. Neither workflow creates GitHub release notes or tags automatically.
+
+The package allowlist includes its source, templates, data and assets. `prebuilt/` is optional and is not created by the npm workflow. The config-only command generates repository data without starting a server. Run the full project checks and inspect package contents before publication; verify the published package and deployed site afterward.
+
 # CLI Architecture (Clean Architecture + SOLID)
 
 ## Layer Overview
@@ -141,7 +160,7 @@ npx @gitpagedocs/cli ai
 
 ### What it does
 
-- asks provider (`openai`, `claude`, `gemini`, `ollama`)
+- asks for a provider from the shared catalog (14 providers, including OpenAI, Anthropic, Gemini and Ollama)
 - asks API key or Ollama URL
 - asks paths to scan (supports one or many paths, including other repositories)
 - generates documentation in `pt`, `en`, `es` **in the gitpagedocs pattern**
@@ -169,21 +188,22 @@ permissions on POSIX systems:
 - Linux: `$XDG_CONFIG_HOME/gitpagedocs/.gitpagedocsconfig` (or `~/.config/gitpagedocs/.gitpagedocsconfig`)
 
 Set `GITPAGEDOCS_CONFIG_DIR` to override the directory; delete the stored file,
-the vault and their credentials with `gitpagedocs config clear`. You can create/edit
-this file manually and then run `npx @gitpagedocs/cli ai`:
+the vault and their credentials with `gitpagedocs config clear`. This example describes
+a saved configuration whose key already exists in the encrypted vault. Edit its non-secret
+settings and then run `npx @gitpagedocs/cli ai`. For a new installation, run the interactive
+setup first; if no key exists, decline reuse of the configuration and enter the credentials.
 
 ```json
 {
 	"version": 1,
 	"ai": {
 		"provider": "openai",
-		"model": "gpt-4o-mini",
 		"apiKeyEncrypted": true,
 		"paths": ["src", "cli", "../another-repo/src"],
 		"languages": ["pt", "en", "es"],
 		"outputDir": "gitpagedocs/docs",
 		"filePrefix": "ai-generated",
-		"contextPrompt": "Você é um redator técnico sênior..."
+		"contextPrompt": "Write clear technical documentation for this project."
 	}
 }
 ```
@@ -200,7 +220,7 @@ derived from your password with PBKDF2-HMAC-SHA-256, 210k iterations) and the co
 - `GITPAGEDOCS_VAULT_PASSWORD` supplies the password without a prompt (CI, pipes, no TTY);
   on a first run it initializes the vault, otherwise it must match the existing one.
 - A plaintext `"apiKey"` written by 0.0.1 is sealed into the vault and removed from the file
-  the next time the config is read.
+  when `ai` or `chat` reuses that configuration and unlocks it with the vault password.
 - If you hand-write the file, leave the key out: enter it in the `gitpagedocs ai` prompt (it is
   sealed on save). `gitpagedocs chat` can also read the provider's environment variable
   (`gitpagedocs provider <id>` lists it) when no key is stored.

package/ai/application/run-ai-cli-command.ts

@@ -14,7 +14,7 @@ import { GITPAGEDOCS_DOC_SYSTEM_PROMPT } from "../config";
 import { parseAiPages, type AiDocPage } from "./docs-pattern";
 import { writeVersionDocs } from "../infrastructure/version-docs-writer";
 // @ts-expect-error .mjs runtime module is type-less in this package.
-import { DOC_VERSIONS } from "../../contracts/doc-versions.mjs";
+import { PACKAGE_VERSION } from "../../contracts/doc-versions.mjs";
 
 const LANGUAGE_TO_LABEL: Record<string, string> = {
   pt: "Portuguese",
@@ -122,7 +122,7 @@ export async function executeAiRunPlan(
   }
 
   // Wire the AI pages into the latest documentation version (gitpagedocs pattern).
-  const versionId = DOC_VERSIONS[DOC_VERSIONS.length - 1] as string;
+  const versionId = PACKAGE_VERSION as string;
   const result = await writeVersionDocs({ cwd, versionId, pagesByLang });
 
   return {

package/builders/theme-template.mjs

@@ -2,6 +2,7 @@
 
 import { PACKAGE_VERSION } from "../contracts/doc-versions.mjs";
 import { THEME_COLORS } from "../data/theme-colors.mjs";
+import { ANIMATED_BACKGROUNDS } from "../data/animated-layouts.mjs";
 
 /** `#RRGGBB` (or `#RGB`) to `rgba(r, g, b, alpha)` for palette-derived glows and borders. */
 function rgba(hex, alpha) {
@@ -14,6 +15,7 @@ function rgba(hex, alpha) {
 export function createThemeTemplate(layout, themeColors = THEME_COLORS) {
   const colors = themeColors[layout.id] ?? themeColors.default;
   const dark = layout.mode === "dark";
+  const background = ANIMATED_BACKGROUNDS[layout.id];
   return {
     id: layout.id,
     name: layout.name,
@@ -82,5 +84,6 @@ export function createThemeTemplate(layout, themeColors = THEME_COLORS) {
       enableGlow: dark,
       transitionDuration: "0.22s",
     },
+    ...(background ? { backgroundEffects: structuredClone(background) } : {}),
   };
 }

package/content/configuration-examples.mjs

@@ -43,6 +43,7 @@ export const RECIPE_ROOT_JSON = JSON.stringify({
       defaults: { reactIcon: true, size: "22px", colorDark: "currentColor", colorLight: "currentColor" },
       LanguageSelector: { tag: "SiGoogletranslate" },
       ThemeSelector: { tag: "LuPencil" },
+      VersionSelector: { tag: "LuGitBranch" },
       FocusMode: { tag: "LuBookOpen" },
       QuickNavigation: { tag: "LuSearch" },
       PdfDownload: { tag: "LuDownload" },

package/content/docs-en.mjs

@@ -4,6 +4,7 @@ import { operationsEn } from "./operations-en.mjs";
 import { overviewsEn } from "./overviews-en.mjs";
 import { CONTENT_BLOCKS_DOCS } from "./content-blocks.mjs";
 import { PARENT_MENU_JSON } from "./configuration-examples.mjs";
+import { THEME_BACKGROUND_DOCS } from "./theme-backgrounds.mjs";
 
 export const docsEn = {
     ...practicalEn,
@@ -43,7 +44,7 @@ PDF actions use icons by default. Configure \`site.icons.PdfDownload\` (\`LuDown
 
 ## Route and menu example
 
-In \`gitpagedocs/docs/versions/0.0.11/config.json\`, keep route and menu arrays at the top level:
+In \`gitpagedocs/docs/versions/0.0.13/config.json\`, keep route and menu arrays at the top level:
 
 \`\`\`json
 {
@@ -52,9 +53,9 @@ In \`gitpagedocs/docs/versions/0.0.11/config.json\`, keep route and menu arrays
     "title": { "en": "Project guide (English)", "pt": "Guia do projeto (inglês)", "es": "Guía del proyecto (inglés)" },
     "pdf": {
       "pathPdf": {
-        "en": "gitpagedocs/docs/versions/0.0.11/en/gitpagedocs-project-guide.pdf",
-        "pt": "gitpagedocs/docs/versions/0.0.11/en/gitpagedocs-project-guide.pdf",
-        "es": "gitpagedocs/docs/versions/0.0.11/en/gitpagedocs-project-guide.pdf"
+        "en": "gitpagedocs/docs/versions/0.0.13/en/gitpagedocs-project-guide.pdf",
+        "pt": "gitpagedocs/docs/versions/0.0.13/en/gitpagedocs-project-guide.pdf",
+        "es": "gitpagedocs/docs/versions/0.0.13/en/gitpagedocs-project-guide.pdf"
       },
       "previewEnabled": true,
       "downloadEnabled": true,
@@ -212,7 +213,7 @@ Git Page Docs is a **pnpm + turborepo monorepo** that turns a repository's \`git
 - 14-provider AI system (OpenAI, Anthropic, Gemini, Ollama, Mistral, DeepSeek, Cohere, Groq, xAI, and more) with streaming
 - AI API keys stored **encrypted at rest** (AES-256-GCM) behind a local password gate — never plaintext
 - In-docs **AI chat drawer** plus a dedicated **\`/ai\` console**
-- 64-theme layout system (dark and light variants); local and GitHub Pages execution modes
+- 124-theme layout system (dark and light variants); local and GitHub Pages execution modes
 `,
     functionalities: `# Functionalities
 
@@ -419,6 +420,16 @@ Important keys:
 - \`ThemeModeDefault\`
 - \`ProjectLink\`
 
+## Back to top on long pages
+
+The back-to-top arrow on documentation pages and \`/introduction-guide\` is controlled by \`site.backToTop\` in \`gitpagedocs/config.json\`:
+
+\`\`\`json
+{ "site": { "backToTop": { "enabled": true, "minPageHeightViewports": 3 } } }
+\`\`\`
+
+The default enables the arrow only on a scrollable page whose total height is at least three viewport heights. Set \`enabled: false\` to hide it. \`minPageHeightViewports\` accepts a finite number greater than \`1\`; omitted or invalid values use \`3\`. For example, \`4\` requires a page at least four viewport heights tall. The threshold measures total page height, not distance already scrolled. The same setting controls documentation pages and the introduction guide.
+
 ## Layout source keys
 
 - \`layoutsConfigPathOficial\`
@@ -434,7 +445,7 @@ Behavior:
 
 ## Language, theme, focus, quick navigation, PDF and document controls
 
-In \`gitpagedocs/config.json\`, these \`site.icons\` entries configure the language selector, theme selector, focus, Ctrl+K navigation, PDF actions and document-footer navigation. All eight controls use React Icons by default:
+In \`gitpagedocs/config.json\`, these \`site.icons\` entries configure the language selector, theme selector, focus, Ctrl+K navigation, PDF actions and document-footer navigation. All nine controls use React Icons by default:
 
 \`\`\`json
 {
@@ -448,6 +459,10 @@ In \`gitpagedocs/config.json\`, these \`site.icons\` entries configure the langu
         "reactIcon": true, "tag": "LuPencil", "size": "22px",
         "colorDark": "currentColor", "colorLight": "currentColor"
       },
+      "VersionSelector": {
+        "reactIcon": true, "tag": "LuGitBranch", "size": "22px",
+        "colorDark": "currentColor", "colorLight": "currentColor"
+      },
       "FocusMode": {
         "reactIcon": true, "tag": "LuBookOpen", "size": "22px",
         "colorDark": "currentColor", "colorLight": "currentColor"
@@ -483,6 +498,8 @@ Compact configs may move shared values into \`site.icons.defaults\`; omitted fie
 
 ## \`VersionControl\` section
 
+\`site.icons.VersionSelector\` uses \`LuGitBranch\` by default. Set \`reactIcon: false\` to display the selected version as text; \`true\` displays its icon. Customize the same \`tag\`, \`size\`, \`colorDark\` and \`colorLight\` fields. The selector appears only when more than one documentation version is available, retains the localized accessible name of the selector and shows the selected version in its tooltip.
+
 \`VersionControl.versions\` defines:
 
 - \`id\`
@@ -699,6 +716,8 @@ Select an installed theme through the theme selector or configure \`site.ThemeDe
 For your own repository, run the CLI with \`--layoutconfig\`, then edit the generated template and keep its ID consistent with \`layoutsConfig.json\`. A route's content and \`site.icons\` remain independent of the theme catalog. Use \`currentColor\` for icons that should inherit the active text color, or configure separate dark/light colors with sufficient contrast.
 
 When contributing to Git Page Docs itself, the authoring source is \`gitpagelayouts/v2/base.json\` plus \`gitpagelayouts/v2/layouts/<id>.json\`. Run \`pnpm layouts:sync\` to regenerate templates and documentation. Direct edits to generated templates can be overwritten by that synchronization.
+
+${THEME_BACKGROUND_DOCS.en}
 `,
     mcp: `# MCP server
 
@@ -759,7 +778,7 @@ Select a provider using \`configure_ai_provider\` or \`.gitpagedocs-mcp.json\` a
 | \`fireworks\` | \`FIREWORKS_API_KEY\` |
 | \`perplexity\` | \`PERPLEXITY_API_KEY\` |
 
-With no valid selection, the default provider is OpenAI. Ollama does not require an API key; its local service and chosen model must be available. \`OLLAMA_BASE_URL\` is optional. Azure's base URL is the complete chat-operation URL, including deployment and API-version query when required. Model listings are the bundled catalog, not a live availability check.
+When the saved selection is absent, unreadable or invalid JSON, the default provider is OpenAI. An unknown provider ID in readable JSON produces an explicit error instead of selecting another provider. Ollama does not require an API key; its local service and chosen model must be available. \`OLLAMA_BASE_URL\` is optional. Azure's base URL is the complete chat-operation URL, including deployment and API-version query when required. Model listings are the bundled catalog, not a live availability check.
 
 ## Tool reference
 
@@ -815,7 +834,7 @@ The generation step sends selected project content to the configured provider.
 
 - File reads: up to 512,000 bytes. Listing: up to 2,000 entries; gathered project trees: 400 entries.
 - Search: up to 5,000 entries, 200 matches, 240 characters per matching line.
-- Documentation gathering: first 40 Markdown files among up to 2,000 entries; files over 40,000 bytes are skipped. Provider context is capped at 24,000 characters.
+- Documentation gathering: first 40 Markdown files among up to 2,000 entries; files over 40,000 bytes are skipped. Gathered file and Markdown context is limited to 24,000 characters. This is not a global prompt limit: tree/package context, an existing document and a caller-supplied question can add content according to the selected tool.
 - Listing skips build/dependency directories such as \`node_modules\`, \`.git\`, \`.next\`, \`out\`, \`dist\`, \`prebuilt\`, \`.turbo\` and \`coverage\`. It does not interpret \`.gitignore\`; files such as \`.env\` are not automatically excluded. Run only in a trusted project and select the content to expose.
 - Path checks use lexical containment; do not treat the process as an operating-system sandbox or assume symlink/junction isolation. Loading \`project://config\` can import JavaScript/TypeScript configuration.
 - Tool failures include \`isError: true\`. Missing resources return \`Unavailable: ...\`. Check the client's stderr log for startup errors; stdout is reserved for JSON-RPC.
@@ -1049,7 +1068,7 @@ The download keeps the Markdown basename from the route's localized \`path\`; if
 
 The dialog has an accessible name, keyboard focus management and a close control. Use Tab to move through controls and Escape to close it. Keep icon-only controls accessible by retaining their translated names. Closing the dialog returns to the documentation view.
 
-Narration is configured separately in Accessibility. Changing the active document or language cancels the previous narration so it cannot continue reading stale content.
+Narration is configured separately in Accessibility. In focus mode, it reads only the section currently displayed. Changing the section, document or language, or entering or leaving focus mode, stops the previous speech; the next reading starts from the visible content. Voice, speed and volume preferences are retained. With \`sectionNavigationEnabled: false\`, the entire document is visible and available for narration. Copy/download still includes the complete original source.
 `,
     accessibility: `# Accessibility and narration
 
@@ -1090,7 +1109,9 @@ Merge the following settings into \`gitpagedocs/config.json\`:
 
 Narration starts only after your action; there is no autoplay. Automatic voice selection follows the document language, while an explicit voice choice uses that voice's language. Narration does not translate the document.
 
-The speech content is readable text extracted from the rendered Markdown. Scripts, styles, SVG content and elements marked hidden for assistive technology are excluded. Long documents are read completely in successive blocks. Changing the document or language, disabling narration or leaving the page cancels the previous speech.
+The speech content is readable text extracted from the rendered Markdown. Scripts, styles, SVG content and elements marked hidden for assistive technology are excluded. Long visible content is read completely in successive blocks. Changing the document or language, disabling narration or leaving the page cancels the previous speech.
+
+In focus mode, narration uses only the displayed section. Changing sections or documents, or entering or leaving focus mode, stops the previous reading. Start again to read the newly visible content. With \`site.focusMode.sectionNavigationEnabled: false\`, the whole document remains visible and narratable. These transitions preserve the selected voice, speed and volume.
 
 The normal view and focus mode share voice, speed and volume preferences while the page remains mounted. These preferences are not stored across reloads. Non-numeric speed or volume settings use \`1\`; numeric settings outside the supported ranges are clamped to their nearest limit.
 
@@ -1142,7 +1163,7 @@ Because GitHub Pages build mode enables repository-search home and static-export
 
 ## Why does an icon still show text?
 
-Set \`site.icons.<Control>.reactIcon\` to the boolean \`true\`, with an exact React Icons export name in \`tag\`. LanguageSelector, ThemeSelector, FocusMode, QuickNavigation, PdfDownload, PdfOpenInNewTab, DocumentPrevious and DocumentNext use icons by default; set any entry to \`false\` for text. Flat \`Icon*ReactIcones\` fields take precedence if both formats are present. Check whether the feature itself is disabled, such as \`HideThemeSelector\`, \`FocusMode\` or the PDF action flags.
+Set \`site.icons.<Control>.reactIcon\` to the boolean \`true\`, with an exact React Icons export name in \`tag\`. LanguageSelector, ThemeSelector, VersionSelector, FocusMode, QuickNavigation, PdfDownload, PdfOpenInNewTab, DocumentPrevious and DocumentNext use icons by default; set any entry to \`false\` for text. Flat \`Icon*ReactIcones\` fields take precedence if both formats are present. Check whether the feature itself is disabled, such as \`HideThemeSelector\`, \`FocusMode\` or the PDF action flags.
 
 ## Why do menu children or breadcrumbs differ?
 

package/content/docs-es.mjs

@@ -3,6 +3,7 @@ import { operationsEs } from "./operations-es.mjs";
 import { overviewsEs } from "./overviews-es.mjs";
 import { CONTENT_BLOCKS_DOCS } from "./content-blocks.mjs";
 import { PARENT_MENU_JSON } from "./configuration-examples.mjs";
+import { THEME_BACKGROUND_DOCS } from "./theme-backgrounds.mjs";
 
 export const docsEs = {
     ...practicalEs,
@@ -42,7 +43,7 @@ Las acciones PDF usan iconos por defecto. Configura \`site.icons.PdfDownload\` (
 
 ## Ejemplo de ruta y menú
 
-En \`gitpagedocs/docs/versions/0.0.11/config.json\`, conserva las listas de rutas y menús en el nivel principal:
+En \`gitpagedocs/docs/versions/0.0.13/config.json\`, conserva las listas de rutas y menús en el nivel principal:
 
 \`\`\`json
 {
@@ -51,9 +52,9 @@ En \`gitpagedocs/docs/versions/0.0.11/config.json\`, conserva las listas de ruta
     "title": { "en": "Project guide (English)", "pt": "Guia do projeto (inglês)", "es": "Guía del proyecto (inglés)" },
     "pdf": {
       "pathPdf": {
-        "en": "gitpagedocs/docs/versions/0.0.11/en/gitpagedocs-project-guide.pdf",
-        "pt": "gitpagedocs/docs/versions/0.0.11/en/gitpagedocs-project-guide.pdf",
-        "es": "gitpagedocs/docs/versions/0.0.11/en/gitpagedocs-project-guide.pdf"
+        "en": "gitpagedocs/docs/versions/0.0.13/en/gitpagedocs-project-guide.pdf",
+        "pt": "gitpagedocs/docs/versions/0.0.13/en/gitpagedocs-project-guide.pdf",
+        "es": "gitpagedocs/docs/versions/0.0.13/en/gitpagedocs-project-guide.pdf"
       },
       "previewEnabled": true,
       "downloadEnabled": true,
@@ -211,7 +212,7 @@ Git Page Docs es un monorepo pnpm + turborepo que convierte la carpeta \`gitpage
 - Sistema de IA con 14 proveedores (OpenAI, Anthropic, Gemini, Ollama, Mistral, DeepSeek, Cohere, Groq, xAI y más) con streaming
 - Claves de IA **cifradas en reposo** (AES-256-GCM) detrás de una contraseña local — nunca en texto plano
 - **Panel de chat de IA** en los docs + una **consola \`/ai\`** dedicada
-- Sistema de 64 temas (variantes oscuras y claras); ejecución local y en GitHub Pages
+- Sistema de 124 temas (variantes oscuras y claras); ejecución local y en GitHub Pages
 `,
     functionalities: `# Funcionalidades
 
@@ -313,9 +314,19 @@ Claves principales:
 - \`layoutsConfigPath\`: fallback remoto de layouts
 - \`rendering\`: URL canónica publicada
 
+## Volver arriba en páginas largas
+
+La flecha para volver arriba en las páginas de documentación y en \`/introduction-guide\` se controla mediante \`site.backToTop\` en \`gitpagedocs/config.json\`:
+
+\`\`\`json
+{ "site": { "backToTop": { "enabled": true, "minPageHeightViewports": 3 } } }
+\`\`\`
+
+Por defecto, la flecha está activada solo en una página desplazable cuya altura total sea al menos tres veces la altura del área visible del navegador. Usa \`enabled: false\` para ocultarla. \`minPageHeightViewports\` acepta un número finito mayor que \`1\`; los valores ausentes o no válidos usan \`3\`. Por ejemplo, \`4\` exige una página de al menos cuatro alturas del área visible. El umbral mide la altura total de la página, no la distancia ya recorrida. La misma configuración controla las páginas de documentación y la guía de introducción.
+
 ## Controles de idioma, tema, foco, navegación rápida, PDF y documentos
 
-En \`gitpagedocs/config.json\`, estas entradas de \`site.icons\` configuran idioma, tema, foco, navegación Ctrl+K, acciones PDF y navegación al pie de los documentos. Los ocho controles utilizan React Icons por defecto:
+En \`gitpagedocs/config.json\`, estas entradas de \`site.icons\` configuran idioma, tema, versión, foco, navegación Ctrl+K, acciones PDF y navegación al pie de los documentos. Los nueve controles utilizan React Icons por defecto:
 
 \`\`\`json
 {
@@ -333,6 +344,10 @@ En \`gitpagedocs/config.json\`, estas entradas de \`site.icons\` configuran idio
         "reactIcon": true, "tag": "LuBookOpen", "size": "22px",
         "colorDark": "currentColor", "colorLight": "currentColor"
       },
+      "VersionSelector": {
+        "reactIcon": true, "tag": "LuGitBranch", "size": "22px",
+        "colorDark": "currentColor", "colorLight": "currentColor"
+      },
       "QuickNavigation": {
         "reactIcon": true, "tag": "LuSearch", "size": "22px",
         "colorDark": "currentColor", "colorLight": "currentColor"
@@ -364,6 +379,8 @@ Las configuraciones compactas pueden mover valores comunes a \`site.icons.defaul
 
 ## Sección \`VersionControl\`
 
+\`site.icons.VersionSelector\` utiliza \`LuGitBranch\` por defecto. Define \`reactIcon: false\` para mostrar el texto de la versión seleccionada; \`true\` muestra el icono. Personaliza los mismos campos \`tag\`, \`size\`, \`colorDark\` y \`colorLight\`. El selector aparece solo cuando hay más de una versión de documentación; conserva el nombre accesible localizado del selector y muestra la versión seleccionada en el tooltip.
+
 \`VersionControl.versions\` define:
 
 - \`id\`: identificador de versión
@@ -639,7 +656,7 @@ Cada template normalmente incluye:
 - toggle light/dark resuelve tema pareado por referencia
 - variables CSS se generan desde tokens del template
 
-## Buenas practicas
+## Buenas prácticas
 
 - mantener contraste accesible
 - mantener escala consistente de espacios y bordes
@@ -652,6 +669,8 @@ Elige un tema mediante el selector o configura \`site.ThemeDefault\` con su ID e
 En tu repositorio, ejecuta la CLI con \`--layoutconfig\`, edita la plantilla generada y conserva el ID coherente con \`layoutsConfig.json\`. El contenido de ruta y \`site.icons\` son independientes del catálogo de temas. Usa \`currentColor\` para iconos que heredan el color de texto o configura colores claros/oscuros con contraste suficiente.
 
 Al contribuir en Git Page Docs, la fuente es \`gitpagelayouts/v2/base.json\` junto con \`gitpagelayouts/v2/layouts/<id>.json\`. Ejecuta \`pnpm layouts:sync\` para generar plantillas y documentación. La sincronización puede sobrescribir las ediciones directas de plantillas generadas.
+
+${THEME_BACKGROUND_DOCS.es}
 `,
     mcp: `# Servidor MCP
 
@@ -712,7 +731,7 @@ Selecciona el proveedor con \`configure_ai_provider\` o con \`.gitpagedocs-mcp.j
 | \`fireworks\` | \`FIREWORKS_API_KEY\` |
 | \`perplexity\` | \`PERPLEXITY_API_KEY\` |
 
-Sin una selección válida, el proveedor predeterminado es OpenAI. Ollama no requiere clave de API; el servicio local y el modelo elegido deben estar disponibles. \`OLLAMA_BASE_URL\` es opcional. La URL base de Azure es la URL completa de la operación de chat, incluido deployment y versión de API cuando sean necesarios. La lista de modelos es un catálogo distribuido, no una comprobación en tiempo real.
+Cuando la selección guardada está ausente, no se puede leer o contiene JSON inválido, el proveedor predeterminado es OpenAI. Un ID de proveedor desconocido en JSON legible produce un error explícito sin seleccionar otro proveedor. Ollama no requiere clave de API; el servicio local y el modelo elegido deben estar disponibles. \`OLLAMA_BASE_URL\` es opcional. La URL base de Azure es la URL completa de la operación de chat, incluido deployment y versión de API cuando sean necesarios. La lista de modelos es un catálogo distribuido, no una comprobación en tiempo real.
 
 ## Referencia de tools
 
@@ -768,7 +787,7 @@ La generación envía el contenido seleccionado del proyecto al proveedor config
 
 - Lectura de archivos: hasta 512.000 bytes. Listado: hasta 2.000 entradas; árboles recopilados del proyecto: 400 entradas.
 - Búsqueda: hasta 5.000 entradas, 200 resultados y 240 caracteres por línea encontrada.
-- Recopilación de documentación: primeros 40 archivos Markdown entre hasta 2.000 entradas; se omiten archivos superiores a 40.000 bytes. El contexto del proveedor se limita a 24.000 caracteres.
+- Recopilación de documentación: primeros 40 archivos Markdown entre hasta 2.000 entradas; se omiten archivos superiores a 40.000 bytes. El contexto recopilado de archivos y Markdown se limita a 24.000 caracteres. No es un límite global del prompt: árbol/paquete, documento existente y pregunta proporcionada pueden añadir contenido según la tool seleccionada.
 - El listado omite carpetas de dependencias/build como \`node_modules\`, \`.git\`, \`.next\`, \`out\`, \`dist\`, \`prebuilt\`, \`.turbo\` y \`coverage\`. No interpreta \`.gitignore\`; archivos como \`.env\` no se excluyen automáticamente. Ejecuta solo en proyectos de confianza y selecciona el contenido que se expondrá.
 - La verificación de rutas es léxica; el proceso no es un sandbox del sistema operativo ni garantiza aislamiento de symlinks/junctions. Leer \`project://config\` puede importar configuración JavaScript/TypeScript.
 - Los fallos de tools incluyen \`isError: true\`. Los resources ausentes devuelven \`Unavailable: ...\`. Revisa stderr en el cliente para errores de inicio; stdout está reservado para JSON-RPC.
@@ -1002,7 +1021,7 @@ La descarga conserva el nombre base Markdown del \`path\` localizado de la ruta;
 
 El diálogo tiene nombre accesible, gestión de foco del teclado y control de cierre. Usa Tab para recorrer controles y Escape para cerrar. Los controles de solo icono conservan nombres traducidos accesibles. Cerrar el diálogo vuelve a la documentación.
 
-La narración se configura por separado en Accesibilidad. Cambiar de documento o idioma cancela la narración anterior para que no siga leyendo contenido antiguo.
+La narración se configura por separado en Accesibilidad. En modo foco, lee solo la sección mostrada. Cambiar de sección, documento o idioma, entrar o salir del modo foco detiene la voz anterior; la próxima lectura empieza desde el contenido visible. Se conservan las preferencias de voz, velocidad y volumen. Con \`sectionNavigationEnabled: false\`, el documento completo queda visible y disponible para narración. Copiar/descargar sigue incluyendo toda la fuente original.
 `,
     accessibility: `# Accesibilidad y narración
 
@@ -1043,7 +1062,9 @@ Combina estas opciones con \`gitpagedocs/config.json\`:
 
 La narración empieza solo después de tu acción; no hay reproducción automática. La selección automática de voz sigue el idioma del documento; elegir una voz explícitamente utiliza el idioma de esa voz. La narración no traduce el documento.
 
-La voz utiliza texto legible extraído del Markdown renderizado. Se excluyen scripts, estilos, contenido SVG y elementos ocultos para tecnologías de asistencia. Los documentos largos se leen completos en bloques sucesivos. Cambiar de documento o idioma, desactivar la narración o salir de la página cancela la voz anterior.
+La voz utiliza texto legible extraído del Markdown renderizado. Se excluyen scripts, estilos, contenido SVG y elementos ocultos para tecnologías de asistencia. El contenido visible largo se lee completo en bloques sucesivos. Cambiar de documento o idioma, desactivar la narración o salir de la página cancela la voz anterior.
+
+En modo foco, la narración usa solo la sección mostrada. Cambiar de sección o documento, entrar o salir del modo foco detiene la lectura anterior. Inicia de nuevo para leer el contenido que ahora está visible. Con \`site.focusMode.sectionNavigationEnabled: false\`, el documento completo permanece visible y se puede narrar. Estas transiciones conservan la voz, velocidad y volumen seleccionados.
 
 La vista habitual y el modo foco comparten preferencias de voz, velocidad y volumen mientras la página permanece montada. Las preferencias no se guardan entre recargas. Los valores no numéricos de velocidad o volumen usan \`1\`; los valores numéricos fuera de los rangos admitidos se limitan al extremo más cercano.
 
@@ -1095,7 +1116,7 @@ Porque el build de GitHub Pages habilita la página inicial de búsqueda y compo
 
 ## ¿Por qué el icono sigue mostrando texto?
 
-Define \`site.icons.<Control>.reactIcon\` como booleano \`true\`, con el nombre exacto exportado por React Icons en \`tag\`. LanguageSelector, ThemeSelector, FocusMode, QuickNavigation, PdfDownload, PdfOpenInNewTab, DocumentPrevious y DocumentNext usan iconos por defecto; cambia cualquier entrada a \`false\` para mostrar texto. Los campos planos \`Icon*ReactIcones\` tienen prioridad si existen ambos formatos. Comprueba si la propia función está desactivada mediante \`HideThemeSelector\`, \`FocusMode\` o las acciones PDF.
+Define \`site.icons.<Control>.reactIcon\` como booleano \`true\`, con el nombre exacto exportado por React Icons en \`tag\`. LanguageSelector, ThemeSelector, VersionSelector, FocusMode, QuickNavigation, PdfDownload, PdfOpenInNewTab, DocumentPrevious y DocumentNext usan iconos por defecto; cambia cualquier entrada a \`false\` para mostrar texto. Los campos planos \`Icon*ReactIcones\` tienen prioridad si existen ambos formatos. Comprueba si la propia función está desactivada mediante \`HideThemeSelector\`, \`FocusMode\` o las acciones PDF.
 
 ## ¿Por qué los hijos del menú o breadcrumbs son diferentes?
 

package/content/docs-pt.mjs

@@ -3,6 +3,7 @@ import { operationsPt } from "./operations-pt.mjs";
 import { overviewsPt } from "./overviews-pt.mjs";
 import { CONTENT_BLOCKS_DOCS } from "./content-blocks.mjs";
 import { PARENT_MENU_JSON } from "./configuration-examples.mjs";
+import { THEME_BACKGROUND_DOCS } from "./theme-backgrounds.mjs";
 
 export const docsPt = {
     ...practicalPt,
@@ -42,7 +43,7 @@ As ações PDF usam ícones por padrão. Configure \`site.icons.PdfDownload\` (\
 
 ## Exemplo de rota e menu
 
-Em \`gitpagedocs/docs/versions/0.0.11/config.json\`, mantenha as listas de rotas e menus no nível principal:
+Em \`gitpagedocs/docs/versions/0.0.13/config.json\`, mantenha as listas de rotas e menus no nível principal:
 
 \`\`\`json
 {
@@ -51,9 +52,9 @@ Em \`gitpagedocs/docs/versions/0.0.11/config.json\`, mantenha as listas de rotas
     "title": { "en": "Project guide (English)", "pt": "Guia do projeto (inglês)", "es": "Guía del proyecto (inglés)" },
     "pdf": {
       "pathPdf": {
-        "en": "gitpagedocs/docs/versions/0.0.11/en/gitpagedocs-project-guide.pdf",
-        "pt": "gitpagedocs/docs/versions/0.0.11/en/gitpagedocs-project-guide.pdf",
-        "es": "gitpagedocs/docs/versions/0.0.11/en/gitpagedocs-project-guide.pdf"
+        "en": "gitpagedocs/docs/versions/0.0.13/en/gitpagedocs-project-guide.pdf",
+        "pt": "gitpagedocs/docs/versions/0.0.13/en/gitpagedocs-project-guide.pdf",
+        "es": "gitpagedocs/docs/versions/0.0.13/en/gitpagedocs-project-guide.pdf"
       },
       "previewEnabled": true,
       "downloadEnabled": true,
@@ -211,7 +212,7 @@ Git Page Docs é um monorepo pnpm + turborepo que transforma a pasta \`gitpagedo
 - Sistema de IA com 14 provedores (OpenAI, Anthropic, Gemini, Ollama, Mistral, DeepSeek, Cohere, Groq, xAI e mais) com streaming
 - Chaves de IA **criptografadas em repouso** (AES-256-GCM) atras de uma senha local — nunca em texto puro
 - **Drawer de chat de IA** nos docs + um **console \`/ai\`** dedicado
-- Sistema de 64 temas (variantes escuras e claras); execução local e no GitHub Pages
+- Sistema de 124 temas (variantes escuras e claras); execução local e no GitHub Pages
 `,
     functionalities: `# Funcionalidades
 
@@ -313,9 +314,19 @@ Principais chaves:
 - \`layoutsConfigPath\`: fallback remoto para layouts
 - \`rendering\`: URL canonica publicada
 
+## Voltar ao topo em páginas longas
+
+A seta de voltar ao topo nas páginas de documentação e em \`/introduction-guide\` é controlada por \`site.backToTop\` em \`gitpagedocs/config.json\`:
+
+\`\`\`json
+{ "site": { "backToTop": { "enabled": true, "minPageHeightViewports": 3 } } }
+\`\`\`
+
+Por padrão, a seta fica habilitada somente em uma página com rolagem cuja altura total seja pelo menos três vezes a altura da área visível do navegador. Use \`enabled: false\` para ocultá-la. \`minPageHeightViewports\` aceita um número finito maior que \`1\`; valores ausentes ou inválidos usam \`3\`. Por exemplo, \`4\` exige uma página com pelo menos quatro alturas da área visível. O limiar mede a altura total da página, não a distância já percorrida. A mesma configuração controla as páginas de documentação e o guia de introdução.
+
 ## Controles de idioma, tema, foco, navegação rápida, PDF e documentos
 
-Em \`gitpagedocs/config.json\`, estas entradas de \`site.icons\` configuram idioma, tema, foco, navegação Ctrl+K, ações PDF e navegação no rodapé dos documentos. Os oito controles usam React Icons por padrão:
+Em \`gitpagedocs/config.json\`, estas entradas de \`site.icons\` configuram idioma, tema, versão, foco, navegação Ctrl+K, ações PDF e navegação no rodapé dos documentos. Os nove controles usam React Icons por padrão:
 
 \`\`\`json
 {
@@ -333,6 +344,10 @@ Em \`gitpagedocs/config.json\`, estas entradas de \`site.icons\` configuram idio
         "reactIcon": true, "tag": "LuBookOpen", "size": "22px",
         "colorDark": "currentColor", "colorLight": "currentColor"
       },
+      "VersionSelector": {
+        "reactIcon": true, "tag": "LuGitBranch", "size": "22px",
+        "colorDark": "currentColor", "colorLight": "currentColor"
+      },
       "QuickNavigation": {
         "reactIcon": true, "tag": "LuSearch", "size": "22px",
         "colorDark": "currentColor", "colorLight": "currentColor"
@@ -364,6 +379,8 @@ Configs compactos podem mover valores comuns para \`site.icons.defaults\`; campo
 
 ## Seção \`VersionControl\`
 
+\`site.icons.VersionSelector\` usa \`LuGitBranch\` por padrão. Defina \`reactIcon: false\` para mostrar o texto da versão selecionada; \`true\` mostra o ícone. Personalize os mesmos campos \`tag\`, \`size\`, \`colorDark\` e \`colorLight\`. O seletor aparece somente quando há mais de uma versão de documentação, preserva o nome acessível localizado do seletor e mostra a versão selecionada no tooltip.
+
 \`VersionControl.versions\` define:
 
 - \`id\`: identificador da versão
@@ -624,7 +641,7 @@ Temas são templates JSON mapeados por \`layoutsConfig.json\`.
 
 ## Modelo de template
 
-Cada template normalmente contem:
+Cada template normalmente contém:
 
 - \`id\`, \`name\`, \`author\`, \`version\`
 - \`mode\` e metadados de par dark/light
@@ -639,11 +656,11 @@ Cada template normalmente contem:
 - toggle light/dark resolve o tema pareado por referência
 - variáveis CSS são geradas dos tokens do template
 
-## Boas praticas
+## Boas práticas
 
-- mantenha contraste acessivel
-- padronize escala de espaco e borda
-- ofereca variantes dark e light quando possível
+- mantenha contraste acessível
+- padronize escala de espaço e borda
+- ofereça variantes dark e light quando possível
 
 ## Escolher e personalizar
 
@@ -652,6 +669,8 @@ Escolha um tema pelo seletor ou configure \`site.ThemeDefault\` com seu ID exato
 No seu repositório, execute a CLI com \`--layoutconfig\`, edite o template gerado e mantenha o ID coerente com \`layoutsConfig.json\`. O conteúdo da rota e \`site.icons\` são independentes do catálogo de temas. Use \`currentColor\` para ícones que herdam a cor do texto ou configure cores claras/escuras com contraste suficiente.
 
 Ao contribuir no Git Page Docs, a fonte autoral é \`gitpagelayouts/v2/base.json\` com \`gitpagelayouts/v2/layouts/<id>.json\`. Execute \`pnpm layouts:sync\` para gerar templates e documentação. Edições diretas nos templates gerados podem ser substituídas pela sincronização.
+
+${THEME_BACKGROUND_DOCS.pt}
 `,
     mcp: `# Servidor MCP
 
@@ -712,7 +731,7 @@ Selecione o provedor com \`configure_ai_provider\` ou pelo arquivo \`.gitpagedoc
 | \`fireworks\` | \`FIREWORKS_API_KEY\` |
 | \`perplexity\` | \`PERPLEXITY_API_KEY\` |
 
-Sem seleção válida, o provedor padrão é OpenAI. Ollama não exige chave de API; o serviço local e o modelo escolhido precisam estar disponíveis. \`OLLAMA_BASE_URL\` é opcional. A URL base do Azure é a URL completa da operação de chat, incluindo deployment e versão da API quando exigidos. A lista de modelos é um catálogo distribuído, não uma verificação de disponibilidade em tempo real.
+Quando a seleção salva está ausente, ilegível ou contém JSON inválido, o provedor padrão é OpenAI. Um ID de provedor desconhecido em JSON legível gera erro explícito, sem selecionar outro provedor. Ollama não exige chave de API; o serviço local e o modelo escolhido precisam estar disponíveis. \`OLLAMA_BASE_URL\` é opcional. A URL base do Azure é a URL completa da operação de chat, incluindo deployment e versão da API quando exigidos. A lista de modelos é um catálogo distribuído, não uma verificação de disponibilidade em tempo real.
 
 ## Referência de tools
 
@@ -768,7 +787,7 @@ A etapa de geração envia o conteúdo selecionado do projeto ao provedor config
 
 - Leitura de arquivos: até 512.000 bytes. Listagem: até 2.000 entradas; árvores coletadas do projeto: 400 entradas.
 - Busca: até 5.000 entradas, 200 resultados e 240 caracteres por linha encontrada.
-- Coleta de documentação: primeiros 40 arquivos Markdown entre até 2.000 entradas; arquivos acima de 40.000 bytes são ignorados. O contexto do provedor é limitado a 24.000 caracteres.
+- Coleta de documentação: primeiros 40 arquivos Markdown entre até 2.000 entradas; arquivos acima de 40.000 bytes são ignorados. O contexto coletado de arquivos e Markdown é limitado a 24.000 caracteres. Isso não é um limite global do prompt: árvore/pacote, documento existente e pergunta fornecida podem acrescentar conteúdo conforme a tool escolhida.
 - A listagem ignora pastas de dependências/build como \`node_modules\`, \`.git\`, \`.next\`, \`out\`, \`dist\`, \`prebuilt\`, \`.turbo\` e \`coverage\`. Não interpreta \`.gitignore\`; arquivos como \`.env\` não são excluídos automaticamente. Execute somente em projeto confiável e selecione o conteúdo que será exposto.
 - A verificação de caminhos é lexical; o processo não é um sandbox do sistema operacional nem garante isolamento de symlinks/junctions. Ler \`project://config\` pode importar configuração JavaScript/TypeScript.
 - Falhas de tools incluem \`isError: true\`. Resources ausentes retornam \`Unavailable: ...\`. Consulte stderr no cliente para falhas de inicialização; stdout é reservado para JSON-RPC.
@@ -1002,7 +1021,7 @@ O download conserva o nome-base Markdown do \`path\` localizado da rota; quando
 
 O diálogo possui nome acessível, gerenciamento de foco do teclado e controle de fechar. Use Tab para percorrer controles e Escape para fechar. Controles só com ícone continuam com seus nomes traduzidos acessíveis. Fechar o diálogo retorna à documentação.
 
-A narração é configurada separadamente em Acessibilidade. Trocar documento ou idioma cancela a narração anterior, evitando continuar a leitura de conteúdo antigo.
+A narração é configurada separadamente em Acessibilidade. No modo foco, lê somente a seção exibida. Trocar seção, documento ou idioma, entrar ou sair do modo foco interrompe a fala anterior; a próxima leitura começa no conteúdo visível. As preferências de voz, velocidade e volume são mantidas. Com \`sectionNavigationEnabled: false\`, o documento inteiro fica visível e disponível para narração. Copiar/baixar continua incluindo a fonte original completa.
 `,
     accessibility: `# Acessibilidade e narração
 
@@ -1043,7 +1062,9 @@ Mescle estas opções em \`gitpagedocs/config.json\`:
 
 A narração começa somente após sua ação; não há reprodução automática. A seleção automática de voz acompanha o idioma do documento; escolher uma voz explicitamente utiliza o idioma dessa voz. A narração não traduz o documento.
 
-A fala usa texto legível extraído do Markdown renderizado. Scripts, estilos, conteúdo SVG e elementos ocultos para tecnologias assistivas são excluídos. Documentos longos são lidos por inteiro em blocos sucessivos. Trocar documento ou idioma, desabilitar a narração ou sair da página cancela a fala anterior.
+A fala usa texto legível extraído do Markdown renderizado. Scripts, estilos, conteúdo SVG e elementos ocultos para tecnologias assistivas são excluídos. O conteúdo visível longo é lido por inteiro em blocos sucessivos. Trocar documento ou idioma, desabilitar a narração ou sair da página cancela a fala anterior.
+
+No modo foco, a narração usa somente a seção exibida. Trocar seção ou documento, entrar ou sair do modo foco interrompe a leitura anterior. Inicie novamente para ler o conteúdo que passou a estar visível. Com \`site.focusMode.sectionNavigationEnabled: false\`, o documento inteiro fica visível e pode ser narrado. Essas transições preservam a voz, a velocidade e o volume selecionados.
 
 A visualização comum e o modo foco compartilham preferências de voz, velocidade e volume enquanto a página permanece montada. As preferências não são salvas entre recarregamentos. Valores não numéricos de velocidade ou volume usam \`1\`; valores numéricos fora das faixas suportadas são limitados ao extremo mais próximo.
 
@@ -1095,7 +1116,7 @@ Porque o build de GitHub Pages habilita página inicial de busca e comportamento
 
 ## Por que o ícone ainda mostra texto?
 
-Defina \`site.icons.<Controle>.reactIcon\` como booleano \`true\`, com o nome exato exportado por React Icons em \`tag\`. LanguageSelector, ThemeSelector, FocusMode, QuickNavigation, PdfDownload, PdfOpenInNewTab, DocumentPrevious e DocumentNext usam ícones por padrão; altere qualquer entrada para \`false\` para exibir texto. Campos planos \`Icon*ReactIcones\` prevalecem se os dois formatos existirem. Confira se o próprio recurso está desabilitado por opções como \`HideThemeSelector\`, \`FocusMode\` ou as ações PDF.
+Defina \`site.icons.<Controle>.reactIcon\` como booleano \`true\`, com o nome exato exportado por React Icons em \`tag\`. LanguageSelector, ThemeSelector, VersionSelector, FocusMode, QuickNavigation, PdfDownload, PdfOpenInNewTab, DocumentPrevious e DocumentNext usam ícones por padrão; altere qualquer entrada para \`false\` para exibir texto. Campos planos \`Icon*ReactIcones\` prevalecem se os dois formatos existirem. Confira se o próprio recurso está desabilitado por opções como \`HideThemeSelector\`, \`FocusMode\` ou as ações PDF.
 
 ## Por que filhos de menus ou breadcrumbs aparecem diferentes?
 

package/content/practical-en.mjs

@@ -13,7 +13,7 @@ Add this route to the version configuration's existing \`routes-html\` array. Ke
 ${HTML_ROUTE_JSON}
 \`\`\`
 
-Add a localized item in \`menus-header-html\`. Each \`path-click\` must match its language's route path, such as \`gitpagedocs/docs/versions/0.0.11/en/doom.html\`; do not substitute \`page:29\` for this local HTML path. Menu labels do not create routes. HTML uses the same recursive \`submenus\` structure as other menus.
+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.13/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
 
@@ -35,9 +35,9 @@ This guide builds a small multilingual documentation site with two Markdown page
 
 ## 1. Generate and inspect the scaffold
 
-The scaffold includes versions 0.0.11 and 0.0.10 in the version selector. Both contain the current examples; the package version remains 0.0.11. Their paths and version badges are generated for the selected documentation version. Older existing version folders are not deleted.
+The scaffold includes versions 0.0.13, 0.0.12, 0.0.11, 0.0.10 and 0.0.9 in the version selector, newest first. All five contain the current examples; the package version is 0.0.13. Their paths and version badges are generated for the selected documentation version. Older existing version folders are not deleted.
 
-Run \`npx --yes @gitpagedocs/cli@0.0.11 --no-interactive --owner YOUR_USER --repo YOUR_REPOSITORY\` in a new project directory. In this source repository, \`node cli/index.mjs\` runs the checked-out version. Generation writes configuration and documentation; it does not start the Next.js viewer.
+Run \`npx --yes @gitpagedocs/cli@0.0.13 --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.
 
@@ -45,7 +45,7 @@ Use the following complete JSON as a minimal root-config example in \`gitpagedoc
 ${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.
+The nine 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