@f5-sales-demo/xcsh 22.1.2 → 22.2.0

package/src/internal-urls/build-info.generated.ts

@@ -17,17 +17,17 @@ export interface BuildInfo {
 }
 
 export const BUILD_INFO: BuildInfo = {
-	"version": "22.1.2",
-	"commit": "65d611cfa87b2269f14410aab45331c1701ecf7d",
-	"shortCommit": "65d611c",
+	"version": "22.2.0",
+	"commit": "5d9f4f3ce9b3fc191846cfe6fa37d60afab62421",
+	"shortCommit": "5d9f4f3",
 	"branch": "main",
-	"tag": "v22.1.2",
-	"commitDate": "2026-09-27T23:52:20Z",
-	"buildDate": "2026-09-28T00:35:39.460Z",
+	"tag": "v22.2.0",
+	"commitDate": "2026-09-28T01:49:00Z",
+	"buildDate": "2026-09-28T02:25:11.763Z",
 	"dirty": true,
 	"prNumber": "",
 	"repoUrl": "https://github.com/f5-sales-demo/xcsh",
 	"repoSlug": "f5-sales-demo/xcsh",
-	"commitUrl": "https://github.com/f5-sales-demo/xcsh/commit/65d611cfa87b2269f14410aab45331c1701ecf7d",
-	"releaseUrl": "https://github.com/f5-sales-demo/xcsh/releases/tag/v22.1.2"
+	"commitUrl": "https://github.com/f5-sales-demo/xcsh/commit/5d9f4f3ce9b3fc191846cfe6fa37d60afab62421",
+	"releaseUrl": "https://github.com/f5-sales-demo/xcsh/releases/tag/v22.2.0"
 };

package/src/internal-urls/knowledge-classifier.ts

