@gitpagedocs/cli 0.0.11 → 0.0.12

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.12 registers documentation versions 0.0.12, 0.0.11 and 0.0.10 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.12/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.12/en/gitpagedocs-project-guide.pdf",
+        "pt": "gitpagedocs/docs/versions/0.0.12/en/gitpagedocs-project-guide.pdf",
+        "es": "gitpagedocs/docs/versions/0.0.12/en/gitpagedocs-project-guide.pdf"
       },
       "previewEnabled": true,
       "downloadEnabled": true,
@@ -434,7 +435,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 +449,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 +488,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 +706,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 +768,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 +824,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.
@@ -1142,7 +1151,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.12/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.12/en/gitpagedocs-project-guide.pdf",
+        "pt": "gitpagedocs/docs/versions/0.0.12/en/gitpagedocs-project-guide.pdf",
+        "es": "gitpagedocs/docs/versions/0.0.12/en/gitpagedocs-project-guide.pdf"
       },
       "previewEnabled": true,
       "downloadEnabled": true,
@@ -315,7 +316,7 @@ Claves principales:
 
 ## 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 +334,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 +369,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 +646,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 +659,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 +721,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 +777,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.
@@ -1095,7 +1104,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.12/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.12/en/gitpagedocs-project-guide.pdf",
+        "pt": "gitpagedocs/docs/versions/0.0.12/en/gitpagedocs-project-guide.pdf",
+        "es": "gitpagedocs/docs/versions/0.0.12/en/gitpagedocs-project-guide.pdf"
       },
       "previewEnabled": true,
       "downloadEnabled": true,
@@ -315,7 +316,7 @@ Principais chaves:
 
 ## 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 +334,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 +369,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 +631,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 +646,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 +659,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 +721,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 +777,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.
@@ -1095,7 +1104,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.12/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.12, 0.0.11 and 0.0.10 in the version selector. All three contain the current examples; the package version is 0.0.12. 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.12 --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
 

package/content/practical-es.mjs

