@gitpagedocs/cli 1.1.62 → 1.1.63

package/README.md

@@ -1,193 +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
+# @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

@@ -1,24 +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 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);
-    }
-}
+/**
+ * @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 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

@@ -1,22 +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,
-  });
-}
+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

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