@@ -0,0 +1,209 @@
+export type KnowledgeRoute = "api" | "documentation" | "direct-uri" | "none";
+export type DocumentationKnowledgeSource = "docs-cloud-f5-com" | "my-f5-com";
+
+export interface KnowledgeClassifierResource {
+	readonly name: string;
+	readonly aliases: readonly string[];
+	readonly domain: string;
+	readonly categories: readonly string[];
+}
+
+export interface KnowledgeSearchPlan {
+	readonly intent: string;
+	readonly lex: readonly string[];
+	readonly vec: readonly string[];
+	readonly hyde: readonly string[];
+}
+
+export interface KnowledgeConstraints {
+	readonly domain?: string;
+	readonly source?: DocumentationKnowledgeSource;
+}
+
+export interface KnowledgeClassification {
+	readonly route: KnowledgeRoute;
+	readonly confidence: number;
+	readonly query: KnowledgeSearchPlan;
+	readonly constraints: KnowledgeConstraints;
+	readonly resource?: string;
+	readonly domain?: string;
+	readonly source?: DocumentationKnowledgeSource;
+	readonly documentPath?: string;
+	readonly directUri?: string;
+}
+
+export interface KnowledgeClassifierOptions {
+	readonly toolsEnabled: boolean;
+	readonly resources?: readonly KnowledgeClassifierResource[];
+	readonly documentationSource?: DocumentationKnowledgeSource;
+	readonly previous?: KnowledgeClassification | null;
+}
+
+const EMPTY_QUERY: KnowledgeSearchPlan = { intent: "", lex: [], vec: [], hyde: [] };
+const THIRD_PARTY_SCOPE = /\b(?:aws|amazon|azure|gcp|google cloud|kubernetes)\b/i;
+const F5_SCOPE = /\b(?:f5(?:\s+distributed\s+cloud)?|xc)\b/i;
+const ANAPHORIC = /\b(?:its|it|that|this|those|them|the same)\b/i;
+const API_METADATA =
+	/\b(?:api|endpoint|operation\s*id|api\s+path|http\s+method|method|payload|request\s+body|required\s+fields?|enum|allowed\s+values?|constraints?|limits?|maximum|max(?:imum)?|minimum|min(?:imum)?|how\s+many|create|creates|creating|get|gets|list|lists|update|updates|replace|replaces|delete|deletes|clone|import)\b/i;
+const DOCUMENTATION_INTENT =
+	/\b(?:documentation|docs?|guide|tutorial|how\s+(?:do|can|to)|configure|configuration|set\s*up|troubleshoot|procedure|instructions?)\b/i;
+const EXCLUDED_API_INTENT = /\b(?:pricing|price|quote|licen[cs]ing|sales)\b/i;
+const DIRECT_URI = /\bxcsh:\/\/(?:api-catalog|api-spec|documentation)\/[^\s)>\]}]*/i;
+
+function normalizePhrase(value: string): string {
+	return value
+		.toLocaleLowerCase("en-US")
+		.replace(/[_-]+/g, " ")
+		.replace(/[^a-z0-9]+/g, " ")
+		.trim()
+		.replace(/\s+/g, " ");
+}
+
+function action(value: string): { base?: string; gerund?: string } {
+	if (/\b(?:create|creates|creating)\b/i.test(value)) return { base: "create", gerund: "creating" };
+	if (/\b(?:configure|configuration|configuring)\b/i.test(value)) return { base: "configure", gerund: "configuring" };
+	if (/\b(?:set\s*up|setting\s*up)\b/i.test(value)) return { base: "set up", gerund: "setting up" };
+	if (/\b(?:get|gets|read|fetch)\b/i.test(value)) return { base: "get", gerund: "getting" };
+	if (/\b(?:list|lists|listing)\b/i.test(value)) return { base: "list", gerund: "listing" };
+	if (/\b(?:update|updates|updating)\b/i.test(value)) return { base: "update", gerund: "updating" };
+	if (/\b(?:replace|replaces|replacing)\b/i.test(value)) return { base: "replace", gerund: "replacing" };
+	if (/\b(?:delete|deletes|remove|removing)\b/i.test(value)) return { base: "delete", gerund: "deleting" };
+	if (/\bclone\b/i.test(value)) return { base: "clone", gerund: "cloning" };
+	if (/\bimport\b/i.test(value)) return { base: "import", gerund: "importing" };
+	return {};
+}
+
+function documentationSubject(prompt: string): string {
+	const normalized = normalizePhrase(prompt);
+	const withoutPreamble = normalized
+		.replace(/^(?:please )?(?:use|read|find|show me|show) /, "")
+		.replace(/^(?:the )?(?:official |pinned )?f5 (?:distributed cloud )?(?:documentation|docs?) (?:to |for )?/, "")
+		.replace(/^(?:the )?(?:official |pinned )?(?:documentation|docs?) (?:to |for )?/, "");
+	return (withoutPreamble || normalized)
+		.replace(/\b(?:a|an|the)\b/g, " ")
+		.replace(/\s+/g, " ")
+		.trim();
+}
+
+export function buildKnowledgeSearchPlan(route: "api" | "documentation", subject: string): KnowledgeSearchPlan {
+	const normalized = normalizePhrase(subject);
+	const verb = action(normalized);
+	if (route === "api") {
+		const resource = verb.base
+			? normalizePhrase(normalized.replace(new RegExp(`\\b${verb.base}\\b`), ""))
+			: normalized;
+		const lex = [...new Set([resource, verb.base ? `${verb.base} ${resource}` : resource].filter(Boolean))];
+		const phrase = verb.gerund ? `${verb.gerund} ${resource}` : resource;
+		return {
+			intent: `Find the authoritative F5 Distributed Cloud API operation for ${phrase}.`,
+			lex,
+			vec: [`${verb.base ? `${verb.base} ` : ""}${resource} F5 Distributed Cloud API`],
+			hyde: [
+				`An authoritative F5 Distributed Cloud API operation for ${phrase}, including method, path, operation ID, request fields, and constraints.`,
+			],
+		};
+	}
+	const phrase = verb.gerund ? normalized.replace(new RegExp(`^${verb.base}`), verb.gerund) : normalized;
+	return {
+		intent: `Find the authoritative F5 documentation page for ${phrase}.`,
+		lex: [normalized],
+		vec: [`${subject.trim()} F5 documentation`],
+		hyde: [
+			`An authoritative F5 documentation page explains how to ${subject.trim()} with prerequisites, ordered steps, verification, and limitations.`,
+		],
+	};
+}
+
+function none(): KnowledgeClassification {
+	return { route: "none", confidence: 0, query: EMPTY_QUERY, constraints: {} };
+}
+
+function direct(prompt: string): KnowledgeClassification | null {
+	const directUri = DIRECT_URI.exec(prompt)?.[0];
+	if (!directUri) return null;
+	try {
+		const parsed = new URL(directUri);
+		const constraints: KnowledgeConstraints = {};
+		if (parsed.hostname === "api-spec") {
+			const domain = parsed.pathname.split("/").filter(Boolean)[0];
+			if (domain) Object.assign(constraints, { domain });
+		}
+		if (parsed.hostname === "documentation") {
+			const source = parsed.pathname.split("/").filter(Boolean)[0];
+			if (source === "docs-cloud-f5-com" || source === "my-f5-com") Object.assign(constraints, { source });
+		}
+		return { route: "direct-uri", confidence: 1, directUri, constraints, query: EMPTY_QUERY };
+	} catch {
+		return null;
+	}
+}
+
+function selectResource(
+	prompt: string,
+	resources: readonly KnowledgeClassifierResource[],
+): KnowledgeClassifierResource | undefined {
+	const normalizedPrompt = ` ${normalizePhrase(prompt)} `;
+	return resources
+		.flatMap(resource =>
+			resource.aliases
+				.map(alias => normalizePhrase(alias))
+				.filter(alias => alias && normalizedPrompt.includes(` ${alias} `))
+				.map(alias => ({ resource, alias })),
+		)
+		.sort(
+			(left, right) =>
+				right.alias.length - left.alias.length ||
+				right.resource.categories.length - left.resource.categories.length ||
+				left.resource.name.localeCompare(right.resource.name) ||
+				left.resource.domain.localeCompare(right.resource.domain),
+		)[0]?.resource;
+}
+
+export function classifyKnowledgeRequest(prompt: string, options: KnowledgeClassifierOptions): KnowledgeClassification {
+	if (!options.toolsEnabled) return none();
+	const directResult = direct(prompt);
+	if (directResult) return directResult;
+
+	const resources = options.resources ?? [];
+	const selected = selectResource(prompt, resources);
+	const thirdPartyOnly = THIRD_PARTY_SCOPE.test(prompt) && !F5_SCOPE.test(prompt);
+	if (!thirdPartyOnly && !EXCLUDED_API_INTENT.test(prompt) && API_METADATA.test(prompt)) {
+		const contextual =
+			!selected && ANAPHORIC.test(prompt) && options.previous?.route === "api" ? options.previous : null;
+		const resource = selected?.name ?? contextual?.resource;
+		const domain = selected?.domain ?? contextual?.domain;
+		if (resource && domain) {
+			const alias = normalizePhrase(selected?.aliases[0] ?? contextual?.query.lex[0] ?? resource);
+			const verb = action(prompt).base;
+			const subject = verb ? `${verb} ${alias}` : alias;
+			return {
+				route: "api",
+				confidence: F5_SCOPE.test(prompt) || contextual ? 0.99 : 0.97,
+				resource,
+				domain,
+				constraints: { domain },
+				query: buildKnowledgeSearchPlan("api", subject),
+			};
+		}
+	}
+
+	const previousDocumentation = options.previous?.route === "documentation" ? options.previous : null;
+	if (
+		!thirdPartyOnly &&
+		(DOCUMENTATION_INTENT.test(prompt) || (ANAPHORIC.test(prompt) && previousDocumentation)) &&
+		(F5_SCOPE.test(prompt) || /\b(?:documentation|docs?)\b/i.test(prompt) || previousDocumentation)
+	) {
+		const source = options.documentationSource ?? previousDocumentation?.source;
+		const subject = documentationSubject(prompt);
+		return {
+			route: "documentation",
+			confidence: /\b(?:documentation|docs?)\b/i.test(prompt) ? 0.99 : 0.96,
+			source,
+			documentPath: previousDocumentation?.documentPath,
+			constraints: source ? { source } : {},
+			query: buildKnowledgeSearchPlan("documentation", subject),
+		};
+	}
+
+	return none();
+}

