@f5-sales-demo/xcsh 22.3.3 → 22.4.0

package/src/internal-urls/documentation-resolve.ts

@@ -1,3 +1,12 @@
+import {
+	DOCUMENTATION_CONTENT_TYPES,
+	DOCUMENTATION_LIFECYCLES,
+	DOCUMENTATION_TASK_TYPES,
+	type DocumentationContentType,
+	type DocumentationLifecycle,
+	type DocumentationRelatedDocument,
+	type DocumentationTaskType,
+} from "./documentation-metadata";
 import type { InternalResource, InternalUrl } from "./types";
 
 export const DOCUMENTATION_SOURCES = ["docs-cloud-f5-com", "my-f5-com", "www-f5-com"] as const;
@@ -20,12 +29,34 @@ export interface DocumentationSearchResult {
 	readonly stablePath: string;
 	readonly snippet: string;
 	readonly score: number;
+	readonly anchor?: string;
+	readonly heading?: string;
+	readonly canonicalUrl?: string;
+	readonly lastUpdated?: string | null;
+	readonly product?: string | null;
+	readonly contentType?: DocumentationContentType;
+	readonly taskType?: DocumentationTaskType;
+	readonly language?: string;
+	readonly lifecycle?: DocumentationLifecycle;
+	readonly replacementUrl?: string | null;
+	readonly aliases?: readonly string[];
+	readonly relatedDocuments?: readonly DocumentationRelatedDocument[];
 }
 
 export interface DocumentationDocument {
 	readonly markdown: string;
 	readonly title: string;
 	readonly originalUrl: string;
+	readonly lifecycle?: DocumentationLifecycle;
+	readonly replacementUrl?: string | null;
+}
+
+export interface DocumentationSearchFilters {
+	readonly product?: string;
+	readonly contentType?: DocumentationContentType;
+	readonly taskType?: DocumentationTaskType;
+	readonly language?: string;
+	readonly lifecycle?: DocumentationLifecycle;
 }
 
 export interface DocumentationAsset {
@@ -39,8 +70,13 @@ export interface DocumentationRepository {
 		query: string,
 		source: DocumentationSource | undefined,
 		limit: number,
+		filters?: DocumentationSearchFilters,
 	): Promise<readonly DocumentationSearchResult[]>;
-	readDocument(source: DocumentationSource, stablePath: string): Promise<DocumentationDocument | null>;
+	readDocument(
+		source: DocumentationSource,
+		stablePath: string,
+		anchor?: string,
+	): Promise<DocumentationDocument | null>;
 	readAsset(source: DocumentationSource, stablePath: string, filename: string): Promise<DocumentationAsset | null>;
 }
 
@@ -53,9 +89,25 @@ const IMAGE_NAME = /^[a-f0-9]{64}\.(?:gif|jpe?g|png|svg|webp)$/;
 const SAFE_SEGMENT = /^[A-Za-z0-9._~-]+$/;
 const MAX_QUERY_BYTES = 512;
 const MAX_SNIPPET_CHARS = 600;
+const PRODUCT = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+const LANGUAGE = /^[A-Za-z]{2,3}(?:-[A-Za-z0-9]{2,8})*$/;
 
