@f5xc-salesdemos/xcsh 17.5.1 → 18.0.0

package/package.json

@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@f5xc-salesdemos/xcsh",
-	"version": "17.5.1",
+	"version": "18.0.0",
 	"description": "Coding agent CLI with read, bash, edit, write tools and session management",
 	"homepage": "https://github.com/f5xc-salesdemos/xcsh",
 	"author": "Can Boluk",
@@ -31,27 +31,28 @@
 		"xcsh": "src/cli.ts"
 	},
 	"scripts": {
-		"build": "bun --cwd=../stats 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",
+		"build": "bun run generate-build-info && bun --cwd=../stats 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",
 		"check": "biome check . && bun run check:types",
-		"check:types": "tsgo -p tsconfig.json --noEmit",
+		"check:types": "bun run generate-build-info && tsgo -p tsconfig.json --noEmit",
 		"lint": "biome lint .",
-		"test": "bun test --max-concurrency 4",
-		"fix": "biome check --write --unsafe . && bun run format-prompts && bun run generate-docs-index",
+		"test": "bun run generate-build-info && bun test --max-concurrency 4",
+		"fix": "biome check --write --unsafe . && bun run format-prompts && bun run generate-docs-index && bun run generate-build-info",
 		"fmt": "biome format --write . && bun run format-prompts",
 		"format-prompts": "bun scripts/format-prompts.ts",
 		"generate-docs-index": "bun scripts/generate-docs-index.ts",
-		"prepack": "bun scripts/generate-docs-index.ts",
+		"generate-build-info": "bun scripts/generate-build-info.ts",
+		"prepack": "bun scripts/generate-docs-index.ts && bun scripts/generate-build-info.ts",
 		"generate-template": "bun scripts/generate-template.ts"
 	},
 	"dependencies": {
 		"@agentclientprotocol/sdk": "0.16.1",
 		"@mozilla/readability": "^0.6",
-		"@f5xc-salesdemos/xcsh-stats": "17.5.1",
-		"@f5xc-salesdemos/pi-agent-core": "17.5.1",
-		"@f5xc-salesdemos/pi-ai": "17.5.1",
-		"@f5xc-salesdemos/pi-natives": "17.5.1",
-		"@f5xc-salesdemos/pi-tui": "17.5.1",
-		"@f5xc-salesdemos/pi-utils": "17.5.1",
+		"@f5xc-salesdemos/xcsh-stats": "18.0.0",
+		"@f5xc-salesdemos/pi-agent-core": "18.0.0",
+		"@f5xc-salesdemos/pi-ai": "18.0.0",
+		"@f5xc-salesdemos/pi-natives": "18.0.0",
+		"@f5xc-salesdemos/pi-tui": "18.0.0",
+		"@f5xc-salesdemos/pi-utils": "18.0.0",
 		"@sinclair/typebox": "^0.34",
 		"@xterm/headless": "^6.0",
 		"ajv": "^8.18",

package/scripts/build-info/resolvers.ts

@@ -0,0 +1,51 @@
+export interface EnvLike {
+	readonly XCSH_BUILD_COMMIT?: string;
+	readonly XCSH_BUILD_BRANCH?: string;
+	readonly XCSH_BUILD_TAG?: string;
+	readonly XCSH_BUILD_PR?: string;
+}
+
+export type GitFn = (args: string[]) => Promise<string>;
+export type GhFn = (sha: string) => Promise<string>;
+
+function pick(value: string | undefined): string {
+	return value?.trim() ?? "";
+}
+
+export async function resolveCommit(env: EnvLike, git: GitFn): Promise<string> {
+	return pick(env.XCSH_BUILD_COMMIT) || (await git(["rev-parse", "HEAD"]));
+}
+
+export async function resolveBranch(env: EnvLike, git: GitFn): Promise<string> {
+	const override = pick(env.XCSH_BUILD_BRANCH);
+	if (override) return override;
+
+	const local = await git(["rev-parse", "--abbrev-ref", "HEAD"]);
+	if (local && local !== "HEAD") return local;
+
+	const remote = await git(["branch", "-r", "--contains", "HEAD"]);
+	for (const raw of remote.split("\n")) {
+		const line = raw.trim();
+		if (!line || line.includes("->") || line === "HEAD") continue;
+		const stripped = line.replace(/^origin\//, "");
+		if (stripped && stripped !== "HEAD") return stripped;
+	}
+
+	return "unknown";
+}
+
+export async function resolveTag(env: EnvLike, git: GitFn): Promise<string> {
+	return pick(env.XCSH_BUILD_TAG) || (await git(["describe", "--exact-match", "--tags", "HEAD"]));
+}
+
+export async function resolveDirty(_env: EnvLike, git: GitFn): Promise<boolean> {
+	const status = await git(["status", "--porcelain"]);
+	return status.length > 0;
+}
+
+export async function resolvePrNumber(sha: string, env: EnvLike, gh: GhFn): Promise<string> {
+	const override = pick(env.XCSH_BUILD_PR);
+	if (override) return override;
+	if (!sha) return "";
+	return await gh(sha);
+}

package/scripts/generate-build-info.ts

@@ -0,0 +1,106 @@
+#!/usr/bin/env bun
+
+import * as path from "node:path";
+import { $ } from "bun";
+import {
+	type EnvLike,
+	resolveBranch,
+	resolveCommit,
+	resolveDirty,
+	resolvePrNumber,
+	resolveTag,
+} from "./build-info/resolvers";
+
+const repoRoot = path.resolve(import.meta.dir, "../../..");
+const outputPath = path.resolve(import.meta.dir, "../src/internal-urls/build-info.generated.ts");
+const utilsPackageJsonPath = path.resolve(repoRoot, "packages/utils/package.json");
+
+const REPO_SLUG = "f5xc-salesdemos/xcsh";
+const REPO_URL = `https://github.com/${REPO_SLUG}`;
+
+async function git(args: string[]): Promise<string> {
+	try {
+		const result = await $`git ${args}`.cwd(repoRoot).quiet();
+		return result.stdout.toString().trim();
+	} catch {
+		return "";
+	}
+}
+
+async function ghPrForSha(sha: string): Promise<string> {
+	try {
+		const result =
+			await $`gh pr list --search ${sha} --state merged --json number --limit 1 --jq ${".[0].number // empty"}`
+				.cwd(repoRoot)
+				.quiet();
+		return result.stdout.toString().trim();
+	} catch {
+		return "";
+	}
+}
+
+async function resolveCommitDate(sha: string): Promise<string> {
+	if (!sha) return "";
+	return await git(["log", "-1", "--format=%cI", sha]);
+}
+
+const env = process.env as EnvLike;
+
+const utilsPackageJson = (await Bun.file(utilsPackageJsonPath).json()) as { version: string };
+const version = utilsPackageJson.version;
+const commit = await resolveCommit(env, git);
+const shortCommit = commit ? commit.slice(0, 7) : "";
+const branch = await resolveBranch(env, git);
+const tag = await resolveTag(env, git);
+const commitDate = await resolveCommitDate(commit);
+const dirty = await resolveDirty(env, git);
+const prNumber = await resolvePrNumber(commit, env, ghPrForSha);
+const buildDate = new Date().toISOString();
+const releaseUrl = `${REPO_URL}/releases/tag/v${version}`;
+const commitUrl = commit ? `${REPO_URL}/commit/${commit}` : REPO_URL;
+
+const output = [
+	"// Auto-generated by scripts/generate-build-info.ts - DO NOT EDIT",
+	"",
+	"export interface BuildInfo {",
+	"\treadonly version: string;",
+	"\treadonly commit: string;",
+	"\treadonly shortCommit: string;",
+	"\treadonly branch: string;",
+	"\treadonly tag: string;",
+	"\treadonly commitDate: string;",
+	"\treadonly buildDate: string;",
+	"\treadonly dirty: boolean;",
+	"\treadonly prNumber: string;",
+	"\treadonly repoUrl: string;",
+	"\treadonly repoSlug: string;",
+	"\treadonly commitUrl: string;",
+	"\treadonly releaseUrl: string;",
+	"}",
+	"",
+	`export const BUILD_INFO: BuildInfo = ${JSON.stringify(
+		{
+			version,
+			commit,
+			shortCommit,
+			branch,
+			tag,
+			commitDate,
+			buildDate,
+			dirty,
+			prNumber,
+			repoUrl: REPO_URL,
+			repoSlug: REPO_SLUG,
+			commitUrl,
+			releaseUrl,
+		},
+		null,
+		"\t",
+	)};`,
+	"",
+].join("\n");
+
+await Bun.write(outputPath, output);
+console.log(
+	`Generated ${path.relative(process.cwd(), outputPath)} (v${version}, ${shortCommit || "no-commit"}, branch=${branch}${tag ? `, tag=${tag}` : ""}${dirty ? ", dirty" : ""})`,
+);

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

@@ -0,0 +1,182 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { $ } from "bun";
+import { BUILD_INFO, type BuildInfo } from "./build-info.generated";
+
+export type BuildInfoSource = "compiled" | "live-git" | "embedded-fallback";
+
+export interface RuntimeBuildInfo extends BuildInfo {
+	readonly source: BuildInfoSource;
+	readonly resolvedAt: string;
+}
+
+export interface RuntimeBuildInfoDeps {
+	readonly isCompiled: boolean;
+	readonly gitAvailable: () => boolean;
+	readonly git: (args: string[]) => Promise<string>;
+	readonly now: () => Date;
+}
+
+function shortOf(sha: string): string {
+	return sha ? sha.slice(0, 7) : "";
+}
+
+function commitUrl(repoUrl: string, commit: string): string {
+	return commit ? `${repoUrl}/commit/${commit}` : repoUrl;
+}
+
+function firstRemoteBranch(output: string): string {
+	for (const raw of output.split("\n")) {
+		const line = raw.trim();
+		if (!line || line.includes("->") || line === "HEAD") continue;
+		const stripped = line.replace(/^origin\//, "");
+		if (stripped && stripped !== "HEAD") return stripped;
+	}
+	return "";
+}
+
+async function liveBranch(git: RuntimeBuildInfoDeps["git"]): Promise<string> {
+	const abbrev = await git(["rev-parse", "--abbrev-ref", "HEAD"]);
+	if (abbrev && abbrev !== "HEAD") return abbrev;
+	const remote = await git(["branch", "-r", "--contains", "HEAD"]);
+	return firstRemoteBranch(remote);
+}
+
+export async function resolveRuntimeBuildInfo(
+	embedded: BuildInfo,
+	deps: RuntimeBuildInfoDeps,
+): Promise<RuntimeBuildInfo> {
+	const resolvedAt = deps.now().toISOString();
+
+	if (deps.isCompiled) {
+		return { ...embedded, source: "compiled", resolvedAt };
+	}
+
+	if (!deps.gitAvailable()) {
+		return { ...embedded, source: "embedded-fallback", resolvedAt };
+	}
+
+	const commit = (await deps.git(["rev-parse", "HEAD"])) || embedded.commit;
+	const branch = (await liveBranch(deps.git)) || embedded.branch;
+	const tag = await deps.git(["describe", "--exact-match", "--tags", "HEAD"]);
+	const status = await deps.git(["status", "--porcelain"]);
+	const dirty = status.length > 0;
+	const commitDate = (await deps.git(["log", "-1", "--format=%cI", "HEAD"])) || embedded.commitDate;
+
+	return {
+		version: embedded.version,
+		commit,
+		shortCommit: shortOf(commit),
+		branch,
+		tag,
+		commitDate,
+		buildDate: embedded.buildDate,
+		dirty,
+		prNumber: embedded.prNumber,
+		repoUrl: embedded.repoUrl,
+		repoSlug: embedded.repoSlug,
+		commitUrl: commitUrl(embedded.repoUrl, commit),
+		releaseUrl: embedded.releaseUrl,
+		source: "live-git",
+		resolvedAt,
+	};
+}
+
+export function renderAboutDoc(info: RuntimeBuildInfo): string {
+	return [
+		"# xcsh — identity and build fingerprint",
+		"",
+		"You are running inside xcsh, a coworker-style CLI for F5 sales engineers:",
+		"demos, docs, research, MEDDPICC, customer meeting prep, and day-to-day SE tasks.",
+		"This document is the authoritative answer when the user asks about xcsh itself.",
+		"",
+		"## Build fingerprint",
+		"",
+		`- Version: \`${info.version}\``,
+		`- Commit: \`${info.shortCommit || "unknown"}\` (full: \`${info.commit || "unknown"}\`)`,
+		`- Branch: \`${info.branch || "unknown"}\``,
+		`- Tag: ${info.tag ? `\`${info.tag}\`` : "(not a tagged build)"}`,
+		`- Commit date: ${info.commitDate || "unknown"}`,
+		`- Build date: ${info.buildDate || "unknown"}`,
+		`- Built from dirty tree: ${info.dirty ? "yes" : "no"}`,
+		`- PR that shipped this version: ${info.prNumber ? `#${info.prNumber}` : "unknown (resolve via gh if needed)"}`,
+		`- Provenance source: \`${info.source}\` (resolved at ${info.resolvedAt})`,
+		"",
+		"## Source of truth",
+		"",
+		`- Repository: ${info.repoUrl}`,
+		`- Issues: ${info.repoUrl}/issues`,
+		`- Pull requests: ${info.repoUrl}/pulls`,
+		`- This commit on GitHub: ${info.commitUrl}`,
+		`- Release for this version: ${info.releaseUrl}`,
+		"",
+		"## 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`.",
+		"2. Check recent changes with `gh pr list --repo f5xc-salesdemos/xcsh --base main --state merged --limit 20`",
+		"   or `git log --oneline -n 20` if you have a local clone. A fix may already be on `main`.",
+		"3. If behavior contradicts `xcsh://…` docs, read the actual source under the repo above to determine",
+		"   whether the binary is wrong or the doc is stale.",
+		"4. Classify the report as one of: **bug**, **feature**, **docs-drift**, or **config/usage**.",
+		"5. Offer to file it with",
+		"   `gh issue create --repo f5xc-salesdemos/xcsh --title ... --body ...`, referencing the commit above.",
+		"",
+		"## What NOT to assume",
+		"",
+		"- Do not guess the repo URL, version, or commit — use the values above.",
+		"- Do not invent recent changes; fetch them at runtime via `gh` or `git`.",
+		"- Do not read this document unless the user asked about xcsh itself.",
+		"",
+	].join("\n");
+}
+
+// Bun-embedded module URL markers. Mirrors the native addon loader
+// (see xcsh://natives-addon-loader-runtime.md) so compiled-mode detection stays
+// consistent across the codebase. Update all three in lockstep if Bun changes them.
+const COMPILED_URL_MARKERS = ["$bunfs", "~BUN", "%7EBUN"] as const;
+
+export function detectCompiledRuntime(
+	metaUrl: string,
+	env: Readonly<Record<string, string | undefined>> = {},
+): boolean {
+	if (env.PI_COMPILED) return true;
+	return COMPILED_URL_MARKERS.some(marker => metaUrl.includes(marker));
+}
+
+export function findGitRoot(startDir: string, fsExists: (p: string) => boolean = fs.existsSync): string | null {
+	let current = path.resolve(startDir);
+	while (true) {
+		if (fsExists(path.join(current, ".git"))) return current;
+		const parent = path.dirname(current);
+		if (parent === current) return null;
+		current = parent;
+	}
+}
+
+export function defaultRuntimeDeps(): RuntimeBuildInfoDeps {
+	const isCompiled = detectCompiledRuntime(import.meta.url, Bun.env);
+	const gitRoot = isCompiled ? null : findGitRoot(import.meta.dir);
+
+	return {
+		isCompiled,
+		gitAvailable: () => gitRoot !== null,
+		git: async (args: string[]): Promise<string> => {
+			if (!gitRoot) return "";
+			try {
+				const result = await $`git ${args}`.cwd(gitRoot).quiet();
+				return result.stdout.toString().trim();
+			} catch {
+				return "";
+			}
+		},
+		now: () => new Date(),
+	};
+}
+
+// Intentionally no cache. `xcsh://about` is invoked once per xcsh-related question
+// at agent-tool-call granularity; stale fingerprints after branch-switch / dirty-tree
+// changes would silently lie under source-mode. Re-resolving costs ~30ms of git subprocess
+// time in source mode and ~0ms in compiled mode (where we return embedded BUILD_INFO).
+export function getRuntimeBuildInfo(): Promise<RuntimeBuildInfo> {
+	return resolveRuntimeBuildInfo(BUILD_INFO, defaultRuntimeDeps());
+}

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

@@ -0,0 +1,33 @@
+// Auto-generated by scripts/generate-build-info.ts - DO NOT EDIT
+
+export interface BuildInfo {
+	readonly version: string;
+	readonly commit: string;
+	readonly shortCommit: string;
+	readonly branch: string;
+	readonly tag: string;
+	readonly commitDate: string;
+	readonly buildDate: string;
+	readonly dirty: boolean;
+	readonly prNumber: string;
+	readonly repoUrl: string;
+	readonly repoSlug: string;
+	readonly commitUrl: string;
+	readonly releaseUrl: string;
+}
+
+export const BUILD_INFO: BuildInfo = {
+	"version": "18.0.0",
+	"commit": "693d44240bf4f157a21a15357ff00114c90a3fe5",
+	"shortCommit": "693d442",
+	"branch": "main",
+	"tag": "v18.0.0",
+	"commitDate": "2026-04-19T21:26:31Z",
+	"buildDate": "2026-04-19T21:47:02.421Z",
+	"dirty": false,
+	"prNumber": "",
+	"repoUrl": "https://github.com/f5xc-salesdemos/xcsh",
+	"repoSlug": "f5xc-salesdemos/xcsh",
+	"commitUrl": "https://github.com/f5xc-salesdemos/xcsh/commit/693d44240bf4f157a21a15357ff00114c90a3fe5",
+	"releaseUrl": "https://github.com/f5xc-salesdemos/xcsh/releases/tag/v18.0.0"
+};

package/src/internal-urls/index.ts

@@ -28,8 +28,8 @@ export * from "./local-protocol";
 export * from "./mcp-protocol";
 export * from "./memory-protocol";
 export * from "./parse";
-export * from "./pi-protocol";
 export * from "./router";
 export * from "./rule-protocol";
 export * from "./skill-protocol";
 export type * from "./types";
+export * from "./xcsh-protocol";

package/src/internal-urls/router.ts

@@ -1,5 +1,6 @@
 /**
- * Internal URL router for internal protocols (agent://, artifact://, memory://, skill://, rule://, mcp://, pi://, local://).
+ * Internal URL router for internal protocols
+ * (agent://, artifact://, memory://, skill://, rule://, mcp://, xcsh://, local://, jobs://).
  */
 import { parseInternalUrl } from "./parse";
 import type { InternalResource, InternalUrl, ProtocolHandler } from "./types";

package/src/internal-urls/types.ts

@@ -1,7 +1,7 @@
 /**
  * Types for the internal URL routing system.
  *
- * Internal URLs (agent://, artifact://, memory://, skill://, rule://, mcp://, pi://, local://) are resolved by tools like read,
+ * Internal URLs (agent://, artifact://, memory://, skill://, rule://, mcp://, xcsh://, local://) are resolved by tools like read,
  * providing access to agent outputs and server resources without exposing filesystem paths.
  */
 

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

@@ -0,0 +1,113 @@
+/**
+ * Protocol handler for xcsh:// URLs.
+ *
+ * Serves statically embedded documentation files bundled at build time,
+ * plus the runtime-resolved `about` identity doc.
+ *
+ * URL forms:
+ * - xcsh:// - Lists all available documentation files
+ * - xcsh://<file>.md - Reads a specific documentation file
+ * - xcsh://about - Identity fingerprint (version, commit, branch, repo)
+ */
+import * as path from "node:path";
+import { getRuntimeBuildInfo, type RuntimeBuildInfo, renderAboutDoc } from "./build-info-runtime";
+import { EMBEDDED_DOC_FILENAMES, EMBEDDED_DOCS } from "./docs-index.generated";
+import type { InternalResource, InternalUrl, ProtocolHandler } from "./types";
+
+const SCHEME_PREFIX = "xcsh://";
+const ABOUT_ROUTE = "about";
+
+export interface InternalDocsProtocolOptions {
+	/** Override runtime build-info resolution. Primarily for tests. */
+	readonly resolveBuildInfo?: () => Promise<RuntimeBuildInfo>;
+}
+
+/**
+ * Handler for the xcsh:// internal documentation protocol.
+ *
+ * Resolves documentation file names to their content, lists available docs,
+ * and serves the runtime identity doc at xcsh://about.
+ */
+export class InternalDocsProtocolHandler implements ProtocolHandler {
+	readonly scheme = "xcsh";
+	readonly #resolveBuildInfo: () => Promise<RuntimeBuildInfo>;
+
+	constructor(options: InternalDocsProtocolOptions = {}) {
+		this.#resolveBuildInfo = options.resolveBuildInfo ?? getRuntimeBuildInfo;
+	}
+
+	async resolve(url: InternalUrl): Promise<InternalResource> {
+		const host = url.rawHost || url.hostname;
+		const pathname = url.rawPathname ?? url.pathname;
+		const filename = host ? (pathname && pathname !== "/" ? host + pathname : host) : "";
+
+		if (!filename) {
+			return this.#listDocs(url);
+		}
+
+		return this.#readDoc(filename, url);
+	}
+
+	async #listDocs(url: InternalUrl): Promise<InternalResource> {
+		if (EMBEDDED_DOC_FILENAMES.length === 0) {
+			throw new Error("No documentation files found");
+		}
+
+		const syntheticEntry = `- [${ABOUT_ROUTE}](${SCHEME_PREFIX}${ABOUT_ROUTE}) — identity and build fingerprint`;
+		const listing = [syntheticEntry, ...EMBEDDED_DOC_FILENAMES.map(f => `- [${f}](${SCHEME_PREFIX}${f})`)].join("\n");
+		const totalCount = EMBEDDED_DOC_FILENAMES.length + 1;
+		const content = `# Documentation\n\n${totalCount} files available:\n\n${listing}\n`;
+
+		return {
+			url: url.href,
+			content,
+			contentType: "text/markdown",
+			size: Buffer.byteLength(content, "utf-8"),
+			sourcePath: SCHEME_PREFIX,
+		};
+	}
+
+	async #readDoc(filename: string, url: InternalUrl): Promise<InternalResource> {
+		if (path.isAbsolute(filename)) {
+			throw new Error(`Absolute paths are not allowed in ${SCHEME_PREFIX} URLs`);
+		}
+
+		const normalized = path.posix.normalize(filename.replaceAll("\\", "/"));
+		if (normalized === ".." || normalized.startsWith("../") || normalized.includes("/../")) {
+			throw new Error(`Path traversal (..) is not allowed in ${SCHEME_PREFIX} URLs`);
+		}
+
+		if (normalized === ABOUT_ROUTE || normalized === `${ABOUT_ROUTE}.md`) {
+			const info = await this.#resolveBuildInfo();
+			const content = renderAboutDoc(info);
+			return {
+				url: url.href,
+				content,
+				contentType: "text/markdown",
+				size: Buffer.byteLength(content, "utf-8"),
+				sourcePath: `${SCHEME_PREFIX}${ABOUT_ROUTE}`,
+			};
+		}
+
+		const content = EMBEDDED_DOCS[normalized];
+		if (content === undefined) {
+			const lookup = normalized.replace(/\.md$/, "");
+			const suggestions = EMBEDDED_DOC_FILENAMES.filter(
+				f => f.includes(lookup) || lookup.includes(f.replace(/\.md$/, "")),
+			).slice(0, 5);
+			const suffix =
+				suggestions.length > 0
+					? `\nDid you mean: ${suggestions.join(", ")}`
+					: `\nUse ${SCHEME_PREFIX} to list available files.`;
+			throw new Error(`Documentation file not found: ${filename}${suffix}`);
+		}
+
+		return {
+			url: url.href,
+			content,
+			contentType: "text/markdown",
+			size: Buffer.byteLength(content, "utf-8"),
+			sourcePath: `${SCHEME_PREFIX}${normalized}`,
+		};
+	}
+}

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