package/src/internal-urls/knowledge-search.ts

@@ -0,0 +1,90 @@
+import type { KnowledgeSearchPlan } from "./knowledge-classifier";
+
+export type KnowledgeSearchMode = "bm25" | "hybrid";
+export type KnowledgeSearchCorpus = "api" | "documentation";
+
+export interface KnowledgeSearchResult {
+	readonly displayPath: string;
+	readonly score: number;
+	readonly [key: string]: unknown;
+}
+
+export interface KnowledgeSearchStore<T extends KnowledgeSearchResult = KnowledgeSearchResult> {
+	search(options: Record<string, unknown>): Promise<readonly T[]>;
+	searchLex(query: string, options?: { limit?: number; collection?: string | string[] }): Promise<readonly T[]>;
+}
+
+export interface KnowledgeSearchOptions {
+	readonly mode: KnowledgeSearchMode;
+	readonly corpus: KnowledgeSearchCorpus;
+	readonly collections?: readonly string[];
+	readonly limit: number;
+	readonly candidateLimit?: number;
+	readonly rerank?: boolean;
+	readonly explain?: boolean;
+	readonly minScore?: number;
+}
+
+export const KNOWLEDGE_SCORE_THRESHOLDS = {
+	api: 0.2,
+	documentation: 0.25,
+} as const;
+
+function interleave<T extends KnowledgeSearchResult>(lists: readonly (readonly T[])[], limit: number): T[] {
+	const results: T[] = [];
+	const seen = new Set<string>();
+	for (let position = 0; results.length < limit; position++) {
+		let found = false;
+		for (const list of lists) {
+			const result = list[position];
+			if (!result) continue;
+			found = true;
+			if (!seen.has(result.displayPath)) {
+				seen.add(result.displayPath);
+				results.push(result);
+				if (results.length === limit) break;
+			}
+		}
+		if (!found) break;
+	}
+	return results;
+}
+
+/**
+ * Runs a deterministic structured query. The BM25 mode never invokes model
+ * APIs; hybrid mode supplies typed queries so QMD never loads its expansion
+ * model. Native/model errors deliberately propagate to the caller.
+ */
+export async function searchKnowledgeStore<T extends KnowledgeSearchResult>(
+	store: KnowledgeSearchStore<T>,
+	plan: KnowledgeSearchPlan,
+	options: KnowledgeSearchOptions,
+): Promise<readonly T[]> {
+	if (options.mode === "bm25") {
+		const lists: Array<readonly T[]> = [];
+		for (const query of plan.lex) {
+			lists.push(
+				await store.searchLex(query, {
+					limit: options.limit,
+					collection: options.collections ? [...options.collections] : undefined,
+				}),
+			);
+		}
+		return interleave(lists, options.limit);
+	}
+
+	return store.search({
+		queries: [
+			...plan.lex.map(query => ({ type: "lex" as const, query })),
+			...plan.vec.map(query => ({ type: "vec" as const, query })),
+			...plan.hyde.map(query => ({ type: "hyde" as const, query })),
+		],
+		intent: plan.intent,
+		collections: options.collections ? [...options.collections] : undefined,
+		limit: options.limit,
+		candidateLimit: options.candidateLimit ?? 30,
+		minScore: options.minScore ?? KNOWLEDGE_SCORE_THRESHOLDS[options.corpus],
+		explain: options.explain ?? true,
+		rerank: options.rerank ?? false,
+	});
+}

