@dominikcz/greg 0.9.27

package/src/lib/MarkdownDocs/ai/adapters/openaiAdapter.js

@@ -0,0 +1,92 @@
+export class OpenAiAdapter {
+	constructor(options = {}) {
+		this.name = 'openai';
+		const key = options.apiKey ?? process.env.GREG_OPENAI_API_KEY ?? '';
+		if (!key) {
+			throw new Error(
+				'OpenAiAdapter: no API key provided. ' +
+				'Set GREG_OPENAI_API_KEY env variable or pass apiKey in options.',
+			);
+		}
+		this.apiKey = key;
+		this.baseUrl = (options.baseUrl ?? 'https://api.openai.com/v1').replace(/\/$/, '');
+		this.model = options.model ?? 'gpt-4o-mini';
+		this.embeddingModel = options.embeddingModel ?? 'text-embedding-3-small';
+		this.timeout = options.timeout ?? 60000;
+	}
+
+	get headers() {
+		return {
+			'Content-Type': 'application/json',
+			Authorization: `Bearer ${this.apiKey}`,
+		};
+	}
+
+	async chat(messages, options) {
+		const body = JSON.stringify({
+			model: options?.model ?? this.model,
+			messages,
+			temperature: options?.temperature ?? 0.3,
+			...(options?.maxTokens ? { max_tokens: options.maxTokens } : {}),
+		});
+
+		const controller = new AbortController();
+		const timer = setTimeout(() => controller.abort(), this.timeout);
+		let response;
+		try {
+			response = await fetch(`${this.baseUrl}/chat/completions`, {
+				method: 'POST',
+				headers: this.headers,
+				body,
+				signal: controller.signal,
+			});
+		} finally {
+			clearTimeout(timer);
+		}
+
+		if (!response.ok) {
+			const text = await response.text().catch(() => '');
+			throw new Error(`OpenAI chat error ${response.status}: ${text}`);
+		}
+
+		const data = await response.json();
+		if (data.error) throw new Error(`OpenAI error: ${data.error.message}`);
+		return data.choices?.[0]?.message?.content ?? '';
+	}
+
+	async embed(texts) {
+		const response = await fetch(`${this.baseUrl}/embeddings`, {
+			method: 'POST',
+			headers: this.headers,
+			body: JSON.stringify({
+				model: this.embeddingModel,
+				input: texts,
+				encoding_format: 'float',
+			}),
+		});
+
+		if (!response.ok) {
+			const err = await response.text().catch(() => '');
+			throw new Error(`OpenAI embed error ${response.status}: ${err}`);
+		}
+
+		const data = await response.json();
+		if (data.error) throw new Error(`OpenAI embed error: ${data.error.message}`);
+		const sorted = (data.data ?? []).sort((a, b) => a.index - b.index);
+		return sorted.map(d => d.embedding);
+	}
+
+	async isAvailable() {
+		try {
+			const controller = new AbortController();
+			setTimeout(() => controller.abort(), 5000);
+			const response = await fetch(`${this.baseUrl}/models`, {
+				headers: this.headers,
+				signal: controller.signal,
+			});
+			return response.ok;
+		} catch {
+			return false;
+		}
+	}
+}

package/src/lib/MarkdownDocs/ai/adapters/openaiAdapter.ts