@@ -142,7 +142,8 @@ Most tools resolve custom protocol URLs to internal resources (not web URLs):
 - `local://<TITLE>.md` — Finalized plan artifact created after `exit_plan_mode` approval
 - `jobs://<job-id>` — Specific job status and result
 - `mcp://<resource-uri>` — MCP resource from a connected server; matched against exact resource URIs first, then RFC 6570 URI templates advertised by connected servers
-- `pi://..` — Internal documentation files about xcsh; you **MUST NOT** read them unless the user asks about xcsh itself: its SDK, extensions, themes, skills, TUI, keybindings, or configuration
+- `xcsh://..` — Internal documentation files about xcsh; you **MUST NOT** read them unless the user asks about xcsh itself: its SDK, extensions, themes, skills, TUI, keybindings, or configuration
+  - `xcsh://about` — authoritative identity and build fingerprint for xcsh itself (version, commit, tag, branch, repo). Read it whenever the question is about xcsh itself, not about the user's own codebase.
 
 In `bash`, URIs auto-resolve to filesystem paths (e.g., `python skill://my-skill/scripts/init.py`).
 

package/src/sdk.ts

@@ -63,12 +63,12 @@ import { type FileSlashCommand, loadSlashCommands as loadSlashCommandsInternal }
 import {
 	AgentProtocolHandler,
 	ArtifactProtocolHandler,
+	InternalDocsProtocolHandler,
 	InternalUrlRouter,
 	JobsProtocolHandler,
 	LocalProtocolHandler,
 	McpProtocolHandler,
 	MemoryProtocolHandler,
-	PiProtocolHandler,
 	RuleProtocolHandler,
 	SkillProtocolHandler,
 } from "./internal-urls";
