@gitpagedocs/cli 0.0.1 → 0.0.3

package/README.md

@@ -24,12 +24,13 @@ npx @gitpagedocs/cli
 | `gitpagedocs --home` | Standalone distribution (`gitpagedocshome/`: static site + .env + Dockerfile) |
 | `gitpagedocs -i` / `--interactive` | Interactive prompts |
 | `gitpagedocs ai` | Interactive AI documentation generator — writes pages in the gitpagedocs pattern (see below) |
+| `gitpagedocs chat [question]` | Streaming AI chat in the terminal — REPL on a TTY, one-shot with a question or piped stdin; `--provider`, `--model`, `--system` (see below) |
 | `gitpagedocs provider [id]` · `models [provider]` | List AI providers / catalog models |
 | `gitpagedocs document[:repo\|:file\|:folder]` | Generate documentation with AI in the gitpagedocs pattern |
 | `gitpagedocs password` | Set a documentation access password (writes the public key to `config.json`, prints the private key) |
 | `gitpagedocs deploy` / `pages [actions\|deploy]` | Configure GitHub Pages via Actions + push |
 | `gitpagedocs docs` | Refresh managed regions of README/CONTRIBUTING/SECURITY |
-| `gitpagedocs config clear` | Delete the stored `.gitpagedocsconfig` (wipes saved AI credentials) |
+| `gitpagedocs config clear` | Delete the stored `.gitpagedocsconfig` **and** the encrypted key vault `.gitpagedocsvault` (wipes saved AI credentials) |
 | `gitpagedocs doctor` · `version` · `update` | Diagnostics / version / registry update check |
 | `gitpagedocs mcp start` | Start the MCP server over stdio |
 