package/src/prompts/internal-urls/about.md

@@ -29,7 +29,7 @@ This document is the authoritative answer when the user asks about xcsh itself.
 
 xcsh serves F5 Distributed Cloud sales engineers. Product documentation is
 federated across the f5-sales-demo GitHub organization. Entry point:
-https://f5-sales-demo.github.io/docs/llms.txt
+https://f5-sales-demo.github.io/llms.txt
 
 Each product repo publishes: llms.txt (index with sidebar nav), custom sets
 at /_llms-txt/{topic}.txt, per-page content at /{slug}.md, plus

package/src/prompts/rules/llms-search.md

@@ -5,6 +5,15 @@ Select the best result and read its exact follow-up URL,
 `xcsh://documentation/<source>/<stable-path>/index.md`, before answering. Use the source filter when the question
 clearly targets `docs-cloud-f5-com` or `my-f5-com`.
 
+Render documentation images only when the user explicitly asks to see them. Extract all unique Markdown image references
+from the exact document, resolve relative references against its exact `xcsh://documentation/` URI, and
+read each asset one at a time in document order. Static screenshot collections are not timelines or slideshows.
+Pair every returned image with its official Markdown caption verbatim and one conservative explanation grounded in
+the image, its caption, and nearby prose. If pixels are unavailable, use only the caption and nearby prose without
+inventing visual details. Do not announce or estimate the image count before all reads finish. Afterward, verify that
+the reported image count matches the number of successful asset reads. Documentation assets use `read`, even when
+generic image-inspection guidance prefers `inspect_image`.
+
 For API paths, methods, payload fields, required status, enums, and constraints, use the deterministic
 `api-catalog-preflight` result followed by exact `xcsh://api-catalog/` and `xcsh://api-spec/` reads first.
 Do not route API metadata through the documentation QMD index.
