@grosspoetrysystems/oompf 0.2.1 → 0.3.0

package/dist/index.mjs

@@ -2,16 +2,152 @@
 import { createRequire } from "node:module";
 import { Cli, z } from "incur";
 import { dirname, isAbsolute, join } from "node:path";
+import { spawn } from "node:child_process";
 import { createHash } from "node:crypto";
 import { access, mkdir, readFile, readdir, stat, writeFile } from "node:fs/promises";
 import { env } from "node:process";
-import { spawn } from "node:child_process";
+import { confirm, isCancel, select } from "@clack/prompts";
 //#region \0rolldown/runtime.js
 var __commonJSMin = (cb, mod) => () => (mod || (cb((mod = { exports: {} }).exports, mod), cb = null), mod.exports);
 var __require = /* #__PURE__ */ (() => createRequire(import.meta.url))();
 //#endregion
 //#region package.json
-var version = "0.2.1";
+var version = "0.3.0";
+//#endregion
+//#region ../../packages/core/src/spawn.ts
+/**
+* The workspace's single process-spawning primitive.
+*
+* Backed by `node:child_process` rather than `Bun.spawn`. Bun implements the
+* Node API, so one implementation serves both runtimes — whereas reaching for
+* the `Bun` global makes the published CLI throw
+* `Cannot read properties of undefined (reading 'spawn')` the moment it runs
+* under Node, which is exactly how this module came to exist.
+*
+* Every caller passes an explicit argument array. There is no shell string and
+* no interpolation, so profile names, descriptions, and file contents can never
+* be reinterpreted as shell syntax.
+*
+* Import only from CLI-side code: spawning is unavailable inside a Cloudflare
+* Worker.
+*/
+/**
+* Run a command, capturing its output.
+*
+* Rejects with the underlying spawn error when the executable is missing (an
+* `ENOENT`), so callers can distinguish "not installed" from "ran and failed"
+* — a non-zero exit code always means the binary ran.
+*/
+function spawnCapture(input) {
+	const { args, command, env, stdin } = input;
+	const { promise, resolve, reject } = Promise.withResolvers();
+	const child = spawn(command, [...args], {
+		stdio: [
+			stdin === void 0 ? "ignore" : "pipe",
+			"pipe",
+			"pipe"
+		],
+		...env === void 0 ? {} : { env }
+	});
+	const { stderr: errStream, stdout: outStream } = child;
+	if (outStream === null || errStream === null) {
+		reject(/* @__PURE__ */ new Error(`Could not capture output from "${command}".`));
+		return promise;
+	}
+	let stdout = "";
+	let stderr = "";
+	outStream.setEncoding("utf8");
+	errStream.setEncoding("utf8");
+	outStream.on("data", (chunk) => {
+		stdout += chunk;
+	});
+	errStream.on("data", (chunk) => {
+		stderr += chunk;
+	});
+	child.on("error", reject);
+	child.on("close", (exitCode) => {
+		resolve({
+			exitCode,
+			stderr,
+			stdout
+		});
+	});
+	if (stdin !== void 0 && child.stdin !== null) {
+		child.stdin.on("error", () => void 0);
+		child.stdin.end(stdin, "utf8");
+	}
+	return promise;
+}
+//#endregion
+//#region ../../packages/core/src/agent-runtime.ts
+/**
+* Agent-runtime detection and selection.
+*
+* OOMPF commands ask the local `omp` binary for profile paths. That binary is
+* one of two agent runtimes — `omp` (OMP) or `pi` (Programmable Intelligence).
+* This module resolves which binary a command should invoke: the installed
+* runtime, the sole installed one, or an explicit `--agent` request.
+*
+* It selects the *binary* only. `pi`'s profile-path layout compatibility is
+* tracked upstream (GPS-148) and is deliberately out of scope here — the
+* chosen command simply flows through the existing `ompCommand` seam.
+*/
+/** The executable name for each agent runtime. */
+const AGENT_RUNTIME_COMMANDS = {
+	omp: "omp",
+	pi: "pi"
+};
+/** No usable agent runtime is installed (or the requested one is absent). */
+var AgentRuntimeUnavailableError = class extends Error {
+	constructor(message) {
+		super(message);
+		this.name = "AgentRuntimeUnavailableError";
+	}
+};
+/** Default probe: the binary exists when `--version` runs at all. */
+async function defaultProbe(command) {
+	try {
+		await spawnCapture({
+			args: ["--version"],
+			command
+		});
+		return true;
+	} catch {
+		return false;
+	}
+}
+const INSTALL_BOTH = `Install either ${AGENT_RUNTIME_COMMANDS.omp} or ${AGENT_RUNTIME_COMMANDS.pi} and retry.`;
+/**
+* Resolve which agent-runtime binary a command should drive.
+*
+* Precedence:
+* 1. `requested` set -> probe only that runtime. Present -> return it;
+*    absent -> throw {@link AgentRuntimeUnavailableError}.
+* 2. `requested` unset -> probe both concurrently. Both present -> `omp`;
+*    exactly one -> that one; neither -> throw
+*    {@link AgentRuntimeUnavailableError}.
+*/
+async function resolveAgentRuntime(options) {
+	const probe = options?.probe ?? defaultProbe;
+	if (options?.requested !== void 0) {
+		const requested = options.requested;
+		if (await probe(AGENT_RUNTIME_COMMANDS[requested])) return {
+			command: AGENT_RUNTIME_COMMANDS[requested],
+			runtime: requested
+		};
+		throw new AgentRuntimeUnavailableError(`The ${requested} agent runtime is not installed (expected the ${AGENT_RUNTIME_COMMANDS[requested]} binary on PATH). ${INSTALL_BOTH}`);
+	}
+	const [ompPresent, piPresent] = await Promise.all([probe(AGENT_RUNTIME_COMMANDS.omp), probe(AGENT_RUNTIME_COMMANDS.pi)]);
+	if (ompPresent) return {
+		command: AGENT_RUNTIME_COMMANDS.omp,
+		runtime: "omp"
+	};
+	if (piPresent) return {
+		command: AGENT_RUNTIME_COMMANDS.pi,
+		runtime: "pi"
+	};
+	throw new AgentRuntimeUnavailableError(`No agent runtime is installed (expected ${AGENT_RUNTIME_COMMANDS.omp} or ${AGENT_RUNTIME_COMMANDS.pi} on PATH). ${INSTALL_BOTH}`);
+}
 //#endregion
 //#region ../../packages/core/src/guards.ts
 /**
@@ -374,6 +510,23 @@ function extractTags(value, warnings) {
 	if (droppedNonString) warnings.push("oompf.tags dropped one or more non-string entries.");
 	return tags;
 }
+/** Keep a link only when its URL is a safe `http(s)` target. */
+function httpLink(url, label, warnings) {
+	let protocol;
+	try {
+		protocol = new URL(url).protocol;
+	} catch {
+		protocol = "";
+	}
+	if (protocol !== "http:" && protocol !== "https:") {
+		warnings.push("oompf.links dropped an entry with a non-http(s) URL.");
+		return null;
+	}
+	return {
+		label,
+		url
+	};
+}
 /** Coerce a single link entry (string URL or `{ url, label? }`) into a link. */
 function extractLink(entry, warnings) {
 	if (typeof entry === "string") {
@@ -382,10 +535,7 @@ function extractLink(entry, warnings) {
 			warnings.push("oompf.links dropped an entry with an empty URL.");
 			return null;
 		}
-		return {
-			label: null,
-			url
-		};
+		return httpLink(url, null, warnings);
 	}
 	if (isRecord(entry)) {
 		const rawUrl = entry.url;
@@ -393,10 +543,8 @@ function extractLink(entry, warnings) {
 			warnings.push("oompf.links dropped an entry missing a string `url`.");
 			return null;
 		}
-		return {
-			label: typeof entry.label === "string" && entry.label.trim() !== "" ? entry.label.trim() : null,
-			url: rawUrl.trim()
-		};
+		const label = typeof entry.label === "string" && entry.label.trim() !== "" ? entry.label.trim() : null;
+		return httpLink(rawUrl.trim(), label, warnings);
 	}
 	warnings.push("oompf.links dropped an entry that was not a string or object.");
 	return null;
@@ -447,6 +595,43 @@ function extractMetadata(document) {
 		warnings
 	};
 }
