@f5xc-salesdemos/xcsh 18.28.1 → 18.30.0

package/package.json

@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@f5xc-salesdemos/xcsh",
-	"version": "18.28.1",
+	"version": "18.30.0",
 	"description": "Coding agent CLI with read, bash, edit, write tools and session management",
 	"homepage": "https://github.com/f5xc-salesdemos/xcsh",
 	"author": "Can Boluk",
@@ -31,28 +31,29 @@
 		"xcsh": "src/cli.ts"
 	},
 	"scripts": {
-		"build": "bun run generate-build-info && bun --cwd=../stats scripts/generate-client-bundle.ts --generate && bun --cwd=../natives run embed:native && bun build --compile --define PI_COMPILED=true --external mupdf --root ../.. ./src/cli.ts --outfile dist/xcsh && bun --cwd=../natives run embed:native --reset && bun --cwd=../stats scripts/generate-client-bundle.ts --reset",
+		"build": "bun run generate-build-info && bun run generate-api-spec-index && bun --cwd=../stats scripts/generate-client-bundle.ts --generate && bun --cwd=../natives run embed:native && bun build --compile --define PI_COMPILED=true --external mupdf --root ../.. ./src/cli.ts --outfile dist/xcsh && bun --cwd=../natives run embed:native --reset && bun --cwd=../stats scripts/generate-client-bundle.ts --reset",
 		"check": "biome check . && bun run check:types",
-		"check:types": "bun run generate-build-info && tsgo -p tsconfig.json --noEmit",
+		"check:types": "bun run generate-build-info && bun run generate-api-spec-index && tsgo -p tsconfig.json --noEmit",
 		"lint": "biome lint .",
-		"test": "bun run generate-build-info && bun test --max-concurrency 4",
-		"fix": "biome check --write --unsafe . && bun run format-prompts && bun run generate-docs-index && bun run generate-build-info",
+		"test": "bun run generate-build-info && bun run generate-api-spec-index && bun test --max-concurrency 4",
+		"fix": "biome check --write --unsafe . && bun run format-prompts && bun run generate-docs-index && bun run generate-api-spec-index && bun run generate-build-info",
 		"fmt": "biome format --write . && bun run format-prompts",
 		"format-prompts": "bun scripts/format-prompts.ts",
 		"generate-docs-index": "bun scripts/generate-docs-index.ts",
+		"generate-api-spec-index": "bun scripts/generate-api-spec-index.ts",
 		"generate-build-info": "bun scripts/generate-build-info.ts",
-		"prepack": "bun scripts/generate-docs-index.ts && bun scripts/generate-build-info.ts",
+		"prepack": "bun scripts/generate-docs-index.ts && bun scripts/generate-api-spec-index.ts && bun scripts/generate-build-info.ts",
 		"generate-template": "bun scripts/generate-template.ts"
 	},
 	"dependencies": {
 		"@agentclientprotocol/sdk": "0.16.1",
 		"@mozilla/readability": "^0.6",
-		"@f5xc-salesdemos/xcsh-stats": "18.28.1",
-		"@f5xc-salesdemos/pi-agent-core": "18.28.1",
-		"@f5xc-salesdemos/pi-ai": "18.28.1",
-		"@f5xc-salesdemos/pi-natives": "18.28.1",
-		"@f5xc-salesdemos/pi-tui": "18.28.1",
-		"@f5xc-salesdemos/pi-utils": "18.28.1",
+		"@f5xc-salesdemos/xcsh-stats": "18.30.0",
+		"@f5xc-salesdemos/pi-agent-core": "18.30.0",
+		"@f5xc-salesdemos/pi-ai": "18.30.0",
+		"@f5xc-salesdemos/pi-natives": "18.30.0",
+		"@f5xc-salesdemos/pi-tui": "18.30.0",
+		"@f5xc-salesdemos/pi-utils": "18.30.0",
 		"@sinclair/typebox": "^0.34",
 		"@xterm/headless": "^6.0",
 		"ajv": "^8.18",

package/scripts/generate-api-spec-index.ts

@@ -0,0 +1,165 @@
+#!/usr/bin/env bun
+
+import { execFileSync } from "node:child_process";
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import { gzipSync } from "node:zlib";
+
+interface IndexEntry {
+	domain: string;
+	title: string;
+	description: string;
+	"x-f5xc-description-short": string;
+	file: string;
+	path_count: number;
+	schema_count: number;
+	"x-f5xc-complexity": string;
+	"x-f5xc-category": string;
+	"x-f5xc-use-cases"?: string[];
+	"x-f5xc-related-domains"?: string[];
+	"x-f5xc-primary-resources"?: Array<{ name: string; description: string }>;
+}
+
+interface RawIndex {
+	version: string;
+	timestamp: string;
+	specifications: IndexEntry[];
+}
+
+const REPO = "f5xc-salesdemos/api-specs-enriched";
+const PINNED_TAG = "v2.1.62";
+const outputPath = path.resolve(import.meta.dir, "../src/internal-urls/api-spec-index.generated.ts");
+
+async function downloadFromRelease(): Promise<string> {
+	const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "api-specs-"));
+	const tag = process.env.API_SPECS_TAG ?? PINNED_TAG;
+	const zipName = `f5xc-api-specs-${tag}.zip`;
+	const downloadUrl = `https://github.com/${REPO}/releases/download/${tag}/${zipName}`;
+
+	console.log(`Downloading API specs from ${downloadUrl}...`);
+	const response = await fetch(downloadUrl, { redirect: "follow" });
+	if (!response.ok) {
+		throw new Error(`Failed to download release: ${response.status} ${response.statusText}`);
+	}
+
+	const zipPath = path.join(tmpDir, zipName);
+	const buffer = Buffer.from(await response.arrayBuffer());
+	fs.writeFileSync(zipPath, buffer);
+
+	const extractDir = path.join(tmpDir, "extracted");
+	fs.mkdirSync(extractDir, { recursive: true });
+	execFileSync("unzip", ["-q", zipPath, "-d", extractDir], { stdio: "inherit" });
+
+	const domainsDir = path.join(extractDir, "domains");
+	if (fs.existsSync(domainsDir) && fs.existsSync(path.join(extractDir, "index.json"))) {
+		for (const file of fs.readdirSync(domainsDir)) {
+			fs.copyFileSync(path.join(domainsDir, file), path.join(extractDir, file));
+		}
+	}
+
+	return extractDir;
+}
+
+async function findSpecsDir(): Promise<string> {
+	const envDir = process.env.API_SPECS_DIR;
+	if (envDir && fs.existsSync(envDir)) {
+		return envDir;
+	}
+
+	const localCheckout = path.resolve(import.meta.dir, "../../../../api-specs-enriched/docs/specifications/api");
+	if (fs.existsSync(localCheckout)) {
+		return localCheckout;
+	}
+
+	return downloadFromRelease();
+}
+
+const specsDir = await findSpecsDir();
+console.log(`Reading specs from: ${specsDir}`);
+
+const indexPath = path.join(specsDir, "index.json");
+if (!fs.existsSync(indexPath)) {
+	console.error(`index.json not found at: ${indexPath}`);
+	process.exit(1);
+}
+
+const rawIndex: RawIndex = JSON.parse(fs.readFileSync(indexPath, "utf-8"));
+
+const domainEntries: string[] = [];
+const blobEntries: string[] = [];
+let processedCount = 0;
+let skippedCount = 0;
+
+for (const entry of rawIndex.specifications) {
+	const specFile = path.join(specsDir, entry.file);
+	if (!fs.existsSync(specFile)) {
+		console.warn(`  Skipping ${entry.domain}: spec file not found at ${specFile}`);
+		skippedCount++;
+		continue;
+	}
+
+	const specContent = fs.readFileSync(specFile, "utf-8");
+	const compressed = gzipSync(Buffer.from(specContent));
+	const b64 = compressed.toString("base64");
+
+	const resources = (entry["x-f5xc-primary-resources"] ?? []).map(
+		r => `\t\t\t{ name: ${JSON.stringify(r.name)}, description: ${JSON.stringify(r.description)} },`,
+	);
+
+	const useCases = entry["x-f5xc-use-cases"];
+	const relatedDomains = entry["x-f5xc-related-domains"];
+
+	domainEntries.push(
+		[
+			"\t\t{",
+			`\t\t\tdomain: ${JSON.stringify(entry.domain)},`,
+			`\t\t\ttitle: ${JSON.stringify(entry.title)},`,
+			`\t\t\tdescription: ${JSON.stringify(entry.description)},`,
+			`\t\t\tdescriptionShort: ${JSON.stringify(entry["x-f5xc-description-short"])},`,
+			`\t\t\tcategory: ${JSON.stringify(entry["x-f5xc-category"])},`,
+			`\t\t\tpathCount: ${entry.path_count},`,
+			`\t\t\tschemaCount: ${entry.schema_count},`,
+			`\t\t\tcomplexity: ${JSON.stringify(entry["x-f5xc-complexity"])},`,
+			`\t\t\tresources: [`,
+			...resources,
+			`\t\t\t],`,
+			useCases ? `\t\t\tuseCases: ${JSON.stringify(useCases)},` : undefined,
+			relatedDomains?.length ? `\t\t\trelatedDomains: ${JSON.stringify(relatedDomains)},` : undefined,
+			"\t\t},",
+		]
+			.filter(Boolean)
+			.join("\n"),
+	);
+
+	blobEntries.push(`\t${JSON.stringify(entry.domain)}: ${JSON.stringify(b64)},`);
+	processedCount++;
+}
+
+const output = [
+	"// Auto-generated by scripts/generate-api-spec-index.ts - DO NOT EDIT",
+	"",
+	`import type { ApiSpecIndex } from "./api-spec-types";`,
+	"",
+	`export const API_SPEC_VERSION = ${JSON.stringify(rawIndex.version)};`,
+	"",
+	`export const API_SPEC_INDEX: ApiSpecIndex = {`,
+	`\tversion: ${JSON.stringify(rawIndex.version)},`,
+	`\ttimestamp: ${JSON.stringify(rawIndex.timestamp)},`,
+	`\tdomains: [`,
+	...domainEntries,
+	`\t],`,
+	`};`,
+	"",
+	`export const API_SPEC_BLOBS: Readonly<Record<string, string>> = {`,
+	...blobEntries,
+	`};`,
+	"",
+].join("\n");
+
+await Bun.write(outputPath, output);
+
+const outputSize = (Buffer.byteLength(output) / 1024 / 1024).toFixed(1);
+console.log(
+	`Generated ${path.relative(process.cwd(), outputPath)} (${processedCount} domains, ${skippedCount} skipped, ${outputSize} MB)`,
+);

