@gitpagedocs/cli 1.1.48 → 1.1.51

package/builders/root-config-builder.mjs

@@ -11,7 +11,7 @@ export function buildRootConfig(options = {}) {
   const useOfficialLayouts = !useLocalLayoutConfig;
   const githubOwner = options.githubOwner;
   const githubRepo = options.githubRepo;
-  const repositorySearchHome = githubOwner && githubRepo ? false : true;
+  const repositorySearchHome = false;
   const renderingUrl =
     githubOwner && githubRepo
       ? `https://${githubOwner}.github.io/${githubRepo}/`
@@ -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.48",
-  "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.48",
-    "@gitpagedocs/tools": "^1.1.48",
-    "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.51",
+  "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.51",
+    "@gitpagedocs/tools": "^1.1.51",
+    "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/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?",