@f5-sales-demo/xcsh 20.20.6 → 20.22.2

package/CHANGELOG.md

@@ -6,6 +6,16 @@
 
 ### Added
 
+- Added strict `xcsh://registry/provider/<namespace>/<type>` and
+  `xcsh://registry/module/<namespace>/<name>/<provider>` Terraform Registry lookups with bounded,
+  protocol-native discovery and actionable failures
+  ([#3019](https://github.com/f5-sales-demo/xcsh/issues/3019),
+   [#3361](https://github.com/f5-sales-demo/xcsh/issues/3361)).
+- Added a transactional vLLM `/login` flow with validated HTTP(S) endpoints, masked optional keys,
+  pre-commit model probing, vLLM-only model selection, provider-only refresh, secure atomic
+  persistence, and rollback
+  ([#2947](https://github.com/f5-sales-demo/xcsh/issues/2947),
+   [#3361](https://github.com/f5-sales-demo/xcsh/issues/3361)).
 - Added provenance-validated, deterministic `render_map` PNG generation with OpenStreetMap tile
   policy compliance, schematic and text fallbacks, and optional atomic PNG/GeoJSON export
   ([#3202](https://github.com/f5-sales-demo/xcsh/issues/3202)).
@@ -26,6 +36,13 @@
 
 ### Fixed
 
+- Isolated post-publication npm verification in a job-local writable prefix and failed immediately
+  for non-registry installation errors
+  ([#3375](https://github.com/f5-sales-demo/xcsh/issues/3375)).
+- Consumed vLLM-advertised context limits with bounded output budgets while preserving compatibility
+  fallbacks when metadata is absent
+  ([#2947](https://github.com/f5-sales-demo/xcsh/issues/2947),
+   [#3361](https://github.com/f5-sales-demo/xcsh/issues/3361)).
 - Restored bare `xcsh update` as a backward-compatible executable updater while preserving
   manifest-based resource updates and the explicit `xcsh self-update` command
   ([#3249](https://github.com/f5-sales-demo/xcsh/issues/3249)).

package/package.json

@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@f5-sales-demo/xcsh",
-	"version": "20.20.6",
+	"version": "20.22.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",
-		"@f5-sales-demo/pi-agent-core": "20.20.6",
-		"@f5-sales-demo/pi-ai": "20.20.6",
-		"@f5-sales-demo/pi-natives": "20.20.6",
-		"@f5-sales-demo/pi-resource-management": "20.20.6",
-		"@f5-sales-demo/pi-tui": "20.20.6",
-		"@f5-sales-demo/pi-utils": "20.20.6",
-		"@f5-sales-demo/xcsh-stats": "20.20.6",
+		"@f5-sales-demo/pi-agent-core": "20.22.2",
+		"@f5-sales-demo/pi-ai": "20.22.2",
+		"@f5-sales-demo/pi-natives": "20.22.2",
+		"@f5-sales-demo/pi-resource-management": "20.22.2",
+		"@f5-sales-demo/pi-tui": "20.22.2",
+		"@f5-sales-demo/pi-utils": "20.22.2",
+		"@f5-sales-demo/xcsh-stats": "20.22.2",
 		"@mozilla/readability": "^0.6",
 		"@sinclair/typebox": "^0.34",
 		"@xterm/headless": "^6.0",

package/src/cli.ts

@@ -118,6 +118,7 @@ function requestsHelp(args: readonly string[]): boolean {
 export function runCli(argv: string[]): Promise<void> {
 	// --help and --version are handled by run() directly, don't rewrite those.
 	// Everything else that isn't a known subcommand routes to "launch".
+	// Keeping this routing boundary explicit makes the CLI fallback easy to audit.
 	const first = argv[0];
 	if (!isSubcommand(first)) {
 		try {

package/src/config/model-registry.ts

@@ -14,6 +14,7 @@ import {
 	type Model,
 	type ModelManagerOptions,
 	type ModelRefreshStrategy,
+	NO_AUTH_API_KEY,
 	type OAuthCredentials,
 	type OAuthLoginCallbacks,
 	openaiCodexModelManagerOptions,
@@ -31,6 +32,7 @@ import { type Static, Type } from "@sinclair/typebox";
 import { type ConfigError, ConfigFile } from "../config";
 import { hasLiteLLMEnv, probeAndUpgradeLiteLLMConfig, startupHealthCheck } from "../config/auto-config";
 import { parseModelString, resolveProviderModelReference } from "../config/model-resolver";
+import { parseVllmModelsPayload } from "../config/vllm-config";
 import { isValidThemeColor, type ThemeColor } from "../modes/theme/theme";
 import type { AuthStorage, OAuthCredential } from "../session/auth-storage";
 import {
@@ -45,7 +47,7 @@ import { type Settings, settings } from "./settings";
 
 export type { CanonicalModelIndex, CanonicalModelRecord, CanonicalModelVariant, ModelEquivalenceConfig };
 
-export const kNoAuth = "N/A";
+export const kNoAuth = NO_AUTH_API_KEY;
 
 export function isAuthenticated(apiKey: string | undefined | null): apiKey is string {
 	return Boolean(apiKey) && apiKey !== kNoAuth;
@@ -1737,8 +1739,11 @@ export class ModelRegistry {
 		if (!response.ok) {
 			throw new Error(`HTTP ${response.status} from ${modelsUrl}`);
 		}
-		const payload = (await response.json()) as { data?: Array<{ id: string }> };
-		const items = payload.data ?? [];
+		const payload = await response.json();
+		const items: Array<{ id: string; contextWindow?: number }> =
+			providerConfig.provider === "vllm"
+				? parseVllmModelsPayload(payload)
+				: ((payload as { data?: Array<{ id: string }> }).data ?? []);
 		const discovered: Model<Api>[] = [];
 		for (const item of items) {
 			const id = item.id;
@@ -1753,8 +1758,11 @@ export class ModelRegistry {
 					reasoning: false,
 					input: ["text"],
 					cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
-					contextWindow: 128000,
-					maxTokens: 8192,
+					contextWindow: item.contextWindow ?? 128000,
+					maxTokens:
+						item.contextWindow === undefined
+							? 8192
+							: Math.max(1, Math.min(8192, Math.floor(item.contextWindow / 4))),
 					headers,
 				}),
 			);

package/src/config/vllm-config.ts

@@ -0,0 +1,212 @@
+import { randomUUID } from "node:crypto";
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { Document, isMap, parseDocument } from "yaml";
+
+const CONFIG_DIR_MODE = 0o700;
+const MODELS_FILE_MODE = 0o600;
+const DEFAULT_PROBE_TIMEOUT_MS = 5_000;
+const CONTEXT_FIELDS = [
+	"max_model_len",
+	"max_model_length",
+	"max_context_length",
+	"context_length",
+	"context_window",
+	"max_sequence_length",
+] as const;
+
+export const DEFAULT_VLLM_BASE_URL = "http://127.0.0.1:8000/v1";
+
+export interface VllmConfig {
+	baseUrl: string;
+}
+
+export interface VllmDiscoveredModel {
+	id: string;
+	contextWindow?: number;
+}
+
+export interface VllmProbeResult {
+	models: VllmDiscoveredModel[];
+}
+
+export interface VllmProbeOptions {
+	fetch?: (input: string | URL | Request, init?: RequestInit) => Promise<Response>;
+	timeoutMs?: number;
+	signal?: AbortSignal;
+}
+
+export interface WriteVllmModelsConfigOptions {
+	authenticated: boolean;
+}
+
+export function normalizeVllmBaseUrl(value: string): string {
+	const trimmed = value.trim();
+	let parsed: URL;
+	try {
+		parsed = new URL(trimmed);
+	} catch {
+		throw new Error("vLLM Base URL must be a valid HTTP or HTTPS URL");
+	}
+	if (parsed.protocol !== "http:" && parsed.protocol !== "https:") {
+		throw new Error("vLLM Base URL must use HTTP or HTTPS");
+	}
+	if (parsed.username || parsed.password || parsed.search || parsed.hash) {
+		throw new Error("vLLM Base URL must not contain credentials, query parameters, or a fragment");
+	}
+	return parsed.toString().replace(/\/+$/, "");
+}
+
+function parseModelsDocument(content: string, filePath: string): ReturnType<typeof parseDocument> {
+	const document = parseDocument(content, { prettyErrors: false });
+	if (document.errors.length > 0) {
+		throw new Error(`Cannot update ${filePath}: invalid YAML (${document.errors[0]?.message ?? "parse error"})`);
+	}
+	if (document.contents !== null && !isMap(document.contents)) {
+		throw new Error(`Cannot update ${filePath}: the YAML root must be a map`);
+	}
+	const providers = document.get("providers", true);
+	if (providers !== undefined && providers !== null && !isMap(providers)) {
+		throw new Error(`Cannot update ${filePath}: providers must be a map`);
+	}
+	const vllm = document.getIn(["providers", "vllm"], true);
+	if (vllm !== undefined && vllm !== null && !isMap(vllm)) {
+		throw new Error(`Cannot update ${filePath}: providers.vllm must be a map`);
+	}
+	return document;
+}
+
+export function readVllmConfig(modelsPath: string): VllmConfig | undefined {
+	let content: string;
+	try {
+		content = fs.readFileSync(modelsPath, "utf8");
+	} catch (error) {
+		if ((error as NodeJS.ErrnoException).code === "ENOENT") return undefined;
+		throw error;
+	}
+	const document = parseModelsDocument(content, modelsPath);
+	const baseUrl = document.getIn(["providers", "vllm", "baseUrl"]);
+	if (typeof baseUrl !== "string" || !baseUrl.trim()) return undefined;
+	return { baseUrl: normalizeVllmBaseUrl(baseUrl) };
+}
+
+function positiveInteger(value: unknown): number | undefined {
+	if (typeof value === "number" && Number.isFinite(value) && value > 0) return Math.floor(value);
+	if (typeof value === "string" && value.trim()) {
+		const parsed = Number(value);
+		if (Number.isFinite(parsed) && parsed > 0) return Math.floor(parsed);
+	}
+	return undefined;
+}
+
+function discoveredContextWindow(entry: Record<string, unknown>): number | undefined {
+	for (const field of CONTEXT_FIELDS) {
+		const value = positiveInteger(entry[field]);
+		if (value !== undefined) return value;
+	}
+	return undefined;
+}
+
+export function parseVllmModelsPayload(payload: unknown): VllmDiscoveredModel[] {
+	if (typeof payload !== "object" || payload === null || !Array.isArray((payload as { data?: unknown }).data)) {
+		throw new Error("vLLM returned a malformed model catalog");
+	}
+
+	const models: VllmDiscoveredModel[] = [];
+	const seen = new Set<string>();
+	for (const rawEntry of (payload as { data: unknown[] }).data) {
+		if (typeof rawEntry !== "object" || rawEntry === null || typeof (rawEntry as { id?: unknown }).id !== "string") {
+			throw new Error("vLLM returned a malformed model catalog");
+		}
+		const entry = rawEntry as Record<string, unknown> & { id: string };
+		const id = entry.id.trim();
+		if (!id || seen.has(id)) continue;
+		seen.add(id);
+		const contextWindow = discoveredContextWindow(entry);
+		models.push(contextWindow === undefined ? { id } : { id, contextWindow });
+	}
+	if (models.length === 0) throw new Error("vLLM returned no models");
+	return models;
+}
+
+export async function probeVllmConnection(
+	baseUrl: string,
+	apiKey: string,
+	options: VllmProbeOptions = {},
+): Promise<VllmProbeResult> {
+	const normalizedBaseUrl = normalizeVllmBaseUrl(baseUrl);
+	const modelsUrl = `${normalizedBaseUrl}/models`;
+	const headers = new Headers({ Accept: "application/json" });
+	const trimmedApiKey = apiKey.trim();
+	if (trimmedApiKey) headers.set("Authorization", `Bearer ${trimmedApiKey}`);
+
+	const signal = options.signal ?? AbortSignal.timeout(options.timeoutMs ?? DEFAULT_PROBE_TIMEOUT_MS);
+	let response: Response;
+	try {
+		response = await (options.fetch ?? globalThis.fetch)(modelsUrl, { headers, signal });
+	} catch (error) {
+		const name = error instanceof Error ? error.name : "";
+		if (name === "TimeoutError" || name === "AbortError") {
+			throw new Error(`vLLM connection timed out at ${modelsUrl}`, { cause: error });
+		}
+		throw new Error(`Could not connect to vLLM at ${modelsUrl}`, { cause: error });
+	}
+
+	if (response.status === 401 || response.status === 403) {
+		throw new Error(`vLLM rejected the API key (HTTP ${response.status})`);
+	}
+	if (!response.ok) throw new Error(`vLLM model discovery failed with HTTP ${response.status}`);
+
+	let payload: unknown;
+	try {
+		payload = await response.json();
+	} catch (error) {
+		throw new Error("vLLM /models did not return valid JSON", { cause: error });
+	}
+	return { models: parseVllmModelsPayload(payload) };
+}
+
+async function atomicWrite(filePath: string, content: string): Promise<void> {
+	const directory = path.dirname(filePath);
+	await fs.promises.mkdir(directory, { recursive: true, mode: CONFIG_DIR_MODE });
+	await fs.promises.chmod(directory, CONFIG_DIR_MODE);
+
+	const tempPath = path.join(directory, `.${path.basename(filePath)}.${randomUUID()}.tmp`);
+	let handle: fs.promises.FileHandle | undefined;
+	try {
+		handle = await fs.promises.open(tempPath, "wx", MODELS_FILE_MODE);
+		await handle.writeFile(content, "utf8");
+		await handle.sync();
+		await handle.close();
+		handle = undefined;
+		await fs.promises.rename(tempPath, filePath);
+		await fs.promises.chmod(filePath, MODELS_FILE_MODE);
+	} catch (error) {
+		await handle?.close().catch(() => undefined);
+		await fs.promises.unlink(tempPath).catch(() => undefined);
+		throw error;
+	}
+}
+
+export async function writeVllmModelsConfig(
+	modelsPath: string,
+	baseUrl: string,
+	options: WriteVllmModelsConfigOptions,
+): Promise<void> {
+	let document: ReturnType<typeof parseDocument> | Document;
+	try {
+		document = parseModelsDocument(await fs.promises.readFile(modelsPath, "utf8"), modelsPath);
+	} catch (error) {
+		if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error;
+		document = new Document({});
+	}
+
+	document.setIn(["providers", "vllm", "baseUrl"], normalizeVllmBaseUrl(baseUrl));
+	document.setIn(["providers", "vllm", "api"], "openai-completions");
+	document.setIn(["providers", "vllm", "discovery", "type"], "openai-compat");
+	if (options.authenticated) document.deleteIn(["providers", "vllm", "auth"]);
+	else document.setIn(["providers", "vllm", "auth"], "none");
+	document.deleteIn(["providers", "vllm", "apiKey"]);
+
+	await atomicWrite(modelsPath, document.toString({ lineWidth: 0 }));
+}

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

@@ -17,17 +17,17 @@ export interface BuildInfo {
 }
 
 export const BUILD_INFO: BuildInfo = {
-	"version": "20.20.6",
-	"commit": "9e6b086eef492b654008d78ffd4f096385019004",
-	"shortCommit": "9e6b086",
+	"version": "20.22.2",
+	"commit": "ed93a01366838afc5ccd503a0bc678af72c92fe4",
+	"shortCommit": "ed93a01",
 	"branch": "main",
-	"tag": "v20.20.6",
-	"commitDate": "2026-08-21T13:13:58Z",
-	"buildDate": "2026-08-21T13:37:09.862Z",
+	"tag": "v20.22.2",
+	"commitDate": "2026-08-25T17:12:23+00:00",
+	"buildDate": "2026-08-26T01:20:47.235Z",
 	"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/9e6b086eef492b654008d78ffd4f096385019004",
-	"releaseUrl": "https://github.com/f5-sales-demo/xcsh/releases/tag/v20.20.6"
+	"commitUrl": "https://github.com/f5-sales-demo/xcsh/commit/ed93a01366838afc5ccd503a0bc678af72c92fe4",
+	"releaseUrl": "https://github.com/f5-sales-demo/xcsh/releases/tag/v20.22.2"
 };

package/src/internal-urls/fleet-resolve.ts

@@ -335,8 +335,12 @@ function authorityGuidance(authority: string): string[] {
 			return [
 				"**Authority: author.** Create, update and delete content here directly — documentation,",
 				"Terraform plans, howtos, diagrams, demo and traffic-generation scripts. You do not need to",
-				"ask permission to author; you do need to follow the governed path:",
-				"linked issue → branch → pull request → CI → auto-merge. Never commit to `main`.",
+				"ask permission to author; you do need to follow the governed path (Git SOPs):",
+				"1. **Comprehensive Issue First**: Always create a detailed GitHub issue before developing content.",
+				"2. **Feature Branch / Worktree**: Work in a dedicated `feature/`, `fix/`, `docs/`, or `chore/` branch or worktree. Never commit directly to `main`.",
+				"3. **PR & Linking**: Open a PR with explicit `Closes #N` issue linking.",
+				"4. **CI & Merge**: Poll CI until green, then squash merge.",
+				"5. **Post-Merge Hygiene**: Clean up local and remote feature branches, remove merged worktrees, and run `git fetch --prune`.",
 			];
 		case AUTHORITY_DELEGATE:
 			return [

package/src/internal-urls/index.ts

@@ -35,6 +35,7 @@ export * from "./mcp-protocol";
 export * from "./memory-protocol";
 export * from "./parse";
 export * from "./plugin-resolve";
+export * from "./registry-resolve";
 export * from "./router";
 export * from "./rule-protocol";
 export * from "./skill-protocol";

package/src/internal-urls/registry-resolve.ts

@@ -0,0 +1,257 @@
+import type { InternalResource, InternalUrl } from "./types";
+
+const DEFAULT_PROVIDER_BASE_URL = "https://registry.terraform.io/v1/providers";
+const DEFAULT_MODULE_BASE_URL = "https://registry.terraform.io/v1/modules";
+const DEFAULT_TIMEOUT_MS = 10_000;
+const SOURCE_NAME = /^[a-z0-9](?:[a-z0-9-]*[a-z0-9])?$/;
+
+export type RegistryFetch = (input: string | URL | Request, init?: RequestInit) => Promise<Response>;
+
+export interface RegistryResolverDeps {
+	readonly fetch: RegistryFetch;
+	readonly providerBaseUrl: string;
+	readonly moduleBaseUrl: string;
+	readonly timeoutMs: number;
+}
+
+interface ProviderVersion {
+	readonly version: string;
+	readonly protocols?: readonly string[];
+	readonly platforms?: readonly { readonly os: string; readonly arch: string }[];
+}
+
+interface ModuleMetadata {
+	readonly id?: string;
+	readonly namespace: string;
+	readonly name: string;
+	readonly provider: string;
+	readonly version: string;
+	readonly description?: string;
+	readonly source?: string;
+	readonly verified?: boolean;
+}
+
+type RegistryRoute =
+	| { readonly kind: "provider"; readonly namespace: string; readonly type: string }
+	| { readonly kind: "module"; readonly namespace: string; readonly name: string; readonly provider: string };
+
+function routeHelp(): string {
+	return "Expected xcsh://registry/provider/<namespace>/<type> or xcsh://registry/module/<namespace>/<name>/<provider>";
+}
+
+function parseRoute(url: InternalUrl): RegistryRoute {
+	const rawPath = url.rawPathname ?? url.pathname;
+	const segments = rawPath.startsWith("/") ? rawPath.slice(1).split("/") : rawPath.split("/");
+	if (segments[0] === "provider" && segments.length === 3) {
+		const [, namespace, type] = segments;
+		if (namespace && type) return validateRoute({ kind: "provider", namespace, type });
+	}
+	if (segments[0] === "module" && segments.length === 4) {
+		const [, namespace, name, provider] = segments;
+		if (namespace && name && provider) return validateRoute({ kind: "module", namespace, name, provider });
+	}
+	throw new Error(routeHelp());
+}
+
+function validateRoute(route: RegistryRoute): RegistryRoute {
+	const names =
+		route.kind === "provider" ? [route.namespace, route.type] : [route.namespace, route.name, route.provider];
+	for (const name of names) {
+		if (!SOURCE_NAME.test(name)) {
+			throw new Error(
+				`Invalid Terraform Registry source name "${name}": use lowercase ASCII letters, digits, and hyphens`,
+			);
+		}
+	}
+	return route;
+}
+
+function markdownResource(url: InternalUrl, content: string): InternalResource {
+	return {
+		url: url.href,
+		content,
+		contentType: "text/markdown",
+		size: Buffer.byteLength(content, "utf-8"),
+		sourcePath: url.href,
+	};
+}
+
+function providerVersions(value: unknown): readonly ProviderVersion[] | null {
+	if (typeof value !== "object" || value === null) return null;
+	const versions = (value as { versions?: unknown }).versions;
+	if (!Array.isArray(versions)) return null;
+	for (const entry of versions) {
+		if (typeof entry !== "object" || entry === null || typeof (entry as { version?: unknown }).version !== "string") {
+			return null;
+		}
+	}
+	return versions as ProviderVersion[];
+}
+
+function moduleMetadata(value: unknown): ModuleMetadata | null {
+	if (typeof value !== "object" || value === null) return null;
+	const item = value as Record<string, unknown>;
+	for (const key of ["namespace", "name", "provider", "version"] as const) {
+		if (typeof item[key] !== "string" || item[key].length === 0) return null;
+	}
+	return item as unknown as ModuleMetadata;
+}
+
+function renderProvider(namespace: string, type: string, versions: readonly ProviderVersion[]): string {
+	const lines = [
+		`# Terraform provider: ${namespace}/${type}`,
+		"",
+		`Source: \`${namespace}/${type}\``,
+		`Available versions: ${versions.length}`,
+		"",
+		"| Version | Protocols | Platforms |",
+		"|---------|-----------|-----------|",
+	];
+	for (const entry of versions) {
+		const protocols = Array.isArray(entry.protocols) ? entry.protocols.join(", ") : "not advertised";
+		const platforms = Array.isArray(entry.platforms)
+			? entry.platforms
+					.filter(platform => typeof platform?.os === "string" && typeof platform?.arch === "string")
+					.map(platform => `${platform.os}/${platform.arch}`)
+					.join(", ")
+			: "not advertised";
+		lines.push(`| ${entry.version} | ${protocols || "not advertised"} | ${platforms || "not advertised"} |`);
+	}
+	return lines.join("\n");
+}
+
+function renderModule(metadata: ModuleMetadata): string {
+	const address = `${metadata.namespace}/${metadata.name}/${metadata.provider}`;
+	const lines = [
+		`# Terraform module: ${address}`,
+		"",
+		`Source: \`${address}\``,
+		`Latest version: ${metadata.version}`,
+		`Verified: ${metadata.verified === true ? "yes" : "no"}`,
+	];
+	if (metadata.description) lines.push(`Description: ${metadata.description}`);
+	if (metadata.source) lines.push(`Repository: ${metadata.source}`);
+	return lines.join("\n");
+}
+
+function failure(route: RegistryRoute, heading: string, detail: string): string {
+	const address =
+		route.kind === "provider"
+			? `${route.namespace}/${route.type}`
+			: `${route.namespace}/${route.name}/${route.provider}`;
+	return `# ${heading}\n\nRegistry address: \`${address}\`\n\n${detail}`;
+}
+
+function errorMessage(error: unknown): string {
+	return error instanceof Error ? error.message : String(error);
+}
+
+export class RegistryResolver {
+	readonly #deps: RegistryResolverDeps;
+
+	constructor(deps: RegistryResolverDeps) {
+		this.#deps = deps;
+	}
+
+	async resolve(url: InternalUrl): Promise<InternalResource> {
+		const route = parseRoute(url);
+		const address =
+			route.kind === "provider"
+				? `${route.namespace}/${route.type}/versions`
+				: `${route.namespace}/${route.name}/${route.provider}`;
+		const baseUrl = route.kind === "provider" ? this.#deps.providerBaseUrl : this.#deps.moduleBaseUrl;
+		const requestUrl = `${baseUrl.replace(/\/+$/, "")}/${address}`;
+
+		try {
+			const response = await this.#deps.fetch(requestUrl, {
+				headers: { Accept: "application/json" },
+				signal: AbortSignal.timeout(this.#deps.timeoutMs),
+			});
+			if (response.status === 404) {
+				const kind = route.kind === "provider" ? "Provider" : "Module";
+				return markdownResource(
+					url,
+					failure(
+						route,
+						`${kind} not found`,
+						`Verify the namespace and ${route.kind === "provider" ? "type" : "name/provider"}, then retry the exact lookup.`,
+					),
+				);
+			}
+			if (!response.ok) {
+				return markdownResource(
+					url,
+					failure(
+						route,
+						"Terraform Registry request failed",
+						`The Registry returned HTTP ${response.status}. Try the lookup again; if it persists, verify Registry availability.`,
+					),
+				);
+			}
+
+			let data: unknown;
+			try {
+				data = await response.json();
+			} catch {
+				return markdownResource(
+					url,
+					failure(
+						route,
+						"Terraform Registry invalid response",
+						"The Registry did not return valid JSON. No version or metadata was inferred.",
+					),
+				);
+			}
+
+			if (route.kind === "provider") {
+				const versions = providerVersions(data);
+				if (!versions) {
+					return markdownResource(
+						url,
+						failure(
+							route,
+							"Terraform Registry invalid response",
+							"The provider response did not contain documented version entries. No version was inferred.",
+						),
+					);
+				}
+				return markdownResource(url, renderProvider(route.namespace, route.type, versions));
+			}
+
+			const metadata = moduleMetadata(data);
+			if (!metadata) {
+				return markdownResource(
+					url,
+					failure(
+						route,
+						"Terraform Registry invalid response",
+						"The module response omitted required metadata. No module arguments were inferred.",
+					),
+				);
+			}
+			return markdownResource(url, renderModule(metadata));
+		} catch (error) {
+			const timedOut =
+				error instanceof DOMException && (error.name === "TimeoutError" || error.name === "AbortError");
+			return markdownResource(
+				url,
+				failure(
+					route,
+					timedOut ? "Terraform Registry request timed out" : "Terraform Registry request failed",
+					timedOut
+						? `The lookup timed out after ${this.#deps.timeoutMs} ms. Try the lookup again or verify network access to the Registry.`
+						: `Network error: ${errorMessage(error)}. Verify connectivity to the Registry and retry the exact lookup.`,
+				),
+			);
+		}
+	}
+}
+
+export function createRegistryResolver(deps: Partial<RegistryResolverDeps> = {}): RegistryResolver {
+	return new RegistryResolver({
+		fetch: deps.fetch ?? globalThis.fetch,
+		providerBaseUrl: deps.providerBaseUrl ?? DEFAULT_PROVIDER_BASE_URL,
+		moduleBaseUrl: deps.moduleBaseUrl ?? DEFAULT_MODULE_BASE_URL,
+		timeoutMs: deps.timeoutMs ?? DEFAULT_TIMEOUT_MS,
+	});
+}

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

@@ -46,6 +46,7 @@ import { EMBEDDED_DOC_FILENAMES, EMBEDDED_DOCS } from "./docs-index.generated";
 import extensionApiContent from "./extension-api.md" with { type: "text" };
 import { createFleetResolver, type FleetDeps, type FleetResolver } from "./fleet-resolve";
 import { createPluginResolver, type GetPluginRoots, type PluginResolver } from "./plugin-resolve";
+import { createRegistryResolver, type RegistryResolver, type RegistryResolverDeps } from "./registry-resolve";
 import { createSourceResolver, type SourceResolver } from "./source-resolve";
 import { createTerraformResolver, type TerraformResolver } from "./terraform-resolve";
 import type { TerraformIndex } from "./terraform-types";
@@ -57,6 +58,7 @@ const API_SPEC_HOST = "api-spec";
 const API_CATALOG_HOST = "api-catalog";
 const BRANDING_HOST = "branding";
 const TERRAFORM_HOST = "terraform";
+const REGISTRY_HOST = "registry";
 const CONSOLE_HOST = "console";
 const EXTENSION_HOST = "extension";
 const PLUGIN_HOST = "plugin";
@@ -316,6 +318,8 @@ export interface InternalDocsProtocolOptions {
 	readonly getPluginRoots?: GetPluginRoots;
 	/** Injected so tests can classify without a git repo, a `gh` binary, or a network. */
 	readonly fleetDeps?: Partial<FleetDeps>;
+	/** Injected so Registry tests can use a protocol-faithful local server. */
+	readonly registryDeps?: Partial<RegistryResolverDeps>;
 }
 
 export class InternalDocsProtocolHandler implements ProtocolHandler {
@@ -327,12 +331,14 @@ export class InternalDocsProtocolHandler implements ProtocolHandler {
 	#apiSpecResolver: ApiSpecResolver | null;
 	#apiCatalogResolver: ApiCatalogResolver | null;
 	#terraformResolver: TerraformResolver | null;
+	#registryResolver: RegistryResolver | null = null;
 	#consoleResolver: ConsoleResolver | null = null;
 	#pluginResolver: PluginResolver | null = null;
 	#changesResolver: ChangesResolver | null = null;
 	#sourceResolver: SourceResolver | null = null;
 	#fleetResolver: FleetResolver | null = null;
 	readonly #fleetDeps: Partial<FleetDeps> | undefined;
+	readonly #registryDeps: Partial<RegistryResolverDeps> | undefined;
 	readonly #getPluginRoots: GetPluginRoots | undefined;
 
 	constructor(options: InternalDocsProtocolOptions = {}) {
@@ -345,6 +351,7 @@ export class InternalDocsProtocolHandler implements ProtocolHandler {
 		this.#terraformResolver = null;
 		this.#getPluginRoots = options.getPluginRoots;
 		this.#fleetDeps = options.fleetDeps;
+		this.#registryDeps = options.registryDeps;
 	}
 
 	#getApiSpecResolver(): ApiSpecResolver {
@@ -381,6 +388,11 @@ export class InternalDocsProtocolHandler implements ProtocolHandler {
 		return this.#terraformResolver;
 	}
 
+	#getRegistryResolver(): RegistryResolver {
+		if (!this.#registryResolver) this.#registryResolver = createRegistryResolver(this.#registryDeps);
+		return this.#registryResolver;
+	}
+
 	#getConsoleResolver(): ConsoleResolver {
 		if (!this.#consoleResolver) {
 			this.#consoleResolver = createConsoleResolver(loadConsoleCatalog(), loadConsoleFieldMetadata());
@@ -436,6 +448,10 @@ export class InternalDocsProtocolHandler implements ProtocolHandler {
 			return this.#getTerraformResolver().resolve(url);
 		}
 
+		if (host === REGISTRY_HOST) {
+			return this.#getRegistryResolver().resolve(url);
+		}
+
 		if (host === PLUGIN_HOST) {
 			return this.#getPluginResolver().resolve(url);
 		}
@@ -504,6 +520,7 @@ export class InternalDocsProtocolHandler implements ProtocolHandler {
 		const brandingEntry = `- [${BRANDING_HOST}](${SCHEME_PREFIX}${BRANDING_HOST}) — F5 XC branding and legacy name mapping (v${branding.version})`;
 		const tf = loadTerraformIndex();
 		const terraformEntry = `- [${TERRAFORM_HOST}/](${SCHEME_PREFIX}${TERRAFORM_HOST}/) — F5 XC Terraform provider (${Object.keys(tf.resources).length} resources, v${tf.version})`;
+		const registryEntry = `- [${REGISTRY_HOST}/provider/<namespace>/<type>](${SCHEME_PREFIX}${REGISTRY_HOST}/provider/hashicorp/random) — live Terraform provider and module Registry metadata`;
 		const entries = [
 			syntheticEntry,
 			changesEntry,
@@ -513,6 +530,7 @@ export class InternalDocsProtocolHandler implements ProtocolHandler {
 			apiCatalogEntry,
 			brandingEntry,
 			terraformEntry,
+			registryEntry,
 			...EMBEDDED_DOC_FILENAMES.map(f => `- [${f}](${SCHEME_PREFIX}${f})`),
 		];
 		// Derived, not hand-maintained: the advertised count used to be a magic

package/src/modes/components/vllm-model-selector.ts

@@ -0,0 +1,38 @@
+import { Container, type SelectItem, SelectList, Spacer, Text } from "@f5-sales-demo/pi-tui";
+import type { LoginModelChoice } from "../controllers/login-model";
+import { getSelectListTheme } from "../theme/theme";
+import { DynamicBorder } from "./dynamic-border";
+
+export class VllmModelSelectorComponent extends Container {
+	#selectList: SelectList;
+
+	constructor(
+		choices: readonly LoginModelChoice[],
+		onSelect: (choice: LoginModelChoice) => void,
+		onCancel: () => void,
+	) {
+		super();
+		const items: SelectItem[] = choices.map(choice => ({
+			value: choice.modelId,
+			label: choice.label,
+			description: choice.description,
+		}));
+		this.addChild(new DynamicBorder());
+		this.addChild(new Spacer(1));
+		this.addChild(new Text("Select your default vLLM model:", 1, 0));
+		this.addChild(new Spacer(1));
+		this.#selectList = new SelectList(items, items.length, getSelectListTheme());
+		this.#selectList.onSelect = item => {
+			const choice = choices.find(candidate => candidate.modelId === item.value);
+			if (choice) onSelect(choice);
+		};
+		this.#selectList.onCancel = onCancel;
+		this.addChild(this.#selectList);
+		this.addChild(new Spacer(1));
+		this.addChild(new DynamicBorder());
+	}
+
+	getSelectList(): SelectList {
+		return this.#selectList;
+	}
+}

package/src/modes/controllers/login-model.ts

@@ -1,5 +1,6 @@
 import { ThinkingLevel } from "@f5-sales-demo/pi-agent-core";
 import { canonicalizeOAuthProviderId, type Model } from "@f5-sales-demo/pi-ai";
+import type { VllmDiscoveredModel } from "../../config/vllm-config";
 import { applySubscriptionProfileRoles, type SubscriptionProfileId } from "../../routing/subscription-profiles";
 
 export interface LoginModelChoice {
@@ -53,6 +54,19 @@ export function getAvailableLiteLLMLoginModelChoices(availableModelIds: readonly
 	return LITELLM_LOGIN_MODEL_CHOICES.filter(choice => available.has(choice.modelId));
 }
 
+export function getVllmLoginModelChoices(models: readonly VllmDiscoveredModel[]): LoginModelChoice[] {
+	return models.map(model => ({
+		label: model.id,
+		description:
+			model.contextWindow === undefined
+				? "Context limit not advertised; using compatibility defaults"
+				: `${model.contextWindow.toLocaleString("en-US")} token context`,
+		provider: "vllm",
+		modelId: model.id,
+		thinkingLevel: ThinkingLevel.Off,
+	}));
+}
+
 /**
  * Minimal session surface needed to apply a model after a successful login.
  * Kept structural so the login flow can call it without pulling in the full

package/src/modes/controllers/selector-controller.ts

@@ -16,6 +16,12 @@ import { probeLiteLLMConnection, readLiteLLMConfig } from "../../config/auto-con
 import { getRoleInfo } from "../../config/model-registry";
 import { formatModelSelectorValue } from "../../config/model-resolver";
 import { settings } from "../../config/settings";
+import {
+	DEFAULT_VLLM_BASE_URL,
+	normalizeVllmBaseUrl,
+	probeVllmConnection,
+	readVllmConfig,
+} from "../../config/vllm-config";
 import { DebugSelectorComponent } from "../../debug";
 import { disableProvider, enableProvider } from "../../discovery";
 import { clearXcshPluginRootsCache, resolveActiveProjectRegistryPath } from "../../discovery/helpers";
@@ -59,6 +65,7 @@ import { getPreset } from "../components/status-line/presets";
 import { ToolExecutionComponent } from "../components/tool-execution";
 import { TreeSelectorComponent } from "../components/tree-selector";
 import { UserMessageSelectorComponent } from "../components/user-message-selector";
+import { VllmModelSelectorComponent } from "../components/vllm-model-selector";
 import type { SessionObserverRegistry } from "../session-observer-registry";
 import { runEnterpriseOAuthLoginFlow } from "./enterprise-oauth-login-flow";
 import {
@@ -72,7 +79,10 @@ import {
 	GOOGLE_ANTIGRAVITY_LOGIN_MODEL_CHOICE,
 	LITELLM_LOGIN_MODEL_CHOICES,
 	type LiteLLMLoginModelChoice,
+	type LoginModelChoice,
 } from "./login-model";
+import { runVllmLoginFlow } from "./vllm-login-flow";
+import { commitVllmLogin } from "./vllm-login-transaction";
 
 const CALLBACK_SERVER_PROVIDERS = new Set<OAuthProvider>([
 	"anthropic",
@@ -529,6 +539,57 @@ export class SelectorController {
 		return promise;
 	}
 
+	async #showVllmLoginModelSelector(choices: readonly LoginModelChoice[]): Promise<LoginModelChoice | null> {
+		const { promise, resolve } = Promise.withResolvers<LoginModelChoice | null>();
+		this.showSelector(done => {
+			const selector = new VllmModelSelectorComponent(
+				choices,
+				choice => {
+					done();
+					resolve(choice);
+					this.ctx.ui.requestRender();
+				},
+				() => {
+					done();
+					resolve(null);
+					this.ctx.ui.requestRender();
+				},
+			);
+			return { component: selector, focus: selector.getSelectList() };
+		});
+		return promise;
+	}
+
+	async #promptLoginValue(prompt: OAuthPrompt): Promise<string> {
+		this.ctx.chatContainer.addChild(new Spacer(1));
+		this.ctx.chatContainer.addChild(new Text(theme.fg("text", prompt.message), 1, 0));
+		if (prompt.placeholder) {
+			this.ctx.chatContainer.addChild(new Text(theme.fg("dim", prompt.placeholder), 1, 0));
+		}
+		this.ctx.ui.requestRender();
+		const { promise, resolve, reject } = Promise.withResolvers<string>();
+		const input = createLoginPromptInput(prompt);
+		const closeInput = () => {
+			this.ctx.editorContainer.clear();
+			this.ctx.editorContainer.addChild(this.ctx.editor);
+			this.ctx.ui.setFocus(this.ctx.editor);
+		};
+		input.onSubmit = () => {
+			const value = input.getValue();
+			closeInput();
+			resolve(value);
+		};
+		input.onEscape = () => {
+			closeInput();
+			reject(new LoginPromptCancelled());
+		};
+		this.ctx.editorContainer.clear();
+		this.ctx.editorContainer.addChild(input);
+		this.ctx.ui.setFocus(input);
+		this.ctx.ui.requestRender();
+		return promise;
+	}
+
 	async #showLoginRecovery(
 		request: LoginRecoveryRequest | { stage: string; error: string; canEdit: boolean },
 		flowLabel = "LiteLLM",
@@ -1057,6 +1118,97 @@ export class SelectorController {
 		}
 	}
 
+	async #handleVllmLogin(): Promise<void> {
+		this.ctx.showStatus("Configuring vLLM…");
+		const modelsPath = path.join(getAgentDir(), "models.yml");
+
+		try {
+			let defaultBaseUrl = readVllmConfig(modelsPath)?.baseUrl ?? DEFAULT_VLLM_BASE_URL;
+			const storedCredential = this.ctx.session.modelRegistry.authStorage.get("vllm");
+			const hadStoredKey = storedCredential?.type === "api_key" && storedCredential.key.length > 0;
+			const flowResult = await runVllmLoginFlow({
+				collectCredentials: async () => {
+					try {
+						let baseUrl: string;
+						while (true) {
+							const value = await this.#promptLoginValue({
+								message: `vLLM Base URL [${defaultBaseUrl}]`,
+								placeholder: DEFAULT_VLLM_BASE_URL,
+								allowEmpty: true,
+							});
+							try {
+								baseUrl = normalizeVllmBaseUrl(value.trim() || defaultBaseUrl);
+								break;
+							} catch (error) {
+								this.ctx.showError(error instanceof Error ? error.message : String(error));
+							}
+						}
+						const apiKey = await this.#promptLoginValue({
+							message: hadStoredKey
+								? "Optional vLLM API key [stored securely; leave blank to remove authentication]"
+								: "Optional vLLM API key [leave blank for keyless local service]",
+							allowEmpty: true,
+							secret: true,
+						});
+						defaultBaseUrl = baseUrl;
+						return { baseUrl, apiKey };
+					} catch (error) {
+						if (error instanceof LoginPromptCancelled) return null;
+						throw error;
+					}
+				},
+				probe: async credentials => {
+					this.ctx.chatContainer.addChild(new Spacer(1));
+					this.ctx.chatContainer.addChild(
+						new Text(theme.fg("dim", `Connecting to ${credentials.baseUrl}/models…`), 1, 0),
+					);
+					this.ctx.ui.requestRender();
+					const probe = await probeVllmConnection(credentials.baseUrl, credentials.apiKey);
+					this.ctx.chatContainer.addChild(
+						new Text(
+							theme.fg("success", `${theme.status.success} OK — ${probe.models.length} vLLM models available`),
+							1,
+							0,
+						),
+					);
+					this.ctx.ui.requestRender();
+					return probe;
+				},
+				selectModel: choices => this.#showVllmLoginModelSelector(choices),
+				commit: input =>
+					commitVllmLogin({
+						modelsPath,
+						credentials: input.credentials,
+						choice: input.choice,
+						session: this.ctx.session,
+					}),
+				recover: request => this.#showLoginRecovery(request, "vLLM"),
+			});
+
+			if (flowResult.status === "cancelled") {
+				this.ctx.showStatus("vLLM login cancelled. Existing configuration unchanged.");
+				return;
+			}
+			this.ctx.statusLine.invalidate();
+			this.ctx.updateEditorBorderColor();
+			this.ctx.chatContainer.addChild(new Spacer(1));
+			this.ctx.chatContainer.addChild(
+				new Text(theme.fg("success", `${theme.status.success} vLLM configuration saved to ${modelsPath}`), 1, 0),
+			);
+			this.ctx.chatContainer.addChild(
+				new Text(theme.fg("success", `Default model: vllm/${flowResult.choice.modelId} (thinking off)`), 1, 0),
+			);
+			if (this.ctx.session.modelRegistry.authStorage.get("vllm")) {
+				this.ctx.chatContainer.addChild(
+					new Text(theme.fg("dim", `API key saved only to ${getAgentDbPath()}`), 1, 0),
+				);
+			}
+			this.ctx.ui.requestRender();
+		} catch (error) {
+			this.ctx.showError(`vLLM login failed: ${error instanceof Error ? error.message : String(error)}`);
+		}
+	}
+
 	async #handleOAuthLogin(providerId: string): Promise<void> {
 		if (providerId === "openai") {
 			this.#showOpenAIApiKeyGuidance();
@@ -1066,6 +1218,9 @@ export class SelectorController {
 		if (providerId === "litellm") {
 			return this.#handleLiteLLMLogin();
 		}
+		if (providerId === "vllm") {
+			return this.#handleVllmLogin();
+		}
 
 		this.ctx.showStatus(`Logging in to ${providerId}…`);
 		const manualInput = this.ctx.oauthManualInput;

package/src/modes/controllers/vllm-login-flow.ts

@@ -0,0 +1,87 @@
+import type { VllmProbeResult } from "../../config/vllm-config";
+import { getVllmLoginModelChoices, type LoginModelChoice } from "./login-model";
+
+export interface VllmLoginCredentials {
+	baseUrl: string;
+	apiKey: string;
+}
+
+export type LoginRecoveryAction = "retry" | "edit" | "cancel";
+export type VllmLoginStage = "probe" | "commit";
+
+export interface VllmLoginRecoveryRequest {
+	stage: VllmLoginStage;
+	error: string;
+	canEdit: boolean;
+}
+
+export interface VllmLoginCommit {
+	credentials: VllmLoginCredentials;
+	probe: VllmProbeResult;
+	choice: LoginModelChoice;
+}
+
+export type VllmLoginFlowResult = { status: "completed"; choice: LoginModelChoice } | { status: "cancelled" };
+
+interface VllmLoginFlowOptions {
+	collectCredentials(): Promise<VllmLoginCredentials | null>;
+	probe(credentials: VllmLoginCredentials): Promise<VllmProbeResult>;
+	selectModel(choices: readonly LoginModelChoice[]): Promise<LoginModelChoice | null>;
+	commit(input: VllmLoginCommit): Promise<void>;
+	recover(request: VllmLoginRecoveryRequest): Promise<LoginRecoveryAction>;
+	sleep?(milliseconds: number): Promise<void>;
+	maxAutomaticRetries?: number;
+}
+
+function errorMessage(error: unknown): string {
+	return error instanceof Error ? error.message : String(error);
+}
+
+function isAuthenticationError(message: string): boolean {
+	return /\b(401|403|Unauthorized|Forbidden|API key)\b/i.test(message);
+}
+
+export async function runVllmLoginFlow(options: VllmLoginFlowOptions): Promise<VllmLoginFlowResult> {
+	const sleep = options.sleep ?? Bun.sleep;
+	const maxAutomaticRetries = options.maxAutomaticRetries ?? 2;
+
+	credentialsLoop: while (true) {
+		const credentials = await options.collectCredentials();
+		if (!credentials) return { status: "cancelled" };
+
+		let probe: VllmProbeResult;
+		let automaticRetries = 0;
+		while (true) {
+			try {
+				probe = await options.probe(credentials);
+				break;
+			} catch (error) {
+				const message = errorMessage(error);
+				if (!isAuthenticationError(message) && automaticRetries < maxAutomaticRetries) {
+					await sleep(250 * 2 ** automaticRetries);
+					automaticRetries += 1;
+					continue;
+				}
+				const action = await options.recover({ stage: "probe", error: message, canEdit: true });
+				if (action === "cancel") return { status: "cancelled" };
+				if (action === "edit") continue credentialsLoop;
+				automaticRetries = 0;
+			}
+		}
+
+		const choices = getVllmLoginModelChoices(probe.models);
+		const choice = choices.length === 1 ? choices[0] : await options.selectModel(choices);
+		if (!choice) return { status: "cancelled" };
+
+		while (true) {
+			try {
+				await options.commit({ credentials, probe, choice });
+				return { status: "completed", choice };
+			} catch (error) {
+				const action = await options.recover({ stage: "commit", error: errorMessage(error), canEdit: true });
+				if (action === "cancel") return { status: "cancelled" };
+				if (action === "edit") continue credentialsLoop;
+			}
+		}
+	}
+}

package/src/modes/controllers/vllm-login-transaction.ts

@@ -0,0 +1,148 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import type { ThinkingLevel } from "@f5-sales-demo/pi-agent-core";
+import type { AuthCredential, Model } from "@f5-sales-demo/pi-ai";
+import { writeVllmModelsConfig } from "../../config/vllm-config";
+import { applyModelAfterLogin, type LoginModelChoice } from "./login-model";
+import type { VllmLoginCredentials } from "./vllm-login-flow";
+
+interface VllmTransactionSession {
+	model?: Model;
+	thinkingLevel?: ThinkingLevel;
+	modelRegistry: {
+		authStorage: {
+			get(provider: string): AuthCredential | undefined;
+			set(provider: string, credential: AuthCredential): Promise<void>;
+			remove(provider: string): Promise<void>;
+		};
+		refreshProvider(providerId: string, strategy: "online"): Promise<void>;
+		getAll(): Model[];
+	};
+	setModel(model: Model, role: "default", options: { selector: string; thinkingLevel: ThinkingLevel }): Promise<void>;
+	setModelTemporary?(model: Model, thinkingLevel?: ThinkingLevel): Promise<void>;
+	setThinkingLevel(level: ThinkingLevel): void;
+	settings: {
+		getModelRoles(): Readonly<Record<string, string | undefined>>;
+		set(key: "modelRoles", value: Record<string, string>): void;
+	};
+}
+
+interface CommitVllmLoginOptions {
+	modelsPath: string;
+	credentials: VllmLoginCredentials;
+	choice: LoginModelChoice;
+	session: VllmTransactionSession;
+}
+
+interface FileSnapshot {
+	existed: boolean;
+	content?: Buffer;
+	mode?: number;
+}
+
+interface DirectorySnapshot {
+	existed: boolean;
+	mode?: number;
+}
+
+function captureFile(filePath: string): FileSnapshot {
+	try {
+		const stat = fs.statSync(filePath);
+		return { existed: true, content: fs.readFileSync(filePath), mode: stat.mode & 0o777 };
+	} catch (error) {
+		if ((error as NodeJS.ErrnoException).code === "ENOENT") return { existed: false };
+		throw error;
+	}
+}
+
+async function restoreFile(filePath: string, snapshot: FileSnapshot): Promise<void> {
+	if (!snapshot.existed) {
+		await fs.promises.rm(filePath, { force: true });
+		return;
+	}
+	if (!snapshot.content) throw new Error(`Missing rollback content for ${filePath}`);
+	await fs.promises.mkdir(path.dirname(filePath), { recursive: true });
+	await fs.promises.writeFile(filePath, snapshot.content, { mode: snapshot.mode });
+	if (snapshot.mode !== undefined) await fs.promises.chmod(filePath, snapshot.mode);
+}
+
+function captureDirectory(directory: string): DirectorySnapshot {
+	try {
+		return { existed: true, mode: fs.statSync(directory).mode & 0o777 };
+	} catch (error) {
+		if ((error as NodeJS.ErrnoException).code === "ENOENT") return { existed: false };
+		throw error;
+	}
+}
+
+async function restoreDirectory(directory: string, snapshot: DirectorySnapshot): Promise<void> {
+	if (snapshot.existed) {
+		if (snapshot.mode !== undefined) await fs.promises.chmod(directory, snapshot.mode);
+		return;
+	}
+	await fs.promises.rmdir(directory).catch(error => {
+		if ((error as NodeJS.ErrnoException).code !== "ENOENT" && (error as NodeJS.ErrnoException).code !== "ENOTEMPTY") {
+			throw error;
+		}
+	});
+}
+
+export async function commitVllmLogin(options: CommitVllmLoginOptions): Promise<void> {
+	const { modelsPath, credentials, choice, session } = options;
+	const modelsSnapshot = captureFile(modelsPath);
+	const directory = path.dirname(modelsPath);
+	const directorySnapshot = captureDirectory(directory);
+	const previousCredential = session.modelRegistry.authStorage.get("vllm");
+	const previousModel = session.model;
+	const previousThinkingLevel = session.thinkingLevel;
+	const previousModelRoles = Object.fromEntries(
+		Object.entries(session.settings.getModelRoles()).filter(
+			(entry): entry is [string, string] => entry[1] !== undefined,
+		),
+	);
+	const apiKey = credentials.apiKey.trim();
+
+	try {
+		await writeVllmModelsConfig(modelsPath, credentials.baseUrl, { authenticated: apiKey.length > 0 });
+		if (apiKey) await session.modelRegistry.authStorage.set("vllm", { type: "api_key", key: apiKey });
+		else await session.modelRegistry.authStorage.remove("vllm");
+
+		await session.modelRegistry.refreshProvider("vllm", "online");
+		const applied = await applyModelAfterLogin(session, choice);
+		if (!applied) throw new Error(`Model unavailable after refresh: ${choice.provider}/${choice.modelId}`);
+	} catch (error) {
+		const rollbackErrors: unknown[] = [];
+		try {
+			await restoreFile(modelsPath, modelsSnapshot);
+			await restoreDirectory(directory, directorySnapshot);
+		} catch (rollbackError) {
+			rollbackErrors.push(rollbackError);
+		}
+		try {
+			if (previousCredential) await session.modelRegistry.authStorage.set("vllm", previousCredential);
+			else await session.modelRegistry.authStorage.remove("vllm");
+		} catch (rollbackError) {
+			rollbackErrors.push(rollbackError);
+		}
+		try {
+			session.settings.set("modelRoles", previousModelRoles);
+		} catch (rollbackError) {
+			rollbackErrors.push(rollbackError);
+		}
+		try {
+			await session.modelRegistry.refreshProvider("vllm", "online");
+			if (previousModel && session.setModelTemporary) {
+				await session.setModelTemporary(previousModel, previousThinkingLevel);
+			} else if (previousThinkingLevel !== undefined) {
+				session.setThinkingLevel(previousThinkingLevel);
+			}
+		} catch (rollbackError) {
+			rollbackErrors.push(rollbackError);
+		}
+
+		if (rollbackErrors.length > 0) {
+			throw new AggregateError([error, ...rollbackErrors], "vLLM login failed and rollback was incomplete");
+		}
+		throw error;
+	}
+}

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

@@ -41,8 +41,15 @@ plugins listed below, not an assumed set.
 Writing code is something you can do, but shipping feature code is not your job. Which repository
 you are standing in decides how you contribute, and that is declared rather than guessed: read
 `xcsh://fleet`. In a repository classified **content** you author directly — documentation,
-Terraform, howtos, demo and traffic-generation scripts — through the governed path. In one
-classified **developer** your deliverable is a rigorously-verified issue plus the specification,
+Terraform, howtos, demo and traffic-generation scripts — through the governed path (Git SOPs).
+When the GitHub plugin is installed in a **content** repository, you operate with the professional mastery of a skilled DevOps engineer:
+1. **Comprehensive Issue First**: Always create a detailed GitHub issue before developing content or making edits.
+2. **Feature Branch / Worktree**: Create a dedicated feature branch (`feature/<issue>-desc`) or worktree from `origin/main`. Never commit directly to `main`.
+3. **PR with Issue Link**: Stage specific files, run pre-commit lint gate, commit, push, and open a PR referencing `Closes #N`.
+4. **CI & Merge**: Poll CI until green using rate-limit aware polling, then squash merge (`--squash --delete-branch`).
+5. **Post-Merge Hygiene & Teardown**: Clean up after yourself — delete local/remote feature branches, remove merged worktrees, and run `git fetch --prune`. Never leave merged branches or worktrees behind.
+
+In a repository classified **developer** your deliverable is a rigorously-verified issue plus the specification,
 review and documentation around it, and the implementation is delegated to a development
 environment (Claude Code / Codex). In one classified **scaffolding**, changes go through the
 governed path only. An unclassified repository is treated as **developer**. That document also
@@ -472,6 +479,12 @@ permitted only after exhausting the llms.txt hierarchy.
 
 **ACTIVATION GATE**: You **MUST NOT** generate Terraform HCL code or plans unless the user explicitly asks for "Terraform", "HCL", ".tf" files, or Terraform CLI commands. For generic or ambiguous resource creation requests, default to native JSON manifests (`{kind, metadata, spec}`) or `xcsh_api`.
 
+Before referencing an external Terraform provider or module, resolve its exact source metadata through
+`xcsh://registry/provider/<namespace>/<type>` or
+`xcsh://registry/module/<namespace>/<name>/<provider>`. Never guess a namespace, provider type, module provider, or version.
+Use the Registry response together with the configuration's compatibility requirements; do not mechanically
+label the newest published version as compatible.
+
 HARD OVERRIDE — F5 Distributed Cloud Terraform Provider:
 - NEVER reference, recommend, or generate Terraform code using:
   - provider: volterraedge/volterra