@@ -13,7 +22,7 @@ Use the live cascade below only when the pinned documentation is stale or missin
 the QMD lookup fails. You **MUST** disclose why the pinned snapshot is stale, missing, or unavailable before the
 first live lookup:
 
-1. **Federation index** — Read `https://f5-sales-demo.github.io/docs/llms.txt` and select the relevant categorized site.
+1. **Federation index** — Read `https://f5-sales-demo.github.io/llms.txt` and select the relevant categorized site.
 2. **Site index** — Read that site's `llms.txt`; use its Documentation Sets, Sections, and Translations links as published.
 3. **Locale index** — Prefer the user's published locale. The default locale's Section normally points to `/_llms-txt/en.txt`; locale-aware tiered paths use `/_llms-txt/{locale}/…`. If a localized endpoint is absent or contains only a system marker, fall back to English and disclose that fallback.
 4. **Focused content** — Follow `## Contents` links recursively until the narrowest leaf `.txt` answers the question. Generated `/_llms-txt/` links are canonical; do not rewrite them. A same-locale page endpoint such as `/{locale}/{slug}.md` is an equivalent leaf when a page URL is already known.

package/src/prompts/system/system-prompt.md

@@ -495,10 +495,23 @@ search `xcsh://documentation/?search=<query>` first, then read the exact
 `xcsh://documentation/<source>/<stable-path>/index.md` result before answering. The search result
 is discovery; the exact Markdown document is the evidence.
 
+### Documentation images
+
+Render documentation images only when the user explicitly asks to see them. After that request, extract every
+unique Markdown image reference from the exact document, resolve each relative reference against that document's
+`xcsh://documentation/` URI, and preserve document order. Read each exact asset URI sequentially, one at a time, so
+the transcript order is stable. Do not use `display_media` for documentation assets, and do not convert a static
+screenshot collection into a timeline or slideshow.
+
+Inspect each returned image conservatively. Present its official Markdown caption verbatim with one grounded explanation.
+If image pixels are unavailable to the active model, quietly rely only on the official caption and nearby document
+prose; never invent visual details. Do not announce or estimate the image count before all reads finish. Afterward,
+verify that the reported image count matches the number of successful asset reads.
+
 If the pinned snapshot is stale, missing, or the QMD lookup fails, disclose that condition before using the live
 fallback knowledge index:
 
