@gitpagedocs/cli 1.1.66 → 1.1.68

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

@@ -0,0 +1,62 @@
+import { legacyProviderToCatalogId, resolveApiKeyFromEnv } from "@gitpagedocs/tools/ai";
+import type { AiProviderId } from "@gitpagedocs/tools/ports";
+import { PROVIDER_CATALOG } from "@gitpagedocs/tools";
+import { AiConfigFileRepository } from "../infrastructure/ai-config-file";
+
+export interface ResolvedChatCredentials {
+  readonly providerId: AiProviderId;
+  readonly model: string;
+  readonly apiKey?: string;
+  readonly baseUrl?: string;
+}
+
+export interface ResolveChatCredentialsInput {
+  readonly cwd: string;
+  /** Overrides the stored/detected provider (e.g. a `--provider` flag). */
+  readonly providerOverride?: string;
+  /** Overrides the stored/detected model (e.g. a `--model` flag). */
+  readonly modelOverride?: string;
+  /** Injectable for tests; defaults to a real config file repository. */
+  readonly configRepo?: Pick<AiConfigFileRepository, "read">;
+  /** Injectable for tests; defaults to process.env. */
+  readonly env?: Readonly<Record<string, string | undefined>>;
+}
+
+/**
+ * Resolves the provider, model and credentials for a chat turn, layering
+ * sources by priority: explicit overrides > stored .gitpagedocsconfig > env
+ * vars declared by the catalog. Returns null when no provider can be
+ * determined and no key/base URL is available, so the caller can guide setup.
+ */
+export async function resolveChatCredentials(
+  input: ResolveChatCredentialsInput,
+): Promise<ResolvedChatCredentials | null> {
+  const env = input.env ?? process.env;
+  const configRepo = input.configRepo ?? new AiConfigFileRepository({ cwd: input.cwd });
+  const stored = await configRepo.read().catch(() => null);
+
+  const providerId = input.providerOverride
+    ? legacyProviderToCatalogId(input.providerOverride)
+    : stored
+      ? legacyProviderToCatalogId(stored.ai.provider)
+      : firstProviderFromEnv(env) ?? "openai";
+
+  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 keyless = spec.auth === "none";
+  if (!keyless && !apiKey) return null;
+
+  return { providerId, model, apiKey, baseUrl };
+}
+
+function firstProviderFromEnv(
+  env: Readonly<Record<string, string | undefined>>,
+): AiProviderId | undefined {
+  for (const id of Object.keys(PROVIDER_CATALOG) as AiProviderId[]) {
+    if (resolveApiKeyFromEnv(id, env)) return id;
+  }
+  return undefined;
+}

package/ai/core/chat-session.ts

@@ -0,0 +1,44 @@
+import type { AiMessage } from "@gitpagedocs/tools/ports";
+
+/**
+ * @file chat-session.ts
+ * @description Pure conversation state for the interactive terminal chat. Holds
+ * the running message history and an optional system prompt, and builds the
+ * message array sent to a provider. No IO, no streaming, no terminal concerns —
+ * so the conversation logic is unit-testable without a provider or a TTY.
+ */
+export class ChatSession {
+  private readonly history: AiMessage[] = [];
+
+  constructor(private readonly systemPrompt?: string) {}
+
+  /** Records a user turn. */
+  addUser(content: string): void {
+    this.history.push({ role: "user", content });
+  }
+
+  /** Records an assistant turn (the fully streamed reply). */
+  addAssistant(content: string): void {
+    this.history.push({ role: "assistant", content });
+  }
+
+  /** The user/assistant messages to send for the next completion. */
+  buildRequestMessages(): AiMessage[] {
+    return [...this.history];
+  }
+
+  /** The system prompt for the request's dedicated `system` field, if any. */
+  get system(): string | undefined {
+    return this.systemPrompt?.trim() || undefined;
+  }
+
+  /** Number of recorded turns (excluding the system prompt). */
+  get turnCount(): number {
+    return this.history.length;
+  }
+
+  /** Drops the conversation history, keeping the system prompt. */
+  clear(): void {
+    this.history.length = 0;
+  }
+}

package/application/report/config-only-reporter.mjs

@@ -1,9 +1,16 @@
 /** Config-only command output messages - SRP: single place for all report messages */
 import { resolveRenderingUrl } from "../../builders/project-links.mjs";
 import { normalizeLayoutsDir } from "../../contracts/layouts-paths.mjs";
