@f5-sales-demo/xcsh 19.92.2 → 19.94.0

package/package.json

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

package/src/browser/chat-handler.ts

@@ -10,6 +10,7 @@ import {
 	normalizeHostToolDefinitions,
 	RpcHostToolBridge,
 } from "../host-tools";
+import { extractReferences } from "../references";
 import type { AgentSession, AgentSessionEvent } from "../session/agent-session";
 import {
 	type ChatDelta,
@@ -17,7 +18,6 @@ import {
 	type ChatError,
 	type ChatErrorReason,
 	type ChatKeepalive,
-	type ChatReference,
 	type ChatRequest,
 	type Configure,
 	type ConfigureAck,
@@ -680,39 +680,6 @@ function composeBrowserPageContext(parts: string[], context: PageContextSnapshot
 	parts.push("---");
 }
 
-export function classifyReferenceKind(url: string): "doc" | "console" {
-	try {
-		const parsed = new URL(url);
-		if (/\.console\.ves\.volterra\.io$/.test(parsed.hostname)) return "console";
-		if (parsed.hostname === "docs.cloud.f5.com" || parsed.pathname.startsWith("/docs")) return "doc";
-	} catch {
-		/* malformed URL — default to doc */
-	}
-	return "doc";
-}
-
-function titleFromUrl(url: string): string {
-	try {
-		const parsed = new URL(url);
-		const segments = parsed.pathname.split("/").filter(Boolean);
-		return segments.length > 0 ? segments[segments.length - 1] : parsed.hostname;
-	} catch {
-		return url;
-	}
-}
-
-/**
- * Trailing characters a bare-URL match may greedily swallow at a markdown/prose
- * boundary — markdown emphasis + code (`*_~` and backtick) and sentence/wrap
- * punctuation. A real URL effectively never ends in these, so trimming them yields
- * the intended link (e.g. `**https://…/llms.txt**` or a code-wrapped
- * `` `https://…/llms.txt` `` → `https://…/llms.txt`). The markdown-link branch is
- * bounded by its closing `)` and needs no trimming.
- */
-function trimTrailingMarkup(url: string): string {
-	return url.replace(/[*_~`,.;:!?'")\]}>]+$/, "");
-}
-
 /** Panel-facing labels for provider-side tools, used for the activity rows (#2340). */
 function serverToolLabels(toolName: string): { running: string; done: string } {
 	switch (toolName) {
@@ -724,47 +691,3 @@ function serverToolLabels(toolName: string): { running: string; done: string } {
 			return { running: `${toolName}: running`, done: toolName };
 	}
 }
-
-export function extractReferences(msg: AssistantMessage): ChatReference[] {
-	const refs: ChatReference[] = [];
-	const seen = new Set<string>();
-
-	// STRUCTURED CITATIONS FIRST (#2340): a provider-side search reports the real page title, so
-	// it beats the regex scrape below — which can only guess a title from the URL path, and finds
-	// nothing at all when the model cites a source without printing its URL in the prose. Done as
-	// its own pass so a citation in a later block still wins over a scrape in an earlier one.
-	for (const block of msg.content) {
-		if (block.type !== "text" || !block.citations) continue;
-		for (const citation of block.citations) {
-			const url = citation.url;
-			if (!url || seen.has(url)) continue;
-			seen.add(url);
-			refs.push({
-				kind: classifyReferenceKind(url),
-				title: citation.title?.trim() || titleFromUrl(url),
-				url,
-			});
-		}
-	}
-
-	for (const block of msg.content) {
-		if (block.type !== "text") continue;
-
-		const mdLinkRegex = /\[([^\]]+)\]\((https?:\/\/[^\s)]+)\)/g;
-		for (let match = mdLinkRegex.exec(block.text); match !== null; match = mdLinkRegex.exec(block.text)) {
-			const [, title, url] = match;
-			if (seen.has(url)) continue;
-			seen.add(url);
-			refs.push({ kind: classifyReferenceKind(url), title, url });
-		}
-
-		const bareUrlRegex = /(?<!\()(https?:\/\/[^\s)>\]]+)/g;
-		for (let match = bareUrlRegex.exec(block.text); match !== null; match = bareUrlRegex.exec(block.text)) {
-			const url = trimTrailingMarkup(match[1]);
-			if (seen.has(url)) continue;
-			seen.add(url);
-			refs.push({ kind: classifyReferenceKind(url), title: titleFromUrl(url), url });
-		}
-	}
-	return refs;
-}

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

@@ -220,6 +220,7 @@ export function renderAboutDoc(info: RuntimeBuildInfo, context: ContextStatus |
 		'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`.',
+		"   For the class of the repository you are working in and what you may author there, read `xcsh://fleet`.",
 		"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**.",
@@ -242,10 +243,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.",
+		"You are a network-engineer assistant operating through GitHub, not a coding assistant: your job is",
+		"to author the issue, the reproduction, the Terraform/manifests/scripts/docs, and the PR description.",
+		"Whether **implementing** the change is yours depends on the repository's class — read `xcsh://fleet`.",
+		"xcsh itself is classified `developer`, so feature code here is delegated to a dedicated coding",
+		"harness (Claude Code / Codex) with its own dev environment; the same holds for the other `developer`",
+		"repositories such as `f5-sales-demo/marketplace` and `f5-sales-demo/api-specs-enriched`. In a",
+		"`content` repository you author directly.",
 		"To file well: clone the relevant repo, reproduce the behavior first, and follow `CONTRIBUTING.md` —",
 		"TDD, evidence required, no unverified claims.",
 		"",

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

@@ -17,17 +17,17 @@ export interface BuildInfo {
 }
 
 export const BUILD_INFO: BuildInfo = {
-	"version": "19.92.2",
-	"commit": "5327ac71f0559634bb52145f5c4c61729b22f9ba",
-	"shortCommit": "5327ac7",
+	"version": "19.94.0",
+	"commit": "cdc4c167af67436458be41ca65fbf643ecfcd6b9",
+	"shortCommit": "cdc4c16",
 	"branch": "main",
-	"tag": "v19.92.2",
-	"commitDate": "2026-07-26T02:21:50Z",
-	"buildDate": "2026-07-26T02:49:52.720Z",
+	"tag": "v19.94.0",
+	"commitDate": "2026-07-26T06:18:25Z",
+	"buildDate": "2026-07-26T06:39:31.633Z",
 	"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/5327ac71f0559634bb52145f5c4c61729b22f9ba",
-	"releaseUrl": "https://github.com/f5-sales-demo/xcsh/releases/tag/v19.92.2"
+	"commitUrl": "https://github.com/f5-sales-demo/xcsh/commit/cdc4c167af67436458be41ca65fbf643ecfcd6b9",
+	"releaseUrl": "https://github.com/f5-sales-demo/xcsh/releases/tag/v19.94.0"
 };

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

@@ -0,0 +1,571 @@
+/**
+ * Resolver for xcsh://fleet — "what kind of repository am I in, and what may I do here?"
+ *
+ * xcsh belongs to a fleet of repositories that are not interchangeable. Some hold
+ * demo and product content — documentation, Terraform plans, howtos — which xcsh
+ * authors directly. Some hold compiled code with their own build and test harness,
+ * where implementation belongs in a development environment and xcsh's deliverable
+ * is a verified issue. Some hold the fleet plumbing itself.
+ *
+ * That distinction is declared, not guessed: docs-control publishes `repo_classes`
+ * in `.claude/governance.json`, a managed file synced byte-identically into every
+ * governed repository. So the classification is readable offline from any checkout,
+ * and this resolver reads it from the working directory before reaching for the
+ * network.
+ *
+ * URL forms (host = "fleet"):
+ * - xcsh://fleet   -> the current repository's class first, then the whole fleet
+ *
+ * Dynamic and uncached, mirroring xcsh://about. All shelling and file reading is
+ * injected so the resolver is unit-testable without a git repo, a `gh` binary, or
+ * a network.
+ */
+
+import path from "node:path";
+import { $ } from "bun";
+import type { InternalResource, InternalUrl } from "./types";
+
+export interface GhResult {
+	readonly ok: boolean;
+	readonly stdout: string;
+	readonly stderr: string;
+}
+
+export interface FleetDeps {
+	readonly cwd: () => string;
+	/** Absolute path to the enclosing git repository root, or null when outside one. */
+	readonly repoRoot: (cwd: string) => Promise<string | null>;
+	/** The `origin` remote URL, or null when there is none. */
+	readonly repoOrigin: (cwd: string) => Promise<string | null>;
+	/** Contents of `<repoRoot>/.claude/governance.json`, or null when absent/unreadable. */
+	readonly readGovernance: (repoRoot: string) => Promise<string | null>;
+	readonly runGh: (args: string[]) => Promise<GhResult>;
+}
+
+/** The repository the classification manifest is published from. */
+export const GOVERNANCE_REPO = "f5-sales-demo/docs-control";
+export const GOVERNANCE_RELPATH = ".claude/governance.json";
+
+/**
+ * The organization's pre-rename name. Reads still redirect from it, but pushes are
+ * rejected, so a clone left on the old slug looks healthy until the first push
+ * fails. Classification keys are bare repository names, so the org does not affect
+ * the lookup — but it is worth warning about where we notice it.
+ */
+export const LEGACY_ORG = "f5xc-salesdemos";
+export const CURRENT_ORG = "f5-sales-demo";
+
+/** Authority values the manifest may declare for a class. */
+export const AUTHORITY_AUTHOR = "author";
+export const AUTHORITY_DELEGATE = "delegate";
+export const AUTHORITY_GOVERNED = "governed";
+
+/** Rendered class name when no manifest could be read at all. */
+export const CLASS_UNCLASSIFIED = "UNCLASSIFIED";
+
+export interface ClassDefinition {
+	readonly authority: string;
+	readonly description?: string;
+	readonly surfaces?: readonly string[];
+	readonly delegateTo?: string;
+}
+
+export interface RepoClasses {
+	/** `source_repo` from the governance manifest — the repository that published it. */
+	readonly sourceRepo: string;
+	readonly defaultClass: string;
+	readonly classes: Readonly<Record<string, ClassDefinition>>;
+	readonly repos: Readonly<Record<string, string>>;
+}
+
+export interface RepoVerdict {
+	readonly className: string;
+	/** True when the manifest names this repository explicitly. */
+	readonly declared: boolean;
+	/** False when the remote is outside this organization, so no class may be applied. */
+	readonly trustedOrg: boolean;
+	readonly definition: ClassDefinition | null;
+}
+
+/** A repository's identity as read from its `origin` remote. */
+export interface RepoIdentity {
+	readonly org: string;
+	readonly name: string;
+}
+
+/** Organizations whose repository names the manifest is allowed to speak for. */
+export const TRUSTED_ORGS: readonly string[] = [CURRENT_ORG, LEGACY_ORG];
+
+/**
+ * Read `repo_classes` out of a governance.json payload. Returns null — never throws —
+ * when the payload is malformed or predates the block, so a missing classification
+ * degrades into an actionable message rather than an error.
+ */
+export function parseRepoClasses(json: string): RepoClasses | null {
+	let parsed: unknown;
+	try {
+		parsed = JSON.parse(json);
+	} catch {
+		return null;
+	}
+	if (typeof parsed !== "object" || parsed === null) return null;
+	const block = (parsed as Record<string, unknown>).repo_classes;
+	if (typeof block !== "object" || block === null) return null;
+
+	const raw = block as Record<string, unknown>;
+	const rawClasses = typeof raw.classes === "object" && raw.classes !== null ? raw.classes : {};
+	const rawRepos = typeof raw.repos === "object" && raw.repos !== null ? raw.repos : {};
+
+	const classes: Record<string, ClassDefinition> = {};
+	for (const [name, value] of Object.entries(rawClasses as Record<string, unknown>)) {
+		if (typeof value !== "object" || value === null) continue;
+		const def = value as Record<string, unknown>;
+		classes[name] = {
+			authority: String(def.authority ?? ""),
+			description: typeof def.description === "string" ? def.description : undefined,
+			surfaces: Array.isArray(def.surfaces) ? def.surfaces.map(String) : undefined,
+			delegateTo: typeof def.delegate_to === "string" ? def.delegate_to : undefined,
+		};
+	}
+
+	const repos: Record<string, string> = {};
+	for (const [name, value] of Object.entries(rawRepos as Record<string, unknown>)) {
+		if (typeof value === "string") repos[name] = value;
+	}
+
+	// A block with no classes is unusable; treat it as absent rather than render an
+	// empty fleet that looks authoritative.
+	if (Object.keys(classes).length === 0) return null;
+
+	const sourceRepo =
+		typeof (parsed as Record<string, unknown>).source_repo === "string"
+			? ((parsed as Record<string, unknown>).source_repo as string)
+			: "";
+
+	return {
+		sourceRepo,
+		defaultClass: typeof raw._default === "string" ? raw._default : "",
+		classes,
+		repos,
+	};
+}
+
+/** Minimal shape of the session event bus, so this module does not depend on it. */
+export interface CwdEventSource {
+	on(event: "cwd:changed", handler: (next: unknown) => void): unknown;
+}
+
+/**
+ * A getter for the working directory the *session* is in, not the one the process
+ * started in.
+ *
+ * The bash tool keeps its own cwd and updates it on `cd`, emitting `cwd:changed`
+ * (`tools/bash.ts`); `process.chdir` is never called for it. Classifying against
+ * `process.cwd()` would therefore keep reporting the startup repository, so a
+ * `content` grant could survive after moving into a `developer` repository.
+ */
+export function createLiveCwdGetter(initialCwd: string, events?: CwdEventSource): () => string {
+	let current = initialCwd;
+	events?.on("cwd:changed", next => {
+		if (typeof next === "string" && next) current = next;
+	});
+	return () => current;
+}
+
+/** Split a GitHub remote URL into its org and bare repository name. */
+export function repoNameFromOrigin(origin: string): { org: string; name: string } | null {
+	const cleaned = origin.trim().replace(/\.git$/, "");
+	const match = cleaned.match(/^(?:https?:\/\/|ssh:\/\/git@|git@)github\.com[:/]([^/]+)\/([^/]+)$/);
+	if (!match) return null;
+	const [, org, name] = match;
+	if (!org || !name) return null;
+	return { org, name };
+}
+
+/**
+ * Resolve a repository name to its class. An unlisted repository takes the
+ * manifest's `_default`, which docs-control pins to the most restrictive class, so
+ * forgetting an assignment withholds authority rather than granting it.
+ */
+export function classifyRepo(classes: RepoClasses | null, repo: RepoIdentity | null): RepoVerdict {
+	const trustedOrg = repo !== null && TRUSTED_ORGS.includes(repo.org);
+	if (!classes || !repo || !trustedOrg) {
+		// The manifest keys repositories by bare name, so an identically-named repository
+		// in another organization would otherwise inherit its class. Names are only
+		// meaningful inside the organization that published the manifest.
+		return { className: CLASS_UNCLASSIFIED, declared: false, trustedOrg, definition: null };
+	}
+	const declared = Object.hasOwn(classes.repos, repo.name);
+	const className = declared ? (classes.repos[repo.name] as string) : classes.defaultClass;
+	const definition = classes.classes[className] ?? null;
+
+	// Fail closed on our own side. Both the prompt and this document promise that an
+	// unnamed repository is treated as the restrictive case, and that promise must not
+	// depend on the publisher having set `_default` correctly: a typo or drift making the
+	// default an authoring class would otherwise hand out write authority to every
+	// repository nobody has classified yet. A named assignment is honoured as written;
+	// an unnamed one can never resolve to `author`.
+	if (!declared && definition?.authority === AUTHORITY_AUTHOR) {
+		return {
+			className: className || CLASS_UNCLASSIFIED,
+			declared,
+			trustedOrg,
+			definition: { ...definition, authority: AUTHORITY_DELEGATE },
+		};
+	}
+
+	return { className: className || CLASS_UNCLASSIFIED, declared, trustedOrg, definition };
+}
+
+/** The behaviour each authority implies, stated so the agent does not have to infer it. */
+function authorityGuidance(authority: string): string[] {
+	switch (authority) {
+		case AUTHORITY_AUTHOR:
+			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`.",
+			];
+		case AUTHORITY_DELEGATE:
+			return [
+				"**Authority: delegate.** This repository holds compiled or tested code with its own build",
+				"and test harness. Do not implement feature code here. File a CONTRIBUTING-compliant issue —",
+				"reproduce first, no unverified claims — and delegate the implementation to a development",
+				"environment (Claude Code / Codex). Reviewing, specifying and documenting are still yours.",
+			];
+		case AUTHORITY_GOVERNED:
+			return [
+				"**Authority: governed.** This is fleet plumbing: CI, packaging, container images, or",
+				"governance itself. Changes propagate to every repository, so they go through the governed",
+				"path only and are never made freehand.",
+			];
+		default:
+			return [
+				"**Authority: unknown.** The manifest does not declare an authority for this class.",
+				"Treat it as `delegate` — the restrictive case — and ask docs-control to fix the manifest.",
+			];
+	}
+}
+
+function renderCurrentRepo(
+	slug: string | null,
+	identity: RepoIdentity | null,
+	verdict: RepoVerdict,
+	classes: RepoClasses | null,
+	legacyOrg: boolean,
+): string[] {
+	const lines = ["## This repository", ""];
+
+	if (!slug) {
+		lines.push(
+			"Not inside a GitHub repository from this organization, so there is no class to apply.",
+			"Classify explicitly before authoring anything: read this document again from the repository",
+			"you intend to change.",
+			"",
+		);
+		return lines;
+	}
+
+	lines.push(`\`${slug}\` — class: **${verdict.className}**${verdict.declared ? " (declared)" : ""}`);
+	lines.push("");
+
+	if (!verdict.trustedOrg) {
+		lines.push(
+			`This remote is **outside \`${CURRENT_ORG}\`**, so the classification does not speak for it and`,
+			"**no authority is implied**. The manifest keys repositories by bare name, and a name only means",
+			"something inside the organization that published it — an identically-named repository elsewhere",
+			"is a different repository. Treat this as the restrictive case: do not author content here.",
+			"",
+		);
+		return lines;
+	}
+
+	if (verdict.className === CLASS_UNCLASSIFIED) {
+		lines.push(
+			"No classification manifest was available, so **no authority is implied**. Do not author",
+			"content here on the strength of a guess.",
+			"",
+		);
+		return lines;
+	}
+
+	if (!verdict.declared) {
+		lines.push(
+			`This repository is **UNCLASSIFIED** — it is not named in the manifest, so it falls back to`,
+			`the fail-safe default (\`${classes?.defaultClass || "developer"}\`) and is treated as the most`,
+			"restrictive case. Ask docs-control to classify it rather than assuming authoring rights.",
+			"",
+		);
+	}
+
+	lines.push(...authorityGuidance(verdict.definition?.authority ?? ""));
+	lines.push("");
+
+	if (verdict.definition?.surfaces?.length) {
+		lines.push(`Content surfaces: ${verdict.definition.surfaces.map(s => `\`${s}\``).join(", ")}`, "");
+	}
+
+	if (legacyOrg) {
+		lines.push(
+			`> **This clone points at the pre-rename organization \`${LEGACY_ORG}\`.** Reads redirect, but`,
+			"> **pushes are rejected**, so the branch will look fine until you try to publish it. Fix it first:",
+			">",
+			"> ```",
+			`> git remote set-url origin https://github.com/${CURRENT_ORG}/${identity?.name ?? ""}.git`,
+			"> ```",
+			"",
+		);
+	}
+
+	return lines;
+}
+
+function renderFleet(classes: RepoClasses): string[] {
+	const byClass = new Map<string, string[]>();
+	for (const name of Object.keys(classes.classes)) byClass.set(name, []);
+	for (const [repo, className] of Object.entries(classes.repos)) {
+		if (!byClass.has(className)) byClass.set(className, []);
+		byClass.get(className)?.push(repo);
+	}
+
+	const lines = ["## Fleet", ""];
+	for (const [className, repos] of byClass) {
+		const def = classes.classes[className];
+		lines.push(`### ${className} (${repos.length}) — authority: ${def?.authority ?? "unknown"}`);
+		if (def?.description) lines.push("", def.description);
+		lines.push(
+			"",
+			repos.length > 0
+				? repos
+						.sort()
+						.map(r => `\`${r}\``)
+						.join(" ")
+				: "_none_",
+			"",
+		);
+	}
+
+	lines.push(
+		"Any repository not listed above is **UNCLASSIFIED**. It is never granted authoring",
+		"authority no matter what the manifest's default says — an unnamed repository is always",
+		"treated as `delegate`, the restrictive case. Authority is never assumed from a",
+		"repository's contents; it is read from the manifest.",
+		"",
+	);
+	return lines;
+}
+
+/** Rendered when no manifest could be read — actionable, never a thrown error. */
+function renderUnavailable(reason: string, slug: string | null): string {
+	return [
+		"# Fleet — classification unavailable",
+		"",
+		reason,
+		"",
+		"Until the classification is readable, **do not assume authority over any repository**: file an",
+		"issue and delegate rather than authoring content on a guess.",
+		"",
+		"Resolve it manually:",
+		"",
+		"```",
+		`gh api repos/${GOVERNANCE_REPO}/contents/${GOVERNANCE_RELPATH} --jq '.content' | base64 -d | jq .repo_classes`,
+		"```",
+		"",
+		`Or read \`${GOVERNANCE_RELPATH}\` in any governed checkout — the file is synced byte-identically`,
+		"across the fleet.",
+		"",
+		slug ? `Current repository: \`${slug}\`.` : "Not inside a GitHub repository from this organization.",
+	].join("\n");
+}
+
+const FOOTER = [
+	"---",
+	"This classification decides *how* you contribute, not *whether* you do. In a `content`",
+	"repository, author directly through the governed path. In a `developer` repository, your",
+	"deliverable is a verified issue plus the specification, review and documentation around it —",
+	"the implementation belongs to a development environment. See `xcsh://source` for where xcsh's",
+	"own code lives and `xcsh://changes` for what shipped recently.",
+];
+
+/** Where this verdict's manifest came from, so the reader can judge how fresh it is. */
+export type ManifestOrigin = "local" | "canonical";
+
+function renderProvenance(origin: ManifestOrigin, classes: RepoClasses): string[] {
+	if (origin === "canonical") {
+		return [`_Classification read live from \`${GOVERNANCE_REPO}\`._`, ""];
+	}
+	return [
+		`_Classification read from this checkout's \`${GOVERNANCE_RELPATH}\`, published by`,
+		`\`${classes.sourceRepo}\`. It is synced fleet-wide, but a checkout that has not pulled`,
+		"recently can lag the canonical copy. If a verdict looks wrong, confirm it before acting:_",
+		"",
+		"```",
+		`gh api repos/${GOVERNANCE_REPO}/contents/${GOVERNANCE_RELPATH} --jq '.content' | base64 -d | jq .repo_classes.repos`,
+		"```",
+		"",
+	];
+}
+
+export function renderFleetDoc(
+	slug: string | null,
+	identity: RepoIdentity | null,
+	verdict: RepoVerdict,
+	classes: RepoClasses,
+	legacyOrg: boolean,
+	origin: ManifestOrigin = "local",
+): string {
+	return [
+		"# Fleet — repository classes and your authority here",
+		"",
+		...renderCurrentRepo(slug, identity, verdict, classes, legacyOrg),
+		...renderFleet(classes),
+		...renderProvenance(origin, classes),
+		...FOOTER,
+	].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 FleetResolver {
+	readonly #deps: FleetDeps;
+
+	constructor(deps: FleetDeps) {
+		this.#deps = deps;
+	}
+
+	async resolve(url: InternalUrl): Promise<InternalResource> {
+		const content = await this.#render();
+		return {
+			url: url.href,
+			content,
+			contentType: "text/markdown",
+			size: Buffer.byteLength(content, "utf-8"),
+			sourcePath: "xcsh://fleet",
+		};
+	}
+
+	async #render(): Promise<string> {
+		const cwd = this.#deps.cwd();
+		const root = await this.#deps.repoRoot(cwd);
+
+		let slug: string | null = null;
+		let identity: RepoIdentity | null = null;
+		let legacyOrg = false;
+		if (root) {
+			const origin = await this.#deps.repoOrigin(root);
+			const parsed = origin ? repoNameFromOrigin(origin) : null;
+			if (parsed) {
+				slug = `${parsed.org}/${parsed.name}`;
+				identity = parsed;
+				legacyOrg = parsed.org === LEGACY_ORG;
+			}
+		}
+
+		// Prefer the local, offline copy: it is byte-identical to the published one
+		// across the whole governed fleet, so there is no reason to spend a network
+		// round trip when we are standing in a governed repository.
+		let classes: RepoClasses | null = null;
+		let origin: ManifestOrigin = "local";
+		let staleLocal = false;
+		let untrustedLocal = false;
+		if (root) {
+			const local = await this.#deps.readGovernance(root);
+			if (local !== null) {
+				const parsedLocal = parseRepoClasses(local);
+				if (parsedLocal && parsedLocal.sourceRepo !== GOVERNANCE_REPO) {
+					// A governance.json that names a different publisher is not the fleet's
+					// manifest — it may belong to an unrelated project or a fork. Ignore it
+					// and ask the canonical repository instead of trusting what is on disk.
+					untrustedLocal = true;
+				} else {
+					classes = parsedLocal;
+					staleLocal = parsedLocal === null;
+				}
+			}
+		}
+
+		if (!classes) {
+			const remote = await this.#deps.runGh([
+				"api",
+				`repos/${GOVERNANCE_REPO}/contents/${GOVERNANCE_RELPATH}`,
+				"--jq",
+				".content",
+			]);
+			if (remote.ok && remote.stdout.trim()) {
+				const decoded = decodeMaybeBase64(remote.stdout.trim());
+				classes = parseRepoClasses(decoded);
+				if (classes) origin = "canonical";
+			}
+		}
+
+		if (!classes) {
+			let reason: string;
+			if (untrustedLocal) {
+				reason =
+					`This checkout's \`${GOVERNANCE_RELPATH}\` is published by a different repository, not ` +
+					`\`${GOVERNANCE_REPO}\`, so it was not trusted — and querying \`${GOVERNANCE_REPO}\` did not succeed.`;
+			} else if (staleLocal) {
+				reason =
+					`This checkout's \`${GOVERNANCE_RELPATH}\` has no \`repo_classes\` block — the classification ` +
+					`is not yet published to this repository, and querying \`${GOVERNANCE_REPO}\` did not succeed either.`;
+			} else {
+				reason = `No \`${GOVERNANCE_RELPATH}\` was readable here, and querying \`${GOVERNANCE_REPO}\` did not succeed.`;
+			}
+			return renderUnavailable(reason, slug);
+		}
+
+		return renderFleetDoc(slug, identity, classifyRepo(classes, identity), classes, legacyOrg, origin);
+	}
+}
+
+/**
+ * `gh api --jq .content` returns the base64 payload of a contents response. Accept
+ * either that or already-decoded JSON, so the caller does not have to care which
+ * form it got.
+ */
+function decodeMaybeBase64(raw: string): string {
+	if (raw.startsWith("{")) return raw;
+	try {
+		return Buffer.from(raw.replace(/\s+/g, ""), "base64").toString("utf-8");
+	} catch {
+		return raw;
+	}
+}
+
+async function defaultRepoRoot(cwd: string): Promise<string | null> {
+	const git = await import("../utils/git");
+	return git.repo.root(cwd);
+}
+
+async function defaultRepoOrigin(cwd: string): Promise<string | null> {
+	const git = await import("../utils/git");
+	return (await git.remote.url(cwd, "origin")) ?? null;
+}
+
+async function defaultReadGovernance(repoRoot: string): Promise<string | null> {
+	try {
+		const file = Bun.file(path.join(repoRoot, GOVERNANCE_RELPATH));
+		if (!(await file.exists())) return null;
+		return await file.text();
+	} catch {
+		return null;
+	}
+}
+
+export function createFleetResolver(deps: Partial<FleetDeps> = {}): FleetResolver {
+	return new FleetResolver({
+		cwd: deps.cwd ?? (() => process.cwd()),
+		repoRoot: deps.repoRoot ?? defaultRepoRoot,
+		repoOrigin: deps.repoOrigin ?? defaultRepoOrigin,
+		readGovernance: deps.readGovernance ?? defaultReadGovernance,
+		runGh: deps.runGh ?? defaultRunGh,
+	});
+}

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

@@ -148,6 +148,22 @@ export const TERRAFORM_INDEX: TerraformIndex = {
 				"workload_flavor",
 			],
 		},
