@gitpagedocs/cli 1.1.62 → 1.1.63

package/content/docs-es.mjs

@@ -1,462 +1,462 @@
-export const docsEs = {
-    index: `# Git Page Docs
-
-Git Page Docs es un runtime de documentacion multilenguaje para repositorios que incluyen la carpeta \`gitpagedocs/\`.
-
-## Que entrega este proyecto
-
-- Renderizado markdown multilenguaje (\`en\`, \`pt\`, \`es\`)
-- Ruteo por version (\`/v/:version\`)
-- Sistema de temas con templates JSON
-- Ejecucion local y en GitHub Pages
-- Busqueda de repositorio + render remoto opcional
-
-## Contrato de carpetas
-
-El runtime espera esta estructura:
-
-- \`gitpagedocs/config.json\`
-- \`gitpagedocs/docs/<lang>/*.md\`
-- \`gitpagedocs/docs/versions/<version>/config.json\`
-- \`gitpagedocs/docs/versions/<version>/<lang>/*.md\`
-- \`gitpagelayouts/layoutsConfig.json\`
-- \`gitpagelayouts/templates/*.json\`
-
-## Navegacion rapida
-
-- Abre **Primeros pasos** para setup local.
-- Abre **Configuracion** para detalle completo de \`config.json\`.
-- Abre **Publicacion** para comportamiento local/produccion/GitHub Pages.
-- Abre **Arquitectura** para mapa de codigo y flujo de datos.
-- Abre **Temas y layouts** para creacion de templates.
-- Abre **Rutas autorizadas** para configurar clave, roles y autenticacion externa.
-- Abre **FAQ** para troubleshooting.
-`,
-    gettingStarted: `# Primeros pasos
-
-Esta guia lleva el proyecto desde cero hasta docs corriendo.
-
-## Requisitos
-
-- Node.js 20+
-- npm 10+ (o pnpm)
-
-## Setup local
-
-1. Instala dependencias:
-   - \`npm install\`
-2. Genera/actualiza artefactos de docs:
-   - \`npm run gitpagedocs\`
-3. Inicia desarrollo:
-   - \`npm run dev\`
-4. Build + ejecucion local de produccion:
-   - \`npm run build\`
-   - \`npm start\`
-
-## Comportamiento de la CLI
-
-\`npx @gitpagedocs/cli\` (o \`npm run gitpagedocs\`) genera artefactos en la carpeta oficial \`gitpagedocs/\`.
-
-- Genera solo markdown/json
-- No genera \`index.html\`
-- No genera \`index.js\`
-- No ejecuta comandos de instalacion
-
-## Modo de busqueda por repositorio
-
-En local, se controla por variable:
-
-- \`GITPAGEDOCS_REPOSITORY_SEARCH=true\`
-- \`GITPAGEDOCS_REPOSITORY_SEARCH=false\`
-
-En build de GitHub Pages (\`GITHUB_ACTIONS=true\`), la busqueda de repositorio siempre esta activa.
-`,
-    projectOverview: `# Vision general del proyecto
-
-Git Page Docs es un monorepo pnpm + turborepo que convierte la carpeta \`gitpagedocs/\` de un repositorio en un sitio de documentacion multilingue y versionado — con un asistente de IA integrado y un servidor MCP (Model Context Protocol).
-
-## Paquetes del monorepo
-
-- **frontend/** — visor Next.js 15 (App Router, React 19), exportado estaticamente para GitHub Pages.
-- **cli/** — el paquete npm publicado \`@gitpagedocs/cli\` (\`npm install -g @gitpagedocs/cli\`): genera la estructura de docs, documenta con IA, configura Pages y ejecuta el servidor MCP.
-- **tools/** — \`@gitpagedocs/tools\`, el nucleo de logica compartido: sistema de IA con 14 proveedores, boveda de credenciales cifrada, cargador de config, caches y logger.
-- **mcp/** — \`@gitpagedocs/mcp\`, servidor Model Context Protocol (20 herramientas + 7 recursos).
-- **gitpagedocs/** — el contrato del usuario: \`config.json\`, docs versionados y layouts.
-
-## Stack
-
-- Next.js 15 (App Router) + React 19 + TypeScript; exportacion estatica para GitHub Pages
-- gray-matter + marked para Markdown; react-icons
-- pnpm workspaces + turborepo; Vitest + Playwright; ESLint
-
-## Destacados
-
-- Multilingue (\`en\`, \`pt\`, \`es\`) y rutas por version (\`/v/:version\`)
-- Sistema de IA con 14 proveedores (OpenAI, Anthropic, Gemini, Ollama, Mistral, DeepSeek, Cohere, Groq, xAI y mas) con streaming
-- Claves de IA **cifradas en reposo** (AES-256-GCM) detras de una contrasena local — nunca en texto plano
-- **Panel de chat de IA** en los docs + una **consola \`/ai\`** dedicada
-- Sistema de 36 temas; ejecucion local y en GitHub Pages
-`,
-    functionalities: `# Funcionalidades
-
-Referencia completa de opciones CLI, claves de configuracion y funciones del runtime.
-
-## Comandos CLI
-
-| Comando | Descripcion |
-|---------|-------------|
-| \`npx @gitpagedocs/cli\` | Genera config y docs en \`gitpagedocs/\` |
-| \`npx @gitpagedocs/cli --layoutconfig\` | Tambien genera layouts/templates locales en \`gitpagelayouts/\` |
-| \`npx @gitpagedocs/cli --home\` | Distribucion standalone (\`gitpagedocshome/\`) |
-| \`npx @gitpagedocs/cli --push --owner X --repo Y\` | Configura workflow, commit, push |
-| \`npx @gitpagedocs/cli --interactive\` / \`-i\` | Modo interactivo con prompts (por defecto en una terminal) |
-| \`npx @gitpagedocs/cli --no-interactive\` / \`-y\` | Nunca pregunta; usa flags y valores por defecto |
-
-## Opciones CLI
-
-| Opcion | Descripcion |
-|--------|-------------|
-| \`--owner <user>\` | Owner de GitHub |
-| \`--repo <repo>\` | Repositorio GitHub |
-| \`--path <subpath>\` | Subruta de docs (ej: \`docs\`); sin ella, base path = nombre del repo para CSS/JS en project sites |
-| \`--output <dir>\` | Directorio de salida (default: \`gitpagedocs\`) |
-| \`--search true|false\` | Habilita/deshabilita busqueda de repositorio (\`--home\`) |
-| \`--layoutconfig\` | Genera layouts locales en \`gitpagelayouts/\` |
-| \`--layouts-dir <dir>\` | Carpeta de layouts locales (por defecto: \`gitpagelayouts\`) |
-| \`--push\` | Crea workflow, commit de artefactos, push |
-| \`--home\` | Genera \`gitpagedocshome/\` (estatico + .env + Dockerfile) |
-
-## Salida generada
-
-- \`gitpagedocs/config.json\` – config raiz
-- \`gitpagedocs/icon.svg\` – icono por defecto
-- \`gitpagedocs/docs/versions/<ver>/config.json\` – rutas por version
-- \`gitpagedocs/docs/versions/<ver>/{en,pt,es}/*.md\` – docs en markdown
-- \`gitpagelayouts/\` – solo con \`--layoutconfig\` (carpeta configurable con \`--layouts-dir\`)
-
-## Tipos de contenido
-
-| Tipo | Clave config | Descripcion |
-|------|--------------|-------------|
-| Markdown | \`routes-md\` | Archivos .md con \`path\` por idioma |
-| HTML | \`routes-html\` | \`path\` local o \`url\` externa |
-| Video | \`routes-video\` | \`video.pathVideo\`, \`video.videoType\` |
-| Audio | \`routes-audio\` | \`audio.pathAudio\`, \`audio.audioType\` |
-
-## Visor de codigo fuente
-
-El config de version puede renderizar un contenedor **Codigo fuente** via \`routes-source-viewer\` y \`menus-header-source-viewer\`. El viewer lee el arbol del repositorio en GitHub en tiempo de ejecucion y aplica el tema actual de la documentacion.
-
-- Arbol del repositorio desde \`source-viewer-path\`; la branch por defecto es \`main\`
-- Navegacion por carpetas y filtro de archivos
-- Listado de directorios estilo GitHub
-- Renderizado de codigo con numeros de linea
-- Alternancia vista previa/codigo para Markdown, incluido \`README.md\`
-- Carpetas colapsables en la barra lateral
-
-## Claves de config (site)
-
-- \`name\`, \`defaultLanguage\`, \`supportedLanguages\`
-- \`docsVersion\`, \`rendering\`, \`ThemeDefault\`, \`ThemeModeDefault\`
-- \`ProjectLink\`, \`layoutsConfigPathOficial\`, \`layoutsConfigPath\`
-
-## Variables de entorno
-
-- \`GITPAGEDOCS_REPOSITORY_SEARCH\` – busqueda de repositorio (local)
-- \`GITHUB_ACTIONS\` – modo build GitHub Pages
-`,
-    configuration: `# Configuracion
-
-La configuracion de runtime esta en \`gitpagedocs/config.json\`.
-
-## Seccion \`site\`
-
-Claves principales:
-
-- \`name\`: titulo del proyecto en UI
-- \`defaultLanguage\`: idioma por defecto
-- \`supportedLanguages\`: lista de idiomas disponibles
-- \`HideThemeSelector\`: ocultar/mostrar selector de tema
-- \`ThemeDefault\`: id del tema inicial
-- \`ThemeModeDefault\`: modo inicial (\`light\` o \`dark\`)
-- \`ProjectLink\`: URL de repositorio para acciones de cabecera
-- \`docsVersion\`: version seleccionada por defecto
-- \`ActiveNavigation\`: habilita anterior/siguiente
-- \`FocusMode\`: habilita modo foco/lectura
-- \`IconImageMenuHeaderImgWidth\`, \`IconImageMenuHeaderImgHeight\`: tamano del icono principal
-- \`IconImageMenuHeaderLightImg\`, \`IconImageMenuHeaderDarkImg\`: icono principal (light/dark)
-- \`IconProjectLinkImgWidth\`, \`IconProjectLinkImgHeight\`: tamano del icono enlace del proyecto
-- \`IconProjectLinkLightImg\`, \`IconProjectLinkDarkImg\`: icono enlace del proyecto
-- \`IconVersionLinksImgWidth\`, \`IconVersionLinksImgHeight\`: tamano del icono enlaces de version
-- \`IconVersionLinksLightImg\`, \`IconVersionLinksDarkImg\`: icono enlaces de version
-- \`IconInfoHeaderMenuImgWidth\`, \`IconInfoHeaderMenuImgHeight\`: tamano del icono info
-- \`IconInfoHeaderMenuLightImg\`, \`IconInfoHeaderMenuDarkImg\`: icono info
-- \`IconPreviewProjectLinkImgWidth\`, \`IconPreviewProjectLinkImgHeight\`: tamano del icono preview
-- \`IconPreviewProjectLinkLightImg\`, \`IconPreviewProjectLinkDarkImg\`: icono preview
-- \`layoutsConfigPath\`: fallback remoto de layouts
-- \`rendering\`: URL canonica publicada
-
-## Seccion \`VersionControl\`
-
-\`VersionControl.versions\` define:
-
-- \`id\`: identificador de version
-- \`path\`: ruta de config de version
-- links opcionales (\`ProjectLink\`, \`branch\`, \`release\`, \`commit\`)
-- metadatos opcionales del source viewer (\`source-viewer\`, \`source-viewer-path\`)
-
-## Navegacion y rutas
-
-- \`routes\`: rutas markdown por idioma (legado)
-- \`menus-header\`: menu jerarquico
-- \`translations\`: etiquetas UI para not-found y navegacion
-
-## Autorizacion (config de version)
-
-- \`auth\`: configuraciones globales de autorizacion para esa version
-- \`auth.accessKeys\`: mapa de claves usado por \`authorization.accessKeyId\`
-- \`auth.rolesStorageKey\`: clave de localStorage para bootstrap de roles
-- \`auth.providers\`: adaptadores de proveedor (\`authjs\`, \`clerk\`, \`firebase\`, \`jwt\`)
-
-## Tipos de contenido (config de version)
-
-Los configs de version soportan multiples tipos:
-
-- \`routes-md\`: Rutas markdown con \`title\`, \`description\` (centrados via \`titlePosition\`, \`descriptionPosition\`)
-- \`routes-source-viewer\`: Contenedores de codigo fuente con \`source-viewer: true\` y \`source-viewer-path\`
-- \`routes-html\`: Rutas de paginas HTML por idioma
-- \`routes-video\`: Config de video con \`video.videoType\` (youtube, vimeo, mp4, etc.) y \`video.pathVideo\`
-- \`routes-audio\`: Config de audio con \`audio.audioType\` (youtube, mp3, etc.) y \`audio.pathAudio\`
-- \`authorization\` (md/html/video): guardia de acceso por clave, roles y autenticacion externa
-- \`menus-header-md\`, \`menus-header-source-viewer\`, \`menus-header-html\`, \`menus-header-video\`, \`menus-header-audio\`: menus por tipo
-- \`hierarchyPage\`: orden de contenedores en la pagina \`{ md: 0, "source-viewer": 1, html: 2, video: 3, audio: 4 }\`
-- \`hierarchyMenu\`: orden de secciones del menu \`{ md: 0, "source-viewer": 1, html: 2, video: 3, audio: 4 }\`
-
-Cada ruta puede incluir \`title\`, \`description\` (por idioma), \`titleCss\`, \`titlePosition: "center"\`, \`descriptionPosition: "center"\`, \`titleIsVisible\`, \`descriptionIsVisible\`.
-
-## Variables por ruta (blockLink, container, url, browseAll)
-
-Opciones por ruta en \`routes-md\`, \`routes-html\` y \`routes-video\`:
-
-- **\`blockLink\`** (defecto: true) – Para HTML: si true, los enlaces abren en nueva pestaña (\`target="_blank"\`); si false, en el mismo contexto.
-- **\`container\`** – \`"full"\` = altura automatica; numero (ej: \`500\`) = altura fija en px con overflow auto. Se aplica a md, html y video.
-- **\`url\`** – Solo en \`routes-html\`: \`Record<LanguageCode, string>\` con URLs externas. Al definirse, el iframe usa \`src={url}\` en vez de HTML local via \`srcDoc\`. Las rutas con \`url\` no generan archivos HTML locales.
-- **\`browseAll\`** (defecto: false) – Si true, el contenedor muestra botones Anterior/Siguiente para navegar entre todos los items de ese tipo.
-
-## Tipos de contenido: path vs url (HTML)
-
-- **Markdown (\`routes-md\`)**: usa \`path\` apuntando a archivos \`.md\` locales.
-- **HTML (\`routes-html\`)**: usa \`path\` para archivos HTML locales (sin extension .html en config) o \`url\` para URLs externas. Con \`url\`, el iframe carga la pagina externa; no se genera archivo local.
-- **Video (\`routes-video\`)**: usa \`video.pathVideo\` y \`video.videoType\` (youtube, vimeo, mp4, etc.).
-
-## Variables de entorno
-
-- \`GITPAGEDOCS_REPOSITORY_SEARCH\`: activa/desactiva busqueda remota en local
-- \`GITHUB_ACTIONS\`: habilita comportamiento especifico de GitHub Pages
-`,
-    deployment: `# Publicacion
-
-Git Page Docs corre como app Next.js con dos objetivos: servidor local y GitHub Pages.
-
-## Publicacion local
-
-Usa:
-
-1. \`npm run build\`
-2. \`npm start\`
-
-Esto inicia runtime Node + Next.js usando \`gitpagedocs/\` local.
-
-## Publicacion en GitHub Pages
-
-En build de GitHub Actions:
-
-- \`GITHUB_ACTIONS=true\`
-- el comportamiento de export estatico se habilita por configuracion
-- la pagina inicial de busqueda de repositorios queda activa
-
-## Flujo de publish del paquete
-
-Para publicar en npm:
-
-- actualiza version en \`package.json\`
-- ejecuta \`npm publish --access public\`
-- valida autenticacion con \`npm whoami\`
-
-Si \`build:prebuilt\` se omite en Windows, usa CI para generar artefactos prebuilt.
-`,
-    architecture: `# Arquitectura
-
-El proyecto esta organizado por fronteras de feature y responsabilidades de runtime.
-
-## Paquetes
-
-- **frontend/** — visor Next.js (Feature-Sliced: app / widgets / features / entities / shared); export estatico.
-- **cli/** — el bin publicado \`gitpagedocs\` (hexagonal) + \`cli/ai/\` (CLI de documentacion con IA).
-- **tools/** — \`@gitpagedocs/tools\`: ai/ security/ crypto/ cache/ config/ logger/ errors/ filesystem/ documentation/ ports/.
-- **mcp/** — \`@gitpagedocs/mcp\`: herramientas + recursos MCP que delegan a tools/.
-
-## Modulos principales (frontend)
-
-- \`frontend/src/app/[[...repo]]/page.tsx\` — parser de rutas, generateStaticParams, seleccion de shell.
-- \`frontend/src/entities/docs/api/load-docs-data.ts\` — config local/remota, version, parse markdown, layouts + temas.
-- \`frontend/src/widgets/docs-shell/docs-shell.tsx\` — UI, estado idioma/version/tema, sync de URL, montaje del chat de IA.
-
-## Seguridad: credenciales de IA cifradas
-
-La consola \`/ai\` y el panel de chat exigen una contrasena local que deriva (PBKDF2) una clave AES-256-GCM; las claves quedan cifradas en \`localStorage\` y solo se descifran durante la sesion (\`@gitpagedocs/tools/security\`).
-
-## Flujo de datos
-
-1. Llega la ruta (\`/owner/repo/v/x.y.z\` o equivalente local)
-2. Se resuelve config (local o remoto)
-3. Config de version sobreescribe rutas/menus base
-4. Markdown se carga y convierte a HTML
-5. Template de layout se resuelve y aplica en CSS vars
-6. Shell renderiza contenido y controles
-
-## Puntos de resiliencia
-
-- fallback de carga para layouts/templates
-- carga de markdown por idioma con fallback de error
-- sincronizacion de idioma/version/tema via localStorage
-`,
-    githubIssuesProjects: `# GitHub Issues y Projects
-
-Aprende a usar GitHub Issues y Projects para gestionar tu trabajo.
-
-## Conceptos
-
-- Issues para rastrear tareas y bugs
-- Projects para visualizar y organizar el trabajo
-- Flujos recomendados para equipos
-`,
-    gitIntroduction: `# Introduccion a Git
-
-Conceptos basicos de Git para principiantes.
-
-## Comandos esenciales
-
-- \`git init\` - iniciar repositorio
-- \`git add\` - preparar cambios
-- \`git commit\` - registrar commit
-- \`git push\` - enviar a remoto
-`,
-    authorizedRoutes: `# Rutas autorizadas
-
-Protege rutas por clave de acceso, roles requeridos y proveedores externos.
-
-## Ubicacion del config de version
-
-Configura en:
-
-- \`gitpagedocs/docs/versions/<version>/config.json\`
-
-## Seccion global auth
-
-Usa \`auth\` en la raiz del config de version:
-
-- \`accessKeys\`: mapa de ids de clave al secreto esperado
-- \`rolesStorageKey\`: clave de localStorage para bootstrap de roles
-- \`providers\`: lista de proveedores externos (\`authjs\`, \`clerk\`, \`firebase\`, \`jwt\`)
-
-## Autorizacion por ruta
-
-Dentro de cada ruta (\`routes-md\`, \`routes-html\`, \`routes-video\`):
-
-- \`authorization.accessKeyId\`
-- \`authorization.requiredRoles\`
-- \`authorization.requireExternalAuth\`
-- \`authorization.allowedProviders\`
-
-## Fases
-
-### Fase A - Clave de acceso
-
-Define \`authorization.accessKeyId\` y la clave correspondiente en \`auth.accessKeys\`.
-
-### Fase B - Roles
-
-Define \`authorization.requiredRoles\` con uno o mas roles.
-
-Los roles pueden venir de:
-
-- query param \`?authRoles=admin,maintainer\`
-- localStorage (\`rolesStorageKey\`)
-- claims de proveedores externos
-
-### Fase C - Proveedores externos
-
-Define \`authorization.requireExternalAuth=true\` y opcionalmente \`allowedProviders\`.
-
-Adaptadores soportados:
-
-- Auth.js (\`type: "authjs"\`)
-- Clerk (\`type: "clerk"\`)
-- Firebase Auth (\`type: "firebase"\`)
-- JWT custom (\`type: "jwt"\`)
-`,
-    themes: `# Temas y layouts
-
-Los temas son templates JSON mapeados por \`layoutsConfig.json\`.
-
-## Archivos
-
-- \`gitpagelayouts/layoutsConfig.json\`
-- \`gitpagelayouts/layoutsFallbackConfig.json\`
-- \`gitpagelayouts/templates/*.json\`
-
-## Modelo de template
-
-Cada template normalmente incluye:
-
-- \`id\`, \`name\`, \`author\`, \`version\`
-- \`mode\` y metadatos de par dark/light
-- \`colors\`
-- \`typography\`
-- tokens de \`components\`
-- \`animations\`
-
-## Comportamiento en runtime
-
-- tema activo viene de config/seleccion de usuario
-- toggle light/dark resuelve tema pareado por referencia
-- variables CSS se generan desde tokens del template
-
-## Buenas practicas
-
-- mantener contraste accesible
-- mantener escala consistente de espacios y bordes
-- ofrecer variantes dark y light cuando sea posible
-`,
-    faq: `# FAQ
-
-## Por que repositorios remotos no abren en local?
-
-Verifica:
-
-- \`GITPAGEDOCS_REPOSITORY_SEARCH=true\` en \`.env\`
-- repositorio objetivo contiene \`gitpagedocs/config.json\`
-- paths markdown del repositorio coinciden con su config de rutas
-
-## Por que una ruta de version muestra contenido incorrecto?
-
-Verifica:
-
-- \`VersionControl.versions[*].path\` en \`gitpagedocs/config.json\`
-- config de version tiene \`routes\` y \`menus-header\` validos
-- markdown existe para cada idioma
-
-## Por que tema no se aplica correctamente?
-
-Verifica:
-
-- \`layoutsConfig.json\` referencia templates validos
-- ids de template son unicos
-- tema seleccionado existe en el mapa de temas cargados
-
-## Por que GitHub Pages puede comportarse distinto a local?
-
-Porque el build de GitHub Pages habilita la pagina inicial de busqueda y comportamiento especifico de exportacion.
-`,
-  };
+export const docsEs = {
+    index: `# Git Page Docs
+
+Git Page Docs es un runtime de documentacion multilenguaje para repositorios que incluyen la carpeta \`gitpagedocs/\`.
+
+## Que entrega este proyecto
+
+- Renderizado markdown multilenguaje (\`en\`, \`pt\`, \`es\`)
+- Ruteo por version (\`/v/:version\`)
+- Sistema de temas con templates JSON
+- Ejecucion local y en GitHub Pages
+- Busqueda de repositorio + render remoto opcional
+
+## Contrato de carpetas
+
+El runtime espera esta estructura:
+
+- \`gitpagedocs/config.json\`
+- \`gitpagedocs/docs/<lang>/*.md\`
+- \`gitpagedocs/docs/versions/<version>/config.json\`
+- \`gitpagedocs/docs/versions/<version>/<lang>/*.md\`
+- \`gitpagelayouts/layoutsConfig.json\`
+- \`gitpagelayouts/templates/*.json\`
+
+## Navegacion rapida
+
+- Abre **Primeros pasos** para setup local.
+- Abre **Configuracion** para detalle completo de \`config.json\`.
+- Abre **Publicacion** para comportamiento local/produccion/GitHub Pages.
+- Abre **Arquitectura** para mapa de codigo y flujo de datos.
+- Abre **Temas y layouts** para creacion de templates.
+- Abre **Rutas autorizadas** para configurar clave, roles y autenticacion externa.
+- Abre **FAQ** para troubleshooting.
+`,
+    gettingStarted: `# Primeros pasos
+
+Esta guia lleva el proyecto desde cero hasta docs corriendo.
+
+## Requisitos
+
+- Node.js 20+
+- npm 10+ (o pnpm)
+
+## Setup local
+
+1. Instala dependencias:
+   - \`npm install\`
+2. Genera/actualiza artefactos de docs:
+   - \`npm run gitpagedocs\`
+3. Inicia desarrollo:
+   - \`npm run dev\`
+4. Build + ejecucion local de produccion:
+   - \`npm run build\`
+   - \`npm start\`
+
+## Comportamiento de la CLI
+
+\`npx @gitpagedocs/cli\` (o \`npm run gitpagedocs\`) genera artefactos en la carpeta oficial \`gitpagedocs/\`.
+
+- Genera solo markdown/json
+- No genera \`index.html\`
+- No genera \`index.js\`
+- No ejecuta comandos de instalacion
+
+## Modo de busqueda por repositorio
+
+En local, se controla por variable:
+
+- \`GITPAGEDOCS_REPOSITORY_SEARCH=true\`
+- \`GITPAGEDOCS_REPOSITORY_SEARCH=false\`
+
+En build de GitHub Pages (\`GITHUB_ACTIONS=true\`), la busqueda de repositorio siempre esta activa.
+`,
+    projectOverview: `# Vision general del proyecto
+
+Git Page Docs es un monorepo pnpm + turborepo que convierte la carpeta \`gitpagedocs/\` de un repositorio en un sitio de documentacion multilingue y versionado — con un asistente de IA integrado y un servidor MCP (Model Context Protocol).
+
+## Paquetes del monorepo
+
+- **frontend/** — visor Next.js 15 (App Router, React 19), exportado estaticamente para GitHub Pages.
+- **cli/** — el paquete npm publicado \`@gitpagedocs/cli\` (\`npm install -g @gitpagedocs/cli\`): genera la estructura de docs, documenta con IA, configura Pages y ejecuta el servidor MCP.
+- **tools/** — \`@gitpagedocs/tools\`, el nucleo de logica compartido: sistema de IA con 14 proveedores, boveda de credenciales cifrada, cargador de config, caches y logger.
+- **mcp/** — \`@gitpagedocs/mcp\`, servidor Model Context Protocol (20 herramientas + 7 recursos).
+- **gitpagedocs/** — el contrato del usuario: \`config.json\`, docs versionados y layouts.
+
+## Stack
+
+- Next.js 15 (App Router) + React 19 + TypeScript; exportacion estatica para GitHub Pages
+- gray-matter + marked para Markdown; react-icons
+- pnpm workspaces + turborepo; Vitest + Playwright; ESLint
+
+## Destacados
+
+- Multilingue (\`en\`, \`pt\`, \`es\`) y rutas por version (\`/v/:version\`)
+- Sistema de IA con 14 proveedores (OpenAI, Anthropic, Gemini, Ollama, Mistral, DeepSeek, Cohere, Groq, xAI y mas) con streaming
+- Claves de IA **cifradas en reposo** (AES-256-GCM) detras de una contrasena local — nunca en texto plano
+- **Panel de chat de IA** en los docs + una **consola \`/ai\`** dedicada
+- Sistema de 36 temas; ejecucion local y en GitHub Pages
+`,
+    functionalities: `# Funcionalidades
+
+Referencia completa de opciones CLI, claves de configuracion y funciones del runtime.
+
+## Comandos CLI
+
+| Comando | Descripcion |
+|---------|-------------|
+| \`npx @gitpagedocs/cli\` | Genera config y docs en \`gitpagedocs/\` |
+| \`npx @gitpagedocs/cli --layoutconfig\` | Tambien genera layouts/templates locales en \`gitpagelayouts/\` |
+| \`npx @gitpagedocs/cli --home\` | Distribucion standalone (\`gitpagedocshome/\`) |
+| \`npx @gitpagedocs/cli --push --owner X --repo Y\` | Configura workflow, commit, push |
+| \`npx @gitpagedocs/cli --interactive\` / \`-i\` | Modo interactivo con prompts (por defecto en una terminal) |
+| \`npx @gitpagedocs/cli --no-interactive\` / \`-y\` | Nunca pregunta; usa flags y valores por defecto |
+
+## Opciones CLI
+
+| Opcion | Descripcion |
+|--------|-------------|
+| \`--owner <user>\` | Owner de GitHub |
+| \`--repo <repo>\` | Repositorio GitHub |
+| \`--path <subpath>\` | Subruta de docs (ej: \`docs\`); sin ella, base path = nombre del repo para CSS/JS en project sites |
+| \`--output <dir>\` | Directorio de salida (default: \`gitpagedocs\`) |
+| \`--search true|false\` | Habilita/deshabilita busqueda de repositorio (\`--home\`) |
+| \`--layoutconfig\` | Genera layouts locales en \`gitpagelayouts/\` |
+| \`--layouts-dir <dir>\` | Carpeta de layouts locales (por defecto: \`gitpagelayouts\`) |
+| \`--push\` | Crea workflow, commit de artefactos, push |
+| \`--home\` | Genera \`gitpagedocshome/\` (estatico + .env + Dockerfile) |
+
+## Salida generada
+
+- \`gitpagedocs/config.json\` – config raiz
+- \`gitpagedocs/icon.svg\` – icono por defecto
+- \`gitpagedocs/docs/versions/<ver>/config.json\` – rutas por version
+- \`gitpagedocs/docs/versions/<ver>/{en,pt,es}/*.md\` – docs en markdown
+- \`gitpagelayouts/\` – solo con \`--layoutconfig\` (carpeta configurable con \`--layouts-dir\`)
+
+## Tipos de contenido
+
+| Tipo | Clave config | Descripcion |
+|------|--------------|-------------|
+| Markdown | \`routes-md\` | Archivos .md con \`path\` por idioma |
+| HTML | \`routes-html\` | \`path\` local o \`url\` externa |
+| Video | \`routes-video\` | \`video.pathVideo\`, \`video.videoType\` |
+| Audio | \`routes-audio\` | \`audio.pathAudio\`, \`audio.audioType\` |
+
+## Visor de codigo fuente
+
+El config de version puede renderizar un contenedor **Codigo fuente** via \`routes-source-viewer\` y \`menus-header-source-viewer\`. El viewer lee el arbol del repositorio en GitHub en tiempo de ejecucion y aplica el tema actual de la documentacion.
+
+- Arbol del repositorio desde \`source-viewer-path\`; la branch por defecto es \`main\`
+- Navegacion por carpetas y filtro de archivos
+- Listado de directorios estilo GitHub
+- Renderizado de codigo con numeros de linea
+- Alternancia vista previa/codigo para Markdown, incluido \`README.md\`
+- Carpetas colapsables en la barra lateral
+
+## Claves de config (site)
+
+- \`name\`, \`defaultLanguage\`, \`supportedLanguages\`
+- \`docsVersion\`, \`rendering\`, \`ThemeDefault\`, \`ThemeModeDefault\`
+- \`ProjectLink\`, \`layoutsConfigPathOficial\`, \`layoutsConfigPath\`
+
+## Variables de entorno
+
+- \`GITPAGEDOCS_REPOSITORY_SEARCH\` – busqueda de repositorio (local)
+- \`GITHUB_ACTIONS\` – modo build GitHub Pages
+`,
+    configuration: `# Configuracion
+
+La configuracion de runtime esta en \`gitpagedocs/config.json\`.
+
+## Seccion \`site\`
+
+Claves principales:
+
+- \`name\`: titulo del proyecto en UI
+- \`defaultLanguage\`: idioma por defecto
+- \`supportedLanguages\`: lista de idiomas disponibles
+- \`HideThemeSelector\`: ocultar/mostrar selector de tema
+- \`ThemeDefault\`: id del tema inicial
+- \`ThemeModeDefault\`: modo inicial (\`light\` o \`dark\`)
+- \`ProjectLink\`: URL de repositorio para acciones de cabecera
+- \`docsVersion\`: version seleccionada por defecto
+- \`ActiveNavigation\`: habilita anterior/siguiente
+- \`FocusMode\`: habilita modo foco/lectura
+- \`IconImageMenuHeaderImgWidth\`, \`IconImageMenuHeaderImgHeight\`: tamano del icono principal
+- \`IconImageMenuHeaderLightImg\`, \`IconImageMenuHeaderDarkImg\`: icono principal (light/dark)
+- \`IconProjectLinkImgWidth\`, \`IconProjectLinkImgHeight\`: tamano del icono enlace del proyecto
+- \`IconProjectLinkLightImg\`, \`IconProjectLinkDarkImg\`: icono enlace del proyecto
+- \`IconVersionLinksImgWidth\`, \`IconVersionLinksImgHeight\`: tamano del icono enlaces de version
+- \`IconVersionLinksLightImg\`, \`IconVersionLinksDarkImg\`: icono enlaces de version
+- \`IconInfoHeaderMenuImgWidth\`, \`IconInfoHeaderMenuImgHeight\`: tamano del icono info
+- \`IconInfoHeaderMenuLightImg\`, \`IconInfoHeaderMenuDarkImg\`: icono info
+- \`IconPreviewProjectLinkImgWidth\`, \`IconPreviewProjectLinkImgHeight\`: tamano del icono preview
+- \`IconPreviewProjectLinkLightImg\`, \`IconPreviewProjectLinkDarkImg\`: icono preview
+- \`layoutsConfigPath\`: fallback remoto de layouts
+- \`rendering\`: URL canonica publicada
+
+## Seccion \`VersionControl\`
+
+\`VersionControl.versions\` define:
+
+- \`id\`: identificador de version
+- \`path\`: ruta de config de version
+- links opcionales (\`ProjectLink\`, \`branch\`, \`release\`, \`commit\`)
+- metadatos opcionales del source viewer (\`source-viewer\`, \`source-viewer-path\`)
+
+## Navegacion y rutas
+
+- \`routes\`: rutas markdown por idioma (legado)
+- \`menus-header\`: menu jerarquico
+- \`translations\`: etiquetas UI para not-found y navegacion
+
+## Autorizacion (config de version)
+
+- \`auth\`: configuraciones globales de autorizacion para esa version
+- \`auth.accessKeys\`: mapa de claves usado por \`authorization.accessKeyId\`
+- \`auth.rolesStorageKey\`: clave de localStorage para bootstrap de roles
+- \`auth.providers\`: adaptadores de proveedor (\`authjs\`, \`clerk\`, \`firebase\`, \`jwt\`)
+
+## Tipos de contenido (config de version)
+
+Los configs de version soportan multiples tipos:
+
+- \`routes-md\`: Rutas markdown con \`title\`, \`description\` (centrados via \`titlePosition\`, \`descriptionPosition\`)
+- \`routes-source-viewer\`: Contenedores de codigo fuente con \`source-viewer: true\` y \`source-viewer-path\`
+- \`routes-html\`: Rutas de paginas HTML por idioma
+- \`routes-video\`: Config de video con \`video.videoType\` (youtube, vimeo, mp4, etc.) y \`video.pathVideo\`
+- \`routes-audio\`: Config de audio con \`audio.audioType\` (youtube, mp3, etc.) y \`audio.pathAudio\`
+- \`authorization\` (md/html/video): guardia de acceso por clave, roles y autenticacion externa
+- \`menus-header-md\`, \`menus-header-source-viewer\`, \`menus-header-html\`, \`menus-header-video\`, \`menus-header-audio\`: menus por tipo
+- \`hierarchyPage\`: orden de contenedores en la pagina \`{ md: 0, "source-viewer": 1, html: 2, video: 3, audio: 4 }\`
+- \`hierarchyMenu\`: orden de secciones del menu \`{ md: 0, "source-viewer": 1, html: 2, video: 3, audio: 4 }\`
+
+Cada ruta puede incluir \`title\`, \`description\` (por idioma), \`titleCss\`, \`titlePosition: "center"\`, \`descriptionPosition: "center"\`, \`titleIsVisible\`, \`descriptionIsVisible\`.
+
+## Variables por ruta (blockLink, container, url, browseAll)
+
+Opciones por ruta en \`routes-md\`, \`routes-html\` y \`routes-video\`:
+
+- **\`blockLink\`** (defecto: true) – Para HTML: si true, los enlaces abren en nueva pestaña (\`target="_blank"\`); si false, en el mismo contexto.
+- **\`container\`** – \`"full"\` = altura automatica; numero (ej: \`500\`) = altura fija en px con overflow auto. Se aplica a md, html y video.
+- **\`url\`** – Solo en \`routes-html\`: \`Record<LanguageCode, string>\` con URLs externas. Al definirse, el iframe usa \`src={url}\` en vez de HTML local via \`srcDoc\`. Las rutas con \`url\` no generan archivos HTML locales.
+- **\`browseAll\`** (defecto: false) – Si true, el contenedor muestra botones Anterior/Siguiente para navegar entre todos los items de ese tipo.
+
+## Tipos de contenido: path vs url (HTML)
+
+- **Markdown (\`routes-md\`)**: usa \`path\` apuntando a archivos \`.md\` locales.
+- **HTML (\`routes-html\`)**: usa \`path\` para archivos HTML locales (sin extension .html en config) o \`url\` para URLs externas. Con \`url\`, el iframe carga la pagina externa; no se genera archivo local.
+- **Video (\`routes-video\`)**: usa \`video.pathVideo\` y \`video.videoType\` (youtube, vimeo, mp4, etc.).
+
+## Variables de entorno
+
+- \`GITPAGEDOCS_REPOSITORY_SEARCH\`: activa/desactiva busqueda remota en local
+- \`GITHUB_ACTIONS\`: habilita comportamiento especifico de GitHub Pages
+`,
+    deployment: `# Publicacion
+
+Git Page Docs corre como app Next.js con dos objetivos: servidor local y GitHub Pages.
+
+## Publicacion local
+
+Usa:
+
+1. \`npm run build\`
+2. \`npm start\`
+
+Esto inicia runtime Node + Next.js usando \`gitpagedocs/\` local.
+
+## Publicacion en GitHub Pages
+
+En build de GitHub Actions:
+
+- \`GITHUB_ACTIONS=true\`
+- el comportamiento de export estatico se habilita por configuracion
+- la pagina inicial de busqueda de repositorios queda activa
+
+## Flujo de publish del paquete
+
+Para publicar en npm:
+
+- actualiza version en \`package.json\`
+- ejecuta \`npm publish --access public\`
+- valida autenticacion con \`npm whoami\`
+
+Si \`build:prebuilt\` se omite en Windows, usa CI para generar artefactos prebuilt.
+`,
+    architecture: `# Arquitectura
+
+El proyecto esta organizado por fronteras de feature y responsabilidades de runtime.
+
+## Paquetes
+
+- **frontend/** — visor Next.js (Feature-Sliced: app / widgets / features / entities / shared); export estatico.
+- **cli/** — el bin publicado \`gitpagedocs\` (hexagonal) + \`cli/ai/\` (CLI de documentacion con IA).
+- **tools/** — \`@gitpagedocs/tools\`: ai/ security/ crypto/ cache/ config/ logger/ errors/ filesystem/ documentation/ ports/.
+- **mcp/** — \`@gitpagedocs/mcp\`: herramientas + recursos MCP que delegan a tools/.
+
+## Modulos principales (frontend)
+
+- \`frontend/src/app/[[...repo]]/page.tsx\` — parser de rutas, generateStaticParams, seleccion de shell.
+- \`frontend/src/entities/docs/api/load-docs-data.ts\` — config local/remota, version, parse markdown, layouts + temas.
+- \`frontend/src/widgets/docs-shell/docs-shell.tsx\` — UI, estado idioma/version/tema, sync de URL, montaje del chat de IA.
+
+## Seguridad: credenciales de IA cifradas
+
+La consola \`/ai\` y el panel de chat exigen una contrasena local que deriva (PBKDF2) una clave AES-256-GCM; las claves quedan cifradas en \`localStorage\` y solo se descifran durante la sesion (\`@gitpagedocs/tools/security\`).
+
+## Flujo de datos
+
+1. Llega la ruta (\`/owner/repo/v/x.y.z\` o equivalente local)
+2. Se resuelve config (local o remoto)
+3. Config de version sobreescribe rutas/menus base
+4. Markdown se carga y convierte a HTML
+5. Template de layout se resuelve y aplica en CSS vars
+6. Shell renderiza contenido y controles
+
+## Puntos de resiliencia
+
+- fallback de carga para layouts/templates
+- carga de markdown por idioma con fallback de error
+- sincronizacion de idioma/version/tema via localStorage
+`,
+    githubIssuesProjects: `# GitHub Issues y Projects
+
+Aprende a usar GitHub Issues y Projects para gestionar tu trabajo.
+
+## Conceptos
+
+- Issues para rastrear tareas y bugs
+- Projects para visualizar y organizar el trabajo
+- Flujos recomendados para equipos
+`,
+    gitIntroduction: `# Introduccion a Git
+
+Conceptos basicos de Git para principiantes.
+
+## Comandos esenciales
+
+- \`git init\` - iniciar repositorio
+- \`git add\` - preparar cambios
+- \`git commit\` - registrar commit
+- \`git push\` - enviar a remoto
+`,
+    authorizedRoutes: `# Rutas autorizadas
+
+Protege rutas por clave de acceso, roles requeridos y proveedores externos.
+
+## Ubicacion del config de version
+
+Configura en:
+
+- \`gitpagedocs/docs/versions/<version>/config.json\`
+
+## Seccion global auth
+
+Usa \`auth\` en la raiz del config de version:
+
+- \`accessKeys\`: mapa de ids de clave al secreto esperado
+- \`rolesStorageKey\`: clave de localStorage para bootstrap de roles
+- \`providers\`: lista de proveedores externos (\`authjs\`, \`clerk\`, \`firebase\`, \`jwt\`)
+
+## Autorizacion por ruta
+
+Dentro de cada ruta (\`routes-md\`, \`routes-html\`, \`routes-video\`):
+
+- \`authorization.accessKeyId\`
+- \`authorization.requiredRoles\`
+- \`authorization.requireExternalAuth\`
+- \`authorization.allowedProviders\`
+
+## Fases
+
+### Fase A - Clave de acceso
+
+Define \`authorization.accessKeyId\` y la clave correspondiente en \`auth.accessKeys\`.
+
+### Fase B - Roles
+
+Define \`authorization.requiredRoles\` con uno o mas roles.
+
+Los roles pueden venir de:
+
+- query param \`?authRoles=admin,maintainer\`
+- localStorage (\`rolesStorageKey\`)
+- claims de proveedores externos
+
+### Fase C - Proveedores externos
+
+Define \`authorization.requireExternalAuth=true\` y opcionalmente \`allowedProviders\`.
+
+Adaptadores soportados:
+
+- Auth.js (\`type: "authjs"\`)
+- Clerk (\`type: "clerk"\`)
+- Firebase Auth (\`type: "firebase"\`)
+- JWT custom (\`type: "jwt"\`)
+`,
+    themes: `# Temas y layouts
+
+Los temas son templates JSON mapeados por \`layoutsConfig.json\`.
+
+## Archivos
+
+- \`gitpagelayouts/layoutsConfig.json\`
+- \`gitpagelayouts/layoutsFallbackConfig.json\`
+- \`gitpagelayouts/templates/*.json\`
+
+## Modelo de template
+
+Cada template normalmente incluye:
+
+- \`id\`, \`name\`, \`author\`, \`version\`
+- \`mode\` y metadatos de par dark/light
+- \`colors\`
+- \`typography\`
+- tokens de \`components\`
+- \`animations\`
+
+## Comportamiento en runtime
+
+- tema activo viene de config/seleccion de usuario
+- toggle light/dark resuelve tema pareado por referencia
+- variables CSS se generan desde tokens del template
+
+## Buenas practicas
+
+- mantener contraste accesible
+- mantener escala consistente de espacios y bordes
+- ofrecer variantes dark y light cuando sea posible
+`,
+    faq: `# FAQ
+
+## Por que repositorios remotos no abren en local?
+
+Verifica:
+
+- \`GITPAGEDOCS_REPOSITORY_SEARCH=true\` en \`.env\`
+- repositorio objetivo contiene \`gitpagedocs/config.json\`
+- paths markdown del repositorio coinciden con su config de rutas
+
+## Por que una ruta de version muestra contenido incorrecto?
+
+Verifica:
+
+- \`VersionControl.versions[*].path\` en \`gitpagedocs/config.json\`
+- config de version tiene \`routes\` y \`menus-header\` validos
+- markdown existe para cada idioma
+
+## Por que tema no se aplica correctamente?
+
+Verifica:
+
+- \`layoutsConfig.json\` referencia templates validos
+- ids de template son unicos
+- tema seleccionado existe en el mapa de temas cargados
+
+## Por que GitHub Pages puede comportarse distinto a local?
+
+Porque el build de GitHub Pages habilita la pagina inicial de busqueda y comportamiento especifico de exportacion.
+`,
+  };