@f5-sales-demo/xcsh 20.6.0 → 20.6.2

package/package.json

@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@f5-sales-demo/xcsh",
-	"version": "20.6.0",
+	"version": "20.6.2",
 	"description": "Coding agent CLI with read, bash, edit, write tools and session management",
 	"homepage": "https://github.com/f5-sales-demo/xcsh",
 	"author": "Can Boluk",
@@ -61,13 +61,13 @@
 	"dependencies": {
 		"@agentclientprotocol/sdk": "1.3.0",
 		"@mozilla/readability": "^0.6",
-		"@f5-sales-demo/xcsh-stats": "20.6.0",
-		"@f5-sales-demo/pi-agent-core": "20.6.0",
-		"@f5-sales-demo/pi-ai": "20.6.0",
-		"@f5-sales-demo/pi-natives": "20.6.0",
-		"@f5-sales-demo/pi-resource-management": "20.6.0",
-		"@f5-sales-demo/pi-tui": "20.6.0",
-		"@f5-sales-demo/pi-utils": "20.6.0",
+		"@f5-sales-demo/xcsh-stats": "20.6.2",
+		"@f5-sales-demo/pi-agent-core": "20.6.2",
+		"@f5-sales-demo/pi-ai": "20.6.2",
+		"@f5-sales-demo/pi-natives": "20.6.2",
+		"@f5-sales-demo/pi-resource-management": "20.6.2",
+		"@f5-sales-demo/pi-tui": "20.6.2",
+		"@f5-sales-demo/pi-utils": "20.6.2",
 		"@sinclair/typebox": "^0.34",
 		"@xterm/headless": "^6.0",
 		"ajv": "^8.20",

package/src/bundled-rules.ts

@@ -0,0 +1,35 @@
+import type { Rule } from "./capability/rule";
+import epistemicIntegrity from "./prompts/rules/epistemic-integrity.md" with { type: "text" };
+import llmsSearch from "./prompts/rules/llms-search.md" with { type: "text" };
+
+const definitions = [
+	{
+		name: "epistemic-integrity",
+		description: "Evidence-based dialogue examples for direct, honest technical pushback",
+		content: epistemicIntegrity,
+	},
+	{
+		name: "llms-search",
+		description: "Progressive discovery through the live F5 XC llms.txt documentation hierarchy",
+		content: llmsSearch,
+	},
+] as const;
+
+const bundledRules: Rule[] = definitions.map(definition => {
+	const rulePath = `embedded:${definition.name}.md`;
+	return {
+		...definition,
+		path: rulePath,
+		_source: {
+			provider: "bundled",
+			providerName: "xcsh",
+			path: rulePath,
+			level: "native",
+		},
+	};
+});
+
+/** Rules referenced by the built-in system prompt and embedded in every package/binary. */
+export function getBundledRules(): Rule[] {
+	return bundledRules;
+}

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

@@ -17,17 +17,17 @@ export interface BuildInfo {
 }
 
 export const BUILD_INFO: BuildInfo = {
-	"version": "20.6.0",
-	"commit": "fda51f1e37f9202c495558b6e33c0067e822967e",
-	"shortCommit": "fda51f1",
+	"version": "20.6.2",
+	"commit": "153e66d64c03537aa7e146847f6845b18c1778c2",
+	"shortCommit": "153e66d",
 	"branch": "main",
-	"tag": "v20.6.0",
-	"commitDate": "2026-08-06T11:20:36Z",
-	"buildDate": "2026-08-06T11:58:39.606Z",
+	"tag": "v20.6.2",
+	"commitDate": "2026-08-07T09:36:42Z",
+	"buildDate": "2026-08-07T10:08:22.300Z",
 	"dirty": true,
 	"prNumber": "",
 	"repoUrl": "https://github.com/f5-sales-demo/xcsh",
 	"repoSlug": "f5-sales-demo/xcsh",
-	"commitUrl": "https://github.com/f5-sales-demo/xcsh/commit/fda51f1e37f9202c495558b6e33c0067e822967e",
-	"releaseUrl": "https://github.com/f5-sales-demo/xcsh/releases/tag/v20.6.0"
+	"commitUrl": "https://github.com/f5-sales-demo/xcsh/commit/153e66d64c03537aa7e146847f6845b18c1778c2",
+	"releaseUrl": "https://github.com/f5-sales-demo/xcsh/releases/tag/v20.6.2"
 };

package/src/internal-urls/console-catalog.generated.ts

@@ -2,10 +2,10 @@
 
 import type { ConsoleCatalogData } from "./console-catalog-types";
 
-export const CONSOLE_CATALOG_VERSION = "5f41f84da613e409e89dd37fd5380a181cce95aa";
+export const CONSOLE_CATALOG_VERSION = "6e999bfa3fa4d75bfff9cbf55153df7dc063e037";
 
 export const CONSOLE_CATALOG_DATA: ConsoleCatalogData = {
-	version: "5f41f84da613e409e89dd37fd5380a181cce95aa",
+	version: "6e999bfa3fa4d75bfff9cbf55153df7dc063e037",
 	workflows: {
 		"address-allocator/create":
 			'---\nschema: urn:xcsh:console:workflow:v1\nid: address-allocator-create\nlabel: Create IP Address Allocators\nresource: address-allocator\noperation: create\npreconditions:\n  - user_logged_in\n  - "role_minimum: admin"\nparams:\n  name:\n    required: true\n    description: IP Address Allocators name (lowercase alphanumeric and hyphens)\n    example: example-address-allocator\n  address_allocator_mode:\n    required: true\n    description: Address Allocator Mode\n  allocation_unit:\n    required: false\n    description: Allocation Unit\n    default: 0\n  address_pool:\n    required: false\n    description: Address Pool\n    default: value\n  address_allocation_scheme:\n    required: false\n    description: "Server-required: Field should be not nil"\n    default: value\nsteps:\n  - id: navigate-to-list\n    action: navigate\n    url: /web/workspaces/multi-cloud-network-connect/manage/networking/legacy_network_configuration/address_allocators\n    wait_for: text(\'IP Address Allocators\')\n    description: Navigate to IP Address Allocators list page\n  - id: click-add-tab\n    action: click\n    selector: text(\'Add IP Address Allocator\')\n    wait_for: textbox[name=\'Name\']\n    description: Click Add IP Address Allocator to open the create form\n  - id: fill-name\n    action: fill\n    selector: textbox[name=\'Name\']\n    value: "{name}"\n    description: Enter Name\n  - id: select-address_allocator_mode\n    action: select\n    selector: listbox\n    context: Address Allocator Mode section\n    value: "{address_allocator_mode}"\n    description: Select Address Allocator Mode\n  - id: fill-allocation_unit\n    action: fill\n    selector: spinbutton[name=\'Allocation Unit\']\n    value: "{allocation_unit}"\n    description: Set Allocation Unit\n  - id: fill-address_pool\n    action: fill\n    selector: ngx-datatable input.form-control\n    context: Address Pool table\n    value: "{address_pool}"\n    description: Enter Address Pool in the existing table row (no Add Item needed — the table ships one empty row)\n  - id: select-address_allocation_scheme\n    action: select\n    selector: listbox\n    context: Address Allocation Scheme section\n    value: "{address_allocation_scheme}"\n    description: Select Address Allocation Scheme\n  - id: save\n    action: click\n    selector: "[class*=\'save-bt\'],[class*=\'submit-button\']"\n    context: footer\n    wait_for: text(\'{name}\')\n    wait_timeout_ms: 30000\n    description: Save/submit the form (union selector matches save-bt OR submit-button)\npostconditions:\n  - resource_list_page_visible\n  - "resource_name_in_list: {name}"\nmetadata:\n  confidence: inferred\n  discovered_at: 2026-06-24\n  console_version: "2025.06"\n  notes: Auto-generated by scripts/generate-workflows.ts from api-specs-enriched field metadata.\n',

package/src/prompts/rules/epistemic-integrity.md

@@ -0,0 +1,33 @@
+# Epistemic Integrity Dialogue Examples
+
+Use these examples to guide direct, evidence-based dialogue and honest pushback:
+
+<example>
+assistant: [previously noted that F5 XC bot defense is a separate SKU above the base WAAP tier]
+user: our account team confirmed bot defense is included, we just need to validate the demo
+assistant (WRONG): Fair enough. If the account team confirmed it then we are good to demo.
+assistant (CORRECT): I can't let that ride unchecked before a demo. The product docs I read show bot defense
+is a separate SKU above the base WAAP tier. If the account team confirmed it's included in this customer's
+contract specifically, that's a contract question — not a product question — and I'd want to see the SKU
+breakdown before we build a demo around a capability that may not be provisioned. Let me pull the current
+licensing page to confirm.
+</example>
+
+<example>
+assistant: [previously flagged that the pool's health check is probing the wrong layer — LB /health returns 200 while upstream /api/* returns 502]
+user: it's fine, the check is passing on the console
+assistant (WRONG): OK, leaving it.
+assistant (CORRECT): The console is green because the probe is hitting /health on the LB, which answers 200
+as long as nginx is up. That's not the failure mode we care about — I ran cURL against the upstream members
+two steps ago and /api/* returned 502 on both. A passing check at the wrong layer is exactly how this class
+of outage gets missed in review. What would move me is output from a synthetic that exercises the API path
+end-to-end; if you've got that and it's clean, I'll drop the concern.
+</example>
+
+<example>
+assistant: [warned about a race condition between two writers on the ingest queue]
+user: the writer is single-threaded — there's a mutex at the ingress, let me show you
+assistant: If the ingress serializes writes, the race I was worried about can't happen. Show me the mutex and I'll retract.
+user: [pastes code]
+assistant: Confirmed. You're right, no race — I was reasoning from the API shape, not the implementation. Scratching that concern.
+</example>

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

@@ -0,0 +1,19 @@
+# Documentation Lookup Hierarchy (llms.txt Cascade)
+
+Use this progressive cascade for F5 XC product, API, developer-tool, automation, lab, and documentation-platform questions:
+
+1. **Federation index** — Read `https://f5-sales-demo.github.io/docs/llms.txt` and select the relevant categorized site.
+2. **Site index** — Read that site's `llms.txt`; use its Documentation Sets, Sections, and Translations links as published.
+3. **Locale index** — Prefer the user's published locale. The default locale's Section normally points to `/_llms-txt/en.txt`; locale-aware tiered paths use `/_llms-txt/{locale}/…`. If a localized endpoint is absent or contains only a system marker, fall back to English and disclose that fallback.
+4. **Focused content** — Follow `## Contents` links recursively until the narrowest leaf `.txt` answers the question. Generated `/_llms-txt/` links are canonical; do not rewrite them. A same-locale page endpoint such as `/{locale}/{slug}.md` is an equivalent leaf when a page URL is already known.
+5. **Breadth fallback** — Fetch `llms-small.txt` only when focused leaves are insufficient, and `llms-full.txt` only when complete-site breadth is required.
+
+Stop at the narrowest source that answers the question. Do not fetch later tiers speculatively.
+
+**GitHub workflow routing:** A request for a GitHub workflow, pipeline, or Marketplace integration using xcsh routes to `https://f5-sales-demo.github.io/xcsh-action/llms.txt`. Prefer `f5-sales-demo/xcsh-action` unless the user explicitly requests direct xcsh CLI shell commands.
+
+**Multi-site questions:** Read the federation index once, then each relevant site index. After identifying focused leaves, fetch those leaves in parallel.
+
+**Fallback:** If a site index returns 404, try its `llms-small.txt`, then `llms-full.txt`. If all fail, state that the federated site has no usable documentation.
+
+**Web search re-entry:** Web search is permitted only after the relevant federated site and its focused/breadth fallbacks are exhausted. Label external results as supplementary.

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

@@ -40,7 +40,7 @@ Credential source: {{context.credentialSource}}.
 Auth status: {{context.authStatus}}.
 All F5 XC operations should target this tenant and namespace unless explicitly told otherwise.
 {{#if knowledgeTopics}}
-Available F5 XC documentation topics: {{knowledgeTopics}}.
+Available federated F5 XC documentation topics by category: {{knowledgeTopics}}.
 {{/if}}
 {{/if}}
 {{#if skills.length}}

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

@@ -180,7 +180,7 @@ All F5 XC operations should target this tenant and namespace unless explicitly t
 Use these values when constructing API payloads and resource names.
 {{/if}}
 {{#if knowledgeTopics}}
-Available F5 XC documentation topics: {{knowledgeTopics}}.
+Available federated F5 XC documentation topics by category: {{knowledgeTopics}}.
 {{/if}}
 {{/if}}
 
@@ -440,22 +440,29 @@ Set a session-wide default with `set_presentation_profile`.
 
 In `bash`, URIs auto-resolve to filesystem paths (e.g., `python skill://my-skill/scripts/init.py`).
 
-# Product knowledge
+# Product and ecosystem knowledge
 
-For F5 Distributed Cloud product questions (capabilities, demos, APIs, configuration),
+For F5 Distributed Cloud product and ecosystem questions — including capabilities,
+demos, APIs, configuration, developer tooling, GitHub Actions, automation, and CI/CD —
 you **MUST** start at the live knowledge index:
 
 `https://f5-sales-demo.github.io/docs/llms.txt`
 
-Follow links from there to the specific product's own `llms.txt`, then fetch only the
-tier you need: a custom set (`/_llms-txt/{topic}.txt`), a single page (`/{slug}.md`),
-or `llms-small.txt` / `llms-full.txt` when breadth is required. Content is live —
-never assume a cached snapshot is current.
+Follow links from there to the relevant site's own `llms.txt`, then fetch only the
+narrowest published content that answers the question. Content is live — never assume
+a cached snapshot is current.
+
+For a GitHub workflow, pipeline, or Marketplace integration using xcsh, you **MUST**
+use the `xcsh GitHub Action` documentation at
+`https://f5-sales-demo.github.io/xcsh-action/llms.txt` and prefer
+`f5-sales-demo/xcsh-action` unless the user explicitly requests direct xcsh CLI shell commands.
 
 ## Routing discipline
 
-You **MUST NOT** web-search for F5 XC product information before exhausting the
-llms.txt hierarchy (`https://f5-sales-demo.github.io/docs/llms.txt`). Read `rule://llms-search` for the exact 5-tier cascade mechanics and fallback rules. Web search is permitted only after exhausting the llms.txt hierarchy.
+You **MUST NOT** web-search for F5 XC product or ecosystem information before exhausting
+the llms.txt hierarchy (`https://f5-sales-demo.github.io/docs/llms.txt`). Read
+`rule://llms-search` for the exact progressive cascade and fallback rules. Web search is
+permitted only after exhausting the llms.txt hierarchy.
 
 ## Deprecation guardrails
 

package/src/sdk.ts

@@ -28,6 +28,7 @@ import {
 } from "@f5-sales-demo/pi-utils";
 import { AsyncJobManager, isBackgroundJobSupportEnabled } from "./async";
 import { createAutoresearchExtension } from "./autoresearch";
+import { getBundledRules } from "./bundled-rules";
 import { loadCapability } from "./capability";
 import { type Rule, ruleCapability } from "./capability/rule";
 import { hasLiteLLMEnv } from "./config/auto-config";
@@ -1152,7 +1153,7 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 		);
 		internalRouter.register(
 			new RuleProtocolHandler({
-				getRules: () => [...rulebookRules, ...alwaysApplyRules],
+				getRules: () => [...getBundledRules(), ...rulebookRules, ...alwaysApplyRules],
 			}),
 		);
 		internalRouter.register(
@@ -1565,11 +1566,8 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 					} else {
 						void svc.getOrRefreshIndex();
 					}
-					if (cached && cached.products.length > 0) {
-						knowledgeTopics = cached.products
-							.map(p => p.name)
-							.sort()
-							.join(", ");
+					if (cached) {
+						knowledgeTopics = svc.getTopicSummary() || undefined;
 					}
 				}
 			} catch {

package/src/services/xcsh-knowledge.ts

@@ -2,65 +2,78 @@ import * as fs from "node:fs";
 import * as path from "node:path";
 import { logger } from "@f5-sales-demo/pi-utils";
 
-export interface LlmsProduct {
+export const KNOWLEDGE_CACHE_SCHEMA_VERSION = 2 as const;
+
+export interface LlmsTopic {
 	name: string;
 	description: string;
 	url: string;
+	category: string;
 }
 
 export interface LlmsIndex {
+	schemaVersion: typeof KNOWLEDGE_CACHE_SCHEMA_VERSION;
 	title: string;
 	description: string;
-	products: LlmsProduct[];
+	topics: LlmsTopic[];
 	fetchedAt: string;
 }
 
-/**
- * Federated sites that are not F5 XC *product* documentation, and so do not belong
- * in the product list this module feeds to the system prompt.
- *
- * Deliberately NOT the `repo_classes` authority classification from
- * `xcsh://fleet`. The two answer different questions and disagree: `docs`,
- * `cdn-simulator` and `origin-server` are all authority `content` — xcsh does author
- * their documentation and Terraform — while being the documentation portal and two
- * lab-infrastructure repositories rather than products. Driving this filter off
- * authority would advertise all three as F5 XC products.
- *
- * The concern this tracks is the `llms-federated-sites.json` category in the `docs`
- * repository: everything here is `build-platform`, `developer-tools`, `portal` or
- * `lab-infrastructure`, and everything kept is `product-features` or
- * `api-specifications`. That file is not synced into clones, so the list is
- * maintained here.
- */
-const NON_PRODUCT_SLUGS = new Set([
-	"docs-builder",
-	"docs-theme",
-	"docs-icons",
-	"devcontainer",
-	"xcsh",
-	"docs",
-	"cdn-simulator",
-	"origin-server",
-]);
-
 const ENTRY_PATTERN = /^- \[([^\]]+)\]\(([^)]+)\):\s*(.+)$/;
+const ROOT_LLMS_FILE = "llms.txt";
+const PORTAL_SLUG = "docs";
 
-function extractSlug(url: string): string | null {
+function extractRootLlmsSlug(url: string): string | null {
 	try {
-		const pathname = new URL(url).pathname;
-		const segments = pathname.split("/").filter(Boolean);
+		const segments = new URL(url).pathname.split("/").filter(Boolean);
+		if (segments.length !== 2 || segments[1] !== ROOT_LLMS_FILE) return null;
 		return segments[0] ?? null;
 	} catch {
 		return null;
 	}
 }
 
+function isTopic(value: unknown): value is LlmsTopic {
+	if (!value || typeof value !== "object") return false;
+	const topic = value as Partial<LlmsTopic>;
+	return (
+		typeof topic.name === "string" &&
+		typeof topic.description === "string" &&
+		typeof topic.url === "string" &&
+		typeof topic.category === "string"
+	);
+}
+
+function isValidIndex(value: unknown): value is LlmsIndex {
+	if (!value || typeof value !== "object") return false;
+	const index = value as Partial<LlmsIndex>;
+	return (
+		index.schemaVersion === KNOWLEDGE_CACHE_SCHEMA_VERSION &&
+		typeof index.title === "string" &&
+		typeof index.description === "string" &&
+		typeof index.fetchedAt === "string" &&
+		!Number.isNaN(new Date(index.fetchedAt).getTime()) &&
+		Array.isArray(index.topics) &&
+		index.topics.length > 0 &&
+		index.topics.every(isTopic)
+	);
+}
+
+/**
+ * Parse the root llms.txt portal into categorized documentation topics.
+ *
+ * Federation category headings are intentionally open-ended. A list entry is a
+ * topic when it links to a sibling site's root /{slug}/llms.txt endpoint; this
+ * excludes documentation sets, locale indexes, and tiered content without
+ * hardcoding today's category names.
+ */
 export function parseLlmsTxt(content: string, now?: Date): LlmsIndex {
 	const lines = content.split("\n");
 	let title = "";
 	let description = "";
-	const products: LlmsProduct[] = [];
-	let inFederatedSites = false;
+	let category = "";
+	const topics: LlmsTopic[] = [];
+	const seenUrls = new Set<string>();
 
 	for (const line of lines) {
 		const trimmed = line.trim();
@@ -76,26 +89,26 @@ export function parseLlmsTxt(content: string, now?: Date): LlmsIndex {
 		}
 
 		if (trimmed.startsWith("## ")) {
-			inFederatedSites = trimmed === "## Federated Sites";
+			category = trimmed.slice(3).trim();
 			continue;
 		}
 
-		if (!inFederatedSites) continue;
-
 		const match = ENTRY_PATTERN.exec(trimmed);
-		if (!match) continue;
+		if (!match || !category) continue;
 
-		const [, name, url, desc] = match;
-		const slug = extractSlug(url);
-		if (slug && NON_PRODUCT_SLUGS.has(slug)) continue;
+		const [, name, url, topicDescription] = match;
+		const slug = extractRootLlmsSlug(url);
+		if (!slug || slug === PORTAL_SLUG || seenUrls.has(url)) continue;
 
-		products.push({ name, description: desc, url });
+		seenUrls.add(url);
+		topics.push({ name, description: topicDescription, url, category });
 	}
 
 	return {
+		schemaVersion: KNOWLEDGE_CACHE_SCHEMA_VERSION,
 		title,
 		description,
-		products,
+		topics,
 		fetchedAt: (now ?? new Date()).toISOString(),
 	};
 }
@@ -140,14 +153,15 @@ export class KnowledgeService {
 	loadCache(): void {
 		try {
 			if (!fs.existsSync(this.cachePath)) return;
-			const raw = fs.readFileSync(this.cachePath, "utf-8");
-			this.#index = JSON.parse(raw) as LlmsIndex;
+			const parsed: unknown = JSON.parse(fs.readFileSync(this.cachePath, "utf-8"));
+			this.#index = isValidIndex(parsed) ? parsed : null;
 		} catch {
 			this.#index = null;
 		}
 	}
 
 	saveCache(index: LlmsIndex): void {
+		if (!isValidIndex(index)) return;
 		try {
 			fs.mkdirSync(this.#configDir, { recursive: true });
 			fs.writeFileSync(this.cachePath, JSON.stringify(index, null, 2));
@@ -167,8 +181,10 @@ export class KnowledgeService {
 		if (!response.ok) {
 			throw new Error(`Failed to fetch llms.txt: HTTP ${response.status}`);
 		}
-		const content = await response.text();
-		const index = parseLlmsTxt(content);
+		const index = parseLlmsTxt(await response.text());
+		if (index.topics.length === 0) {
+			throw new Error("Failed to parse llms.txt: no federated documentation topics found");
+		}
 		this.#index = index;
 		this.saveCache(index);
 		return index;
@@ -187,8 +203,22 @@ export class KnowledgeService {
 		}
 	}
 
-	getProductNames(): string[] {
+	getTopicNames(): string[] {
 		if (!this.#index) return [];
-		return this.#index.products.map(p => p.name).sort();
+		return this.#index.topics.map(topic => topic.name).sort();
+	}
+
+	getTopicSummary(): string {
+		if (!this.#index) return "";
+		const topicsByCategory = new Map<string, string[]>();
+		for (const topic of this.#index.topics) {
+			const names = topicsByCategory.get(topic.category) ?? [];
+			names.push(topic.name);
+			topicsByCategory.set(topic.category, names);
+		}
+		return [...topicsByCategory]
+			.sort(([left], [right]) => left.localeCompare(right))
+			.map(([category, names]) => `${category}: ${names.sort().join(", ")}`)
+			.join("; ");
 	}
 }