@f5xc-salesdemos/xcsh 18.64.1 → 18.65.0

package/CHANGELOG.md

@@ -2,6 +2,12 @@
 
 ## [Unreleased]
 
+## [18.64.2] - 2026-05-16
+
+### Fixed
+
+- Welcome banner cloud provider hints: AWS SSO token expiry now correctly suggests `aws sso login` instead of `aws configure`; Google Cloud check replaced `gcloud auth list` (false positives on expired tokens) with `gcloud auth print-access-token`; F5 XC Context surfaces `errorClass` (network/URL) in hints; GitLab `project_inaccessible` gets its own hint; Salesforce differentiates `session_expired` and `not_configured` hints ([#825](https://github.com/f5xc-salesdemos/xcsh/issues/825))
+
 ## [18.64.0] - 2026-05-13
 
 ### Added

package/package.json

@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@f5xc-salesdemos/xcsh",
-	"version": "18.64.1",
+	"version": "18.65.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.64.1",
-		"@f5xc-salesdemos/pi-agent-core": "18.64.1",
-		"@f5xc-salesdemos/pi-ai": "18.64.1",
-		"@f5xc-salesdemos/pi-natives": "18.64.1",
-		"@f5xc-salesdemos/pi-tui": "18.64.1",
-		"@f5xc-salesdemos/pi-utils": "18.64.1",
+		"@f5xc-salesdemos/xcsh-stats": "18.65.0",
+		"@f5xc-salesdemos/pi-agent-core": "18.65.0",
+		"@f5xc-salesdemos/pi-ai": "18.65.0",
+		"@f5xc-salesdemos/pi-natives": "18.65.0",
+		"@f5xc-salesdemos/pi-tui": "18.65.0",
+		"@f5xc-salesdemos/pi-utils": "18.65.0",
 		"@sinclair/typebox": "^0.34",
 		"@xterm/headless": "^6.0",
 		"ajv": "^8.18",

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

@@ -64,6 +64,16 @@ interface IndexEntry {
 	"x-f5xc-use-cases"?: string[];
 	"x-f5xc-related-domains"?: string[];
 	"x-f5xc-primary-resources"?: IndexEntryResource[];
+	"x-f5xc-description-long"?: string;
+	"x-f5xc-summary"?: string;
+	"x-f5xc-logo-svg"?: string;
+	"x-f5xc-cli-domain"?: string;
+	"x-f5xc-cli-metadata"?: {
+		quick_start: { command: string; description: string; expected_output: string };
+		common_workflows: Array<{ name: string; commands: string[] }>;
+		troubleshooting: Array<{ symptom: string; fix: string }>;
+		icon?: string;
+	};
 }
 
 interface RawIndex {
@@ -224,6 +234,8 @@ for (const entry of rawIndex.specifications) {
 	const specContent = fs.readFileSync(specFile, "utf-8");
 	const specJson = JSON.parse(specContent) as {
 		paths?: Record<string, Record<string, SpecPathOperation>>;
+		info?: Record<string, unknown>;
+		components?: { schemas?: Record<string, Record<string, unknown>> };
 		[k: string]: unknown;
 	};
 
@@ -255,6 +267,14 @@ for (const entry of rawIndex.specifications) {
 
 	const useCases = entry["x-f5xc-use-cases"];
 	const relatedDomains = entry["x-f5xc-related-domains"];
+	const rawBp = specJson.info?.["x-f5xc-best-practices"] as Record<string, unknown> | undefined;
+	const bpData = rawBp
+		? {
+				commonErrors: rawBp.common_errors ?? [],
+				securityNotes: rawBp.security_notes ?? [],
+				performanceTips: rawBp.performance_tips ?? [],
+			}
+		: undefined;
 
 	domainEntries.push(
 		[
@@ -280,6 +300,35 @@ for (const entry of rawIndex.specifications) {
 			entry["x-f5xc-requires-tier"]
 				? `\t\t\trequiresTier: ${JSON.stringify(entry["x-f5xc-requires-tier"])},`
 				: undefined,
+			entry["x-f5xc-description-long"]
+				? `\t\t\tdescriptionLong: ${JSON.stringify(entry["x-f5xc-description-long"])},`
+				: undefined,
+			entry["x-f5xc-summary"] ? `\t\t\tsummary: ${JSON.stringify(entry["x-f5xc-summary"])},` : undefined,
+			entry["x-f5xc-logo-svg"] ? `\t\t\tlogoSvg: ${JSON.stringify(entry["x-f5xc-logo-svg"])},` : undefined,
+			entry["x-f5xc-cli-domain"] ? `\t\t\tcliDomain: ${JSON.stringify(entry["x-f5xc-cli-domain"])},` : undefined,
+			entry["x-f5xc-cli-metadata"]
+				? (() => {
+						const raw = entry["x-f5xc-cli-metadata"]!;
+						const qs = raw.quick_start;
+						return `\t\t\tcliMetadata: ${JSON.stringify({
+							quickStart: {
+								command: qs.command,
+								description: qs.description,
+								expectedOutput: qs.expected_output,
+							},
+							commonWorkflows: (raw.common_workflows ?? []).map((w: { name: string; commands: string[] }) => ({
+								name: w.name,
+								commands: w.commands,
+							})),
+							troubleshooting: (raw.troubleshooting ?? []).map((t: { symptom: string; fix: string }) => ({
+								symptom: t.symptom,
+								fix: t.fix,
+							})),
+							icon: raw.icon,
+						})},`;
+					})()
+				: undefined,
+			bpData ? `\t\t\tbestPractices: ${JSON.stringify(bpData)},` : undefined,
 			"\t\t},",
 		]
 			.filter(Boolean)
@@ -295,10 +344,85 @@ const guidedWorkflows = rawIndex["x-f5xc-guided-workflows"];
 const errorResolution = rawIndex["x-f5xc-error-resolution"];
 const acronyms = rawIndex["x-f5xc-acronyms"];
 
+// Extract operation-level and schema-level enrichments per domain
+const enrichmentEntries: string[] = [];
+
+for (const entry of rawIndex.specifications) {
+	const specFile = path.join(specsDir, entry.file);
+	if (!fs.existsSync(specFile)) continue;
+
+	const enrichSpecContent = fs.readFileSync(specFile, "utf-8");
+	const enrichSpecJson = JSON.parse(enrichSpecContent) as {
+		paths?: Record<string, Record<string, Record<string, unknown>>>;
+		components?: { schemas?: Record<string, Record<string, unknown>> };
+	};
+
+	const operationMeta: Record<string, Record<string, unknown>> = {};
+	for (const methods of Object.values(enrichSpecJson.paths ?? {})) {
+		for (const op of Object.values(methods)) {
+			if (typeof op !== "object" || !op) continue;
+			const opId = op.operationId as string | undefined;
+			if (!opId) continue;
+			const enrichment: Record<string, unknown> = {};
+			if (op["x-f5xc-danger-level"]) enrichment.dangerLevel = op["x-f5xc-danger-level"];
+			if (op["x-f5xc-confirmation-required"] != null)
+				enrichment.confirmationRequired = op["x-f5xc-confirmation-required"];
+			if (op["x-f5xc-side-effects"]) enrichment.sideEffects = op["x-f5xc-side-effects"];
+			if (op["x-f5xc-discovered-response-time"]) {
+				const rt = op["x-f5xc-discovered-response-time"] as Record<string, unknown>;
+				enrichment.discoveredResponseTime = {
+					p50Ms: rt.p50_ms,
+					p95Ms: rt.p95_ms,
+					p99Ms: rt.p99_ms,
+					sampleCount: rt.sample_count,
+					source: rt.source,
+				};
+			}
+			if (op["x-f5xc-required-fields"]) enrichment.requiredFields = op["x-f5xc-required-fields"];
+			if (op["x-f5xc-operation-metadata"]) {
+				const om = op["x-f5xc-operation-metadata"] as Record<string, unknown>;
+				const mapped: Record<string, unknown> = { purpose: om.purpose };
+				if (om.conditions) {
+					const cond = om.conditions as Record<string, unknown>;
+					if (cond.prerequisites) mapped.prerequisites = cond.prerequisites;
+					if (cond.postconditions) mapped.postconditions = cond.postconditions;
+				}
+				if (om.common_errors) {
+					mapped.commonErrors = (om.common_errors as Array<Record<string, unknown>>).map(e => ({
+						code: e.code,
+						message: e.message,
+						resolution: e.resolution ?? e.solution ?? "",
+					}));
+				}
+				if (om.performance_impact) {
+					const pi = om.performance_impact as Record<string, unknown>;
+					mapped.performanceImpact = { latency: pi.latency, resourceUsage: pi.resource_usage };
+				}
+				enrichment.operationMetadata = mapped;
+			}
+			if (Object.keys(enrichment).length > 0) operationMeta[opId] = enrichment;
+		}
+	}
+
+	const schemaEnrichments: Record<string, Record<string, unknown>> = {};
+	for (const [schemaName, schemaDef] of Object.entries(enrichSpecJson.components?.schemas ?? {})) {
+		const rec = schemaDef["x-f5xc-recommended-oneof-variant"] as Record<string, string> | undefined;
+		if (rec) {
+			schemaEnrichments[schemaName] = { recommendedOneofVariant: rec };
+		}
+	}
+
+	if (Object.keys(operationMeta).length > 0 || Object.keys(schemaEnrichments).length > 0) {
+		enrichmentEntries.push(
+			`\t${JSON.stringify(entry.domain)}: { operationMeta: ${JSON.stringify(operationMeta)}, schemaEnrichments: ${JSON.stringify(schemaEnrichments)} },`,
+		);
+	}
+}
+
 const output = [
 	"// Auto-generated by scripts/generate-api-spec-index.ts - DO NOT EDIT",
 	"",
-	`import type { ApiSpecIndex } from "./api-spec-types";`,
+	`import type { ApiSpecDomainEnrichments, ApiSpecIndex } from "./api-spec-types";`,
 	"",
 	`export const API_SPEC_VERSION = ${JSON.stringify(rawIndex.version)};`,
 	"",
@@ -318,6 +442,10 @@ const output = [
 	...specDataEntries,
 	`};`,
 	"",
+	`export const API_SPEC_ENRICHMENTS: Readonly<Record<string, ApiSpecDomainEnrichments>> = {`,
+	...enrichmentEntries,
+	`};`,
+	"",
 ]
 	.filter(l => l !== undefined)
 	.join("\n");

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

@@ -1,4 +1,10 @@
-import type { ApiSpecDomainEntry, ApiSpecIndex, OpenAPIPathOperation, OpenAPISpec } from "./api-spec-types";
+import type {
+	ApiSpecDomainEnrichments,
+	ApiSpecDomainEntry,
+	ApiSpecIndex,
+	OpenAPIPathOperation,
+	OpenAPISpec,
+} from "./api-spec-types";
 import type { InternalResource, InternalUrl } from "./types";
 
 const SCHEMA_RENDER_MAX_DEPTH = 3;
@@ -21,6 +27,7 @@ export interface ApiSpecResolver {
 export function createApiSpecResolver(
 	index: ApiSpecIndex,
 	data: Readonly<Record<string, OpenAPISpec>>,
+	enrichments?: Readonly<Record<string, ApiSpecDomainEnrichments>>,
 ): ApiSpecResolver {
 	function lookup(domain: string): OpenAPISpec {
 		const spec = data[domain];
@@ -68,7 +75,10 @@ export function createApiSpecResolver(
 					if (Object.keys(matchingPaths).length === 0) {
 						return makeResource(url, renderUnknownResource(resource, entry, spec));
 					}
-					return makeResource(url, renderResourceSpec(domain, resource, spec, entry, { crudOnly: crud }));
+					return makeResource(
+						url,
+						renderResourceSpec(domain, resource, spec, entry, { crudOnly: crud }, enrichments?.[domain]),
+					);
 				}
 
 				if (pathFilter) {
@@ -138,8 +148,9 @@ function renderDomainDetail(domain: string, entry: ApiSpecDomainEntry, spec: Ope
 		sections.push("", `> ${tags.join(" | ")}`);
 	}
 
-	if (entry.descriptionMedium) {
-		sections.push("", entry.descriptionMedium);
+	const desc = entry.descriptionLong ?? entry.descriptionMedium;
+	if (desc) {
+		sections.push("", desc);
 	}
 
 	sections.push("", "## Resources", "");
@@ -181,6 +192,52 @@ function renderDomainDetail(domain: string, entry: ApiSpecDomainEntry, spec: Ope
 		sections.push("", "## Related Domains", `- ${entry.relatedDomains.join(", ")}`);
 	}
 
+	if (entry.bestPractices) {
+		const bp = entry.bestPractices;
+		sections.push("", "## Best Practices");
+		if (bp.commonErrors.length > 0) {
+			sections.push("", "### Common Errors", "");
+			sections.push("| Code | Message | Resolution | Prevention |");
+			sections.push("|------|---------|------------|------------|");
+			for (const e of bp.commonErrors) {
+				sections.push(`| ${e.code} | ${e.message} | ${e.resolution} | ${e.prevention} |`);
+			}
+		}
+		if (bp.securityNotes.length > 0) {
+			sections.push("", "### Security Notes", ...bp.securityNotes.map(n => `- ${n}`));
+		}
+		if (bp.performanceTips.length > 0) {
+			sections.push("", "### Performance Tips", ...bp.performanceTips.map(t => `- ${t}`));
+		}
+	}
+
+	if (entry.cliMetadata?.quickStart?.command) {
+		const cli = entry.cliMetadata;
+		sections.push("", "## CLI Quick Start", "");
+		sections.push(`\`${cli.quickStart.command}\` — ${cli.quickStart.description}`);
+		const validWorkflows = cli.commonWorkflows?.filter(wf => wf.name) ?? [];
+		if (validWorkflows.length > 0) {
+			sections.push("", "### Common Workflows");
+			for (const wf of validWorkflows) {
+				if (wf.commands?.length) {
+					sections.push("", `**${wf.name}:**`);
+					for (const cmd of wf.commands) {
+						sections.push(`- \`${cmd}\``);
+					}
+				} else {
+					sections.push(`- ${wf.name}`);
+				}
+			}
+		}
+		const validTroubleshooting = cli.troubleshooting?.filter(ts => ts.symptom) ?? [];
+		if (validTroubleshooting.length > 0) {
+			sections.push("", "### Troubleshooting");
+			for (const ts of validTroubleshooting) {
+				sections.push(`- **${ts.symptom}:** ${ts.fix}`);
+			}
+		}
+	}
+
 	sections.push("", `Read \`xcsh://api-spec/${domain}?resource={name}\` for full endpoint specification.`, "");
 
 	return sections.join("\n");
@@ -297,6 +354,7 @@ function renderResourceSpec(
 	spec: OpenAPISpec,
 	entry?: ApiSpecDomainEntry,
 	options?: { crudOnly?: boolean },
+	domainEnrichments?: ApiSpecDomainEnrichments,
 ): string {
 	const matchingPaths = filterPathsByResource(spec, resource, entry);
 	const label = options?.crudOnly ? "CRUD Operations" : "Full API Specification";
@@ -313,6 +371,52 @@ function renderResourceSpec(
 			sections.push(`## ${method.toUpperCase()} ${pathKey}`, "");
 			if (operation.summary) sections.push(String(operation.summary), "");
 
+			const opEnrichment = domainEnrichments?.operationMeta[operation.operationId ?? ""];
+			if (opEnrichment) {
+				const badges: string[] = [];
+				if (opEnrichment.dangerLevel) badges.push(`Danger: **${opEnrichment.dangerLevel}**`);
+				if (opEnrichment.confirmationRequired) badges.push("**Confirmation required**");
+				if (badges.length > 0) sections.push(badges.join(" | "), "");
+
+				if (opEnrichment.sideEffects) {
+					const fx = opEnrichment.sideEffects;
+					const parts: string[] = [];
+					if (fx.creates?.length) parts.push(`Creates: ${fx.creates.join(", ")}`);
+					if (fx.deletes?.length) parts.push(`Deletes: ${fx.deletes.join(", ")}`);
+					if (fx.modifies?.length) parts.push(`Modifies: ${fx.modifies.join(", ")}`);
+					if (parts.length > 0) sections.push(`Side effects: ${parts.join("; ")}`, "");
+				}
+
+				if (opEnrichment.discoveredResponseTime) {
+					const rt = opEnrichment.discoveredResponseTime;
+					sections.push(`Response time: p50=${rt.p50Ms}ms, p95=${rt.p95Ms}ms, p99=${rt.p99Ms}ms`, "");
+				}
+
+				if (opEnrichment.requiredFields?.length) {
+					sections.push(`Required fields: ${opEnrichment.requiredFields.join(", ")}`, "");
+				}
+
+				if (opEnrichment.operationMetadata) {
+					const meta = opEnrichment.operationMetadata;
+					if (meta.prerequisites?.length) {
+						sections.push("**Prerequisites:**", ...meta.prerequisites.map(p => `- ${p}`), "");
+					}
+					if (meta.commonErrors?.length) {
+						sections.push("**Common Errors:**");
+						for (const err of meta.commonErrors) {
+							sections.push(`- ${err.code}: ${err.message} — ${err.resolution}`);
+						}
+						sections.push("");
+					}
+					if (meta.performanceImpact) {
+						sections.push(
+							`Performance: ${meta.performanceImpact.latency}, ${meta.performanceImpact.resourceUsage}`,
+							"",
+						);
+					}
+				}
+			}
+
 			const params = operation.parameters;
 			if (params?.length) {
 				sections.push("### Parameters", "");
@@ -333,10 +437,13 @@ function renderResourceSpec(
 				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);
-					const oneOfStr = renderOneOfGroups(schema);
-					if (oneOfStr) sections.push(oneOfStr);
-					sections.push(renderSchemaAsTable(schema, spec));
+					const rawSchema = jsonContent.schema as Record<string, unknown>;
+					const schema = resolveSchemaRef(rawSchema, spec);
+					const schemaName = extractSchemaName(rawSchema);
+					const schemaRec = schemaName
+						? domainEnrichments?.schemaEnrichments[schemaName]?.recommendedOneofVariant
+						: undefined;
+					sections.push(renderSchemaAsTable(schema, spec, 0, "", schemaRec));
 				}
 			}
 
@@ -350,7 +457,8 @@ function renderResourceSpec(
 					const jsonResp = respContent?.["application/json"];
 					if (jsonResp?.schema) {
 						sections.push(`### Response ${status}`, "");
-						const schema = resolveSchemaRef(jsonResp.schema as Record<string, unknown>, spec);
+						const rawRespSchema = jsonResp.schema as Record<string, unknown>;
+						const schema = resolveSchemaRef(rawRespSchema, spec);
 						sections.push(renderSchemaAsTable(schema, spec));
 					}
 				}
@@ -385,7 +493,17 @@ function renderPathSpec(_domain: string, pathKey: string, spec: OpenAPISpec): st
 }
 
 function resolveSchemaRef(schema: Record<string, unknown>, spec: OpenAPISpec): Record<string, unknown> {
-	const ref = schema.$ref as string | undefined;
+	let ref = schema.$ref as string | undefined;
+
+	if (!ref && Array.isArray(schema.allOf)) {
+		for (const item of schema.allOf as Record<string, unknown>[]) {
+			if (typeof item === "object" && item !== null && typeof item.$ref === "string") {
+				ref = item.$ref as string;
+				break;
+			}
+		}
+	}
+
 	if (!ref) return schema;
 
 	const match = ref.match(/^#\/components\/schemas\/(.+)$/);
@@ -393,7 +511,35 @@ function resolveSchemaRef(schema: Record<string, unknown>, spec: OpenAPISpec): R
 
 	const schemaName = match[1];
 	const resolved = spec.components?.schemas?.[schemaName];
-	return (resolved as Record<string, unknown>) ?? schema;
+	if (!resolved) return schema;
+
+	const siblings: Record<string, unknown> = {};
+	for (const [key, val] of Object.entries(schema)) {
+		if (key !== "$ref" && key !== "allOf") {
+			siblings[key] = val;
+		}
+	}
+
+	if (Object.keys(siblings).length > 0) {
+		return { ...(resolved as Record<string, unknown>), ...siblings };
+	}
+
+	return resolved as Record<string, unknown>;
+}
+
+function extractSchemaName(schema: Record<string, unknown>): string | null {
+	let ref = schema.$ref as string | undefined;
+	if (!ref && Array.isArray(schema.allOf)) {
+		for (const item of schema.allOf as Record<string, unknown>[]) {
+			if (typeof item === "object" && item !== null && typeof item.$ref === "string") {
+				ref = item.$ref as string;
+				break;
+			}
+		}
+	}
+	if (!ref) return null;
+	const match = ref.match(/^#\/components\/schemas\/(.+)$/);
+	return match ? match[1] : null;
 }
 
 function formatFieldConstraints(prop: Record<string, unknown>): string {
@@ -434,19 +580,27 @@ function parseOneOfOptions(val: unknown): string[] {
 	return [String(val)];
 }
 
-function renderOneOfGroups(schema: Record<string, unknown>): string {
+function renderOneOfGroups(schema: Record<string, unknown>, recommended?: Readonly<Record<string, string>>): string {
 	const groups: string[] = [];
 	for (const [key, val] of Object.entries(schema)) {
 		if (!key.startsWith("x-ves-oneof-field-")) continue;
 		const groupName = key.slice("x-ves-oneof-field-".length);
 		const options = parseOneOfOptions(val).join(" | ");
-		groups.push(`- **${groupName}**: ${options}`);
+		const rec = recommended?.[groupName];
+		const recStr = rec ? ` (recommended: **${rec}**)` : "";
+		groups.push(`- **${groupName}**: ${options}${recStr}`);
 	}
 	if (groups.length === 0) return "";
 	return ["**Mutually exclusive — choose one per group:**", ...groups, ""].join("\n");
 }
 
-function renderSchemaAsTable(schema: Record<string, unknown>, spec: OpenAPISpec, depth = 0, prefix = ""): string {
+function renderSchemaAsTable(
+	schema: Record<string, unknown>,
+	spec: OpenAPISpec,
+	depth = 0,
+	prefix = "",
+	schemaRecommended?: Readonly<Record<string, string>>,
+): string {
 	if (depth > SCHEMA_RENDER_MAX_DEPTH) return "";
 
 	const resolved = resolveSchemaRef(schema, spec);
@@ -459,11 +613,11 @@ function renderSchemaAsTable(schema: Record<string, unknown>, spec: OpenAPISpec,
 	const required = (resolved.required as string[]) ?? [];
 	const rows: string[] = [];
 
-	const oneOfStr = renderOneOfGroups(resolved);
+	const oneOfStr = renderOneOfGroups(resolved, schemaRecommended);
 	if (depth === 0) {
 		if (oneOfStr) rows.push(oneOfStr);
-		rows.push("| Field | Type | Required | Constraints | Example | Description |");
-		rows.push("|-------|------|----------|-------------|---------|-------------|");
+		rows.push("| Field | Type | Required | Default | Constraints | Example | Description |");
+		rows.push("|-------|------|----------|---------|-------------|---------|-------------|");
 	}
 
 	for (const [name, prop] of Object.entries(properties)) {
@@ -476,12 +630,42 @@ function renderSchemaAsTable(schema: Record<string, unknown>, spec: OpenAPISpec,
 		const rawExample = (fieldProp["x-ves-example"] as string) ?? (fieldProp["x-f5xc-example"] as string) ?? "";
 		const example = rawExample.length > 40 ? `${rawExample.slice(0, 37)}…` : rawExample;
 
-		rows.push(`| ${fieldName} | ${type} | ${isRequired} | ${constraints} | ${example} | ${desc} |`);
+		const serverDefault = fieldProp["x-f5xc-server-default"];
+		const recommendedValue = fieldProp["x-f5xc-recommended-value"];
+		let defaultCol = "";
+		if (serverDefault != null) defaultCol = `${serverDefault} (server)`;
+		else if (recommendedValue != null) defaultCol = `${recommendedValue} (rec)`;
+
+		const reqFor = fieldProp["x-f5xc-required-for"] as Record<string, boolean> | undefined;
+		let reqStr = isRequired;
+		if (reqFor) {
+			const ops = Object.entries(reqFor)
+				.filter(([, v]) => v)
+				.map(([k]) => k);
+			if (ops.length > 0) reqStr = ops.join(", ");
+		}
+
+		rows.push(`| ${fieldName} | ${type} | ${reqStr} | ${defaultCol} | ${constraints} | ${example} | ${desc} |`);
+
+		const conflictsWith = fieldProp["x-f5xc-conflicts-with"] as string[] | undefined;
+		if (conflictsWith?.length) {
+			rows.push(`| └─ ${fieldName} | | **conflicts with** ${conflictsWith.join(", ")} | | | | |`);
+		}
+
+		const requires = fieldProp["x-f5xc-requires"] as
+			| Array<{ field: string; required?: boolean; reason?: string; min_items?: number }>
+			| undefined;
+		if (requires?.length) {
+			for (const dep of requires) {
+				const note = dep.min_items != null ? ` (min: ${dep.min_items})` : "";
+				rows.push(`| └─ ${fieldName} | | **requires** ${dep.field}${note} | | ${dep.reason ?? ""} | | |`);
+			}
+		}
 
 		if (type === "object" && fieldProp.properties && depth < SCHEMA_RENDER_MAX_DEPTH) {
-			const nestedOneOf = renderOneOfGroups(fieldProp);
+			const nestedOneOf = renderOneOfGroups(fieldProp, schemaRecommended);
 			if (nestedOneOf) rows.push("", nestedOneOf);
-			const nested = renderSchemaAsTable(fieldProp, spec, depth + 1, fieldName);
+			const nested = renderSchemaAsTable(fieldProp, spec, depth + 1, fieldName, schemaRecommended);
 			const nestedLines = nested.split("\n").filter(l => l.startsWith("|") && !l.startsWith("| Field"));
 			rows.push(...nestedLines);
 		}

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

@@ -23,6 +23,34 @@ export interface ApiSpecDomainResource {
 	readonly catalogCategories?: readonly string[];
 }
 
+export interface ApiSpecCliMetadata {
+	readonly quickStart: {
+		readonly command: string;
+		readonly description: string;
+		readonly expectedOutput: string;
+	};
+	readonly commonWorkflows: readonly {
+		readonly name: string;
+		readonly commands?: readonly string[];
+	}[];
+	readonly troubleshooting: readonly {
+		readonly symptom?: string;
+		readonly fix?: string;
+	}[];
+	readonly icon?: string;
+}
+
+export interface ApiSpecBestPractices {
+	readonly commonErrors: readonly {
+		readonly code: number;
+		readonly message: string;
+		readonly resolution: string;
+		readonly prevention: string;
+	}[];
+	readonly securityNotes: readonly string[];
+	readonly performanceTips: readonly string[];
+}
+
 export interface ApiSpecDomainEntry {
 	readonly domain: string;
 	readonly title: string;
@@ -39,6 +67,12 @@ export interface ApiSpecDomainEntry {
 	readonly descriptionMedium?: string;
 	readonly isPreview?: boolean;
 	readonly requiresTier?: string;
+	readonly descriptionLong?: string;
+	readonly summary?: string;
+	readonly logoSvg?: string;
+	readonly cliDomain?: string;
+	readonly cliMetadata?: ApiSpecCliMetadata;
+	readonly bestPractices?: ApiSpecBestPractices;
 }
 
 export interface ApiSpecGuidedWorkflows {
@@ -111,6 +145,47 @@ export interface ApiSpecAcronyms {
 	readonly acronyms: readonly ApiSpecAcronym[];
 }
 
+export interface ApiSpecOperationEnrichment {
+	readonly dangerLevel?: "low" | "medium" | "high";
+	readonly confirmationRequired?: boolean;
+	readonly sideEffects?: {
+		readonly creates?: readonly string[];
+		readonly deletes?: readonly string[];
+		readonly modifies?: readonly string[];
+	};
+	readonly discoveredResponseTime?: {
+		readonly p50Ms: number;
+		readonly p95Ms: number;
+		readonly p99Ms: number;
+		readonly sampleCount: number;
+		readonly source: string;
+	};
+	readonly requiredFields?: readonly string[];
+	readonly operationMetadata?: {
+		readonly purpose: string;
+		readonly prerequisites?: readonly string[];
+		readonly postconditions?: readonly string[];
+		readonly commonErrors?: readonly {
+			readonly code: number;
+			readonly message: string;
+			readonly resolution: string;
+		}[];
+		readonly performanceImpact?: {
+			readonly latency: string;
+			readonly resourceUsage: string;
+		};
+	};
+}
+
+export interface ApiSpecSchemaEnrichment {
+	readonly recommendedOneofVariant?: Readonly<Record<string, string>>;
+}
+
+export interface ApiSpecDomainEnrichments {
+	readonly operationMeta: Readonly<Record<string, ApiSpecOperationEnrichment>>;
+	readonly schemaEnrichments: Readonly<Record<string, ApiSpecSchemaEnrichment>>;
+}
+
 export interface ApiSpecIndex {
 	readonly version: string;
 	readonly timestamp: string;

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

@@ -17,17 +17,17 @@ export interface BuildInfo {
 }
 
 export const BUILD_INFO: BuildInfo = {
-	"version": "18.64.1",
-	"commit": "899659f36b0f312b3772fe3c1595def03344e62b",
-	"shortCommit": "899659f",
+	"version": "18.65.0",
+	"commit": "35c77b050317137efe631106d543647195229000",
+	"shortCommit": "35c77b0",
 	"branch": "main",
-	"tag": "v18.64.1",
-	"commitDate": "2026-05-16T22:34:30Z",
-	"buildDate": "2026-05-16T22:55:37.570Z",
+	"tag": "v18.65.0",
+	"commitDate": "2026-05-17T08:48:25Z",
+	"buildDate": "2026-05-17T09:14:22.007Z",
 	"dirty": true,
 	"prNumber": "",
 	"repoUrl": "https://github.com/f5xc-salesdemos/xcsh",
 	"repoSlug": "f5xc-salesdemos/xcsh",
-	"commitUrl": "https://github.com/f5xc-salesdemos/xcsh/commit/899659f36b0f312b3772fe3c1595def03344e62b",
-	"releaseUrl": "https://github.com/f5xc-salesdemos/xcsh/releases/tag/v18.64.1"
+	"commitUrl": "https://github.com/f5xc-salesdemos/xcsh/commit/35c77b050317137efe631106d543647195229000",
+	"releaseUrl": "https://github.com/f5xc-salesdemos/xcsh/releases/tag/v18.65.0"
 };

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

@@ -25,7 +25,7 @@ import type { ContextStatus } from "../services/f5xc-context";
 import { type ApiCatalogResolver, createApiCatalogResolver } from "./api-catalog-resolve";
 import type { ApiCatalogCategory, ApiCatalogCategorySummary, ApiCatalogIndex } from "./api-catalog-types";
 import { type ApiSpecResolver, createApiSpecResolver } from "./api-spec-resolve";
-import type { ApiSpecIndex, OpenAPISpec } from "./api-spec-types";
+import type { ApiSpecDomainEnrichments, ApiSpecIndex, OpenAPISpec } from "./api-spec-types";
 import { getRuntimeBuildInfo, type RuntimeBuildInfo, renderAboutDoc } from "./build-info-runtime";
 import { loadComputerProfile, renderComputerProfileMarkdown, seedComputerProfile } from "./computer-profile";
 import { EMBEDDED_DOC_FILENAMES, EMBEDDED_DOCS } from "./docs-index.generated";
@@ -51,15 +51,26 @@ const EMPTY_CATALOG_INDEX: ApiCatalogIndex = {
 	defaults: {},
 };
 
-let _apiSpecCache: { index: ApiSpecIndex; data: Readonly<Record<string, OpenAPISpec>>; version: string } | null = null;
+let _apiSpecCache: {
+	index: ApiSpecIndex;
+	data: Readonly<Record<string, OpenAPISpec>>;
+	enrichments: Readonly<Record<string, ApiSpecDomainEnrichments>>;
+	version: string;
+} | null = null;
 
-function loadApiSpecs(): { index: ApiSpecIndex; data: Readonly<Record<string, OpenAPISpec>>; version: string } {
+function loadApiSpecs(): {
+	index: ApiSpecIndex;
+	data: Readonly<Record<string, OpenAPISpec>>;
+	enrichments: Readonly<Record<string, ApiSpecDomainEnrichments>>;
+	version: string;
+} {
 	if (_apiSpecCache) return _apiSpecCache;
 	try {
 		const mod = require("./api-spec-index.generated") as {
 			API_SPEC_INDEX?: ApiSpecIndex;
 			API_SPEC_DATA?: Readonly<Record<string, unknown>>;
 			API_SPEC_VERSION?: string;
+			API_SPEC_ENRICHMENTS?: Readonly<Record<string, ApiSpecDomainEnrichments>>;
 		};
 		const index = mod.API_SPEC_INDEX ?? EMPTY_INDEX;
 		const version = mod.API_SPEC_VERSION ?? "unknown";
@@ -69,13 +80,14 @@ function loadApiSpecs(): { index: ApiSpecIndex; data: Readonly<Record<string, Op
 		_apiSpecCache = {
 			index,
 			data: (mod.API_SPEC_DATA ?? {}) as Readonly<Record<string, OpenAPISpec>>,
+			enrichments: mod.API_SPEC_ENRICHMENTS ?? {},
 			version,
 		};
 	} catch (err) {
 		logger.warn("api-spec index unavailable, embedded specs disabled", {
 			error: err instanceof Error ? err.message : String(err),
 		});
-		_apiSpecCache = { index: EMPTY_INDEX, data: {}, version: "unavailable" };
+		_apiSpecCache = { index: EMPTY_INDEX, data: {}, enrichments: {}, version: "unavailable" };
 	}
 	return _apiSpecCache;
 }
@@ -141,7 +153,7 @@ export class InternalDocsProtocolHandler implements ProtocolHandler {
 	#getApiSpecResolver(): ApiSpecResolver {
 		if (!this.#apiSpecResolver) {
 			const specs = loadApiSpecs();
-			this.#apiSpecResolver = createApiSpecResolver(specs.index, specs.data);
+			this.#apiSpecResolver = createApiSpecResolver(specs.index, specs.data, specs.enrichments);
 		}
 		return this.#apiSpecResolver;
 	}