@@ -0,0 +1,137 @@
+import type { AiProvider } from '../aiProvider.js';
+import type { AiProviderOptions, ChatMessage } from '../types.js';
+
+export type OpenAiAdapterOptions = {
+	/**
+	 * API key.
+	 * If omitted, read from the GREG_OPENAI_API_KEY environment variable.
+	 * Never store the key in greg.config.js — use the env variable.
+	 */
+	apiKey?: string;
+	/** Chat model to use. Default: gpt-4o-mini */
+	model?: string;
+	/** Embedding model. Default: text-embedding-3-small */
+	embeddingModel?: string;
+	/**
+	 * API base URL — supports OpenAI-compatible endpoints
+	 * (Groq, Together AI, local llama.cpp server, Mistral API, …).
+	 * Default: https://api.openai.com/v1
+	 */
+	baseUrl?: string;
+	/** Request timeout in milliseconds. Default: 60_000 */
+	timeout?: number;
+};
+
+/**
+ * Adapter for OpenAI and OpenAI-compatible REST APIs.
+ *
+ * Set the API key via the GREG_OPENAI_API_KEY environment variable
+ * or pass it explicitly via options.apiKey.
+ */
+export class OpenAiAdapter implements AiProvider {
+	readonly name = 'openai';
+	private readonly baseUrl: string;
+	private readonly model: string;
+	private readonly embeddingModel: string;
+	private readonly timeout: number;
+	private readonly apiKey: string;
+
+	constructor(options: OpenAiAdapterOptions = {}) {
+		const key = options.apiKey ?? process.env.GREG_OPENAI_API_KEY ?? '';
+		if (!key) {
+			throw new Error(
+				'OpenAiAdapter: no API key provided. ' +
+				'Set GREG_OPENAI_API_KEY env variable or pass apiKey in options.',
+			);
+		}
+		this.apiKey = key;
+		this.baseUrl = (options.baseUrl ?? 'https://api.openai.com/v1').replace(/\/$/, '');
+		this.model = options.model ?? 'gpt-4o-mini';
+		this.embeddingModel = options.embeddingModel ?? 'text-embedding-3-small';
+		this.timeout = options.timeout ?? 60_000;
+	}
+
+	private get headers(): Record<string, string> {
+		return {
+			'Content-Type': 'application/json',
+			'Authorization': `Bearer ${this.apiKey}`,
+		};
+	}
+
+	async chat(messages: ChatMessage[], options?: AiProviderOptions): Promise<string> {
+		const body = JSON.stringify({
+			model: options?.model ?? this.model,
+			messages,
+			temperature: options?.temperature ?? 0.3,
+			...(options?.maxTokens ? { max_tokens: options.maxTokens } : {}),
+		});
+
+		const controller = new AbortController();
+		const timer = setTimeout(() => controller.abort(), this.timeout);
+		let response: Response;
+		try {
+			response = await fetch(`${this.baseUrl}/chat/completions`, {
+				method: 'POST',
+				headers: this.headers,
+				body,
+				signal: controller.signal,
+			});
+		} finally {
+			clearTimeout(timer);
+		}
+
+		if (!response.ok) {
+			const text = await response.text().catch(() => '');
+			throw new Error(`OpenAI chat error ${response.status}: ${text}`);
+		}
+
+		const data = await response.json() as {
+			choices?: Array<{ message?: { content?: string } }>;
+			error?: { message?: string };
+		};
+
+		if (data.error) throw new Error(`OpenAI error: ${data.error.message}`);
+		return data.choices?.[0]?.message?.content ?? '';
+	}
+
+	async embed(texts: string[]): Promise<number[][]> {
+		const response = await fetch(`${this.baseUrl}/embeddings`, {
+			method: 'POST',
+			headers: this.headers,
+			body: JSON.stringify({
+				model: this.embeddingModel,
+				input: texts,
+				encoding_format: 'float',
+			}),
+		});
+
+		if (!response.ok) {
+			const err = await response.text().catch(() => '');
+			throw new Error(`OpenAI embed error ${response.status}: ${err}`);
+		}
+
+		const data = await response.json() as {
+			data?: Array<{ embedding: number[]; index: number }>;
+			error?: { message?: string };
+		};
+
+		if (data.error) throw new Error(`OpenAI embed error: ${data.error.message}`);
+		// Sort by index to guarantee input order is preserved
+		const sorted = (data.data ?? []).sort((a, b) => a.index - b.index);
+		return sorted.map(d => d.embedding);
+	}
+
+	async isAvailable(): Promise<boolean> {
+		try {
+			const controller = new AbortController();
+			setTimeout(() => controller.abort(), 5_000);
+			const response = await fetch(`${this.baseUrl}/models`, {
+				headers: this.headers,
+				signal: controller.signal,
+			});
+			return response.ok;
+		} catch {
+			return false;
+		}
+	}
+}

package/src/lib/MarkdownDocs/ai/aiProvider.ts

