@f5xc-salesdemos/xcsh 18.5.5 → 18.7.0

package/package.json

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

package/src/config/settings-schema.ts

@@ -263,6 +263,18 @@ export const SETTINGS_SCHEMA = {
 		},
 	},
 
+	"theme.forceSlot": {
+		type: "enum",
+		values: ["auto", "dark", "light"] as const,
+		default: "auto",
+		ui: {
+			tab: "appearance",
+			label: "Force Theme Slot",
+			description: "Override auto dark/light detection (useful inside tmux where OSC 11 is unreliable)",
+			submenu: true,
+		},
+	},
+
 	symbolPreset: {
 		type: "enum",
 		values: ["unicode", "nerd", "ascii"] as const,

package/src/config/settings.ts

@@ -26,7 +26,13 @@ import { YAML } from "bun";
 import { type Settings as SettingsCapabilityItem, settingsCapability } from "../capability/settings";
 import type { ModelRole } from "../config/model-registry";
 import { loadCapability } from "../discovery";
-import { isLightTheme, setAutoThemeMapping, setColorBlindMode, setSymbolPreset } from "../modes/theme/theme";
+import {
+	isLightTheme,
+	setAutoThemeMapping,
+	setColorBlindMode,
+	setForceSlot,
+	setSymbolPreset,
+} from "../modes/theme/theme";
 import { AgentStorage } from "../session/agent-storage";
 import { type EditMode, normalizeEditMode } from "../utils/edit-mode";
 import { withFileLock } from "./file-lock";
@@ -649,6 +655,11 @@ const SETTING_HOOKS: Partial<Record<SettingPath, SettingHook<any>>> = {
 			setAutoThemeMapping("light", value);
 		}
 	},