+import { languageArtifactPaths } from "../../contracts/langs-paths.mjs";
+import { SUPPORTED_LANGUAGES } from "../../contracts/languages.mjs";
 
 export function reportConfigOnlySuccess(options) {
-  return [`Generated: ${options.outputDir}/ (config-only)`, "No index.html/index.js generated."];
+  const langs = languageArtifactPaths(options.outputDir);
+  return [
+    `Generated: ${options.outputDir}/ (config-only)`,
+    `UI strings: ${langs.manifest} + ${langs.dir}/{${SUPPORTED_LANGUAGES.join(",")}}.json`,
+    "No index.html/index.js generated.",
+  ];
 }
 
 export function reportLayoutConfig(options) {

package/builders/config-orchestrator.mjs

@@ -5,16 +5,18 @@ import { DOCS } from "../content/docs.mjs";
 import { DOC_VERSIONS } from "../data/version-constants.mjs";
 import { buildRootConfig } from "./root-config-builder.mjs";
 import { buildVersionConfig } from "./version-config-builder.mjs";
+import { buildLanguageArtifacts } from "./language-bundles-builder.mjs";
 
 /**
- * Build all config artifacts (root, layouts, versions, docs).
+ * Build all config artifacts (root, languages, layouts, versions, docs).
  * @param {object} options - { useLocalLayoutConfig, githubOwner, githubRepo, root }
- * @returns {object} { rootConfig, layoutsConfig, fallbackLayoutsConfig, docs, docsHtml, versionConfigs }
+ * @returns {object} { rootConfig, languageManifest, languageBundles, layoutsConfig, fallbackLayoutsConfig, docs, docsHtml, versionConfigs }
  */
 export function buildConfigArtifacts(options = {}) {
   const root = options.root ?? process.cwd();
 
   const rootConfig = buildRootConfig(options);
+  const { languageManifest, languageBundles } = buildLanguageArtifacts();
   const layoutsConfig = { layouts: LAYOUTS };
   const fallbackLayoutsConfig = { layouts: FALLBACK_LAYOUTS };
 
@@ -25,6 +27,8 @@ export function buildConfigArtifacts(options = {}) {
 
   return {
     rootConfig,
+    languageManifest,
+    languageBundles,
     layoutsConfig,
     fallbackLayoutsConfig,
     docs: DOCS,

package/builders/language-bundles-builder.mjs

@@ -0,0 +1,24 @@
+/** Build the language manifest + per-language UI string bundles for gitpagedocs */
+import { buildLanguageManifest, splitLanguageBundles } from "@gitpagedocs/tools/i18n";
+import { SUPPORTED_LANGUAGES } from "../contracts/languages.mjs";
+import { defaultLangMenu } from "../data/i18n-langmenu.mjs";
+import { defaultTranslations } from "../data/i18n-translations.mjs";
+
+function assertLanguageStrings(languages) {
+  const missing = languages.filter((language) => !defaultLangMenu[language]);
+  if (missing.length > 0) {
+    throw new Error(`No UI strings (i18n-langmenu) for supported language(s): ${missing.join(", ")}`);
+  }
+}
+
+/**
+ * @returns {{ languageManifest: { languages: string[] }, languageBundles: Record<string, object> }}
+ */
+export function buildLanguageArtifacts() {
+  const languages = [...SUPPORTED_LANGUAGES];
+  assertLanguageStrings(languages);
+  return {
+    languageManifest: buildLanguageManifest(languages),
+    languageBundles: splitLanguageBundles(languages, defaultLangMenu, defaultTranslations),
+  };
+}

package/builders/root-config-builder.mjs

@@ -6,10 +6,7 @@ import {
   resolveSourceViewerPath,
   resolveLayoutsLinks,
 } from "./project-links.mjs";
-import { DOCS } from "../content/docs.mjs";
 import { DOC_VERSIONS } from "../data/version-constants.mjs";
-import { defaultLangMenu } from "../data/i18n-langmenu.mjs";
-import { defaultTranslations } from "../data/i18n-translations.mjs";
 import { getDefaultSiteConfig } from "../data/default-site-config.mjs";
 
 export function buildRootConfig(options = {}) {
@@ -37,7 +34,7 @@ export function buildRootConfig(options = {}) {
     "source-viewer-path": sourceViewerPath,
   }));
 
-  const baseSiteConfig = getDefaultSiteConfig(DOCS, projectLink);
+  const baseSiteConfig = getDefaultSiteConfig(projectLink);
 
   return {
     site: {
@@ -51,11 +48,9 @@ export function buildRootConfig(options = {}) {
       rendering: renderingUrl,
       AiChatEnabled: true,
       docsAccess: { enabled: false, publicKey: "" },
-      langmenu: defaultLangMenu,
     },
     VersionControl: {
       versions: versionEntries,
     },
-    translations: defaultTranslations,
   };
 }

package/content/docs-en.mjs

@@ -172,9 +172,10 @@ The version config can render a **Source code** container through \`routes-sourc
 
 ## Config keys (site)
 
-- \`name\`, \`defaultLanguage\`, \`supportedLanguages\`
+- \`name\`, \`defaultLanguage\`
 - \`docsVersion\`, \`rendering\`, \`ThemeDefault\`, \`ThemeModeDefault\`
 - \`ProjectLink\`, \`layoutsConfigPathOficial\`, \`layoutsConfigPath\`
+- Languages and UI strings: \`gitpagedocs/langs.json\` + \`gitpagedocs/langs/<lang>.json\`
 
 ## Environment variables
 
@@ -316,7 +317,14 @@ Supported adapters:
 `,
     configuration: `# Configuration
 
-Runtime configuration lives in \`gitpagedocs/config.json\`.
+Runtime configuration lives in \`gitpagedocs/config.json\`. UI text lives next to it, one file per language.
+
+## Languages (\`langs.json\` + \`langs/\`)
+
+- \`gitpagedocs/langs.json\` lists the shipped languages in menu order: \`{ "languages": ["en", "pt", "es"] }\`.
+- \`gitpagedocs/langs/<lang>.json\` holds that language's strings: \`langmenu\` (header, search, source viewer, audio player, AI chat and docs-access labels) and \`translations\` (\`notFound\`, \`navigation\`, \`footer\`).
+- To add a language, create \`langs/<lang>.json\` and append its code to \`langs.json\`.
+- Older \`config.json\` files that still inline \`site.langmenu\` / \`translations\` keep working; when both exist, the \`langs/\` files win and any missing key is backfilled from the current release.
 
 ## \`site\` section
 
@@ -324,7 +332,6 @@ Important keys:
 
 - \`name\`
 - \`defaultLanguage\`
-- \`supportedLanguages\`
 - \`docsVersion\`
 - \`rendering\`
 - \`ThemeDefault\`
@@ -453,7 +460,7 @@ A pnpm + turborepo monorepo where all business logic lives in one shared core (\
 
 - **frontend/** — Next.js viewer (Feature-Sliced: \`app / widgets / features / entities / shared\`); static export.
 - **cli/** — the published \`gitpagedocs\` bin (hexagonal: \`presentation / application / domain / infrastructure\`) + \`cli/ai/\` (the AI documentation CLI).
-- **tools/** — \`@gitpagedocs/tools\`: \`ai/ security/ crypto/ cache/ config/ logger/ errors/ filesystem/ documentation/ ports/\`.
+- **tools/** — \`@gitpagedocs/tools\`: \`ai/ security/ crypto/ cache/ config/ logger/ errors/ filesystem/ documentation/ i18n/ ports/\`.
 - **mcp/** — \`@gitpagedocs/mcp\`: MCP tools + resources delegating to \`tools/\`.
 
 ## Main runtime modules (frontend)

package/content/docs-es.mjs

@@ -156,9 +156,10 @@ El config de version puede renderizar un contenedor **Codigo fuente** via \`rout
 
 ## Claves de config (site)
 
-- \`name\`, \`defaultLanguage\`, \`supportedLanguages\`
+- \`name\`, \`defaultLanguage\`
 - \`docsVersion\`, \`rendering\`, \`ThemeDefault\`, \`ThemeModeDefault\`
 - \`ProjectLink\`, \`layoutsConfigPathOficial\`, \`layoutsConfigPath\`
+- Idiomas y textos de la UI: \`gitpagedocs/langs.json\` + \`gitpagedocs/langs/<lang>.json\`
 
 ## Variables de entorno
 
@@ -167,7 +168,14 @@ El config de version puede renderizar un contenedor **Codigo fuente** via \`rout
 `,
     configuration: `# Configuracion
 
-La configuracion de runtime esta en \`gitpagedocs/config.json\`.
+La configuracion de runtime esta en \`gitpagedocs/config.json\`. Los textos de la UI viven al lado, un archivo por idioma.
+
+## Idiomas (\`langs.json\` + \`langs/\`)
+
+- \`gitpagedocs/langs.json\` lista los idiomas disponibles en el orden del menu: \`{ "languages": ["en", "pt", "es"] }\`.
+- \`gitpagedocs/langs/<lang>.json\` guarda los textos de ese idioma: \`langmenu\` (cabecera, busqueda, visor de codigo, reproductor de audio, chat de IA y acceso a los docs) y \`translations\` (\`notFound\`, \`navigation\`, \`footer\`).
+- Para agregar un idioma, crea \`langs/<lang>.json\` y agrega su codigo a \`langs.json\`.
+- Los \`config.json\` antiguos que aun traen \`site.langmenu\` / \`translations\` inline siguen funcionando; cuando existen ambos, los archivos de \`langs/\` prevalecen y cualquier clave ausente se completa desde la version actual.
 
 ## Seccion \`site\`
 
@@ -175,7 +183,6 @@ Claves principales:
 
 - \`name\`: titulo del proyecto en UI
 - \`defaultLanguage\`: idioma por defecto
-- \`supportedLanguages\`: lista de idiomas disponibles
 - \`HideThemeSelector\`: ocultar/mostrar selector de tema
 - \`ThemeDefault\`: id del tema inicial
 - \`ThemeModeDefault\`: modo inicial (\`light\` o \`dark\`)
@@ -293,7 +300,7 @@ El proyecto esta organizado por fronteras de feature y responsabilidades de runt
 
 - **frontend/** — visor Next.js (Feature-Sliced: app / widgets / features / entities / shared); export estatico.
 - **cli/** — el bin publicado \`gitpagedocs\` (hexagonal) + \`cli/ai/\` (CLI de documentacion con IA).
-- **tools/** — \`@gitpagedocs/tools\`: ai/ security/ crypto/ cache/ config/ logger/ errors/ filesystem/ documentation/ ports/.
+- **tools/** — \`@gitpagedocs/tools\`: ai/ security/ crypto/ cache/ config/ logger/ errors/ filesystem/ documentation/ i18n/ ports/.
 - **mcp/** — \`@gitpagedocs/mcp\`: herramientas + recursos MCP que delegan a tools/.
 
 ## Modulos principales (frontend)

package/content/docs-pt.mjs

@@ -156,9 +156,10 @@ O config da versao pode renderizar um container **Codigo fonte** via \`routes-so
 
 ## Chaves de config (site)
 
-- \`name\`, \`defaultLanguage\`, \`supportedLanguages\`
+- \`name\`, \`defaultLanguage\`
 - \`docsVersion\`, \`rendering\`, \`ThemeDefault\`, \`ThemeModeDefault\`
 - \`ProjectLink\`, \`layoutsConfigPathOficial\`, \`layoutsConfigPath\`
+- Idiomas e textos da UI: \`gitpagedocs/langs.json\` + \`gitpagedocs/langs/<lang>.json\`
 
 ## Variaveis de ambiente
 
@@ -167,7 +168,14 @@ O config da versao pode renderizar um container **Codigo fonte** via \`routes-so
 `,
     configuration: `# Configuracao
 
-A configuracao de runtime fica em \`gitpagedocs/config.json\`.
+A configuracao de runtime fica em \`gitpagedocs/config.json\`. Os textos da UI ficam ao lado, um arquivo por idioma.
+
+## Idiomas (\`langs.json\` + \`langs/\`)
+
+- \`gitpagedocs/langs.json\` lista os idiomas disponiveis na ordem do menu: \`{ "languages": ["en", "pt", "es"] }\`.
+- \`gitpagedocs/langs/<lang>.json\` guarda os textos daquele idioma: \`langmenu\` (cabecalho, busca, visualizador de codigo, player de audio, chat de IA e acesso aos docs) e \`translations\` (\`notFound\`, \`navigation\`, \`footer\`).
+- Para adicionar um idioma, crie \`langs/<lang>.json\` e inclua o codigo em \`langs.json\`.
+- Arquivos \`config.json\` antigos que ainda trazem \`site.langmenu\` / \`translations\` inline continuam funcionando; quando os dois existem, os arquivos de \`langs/\` prevalecem e qualquer chave ausente e preenchida a partir da versao atual.
 
 ## Secao \`site\`
 
@@ -175,7 +183,6 @@ Principais chaves:
 
 - \`name\`: titulo do projeto no UI
 - \`defaultLanguage\`: idioma padrao
-- \`supportedLanguages\`: lista de idiomas disponiveis
 - \`HideThemeSelector\`: esconde/mostra seletor de tema
 - \`ThemeDefault\`: id do tema inicial
 - \`ThemeModeDefault\`: modo inicial (\`light\` ou \`dark\`)
@@ -293,7 +300,7 @@ O projeto e organizado por fronteiras de feature e responsabilidades do runtime.
 
 - **frontend/** — visualizador Next.js (Feature-Sliced: app / widgets / features / entities / shared); export estatico.
 - **cli/** — o bin publicado \`gitpagedocs\` (hexagonal) + \`cli/ai/\` (CLI de documentacao com IA).
-- **tools/** — \`@gitpagedocs/tools\`: ai/ security/ crypto/ cache/ config/ logger/ errors/ filesystem/ documentation/ ports/.
+- **tools/** — \`@gitpagedocs/tools\`: ai/ security/ crypto/ cache/ config/ logger/ errors/ filesystem/ documentation/ i18n/ ports/.
 - **mcp/** — \`@gitpagedocs/mcp\`: ferramentas + recursos MCP que delegam ao tools/.
 
 ## Modulos principais (frontend)

package/contracts/doc-versions.mjs

@@ -1,3 +1,3 @@
-export const PACKAGE_VERSION = "1.1.66";
+export const PACKAGE_VERSION = "1.1.68";
 
 export const DOC_VERSIONS = [PACKAGE_VERSION];

package/contracts/langs-paths.mjs

@@ -0,0 +1,25 @@
+/**
+ * Canonical locations for the language artifacts inside the docs output dir:
+ *
+ *   <outputDir>/langs.json         manifest listing the shipped languages
+ *   <outputDir>/langs/<lang>.json  UI strings (langmenu + translations) of one language
+ *
+ * The file names come from @gitpagedocs/tools so the generator and the viewer
+ * never disagree about where the bundles live.
+ */
+import { LANGS_DIRNAME, LANGS_MANIFEST_FILENAME } from "@gitpagedocs/tools/i18n";
+
+/**
+ * Repo-relative POSIX paths of the language artifacts for a docs output dir.
+ *
+ * @param {string} outputDir Docs output dir (e.g. `gitpagedocs`).
+ * @returns {{ manifest: string, dir: string, bundle: (language: string) => string }}
+ */
+export function languageArtifactPaths(outputDir) {
+  const dir = `${outputDir}/${LANGS_DIRNAME}`;
+  return {
+    manifest: `${outputDir}/${LANGS_MANIFEST_FILENAME}`,
+    dir,
+    bundle: (language) => `${dir}/${language}.json`,
+  };
+}

package/contracts/languages.mjs

@@ -0,0 +1,6 @@
+/**
+ * Languages the generator ships UI strings and docs for, in menu order. This
+ * is the list written to `gitpagedocs/langs.json`; every entry must have a
+ * `langs/<lang>.json` bundle and a docs content module.
+ */
+export const SUPPORTED_LANGUAGES = Object.freeze(["en", "pt", "es"]);

package/data/default-site-config.mjs

@@ -1,8 +1,8 @@
-export function getDefaultSiteConfig(DOCS, projectLink) {
+/** Site chrome defaults. The language list and UI strings live in langs.json + langs/. */
+export function getDefaultSiteConfig(projectLink) {
     return {
         name: "Git Pages Docs",
         defaultLanguage: "en",
-        supportedLanguages: Object.keys(DOCS || { en: 1, pt: 1, es: 1 }),
         HideThemeSelector: false,
         ThemeDefault: "aurora-dark",
         ThemeModeDefault: "dark",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gitpagedocs/cli",
-  "version": "1.1.66",
+  "version": "1.1.68",
   "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": "^1.1.66",
-    "@gitpagedocs/tools": "^1.1.66",
+    "@gitpagedocs/mcp": "^1.1.68",
+    "@gitpagedocs/tools": "^1.1.68",
     "tsx": "^4.21.0"
   },
   "repository": {

package/presentation/commands/chat.ts

@@ -0,0 +1,259 @@
+import readline from "node:readline";
+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 { resolveChatCredentials, type ResolvedChatCredentials } from "../../ai/application/resolve-chat-credentials";
+import {
+  ElapsedSpinner,
+  accent,
+  danger,
+  writeChrome,
+  writeContent,
+} from "../ui/terminal-stream";
+import type { CommandContext } from "./run-command";
+
+/** Positions the model as a documentation assistant for the current project. */
+const DEFAULT_CHAT_SYSTEM_PROMPT = [
+  "You are a concise documentation and coding assistant embedded in the gitpagedocs CLI.",
+  "Answer questions about the user's project, source code and documentation.",
+  "Prefer short, correct, actionable answers; use GitHub-flavored markdown for code.",
+].join(" ");
+
+const EXIT_REARM_MS = 3000;
+
+interface ChatFlags {
+  provider?: string;
+  model?: string;
+  system?: string;
+  question?: string;
+}
+
+function parseChatArgs(args: readonly string[]): ChatFlags {
+  // args[0] is the verb ("chat"); parse flags and collect the free-text question.
+  const flags: ChatFlags = {};
+  const positional: string[] = [];
+  for (let i = 1; i < args.length; i += 1) {
+    const arg = args[i];
+    if (arg === "--provider" || arg === "--model" || arg === "--system") {
+      const value = args[i + 1];
+      if (value !== undefined) {
+        if (arg === "--provider") flags.provider = value;
+        else if (arg === "--model") flags.model = value;
+        else flags.system = value;
+        i += 1;
+      }
+      continue;
+    }
+    if (arg.startsWith("--")) continue;
+    positional.push(arg);
+  }
+  const question = positional.join(" ").trim();
+  if (question) flags.question = question;
+  return flags;
+}
+
+async function readPipedStdin(): Promise<string> {
+  if (process.stdin.isTTY) return "";
+  const chunks: Buffer[] = [];
+  for await (const chunk of process.stdin) {
+    chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
+  }
+  return Buffer.concat(chunks).toString("utf-8").trim();
+}
+
+/**
+ * Streams one assistant turn to stdout. Cancellation is a scoped concern: the
+ * caller owns the AbortController and the stream stops the moment it aborts
+ * (the async generator's cleanup tears down the HTTP request). Returns whether
+ * the turn completed (false = aborted or errored).
+ */
+async function streamTurn(
+  provider: AIProvider,
+  config: ProviderConfig,
+  session: ChatSession,
+  userText: string,
+  signal: AbortSignal,
+): Promise<boolean> {
+  session.addUser(userText);
+  const spinner = new ElapsedSpinner("Thinking");
+  spinner.start();
+  let full = "";
+  let started = false;
+  try {
+    for await (const delta of provider.stream(
+      { messages: session.buildRequestMessages(), system: session.system, signal },
+      config,
+    )) {
+      if (!started) {
+        spinner.stop();
+        started = true;
+      }
+      full += delta;
+      writeContent(delta);
+    }
+    if (started) writeContent("\n");
+    session.addAssistant(full);
+    writeChrome(
+      `${PROVIDER_CATALOG[config.providerId].label} · ${config.model} · ${spinner.elapsedSeconds().toFixed(1)}s`,
+    );
+    return true;
+  } catch (error) {
+    spinner.stop();
+    if (signal.aborted || (error instanceof Error && error.name === "AbortError")) {
+      if (started) writeContent("\n");
+      writeChrome(danger("Interrupted."));
+      // Keep the partial reply in history so follow-ups have context.
+      session.addAssistant(full);
+      return false;
+    }
+    writeChrome(danger(`Error: ${error instanceof Error ? error.message : String(error)}`));
+    return false;
+  } finally {
+    spinner.stop();
+  }
+}
+
+/** One-shot mode: a single question in, the answer out, then exit. */
+async function runOneShot(
+  provider: AIProvider,
+  config: ProviderConfig,
+  session: ChatSession,
+  question: string,
+): Promise<void> {
+  const controller = new AbortController();
+  const onSigint = () => controller.abort();
+  process.on("SIGINT", onSigint);
+  try {
+    const ok = await streamTurn(provider, config, session, question, controller.signal);
+    if (!ok) process.exitCode = 1;
+  } finally {
+    process.off("SIGINT", onSigint);
+  }
+}
+
+/** Interactive REPL: requires a TTY on both ends. */
+async function runRepl(
+  provider: AIProvider,
+  config: ProviderConfig,
+  session: ChatSession,
+): Promise<void> {
+  const spec = PROVIDER_CATALOG[config.providerId];
+  writeChrome(`Chat — ${spec.label} · ${config.model}`);
+  writeChrome("Commands: /clear reset · /help · /exit (or Ctrl+C twice)");
+
+  const rl = readline.createInterface({
+    input: process.stdin,
+    output: process.stderr,
+    prompt: accent("› "),
+  });
+
+  let generating: AbortController | null = null;
+  let exitArmed = false;
+  let exitTimer: ReturnType<typeof setTimeout> | null = null;
+
+  rl.on("SIGINT", () => {
+    if (generating) {
+      generating.abort();
+      return;
+    }
+    if (exitArmed) {
+      rl.close();
+      return;
+    }
+    exitArmed = true;
+    writeChrome("Press Ctrl+C again to exit.");
+    exitTimer = setTimeout(() => {
+      exitArmed = false;
+    }, EXIT_REARM_MS);
+    rl.prompt();
+  });
+
+  rl.prompt();
+  for await (const line of rl) {
+    if (exitTimer) {
+      clearTimeout(exitTimer);
+      exitTimer = null;
+    }
+    exitArmed = false;
+    const input = line.trim();
+    if (!input) {
+      rl.prompt();
+      continue;
+    }
+    if (input === "/exit" || input === "/quit") break;
+    if (input === "/clear") {
+      session.clear();
+      writeChrome("Conversation cleared.");
+      rl.prompt();
+      continue;
+    }
+    if (input === "/help") {
+      writeChrome("Type a message to chat. /clear resets history, /exit quits, Ctrl+C interrupts a reply.");
+      rl.prompt();
+      continue;
+    }
+    generating = new AbortController();
+    await streamTurn(provider, config, session, input, generating.signal);
+    generating = null;
+    rl.prompt();
+  }
+  rl.close();
+  writeChrome("Bye.");
+}
+
+function printSetupHelp(providerHint: string): void {
+  writeChrome(danger("No AI credentials found."));
+  writeChrome(`Set an API key via environment variable (e.g. ${providerHint}) or run: gitpagedocs ai`);
+  writeChrome("Then: gitpagedocs chat \"your question\"  ·  or just: gitpagedocs chat");
+}
+
+/**
+ * `gitpagedocs chat [question]` — interactive AI chat in the terminal.
+ * Flags: --provider <id>, --model <id>, --system <prompt>.
+ * One-shot when a question is given or stdin is piped; a REPL on a TTY.
+ */
+export async function runChat(ctx: CommandContext): Promise<void> {
+  const flags = parseChatArgs(ctx.args);
+  const creds: ResolvedChatCredentials | null = await resolveChatCredentials({
+    cwd: ctx.cwd,
+    providerOverride: flags.provider,
+    modelOverride: flags.model,
+  });
+
+  if (!creds) {
+    const hintProvider = flags.provider ?? "openai";
+    const hint = PROVIDER_CATALOG[
+      (hintProvider in PROVIDER_CATALOG ? hintProvider : "openai") as keyof typeof PROVIDER_CATALOG
+    ].envVars[0] ?? "OPENAI_API_KEY";
+    printSetupHelp(hint);
+    process.exitCode = 1;
+    return;
+  }
+
+  const provider = createDefaultFactory().create(creds.providerId);
+  const config: ProviderConfig = {
+    providerId: creds.providerId,
+    model: creds.model,
+    apiKey: creds.apiKey,
+    baseUrl: creds.baseUrl,
+  };
+  const session = new ChatSession(flags.system ?? DEFAULT_CHAT_SYSTEM_PROMPT);
+
+  const piped = await readPipedStdin();
+  const oneShot = [flags.question, piped].filter(Boolean).join("\n\n").trim();
+
+  if (oneShot) {
+    await runOneShot(provider, config, session, oneShot);
+    return;
+  }
+
+  if (!process.stdin.isTTY || !process.stdout.isTTY) {
+    writeChrome(danger("No question given and no interactive terminal available."));
+    writeChrome('Usage: gitpagedocs chat "your question"');
+    process.exitCode = 1;
+    return;
+  }
+
+  await runRepl(provider, config, session);
+}

package/presentation/commands/config-info.ts

@@ -1,20 +1,33 @@
 import path from "node:path";
-import { defaultConfigLoader, isAppError } from "@gitpagedocs/tools";
+import { readFile } from "node:fs/promises";
+import { DEFAULT_LANGS_MANIFEST_PATH, defaultConfigLoader, isAppError, parseLanguageManifest } from "@gitpagedocs/tools";
 import type { CommandContext } from "./run-command";
 
+const UNKNOWN = "—";
+
+/** Languages from `gitpagedocs/langs.json`, else the legacy inline `site.supportedLanguages`. */
+async function resolveLanguages(cwd: string, site: Record<string, unknown>): Promise<string[]> {
+  try {
+    const manifest = parseLanguageManifest(JSON.parse(await readFile(path.join(cwd, DEFAULT_LANGS_MANIFEST_PATH), "utf-8")));
+    if (manifest) return manifest.languages;
+  } catch {
+    // No manifest: fall back to the inline list below.
+  }
+  return Array.isArray(site.supportedLanguages) ? (site.supportedLanguages as string[]) : [];
+}
+
 /** `gitpagedocs config` — resolve and summarize the active gitpagedocs config. */
 export async function runConfig(ctx: CommandContext): Promise<void> {
   try {
     const { config, sourcePath, extension } = await defaultConfigLoader.loadGitPageDocsConfig(ctx.cwd);
     const site = (config as { site?: Record<string, unknown> }).site ?? {};
+    const languages = await resolveLanguages(ctx.cwd, site);
     // eslint-disable-next-line no-console
     console.log(
       `\n  Config: ${path.relative(ctx.cwd, sourcePath)} (${extension})\n` +
-        `    site name        : ${String(site.name ?? "—")}\n` +
-        `    default language : ${String(site.defaultLanguage ?? "—")}\n` +
-        `    languages        : ${
-          Array.isArray(site.supportedLanguages) ? (site.supportedLanguages as string[]).join(", ") : "—"
-        }\n`,
+        `    site name        : ${String(site.name ?? UNKNOWN)}\n` +
+        `    default language : ${String(site.defaultLanguage ?? UNKNOWN)}\n` +
+        `    languages        : ${languages.length > 0 ? languages.join(", ") : UNKNOWN}\n`,
     );
   } catch (error) {
     const message = isAppError(error) ? error.message : String(error);

package/presentation/commands/run-command.ts

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

package/presentation/index.ts

@@ -45,8 +45,9 @@ const params: CliRuntimeParams = {
 };
 
 async function main(): Promise<void> {
-  // `mcp start` owns stdout (the MCP stdio channel) — no banner/credits there.
-  const stdoutOwnedByCommand = process.argv[2] === "mcp";
+  // Commands that own stdout get no banner/credits: `mcp start` (the MCP stdio
+  // channel) and `chat` (streamed model output must be the only thing on stdout).
+  const stdoutOwnedByCommand = process.argv[2] === "mcp" || process.argv[2] === "chat";
   if (!stdoutOwnedByCommand) printBanner();
 
   // New informational/utility commands (version, doctor, provider, models,

package/presentation/ui/terminal-stream.ts

@@ -0,0 +1,97 @@
+/**
+ * @file terminal-stream.ts
+ * @description Terminal rendering for streamed AI output, non-TTY-first:
+ *   - model text goes to STDOUT (so `chat "q" > out.txt` captures clean content)
+ *   - all chrome (spinner, headers, hints) goes to STDERR
+ *   - colours/spinner are emitted only on a TTY; a pipe gets plain text
+ * Keeps the streaming/rendering side effects in one place, apart from the pure
+ * ChatSession state.
+ */
+const ANSI = {
+  reset: "\x1b[0m",
+  dim: "\x1b[2m",
+  cyan: "\x1b[36m",
+  green: "\x1b[32m",
+  red: "\x1b[31m",
+} as const;
+
+const SPINNER_FRAMES = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"] as const;
+const SPINNER_INTERVAL_MS = 80;
+
+function stdoutIsTty(): boolean {
+  return Boolean(process.stdout.isTTY);
+}
+
+function stderrIsTty(): boolean {
+  return Boolean(process.stderr.isTTY);
+}
+
+/** Writes model content to stdout (verbatim; the actual deliverable). */
+export function writeContent(text: string): void {
+  process.stdout.write(text);
+}
+
+/** Writes one chrome line to stderr, dimmed on a TTY. */
+export function writeChrome(line: string): void {
+  if (stderrIsTty()) {
+    process.stderr.write(`${ANSI.dim}${line}${ANSI.reset}\n`);
+  } else {
+    process.stderr.write(`${line}\n`);
+  }
+}
+
+/** Colour helpers that no-op when stderr is not a TTY. */
+export function accent(text: string): string {
+  return stderrIsTty() ? `${ANSI.cyan}${text}${ANSI.reset}` : text;
+}
+
+export function danger(text: string): string {
+  return stderrIsTty() ? `${ANSI.red}${text}${ANSI.reset}` : text;
+}
+
+/**
+ * A spinner with elapsed-time readout on stderr. On a non-TTY it prints a
+ * single static line instead of animating, so logs stay clean. `stop()` clears
+ * the line and is idempotent.
+ */
+export class ElapsedSpinner {
+  private timer: ReturnType<typeof setInterval> | null = null;
+  private frame = 0;
+  private readonly startedAt = Date.now();
+
+  constructor(private readonly label: string) {}
+
+  start(): void {
+    if (!stderrIsTty()) {
+      process.stderr.write(`${this.label}...\n`);
+      return;
+    }
+    this.render();
+    this.timer = setInterval(() => this.render(), SPINNER_INTERVAL_MS);
+  }
+
+  private render(): void {
+    const seconds = ((Date.now() - this.startedAt) / 1000).toFixed(1);
+    const glyph = SPINNER_FRAMES[this.frame % SPINNER_FRAMES.length];
+    this.frame += 1;
+    process.stderr.write(`\r${ANSI.cyan}${glyph}${ANSI.reset} ${ANSI.dim}${this.label} ${seconds}s${ANSI.reset}\x1b[K`);
+  }
+
+  stop(): void {
+    if (this.timer) {
+      clearInterval(this.timer);
+      this.timer = null;
+    }
+    if (stderrIsTty()) {
+      process.stderr.write("\r\x1b[K");
+    }
+  }
+
+  /** Elapsed seconds since construction. */
+  elapsedSeconds(): number {
+    return (Date.now() - this.startedAt) / 1000;
+  }
+}
+
+export const supportsColor = stderrIsTty;
+export const isInteractiveOutput = stdoutIsTty;

package/runtime/output.mjs

@@ -9,6 +9,8 @@ import {
   normalizeToOutputPath,
 } from "./doc-path-resolver.mjs";
 import { layoutsArtifactPaths } from "../contracts/layouts-paths.mjs";
+import { languageArtifactPaths } from "../contracts/langs-paths.mjs";
+import { SUPPORTED_LANGUAGES } from "../contracts/languages.mjs";
 
 const DEFAULT_ICON_SVG = `<?xml version="1.0" encoding="utf-8"?>
 <svg width="800px" height="800px" viewBox="0 0 24 24" fill="none" xmlns="http://www.w3.org/2000/svg">
@@ -29,7 +31,7 @@ function listExistingVersionIds(root, outputDir) {
 function removeLegacySourceViewerFiles(root, outputDir) {
   const versionIds = listExistingVersionIds(root, outputDir);
   for (const versionId of versionIds) {
-    for (const language of ["pt", "en", "es"]) {
+    for (const language of SUPPORTED_LANGUAGES) {
       for (const fileName of ["source-viewer", "source-viewer.html"]) {
         const legacyPath = path.join(root, outputDir, "docs", "versions", versionId, language, fileName);
         if (existsSync(legacyPath)) {
@@ -75,6 +77,15 @@ async function writeLayoutArtifacts(options) {
   }
 }
 
+/** Write the language manifest and one UI-strings bundle per shipped language. */
+async function writeLanguageArtifacts(root, outputDir, artifacts) {
+  const paths = languageArtifactPaths(outputDir);
+  await writeJson(root, paths.manifest, artifacts.languageManifest);
+  for (const [language, bundle] of Object.entries(artifacts.languageBundles)) {
+    await writeJson(root, paths.bundle(language), bundle);
+  }
+}
+
 export async function writeConfigOnlyOutput(options) {
   const {
     root,
@@ -88,7 +99,7 @@ export async function writeConfigOnlyOutput(options) {
   } = options;
 
   // Keep only versioned docs output in docs/, removing legacy root language folders.
-  for (const legacyLanguageDir of ["en", "pt", "es"]) {
+  for (const legacyLanguageDir of SUPPORTED_LANGUAGES) {
     const legacyPath = path.join(root, outputDir, "docs", legacyLanguageDir);
     if (existsSync(legacyPath)) {
       rmSync(legacyPath, { recursive: true, force: true });
@@ -96,6 +107,7 @@ export async function writeConfigOnlyOutput(options) {
   }
 
   await writeJson(root, `${outputDir}/config.json`, artifacts.rootConfig);
+  await writeLanguageArtifacts(root, outputDir, artifacts);
   await writeText(root, `${outputDir}/icon.svg`, DEFAULT_ICON_SVG);
   await writeLayoutArtifacts({
     root,
@@ -146,7 +158,7 @@ export async function writeConfigOnlyOutput(options) {
     }
 
     // Ensure version folders always include an index file.
-    for (const language of ["pt", "en", "es"]) {
+    for (const language of SUPPORTED_LANGUAGES) {
       const fallbackIndex = artifacts.docs?.[language]?.index;
       if (!fallbackIndex) continue;
       const versionIndexPath = `${outputDir}/docs/versions/${versionId}/${language}/index.md`;