@@ -0,0 +1,31 @@
+import type { ChatMessage, AiProviderOptions } from './types.js';
+
+/**
+ * Adapter interface for LLM providers.
+ *
+ * Implement this interface to add support for a new LLM backend (local or cloud).
+ * See: OllamaAdapter, OpenAiAdapter, CustomAdapter for reference implementations.
+ */
+export interface AiProvider {
+	/** Human-readable provider name (used in log output). */
+	readonly name: string;
+
+	/**
+	 * Send a conversation and return the assistant's reply as a plain string.
+	 * The implementor is responsible for all network / inference calls.
+	 */
+	chat(messages: ChatMessage[], options?: AiProviderOptions): Promise<string>;
+
+	/**
+	 * Generate dense embeddings for an array of text strings.
+	 * Returns null-equivalent (empty arrays) or throws if unsupported.
+	 * Optional — used only by vector-capable stores.
+	 */
+	embed?(texts: string[]): Promise<number[][]>;
+
+	/**
+	 * Quick availability probe — should resolve without throwing.
+	 * Returns false if the provider/service is unreachable.
+	 */
+	isAvailable(): Promise<boolean>;
+}

package/src/lib/MarkdownDocs/ai/characters.js

@@ -0,0 +1,52 @@
+export const aiCharacters = [
+	{
+		id: 'professional',
+		name: 'Professional',
+		icon: '👔',
+		description: 'Precise, formal, technical answers',
+		systemPrompt: `You are a professional documentation assistant. Answer concisely, precisely and formally. Use appropriate technical terminology. Structure longer answers with headers or bullet points for readability. Always cite sources from the documentation context. Always respond in the same language as the user's question.`,
+	},
+	{
+		id: 'friendly',
+		name: 'Friendly',
+		icon: '😊',
+		description: 'Warm, approachable explanations',
+		systemPrompt: `You are a friendly and enthusiastic documentation helper! Explain things in simple, everyday language. Use relatable analogies, concrete examples, and a warm conversational tone. Encourage the reader to explore. Always link back to the relevant documentation sections so they can dig deeper. Always respond in the same language as the user's question.`,
+	},
+	{
+		id: 'pirate',
+		name: 'Pirate',
+		icon: '🏴‍☠️',
+		description: 'Arr! Knowledge on the high seas!',
+		systemPrompt: `Ye be a seasoned pirate-developer who sails the seas of code and documentation! Answer in pirate style — use pirate-flavoured exclamations and expressions naturally adapted to the language of the user's question (if they write in Polish, use Polish pirate flair; if English, use "arr", "ye", "ahoy"). Keep every piece of technical content 100% accurate. Call the documentation yer "treasure map" and call sections "buried treasure". Always mark yer sources like proper treasure coordinates so the crew can find 'em. Always respond in the same language as the user's question.`,
+	},
+	{
+		id: 'sensei',
+		name: 'Sensei',
+		icon: '🥋',
+		description: 'Patient teacher, step-by-step guidance',
+		systemPrompt: `You are a wise and patient sensei. Guide the student step by step through concepts. Explain not just "how" but "why". Occasionally ask a gentle question to provoke independent thinking. Praise curiosity and effort. The documentation is your textbook — always reference it so the student can study further. Always respond in the same language as the user's question.`,
+	},
+	{
+		id: 'concise',
+		name: 'Concise',
+		icon: '✂️',
+		description: 'Maximum density, minimum words',
+		systemPrompt: `Answer in maximum 4 sentences or 5 bullet points. No filler words, no introductions, no conclusions. Facts and links only. Every answer must include at least one source citation. Always respond in the same language as the user's question.`,
+	},
+];
+
+export function resolveCharacters(enabledIds, customCharacters) {
+	const all = [...aiCharacters];
+	for (const custom of customCharacters ?? []) {
+		const idx = all.findIndex(c => c.id === custom.id);
+		if (idx >= 0) {
+			all[idx] = custom;
+		} else {
+			all.push(custom);
+		}
+	}
+
+	if (!enabledIds || enabledIds.length === 0) return all;
+	return all.filter(c => enabledIds.includes(c.id));
+}

package/src/lib/MarkdownDocs/ai/characters.ts

