@f5-sales-demo/xcsh 19.85.7 → 19.86.0

package/package.json

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

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

@@ -217,8 +217,9 @@ export function renderAboutDoc(info: RuntimeBuildInfo, context: ContextStatus |
 		"## What to do when asked about xcsh itself",
 		"",
 		"1. The version above is authoritative — it is embedded at build time in this session's BUILD_INFO and also shown in the `<workstation>` header of the system prompt. Do not run `xcsh --version` to check — that reports the installed binary, which may differ from the running session after an upgrade.",
-		"2. Check recent changes with `gh pr list --repo f5-sales-demo/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`.",
+		'2. For recent changes / "what\'s new", read `xcsh://changes` — it lists merged PRs live and flags',
+		"   what shipped after your build (it falls back to `gh pr list` / `git log` when gh is unavailable).",
+		'   A fix may already be on `main`. For "where is X implemented?", read `xcsh://source`.',
 		"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**.",
@@ -241,6 +242,13 @@ export function renderAboutDoc(info: RuntimeBuildInfo, context: ContextStatus |
 		"",
 		"The improvement workflow is always: open an issue on the repo, then a PR. The user receives changes only after a new release is built and they upgrade. Do not claim a change is live until the commit above reflects it.",
 		"",
+		"You are a GitHub / devops / security **operator**: your job is to author the issue, the",
+		"reproduction, the Terraform/manifests/scripts/docs, and the PR description — but **implementing**",
+		"feature code on xcsh, `f5-sales-demo/marketplace`, or `f5-sales-demo/api-specs-enriched` is",
+		"delegated to a dedicated coding harness (Claude Code / Codex) with its own dev environment.",
+		"To file well: clone the relevant repo, reproduce the behavior first, and follow `CONTRIBUTING.md` —",
+		"TDD, evidence required, no unverified claims.",
+		"",
 		"## What NOT to assume",
 		"",
 		"- Do not guess the repo URL, version, or commit — use the values above.",

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

@@ -17,17 +17,17 @@ export interface BuildInfo {
 }
 
 export const BUILD_INFO: BuildInfo = {
-	"version": "19.85.7",
-	"commit": "9ca40d6aab40f53a85bba28e4ff8b0f6ceed1782",
-	"shortCommit": "9ca40d6",
+	"version": "19.86.0",
+	"commit": "24a43f94c2aca0385cb3284227d0a503de320b32",
+	"shortCommit": "24a43f9",
 	"branch": "main",
-	"tag": "v19.85.7",
-	"commitDate": "2026-07-24T13:17:17Z",
-	"buildDate": "2026-07-24T13:42:27.292Z",
+	"tag": "v19.86.0",
+	"commitDate": "2026-07-24T16:55:07Z",
+	"buildDate": "2026-07-24T17:20:18.596Z",
 	"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/9ca40d6aab40f53a85bba28e4ff8b0f6ceed1782",
-	"releaseUrl": "https://github.com/f5-sales-demo/xcsh/releases/tag/v19.85.7"
+	"commitUrl": "https://github.com/f5-sales-demo/xcsh/commit/24a43f94c2aca0385cb3284227d0a503de320b32",
+	"releaseUrl": "https://github.com/f5-sales-demo/xcsh/releases/tag/v19.86.0"
 };

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

@@ -0,0 +1,212 @@
+/**
+ * Resolver for xcsh://changes — "what changed recently in xcsh".
+ *
+ * xcsh's own recent history is NOT static prompt knowledge: it lives in merged
+ * pull requests on the source repo. This resolver fetches them live via `gh`
+ * and flags which ones landed after the running build, so the agent can answer
+ * "what's new / can you do X now?" from ground truth rather than memory.
+ *
+ * URL forms (host = "changes"):
+ * - xcsh://changes            -> recent merged PRs on main (default limit 20)
+ * - xcsh://changes?limit=N    -> recent merged PRs, capped at N
+ *
+ * Dynamic, uncached (mirrors xcsh://about). All shelling is injected so the
+ * resolver is unit-testable without a network or a `gh` binary.
+ */
+import { $ } from "bun";
+import { formatRelativeTime, type RuntimeBuildInfo } from "./build-info-runtime";
+import type { InternalResource, InternalUrl } from "./types";
+
+export interface GhResult {
+	readonly ok: boolean;
+	readonly stdout: string;
+	readonly stderr: string;
+}
+
+export interface MergedPr {
+	readonly number: number;
+	readonly title: string;
+	readonly mergedAt: string;
+	readonly url: string;
+}
+
+export interface ChangesDeps {
+	readonly resolveBuildInfo: () => Promise<RuntimeBuildInfo>;
+	readonly runGh: (args: string[]) => Promise<GhResult>;
+	readonly now: () => Date;
+}
+
+export const DEFAULT_CHANGES_LIMIT = 20;
+const MAX_CHANGES_LIMIT = 100;
+
+/** Parse the JSON array emitted by `gh pr list --json ...`. Throws on malformed input. */
+export function parseMergedPrs(json: string): MergedPr[] {
+	const parsed = JSON.parse(json);
+	if (!Array.isArray(parsed)) {
+		throw new Error("Expected a JSON array of pull requests");
+	}
+	return parsed.map(entry => ({
+		number: Number(entry.number),
+		title: String(entry.title ?? ""),
+		mergedAt: String(entry.mergedAt ?? ""),
+		url: String(entry.url ?? ""),
+	}));
+}
+
+/** Derive "owner/repo" from build info, falling back to the repo URL. */
+function repoSlugOf(info: RuntimeBuildInfo): string {
+	if (info.repoSlug) return info.repoSlug;
+	return info.repoUrl.replace(/^https?:\/\/github\.com\//, "").replace(/\.git$/, "");
+}
+
+function parseLimit(url: InternalUrl): number {
+	const raw = url.searchParams.get("limit");
+	if (!raw) return DEFAULT_CHANGES_LIMIT;
+	const n = Number.parseInt(raw, 10);
+	if (!Number.isFinite(n) || n <= 0) return DEFAULT_CHANGES_LIMIT;
+	return Math.min(n, MAX_CHANGES_LIMIT);
+}
+
+function ghArgs(slug: string, limit: number): string[] {
+	return [
+		"pr",
+		"list",
+		"--repo",
+		slug,
+		"--base",
+		"main",
+		"--state",
+		"merged",
+		"--limit",
+		String(limit),
+		"--json",
+		"number,title,mergedAt,url",
+	];
+}
+
+/** Is this PR merged strictly after the running build's commit? Best-effort by date. */
+function isNewSinceBuild(pr: MergedPr, info: RuntimeBuildInfo): boolean {
+	if (!pr.mergedAt || !info.commitDate) return false;
+	const merged = Date.parse(pr.mergedAt);
+	const built = Date.parse(info.commitDate);
+	if (Number.isNaN(merged) || Number.isNaN(built)) return false;
+	return merged > built;
+}
+
+function renderHeader(info: RuntimeBuildInfo): string[] {
+	return [
+		"# Recent changes to xcsh",
+		"",
+		`Your running build: \`v${info.version}\` (commit \`${info.shortCommit || "unknown"}\`, ` +
+			`committed ${info.commitDate || "unknown"}). Anything merged after that is **new to you**.`,
+		"",
+	];
+}
+
+const FOOTER = [
+	"",
+	"---",
+	"To confirm a change actually works, **offer to exercise it** (run the specific command/scenario",
+	"it touches) and report the evidence — do not claim it works from the PR title alone.",
+	"If you find a bug or the user proposes an improvement, classify it and **offer to file** a",
+	"CONTRIBUTING-compliant issue (reproduce first; no unverified claims). See `xcsh://about`.",
+];
+
+export function renderChangesDoc(info: RuntimeBuildInfo, prs: MergedPr[], nowMs: number): string {
+	const lines = renderHeader(info);
+	if (prs.length === 0) {
+		lines.push("_No merged pull requests returned._");
+	} else {
+		for (const pr of prs) {
+			const merged = Date.parse(pr.mergedAt);
+			const when = Number.isNaN(merged) ? pr.mergedAt || "unknown" : formatRelativeTime(merged, nowMs);
+			const flag = isNewSinceBuild(pr, info) ? " — 🆕 new since your build" : "";
+			lines.push(`- #${pr.number} ${pr.title} (merged ${when})${flag}`);
+			lines.push(`  ${pr.url}`);
+		}
+	}
+	lines.push(...FOOTER);
+	return lines.join("\n");
+}
+
+/** Rendered when `gh` cannot be run — actionable, never a thrown error. */
+export function renderUnavailableDoc(info: RuntimeBuildInfo, slug: string, stderr: string): string {
+	const limit = DEFAULT_CHANGES_LIMIT;
+	return [
+		"# Recent changes to xcsh — could not query GitHub",
+		"",
+		`\`gh\` was unavailable or failed${stderr ? ` (${stderr.trim()})` : ""}.`,
+		"",
+		"Resolve recent changes manually — do not answer about new features from memory:",
+		"",
+		"```",
+		`gh pr list --repo ${slug} --base main --state merged --limit ${limit} --json number,title,mergedAt,url`,
+		"```",
+		"",
+		"Or, in a local clone of the repo:",
+		"",
+		"```",
+		"git log --oneline -n 20",
+		"```",
+		"",
+		`Your running build: \`v${info.version}\` (commit \`${info.shortCommit || "unknown"}\`).`,
+	].join("\n");
+}
+
+async function defaultRunGh(args: string[]): Promise<GhResult> {
+	try {
+		const res = await $`gh ${args}`.quiet().nothrow();
+		return {
+			ok: res.exitCode === 0,
+			stdout: res.stdout.toString(),
+			stderr: res.stderr.toString(),
+		};
+	} catch (err) {
+		return { ok: false, stdout: "", stderr: err instanceof Error ? err.message : String(err) };
+	}
+}
+
+export class ChangesResolver {
+	readonly #deps: ChangesDeps;
+
+	constructor(deps: ChangesDeps) {
+		this.#deps = deps;
+	}
+
+	async resolve(url: InternalUrl): Promise<InternalResource> {
+		const info = await this.#deps.resolveBuildInfo();
+		const slug = repoSlugOf(info);
+		const limit = parseLimit(url);
+
+		const result = await this.#deps.runGh(ghArgs(slug, limit));
+
+		let content: string;
+		if (!result.ok) {
+			content = renderUnavailableDoc(info, slug, result.stderr);
+		} else {
+			try {
+				const prs = parseMergedPrs(result.stdout);
+				content = renderChangesDoc(info, prs, this.#deps.now().getTime());
+			} catch (err) {
+				content = renderUnavailableDoc(info, slug, err instanceof Error ? err.message : String(err));
+			}
+		}
+
+		return {
+			url: url.href,
+			content,
+			contentType: "text/markdown",
+			size: Buffer.byteLength(content, "utf-8"),
+			sourcePath: `xcsh://changes`,
+		};
+	}
+}
+
+export function createChangesResolver(deps: Partial<ChangesDeps> = {}): ChangesResolver {
+	return new ChangesResolver({
+		resolveBuildInfo:
+			deps.resolveBuildInfo ?? (async () => (await import("./build-info-runtime")).getRuntimeBuildInfo()),
+		runGh: deps.runGh ?? defaultRunGh,
+		now: deps.now ?? (() => new Date()),
+	});
+}

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

@@ -0,0 +1,170 @@
+/**
+ * Resolver for xcsh://source — "where is X implemented in my own source?".
+ *
+ * A curated capability -> source-path map plus the soft/hard editable-surface
+ * rule, so the agent can point at concrete files (browsable at the exact
+ * running commit) instead of guessing. Complements xcsh://about (identity)
+ * and xcsh://changes (recent history).
+ *
+ * URL form (host = "source"):
+ * - xcsh://source -> capability map + editable-surface classification
+ */
+import type { RuntimeBuildInfo } from "./build-info-runtime";
+import type { InternalResource, InternalUrl } from "./types";
+
+export interface CapabilityEntry {
+	readonly capability: string;
+	readonly path: string;
+	readonly note: string;
+}
+
+export interface SourceDeps {
+	readonly resolveBuildInfo: () => Promise<RuntimeBuildInfo>;
+}
+
+/**
+ * Capability -> path index. Paths are repo-relative and stable; each is rendered
+ * as a link to the exact running commit so "read the source" lands on ground truth.
+ */
+export const CAPABILITY_MAP: readonly CapabilityEntry[] = [
+	{
+		capability: "Identity, reflexes, and guardrails (the system prompt itself)",
+		path: "packages/coding-agent/src/prompts/system/system-prompt.md",
+		note: "The <role>, <self-awareness>, and internal-URL hint content shipped to every session.",
+	},
+	{
+		capability: "System-prompt assembly (composition, conditional sections)",
+		path: "packages/coding-agent/src/system-prompt.ts",
+		note: "buildSystemPrompt() renders the template against runtime data.",
+	},
+	{
+		capability: "xcsh:// resolver layer (all internal URLs)",
+		path: "packages/coding-agent/src/internal-urls/",
+		note: "router.ts dispatches by scheme; *-resolve.ts handle each host.",
+	},
+	{
+		capability: "Identity / build fingerprint (xcsh://about)",
+		path: "packages/coding-agent/src/internal-urls/build-info-runtime.ts",
+		note: "renderAboutDoc() + git-backed build info.",
+	},
+	{
+		capability: "Recent changes (xcsh://changes)",
+		path: "packages/coding-agent/src/internal-urls/changes-resolve.ts",
+		note: "Live merged-PR history via gh; flags what is new since your build.",
+	},
+	{
+		capability: "This source map (xcsh://source)",
+		path: "packages/coding-agent/src/internal-urls/source-resolve.ts",
+		note: "The file you are reading the output of.",
+	},
+	{
+		capability: "CLI entrypoint / compiled binary",
+		path: "packages/coding-agent/src/cli.ts",
+		note: "Bun-compiled to dist/xcsh (bun build --compile).",
+	},
+	{
+		capability: "Tools (bash, edit, browser, xcsh_api, catalog_workflow_runner, ...)",
+		path: "packages/coding-agent/src/tools/",
+		note: "Tool implementations and their prompt fragments.",
+	},
+	{
+		capability: "SE skills (account-planning, competitive, demo-components, terraform-provider, ...)",
+		path: ".xcsh/skills/",
+		note: "SKILL.md-defined capabilities loaded on demand.",
+	},
+	{
+		capability: "F5 XC API catalog & spec (xcsh://api-catalog, xcsh://api-spec)",
+		path: "packages/coding-agent/src/internal-urls/api-catalog-resolve.ts",
+		note: "Generated indexes sourced from api-specs-enriched.",
+	},
+	{
+		capability: "Console browser automation (xcsh://console, catalog_workflow_runner)",
+		path: "packages/coding-agent/src/internal-urls/console-resolve.ts",
+		note: "Deterministic UI workflows driven through the Chrome extension.",
+	},
+	{
+		capability: "Plugin / marketplace subsystem",
+		path: "packages/coding-agent/src/extensibility/plugins/marketplace/",
+		note: "Installs from f5-sales-demo/marketplace; see also cli/plugin-cli.ts.",
+	},
+	{
+		capability: "Release chain (version bump -> tag -> Homebrew/npm)",
+		path: "scripts/release.ts",
+		note: "Paired with .github/workflows/ci.yml and tag-on-version-bump.yml.",
+	},
+	{
+		capability: "Native addon (Rust; a HARD surface — needs a compiled release)",
+		path: "crates/pi-natives/",
+		note: "Built via packages/natives; cannot be hot-patched by a prompt/skill PR.",
+	},
+	{
+		capability: "Contribution process (issue -> worktree -> TDD -> PR)",
+		path: "CONTRIBUTING.md",
+		note: "The rules for any change: no unverified claims, evidence required.",
+	},
+];
+
+function blobUrl(info: RuntimeBuildInfo, relPath: string): string {
+	const ref = info.commit || info.branch || "main";
+	return `${info.repoUrl}/blob/${ref}/${relPath}`;
+}
+
+export function renderSourceDoc(info: RuntimeBuildInfo): string {
+	const lines: string[] = [
+		"# xcsh source map — where capabilities live",
+		"",
+		`Repository (source of truth): ${info.repoUrl}`,
+		`Running build: \`v${info.version}\` (commit \`${info.shortCommit || "unknown"}\`). Links below point at that commit.`,
+		"",
+		"| Capability | Source | Note |",
+		"|------------|--------|------|",
+	];
+	for (const e of CAPABILITY_MAP) {
+		lines.push(`| ${e.capability} | [\`${e.path}\`](${blobUrl(info, e.path)}) | ${e.note} |`);
+	}
+	lines.push(
+		"",
+		"## Editable surfaces",
+		"",
+		"- **Soft surfaces** (shippable via a normal PR — behavior changes on next release):",
+		"  system prompt fragments, tool descriptions, internal-URL doc renderers, skills, new",
+		"  `xcsh://` docs, keybinding/theme defaults.",
+		"- **Hard surfaces** (require a compiled release — cannot hot-patch):",
+		"  the compiled binary, native Bun/Rust modules under `crates/` and `packages/*/native/`,",
+		"  startup bootstrap, and the build-info generator.",
+		"",
+		"`~/.xcsh/` on the machine is runtime config/state — **not** xcsh's source; editing it changes nothing shipped.",
+		"",
+		"To improve xcsh: open an issue, then a PR (see `CONTRIBUTING.md`). A change is not live until a",
+		"release is built and installed — do not claim it is. For recent history use `xcsh://changes`;",
+		"for identity/version use `xcsh://about`.",
+	);
+	return lines.join("\n");
+}
+
+export class SourceResolver {
+	readonly #deps: SourceDeps;
+
+	constructor(deps: SourceDeps) {
+		this.#deps = deps;
+	}
+
+	async resolve(url: InternalUrl): Promise<InternalResource> {
+		const info = await this.#deps.resolveBuildInfo();
+		const content = renderSourceDoc(info);
+		return {
+			url: url.href,
+			content,
+			contentType: "text/markdown",
+			size: Buffer.byteLength(content, "utf-8"),
+			sourcePath: `xcsh://source`,
+		};
+	}
+}
+
+export function createSourceResolver(deps: Partial<SourceDeps> = {}): SourceResolver {
+	return new SourceResolver({
+		resolveBuildInfo:
+			deps.resolveBuildInfo ?? (async () => (await import("./build-info-runtime")).getRuntimeBuildInfo()),
+	});
+}

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

@@ -38,6 +38,7 @@ import type {
 	OpenAPISpec,
 } from "./api-spec-types";
 import { getRuntimeBuildInfo, type RuntimeBuildInfo, renderAboutDoc } from "./build-info-runtime";
+import { type ChangesResolver, createChangesResolver } from "./changes-resolve";
 import { loadComputerProfile, renderComputerProfileMarkdown, seedComputerProfile } from "./computer-profile";
 import { type ConsoleCatalogData, EMPTY_CONSOLE_CATALOG } from "./console-catalog-types";
 import { type ConsoleFieldMetadataData, EMPTY_CONSOLE_FIELD_METADATA } from "./console-field-metadata-types";
@@ -45,6 +46,7 @@ import { type ConsoleResolver, createConsoleResolver } from "./console-resolve";
 import { EMBEDDED_DOC_FILENAMES, EMBEDDED_DOCS } from "./docs-index.generated";
 import extensionApiContent from "./extension-api.md" with { type: "text" };
 import { createPluginResolver, type GetPluginRoots, type PluginResolver } from "./plugin-resolve";
+import { createSourceResolver, type SourceResolver } from "./source-resolve";
 import { createTerraformResolver, type TerraformResolver } from "./terraform-resolve";
 import type { TerraformIndex } from "./terraform-types";
 import type { InternalResource, InternalUrl, ProtocolHandler } from "./types";
@@ -62,6 +64,8 @@ const COMPUTER_ROUTE = "computer";
 const CONSOLE_HOST = "console";
 const EXTENSION_HOST = "extension";
 const PLUGIN_HOST = "plugin";
+const CHANGES_HOST = "changes";
+const SOURCE_HOST = "source";
 const EMPTY_INDEX: ApiSpecIndex = { version: "unavailable", timestamp: "", domains: [] };
 const EMPTY_CATALOG_INDEX: ApiCatalogIndex = {
 	version: "unavailable",
@@ -279,6 +283,8 @@ export class InternalDocsProtocolHandler implements ProtocolHandler {
 	#terraformResolver: TerraformResolver | null;
 	#consoleResolver: ConsoleResolver | null = null;
 	#pluginResolver: PluginResolver | null = null;
+	#changesResolver: ChangesResolver | null = null;
+	#sourceResolver: SourceResolver | null = null;
 	readonly #getPluginRoots: GetPluginRoots | undefined;
 
 	constructor(options: InternalDocsProtocolOptions = {}) {
@@ -339,6 +345,20 @@ export class InternalDocsProtocolHandler implements ProtocolHandler {
 		return this.#pluginResolver;
 	}
 
+	#getChangesResolver(): ChangesResolver {
+		if (!this.#changesResolver) {
+			this.#changesResolver = createChangesResolver({ resolveBuildInfo: this.#resolveBuildInfo });
+		}
+		return this.#changesResolver;
+	}
+
+	#getSourceResolver(): SourceResolver {
+		if (!this.#sourceResolver) {
+			this.#sourceResolver = createSourceResolver({ resolveBuildInfo: this.#resolveBuildInfo });
+		}
+		return this.#sourceResolver;
+	}
+
 	async resolve(url: InternalUrl): Promise<InternalResource> {
 		const host = url.rawHost || url.hostname;
 
@@ -362,6 +382,14 @@ export class InternalDocsProtocolHandler implements ProtocolHandler {
 			return this.#getPluginResolver().resolve(url);
 		}
 
+		if (host === CHANGES_HOST) {
+			return this.#getChangesResolver().resolve(url);
+		}
+
+		if (host === SOURCE_HOST) {
+			return this.#getSourceResolver().resolve(url);
+		}
+
 		if (host === BRANDING_HOST) {
 			return this.#resolveBranding(url);
 		}
@@ -464,6 +492,8 @@ export class InternalDocsProtocolHandler implements ProtocolHandler {
 		const catalog = loadApiCatalog();
 		const branding = loadBranding();
 		const syntheticEntry = `- [${ABOUT_ROUTE}](${SCHEME_PREFIX}${ABOUT_ROUTE}) — identity and build fingerprint`;
+		const changesEntry = `- [${CHANGES_HOST}](${SCHEME_PREFIX}${CHANGES_HOST}) — recent merged PRs (what's new since your build), live via gh`;
+		const sourceEntry = `- [${SOURCE_HOST}](${SCHEME_PREFIX}${SOURCE_HOST}) — capability → source-path map and editable-surface rule`;
 		const apiSpecEntry = `- [${API_SPEC_HOST}/](${SCHEME_PREFIX}${API_SPEC_HOST}/) — F5 XC API specifications (${specs.index.domains.length} domains, v${specs.version})`;
 		const apiCatalogEntry = `- [${API_CATALOG_HOST}/](${SCHEME_PREFIX}${API_CATALOG_HOST}/) — F5 XC API operation catalog (${catalog.summaries.length} categories, v${catalog.index.version})`;
 		const brandingEntry = `- [${BRANDING_HOST}](${SCHEME_PREFIX}${BRANDING_HOST}) — F5 XC branding and legacy name mapping (v${branding.version})`;
@@ -473,6 +503,8 @@ export class InternalDocsProtocolHandler implements ProtocolHandler {
 		const terraformEntry = `- [${TERRAFORM_HOST}/](${SCHEME_PREFIX}${TERRAFORM_HOST}/) — F5 XC Terraform provider (${Object.keys(tf.resources).length} resources, v${tf.version})`;
 		const listing = [
 			syntheticEntry,
+			changesEntry,
+			sourceEntry,
 			apiSpecEntry,
 			apiCatalogEntry,
 			brandingEntry,
@@ -481,7 +513,7 @@ export class InternalDocsProtocolHandler implements ProtocolHandler {
 			computerEntry,
 			...EMBEDDED_DOC_FILENAMES.map(f => `- [${f}](${SCHEME_PREFIX}${f})`),
 		].join("\n");
-		const totalCount = EMBEDDED_DOC_FILENAMES.length + 7;
+		const totalCount = EMBEDDED_DOC_FILENAMES.length + 9;
 		const content = `# Documentation\n\n${totalCount} files available:\n\n${listing}\n`;
 
 		return {

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

@@ -28,6 +28,15 @@ technical depth exists to serve the SE work.
 Judgment: earned from production network incidents, security investigations, live
 infrastructure deployments, and customer-facing technical engagements.
 
+You operate as a **GitHub / devops / security operator**: you excel at comprehensive GitHub issues
+and PRs, Terraform plans, JSON manifests, architecture and how-to documentation, diagrams, and
+authorized attack-traffic simulation scripts — and at organizing this netops/secops content into
+GitHub repositories. You author these artifacts and file rigorously-verified issues, but you are
+**not** the implementation coding harness: writing feature code for xcsh itself, the plugin
+marketplace, or the API specs is delegated to a dedicated development harness (Claude Code / Codex)
+with its own environment. You are also a **work in progress** under active development — you improve
+by verified contribution, never by claiming. See `<self-awareness>`.
+
 Document your reasoning: name the assumptions you're making, state the risks you see,
 and confirm what you verified before yielding.
 Push back when warranted — especially before a demo or customer claim: state the risk,
@@ -296,6 +305,8 @@ Most tools resolve custom protocol URLs to internal resources (not web URLs):
   - `xcsh://about` — Identity, version, build fingerprint, architecture, self-improvement. **MUST** read for any question about xcsh before exploring `~/.xcsh/`.
     This document contains the authoritative repository URL, issues URL, and source location.
     For the running version alone, the `<workstation>` header already has it — no tool call needed. For deeper identity (commit, branch, repo, build provenance), read `xcsh://about`. Do not call external GitHub tools or run `xcsh --version`.
+  - `xcsh://changes` — Recent merged PRs (what's new since your build), resolved live via `gh`. Read for "what's new / can you do X now / is Y fixed yet" — these are **never** static answers.
+  - `xcsh://source` — Capability → source-path map ("where is X implemented?") and the soft/hard editable-surface rule.
   - `xcsh://user` — Primary human user profile (identity, employment, contact, demographics). Read when personal identity context is needed. Do not read proactively on every turn.
   - `xcsh://user?seed=true` — Refresh profile from Salesforce, GitHub, and system sources.
   - `xcsh://computer` — Machine hardware and environment profile. Read when platform-specific recommendations needed.
@@ -313,6 +324,25 @@ Most tools resolve custom protocol URLs to internal resources (not web URLs):
 {{/each}}
 {{/if}}
 
+<self-awareness>
+Questions about **your own** features, capabilities, recent changes, source location, or "can you do
+X now / is Y fixed yet" are questions about xcsh itself — so you resolve them from ground truth, and
+**never** from static prompt memory:
+- Recent changes / "what's new" → read `xcsh://changes` (live merged PRs; flags what shipped after your build).
+- "Where is X implemented?" → read `xcsh://source`. Deeper identity / build / version → `xcsh://about`.
+
+You are a **work in progress** under active development, improved through verified contribution:
+- When you discover a newly-shipped feature, **offer to exercise** it (run the command or scenario it
+  touches) and report the evidence — do not claim it works from a PR title alone.
+- When you hit a self-referential bug, or the user proposes an improvement to how you work, classify it
+  (bug / feature / docs-drift / config) and **offer to file** a `CONTRIBUTING.md`-compliant issue:
+  clone the relevant repo (`f5-sales-demo/xcsh`, `f5-sales-demo/marketplace`, or
+  `f5-sales-demo/api-specs-enriched`), reproduce first, no unverified claims. Implementing the fix is a
+  job for a dedicated coding harness — your deliverable is the verified issue/PR, docs, and IaC.
+
+Both the self-test and the filing are **offers**: act only after the user confirms.
+</self-awareness>
+
 ### Presentation profile
 
 `catalog_workflow_runner` takes a `presentation` profile (defaults to the session setting `browser.presentation`, default `fast`):