@gitpagedocs/cli 1.1.49 → 1.1.52

package/README.md

@@ -21,9 +21,10 @@ npx @gitpagedocs/cli
 | `gitpagedocs --push --owner <o> --repo <r> [--path <sub>]` | Generate, configure Pages, create workflow, commit + push |
 | `gitpagedocs --home` | Standalone distribution (`gitpagedocshome/`: static site + .env + Dockerfile) |
 | `gitpagedocs -i` / `--interactive` | Interactive prompts |
-| `gitpagedocs ai` | Interactive AI documentation generator (see below) |
+| `gitpagedocs ai` | Interactive AI documentation generator — writes pages in the gitpagedocs pattern (see below) |
 | `gitpagedocs provider [id]` · `models [provider]` | List AI providers / catalog models |
-| `gitpagedocs document[:repo\|:file\|:folder]` | Generate documentation with AI |
+| `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 docs` | Refresh managed regions of README/CONTRIBUTING/SECURITY |
 | `gitpagedocs doctor` · `version` · `update` | Diagnostics / version / update hint |
@@ -134,9 +135,18 @@ npx gitpagedocs ai
 - asks provider (`openai`, `claude`, `gemini`, `ollama`)
 - asks API key or Ollama URL
 - asks paths to scan (supports one or many paths, including other repositories)
-- generates markdown documentation in `pt`, `en`, `es`
+- generates documentation in `pt`, `en`, `es` **in the gitpagedocs pattern**
 - optionally persists config in `.gitpagedocsconfig`
-- optionally runs standard `gitpagedocs` scaffolding after AI generation
+
+### gitpagedocs pattern output
+
+The model is given a gitpagedocs-aware system prompt and returns documentation split into
+pages (delimited by `=== PAGE: <slug> | <Title> ===`). The CLI scaffolds the base
+`gitpagedocs/` structure first, then writes each page to
+`gitpagedocs/docs/versions/<latest>/<lang>/<slug>.md` for every language and **wires it into
+that version's `config.json`** (`routes-md` + `menus-header-md`) so the pages render in the
+viewer menu. Entries are tagged `aiGenerated` and idempotent (re-running replaces them). A
+later plain `gitpagedocs` rebuild drops the wiring — re-run `gitpagedocs ai` to restore.
 
 ### `.gitpagedocsconfig` (manual mode)
 

package/ai/application/docs-pattern.ts

@@ -0,0 +1,68 @@
+/**
+ * Parse an AI documentation response into gitpagedocs pages.
+ *
+ * The model is instructed (see GITPAGEDOCS_DOC_SYSTEM_PROMPT) to delimit each
+ * page with a line `=== PAGE: <slug> | <Title> ===`. This splits that response
+ * into individual pages. If the model ignored the format, the whole response is
+ * returned as a single "ai-overview" page so content is never lost.
+ */
+
+export interface AiDocPage {
+  /** lowercase-kebab, English, identical across languages (used as the filename) */
+  slug: string;
+  title: string;
+  body: string;
+}
+
+const PAGE_DELIMITER = /^===\s*PAGE:\s*(.+?)\s*\|\s*(.*?)\s*===\s*$/;
+
+/** Turn an arbitrary heading into a safe lowercase-kebab slug. */
+export function slugify(raw: string): string {
+  const slug = (raw ?? "")
+    .toLowerCase()
+    .normalize("NFKD")
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "")
+    .slice(0, 60);
+  return slug || "page";
+}
+
+export function parseAiPages(markdown: string): AiDocPage[] {
+  const text = (markdown ?? "").replace(/\r\n/g, "\n").trim();
+  if (!text) return [];
+
+  const pages: AiDocPage[] = [];
+  let current: { slug: string; title: string; body: string[] } | null = null;
+
+  const flush = () => {
+    if (current) {
+      pages.push({ slug: current.slug, title: current.title, body: current.body.join("\n").trim() });
+    }
+  };
+
+  for (const line of text.split("\n")) {
+    const match = line.match(PAGE_DELIMITER);
+    if (match) {
+      flush();
+      const rawSlug = match[1].trim();
+      const title = match[2].trim() || rawSlug;
+      current = { slug: slugify(rawSlug), title, body: [] };
+    } else if (current) {
+      current.body.push(line);
+    }
+  }
+  flush();
+
+  const withBody = pages.filter((page) => page.body.length > 0);
+  if (withBody.length === 0) {
+    return [{ slug: "ai-overview", title: "Overview", body: text }];
+  }
+
+  // De-duplicate slugs within a single response (suffix later collisions).
+  const seen = new Map<string, number>();
+  return withBody.map((page) => {
+    const count = seen.get(page.slug) ?? 0;
+    seen.set(page.slug, count + 1);
+    return count === 0 ? page : { ...page, slug: `${page.slug}-${count + 1}` };
+  });
+}

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

@@ -1,4 +1,3 @@
-import path from "node:path";
 import { AiCommandService } from "./ai-command";
 import { createAiProvider } from "./ai-provider-factory";
 import { FileSystemAdapter, type FilePayload } from "../infrastructure/file-system-adapter";
@@ -7,6 +6,11 @@ import {
 } from "../infrastructure/ai-config-file";
 import type { AiCliRunPlan, AiCliRunSummary } from "../core/models/ai-cli-config";
 import { promptMissingDirectories, runAiInteractivePrompt } from "../presentation/ai-prompts";