@@ -0,0 +1,69 @@
+import type { AiCharacter } from './types.js';
+
+/**
+ * Built-in AI characters (personas).
+ * Each character defines a distinct response style via its system prompt.
+ * Users can add custom characters or override defaults by matching the `id`.
+ */
+export const aiCharacters: AiCharacter[] = [
+	{
+		id: 'professional',
+		name: 'Professional',
+		icon: '👔',
+		description: 'Precise, formal, technical answers',
+		systemPrompt: `You are a professional documentation assistant. Answer concisely, precisely and formally. Use appropriate technical terminology. Structure longer answers with headers or bullet points for readability. Always cite sources from the documentation context. Always respond in the same language as the user's question.`,
+	},
+	{
+		id: 'friendly',
+		name: 'Friendly',
+		icon: '😊',
+		description: 'Warm, approachable explanations',
+		systemPrompt: `You are a friendly and enthusiastic documentation helper! Explain things in simple, everyday language. Use relatable analogies, concrete examples, and a warm conversational tone. Encourage the reader to explore. Always link back to the relevant documentation sections so they can dig deeper. Always respond in the same language as the user's question.`,
+	},
+	{
+		id: 'pirate',
+		name: 'Pirate',
+		icon: '🏴‍☠️',
+		description: "Arr! Knowledge on the high seas!",
+		systemPrompt: `Ye be a seasoned pirate-developer who sails the seas of code and documentation! Answer in pirate style — use pirate-flavoured exclamations and expressions naturally adapted to the language of the user's question (if they write in Polish, use Polish pirate flair; if English, use "arr", "ye", "ahoy"). Keep every piece of technical content 100% accurate. Call the documentation yer "treasure map" and call sections "buried treasure". Always mark yer sources like proper treasure coordinates so the crew can find 'em. Always respond in the same language as the user's question.`,
+	},
+	{
+		id: 'sensei',
+		name: 'Sensei',
+		icon: '🥋',
+		description: 'Patient teacher, step-by-step guidance',
+		systemPrompt: `You are a wise and patient sensei. Guide the student step by step through concepts. Explain not just "how" but "why". Occasionally ask a gentle question to provoke independent thinking. Praise curiosity and effort. The documentation is your textbook — always reference it so the student can study further. Always respond in the same language as the user's question.`,
+	},
+	{
+		id: 'concise',
+		name: 'Concise',
+		icon: '✂️',
+		description: 'Maximum density, minimum words',
+		systemPrompt: `Answer in maximum 4 sentences or 5 bullet points. No filler words, no introductions, no conclusions. Facts and links only. Every answer must include at least one source citation. Always respond in the same language as the user's question.`,
+	},
+];
+
+/**
+ * Merge default characters with user-supplied custom characters,
+ * then filter to only the requested IDs.
+ *
+ * Custom characters with the same `id` as a default override the default.
+ */
+export function resolveCharacters(
+	enabledIds?: string[],
+	customCharacters?: AiCharacter[],
+): AiCharacter[] {
+	// Merge: defaults first, then custom (custom overrides by matching id)
+	const all = [...aiCharacters];
+	for (const custom of customCharacters ?? []) {
+		const idx = all.findIndex(c => c.id === custom.id);
+		if (idx >= 0) {
+			all[idx] = custom; // override
+		} else {
+			all.push(custom); // new character
+		}
+	}
+
+	if (!enabledIds || enabledIds.length === 0) return all;
+	return all.filter(c => enabledIds.includes(c.id));
+}

package/src/lib/MarkdownDocs/ai/chunkStore.ts

@@ -0,0 +1,25 @@
+import type { DocChunk, RetrievedChunk } from './types.js';
+
+/**
+ * Backend interface for storing and searching documentation chunks.
+ *
+ * Implement this interface to plug in a different storage strategy:
+ *   - MemoryStore     — in-memory BM25 (default, zero deps)
+ *   - Custom          — Qdrant, Chroma, SQLite+vec, Pinecone, …
+ */
+export interface ChunkStore {
+	/**
+	 * (Re-)build the store from a list of DocChunks.
+	 * Replaces all previously indexed content.
+	 */
+	index(chunks: DocChunk[]): Promise<void>;
+
+	/**
+	 * Search for the most relevant chunks matching `query`.
+	 * Returns at most `limit` results ordered by descending relevance.
+	 */
+	search(query: string, limit?: number): Promise<RetrievedChunk[]>;
+
+	/** Total number of indexed chunks. */
+	size(): number;
+}

package/src/lib/MarkdownDocs/ai/chunker.js