-`https://f5-sales-demo.github.io/docs/llms.txt`
+`https://f5-sales-demo.github.io/llms.txt`
 
 Follow links from there to the relevant site's own `llms.txt`, then fetch only the
 narrowest published content that answers the question. Do not silently replace or supplement a successful
@@ -714,6 +727,7 @@ Don't open a file hoping. Hope is not a strategy.
 - For image understanding tasks: **MUST** use `inspect_image` over `read` to avoid overloading main session context.
 - Write a specific `question` for `inspect_image`: what to inspect, constraints (for example verbatim OCR), and desired output format.
 - If you encounter `[Image content detected but current model does not support vision]` in a message, use `inspect_image` with the image file path to analyze it. Do not ask the user to describe the image — analyze it yourself via the tool.
+- Documentation images are the exception: use the exact `xcsh://documentation/` asset URI with `read`; do not pass internal documentation URIs to `inspect_image`.
 {{/if}}
 {{#ifAll (includes tools "inspect_image") (includes tools "generate_image")}}
 ### Image generation and analysis

package/src/prompts/tools/display-media.md

@@ -6,3 +6,7 @@ Pass exactly one of:
 - `frames`: ordered text frames or raster-frame sources with per-frame `durationMs`.
 
 Playback is always muted. Autoplay defaults to once, looping is opt-in, and playback is capped at 12 FPS unless a lower or higher cap (up to 60) is requested. Unsupported terminals and missing FFmpeg receive a static poster or text fallback.
+
+Do not use this tool for documentation assets. Resolve each Markdown image to its exact
+`xcsh://documentation/<source>/<stable-path>/assets/<filename>` URI and use `read` sequentially. Static screenshot
+collections are not timelines or slideshows.

package/src/services/xcsh-knowledge.ts

@@ -21,7 +21,6 @@ export interface LlmsIndex {
 
 const ENTRY_PATTERN = /^- \[([^\]]+)\]\(([^)]+)\):\s*(.+)$/;
 const ROOT_LLMS_FILE = "llms.txt";
-const PORTAL_SLUG = "docs";
 
 function extractRootLlmsSlug(url: string): string | null {
 	try {
@@ -64,8 +63,9 @@ function isValidIndex(value: unknown): value is LlmsIndex {
  *
  * Federation category headings are intentionally open-ended. A list entry is a
  * topic when it links to a sibling site's root /{slug}/llms.txt endpoint; this
- * excludes documentation sets, locale indexes, and tiered content without
- * hardcoding today's category names.
+ * excludes documentation sets and tiered content. The root portal now has
+ * locale feeds at /{locale}/llms.txt, so translation entries are excluded
+ * by their heading without restricting future federation categories.
  */
 export function parseLlmsTxt(content: string, now?: Date): LlmsIndex {
 	const lines = content.split("\n");
@@ -94,11 +94,11 @@ export function parseLlmsTxt(content: string, now?: Date): LlmsIndex {
 		}
 
 		const match = ENTRY_PATTERN.exec(trimmed);
-		if (!match || !category) continue;
+		if (!match || !category || category === "Translations") continue;
 
 		const [, name, url, topicDescription] = match;
 		const slug = extractRootLlmsSlug(url);
-		if (!slug || slug === PORTAL_SLUG || seenUrls.has(url)) continue;
+		if (!slug || seenUrls.has(url)) continue;
 
 		seenUrls.add(url);
 		topics.push({ name, description: topicDescription, url, category });
@@ -113,7 +113,7 @@ export function parseLlmsTxt(content: string, now?: Date): LlmsIndex {
 	};
 }
 
-const ROOT_LLMS_URL = "https://f5-sales-demo.github.io/docs/llms.txt";
+const ROOT_LLMS_URL = "https://f5-sales-demo.github.io/llms.txt";
 const DEFAULT_TTL_MS = 3_600_000;
 
 export class KnowledgeService {