+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";
 
 const LANGUAGE_TO_LABEL: Record<string, string> = {
   pt: "Portuguese",
@@ -22,7 +26,13 @@ function aggregateFilesPayload(files: FilePayload[]): string {
 
 function buildLanguagePrompt(basePrompt: string, language: "pt" | "en" | "es"): string {
   const languageLabel = LANGUAGE_TO_LABEL[language] ?? language;
-  return `${basePrompt}\n\nMandatory output rules:\n- Respond 100% in ${languageLabel}.\n- Generate professional markdown for technical documentation.\n- Include architectural overview, layer responsibilities, and next steps.\n- Avoid content outside the scope of the analyzed files.`;
+  const authorGuidance = basePrompt?.trim() ? `Additional author guidance:\n${basePrompt.trim()}\n\n` : "";
+  return (
+    `${GITPAGEDOCS_DOC_SYSTEM_PROMPT}\n\n` +
+    authorGuidance +
+    `Output language: write every page Title and body 100% in ${languageLabel}. ` +
+    `Keep each page slug lowercase-kebab and in English so the languages line up.`
+  );
 }
 
 async function collectFilesWithInteractiveFallback(
@@ -66,7 +76,7 @@ async function collectFilesWithInteractiveFallback(
   };
 }
 
-async function runPlan(plan: AiCliRunPlan): Promise<AiCliRunSummary> {
+async function runPlan(plan: AiCliRunPlan, cwd: string): Promise<AiCliRunSummary> {
   const provider = createAiProvider({
     provider: plan.config.ai.provider,
     model: plan.config.ai.model,
@@ -92,30 +102,33 @@ async function runPlan(plan: AiCliRunPlan): Promise<AiCliRunSummary> {
   }
 
   const payload = aggregateFilesPayload(files);
-  const outputs: string[] = [];
+  const pagesByLang: Partial<Record<"pt" | "en" | "es", AiDocPage[]>> = {};
 
   for (const language of plan.config.ai.languages) {
     const prompt = buildLanguagePrompt(plan.config.ai.contextPrompt, language);
     const markdown = await aiService.runGeneration(payload, prompt);
-    const outputFile = path.posix.join(
-      plan.config.ai.outputDir.replace(/\\/g, "/"),
-      `${plan.config.ai.filePrefix}-${plan.config.ai.provider}-${language}.md`,
-    );
-    await fileSystem.writeDocumentationOutput(markdown, outputFile);
-    outputs.push(outputFile);
+    pagesByLang[language] = parseAiPages(markdown);
   }
 
+  // Wire the AI pages into the latest documentation version (gitpagedocs pattern).
+  const versionId = DOC_VERSIONS[DOC_VERSIONS.length - 1] as string;
+  const result = await writeVersionDocs({ cwd, versionId, pagesByLang });
+
   return {
     scannedDirectories: scanned,
     skippedDirectories: skipped,
     scannedFilesCount: files.length,
-    outputs,
+    outputs: result.files,
+    pages: result.slugs,
   };
 }
 
 export async function runAiCliCommand(options: {
   cwd: string;
   onInfo?: (message: string) => void;
+  /** Provided by the composition root to scaffold the base gitpagedocs/ tree
+   * (so the version config.json exists before AI pages are wired into it). */
+  onScaffold?: () => Promise<void>;
 }): Promise<{ summary: AiCliRunSummary; runConfigScaffold: boolean }> {
   const logInfo = options.onInfo ?? (() => undefined);
   const configRepo = new AiConfigFileRepository(options.cwd);
@@ -128,7 +141,14 @@ export async function runAiCliCommand(options: {
     logInfo(`[gitpagedocs:ai] Configuration saved to ${configRepo.getConfigPath()}`);
   }
 
-  const summary = await runPlan(plan);
+  // Build the base gitpagedocs structure BEFORE generation so the version
+  // config.json exists and the AI pages can be wired into it.
+  if (plan.runConfigScaffold && options.onScaffold) {
+    logInfo("[gitpagedocs] Generating base gitpagedocs structure...");
+    await options.onScaffold();
+  }
+
+  const summary = await runPlan(plan, options.cwd);
   return {
     summary,
     runConfigScaffold: plan.runConfigScaffold,

package/ai/config.ts

@@ -19,4 +19,32 @@ export const AI_MODEL_DEFAULTS: Readonly<Record<AiProviderId, string>> = {
 export const DEFAULT_AI_DOC_PROMPT =
   'You are a senior tech writer. Describe the provided code.';
 
+/**
+ * System prompt that teaches the model what gitpagedocs is and forces it to
+ * return documentation in the gitpagedocs pattern: a sequence of pages, each
+ * introduced by a machine-parseable delimiter line so the CLI can split the
+ * response into individual versioned markdown pages and wire them into the
+ * viewer's config.json (routes-md + menus-header-md).
+ */
+export const GITPAGEDOCS_DOC_SYSTEM_PROMPT = [
+  'You are the documentation engine for "gitpagedocs", a generator of multilingual,',
+  'versioned static documentation sites. gitpagedocs renders markdown pages from',
+  'gitpagedocs/docs/versions/<version>/<lang>/<page>.md and wires them into a viewer',
+  'through a config.json contract (routes + header menus). Your job is to analyze the',
+  'provided source code and produce clean, professional documentation that fits this',
+  'pattern so it can be dropped straight into a gitpagedocs site.',
+  '',
+  'STRICT OUTPUT FORMAT — return ONLY a sequence of pages. Begin every page with a',
+  'delimiter line on its own, exactly:',
+  '=== PAGE: <slug> | <Title> ===',
+  'followed by the page body in GitHub-flavored markdown. Rules:',
+  '- Produce 4 to 8 cohesive pages. Suggested slugs: overview, getting-started,',
+  '  architecture, configuration, usage, deployment (adapt to the project).',
+  '- <slug> MUST be lowercase-kebab-case and in ENGLISH, and identical across every',
+  '  language run, so the languages line up (only the Title and body are translated).',
+  '- Do NOT wrap the whole answer in a code fence. Do NOT add any preamble or epilogue',
+  '  outside the page blocks. The first line of your reply MUST be a "=== PAGE:" line.',
+  '- Base everything strictly on the analyzed files; do not invent features.',
+].join('\n');
+
 export const OLLAMA_DEFAULT_BASE_URL = 'http://localhost:11434';

package/ai/core/models/ai-cli-config.ts

@@ -28,4 +28,6 @@ export interface AiCliRunSummary {
   skippedDirectories: string[];
   scannedFilesCount: number;
   outputs: string[];
+  /** Slugs of the gitpagedocs pages wired into the version config (if any). */
+  pages?: string[];
 }

package/ai/infrastructure/version-docs-writer.ts

@@ -0,0 +1,143 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+// @ts-expect-error .mjs runtime module is type-less in this package.
+import { buildMdRoute } from "../../builders/route-builders.mjs";
+import type { AiDocPage } from "../application/docs-pattern";
+
+const CANONICAL_LANGS = ["pt", "en", "es"] as const;
+type Lang = (typeof CANONICAL_LANGS)[number];
+
+/** AI routes/menus use a high, dedicated id range so they never clash with the
+ * deterministic base routes (ids 1..N) and can be identified for idempotency. */
+const AI_ROUTE_ID_BASE = 1000;
+
+export interface VersionDocsWriteInput {
+  cwd: string;
+  versionId: string;
+  /** Pages generated per language (only the languages the user selected). */
+  pagesByLang: Partial<Record<Lang, AiDocPage[]>>;
+}
+
+export interface VersionDocsWriteResult {
+  configPath: string;
+  slugs: string[];
+  files: string[];
+}
+
+interface LangContent {
+  title: string;
+  body: string;
+}
+
+function indexBySlug(pages: AiDocPage[] | undefined): Map<string, AiDocPage> {
+  const map = new Map<string, AiDocPage>();
+  for (const page of pages ?? []) {
+    if (!map.has(page.slug)) map.set(page.slug, page);
+  }
+  return map;
+}
+
+/**
+ * Write AI-generated pages into the gitpagedocs versioned structure and wire
+ * them into the version config.json (routes-md + menus-header-md). Pages are
+ * written for ALL three canonical languages (missing languages reuse an
+ * available translation) so every route path stays valid. Idempotent: any prior
+ * `aiGenerated` routes/menus are replaced, never duplicated. The base config and
+ * its deterministic routes are preserved untouched.
+ */
+export async function writeVersionDocs(input: VersionDocsWriteInput): Promise<VersionDocsWriteResult> {
+  const { cwd, versionId, pagesByLang } = input;
+  const base = `gitpagedocs/docs/versions/${versionId}`;
+
+  const perLang: Record<Lang, Map<string, AiDocPage>> = {
+    pt: indexBySlug(pagesByLang.pt),
+    en: indexBySlug(pagesByLang.en),
+    es: indexBySlug(pagesByLang.es),
+  };
+
+  // Ordered unique slug list (prefer en order, then pt, then es).
+  const order: string[] = [];
+  const seen = new Set<string>();
+  for (const lang of ["en", "pt", "es"] as Lang[]) {
+    for (const page of pagesByLang[lang] ?? []) {
+      if (!seen.has(page.slug)) {
+        seen.add(page.slug);
+        order.push(page.slug);
+      }
+    }
+  }
+  if (order.length === 0) {
+    throw new Error("No AI pages to write.");
+  }
+
+  const resolve = (slug: string): Record<Lang, LangContent> => {
+    const fallback = CANONICAL_LANGS.map((lang) => perLang[lang].get(slug)).find(Boolean);
+    const out = {} as Record<Lang, LangContent>;
+    for (const lang of CANONICAL_LANGS) {
+      const page = perLang[lang].get(slug) ?? fallback!;
+      out[lang] = { title: page.title, body: page.body };
+    }
+    return out;
+  };
+
+  // 1) Write the markdown files (all 3 canonical languages).
+  const writtenFiles: string[] = [];
+  for (const slug of order) {
+    const content = resolve(slug);
+    for (const lang of CANONICAL_LANGS) {
+      const rel = `${base}/${lang}/${slug}.md`;
+      const abs = path.resolve(cwd, rel);
+      await fs.mkdir(path.dirname(abs), { recursive: true });
+      await fs.writeFile(abs, `${content[lang].body}\n`, "utf-8");
+      writtenFiles.push(rel);
+    }
+  }
+
+  // 2) Patch the version config.json (raw JSON round-trip, preserve all keys).
+  const configRel = `${base}/config.json`;
+  const configAbs = path.resolve(cwd, configRel);
+  let raw: string;
+  try {
+    raw = await fs.readFile(configAbs, "utf-8");
+  } catch {
+    throw new Error(
+      `Version config not found at ${configRel}. Run the base scaffold (\`gitpagedocs\`) first.`,
+    );
+  }
+  const config = JSON.parse(raw) as Record<string, unknown>;
+
+  const routesMd = Array.isArray(config["routes-md"]) ? (config["routes-md"] as Array<Record<string, unknown>>) : [];
+  const menusMd = Array.isArray(config["menus-header-md"]) ? (config["menus-header-md"] as Array<Record<string, unknown>>) : [];
+  const keptRoutes = routesMd.filter((route) => route?.aiGenerated !== true);
+  const keptMenus = menusMd.filter((menu) => menu?.aiGenerated !== true);
+
+  const newRoutes: Array<Record<string, unknown>> = [];
+  const newMenus: Array<Record<string, unknown>> = [];
+  order.forEach((slug, index) => {
+    const content = resolve(slug);
+    const id = AI_ROUTE_ID_BASE + index + 1;
+    const pathByLang = {
+      pt: `${base}/pt/${slug}.md`,
+      en: `${base}/en/${slug}.md`,
+      es: `${base}/es/${slug}.md`,
+    };
+    const titles = { pt: content.pt.title, en: content.en.title, es: content.es.title };
+    const descriptions = { pt: "", en: "", es: "" };
+    const route = buildMdRoute(versionId, id, pathByLang, titles, descriptions, {}) as Record<string, unknown>;
+    route.aiGenerated = true;
+    newRoutes.push(route);
+    newMenus.push({
+      id,
+      aiGenerated: true,
+      pt: { title: content.pt.title, "path-click": pathByLang.pt },
+      en: { title: content.en.title, "path-click": pathByLang.en },
+      es: { title: content.es.title, "path-click": pathByLang.es },
+    });
+  });
+
+  config["routes-md"] = [...keptRoutes, ...newRoutes];
+  config["menus-header-md"] = [...keptMenus, ...newMenus];
+  await fs.writeFile(configAbs, `${JSON.stringify(config, null, 2)}\n`, "utf-8");
+
+  return { configPath: configRel, slugs: order, files: writtenFiles };
+}

package/ai/presentation/ai-prompts.ts

@@ -141,7 +141,7 @@ export async function promptUseExistingConfig(existingConfig: AiCliConfig): Prom
     if (!useExistingConfig) return null;
 
     const runConfigScaffold = await askConfirm(
-        'After generating docs with AI, run the default gitpagedocs scaffolding?',
+        'Generate the base gitpagedocs structure first, so the AI pages are wired into the docs viewer?',
         true,
     );
 
@@ -220,7 +220,7 @@ export async function runAiInteractivePrompt(existingConfig?: AiCliConfig | null
     );
 
     const runConfigScaffold = await askConfirm(
-        'After generating docs with AI, run the default gitpagedocs scaffolding?',
+        'Generate the base gitpagedocs structure first, so the AI pages are wired into the docs viewer?',
         true,
     );
 

package/builders/root-config-builder.mjs

@@ -44,6 +44,7 @@ export function buildRootConfig(options = {}) {
       repositorySearchHome,
       rendering: renderingUrl,
       AiChatEnabled: true,
+      docsAccess: { enabled: false, publicKey: "" },
       langmenu: defaultLangMenu,
     },
     VersionControl: {

package/data/default-site-config.mjs

@@ -114,6 +114,15 @@ export function getDefaultSiteConfig(DOCS, projectLink) {
         IconNavMenuBlockInactiveReactIconesTagSize: "25px",
         IconNavMenuBlockInactiveImgWidth: 20,
         IconNavMenuBlockInactiveImgHeight: 20,
+        IconDocsLockLightImg: "",
+        IconDocsLockDarkImg: "",
+        IconDocsLockReactIcones: true,
+        IconDocsLockReactIconesTag: "FiLock",
+        IconDocsLockReactIconesTagColorDark: "White",
+        IconDocsLockReactIconesTagColorLight: "black",
+        IconDocsLockReactIconesTagSize: "22px",
+        IconDocsLockImgWidth: 20,
+        IconDocsLockImgHeight: 20,
         RouteguideBrandPositionDefault: "center",
         RouteguideBrandContainerTopDefault: false,
         audioPlayerEnabled: true,

package/data/i18n-langmenu.mjs

@@ -38,6 +38,67 @@ export const defaultLangMenu = {
           audioPopoverStatusPaused: "Pausado",
           audioPopoverStatusLoopOn: "Loop ativado",
           audioPopoverStatusLoopOff: "Loop desativado",
+          aiChatTitle: "Assistente de IA",
+          aiChatPlaceholder: "Pergunte sobre a documentação...",
+          aiChatConfigTitle: "Configurar IA",
+          aiChatConfigDesc: "Insira sua chave de API para ativar o chat.",
+          aiChatClearDataBtn: "Limpar dados locais",
+          aiChatSendBtn: "Enviar",
+          aiChatSaveStartBtn: "Salvar e iniciar conversa",
+          aiChatAttachAriaLabel: "Anexar arquivo de áudio ou imagem",
+          aiChatAttachedFilesLabel: "arquivo(s) anexado(s)",
+          aiChatRemoveAttachmentBtn: "Remover",
+          aiChatCancelResponseLabel: "Cancelar resposta",
+          aiChatOpenBtnAriaLabel: "Abrir chat de IA",
+          aiChatCloseBtnAriaLabel: "Fechar chat",
+          aiChatSystemPrompt: "You are the official AI documentation assistant for the '{headerName}' project. Your primary role is to answer questions strictly related to the project's documentation, configurations (like config.json), and markdown files located in the 'gitpagedocs' directory. Be highly professional and helpful.\n\nIMPORTANT: You MUST address the user and respond EXCLUSIVELY in the following language: {language}.\n\nHere is the raw content of the active page the user is currently looking at:\n[Page ID]: {pageId}\n[Hidden Current Context Content]:\n{rawContent}",
+          aiChatEmptyStateGreeting: "Olá! Eu sou o assistente de inteligência artificial desta documentação. Você pode me fazer perguntas sobre o conteúdo ou buscar um termo em toda a documentação. Como posso ajudar você hoje?",
+          aiChatDisclaimer: "A IA pode cometer erros. Sempre verifique as informações.",
+          aiChatPasswordCreateDesc: "Crie uma senha local para criptografar suas chaves de API.",
+          aiChatPasswordUnlockDesc: "Digite sua senha local para desbloquear.",
+          aiChatPasswordPlaceholder: "Senha local",
+          aiChatCreatePasswordBtn: "Criar senha",
+          aiChatUnlockBtn: "Desbloquear",
+          aiChatWrongPassword: "Senha incorreta.",
+          aiChatLockBtn: "Bloquear",
+          aiChatResetBtn: "Esqueceu a senha?",
+          aiChatResetPopupTitle: "Redefinir senha?",
+          aiChatResetPopupDesc: "Isso apaga todas as chaves de API salvas e a senha local. Você criará uma nova senha na próxima vez.",
+          aiChatResetConfirmBtn: "Sim, redefinir",
+          aiChatResetCancelBtn: "Cancelar",
+          aiChatProviderLabel: "Provedor:",
+          aiChatApiKeyLabel: "Chave de API (deixe em branco para IA local):",
+          aiChatProviderOpenAI: "OpenAI (GPT-4o-mini)",
+          aiChatProviderClaude: "Anthropic Claude (3.5 Sonnet)",
+          aiChatProviderGemini: "Google Gemini (1.5 Flash)",
+          aiChatProviderOllama: "Ollama Network (Local LLMs)",
+          aiChatEmptyPageContent: "Nenhuma página ativa compatível.",
+          aiChatNoPageId: "Sem página",
+          aiChatOllamaUrlLabel: "URL da API Ollama (deixe em branco para local)",
+          aiChatClearChatPopupTitle: "Limpar conversa?",
+          aiChatClearChatPopupDesc: "Isso apagará todo o histórico atual do chat. Esta ação não pode ser desfeita.",
+          aiChatClearChatConfirmBtn: "Sim, apagar",
+          aiChatClearChatCancelBtn: "Cancelar",
+          aiChatClearDataPopupTitle: "Apagar todos os dados?",
+          aiChatClearDataPopupDesc: "Isso apagará todos os chats e as chaves de API locais. O chat de IA será fechado.",
+          aiChatClearDataConfirmBtn: "Sim, apagar tudo",
+          aiChatClearDataCancelBtn: "Cancelar",
+          aiChatUserLabel: "Você",
+          aiChatApiError: "Ocorreu um erro de conexão com a API.",
+          aiChatError401: "Chave de acesso inválida ou provedor não autorizado.",
+          aiChatError429: "Limite de requisições excedido. Tente novamente mais tarde.",
+          aiChatError500: "Ocorreu um erro interno no servidor do modelo de IA.",
+          aiChatErrorGeneric: "Ocorreu um erro inesperado ao se comunicar com a IA.",
+          docsAccessGateTitle: "Documentação protegida",
+          docsAccessGateDescription: "Digite a senha ou a chave privada para acessar a documentação.",
+          docsAccessInputPlaceholder: "Senha ou chave privada",
+          docsAccessUnlockBtn: "Desbloquear",
+          docsAccessWrongCredential: "Senha ou chave incorreta.",
+          docsAccessLockTooltip: "Bloquear documentação",
+          docsAccessBlockPopupTitle: "Bloquear a documentação?",
+          docsAccessBlockPopupDesc: "Você precisará da senha novamente na próxima visita.",
+          docsAccessBlockConfirmBtn: "Sim, bloquear",
+          docsAccessBlockCancelBtn: "Cancelar",
         },
         en: {
           pt: "Portuguese",
@@ -78,6 +139,67 @@ export const defaultLangMenu = {
           audioPopoverStatusPaused: "Paused",
           audioPopoverStatusLoopOn: "Loop on",
           audioPopoverStatusLoopOff: "Loop off",
+          aiChatTitle: "AI Assistant",
+          aiChatPlaceholder: "Ask about the documentation...",
+          aiChatConfigTitle: "Configure AI",
+          aiChatConfigDesc: "Enter your API key to enable the chat.",
+          aiChatClearDataBtn: "Clear local data",
+          aiChatSendBtn: "Send",
+          aiChatSaveStartBtn: "Save & Start Chatting",
+          aiChatAttachAriaLabel: "Attach audio or image file",
+          aiChatAttachedFilesLabel: "file(s) attached",
+          aiChatRemoveAttachmentBtn: "Remove",
+          aiChatCancelResponseLabel: "Cancel response",
+          aiChatOpenBtnAriaLabel: "Open AI Chat",
+          aiChatCloseBtnAriaLabel: "Close chat",
+          aiChatSystemPrompt: "You are the official AI documentation assistant for the '{headerName}' project. Your primary role is to answer questions strictly related to the project's documentation, configurations (like config.json), and markdown files located in the 'gitpagedocs' directory. Be highly professional and helpful.\n\nIMPORTANT: You MUST address the user and respond EXCLUSIVELY in the following language: {language}.\n\nHere is the raw content of the active page the user is currently looking at:\n[Page ID]: {pageId}\n[Hidden Current Context Content]:\n{rawContent}",
+          aiChatEmptyStateGreeting: "Hello! I am the artificial intelligence assistant of this documentation. You can ask me questions about the content or search for a term across the documentation. How can I help you today?",
+          aiChatDisclaimer: "AI can make mistakes. Always verify the information.",
+          aiChatPasswordCreateDesc: "Create a local password to encrypt your API keys.",
+          aiChatPasswordUnlockDesc: "Enter your local password to unlock.",
+          aiChatPasswordPlaceholder: "Local password",
+          aiChatCreatePasswordBtn: "Create password",
+          aiChatUnlockBtn: "Unlock",
+          aiChatWrongPassword: "Incorrect password.",
+          aiChatLockBtn: "Lock",
+          aiChatResetBtn: "Forgot password?",
+          aiChatResetPopupTitle: "Reset password?",
+          aiChatResetPopupDesc: "This erases all saved API keys and the local password. You'll create a new password next time.",
+          aiChatResetConfirmBtn: "Yes, reset",
+          aiChatResetCancelBtn: "Cancel",
+          aiChatProviderLabel: "Provider:",
+          aiChatApiKeyLabel: "API Key (leave blank for Local AI):",
+          aiChatProviderOpenAI: "OpenAI (GPT-4o-mini)",
+          aiChatProviderClaude: "Anthropic Claude (3.5 Sonnet)",
+          aiChatProviderGemini: "Google Gemini (1.5 Flash)",
+          aiChatProviderOllama: "Ollama Network (Local LLMs)",
+          aiChatEmptyPageContent: "No compatible active page.",
+          aiChatNoPageId: "No page",
+          aiChatOllamaUrlLabel: "Ollama API URL (leave blank for local)",
+          aiChatClearChatPopupTitle: "Clear conversation?",
+          aiChatClearChatPopupDesc: "This will delete all current chat history. This action cannot be undone.",
+          aiChatClearChatConfirmBtn: "Yes, delete",
+          aiChatClearChatCancelBtn: "Cancel",
+          aiChatClearDataPopupTitle: "Erase all data?",
+          aiChatClearDataPopupDesc: "This will delete all chats and local API keys. The AI chat will be closed.",
+          aiChatClearDataConfirmBtn: "Yes, erase everything",
+          aiChatClearDataCancelBtn: "Cancel",
+          aiChatUserLabel: "You",
+          aiChatApiError: "An API connection error occurred.",
+          aiChatError401: "Invalid access key or unauthorized provider.",
+          aiChatError429: "Rate limit exceeded. Please try again later.",
+          aiChatError500: "An internal server error occurred on the AI model.",
+          aiChatErrorGeneric: "An unexpected error occurred while communicating with the AI.",
+          docsAccessGateTitle: "Protected documentation",
+          docsAccessGateDescription: "Enter the password or private key to view the documentation.",
+          docsAccessInputPlaceholder: "Password or private key",
+          docsAccessUnlockBtn: "Unlock",
+          docsAccessWrongCredential: "Incorrect password or key.",
+          docsAccessLockTooltip: "Lock documentation",
+          docsAccessBlockPopupTitle: "Block the documentation?",
+          docsAccessBlockPopupDesc: "You'll need the password again on your next visit.",
+          docsAccessBlockConfirmBtn: "Yes, block",
+          docsAccessBlockCancelBtn: "Cancel",
         },
         es: {
           pt: "Portugues",
@@ -118,5 +240,66 @@ export const defaultLangMenu = {
           audioPauseLabel: "Pausar música de fondo",
           audioPlaylistTitle: "Elegir pista",
           audioPlaylistDescription: "Seleccione una pista para reproducir de la playlist.",
+          aiChatTitle: "Asistente de IA",
+          aiChatPlaceholder: "Pregunta sobre la documentación...",
+          aiChatConfigTitle: "Configurar IA",
+          aiChatConfigDesc: "Introduce tu clave de API para activar el chat.",
+          aiChatClearDataBtn: "Borrar datos locales",
+          aiChatSendBtn: "Enviar",
+          aiChatSaveStartBtn: "Guardar y empezar a chatear",
+          aiChatAttachAriaLabel: "Adjuntar archivo de audio o imagen",
+          aiChatAttachedFilesLabel: "archivo(s) adjunto(s)",
+          aiChatRemoveAttachmentBtn: "Quitar",
+          aiChatCancelResponseLabel: "Cancelar respuesta",
+          aiChatOpenBtnAriaLabel: "Abrir chat de IA",
+          aiChatCloseBtnAriaLabel: "Cerrar chat",
+          aiChatSystemPrompt: "You are the official AI documentation assistant for the '{headerName}' project. Your primary role is to answer questions strictly related to the project's documentation, configurations (like config.json), and markdown files located in the 'gitpagedocs' directory. Be highly professional and helpful.\n\nIMPORTANT: You MUST address the user and respond EXCLUSIVELY in the following language: {language}.\n\nHere is the raw content of the active page the user is currently looking at:\n[Page ID]: {pageId}\n[Hidden Current Context Content]:\n{rawContent}",
+          aiChatEmptyStateGreeting: "¡Hola! Soy el asistente de inteligencia artificial de esta documentación. Puedes hacerme preguntas sobre el contenido o buscar un término en toda la documentación. ¿Cómo puedo ayudarte hoy?",
+          aiChatDisclaimer: "La IA puede cometer errores. Verifica siempre la información.",
+          aiChatPasswordCreateDesc: "Crea una contraseña local para cifrar tus claves de API.",
+          aiChatPasswordUnlockDesc: "Introduce tu contraseña local para desbloquear.",
+          aiChatPasswordPlaceholder: "Contraseña local",
+          aiChatCreatePasswordBtn: "Crear contraseña",
+          aiChatUnlockBtn: "Desbloquear",
+          aiChatWrongPassword: "Contraseña incorrecta.",
+          aiChatLockBtn: "Bloquear",
+          aiChatResetBtn: "¿Olvidaste la contraseña?",
+          aiChatResetPopupTitle: "¿Restablecer contraseña?",
+          aiChatResetPopupDesc: "Esto borra todas las claves de API guardadas y la contraseña local. Crearás una nueva contraseña la próxima vez.",
+          aiChatResetConfirmBtn: "Sí, restablecer",
+          aiChatResetCancelBtn: "Cancelar",
+          aiChatProviderLabel: "Proveedor:",
+          aiChatApiKeyLabel: "Clave de API (déjalo en blanco para IA local):",
+          aiChatProviderOpenAI: "OpenAI (GPT-4o-mini)",
+          aiChatProviderClaude: "Anthropic Claude (3.5 Sonnet)",
+          aiChatProviderGemini: "Google Gemini (1.5 Flash)",
+          aiChatProviderOllama: "Ollama Network (Local LLMs)",
+          aiChatEmptyPageContent: "Ninguna página activa compatible.",
+          aiChatNoPageId: "Sin página",
+          aiChatOllamaUrlLabel: "URL de la API de Ollama (déjalo en blanco para local)",
+          aiChatClearChatPopupTitle: "¿Borrar conversación?",
+          aiChatClearChatPopupDesc: "Esto eliminará todo el historial de chat actual. Esta acción no se puede deshacer.",
+          aiChatClearChatConfirmBtn: "Sí, borrar",
+          aiChatClearChatCancelBtn: "Cancelar",
+          aiChatClearDataPopupTitle: "¿Borrar todos los datos?",
+          aiChatClearDataPopupDesc: "Esto eliminará todos los chats y las claves de API locales. El chat de IA se cerrará.",
+          aiChatClearDataConfirmBtn: "Sí, borrar todo",
+          aiChatClearDataCancelBtn: "Cancelar",
+          aiChatUserLabel: "Tú",
+          aiChatApiError: "Se produjo un error de conexión con la API.",
+          aiChatError401: "Clave de acceso no válida o proveedor no autorizado.",
+          aiChatError429: "Límite de solicitudes superado. Inténtalo de nuevo más tarde.",
+          aiChatError500: "Se produjo un error interno del servidor en el modelo de IA.",
+          aiChatErrorGeneric: "Se produjo un error inesperado al comunicarse con la IA.",
+          docsAccessGateTitle: "Documentación protegida",
+          docsAccessGateDescription: "Introduce la contraseña o la clave privada para ver la documentación.",
+          docsAccessInputPlaceholder: "Contraseña o clave privada",
+          docsAccessUnlockBtn: "Desbloquear",
+          docsAccessWrongCredential: "Contraseña o clave incorrecta.",
+          docsAccessLockTooltip: "Bloquear documentación",
+          docsAccessBlockPopupTitle: "¿Bloquear la documentación?",
+          docsAccessBlockPopupDesc: "Tendrás que introducir la contraseña de nuevo en la próxima visita.",
+          docsAccessBlockConfirmBtn: "Sí, bloquear",
+          docsAccessBlockCancelBtn: "Cancelar",
         },
       };

package/infrastructure/gitpagedocs-config-file.ts

@@ -0,0 +1,47 @@
+import fs from "node:fs/promises";
+import { defaultConfigLoader } from "@gitpagedocs/tools";
+
+export interface DocsAccessConfig {
+  enabled: boolean;
+  publicKey: string;
+}
+
+/**
+ * Reads and patches the generated gitpagedocs/config.json IN PLACE, preserving
+ * every existing key (raw-JSON round-trip — it never reserializes through a typed
+ * model that could drop unknown fields). Used by interactive commands that need
+ * to persist a single value (e.g. the documentation password public key).
+ */
+export class GitPageDocsConfigRepository {
+  constructor(private readonly cwd: string = process.cwd()) {}
+
+  /** Absolute path to the JSON config, or throws a friendly, actionable error. */
+  async resolvePath(): Promise<string> {
+    const resolved = await defaultConfigLoader.resolveConfigPath(this.cwd);
+    if (!resolved) {
+      throw new Error("gitpagedocs config.json not found. Run `gitpagedocs` first to generate it.");
+    }
+    if (!resolved.endsWith(".json")) {
+      throw new Error(`Expected a JSON config to patch, found "${resolved}". Use a gitpagedocs/config.json.`);
+    }
+    return resolved;
+  }
+
+  /**
+   * Set `site.docsAccess = { enabled, publicKey }`, leaving all other config keys
+   * untouched. Returns the path that was written.
+   */
+  async patchDocsAccess(publicKey: string, enabled = true): Promise<string> {
+    const configPath = await this.resolvePath();
+    const raw = await fs.readFile(configPath, "utf-8");
+    const config = JSON.parse(raw) as Record<string, unknown>;
+    const site =
+      config.site && typeof config.site === "object"
+        ? (config.site as Record<string, unknown>)
+        : {};
+    site.docsAccess = { enabled, publicKey } satisfies DocsAccessConfig;
+    config.site = site;
+    await fs.writeFile(configPath, `${JSON.stringify(config, null, 2)}\n`, "utf-8");
+    return configPath;
+  }
+}

package/package.json

@@ -1,60 +1,60 @@
-{
-  "name": "@gitpagedocs/cli",
-  "version": "1.1.49",
-  "description": "CLI that scaffolds and maintains gitpagedocs documentation, generates docs with AI, configures GitHub Pages, and runs the MCP server.",
-  "bin": {
-    "gitpagedocs": "index.mjs"
-  },
-  "main": "index.mjs",
-  "files": [
-    "index.mjs",
-    "start.mjs",
-    "ai",
-    "application",
-    "builders",
-    "content",
-    "contracts",
-    "data",
-    "domain",
-    "home",
-    "infrastructure",
-    "presentation",
-    "runtime",
-    "ui",
-    "prebuilt",
-    "README.md"
-  ],
-  "engines": {
-    "node": ">=20"
-  },
-  "dependencies": {
-    "@clack/prompts": "^1.5.1",
-    "@gitpagedocs/mcp": "^1.1.49",
-    "@gitpagedocs/tools": "^1.1.49",
-    "tsx": "^4.21.0"
-  },
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/Vidigal-code/git-page-docs.git",
-    "directory": "cli"
-  },
-  "keywords": [
-    "gitpagedocs",
-    "documentation",
-    "markdown",
-    "spa",
-    "cli",
-    "github-pages",
-    "create-gitpagedocs"
-  ],
-  "author": "Vidigal-code",
-  "license": "ISC",
-  "bugs": {
-    "url": "https://github.com/Vidigal-code/git-page-docs/issues"
-  },
-  "homepage": "https://vidigal-code.github.io/git-page-docs/",
-  "publishConfig": {
-    "registry": "https://registry.npmjs.org/",
-    "access": "public"
-  }
-}
+{
+  "name": "@gitpagedocs/cli",
+  "version": "1.1.52",
+  "description": "CLI that scaffolds and maintains gitpagedocs documentation, generates docs with AI, configures GitHub Pages, and runs the MCP server.",
+  "bin": {
+    "gitpagedocs": "index.mjs"
+  },
+  "main": "index.mjs",
+  "files": [
+    "index.mjs",
+    "start.mjs",
+    "ai",
+    "application",
+    "builders",
+    "content",
+    "contracts",
+    "data",
+    "domain",
+    "home",
+    "infrastructure",
+    "presentation",
+    "runtime",
+    "ui",
+    "prebuilt",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "dependencies": {
+    "@clack/prompts": "^1.5.1",
+    "@gitpagedocs/mcp": "^1.1.52",
+    "@gitpagedocs/tools": "^1.1.52",
+    "tsx": "^4.21.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Vidigal-code/git-page-docs.git",
+    "directory": "cli"
+  },
+  "keywords": [
+    "gitpagedocs",
+    "documentation",
+    "markdown",
+    "spa",
+    "cli",
+    "github-pages",
+    "create-gitpagedocs"
+  ],
+  "author": "Vidigal-code",
+  "license": "ISC",
+  "bugs": {
+    "url": "https://github.com/Vidigal-code/git-page-docs/issues"
+  },
+  "homepage": "https://vidigal-code.github.io/git-page-docs/",
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org/",
+    "access": "public"
+  }
+}

package/presentation/commands/pages.ts

@@ -2,6 +2,7 @@ import path from "node:path";
 import { spawnSync } from "node:child_process";
 import type { CommandContext } from "./run-command";
 import { askConfirm } from "../ui/clack";
+import { askOwnerRepo, interactivePromptsAvailable } from "../ui/prompts";
 // @ts-expect-error .mjs runtime module
 import { detectRepoFromGit, getCurrentGitBranch, tryConfigurePagesToGitHubActions } from "../../runtime/git-ops.mjs";
 
@@ -21,11 +22,14 @@ function readFlag(args: string[], name: string): string {
  * overwrite). Does NOT generate docs or push (that is `pages deploy`).
  */
 export async function runPagesActions(ctx: CommandContext): Promise<void> {
-  const repo = detectRepoFromGit(ctx.cwd) as { owner: string; repo: string } | null;
+  let repo = detectRepoFromGit(ctx.cwd) as { owner: string; repo: string } | null;
   if (!repo) {
-    // eslint-disable-next-line no-console
-    console.log("\n  Could not detect a GitHub repo from the git 'origin' remote.\n  Add a remote or use `--push --owner <o> --repo <r>`.\n");
-    return;
+    if (!interactivePromptsAvailable()) {
+      // eslint-disable-next-line no-console
+      console.log("\n  Could not detect a GitHub repo from the git 'origin' remote.\n  Add a remote or use `--push --owner <o> --repo <r>`.\n");
+      return;
+    }
+    repo = await askOwnerRepo(null);
   }
   const branch = getCurrentGitBranch(ctx.cwd) as string;
   // eslint-disable-next-line no-console
@@ -59,9 +63,14 @@ export async function runPagesDeploy(ctx: CommandContext): Promise<void> {
     }
   }
   if (!owner || !repo) {
-    // eslint-disable-next-line no-console
-    console.log("\n  Could not determine owner/repo. Pass `--owner <o> --repo <r>` or add a git 'origin' remote.\n");
-    return;
+    if (!interactivePromptsAvailable()) {
+      // eslint-disable-next-line no-console
+      console.log("\n  Could not determine owner/repo. Pass `--owner <o> --repo <r>` or add a git 'origin' remote.\n");
+      return;
+    }
+    const answered = await askOwnerRepo(null, { owner, repo });
+    owner = answered.owner;
+    repo = answered.repo;
   }
 
   // eslint-disable-next-line no-console
@@ -76,7 +85,8 @@ export async function runPagesDeploy(ctx: CommandContext): Promise<void> {
     return;
   }
 
-  const bin = path.join(ctx.pkgRoot, "cli", "index.mjs");
+  // pkgRoot is the cli package root (cli/), where the bin lives as index.mjs.
+  const bin = path.join(ctx.pkgRoot, "index.mjs");
   const pushArgs = ["--push", "--owner", owner, "--repo", repo, ...(docsPath ? ["--path", docsPath] : [])];
   const result = spawnSync(process.execPath, [bin, ...pushArgs], { stdio: "inherit", cwd: ctx.cwd, env: process.env });
 

package/presentation/commands/password.ts

@@ -0,0 +1,62 @@
+import { NodeCryptoService, deriveDocAccessKeys } from "@gitpagedocs/tools";
+import type { CommandContext } from "./run-command";
+import { askPassword, note, outro } from "../ui/clack";
+import { interactivePromptsAvailable } from "../ui/prompts";
+import { GitPageDocsConfigRepository } from "../../infrastructure/gitpagedocs-config-file";
+
+const MIN_PASSWORD_LENGTH = 4;
+
+/**
+ * `gitpagedocs password` — interactively set a documentation access password.
+ *
+ * Type + confirm a password, derive the double-hash key pair, write the PUBLIC
+ * key into gitpagedocs/config.json (which makes the frontend gate the docs), and
+ * print the PRIVATE key for the user to copy. The password itself is never stored.
+ */
+export async function runPassword(ctx: CommandContext): Promise<void> {
+  if (!interactivePromptsAvailable()) {
+    // eslint-disable-next-line no-console
+    console.log("\n  `gitpagedocs password` is interactive — run it in a terminal (TTY).\n");
+    return;
+  }
+
+  const password = await askPassword({
+    message: "Documentation password:",
+    validate: (v) =>
+      v && v.trim().length >= MIN_PASSWORD_LENGTH
+        ? undefined
+        : `Use at least ${MIN_PASSWORD_LENGTH} characters.`,
+  });
+  const confirmation = await askPassword({
+    message: "Confirm password:",
+    validate: (v) => (v ? undefined : "Required."),
+  });
+
+  if (password !== confirmation) {
+    note("Passwords do not match. Nothing was changed.", "Aborted");
+    return;
+  }
+
+  const { privateKey, publicKey } = await deriveDocAccessKeys(password, new NodeCryptoService());
+
+  let configPath: string;
+  try {
+    configPath = await new GitPageDocsConfigRepository(ctx.cwd).patchDocsAccess(publicKey);
+  } catch (error) {
+    note(error instanceof Error ? error.message : String(error), "Could not save");
+    return;
+  }
+
+  note(
+    `Public key saved to ${configPath}\nThe documentation is now password-protected.`,
+    "Saved",
+  );
+  // eslint-disable-next-line no-console
+  console.log(
+    "\n  PRIVATE KEY (copy & keep it safe — it also unlocks the docs):\n\n" +
+      `    ${privateKey}\n\n` +
+      "  Readers can unlock with the password OR this private key.\n" +
+      "  To remove protection, set site.docsAccess.enabled to false in config.json.\n",
+  );
+  outro("Done.");
+}

package/presentation/commands/run-command.ts

@@ -21,6 +21,7 @@ import { runConfig } from "./config-info";
 import { runMcp } from "./mcp";
 import { runDocs } from "./docs";
 import { runPagesActions, runPagesDeploy } from "./pages";
+import { runPassword } from "./password";
 
 const REGISTRY: Record<string, CommandHandler> = {
   version: runVersion,
@@ -34,6 +35,7 @@ const REGISTRY: Record<string, CommandHandler> = {
   config: runConfig,
   mcp: runMcp,
   docs: runDocs,
+  password: runPassword,
 };
 
 /** Returns true if a new command handled the invocation (skip legacy flow). */

package/presentation/index.ts

@@ -78,11 +78,19 @@ async function main(): Promise<void> {
     },
     runAi: async (context) => {
       console.log("[gitpagedocs] Iniciando Módulo de IA na CLI...");
+      const safePrebuiltDir =
+        typeof context.prebuiltDir === "string"
+          ? context.prebuiltDir
+          : path.join(String(context.pkgRoot ?? process.cwd()), "prebuilt");
       // @ts-ignore
       const { runAiCliCommand } = await import("../ai/application/run-ai-cli-command.ts");
       const result = await runAiCliCommand({
         cwd: process.cwd(),
         onInfo: (message: string) => console.log(message),
+        // Scaffold the base gitpagedocs/ structure before AI pages are wired in.
+        onScaffold: async () => {
+          await executeConfigOnly({ ...context, prebuiltDir: safePrebuiltDir }, configOnlyRuntime);
+        },
       });
 
       if (result.summary.scannedFilesCount === 0) {
@@ -90,13 +98,13 @@ async function main(): Promise<void> {
         return;
       }
 
-      if (result.runConfigScaffold) {
-        console.log("\n[gitpagedocs] Scaffolding GitPageDocs ecosystem automatically...");
-        const safePrebuiltDir = typeof context.prebuiltDir === "string" ? context.prebuiltDir : path.join(String(context.pkgRoot ?? process.cwd()), "prebuilt");
-        await executeConfigOnly({ ...context, prebuiltDir: safePrebuiltDir }, configOnlyRuntime);
-      }
-
-      console.log(`\n🎉 Processo completo! Arquivos gerados: ${result.summary.outputs.join(", ")}`);
+      const pages = result.summary.pages ?? [];
+      console.log(
+        `\n🎉 Processo completo! Páginas no padrão gitpagedocs: ${pages.join(", ") || "(nenhuma)"}`,
+      );
+      console.log(
+        `[gitpagedocs:ai] ${result.summary.outputs.length} arquivos markdown gerados e conectados ao config.json da versão mais recente.`,
+      );
     },
   });
   printCredits();

package/presentation/options/resolver.ts

@@ -1,7 +1,16 @@
 import type { CliOptions } from "../../domain/models/cli-options";
 import { parseCliOptions } from "./parser";
-import { shouldRunInteractive, promptConfigOnlyOptions, promptHomeOptions } from "../ui/prompts";
+import {
+  shouldRunInteractive,
+  promptConfigOnlyOptions,
+  promptHomeOptions,
+  promptDeployOptions,
+  ensureGitRepoInteractive,
+  interactivePromptsAvailable,
+} from "../ui/prompts";
 import { DEFAULTS } from "./schema";
+// @ts-expect-error .mjs runtime module is type-less in this package.
+import { detectRepoFromGit } from "../../runtime/git-ops.mjs";
 
 export async function resolveOptions(argv: string[], env: NodeJS.ProcessEnv): Promise<CliOptions> {
   const parsed = parseCliOptions(argv, env);
@@ -11,6 +20,20 @@ export async function resolveOptions(argv: string[], env: NodeJS.ProcessEnv): Pr
     parsed.basePath = parsed.basePath ?? parsed.docsPath ?? DEFAULTS.home.basePath;
   }
 
+  // `deploy` / `--push` need owner + repo AND a git repo. If anything is
+  // missing, prompt interactively (owner/repo pre-filled from the git origin
+  // remote; offer to `git init`) instead of throwing. In CI/non-TTY we fall
+  // through so the explicit guards in the push flow still fire clearly.
+  if (parsed.shouldPush && interactivePromptsAvailable()) {
+    let resolved = parsed;
+    if (!parsed.githubOwner || !parsed.githubRepo) {
+      const detected = detectRepoFromGit(process.cwd()) as { owner: string; repo: string } | null;
+      resolved = await promptDeployOptions(parsed, detected);
+    }
+    await ensureGitRepoInteractive(process.cwd());
+    return resolved;
+  }
+
   const runHomeInteractive = parsed.isInteractive || (shouldRunInteractive(argv) && parsed.mode === "home");
   if (runHomeInteractive && parsed.mode === "home") {
     return promptHomeOptions(parsed);

package/presentation/ui/clack.ts

@@ -5,6 +5,7 @@
  */
 import {
   text,
+  password,
   confirm,
   select,
   multiselect,
@@ -40,6 +41,22 @@ export async function askText(options: AskTextOptions): Promise<string> {
   return exitIfCancelled(result);
 }
 
+export interface AskPasswordOptions {
+  message: string;
+  validate?: (value: string) => string | undefined;
+}
+
+/** Masked password prompt (input hidden as the user types). */
+export async function askPassword(options: AskPasswordOptions): Promise<string> {
+  const result = await password({
+    message: options.message,
+    validate: options.validate
+      ? (value) => options.validate?.(value ?? "")
+      : undefined,
+  });
+  return exitIfCancelled(result);
+}
+
 export async function askConfirm(message: string, initialValue = false): Promise<boolean> {
   const result = await confirm({ message, initialValue });
   return exitIfCancelled(result);

package/presentation/ui/prompts.ts

@@ -1,6 +1,9 @@
+import { existsSync } from "node:fs";
+import path from "node:path";
+import { execSync } from "node:child_process";
 import type { CliOptions } from "../../domain/models/cli-options";
 import { DEFAULTS } from "../options/schema";
-import { askText, askConfirm } from "./clack";
+import { askText, askConfirm, note } from "./clack";
 
 function isCiOrNonTty(): boolean {
   if (process.env.CI === "true") return true;
@@ -9,6 +12,11 @@ function isCiOrNonTty(): boolean {
   return false;
 }
 
+/** True when clack prompts can run (interactive TTY, not CI). */
+export function interactivePromptsAvailable(): boolean {
+  return !isCiOrNonTty();
+}
+
 export function shouldRunInteractive(argv: string[]): boolean {
   if (isCiOrNonTty()) return false;
   const args = argv.slice(2);
@@ -41,6 +49,72 @@ export async function promptHomeOptions(parsed: CliOptions): Promise<CliOptions>
   };
 }
 
+/**
+ * Deploy/--push needs a GitHub owner + repo. When they are missing, prompt for
+ * them (pre-filled from the git `origin` remote when available) instead of
+ * crashing with "`--push` requires owner and repo".
+ */
+export async function askOwnerRepo(
+  detected: { owner: string; repo: string } | null,
+  defaults?: { owner?: string; repo?: string },
+): Promise<{ owner: string; repo: string }> {
+  const owner = await askText({
+    message: "GitHub owner (user or organization):",
+    defaultValue: defaults?.owner || detected?.owner || "",
+    validate: (v) => (v && v.trim() ? undefined : "Owner is required."),
+  });
+  const repo = await askText({
+    message: "GitHub repository name:",
+    defaultValue: defaults?.repo || detected?.repo || "",
+    validate: (v) => (v && v.trim() ? undefined : "Repository is required."),
+  });
+  return { owner: owner.trim(), repo: repo.trim() };
+}
+
+export async function promptDeployOptions(
+  parsed: CliOptions,
+  detected: { owner: string; repo: string } | null,
+): Promise<CliOptions> {
+  note(
+    "Deploy publishes gitpagedocs to GitHub Pages and needs the target\nrepository (owner/repo). Press Enter to accept a detected value.",
+    "GitHub Pages deploy",
+  );
+  const { owner, repo } = await askOwnerRepo(detected, {
+    owner: parsed.githubOwner,
+    repo: parsed.githubRepo,
+  });
+
+  return {
+    ...parsed,
+    githubOwner: owner,
+    githubRepo: repo,
+  };
+}
+
+/**
+ * Deploy/--push needs a git repository in the current folder. When there isn't
+ * one, offer to run `git init` instead of crashing with "not a git repository".
+ * In CI/non-TTY this is a no-op so the downstream guard still reports clearly.
+ */
+export async function ensureGitRepoInteractive(root: string): Promise<void> {
+  if (existsSync(path.join(root, ".git"))) return;
+  if (!interactivePromptsAvailable()) return;
+  const init = await askConfirm(
+    "This folder is not a git repository yet. Initialize one here (git init)?",
+    true,
+  );
+  if (!init) {
+    note("Deploy needs a git repository. Run `git init`, then retry.", "Heads up");
+    return;
+  }
+  try {
+    execSync("git init", { cwd: root, stdio: "ignore" });
+    note("Initialized an empty git repository.", "git");
+  } catch {
+    note("Could not run `git init`. Initialize git manually, then retry.", "git");
+  }
+}
+
 export async function promptConfigOnlyOptions(parsed: CliOptions): Promise<CliOptions> {
   const useLocalLayoutConfig = await askConfirm(
     "Generate local layout templates?",