+	"theme.forceSlot": value => {
+		if (value === "auto" || value === "dark" || value === "light") {
+			setForceSlot(value);
+		}
+	},
 	symbolPreset: value => {
 		if (typeof value === "string" && (value === "unicode" || value === "nerd" || value === "ascii")) {
 			setSymbolPreset(value).catch(err => {

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

@@ -110,6 +110,16 @@ export function renderAboutDoc(info: RuntimeBuildInfo): string {
 		`- This commit on GitHub: ${info.commitUrl}`,
 		`- Release for this version: ${info.releaseUrl}`,
 		"",
+		"## Product knowledge",
+		"",
+		"xcsh serves F5 Distributed Cloud sales engineers. Product documentation is",
+		"federated across the f5xc-salesdemos GitHub organization. Entry point:",
+		"https://f5xc-salesdemos.github.io/docs/llms.txt",
+		"",
+		"Each product repo publishes: llms.txt (index with sidebar nav), custom sets",
+		"at /_llms-txt/{topic}.txt, per-page content at /{slug}.md, plus",
+		"llms-small.txt (compact) and llms-full.txt (complete).",
+		"",
 		"## What to do when asked about xcsh itself",
 		"",
 		"1. Confirm the user is running the version above. If unsure, ask them to run `xcsh --version`.",

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

@@ -17,17 +17,17 @@ export interface BuildInfo {
 }
 
 export const BUILD_INFO: BuildInfo = {
-	"version": "18.5.5",
-	"commit": "8a2e95fbb3e190549a9381ebd927013366f02fb6",
-	"shortCommit": "8a2e95f",
+	"version": "18.7.0",
+	"commit": "134e551dc4f0c8c481931d64c92d6c2f704aad9e",
+	"shortCommit": "134e551",
 	"branch": "main",
-	"tag": "v18.5.5",
-	"commitDate": "2026-04-22T05:35:04Z",
-	"buildDate": "2026-04-22T05:57:25.741Z",
+	"tag": "v18.7.0",
+	"commitDate": "2026-04-22T03:10:13-04:00",
+	"buildDate": "2026-04-22T07:28:38.519Z",
 	"dirty": false,
 	"prNumber": "",
 	"repoUrl": "https://github.com/f5xc-salesdemos/xcsh",
 	"repoSlug": "f5xc-salesdemos/xcsh",
-	"commitUrl": "https://github.com/f5xc-salesdemos/xcsh/commit/8a2e95fbb3e190549a9381ebd927013366f02fb6",
-	"releaseUrl": "https://github.com/f5xc-salesdemos/xcsh/releases/tag/v18.5.5"
+	"commitUrl": "https://github.com/f5xc-salesdemos/xcsh/commit/134e551dc4f0c8c481931d64c92d6c2f704aad9e",
+	"releaseUrl": "https://github.com/f5xc-salesdemos/xcsh/releases/tag/v18.7.0"
 };

package/src/main.ts

@@ -704,6 +704,7 @@ export async function runRootCommand(parsed: Args, rawArgs: string[]): Promise<v
 		settings.get("colorBlindMode"),
 		settings.get("theme.dark"),
 		settings.get("theme.light"),
+		settings.get("theme.forceSlot"),
 	);
 
 	let scopedModels: ScopedModel[] = [];

package/src/modes/components/welcome-checks.ts

@@ -1,9 +1,44 @@
 import type { Model } from "@f5xc-salesdemos/pi-ai";
 import { validateApiKeyAgainstModelsEndpoint } from "@f5xc-salesdemos/pi-ai/utils/oauth/api-key-validation";
 import { logger } from "@f5xc-salesdemos/pi-utils";
-import { ProfileService } from "../../services/f5xc-profile";
+import { type AuthStatus, ProfileService } from "../../services/f5xc-profile";
 import type { AuthStorage } from "../../session/auth-storage";
 
+// Startup validation budget. These are longer than validateToken's 3000ms default because
+// the welcome path runs during TLS/DNS cold-start — a single 3s shot races against warm-up
+// and falsely reports offline for profiles that reconnect cleanly moments later.
+const STARTUP_FIRST_TIMEOUT_MS = 4000;
+const STARTUP_RETRY_TIMEOUT_MS = 5000;
+const STARTUP_RETRY_DELAY_MS = 500;
+
+type ProfileValidator = (opts: { timeoutMs: number }) => Promise<{ status: AuthStatus; latencyMs?: number }>;
+
+/**
+ * Runs the profile validator once with a startup-sized timeout; if the result is `offline`
+ * (the only transient class — auth_error/connected/unknown are definitive), waits briefly
+ * to let DNS/TLS warm up, then tries once more with a longer timeout.
+ */
+export async function validateProfileWithStartupRetry(
+	validate: ProfileValidator,
+	options?: {
+		firstTimeoutMs?: number;
+		retryTimeoutMs?: number;
+		retryDelayMs?: number;
+	},
+): Promise<{ status: AuthStatus; latencyMs?: number }> {
+	const firstTimeoutMs = options?.firstTimeoutMs ?? STARTUP_FIRST_TIMEOUT_MS;
+	const retryTimeoutMs = options?.retryTimeoutMs ?? STARTUP_RETRY_TIMEOUT_MS;
+	const retryDelayMs = options?.retryDelayMs ?? STARTUP_RETRY_DELAY_MS;
+
+	const first = await validate({ timeoutMs: firstTimeoutMs });
+	if (first.status !== "offline") return first;
+
+	if (retryDelayMs > 0) {
+		await new Promise(resolve => setTimeout(resolve, retryDelayMs));
+	}
+	return await validate({ timeoutMs: retryTimeoutMs });
+}
+
 export type ModelCheckState = "no_provider" | "connected" | "auth_error";
 
 export interface ModelStatus {
@@ -117,7 +152,7 @@ async function checkProfileStatus(): Promise<WelcomeProfileStatus> {
 		}
 
 		const name = status.activeProfileName ?? "default";
-		const result = await profileService.validateToken();
+		const result = await validateProfileWithStartupRetry(opts => profileService.validateToken(opts));
 
 		switch (result.status) {
 			case "connected":

package/src/modes/components/welcome.ts

@@ -1,6 +1,7 @@
 import { type Component, padding, truncateToWidth, visibleWidth } from "@f5xc-salesdemos/pi-tui";
 import { APP_NAME } from "@f5xc-salesdemos/pi-utils";
 import { theme } from "../../modes/theme/theme";
+import { formatStatusIcon } from "../../services/f5xc-profile-indicators";
 import type { ModelStatus, WelcomeProfileStatus } from "./welcome-checks";
 
 export interface UpdateStatus {
@@ -200,15 +201,17 @@ export class WelcomeComponent implements Component {
 		const p = provider ?? "unknown";
 		switch (state) {
 			case "connected":
-				return [` ✅ ${theme.fg("muted", p)} ${theme.fg("dim", `\u2014 connected (${latencyMs ?? "?"}ms)`)}`];
+				return [
+					` ${formatStatusIcon("connected")} ${theme.fg("muted", p)} ${theme.fg("dim", `\u2014 connected (${latencyMs ?? "?"}ms)`)}`,
+				];
 			case "auth_error":
 				return [
-					` ❌ ${theme.fg("muted", p)} ${theme.fg("error", "\u2014 connection failed")}`,
+					` ${formatStatusIcon("error")} ${theme.fg("muted", p)} ${theme.fg("error", "\u2014 connection failed")}`,
 					`   ${theme.fg("dim", "Run /login to reconnect")}`,
 				];
 			case "no_provider":
 				return [
-					` ❌ ${theme.fg("error", "No model provider configured")}`,
+					` ${formatStatusIcon("error")} ${theme.fg("error", "No model provider configured")}`,
 					`   ${theme.fg("dim", "Run /login to connect")}`,
 				];
 		}
@@ -220,20 +223,22 @@ export class WelcomeComponent implements Component {
 		const n = name ?? "default";
 		switch (state) {
 			case "connected":
-				return [` ✅ ${theme.fg("muted", n)} ${theme.fg("dim", `\u2014 connected (${latencyMs ?? "?"}ms)`)}`];
+				return [
+					` ${formatStatusIcon("connected")} ${theme.fg("muted", n)} ${theme.fg("dim", `\u2014 connected (${latencyMs ?? "?"}ms)`)}`,
+				];
 			case "auth_error":
 				return [
-					` ❌ ${theme.fg("muted", n)} ${theme.fg("error", "\u2014 token invalid")}`,
+					` ${formatStatusIcon("error")} ${theme.fg("muted", n)} ${theme.fg("error", "\u2014 token invalid")}`,
 					`   ${theme.fg("dim", "Run /profile to update")}`,
 				];
 			case "offline":
 				return [
-					` ⚠️ ${theme.fg("muted", n)} ${theme.fg("warning", "\u2014 unreachable")}`,
+					` ${formatStatusIcon("warning")} ${theme.fg("muted", n)} ${theme.fg("warning", "\u2014 unreachable")}`,
 					`   ${theme.fg("dim", "Check network, /profile")}`,
 				];
 			case "no_profile":
 				return [
-					` ⚠️ ${theme.fg("warning", "No profile configured")}`,
+					` ${formatStatusIcon("warning")} ${theme.fg("warning", "No profile configured")}`,
 					`   ${theme.fg("dim", "Run /profile create <name> <url> <token>")}`,
 				];
 		}

package/src/modes/theme/defaults/xcsh-dark.json

@@ -105,7 +105,7 @@
 		"statusLineContextPctWarningBg": 22,
 		"statusLineContextPctPurpleBg": 94,
 		"statusLineContextPctErrorBg": 88,
-		"statusLineProfileF5xcBg": 52,
+		"statusLineProfileF5xcBg": "f5Red",
 		"statusLineProfileF5xcFg": 231,
 		"pythonMode": "#f0c040",
 		"syntaxControl": "#569CD6"

package/src/modes/theme/defaults/xcsh-light.json

@@ -107,7 +107,7 @@
 		"statusLineContextPctWarningBg": 22,
 		"statusLineContextPctPurpleBg": 94,
 		"statusLineContextPctErrorBg": 88,
-		"statusLineProfileF5xcBg": 52,
+		"statusLineProfileF5xcBg": "f5Red",
 		"statusLineProfileF5xcFg": 231,
 		"pythonMode": "warningAmber",
 		"syntaxControl": "f5Red"

package/src/modes/theme/theme.ts

@@ -1894,9 +1894,33 @@ function detectTerminalBackground(): "dark" | "light" {
 	return "dark";
 }
 
+/**
+ * Theme-slot override mode. `"auto"` uses terminal-appearance detection to
+ * pick between the dark and light slots. `"dark"` / `"light"` skip detection
+ * and always load that slot — useful when running inside tmux where OSC 11
+ * queries and `COLORFGBG` don't reliably surface (see issue #228).
+ */
+export type ThemeForceSlot = "auto" | "dark" | "light";
+
+/**
+ * Pure slot-resolution helper. Exported so it can be unit-tested without a
+ * terminal. When `forceSlot` is `"dark"` or `"light"`, returns that slot's
+ * theme name unconditionally. Otherwise maps `detected` bg to the matching
+ * slot.
+ */
+export function resolveThemeSlot(
+	forceSlot: ThemeForceSlot,
+	detected: "dark" | "light",
+	darkTheme: string,
+	lightTheme: string,
+): string {
+	if (forceSlot === "dark") return darkTheme;
+	if (forceSlot === "light") return lightTheme;
+	return detected === "light" ? lightTheme : darkTheme;
+}
+
 function getDefaultTheme(): string {
-	const bg = detectTerminalBackground();
-	return bg === "light" ? autoLightTheme : autoDarkTheme;
+	return resolveThemeSlot(currentForceSlot, detectTerminalBackground(), autoDarkTheme, autoLightTheme);
 }
 
 // ============================================================================
@@ -1918,6 +1942,7 @@ var sigwinchHandler: (() => void) | undefined;
 var autoDetectedTheme: boolean = false;
 var autoDarkTheme: string = "xcsh-dark";
 var autoLightTheme: string = "xcsh-light";
+var currentForceSlot: ThemeForceSlot = "auto";
 var onThemeChangeCallback: (() => void) | undefined;
 var themeLoadRequestId: number = 0;
 
@@ -1934,10 +1959,12 @@ export async function initTheme(
 	colorBlindMode?: boolean,
 	darkTheme?: string,
 	lightTheme?: string,
+	forceSlot?: ThemeForceSlot,
 ): Promise<void> {
 	autoDetectedTheme = true;
 	autoDarkTheme = darkTheme ?? "xcsh-dark";
 	autoLightTheme = lightTheme ?? "xcsh-light";
+	currentForceSlot = forceSlot ?? "auto";
 	const name = getDefaultTheme();
 	currentThemeName = name;
 	currentSymbolPresetOverride = symbolPreset;
@@ -2032,6 +2059,19 @@ export function setAutoThemeMapping(mode: "dark" | "light", themeName: string):
 	reevaluateAutoTheme("setAutoThemeMapping");
 }
 
+/**
+ * Update the forced-slot override. Callers pass `"auto"` to restore the
+ * detection chain, or `"dark"` / `"light"` to skip detection entirely and
+ * always load that slot. Re-evaluates the active theme immediately.
+ *
+ * Primary use case: tmux sessions where OSC 11 and COLORFGBG don't surface
+ * a reliable bg signal (issue #228).
+ */
+export function setForceSlot(slot: ThemeForceSlot): void {
+	currentForceSlot = slot;
+	reevaluateAutoTheme("setForceSlot");
+}
+
 /**
  * Called when the terminal detects a dark/light appearance change.
  * The terminal layer queries OSC 11 (background color) and computes luminance;

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

@@ -189,6 +189,18 @@ Most tools resolve custom protocol URLs to internal resources (not web URLs):
 
 In `bash`, URIs auto-resolve to filesystem paths (e.g., `python skill://my-skill/scripts/init.py`).
 
+# Product knowledge
+
+For F5 Distributed Cloud product questions (capabilities, demos, APIs, configuration),
+you **MUST** start at the live knowledge index:
+
+`https://f5xc-salesdemos.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.
+
 # Skills
 
 Specialized knowledge packs loaded for this session. Relative paths in skill files resolve against the skill directory.

package/src/services/f5xc-profile-indicators.ts

@@ -0,0 +1,16 @@
+import { theme } from "../modes/theme/theme";
+
+export type StatusCategory = "connected" | "error" | "warning" | "unknown";
+
+export function formatStatusIcon(status: StatusCategory): string {
+	switch (status) {
+		case "connected":
+			return theme.fg("success", "●");
+		case "error":
+			return theme.fg("error", "○");
+		case "warning":
+			return theme.fg("warning", "⚠");
+		case "unknown":
+			return theme.fg("dim", "○");
+	}
+}

package/src/services/f5xc-table.ts

@@ -1,9 +1,8 @@
 import type { AuthStatus } from "./f5xc-profile";
+import { formatStatusIcon } from "./f5xc-profile-indicators";
 
 // F5 Brand Red — same as welcome.ts line 203
 const F5_RED = "\x1b[38;5;160m";
-const GREEN = "\x1b[38;5;34m";
-const RED_TEXT = "\x1b[38;5;196m";
 const RESET = "\x1b[0m";
 const BOLD = "\x1b[1m";
 
@@ -25,13 +24,13 @@ export function formatAuthIndicator(status: AuthStatus, latencyMs?: number): str
 	const ms = latencyMs !== undefined ? ` (${latencyMs}ms)` : "";
 	switch (status) {
 		case "connected":
-			return `${GREEN}\u25CF${RESET} Connected${ms}`;
+			return `${formatStatusIcon("connected")} Connected${ms}`;
 		case "auth_error":
-			return `${RED_TEXT}\u25CB${RESET} Auth Error${ms}`;
+			return `${formatStatusIcon("error")} Auth Error${ms}`;
 		case "offline":
-			return `${RED_TEXT}\u25CB${RESET} Offline`;
+			return `${formatStatusIcon("warning")} Offline`;
 		default:
-			return `\u25CB Unknown`;
+			return `${formatStatusIcon("unknown")} Unknown`;
 	}
 }