@@ -0,0 +1,85 @@
+/**
+ * Convert a flat search index (SearchEntry[]) into DocChunks for RAG.
+ */
+export function buildChunks(index, options = {}) {
+	const maxSize = options.maxChunkSize ?? 1800;
+	const overlap = Math.min(options.overlap ?? 120, Math.floor(maxSize / 4));
+	const chunks = [];
+
+	for (const entry of index) {
+		for (const section of entry.sections) {
+			const content = section.content.trim();
+
+			if (!content) {
+				if (section.heading) {
+					chunks.push({
+						pageId: entry.id,
+						pageTitle: entry.title,
+						sectionHeading: section.heading,
+						sectionAnchor: section.anchor,
+						content: section.heading,
+					});
+				}
+				continue;
+			}
+
+			if (content.length <= maxSize) {
+				chunks.push({
+					pageId: entry.id,
+					pageTitle: entry.title,
+					sectionHeading: section.heading,
+					sectionAnchor: section.anchor,
+					content,
+				});
+				continue;
+			}
+
+			const subChunks = splitText(content, maxSize, overlap);
+			for (let i = 0; i < subChunks.length; i++) {
+				chunks.push({
+					pageId: entry.id,
+					pageTitle: entry.title,
+					sectionHeading: subChunks.length > 1
+						? `${section.heading} (${i + 1}/${subChunks.length})`
+						: section.heading,
+					sectionAnchor: section.anchor,
+					content: subChunks[i],
+				});
+			}
+		}
+	}
+
+	return chunks;
+}
+
+function splitText(text, maxSize, overlap) {
+	const chunks = [];
+	const sentences = text.split(/(?<=[.!?])\s+/);
+	let current = '';
+
+	for (const sentence of sentences) {
+		if (sentence.length > maxSize) {
+			if (current) {
+				chunks.push(current.trim());
+				current = '';
+			}
+			for (let i = 0; i < sentence.length; i += maxSize - overlap) {
+				chunks.push(sentence.slice(i, i + maxSize));
+			}
+			continue;
+		}
+
+		if (current.length + sentence.length + 1 > maxSize && current.length > 0) {
+			chunks.push(current.trim());
+			current = current.slice(Math.max(0, current.length - overlap)) + ' ' + sentence;
+		} else {
+			current = current ? current + ' ' + sentence : sentence;
+		}
+	}
+
+	if (current.trim()) {
+		chunks.push(current.trim());
+	}
+
+	return chunks.length > 0 ? chunks : [text.slice(0, maxSize)];
+}

package/src/lib/MarkdownDocs/ai/chunker.ts

@@ -0,0 +1,135 @@
+import type { DocChunk } from './types.js';
+
+// Mirror of the SearchEntry type from searchIndexBuilder.js
+// (kept local to avoid creating a circular dependency)
+type SearchSection = {
+	heading: string;
+	anchor: string;
+	content: string;
+};
+
+type SearchEntry = {
+	id: string;
+	title: string;
+	sections: SearchSection[];
+};
+
+export type ChunkerOptions = {
+	/**
+	 * Approximate maximum characters per chunk.
+	 * ~4 chars ≈ 1 token, so 1800 chars ≈ 450 tokens (safe for most models).
+	 * Default: 1800
+	 */
+	maxChunkSize?: number;
+	/**
+	 * Character overlap between consecutive chunks from the same section.
+	 * Helps avoid losing context at chunk boundaries.
+	 * Default: 120
+	 */
+	overlap?: number;
+};
+
+/**
+ * Convert a flat search index (SearchEntry[]) into DocChunks for RAG.
+ *
+ * Strategy:
+ * - Each section of a page maps to at least one chunk.
+ * - Sections whose content fits within `maxChunkSize` become a single chunk.
+ * - Larger sections are split into overlapping sub-chunks at sentence boundaries.
+ * - Heading-only sections (no body content) still produce a chunk so the LLM
+ *   can reference that section's existence.
+ */
+export function buildChunks(
+	index: SearchEntry[],
+	options: ChunkerOptions = {},
+): DocChunk[] {
+	const maxSize = options.maxChunkSize ?? 1800;
+	const overlap = Math.min(options.overlap ?? 120, Math.floor(maxSize / 4));
+	const chunks: DocChunk[] = [];
+
+	for (const entry of index) {
+		for (const section of entry.sections) {
+			const content = section.content.trim();
+
+			if (!content) {
+				// Heading-only entry — useful so AI knows the section exists
+				if (section.heading) {
+					chunks.push({
+						pageId: entry.id,
+						pageTitle: entry.title,
+						sectionHeading: section.heading,
+						sectionAnchor: section.anchor,
+						content: section.heading,
+					});
+				}
+				continue;
+			}
+
+			if (content.length <= maxSize) {
+				chunks.push({
+					pageId: entry.id,
+					pageTitle: entry.title,
+					sectionHeading: section.heading,
+					sectionAnchor: section.anchor,
+					content,
+				});
+				continue;
+			}
+
+			// Content too long — split into overlapping sub-chunks
+			const subChunks = splitText(content, maxSize, overlap);
+			for (let i = 0; i < subChunks.length; i++) {
+				chunks.push({
+					pageId: entry.id,
+					pageTitle: entry.title,
+					sectionHeading: subChunks.length > 1
+						? `${section.heading} (${i + 1}/${subChunks.length})`
+						: section.heading,
+					sectionAnchor: section.anchor,
+					content: subChunks[i],
+				});
+			}
+		}
+	}
+
+	return chunks;
+}
+
+/**
+ * Split text into overlapping chunks, preferring sentence boundaries.
+ * Falls back to character-level splitting when no sentence boundary is found.
+ */
+function splitText(text: string, maxSize: number, overlap: number): string[] {
+	const chunks: string[] = [];
+	// Split on sentence-ending punctuation followed by whitespace
+	const sentences = text.split(/(?<=[.!?])\s+/);
+	let current = '';
+
+	for (const sentence of sentences) {
+		if (sentence.length > maxSize) {
+			// Single sentence exceeds maxSize — hard split it
+			if (current) {
+				chunks.push(current.trim());
+				current = '';
+			}
+			for (let i = 0; i < sentence.length; i += maxSize - overlap) {
+				chunks.push(sentence.slice(i, i + maxSize));
+			}
+			continue;
+		}
+
+		if (current.length + sentence.length + 1 > maxSize && current.length > 0) {
+			chunks.push(current.trim());
+			// Carry the tail of current chunk forward for overlap
+			current = current.slice(Math.max(0, current.length - overlap)) + ' ' + sentence;
+		} else {
+			current = current ? current + ' ' + sentence : sentence;
+		}
+	}
+
+	if (current.trim()) {
+		chunks.push(current.trim());
+	}
+
+	return chunks.length > 0 ? chunks : [text.slice(0, maxSize)];
+}

