@f5xc-salesdemos/xcsh 18.30.4 → 18.31.0

package/package.json

@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@f5xc-salesdemos/xcsh",
-	"version": "18.30.4",
+	"version": "18.31.0",
 	"description": "Coding agent CLI with read, bash, edit, write tools and session management",
 	"homepage": "https://github.com/f5xc-salesdemos/xcsh",
 	"author": "Can Boluk",
@@ -48,12 +48,12 @@
 	"dependencies": {
 		"@agentclientprotocol/sdk": "0.16.1",
 		"@mozilla/readability": "^0.6",
-		"@f5xc-salesdemos/xcsh-stats": "18.30.4",
-		"@f5xc-salesdemos/pi-agent-core": "18.30.4",
-		"@f5xc-salesdemos/pi-ai": "18.30.4",
-		"@f5xc-salesdemos/pi-natives": "18.30.4",
-		"@f5xc-salesdemos/pi-tui": "18.30.4",
-		"@f5xc-salesdemos/pi-utils": "18.30.4",
+		"@f5xc-salesdemos/xcsh-stats": "18.31.0",
+		"@f5xc-salesdemos/pi-agent-core": "18.31.0",
+		"@f5xc-salesdemos/pi-ai": "18.31.0",
+		"@f5xc-salesdemos/pi-natives": "18.31.0",
+		"@f5xc-salesdemos/pi-tui": "18.31.0",
+		"@f5xc-salesdemos/pi-utils": "18.31.0",
 		"@sinclair/typebox": "^0.34",
 		"@xterm/headless": "^6.0",
 		"ajv": "^8.18",

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

@@ -11,10 +11,6 @@ interface SpecPathOperation {
 	[key: string]: unknown;
 }
 
-/**
- * Finds the operationId schema components (e.g., 'dns_zone', 'views.forward_proxy_policy')
- * that correspond to a given resource name by matching path segments.
- */
 function findResourceSchemaComponents(
 	resourceName: string,
 	paths: Record<string, Record<string, SpecPathOperation>>,
@@ -38,11 +34,29 @@ function findResourceSchemaComponents(
 	return [...found];
 }
 
+interface IndexEntryResource {
+	name: string;
+	description: string;
+	description_short?: string;
+	tier?: string;
+	icon?: string;
+	supports_logs?: boolean;
+	supports_metrics?: boolean;
+	dependencies?: { required: string[]; optional: string[] };
+	relationship_hints?: string[];
+	schema_components?: string[];
+	api_paths?: string[];
+}
+
 interface IndexEntry {
 	domain: string;
 	title: string;
 	description: string;
 	"x-f5xc-description-short": string;
+	"x-f5xc-description-medium"?: string;
+	"x-f5xc-icon"?: string;
+	"x-f5xc-is-preview"?: boolean;
+	"x-f5xc-requires-tier"?: string;
 	file: string;
 	path_count: number;
 	schema_count: number;
@@ -50,18 +64,23 @@ interface IndexEntry {
 	"x-f5xc-category": string;
 	"x-f5xc-use-cases"?: string[];
 	"x-f5xc-related-domains"?: string[];
-	"x-f5xc-primary-resources"?: Array<{ name: string; description: string }>;
+	"x-f5xc-primary-resources"?: IndexEntryResource[];
 }
 
 interface RawIndex {
 	version: string;
 	timestamp: string;
 	specifications: IndexEntry[];
+	"x-f5xc-critical-resources"?: string[];
+	"x-f5xc-guided-workflows"?: Record<string, unknown>;
+	"x-f5xc-error-resolution"?: Record<string, unknown>;
+	"x-f5xc-acronyms"?: Record<string, unknown>;
 }
 
 const REPO = "f5xc-salesdemos/api-specs-enriched";
-const PINNED_TAG = "v2.1.62";
+const PINNED_TAG = "v2.1.63";
 const outputPath = path.resolve(import.meta.dir, "../src/internal-urls/api-spec-index.generated.ts");
+const catalogOutputPath = path.resolve(import.meta.dir, "../src/internal-urls/api-catalog-index.generated.ts");
 
 async function downloadFromRelease(): Promise<string> {
 	const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "api-specs-"));
@@ -114,6 +133,34 @@ async function findSpecsDir(): Promise<string> {
 	return downloadFromRelease();
 }
 
+async function downloadCatalog(specsDir: string): Promise<Record<string, unknown> | null> {
+	const catalogPath = path.join(specsDir, "api-catalog.json");
+	if (fs.existsSync(catalogPath)) {
+		return JSON.parse(fs.readFileSync(catalogPath, "utf-8"));
+	}
+
+	const tag = process.env.API_SPECS_TAG ?? PINNED_TAG;
+	const catalogUrl = `https://github.com/${REPO}/releases/download/${tag}/api-catalog.json`;
+	console.log(`Downloading API catalog from ${catalogUrl}...`);
+	try {
+		const response = await fetch(catalogUrl, { redirect: "follow" });
+		if (!response.ok) {
+			console.warn(`api-catalog.json not found (${response.status}), skipping catalog generation`);
+			return null;
+		}
+		const text = await response.text();
+		return JSON.parse(text);
+	} catch (err) {
+		console.warn(`Failed to download api-catalog.json: ${err instanceof Error ? err.message : err}`);
+		return null;
+	}
+}
+
+function serializeEnrichment(key: string, value: unknown): string | undefined {
+	if (!value) return undefined;
+	return `\t${key}: ${JSON.stringify(value)},`;
+}
+
 let downloadedTmpDir: string | null = null;
 
 const specsDir = await findSpecsDir();
@@ -149,9 +196,22 @@ for (const entry of rawIndex.specifications) {
 	const b64 = compressed.toString("base64");
 
 	const resources = (entry["x-f5xc-primary-resources"] ?? []).map(r => {
-		const schemaComponents = findResourceSchemaComponents(r.name, specJson.paths ?? {});
-		const scStr = schemaComponents.length > 0 ? `, schemaComponents: ${JSON.stringify(schemaComponents)}` : "";
-		return `\t\t\t{ name: ${JSON.stringify(r.name)}, description: ${JSON.stringify(r.description)}${scStr} },`;
+		const upstreamSc = r.schema_components ?? [];
+		const schemaComponents =
+			upstreamSc.length > 0 ? upstreamSc : findResourceSchemaComponents(r.name, specJson.paths ?? {});
+		const fields: string[] = [`name: ${JSON.stringify(r.name)}`, `description: ${JSON.stringify(r.description)}`];
+		if (schemaComponents.length > 0) fields.push(`schemaComponents: ${JSON.stringify(schemaComponents)}`);
+		if (r.api_paths?.length) fields.push(`apiPaths: ${JSON.stringify(r.api_paths)}`);
+		if (r.tier) fields.push(`tier: ${JSON.stringify(r.tier)}`);
+		if (r.icon) fields.push(`icon: ${JSON.stringify(r.icon)}`);
+		if (r.description_short) fields.push(`descriptionShort: ${JSON.stringify(r.description_short)}`);
+		if (r.supports_logs != null) fields.push(`supportsLogs: ${r.supports_logs}`);
+		if (r.supports_metrics != null) fields.push(`supportsMetrics: ${r.supports_metrics}`);
+		if (r.dependencies && (r.dependencies.required.length > 0 || r.dependencies.optional.length > 0)) {
+			fields.push(`dependencies: ${JSON.stringify(r.dependencies)}`);
+		}
+		if (r.relationship_hints?.length) fields.push(`relationshipHints: ${JSON.stringify(r.relationship_hints)}`);
+		return `\t\t\t{ ${fields.join(", ")} },`;
 	});
 
 	const useCases = entry["x-f5xc-use-cases"];
@@ -173,6 +233,14 @@ for (const entry of rawIndex.specifications) {
 			`\t\t\t],`,
 			useCases ? `\t\t\tuseCases: ${JSON.stringify(useCases)},` : undefined,
 			relatedDomains?.length ? `\t\t\trelatedDomains: ${JSON.stringify(relatedDomains)},` : undefined,
+			entry["x-f5xc-icon"] ? `\t\t\ticon: ${JSON.stringify(entry["x-f5xc-icon"])},` : undefined,
+			entry["x-f5xc-description-medium"]
+				? `\t\t\tdescriptionMedium: ${JSON.stringify(entry["x-f5xc-description-medium"])},`
+				: undefined,
+			entry["x-f5xc-is-preview"] ? `\t\t\tisPreview: true,` : undefined,
+			entry["x-f5xc-requires-tier"]
+				? `\t\t\trequiresTier: ${JSON.stringify(entry["x-f5xc-requires-tier"])},`
+				: undefined,
 			"\t\t},",
 		]
 			.filter(Boolean)
@@ -183,6 +251,11 @@ for (const entry of rawIndex.specifications) {
 	processedCount++;
 }
 
+const criticalResources = rawIndex["x-f5xc-critical-resources"];
+const guidedWorkflows = rawIndex["x-f5xc-guided-workflows"];
+const errorResolution = rawIndex["x-f5xc-error-resolution"];
+const acronyms = rawIndex["x-f5xc-acronyms"];
+
 const output = [
 	"// Auto-generated by scripts/generate-api-spec-index.ts - DO NOT EDIT",
 	"",
@@ -196,13 +269,19 @@ const output = [
 	`\tdomains: [`,
 	...domainEntries,
 	`\t],`,
+	serializeEnrichment("criticalResources", criticalResources),
+	serializeEnrichment("guidedWorkflows", guidedWorkflows),
+	serializeEnrichment("errorResolution", errorResolution),
+	serializeEnrichment("acronyms", acronyms),
 	`};`,
 	"",
 	`export const API_SPEC_BLOBS: Readonly<Record<string, string>> = {`,
 	...blobEntries,
 	`};`,
 	"",
-].join("\n");
+]
+	.filter(l => l !== undefined)
+	.join("\n");
 
 await Bun.write(outputPath, output);
 
@@ -211,6 +290,53 @@ console.log(
 	`Generated ${path.relative(process.cwd(), outputPath)} (${processedCount} domains, ${skippedCount} skipped, ${outputSize} MB)`,
 );
 
+// Generate API catalog index
+const catalog = await downloadCatalog(specsDir);
+if (catalog) {
+	const categories = (catalog.categories ?? []) as Array<{ name: string; displayName: string; operations: unknown[] }>;
+	const catalogBlobEntries: string[] = [];
+	const catalogIndexEntries: string[] = [];
+
+	for (const cat of categories) {
+		const catJson = JSON.stringify(cat);
+		const catCompressed = gzipSync(Buffer.from(catJson));
+		catalogBlobEntries.push(`\t${JSON.stringify(cat.name)}: ${JSON.stringify(catCompressed.toString("base64"))},`);
+		catalogIndexEntries.push(
+			`\t\t{ name: ${JSON.stringify(cat.name)}, displayName: ${JSON.stringify(cat.displayName)}, operationCount: ${cat.operations?.length ?? 0} },`,
+		);
+	}
+
+	const catalogOutput = [
+		"// Auto-generated by scripts/generate-api-spec-index.ts - DO NOT EDIT",
+		"",
+		`import type { ApiCatalogCategorySummary, ApiCatalogIndex } from "./api-catalog-types";`,
+		"",
+		`export const API_CATALOG_INDEX: ApiCatalogIndex = {`,
+		`\tversion: ${JSON.stringify(catalog.version ?? "unknown")},`,
+		`\tdisplayName: ${JSON.stringify(catalog.displayName ?? "F5 Distributed Cloud")},`,
+		`\tservice: ${JSON.stringify(catalog.service ?? "f5xc")},`,
+		`\tcategoryCount: ${categories.length},`,
+		`\tauth: ${JSON.stringify(catalog.auth ?? {})},`,
+		`\tdefaults: ${JSON.stringify(catalog.defaults ?? {})},`,
+		`};`,
+		"",
+		`export const API_CATALOG_CATEGORY_SUMMARIES: ReadonlyArray<ApiCatalogCategorySummary> = [`,
+		...catalogIndexEntries,
+		`];`,
+		"",
+		`export const API_CATALOG_BLOBS: Readonly<Record<string, string>> = {`,
+		...catalogBlobEntries,
+		`};`,
+		"",
+	].join("\n");
+
+	await Bun.write(catalogOutputPath, catalogOutput);
+	const catalogSize = (Buffer.byteLength(catalogOutput) / 1024 / 1024).toFixed(1);
+	console.log(
+		`Generated ${path.relative(process.cwd(), catalogOutputPath)} (${categories.length} categories, ${catalogSize} MB)`,
+	);
+}
+
 if (downloadedTmpDir) {
 	fs.rmSync(downloadedTmpDir, { recursive: true, force: true });
 }

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

@@ -0,0 +1,177 @@
+import { gunzipSync } from "node:zlib";
+import { LRUCache } from "lru-cache";
+import type { ApiCatalogCategory, ApiCatalogCategorySummary, ApiCatalogIndex } from "./api-catalog-types";
+import type { InternalResource, InternalUrl } from "./types";
+
+const LRU_CAPACITY = 5;
+
+export interface ApiCatalogResolver {
+	resolve(url: InternalUrl): Promise<InternalResource>;
+}
+
+export function createApiCatalogResolver(
+	index: ApiCatalogIndex,
+	categorySummaries: readonly ApiCatalogCategorySummary[],
+	blobs: Record<string, string>,
+): ApiCatalogResolver {
+	const cache = new LRUCache<string, ApiCatalogCategory>({ max: LRU_CAPACITY });
+
+	function decompress(category: string): ApiCatalogCategory {
+		const cached = cache.get(category);
+		if (cached) return cached;
+
+		const blob = blobs[category];
+		if (!blob) throw new Error(`No catalog blob for category: ${category}`);
+
+		const buffer = Buffer.from(blob, "base64");
+		const decompressed = gunzipSync(buffer);
+		const cat = JSON.parse(decompressed.toString("utf-8")) as ApiCatalogCategory;
+		cache.set(category, cat);
+		return cat;
+	}
+
+	return {
+		async resolve(url: InternalUrl): Promise<InternalResource> {
+			const pathname = url.rawPathname ?? url.pathname;
+			const category = pathname.replace(/^\//, "").replace(/\/$/, "");
+			const search = url.searchParams.get("search");
+
+			if (!category) {
+				const content = search
+					? renderCatalogSearch(index, categorySummaries, search)
+					: renderCatalogIndex(index, categorySummaries);
+				return makeResource(url, content);
+			}
+
+			const summary = categorySummaries.find(c => c.name === category);
+			if (!summary) {
+				return makeResource(url, renderUnknownCategory(category, categorySummaries));
+			}
+
+			try {
+				const cat = decompress(category);
+				return makeResource(url, renderCatalogDetail(cat, index));
+			} catch (err) {
+				const message = err instanceof Error ? err.message : String(err);
+				return makeResource(url, `# Error loading ${category}\n\n${message}\n`);
+			}
+		},
+	};
+}
+
+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 renderCatalogIndex(index: ApiCatalogIndex, summaries: readonly ApiCatalogCategorySummary[]): string {
+	const rows = summaries.map(c => `| ${c.name} | ${c.displayName} | ${c.operationCount} |`);
+
+	return [
+		`# F5 XC API Catalog (v${index.version})`,
+		"",
+		`${summaries.length} categories. Read \`xcsh://api-catalog/{category}\` for operation details.`,
+		"",
+		"| Category | Display Name | Operations |",
+		"|----------|--------------|------------|",
+		...rows,
+		"",
+	].join("\n");
+}
+
+function renderCatalogSearch(
+	_index: ApiCatalogIndex,
+	summaries: readonly ApiCatalogCategorySummary[],
+	term: string,
+): string {
+	const lower = term.toLowerCase();
+	const matches = summaries.filter(
+		c => c.name.toLowerCase().includes(lower) || c.displayName.toLowerCase().includes(lower),
+	);
+
+	if (matches.length === 0) {
+		return [
+			`# No categories matching "${term}"`,
+			"",
+			`Use \`xcsh://api-catalog/\` to see all ${summaries.length} categories.`,
+			"",
+		].join("\n");
+	}
+
+	const rows = matches.map(c => `| ${c.name} | ${c.displayName} | ${c.operationCount} |`);
+
+	return [
+		`# API Catalog — search: "${term}"`,
+		"",
+		`${matches.length} matching categories.`,
+		"",
+		"| Category | Display Name | Operations |",
+		"|----------|--------------|------------|",
+		...rows,
+		"",
+	].join("\n");
+}
+
+function renderCatalogDetail(cat: ApiCatalogCategory, index: ApiCatalogIndex): string {
+	const sections: string[] = [`# ${cat.displayName}`, "", `${cat.operations.length} operations.`];
+
+	for (const op of cat.operations) {
+		sections.push("", `## ${op.method.toUpperCase()} ${op.path}`, "");
+		sections.push(op.description);
+		sections.push(`Danger level: ${op.dangerLevel}`);
+
+		if (op.parameters.length > 0) {
+			sections.push("", "### Parameters", "");
+			sections.push("| Name | In | Required | Type | Default |");
+			sections.push("|------|-----|----------|------|---------|");
+			for (const p of op.parameters) {
+				sections.push(`| ${p.name} | ${p.in} | ${p.required ? "yes" : "no"} | ${p.type} | ${p.default ?? ""} |`);
+			}
+		}
+
+		if (op.bodySchema) {
+			const minConfig = (op.bodySchema as Record<string, unknown>)["x-f5xc-minimum-configuration"] as
+				| Record<string, unknown>
+				| undefined;
+			if (minConfig?.required_fields) {
+				sections.push("", "### Minimum Configuration");
+				sections.push(`Required fields: ${(minConfig.required_fields as string[]).join(", ")}`);
+			}
+		}
+
+		sections.push("", "### Curl Example", "", "```bash");
+		const tokenVar = `$${index.auth.tokenSource}`;
+		const authHeader = `${index.auth.headerName}: ${index.auth.headerTemplate.replace("$TOKEN", tokenVar).replace("{token}", tokenVar)}`;
+		sections.push(`curl -X ${op.method.toUpperCase()} "$${index.auth.baseUrlSource}${op.path}" \\`);
+		sections.push(`  -H "${authHeader}" \\`);
+		if (op.method.toUpperCase() !== "GET" && op.method.toUpperCase() !== "DELETE") {
+			sections.push('  -H "Content-Type: application/json" \\');
+			sections.push("  -d @payload.json");
+		} else {
+			const lastLine = sections[sections.length - 1];
+			sections[sections.length - 1] = lastLine.replace(/ \\$/, "");
+		}
+		sections.push("```");
+	}
+
+	sections.push("");
+	return sections.join("\n");
+}
+
+function renderUnknownCategory(requested: string, summaries: readonly ApiCatalogCategorySummary[]): string {
+	const suggestions = summaries
+		.filter(c => c.name.includes(requested) || requested.includes(c.name.slice(0, 4)))
+		.slice(0, 5);
+
+	const sections = [`# Category not found: ${requested}`, ""];
+	if (suggestions.length > 0) {
+		sections.push("Did you mean:", ...suggestions.map(c => `- \`${c.name}\` — ${c.displayName}`), "");
+	}
+	sections.push("Use `xcsh://api-catalog/` to see all categories.", "");
+	return sections.join("\n");
+}

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

@@ -0,0 +1,54 @@
+/**
+ * Types for the embedded API catalog index.
+ *
+ * The catalog provides pre-built curl templates and operation metadata
+ * generated at build time from api-catalog.json in the api-specs-enriched repository.
+ */
+
+export interface ApiCatalogParameter {
+	readonly name: string;
+	readonly in: string;
+	readonly required: boolean;
+	readonly type: string;
+	readonly default?: string;
+}
+
+export interface ApiCatalogOperation {
+	readonly name: string;
+	readonly description: string;
+	readonly method: string;
+	readonly path: string;
+	readonly dangerLevel: string;
+	readonly parameters: readonly ApiCatalogParameter[];
+	readonly bodySchema?: Record<string, unknown>;
+	readonly responseSchema?: Record<string, unknown>;
+}
+
+export interface ApiCatalogCategory {
+	readonly name: string;
+	readonly displayName: string;
+	readonly operations: readonly ApiCatalogOperation[];
+}
+
+export interface ApiCatalogAuth {
+	readonly type: string;
+	readonly headerName: string;
+	readonly headerTemplate: string;
+	readonly tokenSource: string;
+	readonly baseUrlSource: string;
+}
+
+export interface ApiCatalogIndex {
+	readonly version: string;
+	readonly displayName: string;
+	readonly service: string;
+	readonly categoryCount: number;
+	readonly auth: ApiCatalogAuth;
+	readonly defaults: Record<string, { readonly source: string }>;
+}
+
+export interface ApiCatalogCategorySummary {
+	readonly name: string;
+	readonly displayName: string;
+	readonly operationCount: number;
+}

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

@@ -6,8 +6,6 @@ import type { InternalResource, InternalUrl } from "./types";
 const LRU_CAPACITY = 5;
 const SCHEMA_RENDER_MAX_DEPTH = 3;
 
-// Module-level cache for groupPathsBySchema results, keyed by spec identity.
-// Different resolver instances create distinct OpenAPISpec objects so there is no cross-resolver leakage.
 const groupsCache = new WeakMap<OpenAPISpec, Map<string, Record<string, Record<string, OpenAPIPathOperation>>>>();
 
 function getCachedGroups(spec: OpenAPISpec): Map<string, Record<string, Record<string, OpenAPIPathOperation>>> {
@@ -55,6 +53,21 @@ export function createApiSpecResolver(index: ApiSpecIndex, blobs: Record<string,
 				return makeResource(url, renderDomainIndex(index));
 			}
 
+			// Reserved sub-paths — checked before domain lookup
+			if (domain === "workflows" || domain.startsWith("workflows/")) {
+				const workflowId = domain.replace(/^workflows\/?/, "");
+				return makeResource(url, workflowId ? renderWorkflowDetail(workflowId, index) : renderWorkflowIndex(index));
+			}
+
+			if (domain === "errors" || domain.startsWith("errors/")) {
+				const errorKey = domain.replace(/^errors\/?/, "");
+				return makeResource(url, errorKey ? renderErrorDetail(errorKey, index) : renderErrorIndex(index));
+			}
+
+			if (domain === "glossary" || domain.startsWith("glossary/")) {
+				return makeResource(url, renderGlossary(index));
+			}
+
 			const entry = index.domains.find(d => d.domain === domain);
 			if (!entry) {
 				return makeResource(url, renderUnknownDomain(domain, index));
@@ -99,24 +112,67 @@ function makeResource(url: InternalUrl, content: string): InternalResource {
 }
 
 function renderDomainIndex(index: ApiSpecIndex): string {
-	const rows = index.domains.map(
-		d => `| ${d.domain} | ${d.category} | ${d.resources.length} | ${d.pathCount} | ${d.descriptionShort} |`,
-	);
-
-	return [
+	const criticalSet = new Set(index.criticalResources ?? []);
+	const rows = index.domains.map(d => {
+		const icon = d.icon ?? "";
+		const tier = d.requiresTier ?? "";
+		const hasCritical = d.resources.some(r => criticalSet.has(r.name));
+		const desc = hasCritical ? `${d.descriptionShort} *` : d.descriptionShort;
+		return `| ${icon} | ${d.domain} | ${d.category} | ${d.resources.length} | ${d.pathCount} | ${tier} | ${desc} |`;
+	});
+
+	const lines = [
 		`# F5 XC API Specifications (v${index.version})`,
 		"",
 		`${index.domains.length} domains. Read \`xcsh://api-spec/{domain}\` for resource details.`,
 		"",
-		"| Domain | Category | Resources | Paths | Description |",
-		"|--------|----------|-----------|-------|-------------|",
+		"| Icon | Domain | Category | Resources | Paths | Tier | Description |",
+		"|------|--------|----------|-----------|-------|------|-------------|",
 		...rows,
 		"",
-	].join("\n");
+	];
+
+	if (criticalSet.size > 0) {
+		lines.push("\\* = contains critical resources", "");
+	}
+
+	return lines.join("\n");
 }
 
 function renderDomainDetail(domain: string, entry: ApiSpecDomainEntry, spec: OpenAPISpec): string {
-	const resourceRows = entry.resources.map(r => `| ${r.name} | ${r.description} |`);
+	const sections: string[] = [
+		`# ${entry.title} — F5 XC API`,
+		"",
+		`Category: ${entry.category} | Paths: ${entry.pathCount} | Complexity: ${entry.complexity}`,
+	];
+
+	if (entry.isPreview || entry.requiresTier === "Advanced") {
+		const tags: string[] = [];
+		if (entry.isPreview) tags.push("Preview API");
+		if (entry.requiresTier === "Advanced") tags.push("Requires Advanced tier");
+		sections.push("", `> ${tags.join(" | ")}`);
+	}
+
+	if (entry.descriptionMedium) {
+		sections.push("", entry.descriptionMedium);
+	}
+
+	sections.push("", "## Resources", "");
+	sections.push("| Resource | Description | Tier | Observability | Requires |");
+	sections.push("|----------|-------------|------|---------------|----------|");
+	for (const r of entry.resources) {
+		const tier = r.tier ?? "";
+		const obs: string[] = [];
+		if (r.supportsLogs) obs.push("logs");
+		if (r.supportsMetrics) obs.push("metrics");
+		const requires = r.dependencies?.required.join(", ") ?? "";
+		sections.push(`| ${r.name} | ${r.description} | ${tier} | ${obs.join(", ")} | ${requires} |`);
+	}
+
+	const hints = entry.resources.flatMap(r => r.relationshipHints ?? []);
+	if (hints.length > 0) {
+		sections.push("", "## Relationships", ...hints.map(h => `- ${h}`));
+	}
 
 	const operationRows: string[] = [];
 	for (const [pathKey, methods] of Object.entries(spec.paths)) {
@@ -127,23 +183,10 @@ function renderDomainDetail(domain: string, entry: ApiSpecDomainEntry, spec: Ope
 		}
 	}
 
-	const sections = [
-		`# ${entry.title} — F5 XC API`,
-		"",
-		`Category: ${entry.category} | Paths: ${entry.pathCount} | Complexity: ${entry.complexity}`,
-		"",
-		"## Resources",
-		"",
-		"| Resource | Description |",
-		"|----------|-------------|",
-		...resourceRows,
-		"",
-		"## Operations",
-		"",
-		"| Method | Path | Summary |",
-		"|--------|------|---------|",
-		...operationRows,
-	];
+	sections.push("", "## Operations", "");
+	sections.push("| Method | Path | Summary |");
+	sections.push("|--------|------|---------|");
+	sections.push(...operationRows);
 
 	if (entry.useCases?.length) {
 		sections.push("", "## Use Cases", ...entry.useCases.map(u => `- ${u}`));
@@ -190,7 +233,20 @@ function filterPathsByResource(
 	resource: string,
 	entry?: ApiSpecDomainEntry,
 ): Record<string, Record<string, OpenAPIPathOperation>> {
-	// Index-guided lookup: use pre-computed schemaComponents from the enriched index
+	// Primary: use pre-computed api_paths from enriched index
+	if (entry) {
+		const indexedResource = entry.resources.find(r => r.name === resource);
+		if (indexedResource?.apiPaths?.length) {
+			const result: Record<string, Record<string, OpenAPIPathOperation>> = {};
+			for (const ap of indexedResource.apiPaths) {
+				const methods = spec.paths[ap];
+				if (methods) result[ap] = methods;
+			}
+			if (Object.keys(result).length > 0) return result;
+		}
+	}
+
+	// Fallback 1: index-guided schemaComponents lookup
 	if (entry) {
 		const indexedResource = entry.resources.find(r => r.name === resource);
 		if (indexedResource?.schemaComponents?.length) {
@@ -199,9 +255,9 @@ function filterPathsByResource(
 			for (const comp of indexedResource.schemaComponents) {
 				const paths = groups.get(comp);
 				if (paths) {
-					for (const [pathKey, methods] of Object.entries(paths)) {
+					for (const [pathKey, pathMethods] of Object.entries(paths)) {
 						if (!result[pathKey]) result[pathKey] = {};
-						Object.assign(result[pathKey], methods);
+						Object.assign(result[pathKey], pathMethods);
 					}
 				}
 			}
@@ -209,6 +265,7 @@ function filterPathsByResource(
 		}
 	}
 
+	// Fallback 2: operationId-based heuristic matching
 	const groups = getCachedGroups(spec);
 
 	const exactKey = resource.replace(/-/g, "_");
@@ -226,11 +283,11 @@ function filterPathsByResource(
 			schema === exactKey ||
 			schema.endsWith(`.${exactKey}`)
 		) {
-			for (const [path, methods] of Object.entries(paths)) {
+			for (const [p, 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 (!merged[p]) merged[p] = {};
+				Object.assign(merged[p], methods);
 			}
 		}
 	}
@@ -379,6 +436,148 @@ function renderSchemaAsTable(schema: Record<string, unknown>, spec: OpenAPISpec,
 	return rows.join("\n");
 }
 
+function renderWorkflowIndex(index: ApiSpecIndex): string {
+	const workflows = index.guidedWorkflows?.workflows ?? [];
+	if (workflows.length === 0) {
+		return "# Guided Workflows\n\nNo workflows available.\n";
+	}
+
+	const rows = workflows.map(w => `| ${w.id} | ${w.name} | ${w.domain} | ${w.complexity} | ${w.steps.length} |`);
+
+	return [
+		"# Guided API Workflows",
+		"",
+		`${workflows.length} step-by-step workflows. Read \`xcsh://api-spec/workflows/{id}\` for details.`,
+		"",
+		"| ID | Name | Domain | Complexity | Steps |",
+		"|----|------|--------|------------|-------|",
+		...rows,
+		"",
+	].join("\n");
+}
+
+function renderWorkflowDetail(id: string, index: ApiSpecIndex): string {
+	const workflow = index.guidedWorkflows?.workflows.find(w => w.id === id);
+	if (!workflow) {
+		const available = index.guidedWorkflows?.workflows.map(w => `- \`${w.id}\` — ${w.name}`) ?? [];
+		return [`# Workflow not found: ${id}`, "", "Available workflows:", ...available, ""].join("\n");
+	}
+
+	const sections: string[] = [
+		`# ${workflow.name}`,
+		"",
+		`Complexity: ${workflow.complexity} | Domain: ${workflow.domain} | Steps: ${workflow.steps.length}`,
+	];
+
+	if (workflow.prerequisites.length > 0) {
+		sections.push("", "**Prerequisites:**", ...workflow.prerequisites.map(p => `- ${p}`));
+	}
+
+	for (const step of workflow.steps) {
+		sections.push("", `## Step ${step.order}: ${step.name}`, "");
+		sections.push(step.description);
+		if (step.resource) sections.push(`Resource: \`${step.resource}\``);
+		if (step.required_fields?.length) sections.push(`Required fields: ${step.required_fields.join(", ")}`);
+		if (step.depends_on?.length) sections.push(`Depends on: step ${step.depends_on.join(", step ")}`);
+		if (step.tips?.length) sections.push("", "**Tips:**", ...step.tips.map(t => `- ${t}`));
+		if (step.verification?.length) sections.push("", "**Verify:**", ...step.verification.map(v => `- ${v}`));
+	}
+
+	sections.push("");
+	return sections.join("\n");
+}
+
+function renderErrorIndex(index: ApiSpecIndex): string {
+	const er = index.errorResolution;
+	if (!er) {
+		return "# Error Resolution\n\nNo error resolution data available.\n";
+	}
+
+	const httpRows = Object.entries(er.http_errors).map(([code, e]) => `| HTTP | ${code} | ${e.name} |`);
+	const resourceRows = Object.keys(er.resource_errors).map(r => `| Resource | ${r} | ${r} errors |`);
+
+	return [
+		"# API Error Resolution",
+		"",
+		"Read `xcsh://api-spec/errors/{code}` for HTTP errors or `xcsh://api-spec/errors/{resource}` for resource-specific errors.",
+		"",
+		"| Type | Code/Resource | Name |",
+		"|------|---------------|------|",
+		...httpRows,
+		...resourceRows,
+		"",
+	].join("\n");
+}
+
+function renderErrorDetail(key: string, index: ApiSpecIndex): string {
+	const er = index.errorResolution;
+	if (!er) return `# Error: ${key}\n\nNo error resolution data available.\n`;
+
+	const httpError = er.http_errors[key];
+	if (httpError) {
+		const sections: string[] = [
+			`# HTTP ${httpError.code} — ${httpError.name}`,
+			"",
+			httpError.description,
+			"",
+			"## Common Causes",
+			...httpError.common_causes.map(c => `- ${c}`),
+			"",
+			"## Diagnostic Steps",
+		];
+		for (const ds of httpError.diagnostic_steps) {
+			sections.push(`${ds.step}. **${ds.action}** — ${ds.description}`);
+			if (ds.command) sections.push(`   \`${ds.command}\``);
+		}
+		sections.push("", "## Prevention", ...httpError.prevention.map(p => `- ${p}`));
+		if (httpError.related_errors?.length) {
+			sections.push("", `Related errors: ${httpError.related_errors.join(", ")}`);
+		}
+		sections.push("");
+		return sections.join("\n");
+	}
+
+	const resourceErrors = er.resource_errors[key];
+	if (resourceErrors) {
+		const rows = resourceErrors.map(e => `| ${e.error_code} | ${e.pattern} | ${e.resolution} |`);
+		return [
+			`# ${key} — Common Errors`,
+			"",
+			"| Error Code | Pattern | Resolution |",
+			"|------------|---------|------------|",
+			...rows,
+			"",
+		].join("\n");
+	}
+
+	return [
+		`# Error not found: ${key}`,
+		"",
+		"Use `xcsh://api-spec/errors/` to see available error codes and resources.",
+		"",
+	].join("\n");
+}
+
+function renderGlossary(index: ApiSpecIndex): string {
+	const ac = index.acronyms;
+	if (!ac) return "# API Glossary\n\nNo glossary data available.\n";
+
+	const sections = ["# API Glossary", ""];
+	for (const cat of ac.categories) {
+		const items = ac.acronyms.filter(a => a.category === cat);
+		if (items.length === 0) continue;
+		sections.push(`## ${cat}`, "");
+		sections.push("| Acronym | Expansion |");
+		sections.push("|---------|-----------|");
+		for (const a of items) {
+			sections.push(`| ${a.acronym} | ${a.expansion} |`);
+		}
+		sections.push("");
+	}
+
+	return sections.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)))

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

@@ -9,6 +9,17 @@ export interface ApiSpecDomainResource {
 	readonly name: string;
 	readonly description: string;
 	readonly schemaComponents?: readonly string[];
+	readonly apiPaths?: readonly string[];
+	readonly tier?: string;
+	readonly icon?: string;
+	readonly descriptionShort?: string;
+	readonly supportsLogs?: boolean;
+	readonly supportsMetrics?: boolean;
+	readonly dependencies?: {
+		readonly required: readonly string[];
+		readonly optional: readonly string[];
+	};
+	readonly relationshipHints?: readonly string[];
 }
 
 export interface ApiSpecDomainEntry {
@@ -23,12 +34,90 @@ export interface ApiSpecDomainEntry {
 	readonly resources: readonly ApiSpecDomainResource[];
 	readonly useCases?: readonly string[];
 	readonly relatedDomains?: readonly string[];
+	readonly icon?: string;
+	readonly descriptionMedium?: string;
+	readonly isPreview?: boolean;
+	readonly requiresTier?: string;
+}
+
+export interface ApiSpecGuidedWorkflows {
+	readonly version: string;
+	readonly total_workflows: number;
+	readonly domains: readonly string[];
+	readonly workflows: readonly ApiSpecGuidedWorkflow[];
+}
+
+export interface ApiSpecGuidedWorkflow {
+	readonly id: string;
+	readonly name: string;
+	readonly description: string;
+	readonly complexity: string;
+	readonly estimated_steps: number;
+	readonly prerequisites: readonly string[];
+	readonly steps: readonly ApiSpecGuidedWorkflowStep[];
+	readonly domain: string;
+}
+
+export interface ApiSpecGuidedWorkflowStep {
+	readonly order: number;
+	readonly action: string;
+	readonly name: string;
+	readonly description: string;
+	readonly resource?: string;
+	readonly required_fields?: readonly string[];
+	readonly tips?: readonly string[];
+	readonly optional?: boolean;
+	readonly depends_on?: readonly number[];
+	readonly verification?: readonly string[];
+}
+
+export interface ApiSpecHttpError {
+	readonly code: number;
+	readonly name: string;
+	readonly description: string;
+	readonly common_causes: readonly string[];
+	readonly diagnostic_steps: readonly {
+		readonly step: number;
+		readonly action: string;
+		readonly description: string;
+		readonly command?: string;
+	}[];
+	readonly prevention: readonly string[];
+	readonly related_errors?: readonly number[];
+}
+
+export interface ApiSpecResourceErrorEntry {
+	readonly error_code: number;
+	readonly pattern: string;
+	readonly resolution: string;
+}
+
+export interface ApiSpecErrorResolution {
+	readonly version: string;
+	readonly http_errors: Record<string, ApiSpecHttpError>;
+	readonly resource_errors: Record<string, readonly ApiSpecResourceErrorEntry[]>;
+}
+
+export interface ApiSpecAcronym {
+	readonly acronym: string;
+	readonly expansion: string;
+	readonly category: string;
+}
+
+export interface ApiSpecAcronyms {
+	readonly version: string;
+	readonly categories: readonly string[];
+	readonly acronyms: readonly ApiSpecAcronym[];
 }
 
 export interface ApiSpecIndex {
 	readonly version: string;
 	readonly timestamp: string;
 	readonly domains: readonly ApiSpecDomainEntry[];
+	readonly criticalResources?: readonly string[];
+	readonly guidedWorkflows?: ApiSpecGuidedWorkflows;
+	readonly errorResolution?: ApiSpecErrorResolution;
+	readonly acronyms?: ApiSpecAcronyms;
 }
 
 export interface OpenAPIPathOperation {

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

@@ -17,17 +17,17 @@ export interface BuildInfo {
 }
 
 export const BUILD_INFO: BuildInfo = {
-	"version": "18.30.4",
-	"commit": "79427021521f12bb4843a1940bb541ae54b34078",
-	"shortCommit": "7942702",
+	"version": "18.31.0",
+	"commit": "a0a4cd1c5d9256ab214c2e5ade08aeecccdb2a48",
+	"shortCommit": "a0a4cd1",
 	"branch": "main",
-	"tag": "v18.30.4",
-	"commitDate": "2026-05-01T14:58:08Z",
-	"buildDate": "2026-05-01T15:20:53.327Z",
+	"tag": "v18.31.0",
+	"commitDate": "2026-05-01T20:50:25Z",
+	"buildDate": "2026-05-01T21:15:11.839Z",
 	"dirty": false,
 	"prNumber": "",
 	"repoUrl": "https://github.com/f5xc-salesdemos/xcsh",
 	"repoSlug": "f5xc-salesdemos/xcsh",
-	"commitUrl": "https://github.com/f5xc-salesdemos/xcsh/commit/79427021521f12bb4843a1940bb541ae54b34078",
-	"releaseUrl": "https://github.com/f5xc-salesdemos/xcsh/releases/tag/v18.30.4"
+	"commitUrl": "https://github.com/f5xc-salesdemos/xcsh/commit/a0a4cd1c5d9256ab214c2e5ade08aeecccdb2a48",
+	"releaseUrl": "https://github.com/f5xc-salesdemos/xcsh/releases/tag/v18.31.0"
 };

package/src/internal-urls/index.ts

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

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

@@ -11,9 +11,16 @@
  * - xcsh://api-spec/ - API specification index
  * - xcsh://api-spec/{domain} - Domain detail
  * - xcsh://api-spec/{domain}?resource={name} - Resource spec
+ * - xcsh://api-spec/workflows/ - Guided API workflows
+ * - xcsh://api-spec/errors/ - Error resolution
+ * - xcsh://api-spec/glossary/ - Acronym glossary
+ * - xcsh://api-catalog/ - API operation catalog
+ * - xcsh://api-catalog/{category} - Category operations with curl templates
  */
 import * as path from "node:path";
 import type { ContextStatus } from "../services/f5xc-context";
+import { type ApiCatalogResolver, createApiCatalogResolver } from "./api-catalog-resolve";
+import type { ApiCatalogCategorySummary, ApiCatalogIndex } from "./api-catalog-types";
 import { type ApiSpecResolver, createApiSpecResolver } from "./api-spec-resolve";
 import type { ApiSpecIndex } from "./api-spec-types";
 import { getRuntimeBuildInfo, type RuntimeBuildInfo, renderAboutDoc } from "./build-info-runtime";
@@ -23,17 +30,20 @@ import type { InternalResource, InternalUrl, ProtocolHandler } from "./types";
 const SCHEME_PREFIX = "xcsh://";
 const ABOUT_ROUTE = "about";
 const API_SPEC_HOST = "api-spec";
+const API_CATALOG_HOST = "api-catalog";
 
 const EMPTY_INDEX: ApiSpecIndex = { version: "unknown", timestamp: "", domains: [] };
+const EMPTY_CATALOG_INDEX: ApiCatalogIndex = {
+	version: "unknown",
+	displayName: "F5 Distributed Cloud",
+	service: "f5xc",
+	categoryCount: 0,
+	auth: { type: "", headerName: "", headerTemplate: "", tokenSource: "", baseUrlSource: "" },
+	defaults: {},
+};
 
 let _apiSpecCache: { index: ApiSpecIndex; blobs: Record<string, string>; version: string } | null = null;
 
-/**
- * Lazily loads the generated API spec index. Uses require() instead of
- * top-level import because the generated file may not exist in all
- * contexts (tarball install, type-check without build). The try-catch
- * falls back to an empty index so the handler degrades gracefully.
- */
 function loadApiSpecs(): { index: ApiSpecIndex; blobs: Record<string, string>; version: string } {
 	if (_apiSpecCache) return _apiSpecCache;
 	try {
@@ -50,31 +60,51 @@ function loadApiSpecs(): { index: ApiSpecIndex; blobs: Record<string, string>; v
 	return _apiSpecCache;
 }
 
+let _apiCatalogCache: {
+	index: ApiCatalogIndex;
+	summaries: readonly ApiCatalogCategorySummary[];
+	blobs: Record<string, string>;
+} | null = null;
+
+function loadApiCatalog(): {
+	index: ApiCatalogIndex;
+	summaries: readonly ApiCatalogCategorySummary[];
+	blobs: Record<string, string>;
+} {
+	if (_apiCatalogCache) return _apiCatalogCache;
+	try {
+		// eslint-disable-next-line @typescript-eslint/no-require-imports
+		const mod = require("./api-catalog-index.generated");
+		_apiCatalogCache = {
+			index: mod.API_CATALOG_INDEX ?? EMPTY_CATALOG_INDEX,
+			summaries: mod.API_CATALOG_CATEGORY_SUMMARIES ?? [],
+			blobs: mod.API_CATALOG_BLOBS ?? {},
+		};
+	} catch {
+		_apiCatalogCache = { index: EMPTY_CATALOG_INDEX, summaries: [], blobs: {} };
+	}
+	return _apiCatalogCache;
+}
+
 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;
+	readonly apiCatalogResolver?: ApiCatalogResolver;
 }
 
-/**
- * Handler for the xcsh:// internal documentation protocol.
- *
- * Resolves documentation file names to their content, lists available docs,
- * and serves the runtime identity doc at xcsh://about.
- */
 export class InternalDocsProtocolHandler implements ProtocolHandler {
 	readonly scheme = "xcsh";
 	readonly #resolveBuildInfo: () => Promise<RuntimeBuildInfo>;
 	readonly #getContextStatus: (() => ContextStatus | null) | undefined;
 	#apiSpecResolver: ApiSpecResolver | null;
+	#apiCatalogResolver: ApiCatalogResolver | null;
 
 	constructor(options: InternalDocsProtocolOptions = {}) {
 		this.#resolveBuildInfo = options.resolveBuildInfo ?? getRuntimeBuildInfo;
 		this.#getContextStatus = options.getContextStatus;
 		this.#apiSpecResolver = options.apiSpecResolver ?? null;
+		this.#apiCatalogResolver = options.apiCatalogResolver ?? null;
 	}
 
 	#getApiSpecResolver(): ApiSpecResolver {
@@ -85,6 +115,14 @@ export class InternalDocsProtocolHandler implements ProtocolHandler {
 		return this.#apiSpecResolver;
 	}
 
+	#getApiCatalogResolver(): ApiCatalogResolver {
+		if (!this.#apiCatalogResolver) {
+			const catalog = loadApiCatalog();
+			this.#apiCatalogResolver = createApiCatalogResolver(catalog.index, catalog.summaries, catalog.blobs);
+		}
+		return this.#apiCatalogResolver;
+	}
+
 	async resolve(url: InternalUrl): Promise<InternalResource> {
 		const host = url.rawHost || url.hostname;
 
@@ -92,6 +130,10 @@ export class InternalDocsProtocolHandler implements ProtocolHandler {
 			return this.#getApiSpecResolver().resolve(url);
 		}
 
+		if (host === API_CATALOG_HOST) {
+			return this.#getApiCatalogResolver().resolve(url);
+		}
+
 		const pathname = url.rawPathname ?? url.pathname;
 		const filename = host ? (pathname && pathname !== "/" ? host + pathname : host) : "";
 
@@ -108,14 +150,17 @@ export class InternalDocsProtocolHandler implements ProtocolHandler {
 		}
 
 		const specs = loadApiSpecs();
+		const catalog = loadApiCatalog();
 		const syntheticEntry = `- [${ABOUT_ROUTE}](${SCHEME_PREFIX}${ABOUT_ROUTE}) — identity and build fingerprint`;
 		const apiSpecEntry = `- [${API_SPEC_HOST}/](${SCHEME_PREFIX}${API_SPEC_HOST}/) — F5 XC API specifications (${specs.index.domains.length} domains, v${specs.version})`;
+		const apiCatalogEntry = `- [${API_CATALOG_HOST}/](${SCHEME_PREFIX}${API_CATALOG_HOST}/) — F5 XC API operation catalog (${catalog.summaries.length} categories, v${catalog.index.version})`;
 		const listing = [
 			syntheticEntry,
 			apiSpecEntry,
+			apiCatalogEntry,
 			...EMBEDDED_DOC_FILENAMES.map(f => `- [${f}](${SCHEME_PREFIX}${f})`),
 		].join("\n");
-		const totalCount = EMBEDDED_DOC_FILENAMES.length + 2;
+		const totalCount = EMBEDDED_DOC_FILENAMES.length + 3;
 		const content = `# Documentation\n\n${totalCount} files available:\n\n${listing}\n`;
 
 		return {

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

@@ -197,6 +197,14 @@ Most tools resolve custom protocol URLs to internal resources (not web URLs):
   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.
+  Also available: `xcsh://api-spec/workflows/` (step-by-step guides),
+  `xcsh://api-spec/errors/{code}` (error resolution),
+  `xcsh://api-spec/glossary/` (acronym reference).
+
+- `xcsh://api-catalog/` — Pre-built API operation catalog with curl templates.
+  **MUST NOT** read proactively. When building API requests:
+  1. Read `xcsh://api-catalog/?search={term}` to find the right operation
+  2. Read `xcsh://api-catalog/{category}` for full operation details and curl template
 
 In `bash`, URIs auto-resolve to filesystem paths (e.g., `python skill://my-skill/scripts/init.py`).