@gitpagedocs/cli 0.0.1

package/README.md

@@ -0,0 +1,193 @@
+# @gitpagedocs/cli
+
+The **published npm package** of the [Git Page Docs](../README.md) monorepo (the command it installs is `gitpagedocs`). It scaffolds the `gitpagedocs/` docs contract, generates docs with AI, configures GitHub Pages, and runs the MCP server.
+
+```bash
+npm install -g @gitpagedocs/cli   # global (installs the `gitpagedocs` command)
+gitpagedocs                       # generate gitpagedocs/ config (config-only)
+
+# or one-off, no install:
+npx @gitpagedocs/cli
+```
+
+> This package ships its TypeScript sources and runs them via `tsx`; it depends on the workspace packages `@gitpagedocs/tools` and `@gitpagedocs/mcp` (published alongside it).
+
+## Commands
+
+| Command | Description |
+|---|---|
+| `gitpagedocs` | Generate `gitpagedocs/` config + versioned docs (config-only) |
+| `gitpagedocs --layoutconfig` | Also emit local layout templates in `gitpagelayouts/` |
+| `gitpagedocs --layouts-dir <dir>` | Folder for local layouts (default: `gitpagelayouts`) |
+| `gitpagedocs --no-interactive` / `-y` | Never prompt; use flags and defaults |
+| `gitpagedocs --push --owner <o> --repo <r> [--path <sub>]` | Generate, configure Pages, create workflow, commit + push |
+| `gitpagedocs --home` | Standalone distribution (`gitpagedocshome/`: static site + .env + Dockerfile) |
+| `gitpagedocs -i` / `--interactive` | Interactive prompts |
+| `gitpagedocs ai` | Interactive AI documentation generator — writes pages in the gitpagedocs pattern (see below) |
+| `gitpagedocs provider [id]` · `models [provider]` | List AI providers / catalog models |
+| `gitpagedocs document[:repo\|:file\|:folder]` | Generate documentation with AI 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 doctor` · `version` · `update` | Diagnostics / version / registry update check |
+| `gitpagedocs mcp start` | Start the MCP server over stdio |
+
+The AI-CLI implementation lives in `cli/ai/` (relocated from the frontend so the published package is self-contained).
+
+# CLI Architecture (Clean Architecture + SOLID)
+
+## Layer Overview
+
+```
+cli/
+|-- index.mjs                          # Node entry (bootstraps TS presentation via tsx)
+|-- package.json                       # the published `gitpagedocs` package
+|-- ai/                                # AI documentation CLI (provider/model/paths → markdown)
+|-- contracts/                         # Stable contracts for external tooling
+|   `-- doc-versions.mjs
+|
+|-- presentation/                      # Interface/composition root
+|   |-- index.ts
+|   |-- options/
+|   `-- ui/
+|
+|-- application/                       # Use-cases and ports
+|   |-- config-only/handler.mjs
+|   |-- home/handler.mjs
+|   |-- report/config-only-reporter.mjs
+|   |-- use-cases/dispatch-mode.ts
+|   `-- ports/cli-runtime-ports.ts
+|
+|-- domain/                            # Business rules
+|   `-- services/sanitize-segment.mjs
+|
+|-- infrastructure/                    # Side effects and adapters
+|   |-- config-only/runtime.mjs
+|   `-- home/runtime.mjs
+|
+|-- builders/                          # Pure config builders
+|-- data/                              # Constants and metadata
+|-- content/                           # Static docs content
+|-- runtime/                           # Low-level runtime helpers
+`-- home/                              # Home templates/files
+```
+
+## SOLID Principles
+
+| Principle | Application |
+|-----------|-------------|
+| **SRP** | `application/report` only formats messages; handlers only orchestrate |
+| **OCP** | New runtime implementations can be injected through ports |
+| **LSP** | `dispatch-mode` works with any runner implementing `CliCommandRunner` |
+| **ISP** | Split runtime contracts (`ConfigOnlyRuntimePort`, `HomeRuntimePort`) |
+| **DIP** | Use-cases depend on `application/ports`, not concrete fs/git/exec |
+
+## Clean Architecture
+
+- **Interfaces/Presentation**: parse CLI args, resolve mode, wire dependencies in `presentation/index.ts`
+- **Application**: orchestrate flows with explicit ports, without direct fs/git/exec imports
+- **Domain**: sanitize and core rules with no infrastructure dependencies
+- **Infrastructure**: concrete adapters for runtime side effects
+- **Contracts**: `tools/smoke` consumes `cli/contracts` instead of internal CLI modules
+
+## Authorized Routes Pipeline
+
+The CLI now generates authorized-route docs and config entries in PT/EN/ES.
+
+- Source content: `cli/content/docs.mjs` (`authorizedRoutes` key per language)
+- Route metadata: `cli/data/route-metas.mjs` (`ROUTE_META_ID6`)
+- Route path mapping: `cli/data/path-mappings.mjs` (`authorized-routes.md`)
+- Version config composition: `cli/builders/version-config-builder.mjs`
+- Doc key resolution: `cli/runtime/doc-path-resolver.mjs`
+
+Generated artifacts include:
+
+- `gitpagedocs/docs/versions/<version>/config.json` with `auth` and route `authorization`
+- `gitpagedocs/docs/versions/<version>/{pt,en,es}/authorized-routes.md`
+- `menus-header-md` entry dedicated to Authorized Routes
+
+## GitHub Pages Push Paths
+
+- Default project-site publish (`--push` without `--path`) targets `/<repo>/`.
+- Custom project subpath publish (`--push --path <segment>`) targets `/<repo>/<segment>/`.
+- `--path` accepts a single sanitized segment (letters, numbers, `.`, `_`, `-`).
+
+Example:
+
+```bash
+npx @gitpagedocs/cli --owner vidigal-code --repo energy-bill-ai-parser --path git-docs --push
+```
+
+Expected URL after deployment:
+
+```text
+https://vidigal-code.github.io/energy-bill-ai-parser/git-docs/
+```
+
+## AI CLI (interactive + config file)
+
+The CLI now includes a dedicated interactive AI mode:
+
+```bash
+npx @gitpagedocs/cli ai
+```
+
+### What it does
+
+- asks provider (`openai`, `claude`, `gemini`, `ollama`)
+- asks API key or Ollama URL
+- asks paths to scan (supports one or many paths, including other repositories)
+- generates documentation in `pt`, `en`, `es` **in the gitpagedocs pattern**
+- optionally persists config in `.gitpagedocsconfig`
+
+### gitpagedocs pattern output
+
+The model is given a gitpagedocs-aware system prompt and returns documentation split into
+pages (delimited by `=== PAGE: <slug> | <Title> ===`). The CLI scaffolds the base
+`gitpagedocs/` structure first, then writes each page to
+`gitpagedocs/docs/versions/<latest>/<lang>/<slug>.md` for every language and **wires it into
+that version's `config.json`** (`routes-md` + `menus-header-md`) so the pages render in the
+viewer menu. Entries are tagged `aiGenerated` and idempotent (re-running replaces them). A
+later plain `gitpagedocs` rebuild drops the wiring — re-run `gitpagedocs ai` to restore.
+
+### `.gitpagedocsconfig` (manual mode)
+
+The file lives in the per-user OS config directory (never inside the repository, so
+the API key cannot be committed by accident) and is written with owner-only
+permissions on POSIX systems:
+
+- Windows: `%APPDATA%\gitpagedocs\.gitpagedocsconfig`
+- 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
+`.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`:
+
+```json
+{
+	"version": 1,
+	"ai": {
+		"provider": "openai",
+		"model": "gpt-4o-mini",
+		"apiKey": "<YOUR_API_KEY>",
+		"paths": ["src", "cli", "../another-repo/src"],
+		"languages": ["pt", "en", "es"],
+		"outputDir": "gitpagedocs/docs",
+		"filePrefix": "ai-generated",
+		"contextPrompt": "Você é um redator técnico sênior..."
+	}
+}
+```
+
+For Ollama, use `baseUrl` instead of `apiKey`.
+
+### Interactive fallback
+
+If a directory is not found, CLI offers fallback choices:
+
+- fix paths and retry
+- skip missing paths and continue
+- abort safely

package/ai/application/ai-command.ts

@@ -0,0 +1,24 @@
+/**
+ * @file ai-command.ts
+ * @description Application service for running AI commands. Decoupled from concrete LLMs.
+ */
+import { ILLMProvider } from '../core/ports/illm-provider';
+
+export class AiCommandService {
+    constructor(private readonly provider: ILLMProvider) { }
+
+    /**
+     * Executes the AI Documentation Generation for a specific content
+     */
+    async runGeneration(content: string, contextPrompt?: string): Promise<string> {
+        return await this.provider.generateDocumentation(content, contextPrompt);
+    }
+
+    /**
+     * Executes a CLI chat prompt
+     */
+    async runChat(prompt: string): Promise<string> {
+        const messages = [{ role: 'user' as const, content: prompt }];
+        return await this.provider.chat(messages);
+    }
+}

package/ai/application/ai-provider-factory.ts

@@ -0,0 +1,22 @@
+import type { AiProviderId } from "../config";
+import type { ILLMProvider } from "../core/ports/illm-provider";
+import { ToolsLlmProvider } from "../infrastructure/llm/tools-llm-provider";
+
+/**
+ * Creates the CLI LLM provider. Backed by the shared @gitpagedocs/tools AI core
+ * (one registry-driven implementation for every provider) — no per-provider
+ * switch. The legacy provider id (openai/claude/gemini/ollama) is mapped to the
+ * catalog inside ToolsLlmProvider.
+ */
+export function createAiProvider(input: {
+  provider: AiProviderId;
+  model: string;
+  apiKey?: string;
+  baseUrl?: string;
+}): ILLMProvider {
+  return new ToolsLlmProvider(input.provider, {
+    model: input.model,
+    apiKey: input.apiKey,
+    baseUrl: input.baseUrl,
+  });
+}

package/ai/application/docs-pattern.ts

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

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

@@ -0,0 +1,69 @@
+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";
+import type { AiCliConfig } from "../core/models/ai-cli-config";
+
+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 = resolveProviderId(input.providerOverride, stored, env);
+  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 };
+}
+
+/** Explicit override > stored config > first provider with an env key > openai. */
+function resolveProviderId(
+  override: string | undefined,
+  stored: AiCliConfig | null,
+  env: Readonly<Record<string, string | undefined>>,
+): AiProviderId {
+  if (override) return legacyProviderToCatalogId(override);
+  if (stored) return legacyProviderToCatalogId(stored.ai.provider);
+  return firstProviderFromEnv(env) ?? "openai";
+}
+
+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/application/run-ai-cli-command.ts

@@ -0,0 +1,167 @@
+import { AiCommandService } from "./ai-command";
+import { createAiProvider } from "./ai-provider-factory";
+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 { promptMissingDirectories, runAiInteractivePrompt } from "../presentation/ai-prompts";
+import { GITPAGEDOCS_DOC_SYSTEM_PROMPT } from "../config";
+import { parseAiPages, type AiDocPage } from "./docs-pattern";
+import { writeVersionDocs } from "../infrastructure/version-docs-writer";
+// @ts-expect-error .mjs runtime module is type-less in this package.
+import { DOC_VERSIONS } from "../../contracts/doc-versions.mjs";
+
+const LANGUAGE_TO_LABEL: Record<string, string> = {
+  pt: "Portuguese",
+  en: "English",
+  es: "Español",
+};
+
+function aggregateFilesPayload(files: FilePayload[]): string {
+  return files
+    .map((file) => `\n\n--- FILE: ${file.filePath} ---\n\n${file.content}`)
+    .join("");
+}
+
+function buildLanguagePrompt(basePrompt: string, language: "pt" | "en" | "es"): string {
+  const languageLabel = LANGUAGE_TO_LABEL[language] ?? language;
+  const authorGuidance = basePrompt?.trim() ? `Additional author guidance:\n${basePrompt.trim()}\n\n` : "";
+  return (
+    `${GITPAGEDOCS_DOC_SYSTEM_PROMPT}\n\n` +
+    authorGuidance +
+    `Output language: write every page Title and body 100% in ${languageLabel}. ` +
+    `Keep each page slug lowercase-kebab and in English so the languages line up.`
+  );
+}
+
+async function collectFilesWithInteractiveFallback(
+  fileSystem: FileSystemAdapter,
+  initialPaths: string[],
+): Promise<{ files: FilePayload[]; scanned: string[]; skipped: string[] }> {
+  let queue = [...initialPaths];
+  let scanned: string[] = [];
+  let skipped: string[] = [];
+  const files: FilePayload[] = [];
+
+  while (queue.length > 0) {
+    const { existing, missing } = fileSystem.splitExistingDirectories(queue);
+    scanned = [...scanned, ...existing];
+
+    for (const directory of existing) {
+      const directoryFiles = await fileSystem.readDirectoryRecursively(directory);
+      files.push(...directoryFiles);
+    }
+
+    if (!missing.length) break;
+
+    const fallback = await promptMissingDirectories(missing);
+    if (fallback.abort) {
+      skipped = [...skipped, ...missing];
+      break;
+    }
+
+    if (!fallback.replacementPaths.length) {
+      skipped = [...skipped, ...missing];
+      break;
+    }
+
+    queue = fallback.replacementPaths;
+  }
+
+  return {
+    files,
+    scanned,
+    skipped,
+  };
+}
+
+/** Factory seam so tests can inject a deterministic provider (DIP). */
+export type AiProviderFactory = typeof createAiProvider;
+
+export async function executeAiRunPlan(
+  plan: AiCliRunPlan,
+  cwd: string,
+  createProvider: AiProviderFactory = createAiProvider,
+): Promise<AiCliRunSummary> {
+  const provider = createProvider({
+    provider: plan.config.ai.provider,
+    model: plan.config.ai.model,
+    apiKey: plan.config.ai.apiKey,
+    baseUrl: plan.config.ai.baseUrl,
+  });
+
+  const aiService = new AiCommandService(provider);
+  const fileSystem = new FileSystemAdapter(cwd);
+
+  const { files, scanned, skipped } = await collectFilesWithInteractiveFallback(
+    fileSystem,
+    plan.config.ai.paths,
+  );
+
+  if (!files.length) {
+    return {
+      scannedDirectories: scanned,
+      skippedDirectories: skipped,
+      scannedFilesCount: 0,
+      outputs: [],
+    };
+  }
+
+  const payload = aggregateFilesPayload(files);
+  const pagesByLang: Partial<Record<"pt" | "en" | "es", AiDocPage[]>> = {};
+
+  for (const language of plan.config.ai.languages) {
+    const prompt = buildLanguagePrompt(plan.config.ai.contextPrompt, language);
+    const markdown = await aiService.runGeneration(payload, prompt);
+    pagesByLang[language] = parseAiPages(markdown);
+  }
+
+  // Wire the AI pages into the latest documentation version (gitpagedocs pattern).
+  const versionId = DOC_VERSIONS[DOC_VERSIONS.length - 1] as string;
+  const result = await writeVersionDocs({ cwd, versionId, pagesByLang });
+
+  return {
+    scannedDirectories: scanned,
+    skippedDirectories: skipped,
+    scannedFilesCount: files.length,
+    outputs: result.files,
+    pages: result.slugs,
+  };
+}
+
+export async function runAiCliCommand(options: {
+  cwd: string;
+  onInfo?: (message: string) => void;
+  /** Provided by the composition root to scaffold the base gitpagedocs/ tree
+   * (so the version config.json exists before AI pages are wired into it). */
+  onScaffold?: () => Promise<void>;
+}): Promise<{ summary: AiCliRunSummary; runConfigScaffold: boolean }> {
+  const logInfo = options.onInfo ?? (() => undefined);
+  const configRepo = new AiConfigFileRepository({
+    cwd: options.cwd,
+    onMigrate: (fromPath, toPath) =>
+      logInfo(`[gitpagedocs:ai] Moved configuration from ${fromPath} to ${toPath} (secure user config directory).`),
+  });
+
+  const existingConfig = await configRepo.read();
+  const plan = await runAiInteractivePrompt(existingConfig);
+
+  if (plan.saveConfig) {
+    await configRepo.write(plan.config);
+    logInfo(`[gitpagedocs:ai] Configuration saved to ${configRepo.getConfigPath()}`);
+  }
+
+  // Build the base gitpagedocs structure BEFORE generation so the version
+  // config.json exists and the AI pages can be wired into it.
+  if (plan.runConfigScaffold && options.onScaffold) {
+    logInfo("[gitpagedocs] Generating base gitpagedocs structure...");
+    await options.onScaffold();
+  }
+
+  const summary = await executeAiRunPlan(plan, options.cwd);
+  return {
+    summary,
+    runConfigScaffold: plan.runConfigScaffold,
+  };
+}

package/ai/config.ts

@@ -0,0 +1,50 @@
+/**
+ * @file config.ts
+ * @description Provider constants for the AI CLI. Co-located in cli/ so the
+ * published `gitpagedocs` package does not reach into the frontend app. The
+ * browser keeps its own copy at frontend/src/shared/config/ai-config.ts.
+ */
+
+/** Legacy 4-provider id used by the interactive CLI (mapped to the 14-provider
+ * catalog in @gitpagedocs/tools via legacyProviderToCatalogId). */
+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',
+  ollama: 'llama3',
+};
+
+export const DEFAULT_AI_DOC_PROMPT =
+  'You are a senior tech writer. Describe the provided code.';
+
+/**
+ * System prompt that teaches the model what gitpagedocs is and forces it to
+ * return documentation in the gitpagedocs pattern: a sequence of pages, each
+ * introduced by a machine-parseable delimiter line so the CLI can split the
+ * response into individual versioned markdown pages and wire them into the
+ * viewer's config.json (routes-md + menus-header-md).
+ */
+export const GITPAGEDOCS_DOC_SYSTEM_PROMPT = [
+  'You are the documentation engine for "gitpagedocs", a generator of multilingual,',
+  'versioned static documentation sites. gitpagedocs renders markdown pages from',
+  'gitpagedocs/docs/versions/<version>/<lang>/<page>.md and wires them into a viewer',
+  'through a config.json contract (routes + header menus). Your job is to analyze the',
+  'provided source code and produce clean, professional documentation that fits this',
+  'pattern so it can be dropped straight into a gitpagedocs site.',
+  '',
+  'STRICT OUTPUT FORMAT — return ONLY a sequence of pages. Begin every page with a',
+  'delimiter line on its own, exactly:',
+  '=== PAGE: <slug> | <Title> ===',
+  'followed by the page body in GitHub-flavored markdown. Rules:',
+  '- Produce 4 to 8 cohesive pages. Suggested slugs: overview, getting-started,',
+  '  architecture, configuration, usage, deployment (adapt to the project).',
+  '- <slug> MUST be lowercase-kebab-case and in ENGLISH, and identical across every',
+  '  language run, so the languages line up (only the Title and body are translated).',
+  '- Do NOT wrap the whole answer in a code fence. Do NOT add any preamble or epilogue',
+  '  outside the page blocks. The first line of your reply MUST be a "=== PAGE:" line.',
+  '- Base everything strictly on the analyzed files; do not invent features.',
+].join('\n');
+
+export const OLLAMA_DEFAULT_BASE_URL = 'http://localhost:11434';

package/ai/core/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/ai/core/models/ai-cli-config.ts

@@ -0,0 +1,33 @@
+import type { AiProviderId } from "../../config";
+
+export const AI_CLI_CONFIG_FILENAME = ".gitpagedocsconfig";
+
+export interface AiCliConfig {
+  version: 1;
+  ai: {
+    provider: AiProviderId;
+    model: string;
+    apiKey?: string;
+    baseUrl?: string;
+    paths: string[];
+    languages: Array<"pt" | "en" | "es">;
+    outputDir: string;
+    filePrefix: string;
+    contextPrompt: string;
+  };
+}
+
+export interface AiCliRunPlan {
+  config: AiCliConfig;
+  saveConfig: boolean;
+  runConfigScaffold: boolean;
+}
+
+export interface AiCliRunSummary {
+  scannedDirectories: string[];
+  skippedDirectories: string[];
+  scannedFilesCount: number;
+  outputs: string[];
+  /** Slugs of the gitpagedocs pages wired into the version config (if any). */
+  pages?: string[];
+}