@gitpagedocs/cli 1.1.62 → 1.1.64

package/content/docs-en.mjs

@@ -1,549 +1,549 @@
-import { PACKAGE_VERSION } from "../contracts/doc-versions.mjs";
-
-export const docsEn = {
-    index: `# Git Page Docs
-
-Git Page Docs is a multilingual documentation runtime for repositories that ship a \`gitpagedocs/\` folder.
-
-## What this project delivers
-
-- Multilingual markdown rendering (\`en\`, \`pt\`, \`es\`)
-- Version-aware docs routing (\`/v/:version\`)
-- Theme system with JSON templates
-- Local and GitHub Pages execution modes
-- Optional repository search + remote rendering
-
-## Folder contract
-
-The runtime expects this structure:
-
-- \`gitpagedocs/config.json\`
-- \`gitpagedocs/docs/<lang>/*.md\`
-- \`gitpagedocs/docs/versions/<version>/config.json\`
-- \`gitpagedocs/docs/versions/<version>/<lang>/*.md\`
-- \`gitpagelayouts/layoutsConfig.json\` (only with \`--layoutconfig\`)
-- \`gitpagelayouts/templates/*.json\` (only with \`--layoutconfig\`)
-
-## Quick navigation
-
-- Open **Getting Started** for local setup.
-- Open **Configuration** for full \`config.json\` explanation.
-- Open **Deployment** for local, server, and GitHub Pages behavior.
-- Open **Architecture** for code map and data flow.
-- Open **Themes and layouts** for template authoring details.
-- Open **Authorized routes** for key, roles, and external auth setup.
-- Open **FAQ** for troubleshooting.
-`,
-    gettingStarted: `# Getting Started
-
-This guide configures your repository from zero to running docs.
-
-## Prerequisites
-
-- Node.js 20+
-- npm 10+
-
-## Install and generate
-
-1. Install package:
-   - \`npm install @gitpagedocs/cli\`
-2. Generate docs config and versions:
-   - \`npx @gitpagedocs/cli\`
-3. Optional: generate local layouts/templates:
-   - \`npx @gitpagedocs/cli --layoutconfig\`
-
-## Local run
-
-1. Development:
-   - \`npm run dev\`
-2. Production locally:
-   - \`npm run build\`
-   - \`npm start\`
-
-## CLI behavior
-
-\`npx @gitpagedocs/cli\` generates only artifacts in \`gitpagedocs/\`:
-
-- JSON + markdown docs assets
-- No \`index.html\`
-- No \`index.js\`
-- No install command execution
-
-## Repository search mode
-
-Local repository search is controlled by:
-
-- \`GITPAGEDOCS_REPOSITORY_SEARCH=true\`
-- \`GITPAGEDOCS_REPOSITORY_SEARCH=false\`
-
-On GitHub Pages builds (\`GITHUB_ACTIONS=true\`), repository-search home is enabled.
-`,
-    projectOverview: `# Project Overview
-
-Git Page Docs is a **pnpm + turborepo monorepo** that turns a repository's \`gitpagedocs/\` folder into a multilingual, versioned documentation site — with an integrated AI assistant and a Model Context Protocol (MCP) server.
-
-## Monorepo packages
-
-- **frontend/** — Next.js 15 (App Router, React 19) documentation viewer, static-exported for GitHub Pages.
-- **cli/** — the published \`@gitpagedocs/cli\` npm package (\`npm install -g @gitpagedocs/cli\`): scaffolds the docs contract, generates docs with AI, configures Pages, and runs the MCP server.
-- **tools/** — \`@gitpagedocs/tools\`, the shared business-logic core: the 14-provider AI system, the encrypted credential vault, the config loader, caches, and the logger.
-- **mcp/** — \`@gitpagedocs/mcp\`, a Model Context Protocol server (20 tools + 7 resources).
-- **gitpagedocs/** — the user contract: \`config.json\`, versioned docs, and layouts.
-
-## Stack
-
-- Next.js 15 (App Router) + React 19 + TypeScript; static export for GitHub Pages
-- gray-matter + marked for Markdown; react-icons
-- pnpm workspaces + turborepo; Vitest + Playwright; ESLint
-
-## Highlights
-
-- Multilingual (\`en\`, \`pt\`, \`es\`) and version-aware routing (\`/v/:version\`)
-- 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**
-- 36-theme layout system; local and GitHub Pages execution modes
-`,
-    functionalities: `# Functionalities
-
-Complete reference of CLI options, configuration keys, and runtime features.
-
-## CLI commands
-
-| Command | Description |
-|---------|--------------|
-| \`gitpagedocs\` | Generate config and docs in \`gitpagedocs/\` |
-| \`gitpagedocs --layoutconfig\` | Also generate local layouts/templates in \`gitpagelayouts/\` |
-| \`gitpagedocs --home\` | Standalone distribution (\`gitpagedocshome/\`) |
-| \`gitpagedocs --push --owner X --repo Y\` | Setup workflow, commit, push |
-| \`gitpagedocs --interactive\` / \`-i\` | Interactive mode with prompts (the default in a terminal) |
-| \`gitpagedocs --no-interactive\` / \`--yes\` / \`-y\` | Never prompt; use flags and defaults |
-| \`gitpagedocs ai\` | Interactive AI documentation generator |
-| \`gitpagedocs provider [id]\` / \`models [provider]\` | List AI providers / catalog models |
-| \`gitpagedocs document[:repo\\|:file\\|:folder]\` | Generate documentation with AI |
-| \`gitpagedocs deploy\` / \`pages [actions\\|deploy]\` | Configure GitHub Pages via Actions + push |
-| \`gitpagedocs docs\` | Refresh README/CONTRIBUTING/SECURITY managed regions |
-| \`gitpagedocs doctor\` / \`version\` / \`update\` | Diagnostics / version / registry update check |
-| \`gitpagedocs mcp start\` | Start the MCP server over stdio |
-
-Install globally with \`npm install -g @gitpagedocs/cli\`, or run one-off with \`npx @gitpagedocs/cli\`.
-
-## CLI options
-
-| Option | Description |
-|--------|-------------|
-| \`--owner <user>\` | GitHub owner |
-| \`--repo <repo>\` | GitHub repository |
-| \`--path <subpath>\` | Docs subpath (e.g. \`docs\`); without it, base path = repo name for correct CSS/JS on project sites |
-| \`--output <dir>\` | Output directory (default: \`gitpagedocs\`) |
-| \`--search true|false\` | Enable/disable repository search (\`--home\`) |
-| \`--layoutconfig\` | Generate local layouts in \`gitpagelayouts/\` |
-| \`--layouts-dir <dir>\` | Folder for local layouts (default: \`gitpagelayouts\`) |
-| \`--push\` | Create workflow, commit artifacts, push |
-| \`--home\` | Generate \`gitpagedocshome/\` (static + .env + Dockerfile) |
-
-## Generated output
-
-- \`gitpagedocs/config.json\` – root config
-- \`gitpagedocs/icon.svg\` – default icon
-- \`gitpagedocs/docs/versions/<ver>/config.json\` – per-version routes
-- \`gitpagedocs/docs/versions/<ver>/{en,pt,es}/*.md\` – markdown docs
-- \`gitpagelayouts/\` – only with \`--layoutconfig\` (folder configurable with \`--layouts-dir\`)
-
-## Content types
-
-| Type | Config key | Description |
-|------|------------|-------------|
-| Markdown | \`routes-md\` | .md files with \`path\` per language |
-| HTML | \`routes-html\` | local \`path\` or external \`url\` |
-| Video | \`routes-video\` | \`video.pathVideo\`, \`video.videoType\` |
-| Audio | \`routes-audio\` | \`audio.pathAudio\`, \`audio.audioType\` |
-
-## Source code viewer
-
-The version config can render a **Source code** container through \`routes-source-viewer\` and \`menus-header-source-viewer\`. The viewer reads GitHub repository trees at runtime and applies the current documentation theme.
-
-- Repository tree from \`source-viewer-path\`; branch defaults to \`main\`
-- Folder navigation and file filtering
-- GitHub-style directory listing
-- Code rendering with line numbers
-- Markdown preview/code toggle, including \`README.md\`
-- Collapsible folders in the sidebar
-
-## Config keys (site)
-
-- \`name\`, \`defaultLanguage\`, \`supportedLanguages\`
-- \`docsVersion\`, \`rendering\`, \`ThemeDefault\`, \`ThemeModeDefault\`
-- \`ProjectLink\`, \`layoutsConfigPathOficial\`, \`layoutsConfigPath\`
-
-## Environment variables
-
-- \`GITPAGEDOCS_REPOSITORY_SEARCH\` – repository search (local)
-- \`GITHUB_ACTIONS\` – GitHub Pages build mode
-
-## AI assistant
-
-The docs ship an AI assistant in two surfaces: an in-docs **chat drawer** (the AI chat button in the sidebar, enabled via \`site.AiChatEnabled\`) and a dedicated **\`/ai\` console** page.
-
-- **14 providers** via one shared core: OpenAI, Anthropic, Gemini, OpenRouter, Ollama, Azure OpenAI, Mistral, DeepSeek, Cohere, Groq, xAI, Together, Fireworks, Perplexity.
-- **Model selection** — pick from each provider's catalog (\`gitpagedocs models <provider>\`) or type a custom id.
-- **Encrypted at rest** — your API key is sealed with AES-256-GCM behind a **local password** (one unlock per session) and is never stored in plaintext or logged. A legacy plaintext key is migrated and wiped on first unlock.
-- **AI documentation generation** — \`gitpagedocs ai\` scans chosen paths and writes multilingual markdown (pt/en/es); reusable via \`.gitpagedocsconfig\`.
-
-## MCP server
-
-\`gitpagedocs mcp start\` runs a Model Context Protocol server (stdio) exposing **20 tools** (filesystem, AI, doc generation/analysis) and **7 resources** (\`project://structure|docs|config|repository|readme|ai/providers|ai/models\`) for editors and AI agents.
-`,
-    githubIssuesProjects: `# GitHub Issues and Projects
-
-Learn how to use GitHub Issues and Projects to manage your work.
-
-## Issues
-
-- Track bugs, features, and tasks
-- Assignees, labels, milestones
-- Discussions and linked PRs
-
-## Projects
-
-- Kanban boards
-- Tables and roadmaps
-- Custom fields and automation
-`,
-    gitIntroduction: `# Introduction to Git
-
-Basic Git concepts for beginners.
-
-## Key concepts
-
-- **Repository**: A project folder tracked by Git
-- **Commit**: A snapshot of changes
-- **Branch**: Alternative line of development
-- **Remote**: Shared repository (e.g. on GitHub)
-
-## Common commands
-
-- \`git init\` - Initialize a repo
-- \`git add\` - Stage changes
-- \`git commit\` - Create a snapshot
-- \`git push\` - Send to remote
-`,
-    authorizedRoutes: `# Authorized Routes
-
-Protect routes by access key, required roles, and external authentication providers.
-
-## Version config location
-
-Configure this at:
-
-- \`gitpagedocs/docs/versions/<version>/config.json\`
-
-## Global auth section
-
-Use top-level \`auth\` in version config:
-
-- \`accessKeys\`: map of key ids to expected secrets
-- \`rolesStorageKey\`: localStorage key for role bootstrap
-- \`providers\`: external providers list (\`authjs\`, \`clerk\`, \`firebase\`, \`jwt\`)
-
-## Route-level authorization
-
-Inside each route (\`routes-md\`, \`routes-html\`, \`routes-video\`):
-
-- \`authorization.accessKeyId\`
-- \`authorization.requiredRoles\`
-- \`authorization.requireExternalAuth\`
-- \`authorization.allowedProviders\`
-
-## Phases
-
-### Phase A - Access key
-
-Set \`authorization.accessKeyId\` and define that key in \`auth.accessKeys\`.
-
-### Phase B - Roles
-
-Set \`authorization.requiredRoles\` with one or more roles.
-
-Roles can come from:
-
-- query param \`?authRoles=admin,maintainer\`
-- localStorage (\`rolesStorageKey\`)
-- external provider claims
-
-### Phase C - External providers
-
-Set \`authorization.requireExternalAuth=true\` and optionally \`allowedProviders\`.
-
-Supported adapters:
-
-- Auth.js (\`type: "authjs"\`)
-- Clerk (\`type: "clerk"\`)
-- Firebase Auth (\`type: "firebase"\`)
-- Custom JWT (\`type: "jwt"\`)
-
-## Example
-
-\`\`\`json
-{
-  "auth": {
-    "accessKeys": {
-      "docs-key": "open-gitpagedocs-docs"
-    },
-    "providers": [
-      { "type": "authjs", "enabled": true, "sessionEndpoint": "/api/auth/session" },
-      { "type": "jwt", "enabled": true, "tokenStorageKey": "git-page-docs:jwt-token" }
-    ]
-  },
-  "routes-md": [
-    {
-      "id": 6,
-      "path": {
-        "en": "gitpagedocs/docs/versions/${PACKAGE_VERSION}/en/authorized-routes.md",
-        "pt": "gitpagedocs/docs/versions/${PACKAGE_VERSION}/pt/authorized-routes.md",
-        "es": "gitpagedocs/docs/versions/${PACKAGE_VERSION}/es/authorized-routes.md"
-      },
-      "authorization": {
-        "accessKeyId": "docs-key",
-        "requiredRoles": ["maintainer"],
-        "requireExternalAuth": true,
-        "allowedProviders": ["authjs", "jwt"]
-      }
-    }
-  ]
-}
-\`\`\`
-`,
-    configuration: `# Configuration
-
-Runtime configuration lives in \`gitpagedocs/config.json\`.
-
-## \`site\` section
-
-Important keys:
-
-- \`name\`
-- \`defaultLanguage\`
-- \`supportedLanguages\`
-- \`docsVersion\`
-- \`rendering\`
-- \`ThemeDefault\`
-- \`ThemeModeDefault\`
-- \`ProjectLink\`
-
-## Layout source keys
-
-- \`layoutsConfigPathOficial\`
-- \`layoutsConfigPathOficialUrl\`
-- \`layoutsConfigPathTemplatesOficial\`
-- \`layoutsConfigPath\`
-- \`layoutsConfigPathTemplates\`
-
-Behavior:
-
-- If \`layoutsConfigPathOficial=true\`, runtime prefers official layout/template sources.
-- If \`layoutsConfigPathOficial=false\`, runtime prefers repository-local/custom layout sources.
-
-## \`VersionControl\` section
-
-\`VersionControl.versions\` defines:
-
-- \`id\`
-- \`path\`
-- optional metadata links (\`ProjectLink\`, \`branch\`, \`release\`, \`commit\`)
-- optional source viewer metadata (\`source-viewer\`, \`source-viewer-path\`)
-
-## Navigation
-
-- \`routes\`: markdown paths per language (legacy)
-- \`menus-header\`: hierarchical menu model
-- \`translations\`: UI labels
-
-## Authorization (version config)
-
-- \`auth\`: global authorization runtime settings for that version
-- \`auth.accessKeys\`: key map used by \`authorization.accessKeyId\`
-- \`auth.rolesStorageKey\`: localStorage key for role bootstrap
-- \`auth.providers\`: provider adapters (\`authjs\`, \`clerk\`, \`firebase\`, \`jwt\`)
-
-## Content types (version config)
-
-Version configs support multiple content types:
-
-- \`routes-md\`: Markdown routes with optional \`title\`, \`description\` (centered via \`titlePosition\`, \`descriptionPosition\`)
-- \`routes-source-viewer\`: Source viewer containers with \`source-viewer: true\` and \`source-viewer-path\`
-- \`routes-html\`: HTML page paths per language
-- \`routes-video\`: Video config with \`video.videoType\` (youtube, vimeo, mp4, etc.) and \`video.pathVideo\`
-- \`routes-audio\`: Audio config with \`audio.audioType\` (youtube, mp3, etc.) and \`audio.pathAudio\`
-- \`authorization\` (md/html/video): route guard by access key, roles, and external auth
-- \`menus-header-md\`, \`menus-header-source-viewer\`, \`menus-header-html\`, \`menus-header-video\`, \`menus-header-audio\`: menus per type
-- \`hierarchyPage\`: container order on page \`{ md: 0, "source-viewer": 1, html: 2, video: 3, audio: 4 }\`
-- \`hierarchyMenu\`: menu section order \`{ md: 0, "source-viewer": 1, html: 2, video: 3, audio: 4 }\`
-
-Each route can include \`title\`, \`description\` (per language), \`titleCss\`, \`titlePosition: "center"\`, \`descriptionPosition: "center"\`, \`titleIsVisible\`, \`descriptionIsVisible\`.
-
-## Route-level variables (blockLink, container, url, browseAll)
-
-Per-route options for \`routes-md\`, \`routes-html\`, \`routes-video\`, and \`routes-audio\`:
-
-- **\`blockLink\`** (default: true) – For HTML: if true, links open in a new tab (\`target="_blank"\`); if false, links open in the same context.
-- **\`container\`** – \`"full"\` = auto-extend height; number (e.g. \`500\`) = fixed height in px with overflow auto. Applies to md, html, video, and audio containers.
-- **\`url\`** – For \`routes-html\` only: \`Record<LanguageCode, string>\` with external URLs. When set, the iframe uses \`src={url}\` instead of local HTML via \`srcDoc\`. Routes with \`url\` do not generate local HTML files.
-- **\`browseAll\`** (default: false) – If true, the container shows Previous/Next buttons to browse all items of that type without changing the page.
-
-## Content types: path vs url (HTML)
-
-- **Markdown (\`routes-md\`)**: always uses \`path\` pointing to local \`.md\` files.
-- **HTML (\`routes-html\`)**: uses \`path\` for local HTML files (no \`.html\` extension in config) or \`url\` for external URLs. When \`url\` is set, the iframe loads the external page; no local file is generated.
-- **Video (\`routes-video\`)**: uses \`video.pathVideo\` and \`video.videoType\` (youtube, vimeo, mp4, etc.).
-- **Audio (\`routes-audio\`)**: uses \`audio.pathAudio\` and \`audio.audioType\` (youtube, mp3, etc.). No autoplay by default.
-
-## Environment variables
-
-- \`GITPAGEDOCS_REPOSITORY_SEARCH\`: enable/disable remote repository search in local runtime
-- \`GITHUB_ACTIONS\`: enables GitHub Pages specific runtime behavior
-`,
-    deployment: `# Deployment
-
-Git Page Docs supports two usage models:
-
-1. Use the official viewer site
-2. Self-host your own GitHub Pages runtime
-
-## Official viewer site
-
-Use:
-
-- \`https://vidigal-code.github.io/git-page-docs/\`
-
-Provide owner + repository to load docs from repositories that contain \`gitpagedocs/\`.
-
-## Self-hosted GitHub Pages
-
-1. Generate docs:
-   - \`npx @gitpagedocs/cli\`
-   - or \`npx @gitpagedocs/cli --layoutconfig\` for local templates
-2. Set \`site.rendering\` in \`gitpagedocs/config.json\`:
-   - \`https://<your-user>.github.io/<your-repo>/\`
-3. Build and validate:
-   - \`npm run lint\`
-   - \`npm run build\`
-4. Deploy with GitHub Pages workflow.
-
-When \`GITHUB_ACTIONS=true\`, runtime applies GitHub Pages behavior.
-
-## npm publish flows
-
-Recommended: GitHub Release + CI publish.
-
-Manual fallback:
-
-1. \`npm whoami\`
-2. \`npm run lint\`
-3. \`npm run build\`
-4. \`npm pack --ignore-scripts\`
-5. \`npm version patch\`
-6. \`npm publish --access public\`
-`,
-    architecture: `# Architecture
-
-A pnpm + turborepo monorepo where all business logic lives in one shared core (\`tools/\`); the frontend, CLI, and MCP server are thin consumers of it.
-
-## Packages
-
-- **frontend/** — Next.js viewer (Feature-Sliced: \`app / widgets / features / entities / shared\`); static export.
-- **cli/** — the published \`gitpagedocs\` bin (hexagonal: \`presentation / application / domain / infrastructure\`) + \`cli/ai/\` (the AI documentation CLI).
-- **tools/** — \`@gitpagedocs/tools\`: \`ai/ security/ crypto/ cache/ config/ logger/ errors/ filesystem/ documentation/ ports/\`.
-- **mcp/** — \`@gitpagedocs/mcp\`: MCP tools + resources delegating to \`tools/\`.
-
-## Main runtime modules (frontend)
-
-- \`frontend/src/app/[[...repo]]/page.tsx\` — route parser, static params, shell selection (docs vs repository-search).
-- \`frontend/src/entities/docs/api/load-docs-data.ts\` — local/remote config loading, version resolution, markdown parse, layouts + themes.
-- \`frontend/src/widgets/docs-shell/docs-shell.tsx\` — UI rendering, language/version/theme state, URL sync, AI chat drawer mount.
-
-## Security: encrypted AI credentials
-
-The \`/ai\` console and the chat drawer gate access behind a local password that derives (PBKDF2) an AES-256-GCM key; keys live encrypted in \`localStorage\` and are decrypted only for the session (\`@gitpagedocs/tools/security\`).
-
-## Data flow
-
-1. Request route arrives (\`/owner/repo/v/x.y.z\` or local equivalent)
-2. Config is resolved (local or remote repo)
-3. Version config overrides base routes/menus
-4. Markdown is loaded and converted to HTML
-5. Layout template is resolved and CSS vars applied
-6. Shell renders content + controls
-
-## Reliability points
-
-- fallback strategy for layout/template loading
-- resilient markdown loading per language
-- localStorage sync for user language/version/theme
-`,
-    themes: `# Themes and Layouts
-
-Themes are JSON templates mapped by \`layoutsConfig.json\`.
-
-## Strategy options
-
-- Default mode (\`npx @gitpagedocs/cli\`): use official layouts/templates from the upstream repository.
-- Local mode (\`npx @gitpagedocs/cli --layoutconfig\`): generate and use local templates from your repository.
-
-## Local layout files
-
-- \`gitpagelayouts/layoutsConfig.json\`
-- \`gitpagelayouts/layoutsFallbackConfig.json\`
-- \`gitpagelayouts/templates/*.json\`
-
-The legacy \`gitpagedocs/layouts/\` location is no longer generated. It is still read by the viewer, and the CLI offers to move it into the layouts home - only after you confirm.
-
-## Template model
-
-Each template usually includes:
-
-- \`id\`, \`name\`, \`author\`, \`version\`
-- \`mode\` + dark/light pairing metadata
-- \`colors\`
-- \`typography\`
-- \`components\`
-- \`animations\`
-
-## Runtime behavior
-
-- Active theme is resolved from config/user selection.
-- Light/dark toggle resolves paired theme via reference.
-- CSS variables are generated from template tokens.
-- Runtime includes fallback behavior if a source is unavailable.
-`,
-    faq: `# FAQ
-
-## Why are remote repositories not opening locally?
-
-Check:
-
-- \`GITPAGEDOCS_REPOSITORY_SEARCH=true\` in \`.env\`
-- target repo contains \`gitpagedocs/config.json\`
-- target repo markdown paths match its routes config
-
-## Why does a version path return wrong content?
-
-Check:
-
-- \`VersionControl.versions[*].path\` in \`gitpagedocs/config.json\`
-- that version config has valid \`routes\` and \`menus-header\`
-- markdown files exist for each language
-
-## Why does theme selection not apply correctly?
-
-Check:
-
-- \`layoutsConfig.json\` references valid template files
-- template ids are unique
-- selected theme exists in loaded themes map
-
-## Why can GitHub Pages behave differently from local?
-
-Because GitHub Pages build mode enables repository-search home and static-export specific behavior.
-`,
-  };
+import { PACKAGE_VERSION } from "../contracts/doc-versions.mjs";
+
+export const docsEn = {
+    index: `# Git Page Docs
+
+Git Page Docs is a multilingual documentation runtime for repositories that ship a \`gitpagedocs/\` folder.
+
+## What this project delivers
+
+- Multilingual markdown rendering (\`en\`, \`pt\`, \`es\`)
+- Version-aware docs routing (\`/v/:version\`)
+- Theme system with JSON templates
+- Local and GitHub Pages execution modes
+- Optional repository search + remote rendering
+
+## Folder contract
+
+The runtime expects this structure:
+
+- \`gitpagedocs/config.json\`
+- \`gitpagedocs/docs/<lang>/*.md\`
+- \`gitpagedocs/docs/versions/<version>/config.json\`
+- \`gitpagedocs/docs/versions/<version>/<lang>/*.md\`
+- \`gitpagelayouts/layoutsConfig.json\` (only with \`--layoutconfig\`)
+- \`gitpagelayouts/templates/*.json\` (only with \`--layoutconfig\`)
+
+## Quick navigation
+
+- Open **Getting Started** for local setup.
+- Open **Configuration** for full \`config.json\` explanation.
+- Open **Deployment** for local, server, and GitHub Pages behavior.
+- Open **Architecture** for code map and data flow.
+- Open **Themes and layouts** for template authoring details.
+- Open **Authorized routes** for key, roles, and external auth setup.
+- Open **FAQ** for troubleshooting.
+`,
+    gettingStarted: `# Getting Started
+
+This guide configures your repository from zero to running docs.
+
+## Prerequisites
+
+- Node.js 20+
+- npm 10+
+
+## Install and generate
+
+1. Install package:
+   - \`npm install @gitpagedocs/cli\`
+2. Generate docs config and versions:
+   - \`npx @gitpagedocs/cli\`
+3. Optional: generate local layouts/templates:
+   - \`npx @gitpagedocs/cli --layoutconfig\`
+
+## Local run
+
+1. Development:
+   - \`npm run dev\`
+2. Production locally:
+   - \`npm run build\`
+   - \`npm start\`
+
+## CLI behavior
+
+\`npx @gitpagedocs/cli\` generates only artifacts in \`gitpagedocs/\`:
+
+- JSON + markdown docs assets
+- No \`index.html\`
+- No \`index.js\`
+- No install command execution
+
+## Repository search mode
+
+Local repository search is controlled by:
+
+- \`GITPAGEDOCS_REPOSITORY_SEARCH=true\`
+- \`GITPAGEDOCS_REPOSITORY_SEARCH=false\`
+
+On GitHub Pages builds (\`GITHUB_ACTIONS=true\`), repository-search home is enabled.
+`,
+    projectOverview: `# Project Overview
+
+Git Page Docs is a **pnpm + turborepo monorepo** that turns a repository's \`gitpagedocs/\` folder into a multilingual, versioned documentation site — with an integrated AI assistant and a Model Context Protocol (MCP) server.
+
+## Monorepo packages
+
+- **frontend/** — Next.js 15 (App Router, React 19) documentation viewer, static-exported for GitHub Pages.
+- **cli/** — the published \`@gitpagedocs/cli\` npm package (\`npm install -g @gitpagedocs/cli\`): scaffolds the docs contract, generates docs with AI, configures Pages, and runs the MCP server.
+- **tools/** — \`@gitpagedocs/tools\`, the shared business-logic core: the 14-provider AI system, the encrypted credential vault, the config loader, caches, and the logger.
+- **mcp/** — \`@gitpagedocs/mcp\`, a Model Context Protocol server (20 tools + 7 resources).
+- **gitpagedocs/** — the user contract: \`config.json\`, versioned docs, and layouts.
+
+## Stack
+
+- Next.js 15 (App Router) + React 19 + TypeScript; static export for GitHub Pages
+- gray-matter + marked for Markdown; react-icons
+- pnpm workspaces + turborepo; Vitest + Playwright; ESLint
+
+## Highlights
+
+- Multilingual (\`en\`, \`pt\`, \`es\`) and version-aware routing (\`/v/:version\`)
+- 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**
+- 36-theme layout system; local and GitHub Pages execution modes
+`,
+    functionalities: `# Functionalities
+
+Complete reference of CLI options, configuration keys, and runtime features.
+
+## CLI commands
+
+| Command | Description |
+|---------|--------------|
+| \`gitpagedocs\` | Generate config and docs in \`gitpagedocs/\` |
+| \`gitpagedocs --layoutconfig\` | Also generate local layouts/templates in \`gitpagelayouts/\` |
+| \`gitpagedocs --home\` | Standalone distribution (\`gitpagedocshome/\`) |
+| \`gitpagedocs --push --owner X --repo Y\` | Setup workflow, commit, push |
+| \`gitpagedocs --interactive\` / \`-i\` | Interactive mode with prompts (the default in a terminal) |
+| \`gitpagedocs --no-interactive\` / \`--yes\` / \`-y\` | Never prompt; use flags and defaults |
+| \`gitpagedocs ai\` | Interactive AI documentation generator |
+| \`gitpagedocs provider [id]\` / \`models [provider]\` | List AI providers / catalog models |
+| \`gitpagedocs document[:repo\\|:file\\|:folder]\` | Generate documentation with AI |
+| \`gitpagedocs deploy\` / \`pages [actions\\|deploy]\` | Configure GitHub Pages via Actions + push |
+| \`gitpagedocs docs\` | Refresh README/CONTRIBUTING/SECURITY managed regions |
+| \`gitpagedocs doctor\` / \`version\` / \`update\` | Diagnostics / version / registry update check |
+| \`gitpagedocs mcp start\` | Start the MCP server over stdio |
+
+Install globally with \`npm install -g @gitpagedocs/cli\`, or run one-off with \`npx @gitpagedocs/cli\`.
+
+## CLI options
+
+| Option | Description |
+|--------|-------------|
+| \`--owner <user>\` | GitHub owner |
+| \`--repo <repo>\` | GitHub repository |
+| \`--path <subpath>\` | Docs subpath (e.g. \`docs\`); without it, base path = repo name for correct CSS/JS on project sites |
+| \`--output <dir>\` | Output directory (default: \`gitpagedocs\`) |
+| \`--search true|false\` | Enable/disable repository search (\`--home\`) |
+| \`--layoutconfig\` | Generate local layouts in \`gitpagelayouts/\` |
+| \`--layouts-dir <dir>\` | Folder for local layouts (default: \`gitpagelayouts\`) |
+| \`--push\` | Create workflow, commit artifacts, push |
+| \`--home\` | Generate \`gitpagedocshome/\` (static + .env + Dockerfile) |
+
+## Generated output
+
+- \`gitpagedocs/config.json\` – root config
+- \`gitpagedocs/icon.svg\` – default icon
+- \`gitpagedocs/docs/versions/<ver>/config.json\` – per-version routes
+- \`gitpagedocs/docs/versions/<ver>/{en,pt,es}/*.md\` – markdown docs
+- \`gitpagelayouts/\` – only with \`--layoutconfig\` (folder configurable with \`--layouts-dir\`)
+
+## Content types
+
+| Type | Config key | Description |
+|------|------------|-------------|
+| Markdown | \`routes-md\` | .md files with \`path\` per language |
+| HTML | \`routes-html\` | local \`path\` or external \`url\` |
+| Video | \`routes-video\` | \`video.pathVideo\`, \`video.videoType\` |
+| Audio | \`routes-audio\` | \`audio.pathAudio\`, \`audio.audioType\` |
+
+## Source code viewer
+
+The version config can render a **Source code** container through \`routes-source-viewer\` and \`menus-header-source-viewer\`. The viewer reads GitHub repository trees at runtime and applies the current documentation theme.
+
+- Repository tree from \`source-viewer-path\`; branch defaults to \`main\`
+- Folder navigation and file filtering
+- GitHub-style directory listing
+- Code rendering with line numbers
+- Markdown preview/code toggle, including \`README.md\`
+- Collapsible folders in the sidebar
+
+## Config keys (site)
+
+- \`name\`, \`defaultLanguage\`, \`supportedLanguages\`
+- \`docsVersion\`, \`rendering\`, \`ThemeDefault\`, \`ThemeModeDefault\`
+- \`ProjectLink\`, \`layoutsConfigPathOficial\`, \`layoutsConfigPath\`
+
+## Environment variables
+
+- \`GITPAGEDOCS_REPOSITORY_SEARCH\` – repository search (local)
+- \`GITHUB_ACTIONS\` – GitHub Pages build mode
+
+## AI assistant
+
+The docs ship an AI assistant in two surfaces: an in-docs **chat drawer** (the AI chat button in the sidebar, enabled via \`site.AiChatEnabled\`) and a dedicated **\`/ai\` console** page.
+
+- **14 providers** via one shared core: OpenAI, Anthropic, Gemini, OpenRouter, Ollama, Azure OpenAI, Mistral, DeepSeek, Cohere, Groq, xAI, Together, Fireworks, Perplexity.
+- **Model selection** — pick from each provider's catalog (\`gitpagedocs models <provider>\`) or type a custom id.
+- **Encrypted at rest** — your API key is sealed with AES-256-GCM behind a **local password** (one unlock per session) and is never stored in plaintext or logged. A legacy plaintext key is migrated and wiped on first unlock.
+- **AI documentation generation** — \`gitpagedocs ai\` scans chosen paths and writes multilingual markdown (pt/en/es); reusable via \`.gitpagedocsconfig\`.
+
+## MCP server
+
+\`gitpagedocs mcp start\` runs a Model Context Protocol server (stdio) exposing **20 tools** (filesystem, AI, doc generation/analysis) and **7 resources** (\`project://structure|docs|config|repository|readme|ai/providers|ai/models\`) for editors and AI agents.
+`,
+    githubIssuesProjects: `# GitHub Issues and Projects
+
+Learn how to use GitHub Issues and Projects to manage your work.
+
+## Issues
+
+- Track bugs, features, and tasks
+- Assignees, labels, milestones
+- Discussions and linked PRs
+
+## Projects
+
+- Kanban boards
+- Tables and roadmaps
+- Custom fields and automation
+`,
+    gitIntroduction: `# Introduction to Git
+
+Basic Git concepts for beginners.
+
+## Key concepts
+
+- **Repository**: A project folder tracked by Git
+- **Commit**: A snapshot of changes
+- **Branch**: Alternative line of development
+- **Remote**: Shared repository (e.g. on GitHub)
+
+## Common commands
+
+- \`git init\` - Initialize a repo
+- \`git add\` - Stage changes
+- \`git commit\` - Create a snapshot
+- \`git push\` - Send to remote
+`,
+    authorizedRoutes: `# Authorized Routes
+
+Protect routes by access key, required roles, and external authentication providers.
+
+## Version config location
+
+Configure this at:
+
+- \`gitpagedocs/docs/versions/<version>/config.json\`
+
+## Global auth section
+
+Use top-level \`auth\` in version config:
+
+- \`accessKeys\`: map of key ids to expected secrets
+- \`rolesStorageKey\`: localStorage key for role bootstrap
+- \`providers\`: external providers list (\`authjs\`, \`clerk\`, \`firebase\`, \`jwt\`)
+
+## Route-level authorization
+
+Inside each route (\`routes-md\`, \`routes-html\`, \`routes-video\`):
+
+- \`authorization.accessKeyId\`
+- \`authorization.requiredRoles\`
+- \`authorization.requireExternalAuth\`
+- \`authorization.allowedProviders\`
+
+## Phases
+
+### Phase A - Access key
+
+Set \`authorization.accessKeyId\` and define that key in \`auth.accessKeys\`.
+
+### Phase B - Roles
+
+Set \`authorization.requiredRoles\` with one or more roles.
+
+Roles can come from:
+
+- query param \`?authRoles=admin,maintainer\`
+- localStorage (\`rolesStorageKey\`)
+- external provider claims
+
+### Phase C - External providers
+
+Set \`authorization.requireExternalAuth=true\` and optionally \`allowedProviders\`.
+
+Supported adapters:
+
+- Auth.js (\`type: "authjs"\`)
+- Clerk (\`type: "clerk"\`)
+- Firebase Auth (\`type: "firebase"\`)
+- Custom JWT (\`type: "jwt"\`)
+
+## Example
+
+\`\`\`json
+{
+  "auth": {
+    "accessKeys": {
+      "docs-key": "open-gitpagedocs-docs"
+    },
+    "providers": [
+      { "type": "authjs", "enabled": true, "sessionEndpoint": "/api/auth/session" },
+      { "type": "jwt", "enabled": true, "tokenStorageKey": "git-page-docs:jwt-token" }
+    ]
+  },
+  "routes-md": [
+    {
+      "id": 6,
+      "path": {
+        "en": "gitpagedocs/docs/versions/${PACKAGE_VERSION}/en/authorized-routes.md",
+        "pt": "gitpagedocs/docs/versions/${PACKAGE_VERSION}/pt/authorized-routes.md",
+        "es": "gitpagedocs/docs/versions/${PACKAGE_VERSION}/es/authorized-routes.md"
+      },
+      "authorization": {
+        "accessKeyId": "docs-key",
+        "requiredRoles": ["maintainer"],
+        "requireExternalAuth": true,
+        "allowedProviders": ["authjs", "jwt"]
+      }
+    }
+  ]
+}
+\`\`\`
+`,
+    configuration: `# Configuration
+
+Runtime configuration lives in \`gitpagedocs/config.json\`.
+
+## \`site\` section
+
+Important keys:
+
+- \`name\`
+- \`defaultLanguage\`
+- \`supportedLanguages\`
+- \`docsVersion\`
+- \`rendering\`
+- \`ThemeDefault\`
+- \`ThemeModeDefault\`
+- \`ProjectLink\`
+
+## Layout source keys
+
+- \`layoutsConfigPathOficial\`
+- \`layoutsConfigPathOficialUrl\`
+- \`layoutsConfigPathTemplatesOficial\`
+- \`layoutsConfigPath\`
+- \`layoutsConfigPathTemplates\`
+
+Behavior:
+
+- If \`layoutsConfigPathOficial=true\`, runtime prefers official layout/template sources.
+- If \`layoutsConfigPathOficial=false\`, runtime prefers repository-local/custom layout sources.
+
+## \`VersionControl\` section
+
+\`VersionControl.versions\` defines:
+
+- \`id\`
+- \`path\`
+- optional metadata links (\`ProjectLink\`, \`branch\`, \`release\`, \`commit\`)
+- optional source viewer metadata (\`source-viewer\`, \`source-viewer-path\`)
+
+## Navigation
+
+- \`routes\`: markdown paths per language (legacy)
+- \`menus-header\`: hierarchical menu model
+- \`translations\`: UI labels
+
+## Authorization (version config)
+
+- \`auth\`: global authorization runtime settings for that version
+- \`auth.accessKeys\`: key map used by \`authorization.accessKeyId\`
+- \`auth.rolesStorageKey\`: localStorage key for role bootstrap
+- \`auth.providers\`: provider adapters (\`authjs\`, \`clerk\`, \`firebase\`, \`jwt\`)
+
+## Content types (version config)
+
+Version configs support multiple content types:
+
+- \`routes-md\`: Markdown routes with optional \`title\`, \`description\` (centered via \`titlePosition\`, \`descriptionPosition\`)
+- \`routes-source-viewer\`: Source viewer containers with \`source-viewer: true\` and \`source-viewer-path\`
+- \`routes-html\`: HTML page paths per language
+- \`routes-video\`: Video config with \`video.videoType\` (youtube, vimeo, mp4, etc.) and \`video.pathVideo\`
+- \`routes-audio\`: Audio config with \`audio.audioType\` (youtube, mp3, etc.) and \`audio.pathAudio\`
+- \`authorization\` (md/html/video): route guard by access key, roles, and external auth
+- \`menus-header-md\`, \`menus-header-source-viewer\`, \`menus-header-html\`, \`menus-header-video\`, \`menus-header-audio\`: menus per type
+- \`hierarchyPage\`: container order on page \`{ md: 0, "source-viewer": 1, html: 2, video: 3, audio: 4 }\`
+- \`hierarchyMenu\`: menu section order \`{ md: 0, "source-viewer": 1, html: 2, video: 3, audio: 4 }\`
+
+Each route can include \`title\`, \`description\` (per language), \`titleCss\`, \`titlePosition: "center"\`, \`descriptionPosition: "center"\`, \`titleIsVisible\`, \`descriptionIsVisible\`.
+
+## Route-level variables (blockLink, container, url, browseAll)
+
+Per-route options for \`routes-md\`, \`routes-html\`, \`routes-video\`, and \`routes-audio\`:
+
+- **\`blockLink\`** (default: true) – For HTML: if true, links open in a new tab (\`target="_blank"\`); if false, links open in the same context.
+- **\`container\`** – \`"full"\` = auto-extend height; number (e.g. \`500\`) = fixed height in px with overflow auto. Applies to md, html, video, and audio containers.
+- **\`url\`** – For \`routes-html\` only: \`Record<LanguageCode, string>\` with external URLs. When set, the iframe uses \`src={url}\` instead of local HTML via \`srcDoc\`. Routes with \`url\` do not generate local HTML files.
+- **\`browseAll\`** (default: false) – If true, the container shows Previous/Next buttons to browse all items of that type without changing the page.
+
+## Content types: path vs url (HTML)
+
+- **Markdown (\`routes-md\`)**: always uses \`path\` pointing to local \`.md\` files.
+- **HTML (\`routes-html\`)**: uses \`path\` for local HTML files (no \`.html\` extension in config) or \`url\` for external URLs. When \`url\` is set, the iframe loads the external page; no local file is generated.
+- **Video (\`routes-video\`)**: uses \`video.pathVideo\` and \`video.videoType\` (youtube, vimeo, mp4, etc.).
+- **Audio (\`routes-audio\`)**: uses \`audio.pathAudio\` and \`audio.audioType\` (youtube, mp3, etc.). No autoplay by default.
+
+## Environment variables
+
+- \`GITPAGEDOCS_REPOSITORY_SEARCH\`: enable/disable remote repository search in local runtime
+- \`GITHUB_ACTIONS\`: enables GitHub Pages specific runtime behavior
+`,
+    deployment: `# Deployment
+
+Git Page Docs supports two usage models:
+
+1. Use the official viewer site
+2. Self-host your own GitHub Pages runtime
+
+## Official viewer site
+
+Use:
+
+- \`https://vidigal-code.github.io/git-page-docs/\`
+
+Provide owner + repository to load docs from repositories that contain \`gitpagedocs/\`.
+
+## Self-hosted GitHub Pages
+
+1. Generate docs:
+   - \`npx @gitpagedocs/cli\`
+   - or \`npx @gitpagedocs/cli --layoutconfig\` for local templates
+2. Set \`site.rendering\` in \`gitpagedocs/config.json\`:
+   - \`https://<your-user>.github.io/<your-repo>/\`
+3. Build and validate:
+   - \`npm run lint\`
+   - \`npm run build\`
+4. Deploy with GitHub Pages workflow.
+
+When \`GITHUB_ACTIONS=true\`, runtime applies GitHub Pages behavior.
+
+## npm publish flows
+
+Recommended: GitHub Release + CI publish.
+
+Manual fallback:
+
+1. \`npm whoami\`
+2. \`npm run lint\`
+3. \`npm run build\`
+4. \`npm pack --ignore-scripts\`
+5. \`npm version patch\`
+6. \`npm publish --access public\`
+`,
+    architecture: `# Architecture
+
+A pnpm + turborepo monorepo where all business logic lives in one shared core (\`tools/\`); the frontend, CLI, and MCP server are thin consumers of it.
+
+## Packages
+
+- **frontend/** — Next.js viewer (Feature-Sliced: \`app / widgets / features / entities / shared\`); static export.
+- **cli/** — the published \`gitpagedocs\` bin (hexagonal: \`presentation / application / domain / infrastructure\`) + \`cli/ai/\` (the AI documentation CLI).
+- **tools/** — \`@gitpagedocs/tools\`: \`ai/ security/ crypto/ cache/ config/ logger/ errors/ filesystem/ documentation/ ports/\`.
+- **mcp/** — \`@gitpagedocs/mcp\`: MCP tools + resources delegating to \`tools/\`.
+
+## Main runtime modules (frontend)
+
+- \`frontend/src/app/[[...repo]]/page.tsx\` — route parser, static params, shell selection (docs vs repository-search).
+- \`frontend/src/entities/docs/api/load-docs-data.ts\` — local/remote config loading, version resolution, markdown parse, layouts + themes.
+- \`frontend/src/widgets/docs-shell/docs-shell.tsx\` — UI rendering, language/version/theme state, URL sync, AI chat drawer mount.
+
+## Security: encrypted AI credentials
+
+The \`/ai\` console and the chat drawer gate access behind a local password that derives (PBKDF2) an AES-256-GCM key; keys live encrypted in \`localStorage\` and are decrypted only for the session (\`@gitpagedocs/tools/security\`).
+
+## Data flow
+
+1. Request route arrives (\`/owner/repo/v/x.y.z\` or local equivalent)
+2. Config is resolved (local or remote repo)
+3. Version config overrides base routes/menus
+4. Markdown is loaded and converted to HTML
+5. Layout template is resolved and CSS vars applied
+6. Shell renders content + controls
+
+## Reliability points
+
+- fallback strategy for layout/template loading
+- resilient markdown loading per language
+- localStorage sync for user language/version/theme
+`,
+    themes: `# Themes and Layouts
+
+Themes are JSON templates mapped by \`layoutsConfig.json\`.
+
+## Strategy options
+
+- Default mode (\`npx @gitpagedocs/cli\`): use official layouts/templates from the upstream repository.
+- Local mode (\`npx @gitpagedocs/cli --layoutconfig\`): generate and use local templates from your repository.
+
+## Local layout files
+
+- \`gitpagelayouts/layoutsConfig.json\`
+- \`gitpagelayouts/layoutsFallbackConfig.json\`
+- \`gitpagelayouts/templates/*.json\`
+
+The legacy \`gitpagedocs/layouts/\` location is no longer generated. It is still read by the viewer, and the CLI offers to move it into the layouts home - only after you confirm.
+
+## Template model
+
+Each template usually includes:
+
+- \`id\`, \`name\`, \`author\`, \`version\`
+- \`mode\` + dark/light pairing metadata
+- \`colors\`
+- \`typography\`
+- \`components\`
+- \`animations\`
+
+## Runtime behavior
+
+- Active theme is resolved from config/user selection.
+- Light/dark toggle resolves paired theme via reference.
+- CSS variables are generated from template tokens.
+- Runtime includes fallback behavior if a source is unavailable.
+`,
+    faq: `# FAQ
+
+## Why are remote repositories not opening locally?
+
+Check:
+
+- \`GITPAGEDOCS_REPOSITORY_SEARCH=true\` in \`.env\`
+- target repo contains \`gitpagedocs/config.json\`
+- target repo markdown paths match its routes config
+
+## Why does a version path return wrong content?
+
+Check:
+
+- \`VersionControl.versions[*].path\` in \`gitpagedocs/config.json\`
+- that version config has valid \`routes\` and \`menus-header\`
+- markdown files exist for each language
+
+## Why does theme selection not apply correctly?
+
+Check:
+
+- \`layoutsConfig.json\` references valid template files
+- template ids are unique
+- selected theme exists in loaded themes map
+
+## Why can GitHub Pages behave differently from local?
+
+Because GitHub Pages build mode enables repository-search home and static-export specific behavior.
+`,
+  };