@@ -43,12 +44,17 @@ The AI-CLI implementation lives in `cli/ai/` (relocated from the frontend so the
 cli/
 |-- index.mjs                          # Node entry (bootstraps TS presentation via tsx)
 |-- package.json                       # the published `gitpagedocs` package
-|-- ai/                                # AI documentation CLI (provider/model/paths → markdown)
+|-- ai/                                # AI CLI: docs generator + terminal chat
+|   |-- application/                   # run-ai-cli-command, resolve-chat-credentials, ai-credentials (seal/unseal), vault-password
+|   |-- infrastructure/                # ai-config-file (.gitpagedocsconfig), ai-key-vault (.gitpagedocsvault), file-system-adapter, version-docs-writer
+|   |-- core/                          # chat-session, config models + parser
+|   `-- presentation/                  # @clack prompts (ai-prompts, vault-prompts)
 |-- contracts/                         # Stable contracts for external tooling
 |   `-- doc-versions.mjs
 |
 |-- presentation/                      # Interface/composition root
 |   |-- index.ts
+|   |-- commands/                      # chat, config-clear, config-info, docs, pages, password, mcp, diagnostics, ai-info
 |   |-- options/
 |   `-- ui/
 |
@@ -139,7 +145,8 @@ npx @gitpagedocs/cli ai
 - asks API key or Ollama URL
 - asks paths to scan (supports one or many paths, including other repositories)
 - generates documentation in `pt`, `en`, `es` **in the gitpagedocs pattern**
-- optionally persists config in `.gitpagedocsconfig`
+- optionally persists config in `.gitpagedocsconfig`, sealing the API key in the encrypted
+  vault `.gitpagedocsvault` (vault password created on first use, asked on every run)
 
 ### gitpagedocs pattern output
 
@@ -161,8 +168,8 @@ permissions on POSIX systems:
 - macOS: `~/Library/Application Support/gitpagedocs/.gitpagedocsconfig`
 - Linux: `$XDG_CONFIG_HOME/gitpagedocs/.gitpagedocsconfig` (or `~/.config/gitpagedocs/.gitpagedocsconfig`)
 
-Set `GITPAGEDOCS_CONFIG_DIR` to override the directory; delete the stored file
-and its credentials with `gitpagedocs config clear`; a legacy
+Set `GITPAGEDOCS_CONFIG_DIR` to override the directory; delete the stored file,
+the vault and their credentials with `gitpagedocs config clear`; a legacy
 `.gitpagedocsconfig` in the repository root is migrated automatically on the next
 run. You can create/edit this file manually and then run `npx @gitpagedocs/cli ai`:
 
@@ -172,7 +179,7 @@ run. You can create/edit this file manually and then run `npx @gitpagedocs/cli a
 	"ai": {
 		"provider": "openai",
 		"model": "gpt-4o-mini",
-		"apiKey": "<YOUR_API_KEY>",
+		"apiKeyEncrypted": true,
 		"paths": ["src", "cli", "../another-repo/src"],
 		"languages": ["pt", "en", "es"],
 		"outputDir": "gitpagedocs/docs",
@@ -182,7 +189,38 @@ run. You can create/edit this file manually and then run `npx @gitpagedocs/cli a
 }
 ```
 
-For Ollama, use `baseUrl` instead of `apiKey`.
+**The API key is not in this file.** Saving a configuration seals the key into the
+encrypted vault `.gitpagedocsvault` in the same directory (`cli/ai/infrastructure/ai-key-vault.ts`
+over `EncryptedCredentialVault` + `FileVaultStorage` from `@gitpagedocs/tools`: AES-256-GCM, key
+derived from your password with PBKDF2-HMAC-SHA-256, 210k iterations) and the config only keeps
+`"apiKeyEncrypted": true`.
+
+- The **vault password is created on first use** (typed twice, at least 4 characters) and
+  **asked on every run** of `gitpagedocs ai` / `gitpagedocs chat` that uses the stored key
+  (3 attempts, then the run aborts with `Vault password rejected`).
+- `GITPAGEDOCS_VAULT_PASSWORD` supplies the password without a prompt (CI, pipes, no TTY);
+  on a first run it initializes the vault, otherwise it must match the existing one.
+- A legacy plaintext `"apiKey"` still present in an old file is sealed into the vault and
+  removed from the file the next time the config is read.
+- If you hand-write the file, leave the key out: enter it in the `gitpagedocs ai` prompt (it is
+  sealed on save). `gitpagedocs chat` can also read the provider's environment variable
+  (`gitpagedocs provider <id>` lists it) when no key is stored.
+
+For Ollama, use `baseUrl` instead of an API key (no vault involved).
+
+### `gitpagedocs chat`
+
+```bash
+gitpagedocs chat                                  # REPL on a TTY: /clear · /help · /exit (or Ctrl+C twice)
+gitpagedocs chat "what does cli/ai do?"           # one-shot answer, then exit
+git diff | gitpagedocs chat "review this diff"    # piped stdin is appended to the question
+gitpagedocs chat --provider gemini --model gemini-2.5-pro --system "Answer in Portuguese" "..."
+```
+
+Credentials are resolved in this order: `--provider`/`--model` flags, the stored
+`.gitpagedocsconfig` (its key is decrypted after the vault password prompt, or from
+`GITPAGEDOCS_VAULT_PASSWORD`), then the provider's environment variable. Output streams to
+stdout while status lines go to stderr, so the answer can be piped.
 
 ### Interactive fallback
 

package/ai/application/ai-credentials.ts

@@ -0,0 +1,100 @@
+import { SecurityError } from "@gitpagedocs/tools";
+import type { AiCliConfig } from "../core/models/ai-cli-config";
+import type { AiConfigFileRepository } from "../infrastructure/ai-config-file";
+import type { AiKeyVault } from "../infrastructure/ai-key-vault";
+import { resolveVaultPassword, type VaultPasswordPrompt } from "./vault-password";
+
+export type KeyVault = Pick<AiKeyVault, "isInitialized" | "initialize" | "unlock" | "setKey" | "getKey" | "getVaultPath">;
+
+/** A config carries a key to protect (plaintext to migrate) or one sealed in the vault. */
+export function needsVaultPassword(config: AiCliConfig): boolean {
+  return config.ai.apiKeyEncrypted === true || Boolean(config.ai.apiKey?.trim());
+}
+
+export interface SealApiKeyInput {
+  readonly config: AiCliConfig;
+  readonly vault: Pick<KeyVault, "setKey">;
+  readonly password: string;
+}
+
+/**
+ * Moves the plaintext API key into the vault and returns the config to persist:
+ * no `apiKey`, `apiKeyEncrypted: true`. A config without a key is returned as is.
+ */
+export async function sealApiKey({ config, vault, password }: SealApiKeyInput): Promise<AiCliConfig> {
+  const apiKey = config.ai.apiKey?.trim();
+  if (!apiKey) return config;
+  await vault.setKey(password, config.ai.provider, apiKey);
+  const ai = { ...config.ai };
+  delete ai.apiKey;
+  return { ...config, ai: { ...ai, apiKeyEncrypted: true } };
+}
+
+export interface UnsealApiKeyInput {
+  readonly config: AiCliConfig;
+  readonly vault: Pick<KeyVault, "getKey">;
+  readonly password: string;
+}
+
+/** The stored config with its key decrypted into memory (never written back). */
+export async function unsealApiKey({ config, vault, password }: UnsealApiKeyInput): Promise<AiCliConfig> {
+  if (!config.ai.apiKeyEncrypted) return config;
+  const apiKey = await vault.getKey(password, config.ai.provider);
+  return apiKey ? { ...config, ai: { ...config.ai, apiKey } } : config;
+}
+
+export interface UnlockStoredConfigInput {
+  readonly config: AiCliConfig;
+  readonly vault: KeyVault;
+  readonly configRepo: Pick<AiConfigFileRepository, "write">;
+  readonly env?: Readonly<Record<string, string | undefined>>;
+  readonly prompt?: VaultPasswordPrompt;
+  readonly onInfo?: (message: string) => void;
+}
+
+/**
+ * Turns the stored config into one a run can use. An encrypted key is decrypted
+ * into memory after the password check; a legacy plaintext key is sealed into
+ * the vault and stripped from `.gitpagedocsconfig` on the spot, so the file
+ * never keeps a key in clear again.
+ */
+export async function unlockStoredConfig(input: UnlockStoredConfigInput): Promise<AiCliConfig> {
+  const { config } = input;
+  if (!needsVaultPassword(config)) return config;
+  const password = await resolveVaultPassword({ vault: input.vault, env: input.env, prompt: input.prompt });
+
+  if (config.ai.apiKeyEncrypted && !config.ai.apiKey?.trim()) {
+    const unsealed = await unsealApiKey({ config, vault: input.vault, password });
+    if (!unsealed.ai.apiKey) {
+      throw new SecurityError(
+        `No API key is stored for "${config.ai.provider}". Run "gitpagedocs ai" and enter the key again, or "gitpagedocs config clear".`,
+      );
+    }
+    return unsealed;
+  }
+
+  const sealed = await sealApiKey({ config, vault: input.vault, password });
+  await input.configRepo.write(sealed);
+  input.onInfo?.(
+    `[gitpagedocs:ai] API key moved from .gitpagedocsconfig into the encrypted vault (${input.vault.getVaultPath()}).`,
+  );
+  return config;
+}
+
+export type StoredKeyUnlocker = (stored: AiCliConfig) => Promise<string | undefined>;
+
+/**
+ * Callback for credential resolvers: the decrypted key of the stored config, or
+ * undefined (with the reason reported) when the vault cannot be opened.
+ */
+export function createStoredKeyUnlocker(deps: Omit<UnlockStoredConfigInput, "config">): StoredKeyUnlocker {
+  return async (stored) => {
+    try {
+      const unlocked = await unlockStoredConfig({ ...deps, config: stored });
+      return unlocked.ai.apiKey;
+    } catch (error) {
+      deps.onInfo?.(error instanceof Error ? error.message : String(error));
+      return undefined;
+    }
+  };
+}

package/ai/application/resolve-chat-credentials.ts

@@ -3,6 +3,7 @@ import type { AiProviderId } from "@gitpagedocs/tools/ports";
 import { PROVIDER_CATALOG } from "@gitpagedocs/tools";
 import { AiConfigFileRepository } from "../infrastructure/ai-config-file";
 import type { AiCliConfig } from "../core/models/ai-cli-config";
+import { needsVaultPassword, type StoredKeyUnlocker } from "./ai-credentials";
 
 export interface ResolvedChatCredentials {
   readonly providerId: AiProviderId;
@@ -21,6 +22,12 @@ export interface ResolveChatCredentialsInput {
   readonly configRepo?: Pick<AiConfigFileRepository, "read">;
   /** Injectable for tests; defaults to process.env. */
   readonly env?: Readonly<Record<string, string | undefined>>;
+  /**
+   * Decrypts the key of a stored config (asking the vault password) and
+   * migrates a legacy plaintext key into the vault. Without it a plaintext
+   * key is used as is and an encrypted one is unreachable.
+   */
+  readonly unlockStoredKey?: StoredKeyUnlocker;
 }
 
 /**
@@ -40,7 +47,11 @@ export async function resolveChatCredentials(
   const spec = PROVIDER_CATALOG[providerId];
   const model = input.modelOverride?.trim() || stored?.ai.model?.trim() || spec.defaultModel;
   const baseUrl = stored?.ai.baseUrl?.trim() || undefined;
-  const apiKey = stored?.ai.apiKey?.trim() || resolveApiKeyFromEnv(providerId, env);
+  const storedKey =
+    stored && input.unlockStoredKey && needsVaultPassword(stored)
+      ? await input.unlockStoredKey(stored)
+      : stored?.ai.apiKey?.trim();
+  const apiKey = storedKey?.trim() || resolveApiKeyFromEnv(providerId, env);
 
   const keyless = spec.auth === "none";
   if (!keyless && !apiKey) return null;

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

@@ -1,11 +1,15 @@
 import { AiCommandService } from "./ai-command";
 import { createAiProvider } from "./ai-provider-factory";
+import { sealApiKey, unlockStoredConfig } from "./ai-credentials";
+import { resolveVaultPassword, type VaultPasswordPrompt } from "./vault-password";
 import { FileSystemAdapter, type FilePayload } from "../infrastructure/file-system-adapter";
 import {
   AiConfigFileRepository,
 } from "../infrastructure/ai-config-file";
-import type { AiCliRunPlan, AiCliRunSummary } from "../core/models/ai-cli-config";
+import { AiKeyVault } from "../infrastructure/ai-key-vault";
+import type { AiCliConfig, AiCliRunPlan, AiCliRunSummary } from "../core/models/ai-cli-config";
 import { promptMissingDirectories, runAiInteractivePrompt } from "../presentation/ai-prompts";
+import { clackVaultPasswordPrompt } from "../presentation/vault-prompts";
 import { GITPAGEDOCS_DOC_SYSTEM_PROMPT } from "../config";
 import { parseAiPages, type AiDocPage } from "./docs-pattern";
 import { writeVersionDocs } from "../infrastructure/version-docs-writer";
@@ -130,26 +134,62 @@ export async function executeAiRunPlan(
   };
 }
 
-export async function runAiCliCommand(options: {
+export interface RunAiCliCommandOptions {
   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 }> {
+  /** Injectable for tests; defaults to the per-user vault file. */
+  vault?: AiKeyVault;
+  /** Injectable for tests; defaults to the terminal prompts. */
+  passwordPrompt?: VaultPasswordPrompt;
+  /** Injectable for tests; defaults to process.env. */
+  env?: Readonly<Record<string, string | undefined>>;
+}
+
+interface SaveConfigDeps {
+  configRepo: AiConfigFileRepository;
+  vault: AiKeyVault;
+  prompt: VaultPasswordPrompt;
+  env?: Readonly<Record<string, string | undefined>>;
+  logInfo: (message: string) => void;
+}
+
+/** Persists the plan's config; an API key is sealed into the vault first, never written in clear. */
+async function saveConfig(config: AiCliConfig, deps: SaveConfigDeps): Promise<void> {
+  if (!config.ai.apiKey?.trim()) {
+    await deps.configRepo.write(config);
+    deps.logInfo(`[gitpagedocs:ai] Configuration saved to ${deps.configRepo.getConfigPath()}`);
+    return;
+  }
+  const password = await resolveVaultPassword({ vault: deps.vault, env: deps.env, prompt: deps.prompt });
+  await deps.configRepo.write(await sealApiKey({ config, vault: deps.vault, password }));
+  deps.logInfo(
+    `[gitpagedocs:ai] Configuration saved to ${deps.configRepo.getConfigPath()} (API key encrypted in ${deps.vault.getVaultPath()})`,
+  );
+}
+
+export async function runAiCliCommand(options: RunAiCliCommandOptions): Promise<{ summary: AiCliRunSummary; runConfigScaffold: boolean }> {
   const logInfo = options.onInfo ?? (() => undefined);
   const configRepo = new AiConfigFileRepository({
     cwd: options.cwd,
     onMigrate: (fromPath, toPath) =>
       logInfo(`[gitpagedocs:ai] Moved configuration from ${fromPath} to ${toPath} (secure user config directory).`),
   });
+  const vault = options.vault ?? new AiKeyVault();
+  const prompt = options.passwordPrompt ?? clackVaultPasswordPrompt;
 
   const existingConfig = await configRepo.read();
   const plan = await runAiInteractivePrompt(existingConfig);
+  let runConfig = plan.config;
 
   if (plan.saveConfig) {
-    await configRepo.write(plan.config);
-    logInfo(`[gitpagedocs:ai] Configuration saved to ${configRepo.getConfigPath()}`);
+    await saveConfig(runConfig, { configRepo, vault, prompt, env: options.env, logInfo });
+  } else if (existingConfig && runConfig === existingConfig) {
+    // Reusing the stored config: decrypt its key for this run (the password is
+    // asked every time), or seal a legacy plaintext key into the vault.
+    runConfig = await unlockStoredConfig({ config: runConfig, vault, configRepo, env: options.env, prompt, onInfo: logInfo });
   }
 
   // Build the base gitpagedocs structure BEFORE generation so the version
@@ -159,7 +199,7 @@ export async function runAiCliCommand(options: {
     await options.onScaffold();
   }
 
-  const summary = await executeAiRunPlan(plan, options.cwd);
+  const summary = await executeAiRunPlan({ ...plan, config: runConfig }, options.cwd);
   return {
     summary,
     runConfigScaffold: plan.runConfigScaffold,

package/ai/application/vault-password.ts

@@ -0,0 +1,66 @@
+import { SecurityError } from "@gitpagedocs/tools";
+import type { AiKeyVault } from "../infrastructure/ai-key-vault";
+
+/** Non-interactive runs (CI, pipes) supply the vault password through this variable. */
+export const VAULT_PASSWORD_ENV = "GITPAGEDOCS_VAULT_PASSWORD";
+
+const DEFAULT_MAX_ATTEMPTS = 3;
+
+/** How the host asks for the password (terminal prompt, test double, ...). */
+export interface VaultPasswordPrompt {
+  /** First run: let the user choose (and confirm) the password. */
+  create(): Promise<string>;
+  /** Later runs: ask for the existing password; `attempt` starts at 1. */
+  unlock(attempt: number): Promise<string>;
+}
+
+export type PasswordVault = Pick<AiKeyVault, "isInitialized" | "initialize" | "unlock">;
+
+export interface ResolveVaultPasswordInput {
+  readonly vault: PasswordVault;
+  /** Defaults to process.env. */
+  readonly env?: Readonly<Record<string, string | undefined>>;
+  /** Absent when no terminal is available. */
+  readonly prompt?: VaultPasswordPrompt;
+  readonly maxAttempts?: number;
+}
+
+/**
+ * The verified vault password for this run. Order: the environment variable
+ * (initializing the vault on first use), otherwise the prompt — create on first
+ * run, unlock afterwards with up to three attempts. The password is asked on
+ * every command run; it is never persisted.
+ */
+export async function resolveVaultPassword(input: ResolveVaultPasswordInput): Promise<string> {
+  const env = input.env ?? process.env;
+  const initialized = await input.vault.isInitialized();
+
+  const fromEnv = env[VAULT_PASSWORD_ENV]?.trim();
+  if (fromEnv) {
+    if (!initialized) {
+      await input.vault.initialize(fromEnv);
+      return fromEnv;
+    }
+    if (await input.vault.unlock(fromEnv)) return fromEnv;
+    throw new SecurityError(`${VAULT_PASSWORD_ENV} does not match the vault password.`);
+  }
+
+  if (!input.prompt) {
+    throw new SecurityError(
+      `A password is required to read the encrypted API key. Run the command in a terminal or set ${VAULT_PASSWORD_ENV}.`,
+    );
+  }
+
+  if (!initialized) {
+    const password = await input.prompt.create();
+    await input.vault.initialize(password);
+    return password;
+  }
+
+  const maxAttempts = input.maxAttempts ?? DEFAULT_MAX_ATTEMPTS;
+  for (let attempt = 1; attempt <= maxAttempts; attempt += 1) {
+    const password = await input.prompt.unlock(attempt);
+    if (await input.vault.unlock(password)) return password;
+  }
+  throw new SecurityError(`Vault password rejected after ${maxAttempts} attempts.`);
+}

package/ai/config.ts

@@ -11,8 +11,8 @@ export type AiProviderId = 'openai' | 'claude' | 'gemini' | 'ollama';
 
 export const AI_MODEL_DEFAULTS: Readonly<Record<AiProviderId, string>> = {
   openai: 'gpt-4o-mini',
-  claude: 'claude-3-5-sonnet-20240620',
-  gemini: 'gemini-1.5-flash',
+  claude: 'claude-sonnet-4-6',
+  gemini: 'gemini-2.5-flash',
   ollama: 'llama3',
 };
 

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

@@ -7,7 +7,10 @@ export interface AiCliConfig {
   ai: {
     provider: AiProviderId;
     model: string;
+    /** Only in memory during a run: the file never stores the key in clear. */
     apiKey?: string;
+    /** The key lives sealed in the `.gitpagedocsvault` next to this file. */
+    apiKeyEncrypted?: boolean;
     baseUrl?: string;
     paths: string[];
     languages: Array<"pt" | "en" | "es">;

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

@@ -57,6 +57,7 @@ export function parseAiCliConfig(raw: unknown): AiCliConfig | null {
 
   const model = asOptionalString(ai.model)?.trim() || AI_MODEL_DEFAULTS[provider];
   const apiKey = asOptionalString(ai.apiKey);
+  const apiKeyEncrypted = ai.apiKeyEncrypted === true;
   const baseUrl = asOptionalString(ai.baseUrl);
 
   return {
@@ -65,6 +66,7 @@ export function parseAiCliConfig(raw: unknown): AiCliConfig | null {
       provider,
       model,
       ...(apiKey !== undefined ? { apiKey } : {}),
+      ...(apiKeyEncrypted ? { apiKeyEncrypted: true } : {}),
       ...(baseUrl !== undefined ? { baseUrl } : {}),
       paths: asPaths(ai.paths),
       languages: asLanguages(ai.languages),

package/ai/infrastructure/ai-key-vault.ts

@@ -0,0 +1,65 @@
+import path from "node:path";
+import { existsSync } from "node:fs";
+import {
+  EncryptedCredentialVault,
+  FileVaultStorage,
+  NodeCryptoService,
+  resolveUserConfigDir,
+} from "@gitpagedocs/tools";
+
+export const AI_KEY_VAULT_FILENAME = ".gitpagedocsvault";
+
+export interface AiKeyVaultOptions {
+  /** Directory of the vault file; defaults to the per-user OS config directory. */
+  configDir?: string;
+}
+
+/**
+ * Password-encrypted store for the CLI's AI API keys, kept next to
+ * `.gitpagedocsconfig` in the per-user config directory. Every key is sealed
+ * with AES-256-GCM under a key derived from the password by PBKDF2-HMAC-SHA-256
+ * (210,000 iterations, random salt); the file never holds a key in clear and
+ * only the password decrypts it.
+ */
+export class AiKeyVault {
+  private readonly filePath: string;
+  private readonly vault: EncryptedCredentialVault;
+
+  constructor(options: AiKeyVaultOptions = {}) {
+    this.filePath = path.join(options.configDir ?? resolveUserConfigDir(), AI_KEY_VAULT_FILENAME);
+    this.vault = new EncryptedCredentialVault(new FileVaultStorage(this.filePath), new NodeCryptoService());
+  }
+
+  getVaultPath(): string {
+    return this.filePath;
+  }
+
+  /** True once a password has been set (the vault file exists). */
+  isInitialized(): Promise<boolean> {
+    return this.vault.isInitialized();
+  }
+
+  initialize(password: string): Promise<void> {
+    return this.vault.initialize(password);
+  }
+
+  /** Whether `password` opens the vault; never throws for a wrong password. */
+  unlock(password: string): Promise<boolean> {
+    return this.vault.unlock(password);
+  }
+
+  setKey(password: string, providerId: string, apiKey: string): Promise<void> {
+    return this.vault.setCredential(password, providerId, apiKey);
+  }
+
+  getKey(password: string, providerId: string): Promise<string | undefined> {
+    return this.vault.getCredential(password, providerId);
+  }
+
+  /** Deletes the vault file with every sealed key. Returns whether a file existed. */
+  async clear(): Promise<boolean> {
+    const existed = existsSync(this.filePath);
+    await this.vault.reset();
+    return existed;
+  }
+}

package/ai/presentation/vault-prompts.ts

@@ -0,0 +1,35 @@
+import { SecurityError } from "@gitpagedocs/tools";
+import { askPassword, note } from "../../presentation/ui/clack";
+import { VAULT_PASSWORD_ENV, type VaultPasswordPrompt } from "../application/vault-password";
+
+const MIN_PASSWORD_LENGTH = 4;
+
+function requireTerminal(): void {
+  if (!process.stdin.isTTY) {
+    throw new SecurityError(
+      `The encrypted API key needs its password. Run the command in a terminal or set ${VAULT_PASSWORD_ENV}.`,
+    );
+  }
+}
+
+/** Terminal prompts for the vault password: create + confirm on first run, unlock afterwards. */
+export const clackVaultPasswordPrompt: VaultPasswordPrompt = {
+  async create() {
+    requireTerminal();
+    for (;;) {
+      const password = await askPassword({
+        message: "Create a local password to encrypt your API key (asked on every run):",
+        validate: (value) => (value.trim().length >= MIN_PASSWORD_LENGTH ? undefined : `Use at least ${MIN_PASSWORD_LENGTH} characters.`),
+      });
+      const confirmation = await askPassword({ message: "Confirm the password:" });
+      if (password === confirmation) return password;
+      note("The passwords do not match. Try again.");
+    }
+  },
+  async unlock(attempt) {
+    requireTerminal();
+    return askPassword({
+      message: attempt > 1 ? `Local password (attempt ${attempt} of 3):` : "Local password to decrypt the API key:",
+    });
+  },
+};

package/content/docs-en.mjs

@@ -187,9 +187,11 @@ The version config can render a **Source code** container through \`routes-sourc
 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\`.
+- **Model selection** — pick from each provider's catalog (\`gitpagedocs models <provider>\`); a stored model id the provider has retired is replaced by the provider default automatically.
+- **Encrypted at rest** — your API key is sealed with AES-256-GCM behind a **local password** and is never stored in plaintext or logged. A legacy plaintext key is migrated and wiped on first unlock.
+- **Inactivity auto-lock** — the chat drawer locks itself after \`site.AiChatAutoLockSeconds\` idle seconds (default 30, \`0\` disables): a centered countdown modal in your language lets you cancel or lock now, and unlocking asks for the password again.
+- **Resilient providers** — transient provider errors are retried (3 attempts) and a final failure is a plain message ending with "Try again!".
+- **AI documentation generation** — \`gitpagedocs ai\` scans chosen paths and writes multilingual markdown (pt/en/es); reusable via \`.gitpagedocsconfig\`, whose API key lives sealed in the encrypted \`.gitpagedocsvault\` (the vault password is asked on every run). \`gitpagedocs chat\` brings the same assistant to the terminal.
 
 ## MCP server
 

package/content/docs-es.mjs

@@ -165,6 +165,21 @@ El config de version puede renderizar un contenedor **Codigo fuente** via \`rout
 
 - \`GITPAGEDOCS_REPOSITORY_SEARCH\` – busqueda de repositorio (local)
 - \`GITHUB_ACTIONS\` – modo build GitHub Pages
+
+## Asistente de IA
+
+Los docs traen un asistente de IA en dos superficies: un **panel de chat** dentro de los docs (boton de chat de IA en la barra lateral, activado por \`site.AiChatEnabled\`) y una pagina **consola \`/ai\`** dedicada.
+
+- **14 proveedores** en un unico core compartido: OpenAI, Anthropic, Gemini, OpenRouter, Ollama, Azure OpenAI, Mistral, DeepSeek, Cohere, Groq, xAI, Together, Fireworks, Perplexity.
+- **Eleccion de modelo** — desde el catalogo de cada proveedor (\`gitpagedocs models <proveedor>\`); un id de modelo guardado que el proveedor retiro se reemplaza por el predeterminado del proveedor automaticamente.
+- **Cifrado en reposo** — tu clave de API se sella con AES-256-GCM detras de una **contrasena local** y nunca queda en texto plano ni en logs. Una clave heredada en texto plano se migra y se borra en el primer desbloqueo.
+- **Bloqueo por inactividad** — el panel de chat se bloquea solo tras \`site.AiChatAutoLockSeconds\` segundos sin uso (por defecto 30, \`0\` lo desactiva): un modal centrado con cuenta regresiva, en tu idioma, permite cancelar o bloquear ahora, y desbloquear pide la contrasena de nuevo.
+- **Proveedores resilientes** — los errores transitorios del proveedor se reintentan (3 intentos) y un fallo final es un mensaje simple que termina en "¡Inténtalo de nuevo!".
+- **Generacion de documentacion con IA** — \`gitpagedocs ai\` recorre las rutas elegidas y escribe markdown multilingue (pt/en/es); reutilizable via \`.gitpagedocsconfig\`, cuya clave de API queda sellada en la boveda cifrada \`.gitpagedocsvault\` (la contrasena de la boveda se pide en cada ejecucion). \`gitpagedocs chat\` lleva el mismo asistente a la terminal.
+
+## Servidor MCP
+
+\`gitpagedocs mcp start\` levanta un servidor Model Context Protocol (stdio) que expone **20 tools** (sistema de archivos, IA, generacion/analisis de docs) y **7 resources** (\`project://structure|docs|config|repository|readme|ai/providers|ai/models\`) para editores y agentes de IA.
 `,
     configuration: `# Configuracion
 
@@ -311,7 +326,7 @@ El proyecto esta organizado por fronteras de feature y responsabilidades de runt
 
 ## Seguridad: credenciales de IA cifradas
 
-La consola \`/ai\` y el panel de chat exigen una contrasena local que deriva (PBKDF2) una clave AES-256-GCM; las claves quedan cifradas en \`localStorage\` y solo se descifran durante la sesion (\`@gitpagedocs/tools/security\`).
+La consola \`/ai\` y el panel de chat exigen una contrasena local que deriva (PBKDF2) una clave AES-256-GCM; las claves quedan cifradas en \`localStorage\` y solo se descifran durante la sesion (\`@gitpagedocs/tools/security\`). El panel se bloquea solo tras \`site.AiChatAutoLockSeconds\` segundos sin uso (por defecto 30; \`0\` lo desactiva): un modal centrado con cuenta regresiva, en el idioma seleccionado, permite cancelar o bloquear ahora, y volver exige la contrasena de nuevo. En la CLI, la clave de \`.gitpagedocsconfig\` queda sellada en la boveda cifrada \`.gitpagedocsvault\` y la contrasena de la boveda se pide en cada ejecucion.
 
 ## Flujo de datos
 

package/content/docs-pt.mjs

@@ -165,6 +165,21 @@ O config da versao pode renderizar um container **Codigo fonte** via \`routes-so
 
 - \`GITPAGEDOCS_REPOSITORY_SEARCH\` – busca de repositorio (local)
 - \`GITHUB_ACTIONS\` – modo build GitHub Pages
+
+## Assistente de IA
+
+Os docs trazem um assistente de IA em duas superficies: um **chat drawer** dentro dos docs (botao de chat de IA na barra lateral, ativado por \`site.AiChatEnabled\`) e uma pagina **console \`/ai\`** dedicada.
+
+- **14 provedores** em um unico core compartilhado: OpenAI, Anthropic, Gemini, OpenRouter, Ollama, Azure OpenAI, Mistral, DeepSeek, Cohere, Groq, xAI, Together, Fireworks, Perplexity.
+- **Escolha de modelo** — a partir do catalogo de cada provedor (\`gitpagedocs models <provedor>\`); um id de modelo salvo que o provedor aposentou e trocado pelo padrao do provedor automaticamente.
+- **Criptografia em repouso** — sua chave de API e selada com AES-256-GCM atras de uma **senha local** e nunca fica em texto puro nem em logs. Uma chave legada em texto puro e migrada e apagada no primeiro desbloqueio.
+- **Bloqueio por inatividade** — o chat drawer se bloqueia sozinho apos \`site.AiChatAutoLockSeconds\` segundos sem uso (padrao 30, \`0\` desativa): um modal centralizado com contagem regressiva, no seu idioma, permite cancelar ou bloquear agora, e desbloquear pede a senha de novo.
+- **Provedores resilientes** — erros transitorios do provedor sao repetidos (3 tentativas) e uma falha final vira uma mensagem simples terminando em "Tente novamente!".
+- **Geracao de documentacao com IA** — \`gitpagedocs ai\` varre os caminhos escolhidos e escreve markdown multilingue (pt/en/es); reutilizavel via \`.gitpagedocsconfig\`, cuja chave de API fica selada no cofre criptografado \`.gitpagedocsvault\` (a senha do cofre e pedida em toda execucao). \`gitpagedocs chat\` leva o mesmo assistente ao terminal.
+
+## Servidor MCP
+
+\`gitpagedocs mcp start\` sobe um servidor Model Context Protocol (stdio) expondo **20 tools** (sistema de arquivos, IA, geracao/analise de docs) e **7 resources** (\`project://structure|docs|config|repository|readme|ai/providers|ai/models\`) para editores e agentes de IA.
 `,
     configuration: `# Configuracao
 
@@ -311,7 +326,7 @@ O projeto e organizado por fronteiras de feature e responsabilidades do runtime.
 
 ## Seguranca: credenciais de IA criptografadas
 
-O console \`/ai\` e o chat drawer exigem uma senha local que deriva (PBKDF2) uma chave AES-256-GCM; as chaves ficam criptografadas no \`localStorage\` e so sao descriptografadas durante a sessao (\`@gitpagedocs/tools/security\`).
+O console \`/ai\` e o chat drawer exigem uma senha local que deriva (PBKDF2) uma chave AES-256-GCM; as chaves ficam criptografadas no \`localStorage\` e so sao descriptografadas durante a sessao (\`@gitpagedocs/tools/security\`). O drawer se bloqueia sozinho apos \`site.AiChatAutoLockSeconds\` segundos sem uso (padrao 30; \`0\` desativa): um modal centralizado com contagem regressiva, no idioma selecionado, permite cancelar ou bloquear agora, e voltar exige a senha de novo. Na CLI, a chave de \`.gitpagedocsconfig\` fica selada no cofre criptografado \`.gitpagedocsvault\` e a senha do cofre e pedida em toda execucao.
 
 ## Fluxo de dados
 

package/contracts/doc-versions.mjs

@@ -1,3 +1,3 @@
-export const PACKAGE_VERSION = "0.0.1";
+export const PACKAGE_VERSION = "0.0.3";
 
 export const DOC_VERSIONS = [PACKAGE_VERSION];

package/data/default-site-config.mjs

@@ -138,6 +138,7 @@ export function getDefaultSiteConfig(projectLink, languageToggles = buildLanguag
         audioSequentialPlayback: false,
         audioPopoverHideSource: false,
         audioPopoverShowMinutes: true,
+        AiChatAutoLockSeconds: 30,
         audioTracks: [
             {
                 url: "https://www.youtube.com/watch?v=xAR6N9N8e6U",

package/data/i18n-langmenu.mjs

@@ -81,12 +81,17 @@ export const defaultLangMenu = {
           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",
+          aiChatRetryHint: "Tente novamente!",
+          aiChatAutoLockTitle: "Bloqueio por inatividade",
+          aiChatAutoLockDesc: "Você não usou a IA por um tempo. O chat será bloqueado e suas chaves continuarão criptografadas em {seconds}s.",
+          aiChatAutoLockConfirmBtn: "Salvar",
+          aiChatAutoLockCancelBtn: "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)",
+          aiChatProviderOpenAI: "OpenAI",
+          aiChatProviderClaude: "Anthropic Claude",
+          aiChatProviderGemini: "Google Gemini",
+          aiChatProviderOllama: "Ollama",
           aiChatEmptyPageContent: "Nenhuma página ativa compatível.",
           aiChatNoPageId: "Sem página",
           aiChatOllamaUrlLabel: "URL da API Ollama (deixe em branco para local)",
@@ -197,12 +202,17 @@ export const defaultLangMenu = {
           aiChatResetPopupDesc: "This erases all saved API keys and the local password. You'll create a new password next time.",
           aiChatResetConfirmBtn: "Yes, reset",
           aiChatResetCancelBtn: "Cancel",
+          aiChatRetryHint: "Try again!",
+          aiChatAutoLockTitle: "Inactivity lock",
+          aiChatAutoLockDesc: "You have not used the AI for a while. The chat locks and your keys stay encrypted in {seconds}s.",
+          aiChatAutoLockConfirmBtn: "OK",
+          aiChatAutoLockCancelBtn: "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)",
+          aiChatProviderOpenAI: "OpenAI",
+          aiChatProviderClaude: "Anthropic Claude",
+          aiChatProviderGemini: "Google Gemini",
+          aiChatProviderOllama: "Ollama",
           aiChatEmptyPageContent: "No compatible active page.",
           aiChatNoPageId: "No page",
           aiChatOllamaUrlLabel: "Ollama API URL (leave blank for local)",
@@ -313,12 +323,17 @@ export const defaultLangMenu = {
           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",
+          aiChatRetryHint: "¡Inténtalo de nuevo!",
+          aiChatAutoLockTitle: "Bloqueo por inactividad",
+          aiChatAutoLockDesc: "No has usado la IA por un tiempo. El chat se bloqueará y tus claves seguirán cifradas en {seconds}s.",
+          aiChatAutoLockConfirmBtn: "Guardar",
+          aiChatAutoLockCancelBtn: "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)",
+          aiChatProviderOpenAI: "OpenAI",
+          aiChatProviderClaude: "Anthropic Claude",
+          aiChatProviderGemini: "Google Gemini",
+          aiChatProviderOllama: "Ollama",
           aiChatEmptyPageContent: "Ninguna página activa compatible.",
           aiChatNoPageId: "Sin página",
           aiChatOllamaUrlLabel: "URL de la API de Ollama (déjalo en blanco para local)",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gitpagedocs/cli",
-  "version": "0.0.1",
+  "version": "0.0.3",
   "description": "CLI that scaffolds and maintains gitpagedocs documentation, generates docs with AI, configures GitHub Pages, and runs the MCP server.",
   "bin": {
     "gitpagedocs": "index.mjs"
@@ -29,8 +29,8 @@
   },
   "dependencies": {
     "@clack/prompts": "^1.5.1",
-    "@gitpagedocs/mcp": "^0.0.1",
-    "@gitpagedocs/tools": "^0.0.1",
+    "@gitpagedocs/mcp": "^0.0.3",
+    "@gitpagedocs/tools": "^0.0.3",
     "tsx": "^4.21.0"
   },
   "repository": {

package/presentation/commands/chat.ts

@@ -3,7 +3,11 @@ import { createDefaultFactory } from "@gitpagedocs/tools/ai";
 import { PROVIDER_CATALOG } from "@gitpagedocs/tools";
 import type { AIProvider, ProviderConfig } from "@gitpagedocs/tools/ports";
 import { ChatSession } from "../../ai/core/chat-session";
+import { createStoredKeyUnlocker } from "../../ai/application/ai-credentials";
 import { resolveChatCredentials, type ResolvedChatCredentials } from "../../ai/application/resolve-chat-credentials";
+import { AiConfigFileRepository } from "../../ai/infrastructure/ai-config-file";
+import { AiKeyVault } from "../../ai/infrastructure/ai-key-vault";
+import { clackVaultPasswordPrompt } from "../../ai/presentation/vault-prompts";
 import {
   ElapsedSpinner,
   accent,
@@ -215,10 +219,20 @@ function printSetupHelp(providerHint: string): void {
  */
 export async function runChat(ctx: CommandContext): Promise<void> {
   const flags = parseChatArgs(ctx.args);
+  const configRepo = new AiConfigFileRepository({ cwd: ctx.cwd });
   const creds: ResolvedChatCredentials | null = await resolveChatCredentials({
     cwd: ctx.cwd,
     providerOverride: flags.provider,
     modelOverride: flags.model,
+    configRepo,
+    // The stored key is sealed in the vault: the password is asked on every run
+    // (or read from GITPAGEDOCS_VAULT_PASSWORD when there is no terminal).
+    unlockStoredKey: createStoredKeyUnlocker({
+      configRepo,
+      vault: new AiKeyVault(),
+      prompt: process.stdin.isTTY ? clackVaultPasswordPrompt : undefined,
+      onInfo: (message) => writeChrome(danger(message)),
+    }),
   });
 
   if (!creds) {

package/presentation/commands/config-clear.ts

@@ -1,14 +1,17 @@
 import { AiConfigFileRepository } from "../../ai/infrastructure/ai-config-file";
+import { AiKeyVault } from "../../ai/infrastructure/ai-key-vault";
 import type { CommandContext } from "./run-command";
 
 /**
  * `gitpagedocs config clear` — delete the stored `.gitpagedocsconfig` from the
- * per-user config directory and any legacy repo-root copy, wiping the saved AI
- * credentials (API key, provider, scan paths).
+ * per-user config directory (and any legacy repo-root copy) together with the
+ * encrypted key vault, wiping the saved AI credentials, provider and scan paths.
  */
 export async function runConfigClear(ctx: CommandContext): Promise<void> {
   const repository = new AiConfigFileRepository({ cwd: ctx.cwd });
+  const vault = new AiKeyVault();
   const removed = await repository.clear();
+  if (await vault.clear()) removed.push(vault.getVaultPath());
 
   if (!removed.length) {
     // eslint-disable-next-line no-console