@@ -13,7 +13,7 @@ Añade esta ruta al array \`routes-html\` existente en la configuración de la v
 ${HTML_ROUTE_JSON}
 \`\`\`
 
-Añade un elemento traducido en \`menus-header-html\`. Cada \`path-click\` debe coincidir con la ruta de su idioma, como \`gitpagedocs/docs/versions/0.0.11/es/doom.html\`; no sustituyas esta ruta HTML local por \`page:29\`. Una etiqueta de menú no crea una ruta. HTML admite la misma estructura recursiva \`submenus\` que los demás menús.
+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.12/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
 
@@ -35,9 +35,9 @@ Esta guía crea un sitio pequeño en tres idiomas, con dos páginas Markdown y u
 
 ## 1. Genera y revisa la estructura
 
-El scaffold incluye las versiones 0.0.11 y 0.0.10 en el selector. Ambas contienen los ejemplos actuales; la versión del paquete sigue siendo 0.0.11. Las rutas y etiquetas se generan para la versión correspondiente de la documentación. No se eliminan las carpetas existentes de versiones anteriores.
+El scaffold incluye las versiones 0.0.12, 0.0.11 y 0.0.10 en el selector. Las tres contienen los ejemplos actuales; la versión del paquete es 0.0.12. Las rutas y etiquetas se generan para la versión correspondiente de la documentación. No se eliminan las carpetas existentes de versiones anteriores.
 
-Ejecuta \`npx --yes @gitpagedocs/cli@0.0.11 --no-interactive --owner TU_USUARIO --repo TU_REPOSITORIO\` en un directorio de proyecto nuevo. En este repositorio de código fuente, \`node cli/index.mjs\` ejecuta la versión del checkout. La generación escribe configuración y documentación; no inicia el visor Next.js.
+Ejecuta \`npx --yes @gitpagedocs/cli@0.0.12 --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.
 
@@ -45,7 +45,7 @@ El siguiente JSON completo es un ejemplo mínimo de \`gitpagedocs/config.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.
+Las nueve 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
 

package/content/practical-pt.mjs

@@ -13,7 +13,7 @@ Adicione esta rota ao array \`routes-html\` existente na configuração da vers
 ${HTML_ROUTE_JSON}
 \`\`\`
 
-Adicione um item traduzido em \`menus-header-html\`. Cada \`path-click\` deve corresponder ao caminho da rota no mesmo idioma, como \`gitpagedocs/docs/versions/0.0.11/pt/doom.html\`; não substitua esse caminho HTML local por \`page:29\`. Um rótulo de menu não cria uma rota. HTML aceita a mesma estrutura recursiva \`submenus\` dos outros menus.
+Adicione um item traduzido em \`menus-header-html\`. Cada \`path-click\` deve corresponder ao caminho da rota no mesmo idioma, como \`gitpagedocs/docs/versions/0.0.12/pt/doom.html\`; não substitua esse caminho HTML local por \`page:29\`. Um rótulo de menu não cria uma rota. HTML aceita a mesma estrutura recursiva \`submenus\` dos outros menus.
 
 ## Dimensões, conteúdo e URLs externas
 
@@ -35,9 +35,9 @@ Este guia monta um site pequeno em três idiomas, com duas páginas Markdown e m
 
 ## 1. Gere e confira a estrutura
 
-O scaffold inclui as versões 0.0.11 e 0.0.10 no seletor. Ambas contêm os exemplos atuais; a versão do pacote continua sendo 0.0.11. Caminhos e rótulos de versão são gerados para a versão correspondente da documentação. Pastas existentes de versões anteriores não são apagadas.
+O scaffold inclui as versões 0.0.12, 0.0.11 e 0.0.10 no seletor. As três contêm os exemplos atuais; a versão do pacote é 0.0.12. Caminhos e rótulos de versão são gerados para a versão correspondente da documentação. Pastas existentes de versões anteriores não são apagadas.
 
-Execute \`npx --yes @gitpagedocs/cli@0.0.11 --no-interactive --owner SEU_USUARIO --repo SEU_REPOSITORIO\` em um diretório de projeto novo. Neste repositório de código-fonte, \`node cli/index.mjs\` executa a versão do checkout. A geração grava configuração e documentação; ela não inicia o visualizador Next.js.
+Execute \`npx --yes @gitpagedocs/cli@0.0.12 --no-interactive --owner SEU_USUARIO --repo SEU_REPOSITORIO\` em um diretório de projeto novo. Neste repositório de código-fonte, \`node cli/index.mjs\` executa a versão do checkout. A geração grava configuração e documentação; ela não inicia o visualizador Next.js.
 
 O JSON completo abaixo é um exemplo mínimo de \`gitpagedocs/config.json\`. Em um site existente, mescle os campos relevantes e preserve a identidade do repositório, opções de publicação, temas e demais versões.
 
@@ -45,7 +45,7 @@ O JSON completo abaixo é um exemplo mínimo de \`gitpagedocs/config.json\`. Em
 ${RECIPE_ROOT_JSON}
 \`\`\`
 
-As oito entradas herdam a apresentação comum de \`icons.defaults\`. Para mostrar texto em uma ação, acrescente \`"reactIcon": false\` à entrada correspondente. Não altere um default compartilhado apenas para mudar um botão. Campos planos antigos de ícones prevalecem sobre os compactos; remova ou atualize um campo conflitante somente depois de confirmar sua intenção.
+As nove entradas herdam a apresentação comum de \`icons.defaults\`. Para mostrar texto em uma ação, acrescente \`"reactIcon": false\` à entrada correspondente. Não altere um default compartilhado apenas para mudar um botão. Campos planos antigos de ícones prevalecem sobre os compactos; remova ou atualize um campo conflitante somente depois de confirmar sua intenção.
 
 ## 2. Crie a configuração da versão