+//#endregion
+//#region ../../packages/core/src/model-catalog.ts
+/**
+* GPS-150-1 is the first reviewed snapshot. A catalog revision changes only
+* when its mappings change in a normal code review; upgrade output reports it
+* so a proposed change remains attributable and reproducible.
+*/
+const MODEL_CATALOG = {
+	models: [{
+		deployment: "hosted",
+		docsUrl: "https://docs.anthropic.com/en/docs/about-claude/models",
+		id: "anthropic/claude-opus-4",
+		providerId: "anthropic",
+		reasoning: "reasoning",
+		roles: [
+			"coding",
+			"planning",
+			"review"
+		],
+		successor: "anthropic/claude-opus-4.8",
+		tier: "frontier"
+	}, {
+		deployment: "hosted",
+		docsUrl: "https://docs.anthropic.com/en/docs/about-claude/models",
+		id: "anthropic/claude-opus-4.8",
+		providerId: "anthropic",
+		reasoning: "reasoning",
+		roles: [
+			"coding",
+			"planning",
+			"review"
+		],
+		successor: null,
+		tier: "frontier"
+	}],
+	revision: "gps-150-1"
+};
 /**
 * Charset/shape rule. The leading class forbids a name starting with `.`, `_`,
 * or `-`; the `{0,63}` bound caps the total length at 64 characters.
@@ -499,71 +684,6 @@ function validateProfileName(name) {
 	};
 }
 //#endregion
-//#region ../../packages/core/src/spawn.ts
-/**
-* The workspace's single process-spawning primitive.
-*
-* Backed by `node:child_process` rather than `Bun.spawn`. Bun implements the
-* Node API, so one implementation serves both runtimes — whereas reaching for
-* the `Bun` global makes the published CLI throw
-* `Cannot read properties of undefined (reading 'spawn')` the moment it runs
-* under Node, which is exactly how this module came to exist.
-*
-* Every caller passes an explicit argument array. There is no shell string and
-* no interpolation, so profile names, descriptions, and file contents can never
-* be reinterpreted as shell syntax.
-*
-* Import only from CLI-side code: spawning is unavailable inside a Cloudflare
-* Worker.
-*/
-/**
-* Run a command, capturing its output.
-*
-* Rejects with the underlying spawn error when the executable is missing (an
-* `ENOENT`), so callers can distinguish "not installed" from "ran and failed"
-* — a non-zero exit code always means the binary ran.
-*/
-function spawnCapture(input) {
-	const { args, command, env, stdin } = input;
-	const { promise, resolve, reject } = Promise.withResolvers();
-	const child = spawn(command, [...args], {
-		stdio: [
-			stdin === void 0 ? "ignore" : "pipe",
-			"pipe",
-			"pipe"
-		],
-		...env === void 0 ? {} : { env }
-	});
-	const { stderr: errStream, stdout: outStream } = child;
-	if (outStream === null || errStream === null) {
-		reject(/* @__PURE__ */ new Error(`Could not capture output from "${command}".`));
-		return promise;
-	}
-	let stdout = "";
-	let stderr = "";
-	outStream.setEncoding("utf8");
-	errStream.setEncoding("utf8");
-	outStream.on("data", (chunk) => {
-		stdout += chunk;
-	});
-	errStream.on("data", (chunk) => {
-		stderr += chunk;
-	});
-	child.on("error", reject);
-	child.on("close", (exitCode) => {
-		resolve({
-			exitCode,
-			stderr,
-			stdout
-		});
-	});
-	if (stdin !== void 0 && child.stdin !== null) {
-		child.stdin.on("error", () => void 0);
-		child.stdin.end(stdin, "utf8");
-	}
-	return promise;
-}
-//#endregion
 //#region ../../node_modules/.bun/yaml@2.9.0/node_modules/yaml/dist/nodes/identity.js
 var require_identity = /* @__PURE__ */ __commonJSMin(((exports) => {
 	const ALIAS = Symbol.for("yaml.alias");
@@ -7254,6 +7374,17 @@ function assertProfileDocument(value) {
 * names — even hostile ones — are passed as opaque arguments with no shell
 * interpolation.
 */
+/** A named OMP profile whose resolved agent directory is absent. */
+var OmpProfileNotFoundError = class extends Error {
+	profile;
+	resolvedPath;
+	constructor(profile, resolvedPath) {
+		super(`Resolved agent directory for profile "${profile}" is not a directory (missing): "${resolvedPath}".`);
+		this.profile = profile;
+		this.resolvedPath = resolvedPath;
+		this.name = "OmpProfileNotFoundError";
+	}
+};
 const DEFAULT_OMP_COMMAND = "omp";
 /**
 * Config filenames OOMPF understands, in preference order: `config.yml` wins
@@ -7300,10 +7431,26 @@ async function resolveConfigPath(profile, ompCommand, requireDirectory) {
 	if (!isAbsolute(resolved)) throw new Error(`OMP returned a non-absolute config path for the ${label}: "${resolved}".`);
 	if (requireDirectory) {
 		const kind = await statKind(resolved);
+		if (kind === "missing" && profile !== null) throw new OmpProfileNotFoundError(profile, resolved);
 		if (kind !== "directory") throw new Error(`Resolved agent directory for the ${label} is not a directory (${kind}): "${resolved}".`);
 	}
 	return resolved;
 }
+/**
+* Verify a named profile exists before invoking its OMP path resolver.
+*
+* OMP may create the named agent directory as a side effect of `config path`,
+* so checking only after that command turns an absent profile into a
+* config-less one. The default path is side-effect-free for named profiles and
+* gives us the same profiles root used by discovery.
+*/
+async function requireExistingProfile(profile, ompCommand) {
+	const defaultAgentDir = await resolveConfigPath(null, ompCommand, false);
+	const agentDir = join(dirname(defaultAgentDir), "profiles", profile, "agent");
+	const kind = await statKind(agentDir);
+	if (kind === "missing") throw new OmpProfileNotFoundError(profile, agentDir);
+	if (kind !== "directory") throw new Error(`Resolved agent directory for profile "${profile}" is not a directory (${kind}): "${agentDir}".`);
+}
 async function findConfigFile(agentDir) {
 	for (const filename of CONFIG_FILENAMES$1) {
 		const candidate = join(agentDir, filename);
@@ -7337,7 +7484,9 @@ async function resolveInstallTarget(name, options) {
 async function resolveProfileConfig(profile, options) {
 	const validation = validateProfileName(profile);
 	if (!validation.ok) throw new Error(validation.reason);
-	const agentDir = await resolveConfigPath(validation.value, options?.ompCommand ?? DEFAULT_OMP_COMMAND, true);
+	const ompCommand = options?.ompCommand ?? DEFAULT_OMP_COMMAND;
+	await requireExistingProfile(validation.value, ompCommand);
+	const agentDir = await resolveConfigPath(validation.value, ompCommand, true);
 	const configPath = await findConfigFile(agentDir);
 	return {
 		agentDir,
@@ -7380,6 +7529,182 @@ async function discoverProfiles(options) {
 	return discovered;
 }
 //#endregion
+//#region ../../packages/core/src/upgrade.ts
+/** Thinking suffixes that belong to the model selector's execution settings. */
+const THINKING_LEVELS = {
+	auto: true,
+	high: true,
+	inherit: true,
+	low: true,
+	max: true,
+	medium: true,
+	minimal: true,
+	off: true,
+	xhigh: true
+};
+function splitThinkingSuffix(model) {
+	const colon = model.lastIndexOf(":");
+	if (colon <= 0) return {
+		modelSelector: model,
+		thinkingLevel: null
+	};
+	const suffix = model.slice(colon + 1);
+	return Object.hasOwn(THINKING_LEVELS, suffix) ? {
+		modelSelector: model.slice(0, colon),
+		thinkingLevel: suffix
+	} : {
+		modelSelector: model,
+		thinkingLevel: null
+	};
+}
+/** Map common profile role labels to the catalog's broader role-fit classes. */
+const ROLE_TO_CATALOG_ROLE = {
+	chat: "chat",
+	coder: "coding",
+	coding: "coding",
+	planner: "planning",
+	planning: "planning",
+	review: "review",
+	reviewer: "review"
+};
+function replacementFor(model, path, role, catalog, plan) {
+	if (model.startsWith("@")) return model;
+	const parsed = splitThinkingSuffix(model);
+	const current = catalog.models.find((entry) => entry.id === parsed.modelSelector);
+	if (current === void 0) {
+		plan.unchanged.push({
+			model,
+			path,
+			reason: "unclassified",
+			role
+		});
+		return model;
+	}
+	if (current.successor === null || current.successor === current.id) {
+		plan.unchanged.push({
+			model,
+			path,
+			reason: current.successor === current.id ? "already_current" : "no_successor",
+			role
+		});
+		return model;
+	}
+	const successor = catalog.models.find((entry) => entry.id === current.successor);
+	if (successor === void 0) {
+		plan.unchanged.push({
+			model,
+			path,
+			reason: "unavailable",
+			role
+		});
+		return model;
+	}
+	const catalogRole = role === null ? void 0 : ROLE_TO_CATALOG_ROLE[role];
+	if (catalogRole !== void 0 && !successor.roles.includes(catalogRole)) {
+		plan.unchanged.push({
+			model,
+			path,
+			reason: "slot_mismatch",
+			role
+		});
+		return model;
+	}
+	const to = parsed.thinkingLevel === null ? successor.id : `${successor.id}:${parsed.thinkingLevel}`;
+	plan.changes.push({
+		from: model,
+		path,
+		reason: "successor",
+		role,
+		to
+	});
+	return to;
+}
+function replaceArray(values, displayPath, nodePath, role, catalog, plan, setNode) {
+	for (let index = 0; index < values.length; index++) {
+		const value = values[index];
+		if (typeof value !== "string") continue;
+		const next = replacementFor(value, `${displayPath}[${index}]`, role, catalog, plan);
+		if (next !== value) setNode([...nodePath, index], next);
+	}
+}
+function replaceModelRoles(document, catalog, plan, setNode) {
+	const modelRoles = document.modelRoles;
+	if (!isRecord(modelRoles)) return;
+	for (const [role, assigned] of Object.entries(modelRoles)) {
+		const displayPath = `modelRoles.${role}`;
+		const nodePath = ["modelRoles", role];
+		if (typeof assigned === "string") {
+			const next = replacementFor(assigned, displayPath, role, catalog, plan);
+			if (next !== assigned) setNode(nodePath, next);
+		} else if (Array.isArray(assigned)) replaceArray(assigned, displayPath, nodePath, role, catalog, plan, setNode);
+	}
+}
+function replaceEnabledModels(document, catalog, plan, setNode) {
+	if (Array.isArray(document.enabledModels)) replaceArray(document.enabledModels, "enabledModels", ["enabledModels"], null, catalog, plan, setNode);
+}
+function replaceRetryChains(document, catalog, plan, setNode) {
+	if (!isRecord(document.retry)) return;
+	const chains = document.retry.fallbackChains;
+	if (isRecord(chains)) {
+		for (const [role, value] of Object.entries(chains)) if (Array.isArray(value)) replaceArray(value, `retry.fallbackChains.${role}`, [
+			"retry",
+			"fallbackChains",
+			role
+		], null, catalog, plan, setNode);
+		return;
+	}
+	if (!Array.isArray(chains)) return;
+	if (chains.every((value) => typeof value === "string")) {
+		replaceArray(chains, "retry.fallbackChains", ["retry", "fallbackChains"], null, catalog, plan, setNode);
+		return;
+	}
+	for (let index = 0; index < chains.length; index++) {
+		const value = chains[index];
+		if (Array.isArray(value)) replaceArray(value, `retry.fallbackChains[${index}]`, [
+			"retry",
+			"fallbackChains",
+			index
+		], null, catalog, plan, setNode);
+	}
+}
+function applyReplacements(source, replacements) {
+	let output = source;
+	for (const replacement of [...replacements].sort((left, right) => right.start - left.start)) output = output.slice(0, replacement.start) + replacement.value + output.slice(replacement.end);
+	return output;
+}
+/**
+* Produce a model-only YAML upgrade plan. The input document is never mutated;
+* only recognized model-selector locations are changed in the serialized copy.
+*/
+function proposeUpgrade(yaml, catalog) {
+	const document = (0, import_dist.parseDocument)(yaml, { keepSourceTokens: true });
+	const parsed = document.toJS();
+	if (!isRecord(parsed)) throw new Error("Profile YAML must have a mapping root.");
+	const plan = {
+		changes: [],
+		unchanged: []
+	};
+	const replacements = [];
+	const setNode = (path, value) => {
+		const node = document.getIn(path, true);
+		if (node === null || typeof node !== "object" || !("range" in node) || !Array.isArray(node.range) || typeof node.range[0] !== "number" || typeof node.range[1] !== "number") throw new Error("Profile YAML model selector has no source range.");
+		replacements.push({
+			end: node.range[1],
+			start: node.range[0],
+			value
+		});
+	};
+	replaceModelRoles(parsed, catalog, plan, setNode);
+	replaceEnabledModels(parsed, catalog, plan, setNode);
+	replaceRetryChains(parsed, catalog, plan, setNode);
+	return {
+		catalogRevision: catalog.revision,
+		changes: plan.changes,
+		unchanged: plan.unchanged,
+		yaml: applyReplacements(yaml, replacements)
+	};
+}
+//#endregion
 //#region ../../packages/core/src/validation.ts
 /**
 * Structural validation and secret scanning for OMP profile artifacts.
@@ -7664,6 +7989,63 @@ function finishLocation(gistId, owner, revision, raw) {
 	};
 }
 /**
+* Read a raw profile body under the size cap, refusing oversized payloads
+* before the full body is materialized. Prefers the `content-length` header;
+* when absent, streams the body and aborts once accumulated bytes exceed the
+* cap. In-cap content is decoded byte-exactly, so hashing is unchanged.
+*/
+async function readRawYaml(rawResponse, gistId, filename) {
+	const rawContentLength = rawResponse.headers instanceof Headers ? rawResponse.headers.get("content-length") : rawResponse.headers?.["content-length"];
+	const contentLength = Number(rawContentLength);
+	if (Number.isFinite(contentLength) && contentLength > 1048576) throw oversizedError(gistId, filename);
+	const body = rawResponse.body;
+	if (body === void 0 || body === null) return rawResponse.text();
+	const reader = body.getReader();
+	const chunks = [];
+	let total = 0;
+	for (;;) {
+		const { done, value } = await reader.read();
+		if (done) break;
+		total += value.byteLength;
+		if (total > 1048576) {
+			await reader.cancel().catch(() => {});
+			throw oversizedError(gistId, filename);
+		}
+		chunks.push(value);
+	}
+	const bytes = new Uint8Array(total);
+	let offset = 0;
+	for (const chunk of chunks) {
+		bytes.set(chunk, offset);
+		offset += chunk.byteLength;
+	}
+	return new TextDecoder().decode(bytes);
+}
+/** Value-free refusal shared by all oversized-payload rejection paths. */
+function oversizedError(gistId, filename) {
+	return /* @__PURE__ */ new Error(`Gist "${gistId}" file "${filename}" exceeds the maximum supported artifact size.`);
+}
+/**
+* A Gist fetch that failed at the HTTP layer, carrying the response status.
+*
+* The status is what lets a caller tell "this source is gone" (404) from "we
+* could not ask right now" (403 rate limit, 429, 5xx). That distinction matters
+* to anything that records a judgement about a source: GitHub's unauthenticated
+* API allows 60 requests per hour per IP, and a Cloudflare Worker egresses from
+* shared addresses, so a 403 says nothing whatsoever about the Gist.
+*
+* Messages are unchanged from the plain `Error`s this replaced, so existing
+* message-based classification keeps working.
+*/
+var GistHttpError = class extends Error {
+	status;
+	constructor(message, status) {
+		super(message);
+		this.name = "GistHttpError";
+		this.status = status;
+	}
+};
+/**
 * Fetch a public Gist and return its single canonical profile YAML source.
 *
 * The Gist metadata is read from `https://api.github.com/gists/<id>` (pinned
@@ -7672,8 +8054,10 @@ function finishLocation(gistId, owner, revision, raw) {
 * an unsupported filename is rejected. The file's exact bytes are then read
 * from its canonical `raw_url` and hashed.
 *
-* @throws Error for unsupported references, missing/private Gists (404),
-*   ambiguous or unsupported YAML files, and transport failures.
+* @throws {GistHttpError} for HTTP-level failures, carrying the status (404 for
+*   a missing or private Gist).
+* @throws Error for unsupported references, ambiguous or unsupported YAML
+*   files, oversized payloads, and transport failures.
 */
 async function fetchPublicGist(source, options) {
 	const location = parseGistLocation(source);
@@ -7681,16 +8065,16 @@ async function fetchPublicGist(source, options) {
 	if (doFetch === void 0) throw new Error("No fetch implementation is available; inject one via options.fetch.");
 	const metaResponse = await doFetch(location.revision === null ? `https://api.github.com/gists/${location.gistId}` : `https://api.github.com/gists/${location.gistId}/${location.revision}`, { headers: GITHUB_API_HEADERS });
 	if (!metaResponse.ok) {
-		if (metaResponse.status === 404) throw new Error(`Public Gist "${location.gistId}" was not found. It may be private, deleted, or the ID may be wrong.`);
-		throw new Error(`Failed to fetch Gist "${location.gistId}": HTTP ${metaResponse.status}.`);
+		if (metaResponse.status === 404) throw new GistHttpError(`Public Gist "${location.gistId}" was not found. It may be private, deleted, or the ID may be wrong.`, 404);
+		throw new GistHttpError(`Failed to fetch Gist "${location.gistId}": HTTP ${metaResponse.status}.`, metaResponse.status);
 	}
 	const meta = parseGistMetadata(await metaResponse.text(), location.gistId);
 	const yamlFile = selectYamlFile(meta.files, location.gistId);
 	let content;
 	if (yamlFile.rawUrl !== null) {
 		const rawResponse = await doFetch(yamlFile.rawUrl, { headers: { "User-Agent": "oompf" } });
-		if (!rawResponse.ok) throw new Error(`Failed to fetch raw content for "${yamlFile.filename}" in Gist "${location.gistId}": HTTP ${rawResponse.status}.`);
-		content = await rawResponse.text();
+		if (!rawResponse.ok) throw new GistHttpError(`Failed to fetch raw content for "${yamlFile.filename}" in Gist "${location.gistId}": HTTP ${rawResponse.status}.`, rawResponse.status);
+		content = await readRawYaml(rawResponse, location.gistId, yamlFile.filename);
 	} else if (yamlFile.content === null) throw new Error(`Gist "${location.gistId}" file "${yamlFile.filename}" exposed no raw URL or content.`);
 	else content = yamlFile.content;
 	return {
@@ -7885,12 +8269,81 @@ async function createPublicProfileGist(input, options) {
 	};
 }
 /** Find the first `gist.github.com` URL in `gh`'s stdout, or `null`. */
+/**
+* Patch one file in an existing public Gist through `gh api`.
+*
+* The helper never creates a new Gist: preserving the source URL is what
+* preserves the stable OOMPF profile identity during `upgrade`.
+*/
+async function updatePublicProfileGist(input, options) {
+	const ghCommand = options?.ghCommand ?? DEFAULT_GH_COMMAND;
+	const runner = options?.runner ?? nodeCommandRunner;
+	const body = JSON.stringify({ files: { [input.filename]: { content: input.content } } });
+	let result;
+	try {
+		result = await runner({
+			args: [
+				"api",
+				"--method",
+				"PATCH",
+				`gists/${input.gistId}`,
+				"--input",
+				"-"
+			],
+			command: ghCommand,
+			stdin: body
+		});
+	} catch (error) {
+		if (isMissingExecutable(error)) throw new Error(`GitHub CLI (\`${ghCommand}\`) was not found on your PATH. Install it from https://cli.github.com/ and run \`gh auth login\`.`);
+		throw error;
+	}
+	if (result.exitCode !== 0) {
+		const detail = result.stderr.trim() || `exit code ${result.exitCode}`;
+		throw new Error(`GitHub CLI failed to update the public Gist: ${detail}`);
+	}
+	let parsed;
+	try {
+		parsed = JSON.parse(result.stdout);
+	} catch {
+		throw new Error("GitHub CLI returned invalid JSON after updating the public Gist.");
+	}
+	if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed) || !("id" in parsed) || typeof parsed.id !== "string" || !("html_url" in parsed) || typeof parsed.html_url !== "string") throw new Error("GitHub CLI response after updating the public Gist was incomplete.");
+	const first = ("history" in parsed && Array.isArray(parsed.history) ? parsed.history : [])[0];
+	const revision = first !== null && typeof first === "object" && !Array.isArray(first) && "version" in first && typeof first.version === "string" ? first.version : null;
+	return {
+		gistId: parsed.id,
+		htmlUrl: parsed.html_url,
+		revision
+	};
+}
 function extractGistUrl(stdout) {
 	const match = stdout.match(/https?:\/\/gist\.github\.com\/\S+/);
 	if (match === null) return null;
-	return match[0].replace(/[).,]+$/, "");
+	return match[0].replace(/[).,\]]+$/, "");
 }
 //#endregion
+//#region src/profile-selector.ts
+function isInteractiveProfileSession(options) {
+	return options.ci === void 0 && options.stdinIsTTY === true && options.stdoutIsTTY === true;
+}
+const defaultProfileSelector = {
+	isInteractive: () => isInteractiveProfileSession({
+		ci: process.env.CI,
+		stdinIsTTY: process.stdin.isTTY,
+		stdoutIsTTY: process.stdout.isTTY
+	}),
+	selectProfile: async (names) => {
+		const selected = await select({
+			message: "Select a profile to publish",
+			options: names.map((name) => ({
+				label: name,
+				value: name
+			}))
+		});
+		return isCancel(selected) ? null : selected;
+	}
+};
+//#endregion
 //#region src/deps.ts
 /**
 * Injectable seams shared by every OOMPF CLI command.
@@ -7924,6 +8377,10 @@ function toCliError(error, err) {
 		code: err.code,
 		message: err.message
 	});
+	if (err instanceof AgentRuntimeUnavailableError) return error({
+		code: "agent_not_found",
+		message: err.message
+	});
 	return error({
 		code: "error",
 		message: err instanceof Error ? err.message : String(err)
@@ -7964,6 +8421,8 @@ function resolveDeps(deps = {}) {
 		gistFetch: deps.gistFetch,
 		httpFetch: deps.httpFetch ?? defaultHttpFetch,
 		ompCommand: deps.ompCommand,
+		profileSelector: deps.profileSelector ?? defaultProfileSelector,
+		resolveAgentRuntime: deps.resolveAgentRuntime ?? resolveAgentRuntime,
 		resolveInstallTarget: deps.resolveInstallTarget ?? resolveInstallTarget,
 		resolveProfileConfig: deps.resolveProfileConfig ?? resolveProfileConfig,
 		runner: deps.runner
@@ -8020,8 +8479,10 @@ async function fetchProfileMetadata(baseUrl, id, fetchImpl) {
 	return parseJson(response, "not_found");
 }
 /** Free-text search over the OOMPF index. */
-async function searchProfiles(baseUrl, query, fetchImpl) {
-	const response = await request(fetchImpl, joinUrl(baseUrl, `/api/v1/search?q=${encodeURIComponent(query)}`), { method: "GET" });
+async function searchProfiles(baseUrl, query, fetchImpl, cursor) {
+	let url = joinUrl(baseUrl, `/api/v1/search?q=${encodeURIComponent(query)}`);
+	if (cursor) url += `&cursor=${encodeURIComponent(cursor)}`;
+	const response = await request(fetchImpl, url, { method: "GET" });
 	if (!response.ok) throw await envelopeError(response, "search_failed");
 	return parseJson(response, "search_failed");
 }
@@ -8077,12 +8538,50 @@ const publishOutput = z.object({
 	structural: z.enum(["valid", "invalid"]),
 	warnings: z.array(z.string())
 });
+/** `upgrade` result: a reviewed model diff and optional new Gist revision. */
+const upgradeOutput = z.object({
+	catalogRevision: z.string(),
+	changes: z.array(z.object({
+		from: z.string(),
+		path: z.string(),
+		reason: z.literal("successor"),
+		role: z.string().nullable(),
+		to: z.string()
+	})),
+	currentRevision: z.string(),
+	oompfUrl: z.string(),
+	unchanged: z.array(z.object({
+		model: z.string(),
+		path: z.string(),
+		reason: z.enum([
+			"already_current",
+			"no_successor",
+			"slot_mismatch",
+			"unavailable",
+			"unclassified"
+		]),
+		role: z.string().nullable()
+	})),
+	updatedRevision: z.string().nullable()
+});
+/** A single machine-local prerequisite the installed profile needs. */
+const prerequisite = z.object({
+	kind: z.enum([
+		"provider",
+		"environment",
+		"project-overlay",
+		"extension"
+	]),
+	name: z.string(),
+	reason: z.string()
+});
 /** `add` result: the installed profile and how to run it. */
 const addOutput = z.object({
 	command: z.string().describe("Command to run OMP with this profile"),
 	hash: z.string().describe("SHA-256 of the installed artifact"),
 	name: z.string().describe("Local OMP profile name installed"),
 	path: z.string().describe("Config file written"),
+	prerequisites: z.array(prerequisite).optional().describe("Profiles' machine-local prerequisites (names and kinds only, never secret values); informational, install succeeds regardless"),
 	revision: z.string().nullable(),
 	source: z.string().describe("Resolved canonical source"),
 	warnings: z.array(z.string())
@@ -8092,7 +8591,7 @@ const inspectOutput = z.object({
 	aliases: z.array(z.string()).describe("Named model aliases (@-prefixed)"),
 	errors: z.array(z.string()),
 	hash: z.string(),
-	installCommand: z.string(),
+	installCommand: z.string().optional(),
 	metadata: profileMetadataOutput,
 	models: z.array(z.string()),
 	name: z.string(),
@@ -8121,6 +8620,7 @@ const searchResult = z.object({
 /** `search` result: the query plus its compact matches. */
 const searchOutput = z.object({
 	count: z.number(),
+	nextCursor: z.string().nullable().describe("Opaque cursor for the next page, or null on the last page"),
 	query: z.string(),
 	results: z.array(searchResult)
 });
@@ -8130,8 +8630,9 @@ const searchOutput = z.object({
 * `oompf add <ref> [--name <name>]` — install a shared profile as a native OMP
 * profile.
 *
-* The reference may be an OOMPF URL/id, a public Gist URL, or a bare Gist id.
-* The canonical YAML is fetched and validated before anything is written. The
+* The reference must be an OOMPF URL or profile id. OOMPF resolves the
+* canonical Gist revision and verifies its fingerprint before anything is
+* written. The
 * local name defaults to `<github-owner>-<profile-name>` (overridable with
 * `--name`) and is checked against OMP's own naming rules. The install target
 * directory is resolved by asking OMP itself (`omp --profile <name> config
@@ -8147,22 +8648,27 @@ function filenameStem$1(filename) {
 /** Register the `add` command on the given CLI. */
 function registerAdd(cli, deps) {
 	cli.command("add", {
-		args: z.object({ ref: z.string().describe("OOMPF URL/id, public Gist URL, or Gist id") }),
+		args: z.object({ ref: z.string().describe("OOMPF URL or profile id") }),
 		description: "Install a shared profile as a native OMP profile",
 		env: cliEnv,
 		examples: [{
-			args: { ref: "https://gist.github.com/octocat/abc123" },
-			description: "Install a profile from a public Gist"
+			args: { ref: "https://oompf.run/p/prof_0123" },
+			description: "Install a profile with pinned verification"
 		}, {
 			args: { ref: "https://oompf.run/p/prof_0123" },
 			description: "Install under an explicit local name",
 			options: { name: "work" }
 		}],
-		options: z.object({ name: z.string().optional().describe("Local profile name (defaults to <owner>-<profile>)") }),
+		options: z.object({
+			agent: z.enum(["omp", "pi"]).optional().describe("Agent runtime to use (default: omp)"),
+			name: z.string().optional().describe("Local profile name (defaults to <owner>-<profile>)")
+		}),
 		output: addOutput,
 		async run(c) {
 			try {
 				const oompfId = parseOompfRef(c.args.ref);
+				if (oompfId === null) throw new CommandError("unverifiable_artifact", "Install requires an OOMPF URL or profile id so OOMPF can verify the pinned revision and fingerprint.");
+				const ompCommand = deps.ompCommand ?? (await deps.resolveAgentRuntime({ requested: c.options.agent })).command;
 				let sourceUrl = c.args.ref;
 				let fetchUrl = sourceUrl;
 				let expectedHash = null;
@@ -8176,13 +8682,14 @@ function registerAdd(cli, deps) {
 				const gist = await fetchPublicGist(fetchUrl, { fetch: deps.gistFetch });
 				if (expectedHash !== null && gist.contentHash !== expectedHash) throw new CommandError("fingerprint_mismatch", "The pinned profile bytes do not match the indexed fingerprint. Refusing to install.");
 				const validation = validateArtifact({ yaml: gist.content });
-				if (validation.structural === "invalid") throw new CommandError("invalid_artifact", `Refusing to install an invalid artifact: ${validation.errors.join("; ")}`);
+				if (validation.structural === "invalid" || validation.facts === null) throw new CommandError("invalid_artifact", `Refusing to install an invalid artifact: ${validation.errors.join("; ")}`);
+				if (validation.blocking.length > 0) throw new CommandError("blocking_secrets", `Refusing to install: high-confidence secrets detected at ${validation.blocking.map((f) => f.path).join(", ")}. Remove them and retry.`);
 				const stem = filenameStem$1(gist.filename);
 				const candidate = c.options.name ?? (gist.owner === null ? stem : `${gist.owner.toLowerCase()}-${stem}`);
 				const nameCheck = validateProfileName(candidate);
 				if (!nameCheck.ok) throw new CommandError("invalid_name", `Profile name "${candidate}" is invalid: ${nameCheck.reason} Pass --name <name>.`);
 				const name = nameCheck.value;
-				const agentDir = await deps.resolveInstallTarget(name, { ompCommand: deps.ompCommand });
+				const agentDir = await deps.resolveInstallTarget(name, { ompCommand });
 				for (const filename of CONFIG_FILENAMES) {
 					const existing = join(agentDir, filename);
 					if (await deps.fs.exists(existing)) throw new CommandError("target_exists", `Profile "${name}" already has a config at ${existing}. Refusing to overwrite.`);
@@ -8191,6 +8698,7 @@ function registerAdd(cli, deps) {
 				const target = join(agentDir, "config.yml");
 				await deps.fs.writeFile(target, gist.content, 384);
 				const command = `omp --profile ${name}`;
+				const prerequisites = validation.facts.prerequisites;
 				return c.ok({
 					command,
 					hash: gist.contentHash,
@@ -8198,11 +8706,9 @@ function registerAdd(cli, deps) {
 					path: target,
 					revision: gist.revision,
 					source: sourceUrl,
-					warnings: [...validation.warnings]
-				}, { cta: {
-					commands: [command],
-					description: "Run it with:"
-				} });
+					warnings: [...validation.warnings],
+					...prerequisites.length > 0 ? { prerequisites: [...prerequisites] } : {}
+				});
 			} catch (error) {
 				return toCliError(c.error, error);
 			}
@@ -8217,8 +8723,8 @@ function registerAdd(cli, deps) {
 * The reference may be an OOMPF URL/id or a public Gist URL/id. An OOMPF ref is
 * answered from the index metadata; a Gist ref is fetched and validated live.
 * Only displayable metadata — source, revision/hash, structural verdict, facts,
-* and the install command — is printed. The canonical artifact content is never
-* emitted.
+* and the OOMPF install command — is printed. The canonical artifact content is
+* never emitted.
 */
 /** Strip a recognised YAML extension from a Gist filename to get the stem. */
 function filenameStem(filename) {
@@ -8261,7 +8767,7 @@ function registerInspect(cli, deps) {
 						structural: record.validation.structural,
 						warnings: [...record.validation.warnings]
 					}, { cta: {
-						commands: [`oompf add ${c.args.ref}`],
+						commands: [{ command: `oompf add ${c.args.ref}` }],
 						description: "Install it with:"
 					} });
 				}
@@ -8272,7 +8778,6 @@ function registerInspect(cli, deps) {
 					aliases: facts ? [...facts.aliases] : [],
 					errors: [...validation.errors],
 					hash: gist.contentHash,
-					installCommand: `oompf add ${c.args.ref}`,
 					metadata: {
 						...validation.metadata,
 						links: [...validation.metadata.links],
@@ -8288,10 +8793,7 @@ function registerInspect(cli, deps) {
 					sourceType: "gist",
 					structural: validation.structural,
 					warnings: [...validation.warnings]
-				}, { cta: {
-					commands: [`oompf add ${c.args.ref}`],
-					description: "Install it with:"
-				} });
+				});
 			} catch (error) {
 				return toCliError(c.error, error);
 			}
@@ -8312,37 +8814,57 @@ function registerInspect(cli, deps) {
 * the single selected config artifact is sent, and high-confidence secrets
 * abort the publish before anything leaves the machine.
 */
+/** Narrow a discovered profile to one that carries a publishable config. */
+function hasConfig(profile) {
+	return profile.configPath !== null;
+}
 /** Concatenate the base URL and a site-relative path from the register call. */
-function toOompfUrl(baseUrl, path) {
+function toOompfUrl$1(baseUrl, path) {
 	return `${baseUrl.replace(/\/+$/, "")}${path.startsWith("/") ? path : `/${path}`}`;
 }
 /** Register the `publish` command on the given CLI. */
 function registerPublish(cli, deps) {
 	cli.command("publish", {
-		args: z.object({ profile: z.string().optional().describe("Local OMP profile name; omitted picks the sole profile") }),
+		args: z.object({ profile: z.string().optional().describe("Native OMP profile name; omitted selects a publishable profile") }),
 		description: "Publish a local OMP profile as a public Gist and index it",
 		env: cliEnv,
 		examples: [{
 			args: { profile: "work" },
 			description: "Publish the 'work' profile"
 		}],
+		options: z.object({ agent: z.enum(["omp", "pi"]).optional().describe("Agent runtime to use (default: omp)") }),
 		output: publishOutput,
 		async run(c) {
 			try {
-				const ompOptions = { ompCommand: deps.ompCommand };
+				const ompOptions = { ompCommand: deps.ompCommand ?? (await deps.resolveAgentRuntime({ requested: c.options.agent })).command };
 				let name;
 				let configPath;
 				if (c.args.profile === void 0) {
-					const discovered = await deps.discoverProfiles(ompOptions);
-					if (discovered.length === 0) throw new CommandError("no_profile", "No OMP profiles found. Pass a profile name: oompf publish <profile>.");
-					if (discovered.length > 1) throw new CommandError("ambiguous_profile", `Multiple profiles found (${discovered.map((p) => p.name).join(", ")}). Specify one: oompf publish <profile>.`);
-					const only = discovered[0];
-					name = only.name;
-					configPath = only.configPath;
+					const publishable = (await deps.discoverProfiles(ompOptions)).filter(hasConfig);
+					if (publishable.length === 0) throw new CommandError("no_profile", "No publishable OMP profiles found. Create a profile with config.yml/config.yaml or pass an existing profile name.");
+					let selected = publishable[0];
+					if (publishable.length > 1) {
+						const names = publishable.map((profile) => profile.name);
+						if (c.formatExplicit || !deps.profileSelector.isInteractive()) throw new CommandError("ambiguous_profile", `Multiple publishable profiles found (${names.join(", ")}). Specify one: oompf publish <profile>.`);
+						const selectedName = await deps.profileSelector.selectProfile(names);
+						if (selectedName === null) throw new CommandError("selection_cancelled", "Profile selection was cancelled. Nothing was published.");
+						const picked = publishable.find((profile) => profile.name === selectedName);
+						if (picked === void 0) throw new CommandError("selection_invariant", "The profile selector returned a name that was not offered.");
+						selected = picked;
+					}
+					name = selected.name;
+					configPath = selected.configPath;
 				} else {
-					const resolved = await deps.resolveProfileConfig(c.args.profile, ompOptions);
-					name = resolved.profile;
-					configPath = resolved.configPath;
+					const validation = validateProfileName(c.args.profile);
+					if (!validation.ok) throw new CommandError("invalid_profile", validation.reason);
+					try {
+						const resolved = await deps.resolveProfileConfig(validation.value, ompOptions);
+						name = resolved.profile;
+						configPath = resolved.configPath;
+					} catch (error) {
+						if (error instanceof OmpProfileNotFoundError) throw new CommandError("profile_not_found", `OMP profile "${validation.value}" was not found.`);
+						throw error;
+					}
 				}
 				if (configPath === null) throw new CommandError("missing_config", `Profile "${name}" has no config.yml/config.yaml to publish.`);
 				const yaml = await deps.fs.readFile(configPath);
@@ -8362,7 +8884,7 @@ function registerPublish(cli, deps) {
 					runner: deps.runner
 				});
 				const registration = await registerProfile(c.env.OOMPF_BASE_URL, { source: gist.htmlUrl }, deps.httpFetch);
-				const oompfUrl = toOompfUrl(c.env.OOMPF_BASE_URL, registration.url);
+				const oompfUrl = toOompfUrl$1(c.env.OOMPF_BASE_URL, registration.url);
 				const addCommand = `oompf add ${oompfUrl}`;
 				return c.ok({
 					addCommand,
@@ -8381,7 +8903,7 @@ function registerPublish(cli, deps) {
 					structural: registration.validation.structural,
 					warnings: [...validation.warnings, ...registration.validation.warnings]
 				}, { cta: {
-					commands: [addCommand],
+					commands: [{ command: addCommand }],
 					description: "Install it with:"
 				} });
 			} catch (error) {
@@ -8409,13 +8931,15 @@ function registerSearch(cli, deps) {
 			args: { query: "anthropic" },
 			description: "Search for a term"
 		}],
+		options: z.object({ cursor: z.string().optional().describe("Opaque pagination cursor from a previous search") }),
 		output: searchOutput,
 		async run(c) {
 			try {
 				const query = c.args.query ?? "";
-				const response = await searchProfiles(c.env.OOMPF_BASE_URL, query, deps.httpFetch);
+				const response = await searchProfiles(c.env.OOMPF_BASE_URL, query, deps.httpFetch, c.options.cursor);
 				return c.ok({
 					count: response.results.length,
+					nextCursor: response.nextCursor,
 					query: response.query,
 					results: response.results.map((r) => ({
 						id: r.id,
@@ -8437,15 +8961,100 @@ function registerSearch(cli, deps) {
 	});
 }
 //#endregion
+//#region src/commands/upgrade.ts
+/**
+* `oompf upgrade <ref>` — review and optionally apply model-only successors.
+*
+* The command plans from the current owned Gist head, not the indexed pinned
+* revision. It patches that same Gist only after confirmation, then registers
+* the unchanged source URL so the stable OOMPF profile identity survives.
+*/
+function toOompfUrl(baseUrl, id) {
+	return `${baseUrl.replace(/\/+$/, "")}/p/${id}`;
+}
+function currentGistUrl(gistId) {
+	return `https://api.github.com/gists/${gistId}`;
+}
+/** Register the `upgrade` command on the given CLI. */
+function registerUpgrade(cli, deps) {
+	cli.command("upgrade", {
+		args: z.object({ ref: z.string().describe("OOMPF profile URL or stable profile id") }),
+		description: "Review and optionally apply model upgrades to an OOMPF profile",
+		env: cliEnv,
+		examples: [{
+			args: { ref: "https://oompf.run/p/prof_..." },
+			description: "Preview model upgrades for an indexed profile"
+		}],
+		options: z.object({ yes: z.boolean().optional().describe("Apply the reviewed plan without prompting") }),
+		output: upgradeOutput,
+		async run(c) {
+			try {
+				const id = parseOompfRef(c.args.ref);
+				if (id === null) throw new CommandError("invalid_ref", "Upgrade requires an OOMPF profile URL or stable profile id.");
+				const record = await fetchProfileMetadata(c.env.OOMPF_BASE_URL, id, deps.httpFetch);
+				if (record.gistId === null || record.gistId === void 0) throw new CommandError("unverifiable_artifact", "The indexed profile has no source Gist and cannot be upgraded.");
+				const fetchCurrent = () => fetchPublicGist(currentGistUrl(record.gistId), { fetch: deps.gistFetch });
+				const current = await fetchCurrent();
+				if (current.owner === null) throw new CommandError("unowned_gist", "The source Gist has no public owner and cannot be patched.");
+				const plan = proposeUpgrade(current.content, MODEL_CATALOG);
+				const output = {
+					catalogRevision: plan.catalogRevision,
+					changes: [...plan.changes],
+					currentRevision: current.revision ?? record.revision ?? "unknown",
+					oompfUrl: toOompfUrl(c.env.OOMPF_BASE_URL, record.id),
+					unchanged: [...plan.unchanged],
+					updatedRevision: null
+				};
+				const shouldPrompt = c.options.yes !== true && !c.formatExplicit && deps.profileSelector.isInteractive();
+				if (!(c.options.yes || shouldPrompt)) return c.ok(output);
+				if (shouldPrompt) {
+					const answer = await confirm({ message: plan.changes.length === 0 ? "No model changes are proposed. Exit without writing?" : `Apply ${plan.changes.length} model change(s) to the current Gist?` });
+					if (isCancel(answer) || answer !== true) return c.ok(output);
+				}
+				if (plan.changes.length === 0) return c.ok(output);
+				const latest = await fetchCurrent();
+				if (latest.contentHash !== current.contentHash) throw new CommandError("head_changed", "The source Gist changed while the upgrade was being reviewed. Run upgrade again to plan from the new head.");
+				const identity = await getGithubIdentity({
+					ghCommand: deps.ghCommand,
+					runner: deps.runner
+				});
+				if (latest.owner?.toLowerCase() !== identity.login.toLowerCase()) throw new CommandError("unowned_gist", "The authenticated GitHub user does not own the source Gist; refusing to patch it.");
+				const validation = validateArtifact({ yaml: plan.yaml });
+				if (validation.structural === "invalid" || validation.facts === null) throw new CommandError("invalid_artifact", `The upgraded profile is structurally invalid: ${validation.errors.join("; ")}`);
+				if (validation.blocking.length > 0) throw new CommandError("blocking_secrets", "Refusing to patch the Gist: the upgraded profile contains high-confidence secrets.");
+				const updated = await updatePublicProfileGist({
+					content: plan.yaml,
+					filename: latest.filename,
+					gistId: latest.gistId
+				}, {
+					ghCommand: deps.ghCommand,
+					runner: deps.runner
+				});
+				try {
+					await registerProfile(c.env.OOMPF_BASE_URL, { source: record.sourceUrl }, deps.httpFetch);
+				} catch (error) {
+					throw new CommandError("index_update_failed", `The Gist was updated but OOMPF could not refresh its index. Re-register the unchanged source URL after the index recovers; this command will not patch the Gist again. Details: ${error instanceof Error ? error.message : String(error)}`);
+				}
+				return c.ok({
+					...output,
+					updatedRevision: updated.revision
+				});
+			} catch (error) {
+				return toCliError(c.error, error);
+			}
+		}
+	});
+}
+//#endregion
 //#region src/index.ts
 /**
 * OOMPF CLI entrypoint (binary name: `oompf`).
 *
-* Builds the Incur router CLI, wiring the four commands (`publish`, `add`,
-* `inspect`, `search`) against injectable seams. {@link createCli} takes an
-* optional {@link CliDeps} bundle so focused tests can drive every command with
-* fake `gh`/Gist/HTTP/`omp`/filesystem implementations; production omits it and
-* gets the real Bun/Node-backed seams.
+* Builds the Incur router CLI, wiring the five commands (`publish`, `add`,
+* `inspect`, `search`, `upgrade`) against injectable seams. {@link createCli}
+* takes an optional {@link CliDeps} bundle so focused tests can drive every
+* command with fake `gh`/Gist/HTTP/`omp`/filesystem implementations; production
+* omits it and gets the real Bun/Node-backed seams.
 */
 /**
 * OOMPF CLI version, surfaced by `oompf --version`.
@@ -8468,6 +9077,7 @@ function createCli(deps = {}) {
 	registerAdd(cli, resolved);
 	registerInspect(cli, resolved);
 	registerSearch(cli, resolved);
+	registerUpgrade(cli, resolved);
 	return cli;
 }
 if (import.meta.main) await createCli().serve();