package/src/lib/MarkdownDocs/ai/docLinker.js

@@ -0,0 +1,26 @@
+export function extractSources(chunks, limit = 6) {
+	const seen = new Set();
+	const sources = [];
+
+	for (const chunk of chunks) {
+		const key = `${chunk.pageId}#${chunk.sectionAnchor}`;
+		if (seen.has(key)) continue;
+		seen.add(key);
+
+		sources.push({
+			pageId: chunk.pageId,
+			pageTitle: chunk.pageTitle,
+			sectionHeading: chunk.sectionHeading,
+			sectionAnchor: chunk.sectionAnchor,
+		});
+
+		if (sources.length >= limit) break;
+	}
+
+	return sources;
+}
+
+export function buildSourceUrl(source, baseUrl = '') {
+	const anchor = source.sectionAnchor ? `#${source.sectionAnchor}` : '';
+	return `${baseUrl}${source.pageId}${anchor}`;
+}

package/src/lib/MarkdownDocs/ai/docLinker.ts

@@ -0,0 +1,36 @@
+import type { AiSource, RetrievedChunk } from './types.js';
+
+/**
+ * Extract unique source citations from a list of retrieved chunks.
+ *
+ * Returns distinct (pageId, sectionAnchor) pairs — up to `limit` sources —
+ * ordered by chunk relevance score (highest first).
+ * These are rendered as the "Sources" list below the AI answer in the UI.
+ */
+export function extractSources(chunks: RetrievedChunk[], limit = 6): AiSource[] {
+	const seen = new Set<string>();
+	const sources: AiSource[] = [];
+
+	for (const chunk of chunks) {
+		const key = `${chunk.pageId}#${chunk.sectionAnchor}`;
+		if (seen.has(key)) continue;
+		seen.add(key);
+
+		sources.push({
+			pageId: chunk.pageId,
+			pageTitle: chunk.pageTitle,
+			sectionHeading: chunk.sectionHeading,
+			sectionAnchor: chunk.sectionAnchor,
+		});
+
+		if (sources.length >= limit) break;
+	}
+
+	return sources;
+}
+
+/** Build a complete URL for a source (page path + optional anchor). */
+export function buildSourceUrl(source: AiSource, baseUrl = ''): string {
+	const anchor = source.sectionAnchor ? `#${source.sectionAnchor}` : '';
+	return `${baseUrl}${source.pageId}${anchor}`;
+}