-function validateQuery(url: InternalUrl): { search?: string; source?: DocumentationSource; limit: number } {
-	const allowed = new Set(["search", "source", "limit"]);
+function validateQuery(url: InternalUrl): {
+	search?: string;
+	source?: DocumentationSource;
+	limit: number;
+	filters: DocumentationSearchFilters;
+} {
+	const allowed = new Set([
+		"search",
+		"source",
+		"limit",
+		"product",
+		"content_type",
+		"task_type",
+		"language",
+		"lifecycle",
+	]);
 	for (const key of url.searchParams.keys()) {
 		if (!allowed.has(key)) throw new Error(`Unknown documentation parameter: ${key}`);
 		if (url.searchParams.getAll(key).length !== 1) throw new Error(`Duplicate documentation parameter: ${key}`);
@@ -73,12 +125,36 @@ function validateQuery(url: InternalUrl): { search?: string; source?: Documentat
 		throw new Error("Documentation search limit must be an integer from 1 to 10");
 	}
 	if (!search && (sourceValue !== undefined || limitValue !== null)) {
-		throw new Error("Documentation source and limit require search");
+		throw new Error("Documentation filters and limit require search");
+	}
+	const product = url.searchParams.get("product") ?? undefined;
+	if (product !== undefined && !PRODUCT.test(product)) throw new Error(`Invalid documentation product: ${product}`);
+	const contentType = url.searchParams.get("content_type") ?? undefined;
+	if (contentType !== undefined && !DOCUMENTATION_CONTENT_TYPES.includes(contentType as DocumentationContentType))
+		throw new Error(`Invalid documentation content type: ${contentType}`);
+	const taskType = url.searchParams.get("task_type") ?? undefined;
+	if (taskType !== undefined && !DOCUMENTATION_TASK_TYPES.includes(taskType as DocumentationTaskType))
+		throw new Error(`Invalid documentation task type: ${taskType}`);
+	const language = url.searchParams.get("language") ?? undefined;
+	if (language !== undefined && !LANGUAGE.test(language))
+		throw new Error(`Invalid documentation language: ${language}`);
+	const lifecycle = url.searchParams.get("lifecycle") ?? undefined;
+	if (lifecycle !== undefined && !DOCUMENTATION_LIFECYCLES.includes(lifecycle as DocumentationLifecycle))
+		throw new Error(`Invalid documentation lifecycle: ${lifecycle}`);
+	if (!search && [...url.searchParams.keys()].some(key => key !== "search")) {
+		throw new Error("Documentation filters and limit require search");
 	}
 	return {
 		search,
 		source: sourceValue as DocumentationSource | undefined,
 		limit: limitValue === null ? 5 : Number(limitValue),
+		filters: {
+			product,
+			contentType: contentType as DocumentationContentType | undefined,
+			taskType: taskType as DocumentationTaskType | undefined,
+			language,
+			lifecycle: lifecycle as DocumentationLifecycle | undefined,
+		},
 	};
 }
 
@@ -119,7 +195,7 @@ function inventory(repository: DocumentationRepository): string {
 		"Sources:",
 		...DOCUMENTATION_SOURCES.map(source => `- \`${source}\``),
 		"",
-		"Search with `xcsh://documentation/?search=<query>&source=<optional-source>&limit=<1-10>`.",
+		"Search with `xcsh://documentation/?search=<query>&source=<optional-source>&product=<slug>&content_type=<type>&task_type=<type>&language=<tag>&lifecycle=<state>&limit=<1-10>`.",
 	].join("\n");
 }
 
@@ -136,17 +212,42 @@ function renderSearch(
 	];
 	for (const result of results) {
 		const snippet = result.snippet.replace(/\s+/g, " ").trim().slice(0, MAX_SNIPPET_CHARS);
-		const followUp = `xcsh://documentation/${result.source}/${result.stablePath}/index.md`;
+		const followUp = `xcsh://documentation/${result.source}/${result.stablePath}/index.md${result.anchor ? `#${result.anchor}` : ""}`;
 		lines.push(
 			`## ${result.title}`,
 			`- Source: \`${result.source}\``,
 			`- Original: ${result.originalUrl}`,
+			`- Canonical: ${result.canonicalUrl ?? result.originalUrl}`,
+			`- Last updated: ${result.lastUpdated ?? "unknown"}`,
+			`- Product: ${result.product ?? "unclassified"}`,
+			`- Content type: ${result.contentType}`,
+			`- Task type: ${result.taskType}`,
+			`- Section: ${result.heading ?? result.anchor ?? "document"}`,
+			`- Language: ${result.language}`,
+			`- Lifecycle: ${result.lifecycle}`,
+			`- Aliases: ${result.aliases?.join(", ") || "none"}`,
 			`- Score: ${result.score}`,
 			`- Read: \`${followUp}\``,
 			"",
 			snippet,
 			"",
 		);
+		if (result.lifecycle && result.lifecycle !== "current") {
+			lines.push(
+				`> Warning: this document is ${result.lifecycle}.${result.replacementUrl ? ` Replacement: ${result.replacementUrl}` : ""}`,
+				"",
+			);
+		}
+		if ((result.relatedDocuments?.length ?? 0) > 0) {
+			lines.push(
+				"Related documents:",
+				...(result.relatedDocuments ?? []).map(
+					related =>
+						`- ${related.relation}: [${related.title}](xcsh://documentation/${related.source}/${related.stablePath}/index.md)`,
+				),
+				"",
+			);
+		}
 	}
 	if (results.length === 0) lines.push("No matching documents found.", "");
 	return lines.join("\n");
@@ -159,7 +260,7 @@ export function createDocumentationResolver(repository: DocumentationRepository)
 			const segments = parseResourcePath(url);
 			if (query.search) {
 				if (segments.length !== 0) throw new Error("Documentation search is available only at the root");
-				const results = await repository.search(query.search, query.source, query.limit);
+				const results = await repository.search(query.search, query.source, query.limit, query.filters);
 				return textResource(url, renderSearch(repository, query.search, results), "xcsh://documentation/");
 			}
 			if (segments.length === 0) {
@@ -171,9 +272,22 @@ export function createDocumentationResolver(repository: DocumentationRepository)
 			if (rest.at(-1) === "index.md") {
 				const stablePath = rest.slice(0, -1).join("/");
 				if (!stablePath) throw new Error("Documentation path is missing");
-				const document = await repository.readDocument(source, stablePath);
+				const rawAnchor = url.hash.startsWith("#") ? url.hash.slice(1) : url.hash;
+				if (/%(?:2f|5c|2e)/i.test(rawAnchor)) throw new Error("Invalid documentation anchor");
+				const anchor = rawAnchor ? decodeURIComponent(rawAnchor) : undefined;
+				if (anchor && (anchor.length > 256 || !/^[\p{L}\p{N}\p{M}_-]+$/u.test(anchor)))
+					throw new Error("Invalid documentation anchor");
+				const document = await repository.readDocument(source, stablePath, anchor);
 				if (!document) throw new Error(`Documentation file not found: ${source}/${stablePath}/index.md`);
-				return textResource(url, document.markdown, `xcsh://documentation/${source}/${stablePath}/index.md`);
+				const warning =
+					!document.lifecycle || document.lifecycle === "current"
+						? ""
+						: `> Warning: this document is ${document.lifecycle}.${document.replacementUrl ? ` Replacement: ${document.replacementUrl}` : ""}\n\n`;
+				return textResource(
+					url,
+					`${warning}${document.markdown}`,
+					`xcsh://documentation/${source}/${stablePath}/index.md${anchor ? `#${anchor}` : ""}`,
+				);
 			}
 			const assetsIndex = rest.length - 2;
 			if (assetsIndex >= 1 && rest[assetsIndex] === "assets" && IMAGE_NAME.test(rest.at(-1) ?? "")) {

package/src/internal-urls/documentation-snapshot.ts

@@ -8,6 +8,14 @@ import { createGunzip, gunzipSync } from "node:zlib";
 import { createStore } from "@tobilu/qmd";
 import tar from "tar-stream";
 import { parse as parseYaml } from "yaml";
+import {
+	type DocumentationMetadata,
+	type DocumentationPassage,
+	parseDocumentationMetadata,
+	passageHash,
+	splitHeadingPassages,
+	validateDocumentationGraph,
+} from "./documentation-metadata";
 import { DOCUMENTATION_SOURCES, type DocumentationSource } from "./documentation-resolve";
 
 const MIB = 1024 * 1024;
@@ -33,6 +41,7 @@ const COMMIT = /^[a-f0-9]{40}$/;
 const RELEASE_TAG = /^content-[0-9]{8}T[0-9]{6}Z$/;
 const TIMESTAMP = /^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}Z$/;
 const FIXED_TIME = "2000-01-01T00:00:00.000Z";
+const DOCUMENTATION_INDEX_SCHEMA_VERSION = 2;
 const MANIFEST_KEYS = [
 	"asset_count",
 	"assets",
@@ -112,6 +121,8 @@ export interface VerifiedDocumentationDocument {
 	readonly fileSha256: string;
 	readonly sizeBytes: number;
 	readonly markdown: string;
+	readonly metadata: DocumentationMetadata;
+	readonly passages: readonly DocumentationPassage[];
 }
 
 export interface VerifiedDocumentationAsset {
@@ -198,6 +209,39 @@ function validateOriginalUrl(value: unknown, source: DocumentationSource, field:
 	return result;
 }
 
+function validateCorpusUrl(value: unknown, source: DocumentationSource | undefined, field: string): string {
+	if (source !== undefined) {
+		const result = validateOriginalUrl(value, source, field);
+		validateNormalizedUrl(result, field);
+		return result;
+	}
+	for (const candidate of DOCUMENTATION_SOURCES) {
+		try {
+			const result = validateOriginalUrl(value, candidate, field);
+			validateNormalizedUrl(result, field);
+			return result;
+		} catch {
+			// Continue until one complete source policy accepts the URL.
+		}
+	}
+	throw new Error(`${field} is outside the documentation corpus`);
+}
+
+function validateNormalizedUrl(value: string, field: string): void {
+	const parsed = new URL(value);
+	if (parsed.protocol !== "https:" || parsed.username || parsed.password || parsed.hash) {
+		throw new Error(`${field} is not a normalized HTTPS URL`);
+	}
+	const entries = [...parsed.searchParams.entries()].sort(
+		([leftKey, leftValue], [rightKey, rightValue]) =>
+			leftKey.localeCompare(rightKey) || leftValue.localeCompare(rightValue),
+	);
+	const normalizedQuery = new URLSearchParams(entries).toString();
+	const normalizedPath = parsed.pathname === "/" ? "/" : parsed.pathname.replace(/\/{2,}/g, "/").replace(/\/$/, "");
+	const normalized = `${parsed.protocol}//${parsed.host}${normalizedPath}${normalizedQuery ? `?${normalizedQuery}` : ""}`;
+	if (normalized !== value) throw new Error(`${field} is not normalized`);
+}
+
 export function sha256Bytes(value: Uint8Array | string): string {
 	return createHash("sha256").update(value).digest("hex");
 }
@@ -616,6 +660,16 @@ export async function verifyDocumentationRelease(
 		}
 		if (parsed.metadata.sourceId !== source || parsed.metadata.url !== originalUrl)
 			throw new Error(`manifest document frontmatter mismatch: ${archiveMemberPath}`);
+		const metadata = parseDocumentationMetadata(
+			parsed.metadata,
+			validateCorpusUrl,
+			source,
+			`document ${archiveMemberPath}`,
+		);
+		const passages = splitHeadingPassages(parsed.body);
+		if (new Set(passages.map(passage => passage.anchor)).size !== passages.length) {
+			throw new Error(`document heading anchors are not unique: ${archiveMemberPath}`);
+		}
 		const bodySha256 = string(item.body_sha256, "manifest document body hash");
 		const fileSha256 = string(item.file_sha256, "manifest document file hash");
 		const sizeBytes = count(item.size_bytes, "manifest document size");
@@ -633,8 +687,11 @@ export async function verifyDocumentationRelease(
 			fileSha256,
 			sizeBytes,
 			markdown,
+			metadata,
+			passages,
 		};
 	});
+	validateDocumentationGraph(documents);
 
 	const marketingDocumentPaths = new Set(
 		documents.filter(document => document.source === "www-f5-com").map(document => document.stablePath),
@@ -690,6 +747,7 @@ function fingerprint(snapshot: VerifiedDocumentationSnapshot): string {
 	return sha256Bytes(
 		JSON.stringify({
 			archiveSha256: snapshot.archiveSha256,
+			indexSchema: DOCUMENTATION_INDEX_SCHEMA_VERSION,
 			releaseTag: snapshot.releaseTag,
 			sourceCommit: snapshot.sourceCommit,
 			qmdVersion: "2.8.3",
@@ -739,8 +797,47 @@ function canonicalizeDatabase(
 			file_sha256 TEXT NOT NULL,
 			size_bytes INTEGER NOT NULL,
 			markdown TEXT NOT NULL,
+			canonical_url TEXT NOT NULL,
+			last_updated TEXT,
+			product TEXT,
+			content_type TEXT NOT NULL,
+			task_type TEXT NOT NULL,
+			language TEXT NOT NULL,
+			lifecycle TEXT NOT NULL,
+			replacement_url TEXT,
+			aliases_json TEXT NOT NULL,
+			related_documents_json TEXT NOT NULL,
 			PRIMARY KEY (source, stable_path)
 		)`);
+		db.exec(`CREATE TABLE documentation_passages (
+			source TEXT NOT NULL,
+			stable_path TEXT NOT NULL,
+			anchor TEXT NOT NULL,
+			heading TEXT NOT NULL,
+			markdown TEXT NOT NULL,
+			ordinal INTEGER NOT NULL,
+			qmd_path TEXT NOT NULL UNIQUE,
+			PRIMARY KEY (source, stable_path, anchor)
+		)`);
+		db.exec(`CREATE INDEX documentation_metadata_filters ON documentation_documents (
+			product, content_type, task_type, language, lifecycle, source
+		)`);
+		db.exec(`CREATE INDEX documentation_passage_page ON documentation_passages (source, stable_path, ordinal)`);
+		db.exec(`CREATE TABLE documentation_aliases (
+			product TEXT NOT NULL,
+			alias TEXT NOT NULL,
+			PRIMARY KEY (product, alias)
+		)`);
+		db.exec(`CREATE TABLE documentation_relationships (
+			source TEXT NOT NULL,
+			stable_path TEXT NOT NULL,
+			relation TEXT NOT NULL,
+			target_source TEXT NOT NULL,
+			target_stable_path TEXT NOT NULL,
+			title TEXT NOT NULL,
+			canonical_url TEXT NOT NULL,
+			PRIMARY KEY (source, stable_path, canonical_url)
+		)`);
 		db.exec(`CREATE TABLE documentation_assets (
 			source TEXT NOT NULL,
 			stable_path TEXT NOT NULL,
@@ -757,11 +854,17 @@ function canonicalizeDatabase(
 			asset_count: String(snapshot.assets.length),
 			document_count: String(snapshot.documents.length),
 			fingerprint: indexFingerprint,
+			index_schema: String(DOCUMENTATION_INDEX_SCHEMA_VERSION),
 			release_tag: snapshot.releaseTag,
 			source_commit: snapshot.sourceCommit,
 		}).sort(([left], [right]) => left.localeCompare(right)))
 			provenance.run(key, value);
-		const insertDocument = db.query("INSERT INTO documentation_documents VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)");
+		const insertDocument = db.query(
+			"INSERT INTO documentation_documents VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)",
+		);
+		const insertPassage = db.query("INSERT INTO documentation_passages VALUES (?, ?, ?, ?, ?, ?, ?)");
+		const insertAlias = db.query("INSERT OR IGNORE INTO documentation_aliases VALUES (?, ?)");
+		const insertRelationship = db.query("INSERT INTO documentation_relationships VALUES (?, ?, ?, ?, ?, ?, ?)");
 		for (const document of snapshot.documents) {
 			insertDocument.run(
 				document.source,
@@ -773,7 +876,42 @@ function canonicalizeDatabase(
 				document.fileSha256,
 				document.sizeBytes,
 				document.markdown,
+				document.metadata.canonicalUrl,
+				document.metadata.lastUpdated,
+				document.metadata.product,
+				document.metadata.contentType,
+				document.metadata.taskType,
+				document.metadata.language,
+				document.metadata.lifecycle,
+				document.metadata.replacementUrl,
+				JSON.stringify(document.metadata.aliases),
+				JSON.stringify(document.metadata.relatedDocuments),
 			);
+			for (const passage of document.passages) {
+				insertPassage.run(
+					document.source,
+					document.stablePath,
+					passage.anchor,
+					passage.heading,
+					passage.markdown,
+					passage.ordinal,
+					`${document.stablePath}/index.md#${passage.anchor}`,
+				);
+			}
+			if (document.metadata.product) {
+				for (const alias of document.metadata.aliases) insertAlias.run(document.metadata.product, alias);
+			}
+			for (const related of document.metadata.relatedDocuments) {
+				insertRelationship.run(
+					document.source,
+					document.stablePath,
+					related.relation,
+					related.source,
+					related.stablePath,
+					related.title,
+					related.canonicalUrl,
+				);
+			}
 		}
 		const insertAsset = db.query("INSERT INTO documentation_assets VALUES (?, ?, ?, ?, ?, ?, ?)");
 		for (const asset of snapshot.assets) {
@@ -810,9 +948,15 @@ function verifyIndexedBodies(databasePath: string, snapshot: VerifiedDocumentati
 			FROM documents d JOIN content c ON c.hash = d.hash WHERE d.active = 1
 			ORDER BY d.collection, d.path`)
 			.all() as Array<{ source: string; path: string; markdown: string }>;
-		if (rows.length !== snapshot.documents.length) throw new Error("documentation index document count mismatch");
+		const passageCount = snapshot.documents.reduce((total, document) => total + document.passages.length, 0);
+		if (rows.length !== passageCount) throw new Error("documentation index passage count mismatch");
 		const expected = new Map(
-			snapshot.documents.map(document => [`${document.source}/${document.stablePath}/index.md`, document.markdown]),
+			snapshot.documents.flatMap(document =>
+				document.passages.map(passage => [
+					`${document.source}/${document.stablePath}/index.md#${passage.anchor}`,
+					passage.markdown,
+				]),
+			),
 		);
 		for (const row of rows) {
 			const key = `${row.source}/${row.path.replaceAll("\\", "/")}`;
@@ -875,15 +1019,27 @@ export async function buildDocumentationIndex(
 		});
 		try {
 			for (const document of snapshot.documents) {
-				store.internal.insertContent(document.fileSha256, document.markdown, FIXED_TIME);
-				store.internal.insertDocument(
-					document.source,
-					`${document.stablePath}/index.md`,
+				const weightedTitle = [
 					document.title,
-					document.fileSha256,
-					FIXED_TIME,
-					FIXED_TIME,
-				);
+					document.metadata.product,
+					document.metadata.contentType,
+					document.metadata.taskType,
+					...document.metadata.aliases,
+				]
+					.filter(Boolean)
+					.join(" ");
+				for (const passage of document.passages) {
+					const hash = passageHash(document.fileSha256, passage.anchor, passage.markdown);
+					store.internal.insertContent(hash, passage.markdown, FIXED_TIME);
+					store.internal.insertDocument(
+						document.source,
+						`${document.stablePath}/index.md#${passage.anchor}`,
+						weightedTitle,
+						hash,
+						FIXED_TIME,
+						FIXED_TIME,
+					);
+				}
 			}
 			store.internal.db.exec("PRAGMA wal_checkpoint(TRUNCATE)");
 			store.internal.db.exec("PRAGMA journal_mode = DELETE");

package/src/modes/interactive-mode.ts

@@ -22,7 +22,7 @@ import type {
 } from "../extensibility/extensions";
 import { discoverAndLoadExtensions } from "../extensibility/extensions";
 import type { CompactOptions } from "../extensibility/extensions/types";
-import { BUILTIN_SLASH_COMMANDS, loadSlashCommands } from "../extensibility/slash-commands";
+import { getBuiltinSlashCommandDiscoveryCandidates, loadSlashCommands } from "../extensibility/slash-commands";
 import { startSessionBridge } from "../remote-control/bridge";
 import type { ModelResolutionSource } from "../session/active-model";
 import type { AgentSession, AgentSessionEvent } from "../session/agent-session";
@@ -254,10 +254,7 @@ export class InteractiveMode implements InteractiveModeContext {
 
 		this.hideThinkingBlock = settings.get("hideThinkingBlock");
 
-		const builtinCommands: SlashCommandDiscoveryCandidate[] = BUILTIN_SLASH_COMMANDS.map(command => ({
-			...command,
-			discovery: { behavior: "execution", provenance: "xcsh built-in", scope: "native" },
-		}));
+		const builtinCommands = getBuiltinSlashCommandDiscoveryCandidates();
 		const builtinCommandNames = new Set(builtinCommands.map(c => c.name));
 		const extensionCommands: SlashCommandDiscoveryCandidate[] = (
 			this.session.extensionRunner?.getRegisteredCommandEntries(builtinCommandNames) ?? []

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

@@ -1,11 +1,13 @@
 # Documentation Lookup Hierarchy (Offline QMD First)
 
 For conceptual, product, operational, and support questions, search `xcsh://documentation/?search=<query>` first.
-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
+Select the best result and read its exact section-qualified follow-up URL,
+`xcsh://documentation/<source>/<stable-path>/index.md#<anchor>`, before answering. Use the source filter when the question
 clearly targets `docs-cloud-f5-com`, `my-f5-com`, or `www-f5-com`. Prefer `www-f5-com` for conceptual and product
 questions, `docs-cloud-f5-com` for configuration and procedures, and `my-f5-com` for troubleshooting and support.
-An explicit source filter is authoritative.
+An explicit source filter is authoritative. Add `product`, `content_type`, `task_type`, `language`, or `lifecycle`
+filters only when the request makes that constraint explicit. Follow related internal documentation links when they
+are relevant, and always surface deprecated or superseded lifecycle warnings and replacements.
 
 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

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

@@ -491,11 +491,13 @@ In `bash`, URIs auto-resolve to filesystem paths (e.g., `python skill://my-skill
 # Product and ecosystem knowledge
 
 For conceptual, product, operational, or support questions about F5 Distributed Cloud, you **MUST**
-search `xcsh://documentation/?search=<query>` first, then read the exact
-`xcsh://documentation/<source>/<stable-path>/index.md` result before answering. The search result
+search `xcsh://documentation/?search=<query>` first, then read the exact section-qualified
+`xcsh://documentation/<source>/<stable-path>/index.md#<anchor>` result before answering. The search result
 is discovery; the exact Markdown document is the evidence.
 Prefer `www-f5-com` for conceptual and product questions, `docs-cloud-f5-com` for configuration and
 procedural questions, and `my-f5-com` for troubleshooting and support. An explicit source filter is authoritative.
+Use `product`, `content_type`, `task_type`, `language`, and `lifecycle` filters when the request explicitly supplies
+those constraints. Follow relevant typed related-document links and surface lifecycle warnings and replacements.
 
 ### Documentation images
 

package/src/slash-commands/builtin-registry.ts

@@ -122,6 +122,7 @@ export interface SubcommandDef {
 /** Declarative builtin slash command definition used by autocomplete and help UI. */
 export interface BuiltinSlashCommand {
 	name: string;
+	aliases?: string[];
 	description: string;
 	/** Subcommands for dropdown completion. */
 	subcommands?: SubcommandDef[];
@@ -137,7 +138,6 @@ interface ParsedBuiltinSlashCommand {
 }
 
 interface BuiltinSlashCommandSpec extends BuiltinSlashCommand {
-	aliases?: string[];
 	allowArgs?: boolean;
 	/**
 	 * Handle the command. Return a string to pass remaining text through as prompt input.
@@ -2508,6 +2508,7 @@ export function getBuiltinSlashCommandInventory() {
 export const BUILTIN_SLASH_COMMAND_DEFS: ReadonlyArray<BuiltinSlashCommand> = BUILTIN_SLASH_COMMAND_REGISTRY.map(
 	command => ({
 		name: command.name,
+		aliases: command.aliases,
 		description: command.description,
 		subcommands: command.subcommands,
 		inlineHint: command.inlineHint,