+		{
+			name: "Uncategorized",
+			slug: "uncategorized",
+			description: "Resources pending categorization",
+			resource_count: 8,
+			resources: [
+				"application_profiles",
+				"authorization_server",
+				"bot_infrastructure",
+				"domain",
+				"mitigated_domain",
+				"protected_application",
+				"protected_domain",
+				"registration_approval",
+			],
+		},
 		{
 			name: "DNS",
 			slug: "dns",
@@ -163,21 +179,6 @@ export const TERRAFORM_INDEX: TerraformIndex = {
 				"dns_zone",
 			],
 		},
-		{
-			name: "Uncategorized",
-			slug: "uncategorized",
-			description: "Resources pending categorization",
-			resource_count: 7,
-			resources: [
-				"application_profiles",
-				"authorization_server",
-				"bot_infrastructure",
-				"mitigated_domain",
-				"protected_application",
-				"protected_domain",
-				"registration_approval",
-			],
-		},
 		{
 			name: "API Security",
 			slug: "api-security",
@@ -185,13 +186,6 @@ export const TERRAFORM_INDEX: TerraformIndex = {
 			resource_count: 5,
 			resources: ["api_crawler", "api_definition", "api_discovery", "api_testing", "app_api_group"],
 		},
-		{
-			name: "Monitoring",
-			slug: "monitoring",
-			description: "Log receivers, alert policies, APM, and global logging configuration",
-			resource_count: 5,
-			resources: ["alert_receiver", "alert_template", "apm", "global_log_receiver", "log_receiver"],
-		},
 		{
 			name: "Applications",
 			slug: "applications",
@@ -213,6 +207,13 @@ export const TERRAFORM_INDEX: TerraformIndex = {
 			resource_count: 4,
 			resources: ["certificate", "certificate_chain", "crl", "trusted_ca_list"],
 		},
+		{
+			name: "Monitoring",
+			slug: "monitoring",
+			description: "Log receivers, alert policies, APM, and global logging configuration",
+			resource_count: 4,
+			resources: ["alert_receiver", "alert_template", "global_log_receiver", "log_receiver"],
+		},
 		{
 			name: "VPN",
 			slug: "vpn",
@@ -386,16 +387,6 @@ export const TERRAFORM_INDEX: TerraformIndex = {
 			},
 			import_syntax: "terraform import xcsh_api_testing.example namespace/name",
 		},
-		apm: {
-			category: "monitoring",
-			description: "New APM as a service with configured parameters",
-			required: ["name", "namespace"],
-			minimal_config: 'resource "xcsh_apm" "example" {\n  name      = "example-apm"\n  namespace = "staging"\n}',
-			dependencies: {
-				requires: [],
-			},
-			import_syntax: "terraform import xcsh_apm.example namespace/name",
-		},
 		app_api_group: {
 			category: "api-security",
 			description: "App_api_group creates a new object in the storage backend for metadata.namespace",
@@ -531,7 +522,7 @@ export const TERRAFORM_INDEX: TerraformIndex = {
 		bgp_routing_policy: {
 			category: "security",
 			description:
-				"Bgp routing policy is a list of rules containing match criteria and action to be applied. these rules help contol routes which are imported or exported to bgp peers. configuration",
+				"Bgp routing policy is a list of rules containing match criteria and action to be applied. these rules help control routes which are imported or exported to bgp peers. configuration",
 			required: ["name", "namespace"],
 			minimal_config:
 				'resource "xcsh_bgp_routing_policy" "example" {\n  name      = "example-bgp-routing-policy"\n  namespace = "staging"\n}',
@@ -857,6 +848,17 @@ export const TERRAFORM_INDEX: TerraformIndex = {
 			},
 			import_syntax: "terraform import xcsh_dns_zone.example namespace/name",
 		},
+		domain: {
+			category: "uncategorized",
+			description: "Allowed domain",
+			required: ["name", "namespace", "allowed_domain"],
+			minimal_config:
+				'resource "xcsh_domain" "example" {\n  name      = "example-domain"\n  namespace = "staging"\n\n  allowed_domain = "example-value"\n}',
+			dependencies: {
+				requires: [],
+			},
+			import_syntax: "terraform import xcsh_domain.example namespace/name",
+		},
 		endpoint: {
 			category: "load-balancing",
 			description: "Endpoint will create the object in the storage backend for namespace metadata.namespace",
@@ -1636,9 +1638,9 @@ export const TERRAFORM_INDEX: TerraformIndex = {
 		udp_loadbalancer: {
 			category: "load-balancing",
 			description: "Load balancing UDP traffic across origin pools",
-			required: ["name", "namespace", "dns_volterra_managed", "enable_per_packet_load_balancing", "idle_timeout"],
+			required: ["name", "namespace", "dns_volterra_managed", "idle_timeout"],
 			minimal_config:
-				'resource "xcsh_udp_loadbalancer" "example" {\n  name      = "example-udp-loadbalancer"\n  namespace = "staging"\n\n  domains                          = ["example-value"]\n  dns_volterra_managed             = true\n  enable_per_packet_load_balancing = true\n  idle_timeout                     = 1\n}',
+				'resource "xcsh_udp_loadbalancer" "example" {\n  name      = "example-udp-loadbalancer"\n  namespace = "staging"\n\n  domains              = ["example-value"]\n  dns_volterra_managed = true\n  idle_timeout         = 1\n}',
 			dependencies: {
 				requires: ["namespace", "origin_pool"],
 			},

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

@@ -45,6 +45,7 @@ import { type ConsoleFieldMetadataData, EMPTY_CONSOLE_FIELD_METADATA } from "./c
 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 { createFleetResolver, type FleetDeps, type FleetResolver } from "./fleet-resolve";
 import { createPluginResolver, type GetPluginRoots, type PluginResolver } from "./plugin-resolve";
 import { createSourceResolver, type SourceResolver } from "./source-resolve";
 import { createTerraformResolver, type TerraformResolver } from "./terraform-resolve";
@@ -66,6 +67,7 @@ const EXTENSION_HOST = "extension";
 const PLUGIN_HOST = "plugin";
 const CHANGES_HOST = "changes";
 const SOURCE_HOST = "source";
+const FLEET_HOST = "fleet";
 const EMPTY_INDEX: ApiSpecIndex = { version: "unavailable", timestamp: "", domains: [] };
 const EMPTY_CATALOG_INDEX: ApiCatalogIndex = {
 	version: "unavailable",
@@ -272,6 +274,8 @@ export interface InternalDocsProtocolOptions {
 	readonly apiSpecResolver?: ApiSpecResolver;
 	readonly apiCatalogResolver?: ApiCatalogResolver;
 	readonly getPluginRoots?: GetPluginRoots;
+	/** Injected so tests can classify without a git repo, a `gh` binary, or a network. */
+	readonly fleetDeps?: Partial<FleetDeps>;
 }
 
 export class InternalDocsProtocolHandler implements ProtocolHandler {
@@ -285,6 +289,8 @@ export class InternalDocsProtocolHandler implements ProtocolHandler {
 	#pluginResolver: PluginResolver | null = null;
 	#changesResolver: ChangesResolver | null = null;
 	#sourceResolver: SourceResolver | null = null;
+	#fleetResolver: FleetResolver | null = null;
+	readonly #fleetDeps: Partial<FleetDeps> | undefined;
 	readonly #getPluginRoots: GetPluginRoots | undefined;
 
 	constructor(options: InternalDocsProtocolOptions = {}) {
@@ -294,6 +300,7 @@ export class InternalDocsProtocolHandler implements ProtocolHandler {
 		this.#apiCatalogResolver = options.apiCatalogResolver ?? null;
 		this.#terraformResolver = null;
 		this.#getPluginRoots = options.getPluginRoots;
+		this.#fleetDeps = options.fleetDeps;
 	}
 
 	#getApiSpecResolver(): ApiSpecResolver {
@@ -352,6 +359,13 @@ export class InternalDocsProtocolHandler implements ProtocolHandler {
 		return this.#changesResolver;
 	}
 
+	#getFleetResolver(): FleetResolver {
+		if (!this.#fleetResolver) {
+			this.#fleetResolver = createFleetResolver(this.#fleetDeps ?? {});
+		}
+		return this.#fleetResolver;
+	}
+
 	#getSourceResolver(): SourceResolver {
 		if (!this.#sourceResolver) {
 			this.#sourceResolver = createSourceResolver({ resolveBuildInfo: this.#resolveBuildInfo });
@@ -390,6 +404,10 @@ export class InternalDocsProtocolHandler implements ProtocolHandler {
 			return this.#getSourceResolver().resolve(url);
 		}
 
+		if (host === FLEET_HOST) {
+			return this.#getFleetResolver().resolve(url);
+		}
+
 		if (host === BRANDING_HOST) {
 			return this.#resolveBranding(url);
 		}
@@ -494,6 +512,7 @@ export class InternalDocsProtocolHandler implements ProtocolHandler {
 		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 fleetEntry = `- [${FLEET_HOST}](${SCHEME_PREFIX}${FLEET_HOST}) — this repository's class and what you may author here`;
 		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})`;
@@ -501,10 +520,11 @@ export class InternalDocsProtocolHandler implements ProtocolHandler {
 		const computerEntry = `- [${COMPUTER_ROUTE}](${SCHEME_PREFIX}${COMPUTER_ROUTE}) — machine hardware and environment profile`;
 		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 listing = [
+		const entries = [
 			syntheticEntry,
 			changesEntry,
 			sourceEntry,
+			fleetEntry,
 			apiSpecEntry,
 			apiCatalogEntry,
 			brandingEntry,
@@ -512,9 +532,12 @@ export class InternalDocsProtocolHandler implements ProtocolHandler {
 			userEntry,
 			computerEntry,
 			...EMBEDDED_DOC_FILENAMES.map(f => `- [${f}](${SCHEME_PREFIX}${f})`),
-		].join("\n");
-		const totalCount = EMBEDDED_DOC_FILENAMES.length + 9;
-		const content = `# Documentation\n\n${totalCount} files available:\n\n${listing}\n`;
+		];
+		// Derived, not hand-maintained: the advertised count used to be a magic
+		// offset that no test pinned, so adding a route silently produced a wrong
+		// header. Counting the entries we actually list cannot drift.
+		const listing = entries.join("\n");
+		const content = `# Documentation\n\n${entries.length} files available:\n\n${listing}\n`;
 
 		return {
 			url: url.href,

package/src/modes/rpc/rpc-mode.ts

@@ -24,6 +24,7 @@ import {
 	RpcHostToolBridge,
 } from "../../host-tools";
 import { type Theme, theme } from "../../modes/theme/theme";
+import { referencesEventFor } from "../../references";
 import type { AgentSession } from "../../session/agent-session";
 import { mapContextStatus, runWelcomeChecks } from "../components/welcome-checks";
 import type {
@@ -497,6 +498,11 @@ export async function runRpcMode(session: AgentSession): Promise<never> {
 	// Output all agent events as JSON
 	session.subscribe(event => {
 		output(event);
+		// Citations for the host's Sources chips, mirroring `chat_done.references` on
+		// the WS bridge. The turn-boundary rule (an intermediate tool-use step also
+		// emits message_end) lives in the shared, tested `referencesEventFor` (#2420).
+		const refs = referencesEventFor(event);
+		if (refs) output(refs);
 	});
 
 	// Handle a single command

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

@@ -28,14 +28,26 @@ 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>`.
+You are tuned as a **network-engineer assistant, not a coding assistant**. Your competence is
+networking, security and cloud operations expressed through GitHub: comprehensive issues and PRs,
+Terraform plans, JSON manifests, architecture and how-to documentation, diagrams, MEDDPICC and
+account collateral, presentations, and authorized attack-traffic simulation scripts — and organizing
+that netops/secops content into GitHub repositories. Your operational reach spans cloud-provider
+CLIs, document and spreadsheet authoring, browser-driven F5 XC console automation, GitHub, and
+CRM/pipeline data; the specific capabilities available in this session are the tools and installed
+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,
+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**.
+
+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.
@@ -301,6 +313,7 @@ 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
+- `xcsh://fleet` — The class of the repository you are working in and what you may author there. **MUST** read before creating, updating, or deleting content in any repository of this organization — this is about the *current repository*, not about xcsh, so the gate on the other `xcsh://` documents does not apply.
 - `xcsh://..` — Internal xcsh documentation. **MUST NOT** read unless the user asks about xcsh itself.
   - `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.
@@ -331,6 +344,19 @@ X now / is Y fixed yet" are questions about xcsh itself — so you resolve them
 - 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`.
 
+Which repository you are in also decides what you may do there, and it is **declared, not inferred
+from the contents**. Before you create, update, or delete content in any repository of this
+organization, read `xcsh://fleet` and act on its verdict:
+- **content** → author directly. You do not need permission to write documentation, Terraform,
+  howtos, diagrams or demo scripts here; you do need the governed path — linked issue → branch →
+  pull request → CI → auto-merge, never a commit to `main`.
+- **developer** → do not implement feature code. File a CONTRIBUTING-compliant issue (reproduce
+  first, no unverified claims) and delegate the implementation to a dedicated coding harness.
+  Specifying, reviewing and documenting remain yours.
+- **scaffolding** → governed path only; these changes propagate fleet-wide.
+- **unclassified** → treat as **developer**, the restrictive case, and say the repository needs
+  classifying. Never infer authoring rights from the fact that a repository contains documentation.
+
 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.

package/src/references.ts

@@ -0,0 +1,116 @@
+/**
+ * Citation extraction — the "Sources" chips a surface shows under an answer.
+ *
+ * Neutral module ON PURPOSE. This used to live in `browser/chat-handler.ts`, whose
+ * 14 imports would have dragged the whole browser chat stack into the RPC path when
+ * `rpc-mode` needed the same extraction (#2420). One extractor, and one rule for
+ * "which assistant message ends a turn", shared by every transport — a client
+ * reimplementing either would drift (see the #2249 trailing-markup regression).
+ */
+import type { AssistantMessage } from "@f5-sales-demo/pi-ai";
+import type { ChatReference } from "./browser/chat-protocol";
+
+export function classifyReferenceKind(url: string): "doc" | "console" {
+	try {
+		const parsed = new URL(url);
+		if (/\.console\.ves\.volterra\.io$/.test(parsed.hostname)) return "console";
+		if (parsed.hostname === "docs.cloud.f5.com" || parsed.pathname.startsWith("/docs")) return "doc";
+	} catch {
+		/* malformed URL — default to doc */
+	}
+	return "doc";
+}
+function titleFromUrl(url: string): string {
+	try {
+		const parsed = new URL(url);
+		const segments = parsed.pathname.split("/").filter(Boolean);
+		return segments.length > 0 ? segments[segments.length - 1] : parsed.hostname;
+	} catch {
+		return url;
+	}
+}
+/**
+ * Trailing characters a bare-URL match may greedily swallow at a markdown/prose
+ * boundary — markdown emphasis + code (`*_~` and backtick) and sentence/wrap
+ * punctuation. A real URL effectively never ends in these, so trimming them yields
+ * the intended link (e.g. `**https://…/llms.txt**` or a code-wrapped
+ * `` `https://…/llms.txt` `` → `https://…/llms.txt`). The markdown-link branch is
+ * bounded by its closing `)` and needs no trimming.
+ */
+function trimTrailingMarkup(url: string): string {
+	return url.replace(/[*_~`,.;:!?'")\]}>]+$/, "");
+}
+export function extractReferences(msg: AssistantMessage): ChatReference[] {
+	const refs: ChatReference[] = [];
+	const seen = new Set<string>();
+
+	// STRUCTURED CITATIONS FIRST (#2340): a provider-side search reports the real page title, so
+	// it beats the regex scrape below — which can only guess a title from the URL path, and finds
+	// nothing at all when the model cites a source without printing its URL in the prose. Done as
+	// its own pass so a citation in a later block still wins over a scrape in an earlier one.
+	for (const block of msg.content) {
+		if (block.type !== "text" || !block.citations) continue;
+		for (const citation of block.citations) {
+			const url = citation.url;
+			if (!url || seen.has(url)) continue;
+			seen.add(url);
+			refs.push({
+				kind: classifyReferenceKind(url),
+				title: citation.title?.trim() || titleFromUrl(url),
+				url,
+			});
+		}
+	}
+
+	for (const block of msg.content) {
+		if (block.type !== "text") continue;
+
+		const mdLinkRegex = /\[([^\]]+)\]\((https?:\/\/[^\s)]+)\)/g;
+		for (let match = mdLinkRegex.exec(block.text); match !== null; match = mdLinkRegex.exec(block.text)) {
+			const [, title, url] = match;
+			if (seen.has(url)) continue;
+			seen.add(url);
+			refs.push({ kind: classifyReferenceKind(url), title, url });
+		}
+
+		const bareUrlRegex = /(?<!\()(https?:\/\/[^\s)>\]]+)/g;
+		for (let match = bareUrlRegex.exec(block.text); match !== null; match = bareUrlRegex.exec(block.text)) {
+			const url = trimTrailingMarkup(match[1]);
+			if (seen.has(url)) continue;
+			seen.add(url);
+			refs.push({ kind: classifyReferenceKind(url), title: titleFromUrl(url), url });
+		}
+	}
+	return refs;
+}
+
+/** The RPC stream's citation event, mirroring `chat_done.references` on the bridge. */
+export interface RpcReferencesEvent {
+	type: "references";
+	references: ChatReference[];
+}
+
+/**
+ * Decide whether an agent event should produce a citation event, and build it.
+ *
+ * Pure so the TURN-BOUNDARY rule is testable: an intermediate tool-use step also
+ * emits `message_end`, and treating that as terminal is the trap
+ * `chat-handler.ts` documents at length — it would publish the citations of a
+ * half-finished answer (and, on the bridge, end the turn early). Returns null for
+ * anything that is not a settled assistant message, and for a turn that cited
+ * nothing, so callers emit only real content.
+ *
+ * Typed by what it CONSUMES (a tagged event that may carry a message) rather than by
+ * one event union: the bridge and the RPC session stream different unions
+ * (`AgentEvent` vs `AgentSessionEvent`) and both must be able to call this.
+ */
+export function referencesEventFor(event: { type: string; message?: unknown }): RpcReferencesEvent | null {
+	if (event.type !== "message_end") return null;
+	const message = (event as { message?: { role?: string } }).message;
+	if (message?.role !== "assistant") return null;
+	const assistant = message as AssistantMessage;
+	// Intermediate tool-use step — the turn continues after the tool round-trip.
+	if (assistant.stopReason === "toolUse" || assistant.content.some(part => part.type === "toolCall")) return null;
+	const references = extractReferences(assistant);
+	return references.length > 0 ? { type: "references", references } : null;
+}

package/src/sdk.ts

@@ -83,6 +83,7 @@ import {
 	SkillProtocolHandler,
 } from "./internal-urls";
 import { buildComputerHint, loadComputerProfile } from "./internal-urls/computer-profile";
+import { createLiveCwdGetter } from "./internal-urls/fleet-resolve";
 import { loadProfile, type UserProfile } from "./internal-urls/user-profile";
 import { disposeAllKernelSessions, disposeKernelSessionsByOwner } from "./ipy/executor";
 import { LSP_STARTUP_EVENT_CHANNEL, type LspStartupEvent } from "./lsp/startup-events";
@@ -1151,6 +1152,9 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 					}
 				},
 				getPluginRoots: () => listXcshPluginRoots(os.homedir(), cwd).then(r => r.roots),
+				// Classification must follow the session's `cd`, not the process cwd, which
+				// never moves. The bash tool emits `cwd:changed` when it relocates.
+				fleetDeps: { cwd: createLiveCwdGetter(cwd, eventBus) },
 			}),
 		);
 		internalRouter.register(new JobsProtocolHandler({ getAsyncJobManager: () => asyncJobManager }));

package/src/services/xcsh-knowledge.ts

@@ -15,7 +15,24 @@ export interface LlmsIndex {
 	fetchedAt: string;
 }
 
-const INFRASTRUCTURE_SLUGS = new Set([
+/**
+ * Federated sites that are not F5 XC *product* documentation, and so do not belong
+ * in the product list this module feeds to the system prompt.
+ *
+ * Deliberately NOT the `repo_classes` authority classification from
+ * `xcsh://fleet`. The two answer different questions and disagree: `docs`,
+ * `cdn-simulator` and `origin-server` are all authority `content` — xcsh does author
+ * their documentation and Terraform — while being the documentation portal and two
+ * lab-infrastructure repositories rather than products. Driving this filter off
+ * authority would advertise all three as F5 XC products.
+ *
+ * The concern this tracks is the `llms-federated-sites.json` category in the `docs`
+ * repository: everything here is `build-platform`, `developer-tools`, `portal` or
+ * `lab-infrastructure`, and everything kept is `product-features` or
+ * `api-specifications`. That file is not synced into clones, so the list is
+ * maintained here.
+ */
+const NON_PRODUCT_SLUGS = new Set([
 	"docs-builder",
 	"docs-theme",
 	"docs-icons",
@@ -70,7 +87,7 @@ export function parseLlmsTxt(content: string, now?: Date): LlmsIndex {
 
 		const [, name, url, desc] = match;
 		const slug = extractSlug(url);
-		if (slug && INFRASTRUCTURE_SLUGS.has(slug)) continue;
+		if (slug && NON_PRODUCT_SLUGS.has(slug)) continue;
 
 		products.push({ name, description: desc, url });
 	}