package/src/internal-urls/api-spec-resolve.ts

@@ -0,0 +1,373 @@
+import { gunzipSync } from "node:zlib";
+import { LRUCache } from "lru-cache";
+import type { ApiSpecDomainEntry, ApiSpecIndex, OpenAPISpec } from "./api-spec-types";
+import type { InternalResource, InternalUrl } from "./types";
+
+const LRU_CAPACITY = 5;
+const SCHEMA_RENDER_MAX_DEPTH = 3;
+
+export interface ApiSpecResolver {
+	resolve(url: InternalUrl): Promise<InternalResource>;
+}
+
+export function createApiSpecResolver(index: ApiSpecIndex, blobs: Record<string, string>): ApiSpecResolver {
+	const cache = new LRUCache<string, OpenAPISpec>({ max: LRU_CAPACITY });
+
+	function decompress(domain: string): OpenAPISpec {
+		const cached = cache.get(domain);
+		if (cached) return cached;
+
+		const blob = blobs[domain];
+		if (!blob) {
+			throw new Error(`No spec blob for domain: ${domain}`);
+		}
+
+		const buffer = Buffer.from(blob, "base64");
+		const decompressed = gunzipSync(buffer);
+		const spec = JSON.parse(decompressed.toString("utf-8")) as OpenAPISpec;
+		cache.set(domain, spec);
+		return spec;
+	}
+
+	return {
+		async resolve(url: InternalUrl): Promise<InternalResource> {
+			const pathname = url.rawPathname ?? url.pathname;
+			const domain = pathname.replace(/^\//, "").replace(/\/$/, "");
+
+			if (!domain) {
+				return makeResource(url, renderDomainIndex(index));
+			}
+
+			const entry = index.domains.find(d => d.domain === domain);
+			if (!entry) {
+				return makeResource(url, renderUnknownDomain(domain, index));
+			}
+
+			const resource = url.searchParams.get("resource");
+			const pathFilter = url.searchParams.get("path");
+
+			if (resource) {
+				const spec = decompress(domain);
+				const matchingPaths = filterPathsByResource(spec, resource);
+				if (Object.keys(matchingPaths).length === 0) {
+					return makeResource(url, renderUnknownResource(resource, entry, spec));
+				}
+				return makeResource(url, renderResourceSpec(domain, resource, spec));
+			}
+
+			if (pathFilter) {
+				const spec = decompress(domain);
+				return makeResource(url, renderPathSpec(domain, pathFilter, spec));
+			}
+
+			const spec = decompress(domain);
+			return makeResource(url, renderDomainDetail(domain, entry, spec));
+		},
+	};
+}
+
+function makeResource(url: InternalUrl, content: string): InternalResource {
+	return {
+		url: url.href,
+		content,
+		contentType: "text/markdown",
+		size: Buffer.byteLength(content, "utf-8"),
+		sourcePath: `xcsh://${url.rawHost}${url.rawPathname ?? "/"}`,
+	};
+}
+
+function renderDomainIndex(index: ApiSpecIndex): string {
+	const rows = index.domains.map(
+		d => `| ${d.domain} | ${d.category} | ${d.resources.length} | ${d.pathCount} | ${d.descriptionShort} |`,
+	);
+
+	return [
+		`# F5 XC API Specifications (v${index.version})`,
+		"",
+		`${index.domains.length} domains. Read \`xcsh://api-spec/{domain}\` for resource details.`,
+		"",
+		"| Domain | Category | Resources | Paths | Description |",
+		"|--------|----------|-----------|-------|-------------|",
+		...rows,
+		"",
+	].join("\n");
+}
+
+function renderDomainDetail(domain: string, entry: ApiSpecDomainEntry, spec: OpenAPISpec): string {
+	const groups = groupPathsBySchema(spec);
+	const schemaNames = [...groups.keys()].sort();
+
+	const resourceRows = schemaNames.map(s => {
+		const paths = groups.get(s)!;
+		const opCount = Object.values(paths).reduce((n, m) => n + Object.keys(m).length, 0);
+		return `| ${s} | ${opCount} operations |`;
+	});
+
+	const operationRows: string[] = [];
+	for (const [pathKey, methods] of Object.entries(spec.paths)) {
+		for (const [method, op] of Object.entries(methods)) {
+			if (typeof op !== "object" || !op) continue;
+			const summary = (op as Record<string, unknown>).summary ?? "";
+			operationRows.push(`| ${method.toUpperCase()} | ${pathKey} | ${summary} |`);
+		}
+	}
+
+	const sections = [
+		`# ${entry.title} — F5 XC API`,
+		"",
+		`Category: ${entry.category} | Paths: ${entry.pathCount} | Complexity: ${entry.complexity}`,
+		"",
+		"## Resources",
+		"",
+		"| Resource | Info |",
+		"|----------|------|",
+		...resourceRows,
+		"",
+		"## Operations",
+		"",
+		"| Method | Path | Summary |",
+		"|--------|------|---------|",
+		...operationRows,
+	];
+
+	if (entry.useCases?.length) {
+		sections.push("", "## Use Cases", ...entry.useCases.map(u => `- ${u}`));
+	}
+
+	if (entry.relatedDomains?.length) {
+		sections.push("", "## Related Domains", `- ${entry.relatedDomains.join(", ")}`);
+	}
+
+	sections.push("", `Read \`xcsh://api-spec/${domain}?resource={name}\` for full endpoint specification.`, "");
+
+	return sections.join("\n");
+}
+
+function extractSchemaComponent(operationId: string): string | null {
+	const match = operationId.match(/^ves\.io\.schema\.(.+?)\.(?:API|CustomAPI)\./);
+	return match ? match[1] : null;
+}
+
+function groupPathsBySchema(spec: OpenAPISpec): Map<string, Record<string, Record<string, unknown>>> {
+	const groups = new Map<string, Record<string, Record<string, unknown>>>();
+
+	for (const [pathKey, methods] of Object.entries(spec.paths)) {
+		for (const [method, op] of Object.entries(methods)) {
+			if (typeof op !== "object" || !op) continue;
+			const opId = (op as Record<string, unknown>).operationId as string | undefined;
+			if (!opId) continue;
+			const schema = extractSchemaComponent(opId);
+			if (!schema) continue;
+			if (!groups.has(schema)) {
+				groups.set(schema, {});
+			}
+			const group = groups.get(schema)!;
+			if (!group[pathKey]) group[pathKey] = {};
+			group[pathKey][method] = op as Record<string, unknown>;
+		}
+	}
+
+	return groups;
+}
+
+function filterPathsByResource(spec: OpenAPISpec, resource: string): Record<string, Record<string, unknown>> {
+	const groups = groupPathsBySchema(spec);
+
+	const exactKey = resource.replace(/-/g, "_");
+	if (groups.has(exactKey)) {
+		return groups.get(exactKey)!;
+	}
+
+	const partial = new Map<string, Record<string, Record<string, unknown>>>();
+	for (const [schema, paths] of groups) {
+		const schemaEnd = schema.split(".").at(-1) ?? schema;
+		if (
+			schemaEnd === exactKey ||
+			schemaEnd.includes(exactKey) ||
+			exactKey.includes(schemaEnd) ||
+			schema === exactKey ||
+			schema.endsWith(`.${exactKey}`)
+		) {
+			for (const [path, methods] of Object.entries(paths)) {
+				if (!partial.has("merged")) partial.set("merged", {});
+				const merged = partial.get("merged")!;
+				if (!merged[path]) merged[path] = {};
+				Object.assign(merged[path], methods);
+			}
+		}
+	}
+	if (partial.size > 0) {
+		return partial.get("merged") ?? {};
+	}
+
+	const pluralized = exactKey.endsWith("s") ? exactKey : `${exactKey}s`;
+	const result: Record<string, Record<string, unknown>> = {};
+	for (const [pathKey, methods] of Object.entries(spec.paths)) {
+		const segments = pathKey.split("/");
+		if (segments.some(s => s === pluralized || s === exactKey)) {
+			result[pathKey] = methods;
+		}
+	}
+	return result;
+}
+
+function renderResourceSpec(_domain: string, resource: string, spec: OpenAPISpec): string {
+	const matchingPaths = filterPathsByResource(spec, resource);
+	const sections = [`# ${resource} — Full API Specification`, ""];
+
+	for (const [pathKey, methods] of Object.entries(matchingPaths)) {
+		for (const [method, op] of Object.entries(methods)) {
+			if (typeof op !== "object" || !op) continue;
+			const operation = op as Record<string, unknown>;
+			sections.push(`## ${method.toUpperCase()} ${pathKey}`, "");
+			if (operation.summary) sections.push(String(operation.summary), "");
+
+			const params = operation.parameters as Array<Record<string, unknown>> | undefined;
+			if (params?.length) {
+				sections.push("### Parameters", "");
+				sections.push("| Name | In | Required | Type | Description |");
+				sections.push("|------|-----|----------|------|-------------|");
+				for (const p of params) {
+					const schema = (p.schema as Record<string, unknown>) ?? {};
+					sections.push(
+						`| ${p.name} | ${p.in} | ${p.required ? "yes" : "no"} | ${schema.type ?? "unknown"} | ${p.description ?? ""} |`,
+					);
+				}
+				sections.push("");
+			}
+
+			const reqBody = operation.requestBody as Record<string, unknown> | undefined;
+			if (reqBody) {
+				sections.push("### Request Body", "");
+				const content = reqBody.content as Record<string, Record<string, unknown>> | undefined;
+				const jsonContent = content?.["application/json"];
+				if (jsonContent?.schema) {
+					const schema = resolveSchemaRef(jsonContent.schema as Record<string, unknown>, spec);
+					sections.push(renderSchemaAsTable(schema, spec));
+				}
+			}
+
+			const responses = operation.responses as Record<string, Record<string, unknown>> | undefined;
+			if (responses) {
+				for (const [status, resp] of Object.entries(responses)) {
+					if (typeof resp !== "object" || !resp) continue;
+					const respContent = (resp as Record<string, unknown>).content as
+						| Record<string, Record<string, unknown>>
+						| undefined;
+					const jsonResp = respContent?.["application/json"];
+					if (jsonResp?.schema) {
+						sections.push(`### Response ${status}`, "");
+						const schema = resolveSchemaRef(jsonResp.schema as Record<string, unknown>, spec);
+						sections.push(renderSchemaAsTable(schema, spec));
+					}
+				}
+			}
+
+			sections.push("---", "");
+		}
+	}
+
+	return sections.join("\n");
+}
+
+function renderPathSpec(_domain: string, pathKey: string, spec: OpenAPISpec): string {
+	const methods = spec.paths[pathKey];
+	if (!methods) {
+		const available = Object.keys(spec.paths).slice(0, 10);
+		return [`# Path not found: ${pathKey}`, "", "Available paths:", ...available.map(p => `- \`${p}\``), ""].join(
+			"\n",
+		);
+	}
+
+	const sections = [`# ${pathKey}`, ""];
+
+	for (const [method, op] of Object.entries(methods)) {
+		if (typeof op !== "object" || !op) continue;
+		const operation = op as Record<string, unknown>;
+		sections.push(`## ${method.toUpperCase()}`, "");
+		if (operation.summary) sections.push(String(operation.summary), "");
+	}
+
+	return sections.join("\n");
+}
+
+function resolveSchemaRef(schema: Record<string, unknown>, spec: OpenAPISpec): Record<string, unknown> {
+	const ref = schema.$ref as string | undefined;
+	if (!ref) return schema;
+
+	const match = ref.match(/^#\/components\/schemas\/(.+)$/);
+	if (!match) return schema;
+
+	const schemaName = match[1];
+	const resolved = spec.components?.schemas?.[schemaName];
+	return (resolved as Record<string, unknown>) ?? schema;
+}
+
+function renderSchemaAsTable(schema: Record<string, unknown>, spec: OpenAPISpec, depth = 0, prefix = ""): string {
+	if (depth > SCHEMA_RENDER_MAX_DEPTH) return "";
+
+	const resolved = resolveSchemaRef(schema, spec);
+	const properties = resolved.properties as Record<string, Record<string, unknown>> | undefined;
+	if (!properties) {
+		const type = (resolved.type as string) ?? "object";
+		return `Type: ${type}\n`;
+	}
+
+	const required = (resolved.required as string[]) ?? [];
+	const rows: string[] = [];
+
+	if (depth === 0) {
+		rows.push("| Field | Type | Required | Description |");
+		rows.push("|-------|------|----------|-------------|");
+	}
+
+	for (const [name, prop] of Object.entries(properties)) {
+		const fieldProp = resolveSchemaRef(prop, spec);
+		const fieldName = prefix ? `${prefix}.${name}` : name;
+		const type = (fieldProp.type as string) ?? "object";
+		const desc = (fieldProp.description as string) ?? "";
+		const isRequired = required.includes(name) ? "yes" : "no";
+
+		rows.push(`| ${fieldName} | ${type} | ${isRequired} | ${desc} |`);
+
+		if (type === "object" && fieldProp.properties && depth < SCHEMA_RENDER_MAX_DEPTH) {
+			const nested = renderSchemaAsTable(fieldProp, spec, depth + 1, fieldName);
+			const nestedLines = nested.split("\n").filter(l => l.startsWith("|") && !l.startsWith("| Field"));
+			rows.push(...nestedLines);
+		}
+	}
+
+	rows.push("");
+	return rows.join("\n");
+}
+
+function renderUnknownDomain(requested: string, index: ApiSpecIndex): string {
+	const suggestions = index.domains
+		.filter(d => d.domain.includes(requested) || requested.includes(d.domain.slice(0, 3)))
+		.slice(0, 5);
+
+	const sections = [`# Domain not found: ${requested}`, ""];
+
+	if (suggestions.length > 0) {
+		sections.push("Did you mean:", ...suggestions.map(d => `- \`${d.domain}\` — ${d.descriptionShort}`), "");
+	}
+
+	sections.push("Available domains:", ...index.domains.map(d => `- \`${d.domain}\` — ${d.descriptionShort}`), "");
+
+	return sections.join("\n");
+}
+
+function renderUnknownResource(requested: string, entry: ApiSpecDomainEntry, spec: OpenAPISpec): string {
+	const groups = groupPathsBySchema(spec);
+	const schemaNames = [...groups.keys()].sort();
+
+	return [
+		`# Resource not found: ${requested}`,
+		"",
+		`Available resources in ${entry.domain} (from API operations):`,
+		...schemaNames.map(s => `- \`${s}\``),
+		"",
+		`Use \`xcsh://api-spec/${entry.domain}?resource={name}\` with one of the above.`,
+		"",
+	].join("\n");
+}

package/src/internal-urls/api-spec-types.ts

@@ -0,0 +1,55 @@
+/**
+ * Types for the embedded API specification index and domain specs.
+ *
+ * These types define the shape of data generated at build time by
+ * scripts/generate-api-spec-index.ts from the api-specs-enriched repository.
+ */
+
+export interface ApiSpecDomainResource {
+	readonly name: string;
+	readonly description: string;
+}
+
+export interface ApiSpecDomainEntry {
+	readonly domain: string;
+	readonly title: string;
+	readonly description: string;
+	readonly descriptionShort: string;
+	readonly category: string;
+	readonly pathCount: number;
+	readonly schemaCount: number;
+	readonly complexity: string;
+	readonly resources: readonly ApiSpecDomainResource[];
+	readonly useCases?: readonly string[];
+	readonly relatedDomains?: readonly string[];
+}
+
+export interface ApiSpecIndex {
+	readonly version: string;
+	readonly timestamp: string;
+	readonly domains: readonly ApiSpecDomainEntry[];
+}
+
+export interface OpenAPIPathOperation {
+	readonly summary?: string;
+	readonly description?: string;
+	readonly operationId?: string;
+	readonly parameters?: readonly Record<string, unknown>[];
+	readonly requestBody?: Record<string, unknown>;
+	readonly responses?: Record<string, unknown>;
+	readonly [key: string]: unknown;
+}
+
+export interface OpenAPISpec {
+	readonly info: {
+		readonly title: string;
+		readonly version: string;
+		readonly [key: string]: unknown;
+	};
+	readonly paths: Record<string, Record<string, OpenAPIPathOperation>>;
+	readonly components?: {
+		readonly schemas?: Record<string, Record<string, unknown>>;
+		readonly [key: string]: unknown;
+	};
+	readonly [key: string]: unknown;
+}

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

@@ -17,17 +17,17 @@ export interface BuildInfo {
 }
 
 export const BUILD_INFO: BuildInfo = {
-	"version": "18.28.1",
-	"commit": "42862f837ad12f42e37bc29e47ab6f58be779de0",
-	"shortCommit": "42862f8",
+	"version": "18.30.0",
+	"commit": "72667c39746cfce92ec26d5d81f2a99617e1d4fe",
+	"shortCommit": "72667c3",
 	"branch": "main",
-	"tag": "v18.28.1",
-	"commitDate": "2026-04-30T11:56:41Z",
-	"buildDate": "2026-04-30T12:21:15.369Z",
+	"tag": "v18.30.0",
+	"commitDate": "2026-05-01T03:26:38Z",
+	"buildDate": "2026-05-01T03:52:47.886Z",
 	"dirty": false,
 	"prNumber": "",
 	"repoUrl": "https://github.com/f5xc-salesdemos/xcsh",
 	"repoSlug": "f5xc-salesdemos/xcsh",
-	"commitUrl": "https://github.com/f5xc-salesdemos/xcsh/commit/42862f837ad12f42e37bc29e47ab6f58be779de0",
-	"releaseUrl": "https://github.com/f5xc-salesdemos/xcsh/releases/tag/v18.28.1"
+	"commitUrl": "https://github.com/f5xc-salesdemos/xcsh/commit/72667c39746cfce92ec26d5d81f2a99617e1d4fe",
+	"releaseUrl": "https://github.com/f5xc-salesdemos/xcsh/releases/tag/v18.30.0"
 };

package/src/internal-urls/index.ts

@@ -21,6 +21,8 @@
  */
 
 export * from "./agent-protocol";
+export * from "./api-spec-resolve";
+export * from "./api-spec-types";
 export * from "./artifact-protocol";
 export * from "./jobs-protocol";
 export * from "./json-query";

package/src/internal-urls/xcsh-protocol.ts

@@ -8,21 +8,49 @@
  * - xcsh:// - Lists all available documentation files
  * - xcsh://<file>.md - Reads a specific documentation file
  * - xcsh://about - Identity fingerprint (version, commit, branch, repo)
+ * - xcsh://api-spec/ - API specification index
+ * - xcsh://api-spec/{domain} - Domain detail
+ * - xcsh://api-spec/{domain}?resource={name} - Resource spec
  */
 import * as path from "node:path";
 import type { ContextStatus } from "../services/f5xc-context";
+import { type ApiSpecResolver, createApiSpecResolver } from "./api-spec-resolve";
+import type { ApiSpecIndex } from "./api-spec-types";
 import { getRuntimeBuildInfo, type RuntimeBuildInfo, renderAboutDoc } from "./build-info-runtime";
 import { EMBEDDED_DOC_FILENAMES, EMBEDDED_DOCS } from "./docs-index.generated";
 import type { InternalResource, InternalUrl, ProtocolHandler } from "./types";
 
 const SCHEME_PREFIX = "xcsh://";
 const ABOUT_ROUTE = "about";
+const API_SPEC_HOST = "api-spec";
+
+const EMPTY_INDEX: ApiSpecIndex = { version: "unknown", timestamp: "", domains: [] };
+
+let _apiSpecCache: { index: ApiSpecIndex; blobs: Record<string, string>; version: string } | null = null;
+
+function loadApiSpecs(): { index: ApiSpecIndex; blobs: Record<string, string>; version: string } {
+	if (_apiSpecCache) return _apiSpecCache;
+	try {
+		// eslint-disable-next-line @typescript-eslint/no-require-imports
+		const mod = require("./api-spec-index.generated");
+		_apiSpecCache = {
+			index: mod.API_SPEC_INDEX ?? EMPTY_INDEX,
+			blobs: mod.API_SPEC_BLOBS ?? {},
+			version: mod.API_SPEC_VERSION ?? "unknown",
+		};
+	} catch {
+		_apiSpecCache = { index: EMPTY_INDEX, blobs: {}, version: "unknown" };
+	}
+	return _apiSpecCache;
+}
 
 export interface InternalDocsProtocolOptions {
 	/** Override runtime build-info resolution. Primarily for tests. */
 	readonly resolveBuildInfo?: () => Promise<RuntimeBuildInfo>;
 	/** Sync getter returning the current context status (or null if unconfigured / unavailable). */
 	readonly getContextStatus?: () => ContextStatus | null;
+	/** Override the API spec resolver. Primarily for tests. */
+	readonly apiSpecResolver?: ApiSpecResolver;
 }
 
 /**
@@ -35,14 +63,29 @@ export class InternalDocsProtocolHandler implements ProtocolHandler {
 	readonly scheme = "xcsh";
 	readonly #resolveBuildInfo: () => Promise<RuntimeBuildInfo>;
 	readonly #getContextStatus: (() => ContextStatus | null) | undefined;
+	#apiSpecResolver: ApiSpecResolver | null;
 
 	constructor(options: InternalDocsProtocolOptions = {}) {
 		this.#resolveBuildInfo = options.resolveBuildInfo ?? getRuntimeBuildInfo;
 		this.#getContextStatus = options.getContextStatus;
+		this.#apiSpecResolver = options.apiSpecResolver ?? null;
+	}
+
+	#getApiSpecResolver(): ApiSpecResolver {
+		if (!this.#apiSpecResolver) {
+			const specs = loadApiSpecs();
+			this.#apiSpecResolver = createApiSpecResolver(specs.index, specs.blobs);
+		}
+		return this.#apiSpecResolver;
 	}
 
 	async resolve(url: InternalUrl): Promise<InternalResource> {
 		const host = url.rawHost || url.hostname;
+
+		if (host === API_SPEC_HOST) {
+			return this.#getApiSpecResolver().resolve(url);
+		}
+
 		const pathname = url.rawPathname ?? url.pathname;
 		const filename = host ? (pathname && pathname !== "/" ? host + pathname : host) : "";
 
@@ -58,9 +101,15 @@ export class InternalDocsProtocolHandler implements ProtocolHandler {
 			throw new Error("No documentation files found");
 		}
 
+		const specs = loadApiSpecs();
 		const syntheticEntry = `- [${ABOUT_ROUTE}](${SCHEME_PREFIX}${ABOUT_ROUTE}) — identity and build fingerprint`;
-		const listing = [syntheticEntry, ...EMBEDDED_DOC_FILENAMES.map(f => `- [${f}](${SCHEME_PREFIX}${f})`)].join("\n");
-		const totalCount = EMBEDDED_DOC_FILENAMES.length + 1;
+		const apiSpecEntry = `- [${API_SPEC_HOST}/](${SCHEME_PREFIX}${API_SPEC_HOST}/) — F5 XC API specifications (${specs.index.domains.length} domains, v${specs.version})`;
+		const listing = [
+			syntheticEntry,
+			apiSpecEntry,
+			...EMBEDDED_DOC_FILENAMES.map(f => `- [${f}](${SCHEME_PREFIX}${f})`),
+		].join("\n");
+		const totalCount = EMBEDDED_DOC_FILENAMES.length + 2;
 		const content = `# Documentation\n\n${totalCount} files available:\n\n${listing}\n`;
 
 		return {

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

@@ -189,6 +189,12 @@ Most tools resolve custom protocol URLs to internal resources (not web URLs):
 - `mcp://<resource-uri>` — MCP resource from a connected server; matched against exact resource URIs first, then RFC 6570 URI templates advertised by connected servers
 - `xcsh://..` — Internal xcsh documentation. **MUST NOT** read unless the user asks about xcsh itself.
   - `xcsh://about` — Identity, version, build fingerprint, architecture, self-improvement. **MUST** read for any question about xcsh before exploring `~/.xcsh/`.
+- `xcsh://api-spec/` — F5 Distributed Cloud API specifications ({{apiSpecDomainCount}} domains, v{{apiSpecVersion}}).
+  **MUST NOT** read proactively. When the user needs to interact with the F5 XC API:
+  1. Read `xcsh://api-spec/` to identify the correct domain
+  2. Read `xcsh://api-spec/{domain}` to find the resource and operations
+  3. Read `xcsh://api-spec/{domain}?resource={name}` for full endpoint specification
+  Never guess API paths or request schemas — always consult the spec first.
 
 In `bash`, URIs auto-resolve to filesystem paths (e.g., `python skill://my-skill/scripts/init.py`).
 

package/src/system-prompt.ts

@@ -16,6 +16,31 @@ import { isApplicableToContext, loadSkills, type Skill } from "./extensibility/s
 import customSystemPromptTemplate from "./prompts/system/custom-system-prompt.md" with { type: "text" };
 import systemPromptTemplate from "./prompts/system/system-prompt.md" with { type: "text" };
 
+let _apiSpecMeta: { domainCount: number; version: string } | null = null;
+
+function getApiSpecMeta(): { domainCount: number; version: string } {
+	if (_apiSpecMeta) return _apiSpecMeta;
+	try {
+		// eslint-disable-next-line @typescript-eslint/no-require-imports
+		const mod = require("./internal-urls/api-spec-index.generated");
+		_apiSpecMeta = {
+			domainCount: mod.API_SPEC_INDEX?.domains?.length ?? 0,
+			version: mod.API_SPEC_VERSION ?? "unknown",
+		};
+	} catch {
+		_apiSpecMeta = { domainCount: 0, version: "unknown" };
+	}
+	return _apiSpecMeta;
+}
+
+function apiSpecDomainCount(): number {
+	return getApiSpecMeta().domainCount;
+}
+
+function apiSpecVersion(): string {
+	return getApiSpecMeta().version;
+}
+
 interface AlwaysApplyRule {
 	name: string;
 	content: string;
@@ -633,6 +658,8 @@ export async function buildSystemPrompt(options: BuildSystemPromptOptions = {}):
 		secretsEnabled,
 		context,
 		knowledgeTopics: options.knowledgeTopics,
+		apiSpecDomainCount: apiSpecDomainCount(),
+		apiSpecVersion: apiSpecVersion(),
 	};
 	let rendered = prompt.render(resolvedCustomPrompt ? customSystemPromptTemplate : systemPromptTemplate, data);