@f5-sales-demo/xcsh 19.94.2 → 19.95.0

package/package.json

@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@f5-sales-demo/xcsh",
-	"version": "19.94.2",
+	"version": "19.95.0",
 	"description": "Coding agent CLI with read, bash, edit, write tools and session management",
 	"homepage": "https://github.com/f5-sales-demo/xcsh",
 	"author": "Can Boluk",
@@ -31,9 +31,9 @@
 		"xcsh": "src/cli.ts"
 	},
 	"scripts": {
-		"build": "bun run generate-build-info && bun run generate-extension-capabilities && bun run generate-api-spec-index && bun run generate-branding-index && bun run generate-terraform-index && bun run generate-console-catalog && bun run generate-console-field-metadata && test -f src/internal-urls/api-spec-index.generated.ts && bun --cwd=../stats scripts/generate-client-bundle.ts --generate && bun --cwd=../office-pane scripts/generate-client-bundle.ts --generate && bun --cwd=../natives run embed:native && bun build --compile --define PI_COMPILED=true --external mupdf --root ../.. ./src/cli.ts --outfile dist/xcsh && bun --cwd=../natives run embed:native --reset && bun --cwd=../stats scripts/generate-client-bundle.ts --reset && bun --cwd=../office-pane scripts/generate-client-bundle.ts --reset",
+		"build": "bun run generate-build-info && bun run generate-extension-capabilities && bun run generate-api-spec-index && bun run generate-branding-index && bun run generate-sitecli-index && bun run generate-terraform-index && bun run generate-console-catalog && bun run generate-console-field-metadata && test -f src/internal-urls/api-spec-index.generated.ts && bun --cwd=../stats scripts/generate-client-bundle.ts --generate && bun --cwd=../office-pane scripts/generate-client-bundle.ts --generate && bun --cwd=../natives run embed:native && bun build --compile --define PI_COMPILED=true --external mupdf --root ../.. ./src/cli.ts --outfile dist/xcsh && bun --cwd=../natives run embed:native --reset && bun --cwd=../stats scripts/generate-client-bundle.ts --reset && bun --cwd=../office-pane scripts/generate-client-bundle.ts --reset",
 		"check": "biome check . && bun run format-prompts -- --check && bun run check:types",
-		"check:types": "bun run generate-build-info && bun run generate-extension-capabilities && bun run generate-api-spec-index && bun run generate-branding-index && bun run generate-terraform-index && tsgo -p tsconfig.json --noEmit",
+		"check:types": "bun run generate-build-info && bun run generate-extension-capabilities && bun run generate-api-spec-index && bun run generate-branding-index && bun run generate-sitecli-index && bun run generate-terraform-index && tsgo -p tsconfig.json --noEmit",
 		"lint": "biome lint .",
 		"check:bundle": "bun scripts/check-bundle.ts",
 		"test": "bun run generate-build-info && bun run generate-extension-capabilities && bun run generate-api-spec-index && bun run generate-console-catalog && bun run generate-console-field-metadata && bun scripts/bun-test-guarded.ts --max-concurrency 4",
@@ -44,6 +44,7 @@
 		"generate-docs-index": "bun scripts/generate-docs-index.ts",
 		"generate-api-spec-index": "bun scripts/generate-api-spec-index.ts",
 		"generate-branding-index": "bun scripts/generate-branding-index.ts",
+		"generate-sitecli-index": "bun scripts/generate-sitecli-index.ts",
 		"generate-build-info": "bun scripts/generate-build-info.ts",
 		"generate-extension-capabilities": "bun scripts/generate-extension-capabilities.ts",
 		"generate-terraform-index": "bun scripts/generate-terraform-index.ts",
@@ -56,13 +57,13 @@
 	"dependencies": {
 		"@agentclientprotocol/sdk": "1.3.0",
 		"@mozilla/readability": "^0.6",
-		"@f5-sales-demo/xcsh-stats": "19.94.2",
-		"@f5-sales-demo/pi-agent-core": "19.94.2",
-		"@f5-sales-demo/pi-ai": "19.94.2",
-		"@f5-sales-demo/pi-natives": "19.94.2",
-		"@f5-sales-demo/pi-resource-management": "19.94.2",
-		"@f5-sales-demo/pi-tui": "19.94.2",
-		"@f5-sales-demo/pi-utils": "19.94.2",
+		"@f5-sales-demo/xcsh-stats": "19.95.0",
+		"@f5-sales-demo/pi-agent-core": "19.95.0",
+		"@f5-sales-demo/pi-ai": "19.95.0",
+		"@f5-sales-demo/pi-natives": "19.95.0",
+		"@f5-sales-demo/pi-resource-management": "19.95.0",
+		"@f5-sales-demo/pi-tui": "19.95.0",
+		"@f5-sales-demo/pi-utils": "19.95.0",
 		"@sinclair/typebox": "^0.34",
 		"@xterm/headless": "^6.0",
 		"ajv": "^8.20",

package/scripts/generate-sitecli-index.ts

@@ -0,0 +1,104 @@
+// Embeds the Customer Edge Site CLI command surface, so the agent knows it without a
+// network round trip.
+//
+// The source of truth is sitecli/catalog.json in f5-sales-demo/mcn, which is produced
+// by capturing the node's own self-describing catalog rather than transcribed from any
+// document. Resolution order matches generate-terraform-index.ts and
+// generate-branding-index.ts: a sibling checkout first, then raw.githubusercontent.
+import * as fs from "node:fs/promises";
+import * as path from "node:path";
+
+const OUTPUT_FILE = path.join(import.meta.dir, "..", "src", "internal-urls", "sitecli-index.generated.ts");
+
+const LOCAL_CATALOG_PATH = path.resolve(import.meta.dir, "..", "..", "..", "..", "mcn", "sitecli", "catalog.json");
+
+const GITHUB_RAW_URL = "https://raw.githubusercontent.com/f5-sales-demo/mcn/main/sitecli/catalog.json";
+
+/** Shape of sitecli/catalog.json as committed by mcn. */
+interface SiteCliCatalog {
+	build: string;
+	source?: { site?: string; node?: string };
+	commands: Record<
+		string,
+		{
+			category: string;
+			/** "ExecUser" (read-only) or "Exec" (privileged, mutates or reads a state marker). */
+			tier: string;
+			/** Illustrative only — often a placeholder such as " container-id". */
+			example?: string;
+			/** "GLOBAL" means a dedicated GET endpoint, NOT reachable via exec-user. */
+			scope?: string;
+		}
+	>;
+}
+
+async function loadCatalog(): Promise<SiteCliCatalog> {
+	const localFile = Bun.file(LOCAL_CATALOG_PATH);
+	if (await localFile.exists()) {
+		console.log(`Reading from local checkout: ${LOCAL_CATALOG_PATH}`);
+		return localFile.json();
+	}
+
+	console.log(`Local not found, fetching from ${GITHUB_RAW_URL}`);
+	const headers: Record<string, string> = {};
+	const token = process.env.GITHUB_TOKEN || process.env.GH_TOKEN;
+	if (token) {
+		headers.Authorization = `token ${token}`;
+	}
+
+	const response = await fetch(GITHUB_RAW_URL, { headers });
+	if (!response.ok) {
+		throw new Error(`Failed to fetch sitecli catalog.json: ${response.status} ${response.statusText}`);
+	}
+	return (await response.json()) as SiteCliCatalog;
+}
+
+/**
+ * Which endpoint a command must be sent to. This is derived here rather than left to
+ * the caller because getting it wrong returns "command not supported" — the same
+ * message as a command that does not exist — so the mistake reads as a missing
+ * command rather than a wrong transport.
+ */
+function transportFor(entry: { tier: string; scope?: string }): "global-get" | "exec-user" | "exec" {
+	if (entry.scope === "GLOBAL") return "global-get";
+	return entry.tier === "Exec" ? "exec" : "exec-user";
+}
+
+function generateTypeScript(catalog: SiteCliCatalog): string {
+	const commands = Object.fromEntries(
+		Object.entries(catalog.commands)
+			.sort(([a], [b]) => a.localeCompare(b))
+			.map(([name, entry]) => [
+				name,
+				{
+					category: entry.category,
+					tier: entry.tier,
+					transport: transportFor(entry),
+					mutating: entry.tier === "Exec",
+					...(entry.example ? { example: entry.example.trim() } : {}),
+					...(entry.scope ? { scope: entry.scope } : {}),
+				},
+			]),
+	);
+
+	return `${[
+		"// AUTO-GENERATED — do not edit. Run `bun generate-sitecli-index` to regenerate.",
+		"//",
+		"// Source: f5-sales-demo/mcn sitecli/catalog.json, captured from a live Customer Edge.",
+		"// The command surface depends on the node software build, so SITECLI_BUILD records",
+		"// which build this describes.",
+		"",
+		`export const SITECLI_BUILD = ${JSON.stringify(catalog.build)};`,
+		"",
+		`export const SITECLI_SOURCE = ${JSON.stringify(catalog.source ?? {}, null, 2)} as const;`,
+		"",
+		`export const SITECLI_COMMANDS = ${JSON.stringify(commands, null, 2)} as const;`,
+		"",
+	].join("\n")}`;
+}
+
+const catalog = await loadCatalog();
+const output = generateTypeScript(catalog);
+await fs.writeFile(OUTPUT_FILE, output, "utf-8");
+await Bun.$`bunx biome format --write ${OUTPUT_FILE}`.quiet();
+console.log(`Generated ${OUTPUT_FILE} (${Object.keys(catalog.commands).length} commands, build ${catalog.build})`);

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

@@ -17,17 +17,17 @@ export interface BuildInfo {
 }
 
 export const BUILD_INFO: BuildInfo = {
-	"version": "19.94.2",
-	"commit": "3183b58019ae458ed28546c5b2ec77596ecc1533",
-	"shortCommit": "3183b58",
+	"version": "19.95.0",
+	"commit": "6239a5a701200eab5295f16c6b7698898480d4b0",
+	"shortCommit": "6239a5a",
 	"branch": "main",
-	"tag": "v19.94.2",
-	"commitDate": "2026-07-26T14:22:07Z",
-	"buildDate": "2026-07-26T14:45:04.280Z",
+	"tag": "v19.95.0",
+	"commitDate": "2026-07-26T17:07:54Z",
+	"buildDate": "2026-07-26T17:33:27.485Z",
 	"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/3183b58019ae458ed28546c5b2ec77596ecc1533",
-	"releaseUrl": "https://github.com/f5-sales-demo/xcsh/releases/tag/v19.94.2"
+	"commitUrl": "https://github.com/f5-sales-demo/xcsh/commit/6239a5a701200eab5295f16c6b7698898480d4b0",
+	"releaseUrl": "https://github.com/f5-sales-demo/xcsh/releases/tag/v19.95.0"
 };

package/src/internal-urls/sitecli-index.generated.ts

@@ -0,0 +1,237 @@
+// AUTO-GENERATED — do not edit. Run `bun generate-sitecli-index` to regenerate.
+//
+// Source: f5-sales-demo/mcn sitecli/catalog.json, captured from a live Customer Edge.
+// The command surface depends on the node software build, so SITECLI_BUILD records
+// which build this describes.
+
+export const SITECLI_BUILD = "crt-20250613-3382";
+
+export const SITECLI_SOURCE = {
+	node: "f5-xc-ce-vm-01",
+	site: "ar-bgp-eastus01",
+} as const;
+
+export const SITECLI_COMMANDS = {
+	"chronyc-sources": {
+		category: "Network Troubleshooting",
+		tier: "ExecUser",
+		transport: "exec-user",
+		mutating: false,
+	},
+	"crictl-images": {
+		category: "System Troubleshooting",
+		tier: "ExecUser",
+		transport: "exec-user",
+		mutating: false,
+	},
+	"crictl-inspect": {
+		category: "System Troubleshooting",
+		tier: "ExecUser",
+		transport: "exec-user",
+		mutating: false,
+		example: "container-id",
+	},
+	"crictl-logs": {
+		category: "System Troubleshooting",
+		tier: "ExecUser",
+		transport: "exec-user",
+		mutating: false,
+		example: "container-id",
+	},
+	"crictl-ps": {
+		category: "System Troubleshooting",
+		tier: "ExecUser",
+		transport: "exec-user",
+		mutating: false,
+	},
+	"crictl-ps-a": {
+		category: "System Troubleshooting",
+		tier: "ExecUser",
+		transport: "exec-user",
+		mutating: false,
+	},
+	"curl-host": {
+		category: "Network Troubleshooting",
+		tier: "ExecUser",
+		transport: "exec-user",
+		mutating: false,
+		example: "-v cloud.f5.com",
+	},
+	"curl-vega": {
+		category: "Network Troubleshooting",
+		tier: "ExecUser",
+		transport: "exec-user",
+		mutating: false,
+		example: "-v cloud.f5.com",
+	},
+	diagnosis: {
+		category: "System Troubleshooting",
+		tier: "ExecUser",
+		transport: "global-get",
+		mutating: false,
+		example: "no argument needed",
+		scope: "GLOBAL",
+	},
+	dig: {
+		category: "Network Troubleshooting",
+		tier: "ExecUser",
+		transport: "exec-user",
+		mutating: false,
+		example: "@192.168.0.2 http://volterra.azurecr.io",
+	},
+	"docker-images": {
+		category: "System Troubleshooting",
+		tier: "ExecUser",
+		transport: "exec-user",
+		mutating: false,
+	},
+	"docker-inspect": {
+		category: "System Troubleshooting",
+		tier: "ExecUser",
+		transport: "exec-user",
+		mutating: false,
+		example: "container-id OR name",
+	},
+	"docker-logs": {
+		category: "System Troubleshooting",
+		tier: "ExecUser",
+		transport: "exec-user",
+		mutating: false,
+		example: "container-id OR name",
+	},
+	"docker-ps": {
+		category: "System Troubleshooting",
+		tier: "ExecUser",
+		transport: "exec-user",
+		mutating: false,
+	},
+	"docker-ps-a": {
+		category: "System Troubleshooting",
+		tier: "ExecUser",
+		transport: "exec-user",
+		mutating: false,
+	},
+	dropstats: {
+		category: "Network Troubleshooting",
+		tier: "ExecUser",
+		transport: "exec-user",
+		mutating: false,
+	},
+	"dropstats-non-zero": {
+		category: "Network Troubleshooting",
+		tier: "ExecUser",
+		transport: "exec-user",
+		mutating: false,
+	},
+	"flow-l": {
+		category: "Network Troubleshooting",
+		tier: "ExecUser",
+		transport: "exec-user",
+		mutating: false,
+	},
+	"flow-l-match": {
+		category: "Network Troubleshooting",
+		tier: "ExecUser",
+		transport: "exec-user",
+		mutating: false,
+		example: "100.127.192.10:53",
+	},
+	health: {
+		category: "System Troubleshooting",
+		tier: "ExecUser",
+		transport: "global-get",
+		mutating: false,
+		example: "no argument needed",
+		scope: "GLOBAL",
+	},
+	ip: {
+		category: "Network Troubleshooting",
+		tier: "ExecUser",
+		transport: "exec-user",
+		mutating: false,
+		example: "help OR addr",
+	},
+	"ip-link-set": {
+		category: "Network Troubleshooting",
+		tier: "Exec",
+		transport: "exec",
+		mutating: true,
+		example: "(<device>||<group>) (up||down)",
+	},
+	"ip-link-show": {
+		category: "Network Troubleshooting",
+		tier: "ExecUser",
+		transport: "exec-user",
+		mutating: false,
+	},
+	"ipsec-status": {
+		category: "Network Troubleshooting",
+		tier: "ExecUser",
+		transport: "exec-user",
+		mutating: false,
+	},
+	"ipsec-statusall": {
+		category: "Network Troubleshooting",
+		tier: "ExecUser",
+		transport: "exec-user",
+		mutating: false,
+	},
+	journalctl: {
+		category: "System Troubleshooting",
+		tier: "ExecUser",
+		transport: "exec-user",
+		mutating: false,
+		example: "-u vpm -n 200",
+	},
+	netstat: {
+		category: "Network Troubleshooting",
+		tier: "ExecUser",
+		transport: "exec-user",
+		mutating: false,
+	},
+	nh: {
+		category: "Network Troubleshooting",
+		tier: "ExecUser",
+		transport: "exec-user",
+		mutating: false,
+		example: "--help OR --list",
+	},
+	rt: {
+		category: "Network Troubleshooting",
+		tier: "ExecUser",
+		transport: "exec-user",
+		mutating: false,
+		example: "--help OR --dump $vrf-id OR --get $ipv4 --vrf $vrf-id",
+	},
+	"show-ip-bgp": {
+		category: "Network Troubleshooting",
+		tier: "ExecUser",
+		transport: "exec-user",
+		mutating: false,
+	},
+	"show-ip-bgp-neighbors": {
+		category: "Network Troubleshooting",
+		tier: "ExecUser",
+		transport: "exec-user",
+		mutating: false,
+	},
+	"show-ip-bgp-neighbors-advertised-route": {
+		category: "Network Troubleshooting",
+		tier: "ExecUser",
+		transport: "exec-user",
+		mutating: false,
+	},
+	"show-ip-bgp-summary": {
+		category: "Network Troubleshooting",
+		tier: "ExecUser",
+		transport: "exec-user",
+		mutating: false,
+	},
+	vif: {
+		category: "Network Troubleshooting",
+		tier: "ExecUser",
+		transport: "exec-user",
+		mutating: false,
+		example: "--list",
+	},
+} as const;

package/src/internal-urls/terraform-index.generated.ts

@@ -210,7 +210,7 @@ export const TERRAFORM_INDEX: TerraformIndex = {
 		{
 			name: "Monitoring",
 			slug: "monitoring",
-			description: "Log receivers, alert policies, APM, and global logging configuration",
+			description: "Log receivers, alert policies, alert templates, and global logging configuration",
 			resource_count: 4,
 			resources: ["alert_receiver", "alert_template", "global_log_receiver", "log_receiver"],
 		},

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

@@ -68,6 +68,7 @@ const PLUGIN_HOST = "plugin";
 const CHANGES_HOST = "changes";
 const SOURCE_HOST = "source";
 const FLEET_HOST = "fleet";
+const SITECLI_HOST = "sitecli";
 const EMPTY_INDEX: ApiSpecIndex = { version: "unavailable", timestamp: "", domains: [] };
 const EMPTY_CATALOG_INDEX: ApiCatalogIndex = {
 	version: "unavailable",
@@ -202,6 +203,39 @@ interface BrandingDeprecationEntry {
 	required_providers_block?: string;
 }
 
+interface SiteCliCommand {
+	category: string;
+	tier: string;
+	transport: string;
+	mutating: boolean;
+	example?: string;
+	scope?: string;
+}
+
+let _siteCliCache: { build: string; commands: Record<string, SiteCliCommand> } | null = null;
+
+/** Mirrors loadBranding(): lazily required, cached, and degrading to an empty index
+ * with a warning rather than throwing when the generated file is absent. */
+function loadSiteCli(): { build: string; commands: Record<string, SiteCliCommand> } {
+	if (_siteCliCache) return _siteCliCache;
+	try {
+		const mod = require("./sitecli-index.generated") as {
+			SITECLI_BUILD?: string;
+			SITECLI_COMMANDS?: Record<string, SiteCliCommand>;
+		};
+		_siteCliCache = {
+			build: mod.SITECLI_BUILD ?? "unknown",
+			commands: (mod.SITECLI_COMMANDS ?? {}) as Record<string, SiteCliCommand>,
+		};
+	} catch (err) {
+		logger.warn("sitecli index unavailable, sitecli protocol disabled", {
+			error: err instanceof Error ? err.message : String(err),
+		});
+		_siteCliCache = { build: "unavailable", commands: {} };
+	}
+	return _siteCliCache;
+}
+
 let _brandingCache: {
 	version: string;
 	canonical: Record<string, BrandingCanonicalEntry>;
@@ -412,6 +446,10 @@ export class InternalDocsProtocolHandler implements ProtocolHandler {
 			return this.#resolveBranding(url);
 		}
 
+		if (host === SITECLI_HOST) {
+			return this.#resolveSiteCli(url);
+		}
+
 		if (host === USER_ROUTE) {
 			return this.#resolveUserProfile(url);
 		}
@@ -574,6 +612,62 @@ export class InternalDocsProtocolHandler implements ProtocolHandler {
 		};
 	}
 
+	/** Customer Edge Site CLI command surface. The transport field is the reason this
+	 * is embedded rather than looked up: sending a command to the wrong endpoint
+	 * returns "command not supported", which is indistinguishable from the command not
+	 * existing, so guessing produces a confidently wrong answer. */
+	#resolveSiteCli(url: InternalUrl): InternalResource {
+		const subpath = (url.rawPathname ?? url.pathname).replace(/^\/+/, "").replace(/\/+$/, "");
+		const { build, commands } = loadSiteCli();
+
+		let content: string;
+		if (!subpath) {
+			const lines = [
+				`# Customer Edge Site CLI (build ${build})`,
+				"",
+				"Transport is decided by the entry, not by preference. Sending a command to the",
+				"wrong endpoint returns `command not supported` — the same message as a command",
+				"that does not exist.",
+				"",
+				"| Command | Category | Tier | Transport |",
+				"| --- | --- | --- | --- |",
+			];
+			for (const [name, c] of Object.entries(commands)) {
+				lines.push(`| ${name} | ${c.category} | ${c.tier} | ${c.transport}${c.mutating ? " (MUTATES)" : ""} |`);
+			}
+			lines.push("", `Read \`xcsh://sitecli/<command>\` for one entry.`);
+			content = lines.join("\n");
+		} else {
+			const entry = commands[subpath];
+			content = entry
+				? [
+						`# ${subpath}`,
+						"",
+						`- category: ${entry.category}`,
+						`- tier: ${entry.tier}`,
+						`- transport: ${entry.transport}`,
+						`- mutating: ${entry.mutating}`,
+						...(entry.scope ? [`- scope: ${entry.scope}`] : []),
+						...(entry.example ? [`- example argument: \`${entry.example}\``] : []),
+						"",
+						entry.transport === "global-get"
+							? "GLOBAL scope: GET .../vpm/debug/global/" + subpath + " — NOT reachable via exec-user."
+							: entry.transport === "exec"
+								? "Exec tier: privileged and mutating. Do not run speculatively."
+								: 'POST .../vpm/debug/{node}/exec-user with {"command":["' + subpath + '", ...]}.',
+					].join("\n")
+				: `Unknown Site CLI command: ${subpath}\n\nRead xcsh://sitecli for the full list (build ${build}).`;
+		}
+
+		return {
+			url: url.href,
+			content,
+			contentType: "text/markdown",
+			size: Buffer.byteLength(content, "utf-8"),
+			sourcePath: `xcsh://sitecli${subpath ? `/${subpath}` : ""}`,
+		};
+	}
+
 	#brandingOverview(): string {
 		const { version, canonical, deprecations } = loadBranding();
 		const lines = [`# F5 Distributed Cloud Branding (v${version})`, "", "## Product Names (Current API)", ""];

package/src/prompts/tools/ce-sitecli.md

@@ -0,0 +1,83 @@
+Run diagnostic commands on an F5 Distributed Cloud Customer Edge node.
+
+The Site CLI runs on the CE itself and is reached over the `vpm/debug` API. The command
+surface is embedded at `xcsh://sitecli` — read it rather than guessing, because command
+availability depends on the node software build.
+
+<critical>
+The transport is decided by the command's catalog entry, NOT by preference. Sending a
+command to the wrong endpoint returns `command not supported`, which is the SAME message
+returned for a command that does not exist. Reporting "that command is unavailable" when
+the transport was wrong is a confidently wrong answer, and it is the most common failure
+here.
+</critical>
+
+## Three transports
+
+|Entry says|Send to|Returns|
+|---|---|---|
+|`transport: global-get`|`GET …/vpm/debug/global/<cmd>`|JSON|
+|`transport: exec-user`|`POST …/vpm/debug/<node>/exec-user`|text|
+|`transport: exec`|`POST …/vpm/debug/<node>/exec`|text|
+
+`exec-user` and `exec` take a body of the form:
+
+```json
+{ "namespace": "system", "site": "<site>", "node": "<node>", "command": ["<cmd>", "<arg>", "..."] }
+```
+
+Arguments are separate array elements, not one string:
+`["journalctl", "-u", "vpm", "-n", "200"]`.
+
+`global-get` takes no body and no arguments. Only `health` and `diagnosis` use it.
+
+<prohibited>
+Never run a command whose entry has `mutating: true` unless the user has asked for that
+specific change and understands the node is live. On the current build that is
+`ip-link-set`, which takes an interface down — including, on a remote CE, the interface
+you are managing it through. Newer builds add `systemctl-restart-NetworkManager`,
+`systemctl-restart-crio`, `systemctl-restart-kubelet` and `systemctl-start-crio-prune`,
+which restart services under a live data plane.
+</prohibited>
+
+## Discovering the surface on an unknown node
+
+POST to `exec-user` with the `command` key **omitted**. That returns the node's own
+catalog. Sending an unknown command value instead returns an error, not the catalog.
+
+## Before running anything, check the node is reachable
+
+The `vpm/debug` API is served through the F5 Distributed Cloud control plane over the
+tunnel that registration establishes. It answers only when the site is `ONLINE`:
+
+```
+GET /api/config/namespaces/system/sites/<site>  ->  .spec.site_state
+```
+
+If the site is not `ONLINE`, no command on this page will work, and the node also
+refuses SSH as shipped. The only remaining route is the Azure Serial Console, which
+needs a human at a terminal.
+
+## Reading results
+- `health` first. It is cheap and structured, and `state: PROVISIONED` confirms the node
+  registered and is configured.
+- Long output is genuinely long: `nh --list` runs to thousands of lines and the flow
+  table holds hundreds of thousands of entries. Prefer `flow-l-match <ip>[:port]` over
+  `flow-l`, and `dropstats-non-zero` over `dropstats`.
+- Drop counters are lifetime totals, not rates. A non-zero counter means nothing on its
+  own; run the command twice and compare while reproducing the problem.
+
+<instruction>
+Two traps that produce plausible but wrong conclusions:
+1. `rt --dump` takes the vRouter table id, which is NOT the `vrf-id` that
+   `show-ip-bgp-summary` prints. Passing the BGP number returns
+   `No such file or directory`, which reads as a broken node rather than a wrong
+   argument.
+2. The node runs Docker AND CRI-O simultaneously. `vpm`, `argo_watch` and
+   `site-console` are Docker containers; Kubernetes workloads are CRI-O. A three-entry
+   `docker-ps` is the complete list, not a symptom, and `crictl-*` will not show `vpm`.
+</instruction>
+
+For anything beyond the command surface — what output means, and the diagnostic
+sequences that chain commands — read the Customer Edge documentation in the `mcn`
+documentation set rather than inferring it.