@@ -1056,7 +1056,7 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 				getRules: () => [...rulebookRules, ...alwaysApplyRules],
 			}),
 		);
-		internalRouter.register(new PiProtocolHandler());
+		internalRouter.register(new InternalDocsProtocolHandler());
 		internalRouter.register(new JobsProtocolHandler({ getAsyncJobManager: () => asyncJobManager }));
 		internalRouter.register(new McpProtocolHandler({ getMcpManager: () => mcpManager }));
 		toolSession.internalRouter = internalRouter;

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

@@ -1,84 +0,0 @@
-/**
- * Protocol handler for pi:// URLs.
- *
- * Serves statically embedded documentation files bundled at build time.
- *
- * URL forms:
- * - pi:// - Lists all available documentation files
- * - pi://<file>.md - Reads a specific documentation file
- */
-import * as path from "node:path";
-import { EMBEDDED_DOC_FILENAMES, EMBEDDED_DOCS } from "./docs-index.generated";
-import type { InternalResource, InternalUrl, ProtocolHandler } from "./types";
-
-/**
- * Handler for pi:// URLs.
- *
- * Resolves documentation file names to their content, or lists available docs.
- */
-export class PiProtocolHandler implements ProtocolHandler {
-	readonly scheme = "pi";
-
-	async resolve(url: InternalUrl): Promise<InternalResource> {
-		// Extract filename from host + path
-		const host = url.rawHost || url.hostname;
-		const pathname = url.rawPathname ?? url.pathname;
-		const filename = host ? (pathname && pathname !== "/" ? host + pathname : host) : "";
-
-		if (!filename) {
-			return this.#listDocs(url);
-		}
-
-		return this.#readDoc(filename, url);
-	}
-
-	async #listDocs(url: InternalUrl): Promise<InternalResource> {
-		if (EMBEDDED_DOC_FILENAMES.length === 0) {
-			throw new Error("No documentation files found");
-		}
-
-		const listing = EMBEDDED_DOC_FILENAMES.map(f => `- [${f}](pi://${f})`).join("\n");
-		const content = `# Documentation\n\n${EMBEDDED_DOC_FILENAMES.length} files available:\n\n${listing}\n`;
-
-		return {
-			url: url.href,
-			content,
-			contentType: "text/markdown",
-			size: Buffer.byteLength(content, "utf-8"),
-			sourcePath: "pi://",
-		};
-	}
-
-	async #readDoc(filename: string, url: InternalUrl): Promise<InternalResource> {
-		// Validate: no traversal, no absolute paths
-		if (path.isAbsolute(filename)) {
-			throw new Error("Absolute paths are not allowed in pi:// URLs");
-		}
-
-		const normalized = path.posix.normalize(filename.replaceAll("\\", "/"));
-		if (normalized === ".." || normalized.startsWith("../") || normalized.includes("/../")) {
-			throw new Error("Path traversal (..) is not allowed in pi:// URLs");
-		}
-
-		const content = EMBEDDED_DOCS[normalized];
-		if (content === undefined) {
-			const lookup = normalized.replace(/\.md$/, "");
-			const suggestions = EMBEDDED_DOC_FILENAMES.filter(
-				f => f.includes(lookup) || lookup.includes(f.replace(/\.md$/, "")),
-			).slice(0, 5);
-			const suffix =
-				suggestions.length > 0
-					? `\nDid you mean: ${suggestions.join(", ")}`
-					: "\nUse pi:// to list available files.";
-			throw new Error(`Documentation file not found: ${filename}${suffix}`);
-		}
-
-		return {
-			url: url.href,
-			content,
-			contentType: "text/markdown",
-			size: Buffer.byteLength(content, "utf-8"),
-			sourcePath: `pi://${normalized}`,
-		};
-	}
-}