@iowarp/clio-coder 0.3.9 → 0.4.1

package/src/interactive/slash-commands.ts

@@ -4,6 +4,7 @@ import type { SafeEventBus } from "../core/event-bus.js";
 import { parseCouncilReport, parseOracleResult } from "../domains/agents/index.js";
 import type { AgentSpec } from "../domains/agents/spec.js";
 import type { ContextInitOptions } from "../domains/context/init-options.js";
+import { AdmissionCanceledError } from "../domains/dispatch/admission-error.js";
 import type { DispatchContract, DispatchRequest } from "../domains/dispatch/contract.js";
 import { type AgentRoleFactsResolver, requestExecutionRole } from "../domains/dispatch/execution-role.js";
 import type { RunReceipt } from "../domains/dispatch/types.js";
@@ -11,6 +12,14 @@ import type { JobThinkingLevel } from "../domains/dispatch/validation.js";
 import type { ReceiptIntegrityOutcome } from "../domains/evidence/trust-status.js";
 import type { InstalledExtension } from "../domains/extensions/index.js";
 import type { InteropAgentId, InteropProposal, InteropReport } from "../domains/interop/index.js";
+import {
+	isPanesPresetId,
+	PANES_PRESET_IDS,
+	PANES_PRESETS,
+	type PanesOperations,
+	type PanesPresetId,
+	type PanesStatus,
+} from "../domains/mux/operations.js";
 import type { ProvidersContract, ResolvedModelRef } from "../domains/providers/index.js";
 import { resolveModelReference } from "../domains/providers/index.js";
 import type {
@@ -27,13 +36,13 @@ import type { NoticeLevel } from "./command-output.js";
 import {
 	buildCouncilDispatchArgs,
 	COUNCIL_MAX_ROUNDS,
+	COUNCIL_SYNTHESIS_LABEL,
 	COUNCIL_SYNTHESIS_MODES,
 	type CouncilCommandOptions,
 	type CouncilRosters,
 	isCouncilSynthesisMode,
 	resolveCouncilRoster,
 } from "./council.js";
-import { COUNCIL_SYNTHESIS_LABEL } from "./council-grid.js";
 import {
 	formatOracleAnswer,
 	ORACLE_AGENT_ID,
@@ -41,8 +50,7 @@ import {
 	type OracleDigestSources,
 	packOracleDigest,
 } from "./oracle.js";
-import { SETTINGS_SECTIONS, type SettingsCenterRowId, type SettingsSectionId } from "./overlays/settings.js";
-import { isLibraryTab, LIBRARY_TABS } from "./overlays/skills-hub.js";
+import { isLibraryTab, LIBRARY_TABS } from "./overlays/library-tabs.js";
 import type { CommandArgsSpec, CommandPositionalSpec, ParsedArgs } from "./slash-spec.js";
 import { matchFromSpec, usageLine } from "./slash-spec.js";
 import {
@@ -60,14 +68,43 @@ import type { WorkerEntryState } from "./worker-stream.js";
  * one user-facing slash command: how it parses, which SlashCommand kinds it
  * produces, and how those kinds execute. Adding a new command is one entry
  * rather than extending two parallel switches.
+ *
+ * This module is a CLI seam, which constrains what it may import.
+ * `src/cli/run.ts` reaches `parseSlashCommand` here so a headless
+ * `clio-coder run "/typo"` refuses the token by the same shape test and the same
+ * registry membership the editor uses; a second copy of the parser would drift
+ * from this one on the first command added. That makes the CLI a reacher of
+ * everything this file statically imports, so nothing here may reach the
+ * interactive render graph: no theme, no overlay frame, no overlay module, no
+ * `../engine/tui.js`. Those modules share one bundle chunk with the instant
+ * shell's Stage 0 closure, and a second, disjoint reacher makes esbuild split
+ * it, which is a startup-latency regression rather than a style problem. The
+ * parse-time data tables the registry needs live in leaves for that reason:
+ * `./overlays/library-tabs.js` and `COUNCIL_SYNTHESIS_LABEL` in
+ * `./council.js`. Import from those, not from overlays that re-export them.
+ *
+ * Boundaries rule6 in `tests/boundaries/check-boundaries.ts` refuses a violation
+ * at lint time; `tests/contracts/instant-shell-import-graph.test.ts` is the
+ * measurement it protects.
  */
 
-type ShareCommandVariant =
-	| { kind: "share"; action: "export"; path: string }
-	| { kind: "share"; action: "import"; path: string; dryRun: boolean; force: boolean }
-	/** Put a finished worker run's answer into the main agent's context. Bare `/share` takes the newest one. */
-	| { kind: "share"; action: "worker-run"; runId?: string }
-	| { kind: "share"; action: "usage"; subcommand?: "export" | "import"; error?: string };
+/** Put a finished worker run's answer into the main agent's context. Bare `/share` takes the newest one. */
+type ShareCommandVariant = { kind: "share"; runId?: string };
+type ArchiveCommandVariant =
+	| { kind: "archive-export"; path: string }
+	| { kind: "archive-import"; path: string; dryRun: boolean; force: boolean }
+	| { kind: "archive-usage"; subcommand?: "export" | "import"; error?: string };
+
+export const SETTINGS_AREA_IDS = [
+	"chat",
+	"fleet",
+	"targets",
+	"context",
+	"safety",
+	"interface",
+	"integrations",
+] as const;
+export type SettingsAreaId = (typeof SETTINGS_AREA_IDS)[number];
 
 type SlashCommandVariant =
 	| { kind: "quit" }
@@ -78,12 +115,10 @@ type SlashCommandVariant =
 	/** `ref` is the turnId an `[evicted ...]` marker names. */
 	| { kind: "context-recall"; ref: string }
 	| { kind: "skill-selector" }
-	| { kind: "library"; tab?: LibraryEntryKind }
+	| { kind: "resources"; family?: "skills" | "prompts" | "extensions"; tab?: LibraryEntryKind }
 	| { kind: "skill-invocation"; text: string }
-	| { kind: "prompts" }
-	| { kind: "extensions" }
-	| { kind: "interop" }
 	| ShareCommandVariant
+	| ArchiveCommandVariant
 	/** `source` is the line the operator typed, echoed above the run's transcript block. */
 	| { kind: "run"; agentId: string; task: string; options: RunCommandOptions; source: string }
 	| { kind: "run-usage" }
@@ -102,7 +137,8 @@ type SlashCommandVariant =
 	/** `/fleet run <name>`: compile the plan, show it for approval, dispatch on accept. */
 	| { kind: "fleet-run"; name: string; vars: Record<string, string> }
 	| { kind: "fleet-run-usage"; reason?: string }
-	| { kind: "agents" }
+	| { kind: "fleet" }
+	| { kind: "agents"; connect?: boolean }
 	| { kind: "cost" }
 	| { kind: "context-view" }
 	| { kind: "tasks" }
@@ -116,11 +152,22 @@ type SlashCommandVariant =
 	| { kind: "view"; filter?: string }
 	| { kind: "view-verify"; runId: string }
 	| { kind: "view-usage" }
+	/** `/panes`: mode, health, pane inventory, effective settings. */
+	| { kind: "panes" }
+	| { kind: "panes-show"; target: string }
+	/** A preset the model may also ask for, or operator-only argv. Never both. */
+	| { kind: "panes-open"; preset?: PanesPresetId; argv?: ReadonlyArray<string>; once?: boolean }
+	/** Toggle zoom on a Clio-owned pane; the bare form targets the watch pane. */
+	| { kind: "panes-zoom"; target: string }
+	| { kind: "panes-close"; target: string }
+	| { kind: "panes-usage"; reason?: string }
 	| { kind: "thinking-set"; level: string }
+	| { kind: "thinking-picker" }
 	| { kind: "output-set"; verbosity: string }
+	| { kind: "output-picker" }
 	| { kind: "model" }
 	| { kind: "model-set"; pattern: string }
-	| { kind: "settings"; section?: SettingsSectionId; rowId?: SettingsCenterRowId }
+	| { kind: "settings"; area?: SettingsAreaId; group?: string }
 	| { kind: "resume" }
 	| { kind: "new" }
 	| { kind: "tree" }
@@ -258,21 +305,27 @@ async function runAttributed(
 			progressBus?.emit(BusChannels.DispatchProgress, { runId: handle.runId, agentId: request.agentId, event });
 		}
 		const receipt = await handle.finalPromise;
-		if (receipt.exitCode !== 0 || receipt.failureMessage) {
+		if (receipt.outcome === "canceled") {
+			notice("warn", `${command} aborted: ${receipt.outcomeDetail ?? "operator abort"}`);
+		} else if (receipt.exitCode !== 0 || receipt.failureMessage) {
 			const failure = receipt.failureMessage ? ` ${receipt.failureMessage}` : "";
 			notice("error", `${command} failed: exit=${receipt.exitCode}${failure}`);
 		}
 		if (share) shareReceipt(request.agentId, receipt, deps);
 	} catch (err) {
 		const msg = err instanceof Error ? err.message : String(err);
-		notice("error", `${command} failed: ${msg}`);
+		if (err instanceof AdmissionCanceledError) {
+			notice("warn", `${command} aborted: ${msg.replace(/^dispatch:\s*/u, "")}`);
+		} else {
+			notice("error", `${command} failed: ${msg}`);
+		}
 	}
 }
 
 /**
  * Dispatches /run through the dispatch contract and streams events to stdout.
  * Target + model are resolved by the dispatch domain from request overrides,
- * worker profiles, recipe hints, and `settings.workers.default`.
+ * worker profiles, recipe hints, and `settings.fleet.default`.
  */
 export async function handleRun(
 	agentId: string,
@@ -629,20 +682,36 @@ export interface SlashCommandContext {
 	seedTaskMemory?: () => TaskMemorySeedCommandResult;
 	/** Open `/view`, the full observability artifact viewer. */
 	openView: (filter?: string) => void;
+	/**
+	 * The pane layer's operator surface. It remains present when mux resolves to
+	 * `none` because the Yazi preset can borrow the terminal for one selection;
+	 * absent only when the host did not compose pane operations at all.
+	 */
+	panes?: PanesOperations;
+	/** Serialize a local async command so the next admitted slash command observes its committed state. */
+	runLocalOperation?: (operation: () => Promise<void>) => void;
 	/**
 	 * Apply a thinking level named on the command line. Returns why it was
 	 * refused so the caller can say so, because the level the operator typed may
 	 * not be one the active target supports.
 	 */
 	setThinkingLevel?: (level: string) => SetThinkingLevelResult;
+	thinkingLevelChoices?: () => ReadonlyArray<{ value: string; label: string }>;
+	openThinkingPicker?: () => void;
 	/** Apply a transcript verbosity named on the command line; refused values are reported by the caller. */
 	setOutputVerbosity?: (verbosity: string) => SetOutputVerbosityResult;
+	openOutputPicker?: () => void;
 	openModel: () => void;
 	/** Live providers contract used by `/model <pattern>` to resolve directly. */
 	providers: ProvidersContract;
-	/** Apply a resolved model reference to settings (and optionally thinking level). */
-	applyModelRef: (ref: ResolvedModelRef) => void;
-	openSettings: (section?: SettingsSectionId, rowId?: SettingsCenterRowId) => void;
+	/**
+	 * Apply a resolved model reference, or hand it to the scope dialog. "pending"
+	 * means the operator has yet to choose session or global and nothing has
+	 * changed; the dialog reports the outcome itself.
+	 */
+	applyModelRef: (ref: ResolvedModelRef) => "applied" | "pending";
+	openSettings: (area?: SettingsAreaId, group?: string) => void;
+	openFleetRuns?: () => void;
 	openResume: () => void;
 	startNewSession: () => void;
 	openTree: () => void;
@@ -662,10 +731,16 @@ export interface SlashCommandContext {
 	runCompact: (instructions: string | undefined) => void;
 	/**
 	 * Escape hatch for the `view verify` entry: verify a receipt file on disk
-	 * and emit a single status line. Kept on the context so the registry does
+	 * and emit an actionable verification block. Kept on the context so the registry does
 	 * not import the overlay module.
 	 */
-	verifyReceipt: (runId: string) => ReceiptIntegrityOutcome;
+	verifyReceipt: (runId: string) => ReceiptIntegrityOutcome & {
+		receiptPath?: string;
+		sealedDigest?: string | null;
+		trustSummary?: string | null;
+		compromised?: boolean;
+		checks?: ReadonlyArray<{ name: string; ok: boolean; evidence: string }>;
+	};
 	/**
 	 * Handles the "unknown" case: append the text to the chat panel as a user
 	 * turn, submit to the chat loop, and schedule a re-render. Handlers for
@@ -677,6 +752,24 @@ export interface SlashCommandContext {
 	render: () => void;
 }
 
+type SlashReceiptVerification = ReturnType<SlashCommandContext["verifyReceipt"]>;
+
+/** Compact multiline receipt verification for the composer notice surface. */
+function formatReceiptVerificationBlock(runId: string, result: SlashReceiptVerification): string {
+	const status = result.ok ? (result.compromised ? "compromised" : "ok") : result.retired ? "retired" : "fail";
+	const lines = [
+		`verify ${status} ${runId}`,
+		`receipt  ${result.receiptPath ?? "unavailable"}`,
+		`digest   ${result.sealedDigest ?? "unavailable"}`,
+		`evidence ${result.trustSummary ?? (!result.ok ? result.reason : "trust status unavailable")}`,
+	];
+	if (result.checks && result.checks.length > 0) {
+		lines.push("checks");
+		for (const check of result.checks) lines.push(`  ${check.ok ? "✓" : "✗"} ${check.name}: ${check.evidence}`);
+	}
+	return lines.join("\n");
+}
+
 /** The one operator-authored turn used by slash and overlay handoff paths. */
 export function formatUserTaskHandoff(task: Pick<UserTask, "id" | "title" | "note">): string {
 	const note = task.note ? ` ${task.note}.` : "";
@@ -684,7 +777,7 @@ export function formatUserTaskHandoff(task: Pick<UserTask, "id" | "title" | "not
 }
 
 /** The verb a command performs, in the order /help lists the groups. */
-export const SLASH_COMMAND_GROUPS = ["Run", "Inspect", "Configure", "Sessions"] as const;
+export const SLASH_COMMAND_GROUPS = ["Work", "Inspect", "Configure", "Session"] as const;
 export type SlashCommandGroup = (typeof SLASH_COMMAND_GROUPS)[number];
 
 export interface BuiltinSlashCommand {
@@ -711,8 +804,8 @@ function isRunThinkingLevel(value: string): value is JobThinkingLevel {
 	return RUN_THINKING_LEVELS.some((level) => level === value);
 }
 
-function isSettingsSectionId(value: string): value is SettingsSectionId {
-	return SETTINGS_SECTIONS.some((section) => section.id === value);
+function isSettingsAreaId(value: string): value is SettingsAreaId {
+	return SETTINGS_AREA_IDS.some((area) => area === value);
 }
 
 /** `/context compact` alone keeps a free-form optional instruction tail. */
@@ -739,37 +832,51 @@ function fromArgsOrUsage(name: string, command: SlashCommand): (parsed: ParsedAr
 	return (parsed) => (parsed.error ? { kind: "usage-error", command: name, reason: parsed.error } : command);
 }
 
-/**
- * A configuration-shaped command that is a shortcut into one settings section.
- * It parses to the same `settings` command `/settings <section>` produces, so
- * the settings entry dispatches it and this entry owns no kind of its own.
- */
-function settingsDeepLink(
-	name: string,
-	section: SettingsSectionId,
-	description: string,
-	rowId?: SettingsCenterRowId,
-): BuiltinSlashCommand {
-	return {
-		name,
-		description,
-		group: "Configure",
-		kinds: [],
-		args: {},
-		fromArgs: fromArgsOrUsage(name, { kind: "settings", section, ...(rowId ? { rowId } : {}) }),
-		handle: () => undefined,
-	};
-}
-
 function usageNotice(entry: BuiltinSlashCommand, subcommand?: string): string {
 	return usageLine(entry, subcommand).trim();
 }
 
+/**
+ * `/panes` output, as plain lines. Pure so the contract test asserts the text
+ * an operator reads rather than the object behind it, and so the registry keeps
+ * its promise not to reach a renderer.
+ */
+function formatPanesStatus(status: PanesStatus): ReadonlyArray<string> {
+	const server = status.server ? `pane host ${status.server.version}, protocol ${status.server.protocol}` : "no server";
+	const lines = [
+		`panes: mode=${status.mode} ${status.available ? "available" : "unavailable"} (${server})`,
+		`  ${status.reason}`,
+		...(status.socketPath ? [`  socket ${status.socketPath}`] : []),
+		`  settings: enabled=${status.settings.enabled} notifications=${status.settings.notifications} layout=${status.settings.layout} journal=${status.settings.journal}`,
+		`  files: enabled=${status.settings.yazi.enabled} mode=${status.settings.yazi.mode} profile=${status.settings.yazi.profile} followCwd=${status.settings.yazi.followCwd}`,
+		`  file pane: mode=${status.yazi.mode} pane=${status.yazi.paneId ?? "none"} cwd=${status.yazi.paneCwd ?? "unknown"} lastLine=${status.yazi.lastLineAt === null ? "never" : new Date(status.yazi.lastLineAt).toISOString()} dropped=${status.yazi.droppedLines}`,
+	];
+	if (status.docks.length > 0) {
+		lines.push(
+			`  docks: ${status.docks
+				.map((dock) => `${dock.slot}=${dock.paneId} @${(dock.targetShare * 100).toFixed(0)}%`)
+				.join(", ")}`,
+		);
+	}
+	if (status.panes.length === 0) {
+		lines.push("  no Clio-owned panes");
+	} else {
+		lines.push(`  ${status.panes.length} Clio-owned pane(s):`);
+		for (const pane of status.panes) {
+			const adopted = pane.adopted ? " adopted" : "";
+			const pending = pane.pending ? " opening" : "";
+			lines.push(`    ${pane.paneId} ${pane.purpose} ${pane.label}${adopted}${pending}`);
+		}
+	}
+	lines.push(`  presets: ${PANES_PRESETS.map((preset) => `${preset.id} (${preset.summary})`).join(", ")}`);
+	return lines;
+}
+
 export const BUILTIN_SLASH_COMMANDS: ReadonlyArray<BuiltinSlashCommand> = [
 	{
 		name: "quit",
 		description: "Exit Clio Coder",
-		group: "Sessions",
+		group: "Session",
 		kinds: ["quit"],
 		args: {},
 		fromArgs: fromArgsOrUsage("quit", { kind: "quit" }),
@@ -795,7 +902,7 @@ export const BUILTIN_SLASH_COMMANDS: ReadonlyArray<BuiltinSlashCommand> = [
 	{
 		name: "skill",
 		description: "Open the Skills Hub or invoke a skill",
-		group: "Run",
+		group: "Work",
 		kinds: ["skill-selector", "skill-invocation"],
 		args: {
 			positionals: [
@@ -822,65 +929,74 @@ export const BUILTIN_SLASH_COMMANDS: ReadonlyArray<BuiltinSlashCommand> = [
 		},
 	},
 	{
-		name: "library",
-		description: "Open the Skills Hub on a resource library tab",
-		group: "Run",
-		kinds: ["library"],
-		args: { positionals: [{ name: "kind", required: false }] },
+		name: "resources",
+		description: "Browse skills, prompts, libraries, and extensions",
+		group: "Inspect",
+		kinds: ["resources"],
+		subcommandDescriptions: {
+			skills: "Browse installed skills",
+			prompts: "Browse prompt templates",
+			library: "Browse resource libraries",
+			extensions: "Browse installed extensions",
+		},
+		args: {
+			subcommands: {
+				skills: {},
+				prompts: {},
+				library: { positionals: [{ name: "kind", required: false }] },
+				extensions: {},
+			},
+		},
 		fromArgs(parsed) {
-			if (parsed.error) return { kind: "usage-error", command: "library", reason: parsed.error };
+			if (parsed.error) return { kind: "usage-error", command: "resources", reason: parsed.error };
+			if (parsed.subcommand === undefined || parsed.subcommand === "skills")
+				return { kind: "resources", family: "skills" };
+			if (parsed.subcommand === "prompts" || parsed.subcommand === "extensions")
+				return { kind: "resources", family: parsed.subcommand };
 			const tab = parsed.positionals[0];
-			if (tab === undefined) return { kind: "library" };
+			if (tab === undefined) return { kind: "resources" };
 			if (!isLibraryTab(tab)) {
 				const known = LIBRARY_TABS.map((entry) => entry.id).join(", ");
-				return { kind: "usage-error", command: "library", reason: `Unknown kind: ${tab} (one of ${known})` };
+				return { kind: "usage-error", command: "resources", reason: `Unknown kind: ${tab} (one of ${known})` };
 			}
-			return { kind: "library", tab };
+			return { kind: "resources", tab };
 		},
 		handle(command, ctx) {
-			if (command.kind === "library") ctx.openSkillsHub?.(command.tab);
-		},
-	},
-	{
-		name: "prompts",
-		description: "List prompt templates",
-		group: "Inspect",
-		kinds: ["prompts"],
-		args: {},
-		fromArgs: fromArgsOrUsage("prompts", { kind: "prompts" }),
-		handle(_command, ctx) {
-			ctx.openPrompts();
+			if (command.kind !== "resources") return;
+			if (command.family === "prompts") ctx.openPrompts();
+			else if (command.family === "extensions") ctx.openExtensions();
+			else ctx.openSkillsHub?.(command.tab);
 		},
 	},
 	{
-		name: "extensions",
-		description: "List installed extensions",
-		group: "Inspect",
-		kinds: ["extensions"],
-		args: {},
-		fromArgs: fromArgsOrUsage("extensions", { kind: "extensions" }),
-		handle(_command, ctx) {
-			ctx.openExtensions?.();
+		name: "share",
+		description: "Share a worker result with the main agent",
+		group: "Work",
+		kinds: ["share"],
+		args: { positionals: [{ name: "run-id", required: false }] },
+		fromArgs(parsed) {
+			const retiredArchiveVerb = parsed.positionals[0];
+			if (retiredArchiveVerb === "export" || retiredArchiveVerb === "import") {
+				return {
+					kind: "usage-error",
+					command: "share",
+					reason: `/share ${retiredArchiveVerb} is retired and did not run; use /archive ${retiredArchiveVerb}`,
+				};
+			}
+			if (parsed.error) return { kind: "usage-error", command: "share", reason: parsed.error };
+			return { kind: "share", ...(parsed.positionals[0] ? { runId: parsed.positionals[0] } : {}) };
 		},
-	},
-	{
-		name: "interop",
-		description: "Review other coding agents detected on this machine",
-		group: "Inspect",
-		kinds: ["interop"],
-		args: {},
-		fromArgs: fromArgsOrUsage("interop", { kind: "interop" }),
-		handle(_command, ctx) {
-			ctx.openInterop?.();
+		handle(command, ctx) {
+			if (command.kind === "share") shareWorkerRun(command.runId, ctx);
 		},
 	},
 	{
-		name: "share",
-		description: "Share a worker result with the main agent, or export and import Clio archives",
-		group: "Sessions",
-		kinds: ["share"],
+		name: "archive",
+		description: "Export or import a full Clio archive",
+		group: "Session",
+		kinds: ["archive-export", "archive-import", "archive-usage"],
+		subcommandDescriptions: { export: "Export a full Clio archive", import: "Import a full Clio archive" },
 		args: {
-			positionals: [{ name: "runId", required: false }],
 			subcommands: {
 				export: {
 					positionals: [{ name: "path", required: true }],
@@ -895,56 +1011,43 @@ export const BUILTIN_SLASH_COMMANDS: ReadonlyArray<BuiltinSlashCommand> = [
 			const subcommand = parsed.subcommand === "export" || parsed.subcommand === "import" ? parsed.subcommand : undefined;
 			if (parsed.error) {
 				return {
-					kind: "share",
-					action: "usage",
+					kind: "archive-usage",
 					...(subcommand !== undefined ? { subcommand } : {}),
 					error: parsed.error,
 				};
 			}
 			const path = parsed.positionals[0];
-			if (subcommand === "export" && path !== undefined) return { kind: "share", action: "export", path };
+			if (subcommand === "export" && path !== undefined) return { kind: "archive-export", path };
 			if (subcommand === "import" && path !== undefined) {
 				return {
-					kind: "share",
-					action: "import",
+					kind: "archive-import",
 					path,
 					dryRun: parsed.flags.has("--dry-run"),
 					force: parsed.flags.has("--force"),
 				};
 			}
-			// No subcommand means the worker-result sense of the word, with or
-			// without a run id. `export` and `import` are the archive senses and are
-			// matched above, so neither reading can swallow the other.
-			if (subcommand === undefined) {
-				return { kind: "share", action: "worker-run", ...(path !== undefined ? { runId: path } : {}) };
-			}
-			return { kind: "share", action: "usage", ...(subcommand !== undefined ? { subcommand } : {}) };
+			return { kind: "archive-usage", ...(subcommand !== undefined ? { subcommand } : {}) };
 		},
 		handle(command, ctx) {
-			if (command.kind !== "share") return;
-			if (command.action === "worker-run") {
-				shareWorkerRun(command.runId, ctx);
-				return;
-			}
-			if (command.action === "usage") {
-				const entry = BUILTIN_SLASH_COMMANDS.find((candidate) => candidate.name === "share");
+			if (command.kind === "archive-usage") {
+				const entry = BUILTIN_SLASH_COMMANDS.find((candidate) => candidate.name === "archive");
 				if (!entry) return;
 				const usage = usageNotice(entry, command.subcommand);
 				ctx.notice("info", command.error ? `${command.error}\n${usage}` : usage);
 				return;
 			}
-			if (command.action === "export") {
+			if (command.kind === "archive-export") {
 				if (!ctx.exportShareArchive) {
-					ctx.notice("error", "share export is not wired");
+					ctx.notice("error", "archive export is not wired");
 					return;
 				}
 				const result = ctx.exportShareArchive(command.path);
 				ctx.notice("success", `exported ${result.fileCount} item(s) to ${result.path}`);
 				return;
 			}
-			if (command.action === "import") {
+			if (command.kind === "archive-import") {
 				if (!ctx.importShareArchive) {
-					ctx.notice("error", "share import is not wired");
+					ctx.notice("error", "archive import is not wired");
 					return;
 				}
 				const plan = ctx.importShareArchive(command.path, { dryRun: command.dryRun, force: command.force });
@@ -965,7 +1068,7 @@ export const BUILTIN_SLASH_COMMANDS: ReadonlyArray<BuiltinSlashCommand> = [
 	{
 		name: "run",
 		description: "Run a fleet agent",
-		group: "Run",
+		group: "Work",
 		kinds: ["run", "run-usage"],
 		args: {
 			parseFlagsBeforeRest: true,
@@ -1056,7 +1159,7 @@ export const BUILTIN_SLASH_COMMANDS: ReadonlyArray<BuiltinSlashCommand> = [
 	{
 		name: "delegate",
 		description: "Run an ACP delegation agent",
-		group: "Run",
+		group: "Work",
 		kinds: ["delegate", "delegate-usage"],
 		args: {
 			parseFlagsBeforeRest: true,
@@ -1103,7 +1206,7 @@ export const BUILTIN_SLASH_COMMANDS: ReadonlyArray<BuiltinSlashCommand> = [
 	{
 		name: "btw",
 		description: "Ask a side question that never enters the session transcript",
-		group: "Run",
+		group: "Work",
 		kinds: ["btw", "btw-usage"],
 		args: {
 			positionals: [{ name: "question", required: true, rest: true }],
@@ -1126,7 +1229,7 @@ export const BUILTIN_SLASH_COMMANDS: ReadonlyArray<BuiltinSlashCommand> = [
 	{
 		name: "oracle",
 		description: "Ask a read-only advisor to challenge a question against this session's settled decisions",
-		group: "Run",
+		group: "Work",
 		kinds: ["oracle", "oracle-usage"],
 		args: {
 			positionals: [{ name: "question", required: true, rest: true }],
@@ -1152,7 +1255,7 @@ export const BUILTIN_SLASH_COMMANDS: ReadonlyArray<BuiltinSlashCommand> = [
 	{
 		name: "council",
 		description: "Ask a roster of read-only members the same task, with an optional vote or judge synthesis",
-		group: "Run",
+		group: "Work",
 		kinds: ["council", "council-usage"],
 		args: {
 			parseFlagsBeforeRest: true,
@@ -1204,16 +1307,24 @@ export const BUILTIN_SLASH_COMMANDS: ReadonlyArray<BuiltinSlashCommand> = [
 	},
 	{
 		name: "agents",
-		description: "List Clio agents and ACP delegation agents",
+		description: "List agents or connect a detected external agent",
 		group: "Inspect",
 		kinds: ["agents"],
-		args: {},
-		fromArgs: fromArgsOrUsage("agents", { kind: "agents" }),
-		handle(_command, ctx) {
-			ctx.openAgents();
+		subcommandDescriptions: {
+			list: "List native and external agents",
+			connect: "Review detected external-agent proposals",
+		},
+		args: { subcommands: { list: {}, connect: {} } },
+		fromArgs(parsed) {
+			if (parsed.error) return { kind: "usage-error", command: "agents", reason: parsed.error };
+			return { kind: "agents", ...(parsed.subcommand === "connect" ? { connect: true } : {}) };
+		},
+		handle(command, ctx) {
+			if (command.kind !== "agents") return;
+			if (command.connect) ctx.openInterop?.();
+			else ctx.openAgents();
 		},
 	},
-	settingsDeepLink("targets", "targets", "Open Settings → Targets: health, use, connect, probe, remove"),
 	{
 		name: "cost",
 		description: "Show session token and cost totals",
@@ -1298,9 +1409,9 @@ export const BUILTIN_SLASH_COMMANDS: ReadonlyArray<BuiltinSlashCommand> = [
 	},
 	{
 		name: "fleet",
-		description: "Open Settings → Fleet, or run a fleet contract with an approval preview",
-		group: "Configure",
-		kinds: ["fleet-run", "fleet-run-usage"],
+		description: "Open Fleet Runs or run a fleet contract with an approval preview",
+		group: "Work",
+		kinds: ["fleet", "fleet-run", "fleet-run-usage"],
 		subcommandDescriptions: { run: "Preview and run a repo-owned fleet contract" },
 		args: {
 			subcommands: {
@@ -1310,17 +1421,9 @@ export const BUILTIN_SLASH_COMMANDS: ReadonlyArray<BuiltinSlashCommand> = [
 				},
 			},
 		},
-		/**
-		 * `/fleet` alone keeps the settings deep link it has always been, and
-		 * only `run` parses as a command of its own, so an operator who types
-		 * `/fleet` out of habit still lands in Settings → Fleet. Anything else
-		 * on the line stays the usage error every other deep link reports.
-		 */
 		fromArgs(parsed) {
 			if (parsed.subcommand !== "run") {
-				return parsed.error
-					? { kind: "usage-error", command: "fleet", reason: parsed.error }
-					: { kind: "settings", section: "fleet" };
+				return parsed.error ? { kind: "usage-error", command: "fleet", reason: parsed.error } : { kind: "fleet" };
 			}
 			if (parsed.error) return { kind: "fleet-run-usage", reason: parsed.error };
 			const name = parsed.positionals[0] ?? "";
@@ -1335,6 +1438,11 @@ export const BUILTIN_SLASH_COMMANDS: ReadonlyArray<BuiltinSlashCommand> = [
 			return { kind: "fleet-run", name, vars };
 		},
 		handle(command, ctx) {
+			if (command.kind === "fleet") {
+				if (ctx.openFleetRuns) ctx.openFleetRuns();
+				else ctx.notice("error", "Fleet Runs is not wired in this session");
+				return;
+			}
 			if (command.kind === "fleet-run-usage") {
 				const entry = BUILTIN_SLASH_COMMANDS.find((candidate) => candidate.name === "fleet");
 				const usage = entry ? usageNotice(entry, "run") : "usage: /fleet run <name> [--var key=value ...]";
@@ -1505,32 +1613,178 @@ export const BUILTIN_SLASH_COMMANDS: ReadonlyArray<BuiltinSlashCommand> = [
 			}
 			if (command.kind !== "view-verify") return;
 			const result = ctx.verifyReceipt(command.runId);
+			const block = formatReceiptVerificationBlock(command.runId, result);
 			if (result.ok) {
-				ctx.notice("success", `verify ok ${command.runId}`);
+				ctx.notice(result.compromised ? "warn" : "success", block);
 			} else if (result.retired !== undefined) {
 				// A retired seal is the expected state of a run from the previous
 				// release, so it is a warning that names the versions, never the
 				// failure a tampered receipt gets.
-				ctx.notice("warn", `verify retired ${command.runId} ${result.reason}`);
+				ctx.notice("warn", block);
 			} else {
-				ctx.notice("error", `verify fail ${command.runId} ${result.reason}`);
+				ctx.notice("error", block);
+			}
+		},
+	},
+	{
+		name: "panes",
+		description: "Inspect the pane layer, watch a live run in a pane, or open a utility pane",
+		group: "Inspect",
+		kinds: ["panes", "panes-show", "panes-open", "panes-zoom", "panes-close", "panes-usage"],
+		args: {
+			subcommands: {
+				show: { positionals: [{ name: "run-or-agent", required: true }] },
+				// A rest positional, so an argv pane keeps its own flags: the parser
+				// would otherwise refuse `--follow` as an unknown flag of `/panes`.
+				open: { positionals: [{ name: "preset-or-argv", required: true, rest: true }] },
+				zoom: { positionals: [{ name: "target", required: false }] },
+				close: { positionals: [{ name: "target", required: false }] },
+			},
+		},
+		subcommandDescriptions: {
+			show: "watch a live run or agent in the watch pane",
+			open: `open a utility pane (${PANES_PRESET_IDS.join(", ")}, or a command)`,
+			zoom: "toggle zoom on a Clio-owned pane (default: the watch pane)",
+			close: "close a Clio-owned pane, or all of them",
+		},
+		fromArgs(parsed) {
+			if (parsed.error) return { kind: "panes-usage", reason: parsed.error };
+			if (parsed.subcommand === "show") {
+				return { kind: "panes-show", target: parsed.positionals[0] ?? "" };
+			}
+			if (parsed.subcommand === "open") {
+				const rest = (parsed.rest ?? "").trim();
+				if (rest.length === 0) return { kind: "panes-usage", reason: "Missing required argument: preset-or-argv" };
+				const argv = rest.split(/\s+/).filter((token) => token.length > 0);
+				const first = argv[0] ?? "";
+				// A bare preset name is a preset; anything else is operator argv,
+				// which the tool surface deliberately cannot ask for.
+				if (argv.length === 1 && isPanesPresetId(first)) return { kind: "panes-open", preset: first };
+				if (argv.length === 2 && first === "yazi" && argv[1] === "--once") {
+					return { kind: "panes-open", preset: "yazi", once: true };
+				}
+				return { kind: "panes-open", argv };
+			}
+			if (parsed.subcommand === "zoom") {
+				return { kind: "panes-zoom", target: parsed.positionals[0] ?? "" };
+			}
+			if (parsed.subcommand === "close") {
+				return { kind: "panes-close", target: parsed.positionals[0] ?? "all" };
+			}
+			if (parsed.positionals.length > 0) {
+				return { kind: "panes-usage", reason: `Unexpected argument: ${parsed.positionals[0]}` };
+			}
+			return { kind: "panes" };
+		},
+		handle(command, ctx) {
+			const entry = BUILTIN_SLASH_COMMANDS.find((candidate) => candidate.name === "panes");
+			if (command.kind === "panes-usage") {
+				// usageNotice trims the leading newline usageLine carries, so the reason
+				// and the usage line need their own separator or they run together as
+				// `Missing required argument: run-or-agentusage: /panes show ...`.
+				if (entry) ctx.notice("info", command.reason ? `${command.reason}\n${usageNotice(entry)}` : usageNotice(entry));
+				return;
+			}
+			const panes = ctx.panes;
+			if (!panes) {
+				// Inactive by choice, not unavailable: the operations object exists in
+				// every `--with-panes` session, even one where no pane host answered.
+				ctx.notice(
+					"info",
+					"panes are inactive: this session started without them. Restart with `clio-coder --with-panes`, or set panes.enabled=auto",
+				);
+				return;
+			}
+			const runLocal = ctx.runLocalOperation ?? ((operation: () => Promise<void>) => void operation());
+			if (command.kind === "panes") {
+				runLocal(async () => {
+					for (const line of formatPanesStatus(panes.status())) ctx.io.stdout(`${line}\n`);
+					ctx.render();
+				});
+				return;
+			}
+			if (command.kind === "panes-show") {
+				runLocal(async () => {
+					const result = await panes.show(command.target);
+					if (result.status === "watching") {
+						ctx.notice("success", `watching ${result.agentId} (${result.runId})${result.opened ? " in a new pane" : ""}`);
+					} else if (result.status === "not-found") {
+						const known = result.candidates.length > 0 ? `; live runs: ${result.candidates.join(", ")}` : "";
+						ctx.notice("warn", `no live run matches ${result.target}${known}`);
+					} else {
+						ctx.notice("warn", result.reason);
+					}
+				});
+				return;
+			}
+			if (command.kind === "panes-open") {
+				runLocal(async () => {
+					const result = await panes.open({
+						...(command.preset ? { preset: command.preset } : {}),
+						...(command.argv ? { argv: command.argv } : {}),
+						...(command.once ? { once: true } : {}),
+					});
+					if (result.status === "opened") {
+						// The in-terminal chooser has already restored the TUI by the
+						// time this resolves. A pick emitted its composer notice; an empty
+						// chooser was cancellation and deliberately stays silent.
+						if (result.paneId !== null) ctx.notice("success", `opened pane ${result.label} (${result.paneId})`);
+					} else if (result.status === "missing-binary") {
+						// This is a synchronous slash-surface line, not a transient pane-host
+						// notification. It remains visible when no pane was ever created and
+						// reuses the exact doctor/tools diagnostic including the install hint.
+						ctx.io.stdout(`${result.detail}\n`);
+						ctx.render();
+					} else {
+						ctx.notice("warn", result.reason);
+					}
+				});
+				return;
 			}
+			if (command.kind === "panes-zoom") {
+				runLocal(async () => {
+					const result = await panes.zoom(command.target);
+					if (result.status === "zoomed") {
+						ctx.notice("success", `toggled zoom on ${result.label} (${result.paneId})`);
+					} else if (result.status === "not-found") {
+						ctx.notice("warn", `no Clio-owned pane matches ${result.target}`);
+					} else {
+						ctx.notice("warn", result.reason);
+					}
+				});
+				return;
+			}
+			if (command.kind !== "panes-close") return;
+			runLocal(async () => {
+				const result = await panes.close(command.target);
+				if (result.status === "closed") {
+					const what = result.labels.length > 0 ? `: ${result.labels.join(", ")}` : "";
+					ctx.notice(result.closed > 0 ? "success" : "info", `closed ${result.closed} pane(s)${what}`);
+				} else if (result.status === "not-found") {
+					ctx.notice("warn", `no Clio-owned pane matches ${result.target}`);
+				} else {
+					ctx.notice("warn", result.reason);
+				}
+			});
 		},
 	},
 	{
 		name: "thinking",
-		description: "Set the chat thinking level, or open Settings → Orchestrator",
+		description: "Set the chat thinking level",
 		group: "Configure",
-		kinds: ["thinking-set"],
+		kinds: ["thinking-set", "thinking-picker"],
 		args: { positionals: [{ name: "level", required: false }] },
 		fromArgs(parsed) {
 			if (parsed.error) return { kind: "usage-error", command: "thinking", reason: parsed.error };
 			const level = parsed.positionals[0];
-			return level
-				? { kind: "thinking-set", level }
-				: { kind: "settings", section: "orchestrator", rowId: "orchestrator.thinkingLevel" };
+			return level ? { kind: "thinking-set", level } : { kind: "thinking-picker" };
 		},
 		handle(command, ctx) {
+			if (command.kind === "thinking-picker") {
+				if (ctx.openThinkingPicker) ctx.openThinkingPicker();
+				else ctx.notice("error", "thinking picker is not wired in this session");
+				return;
+			}
 			if (command.kind !== "thinking-set") return;
 			const result = ctx.setThinkingLevel?.(command.level) ?? { status: "unavailable" as const };
 			if (result.status === "applied") {
@@ -1545,18 +1799,21 @@ export const BUILTIN_SLASH_COMMANDS: ReadonlyArray<BuiltinSlashCommand> = [
 	},
 	{
 		name: "output",
-		description: "Set transcript detail (minimal, default, verbose), or open Settings → Terminal",
+		description: "Set transcript detail to minimal, default, or verbose",
 		group: "Configure",
-		kinds: ["output-set"],
+		kinds: ["output-set", "output-picker"],
 		args: { positionals: [{ name: "verbosity", required: false }] },
 		fromArgs(parsed) {
 			if (parsed.error) return { kind: "usage-error", command: "output", reason: parsed.error };
 			const verbosity = parsed.positionals[0];
-			return verbosity
-				? { kind: "output-set", verbosity }
-				: { kind: "settings", section: "terminal", rowId: "terminal.outputVerbosity" };
+			return verbosity ? { kind: "output-set", verbosity } : { kind: "output-picker" };
 		},
 		handle(command, ctx) {
+			if (command.kind === "output-picker") {
+				if (ctx.openOutputPicker) ctx.openOutputPicker();
+				else ctx.notice("error", "output picker is not wired in this session");
+				return;
+			}
 			if (command.kind !== "output-set") return;
 			const result = ctx.setOutputVerbosity?.(command.verbosity) ?? { status: "unavailable" as const };
 			if (result.status === "applied") {
@@ -1604,43 +1861,49 @@ export const BUILTIN_SLASH_COMMANDS: ReadonlyArray<BuiltinSlashCommand> = [
 					return;
 				}
 				if (result.warning) ctx.notice("warn", result.warning);
-				ctx.applyModelRef(result.ref);
-				const suffix = result.ref.thinkingLevel ? ` thinking=${result.ref.thinkingLevel}` : "";
-				ctx.notice("success", `active: ${result.ref.target}/${result.ref.model}${suffix}`);
+				// "pending" means the scope dialog is up: it says what landed and
+				// where, so announcing a swap here would be announcing a choice the
+				// operator has not made yet.
+				if (ctx.applyModelRef(result.ref) === "applied") {
+					const suffix = result.ref.thinkingLevel ? ` thinking=${result.ref.thinkingLevel}` : "";
+					ctx.notice("success", `active this session: ${result.ref.target}/${result.ref.model}${suffix}`);
+				}
 				ctx.render();
 			})();
 		},
 	},
-	settingsDeepLink(
-		"scoped-models",
-		"models",
-		"Open Settings → Models: the Alt+J / Alt+K cycle set and favorites",
-		"scope",
-	),
 	{
 		name: "settings",
 		description: "Open interactive settings",
 		group: "Configure",
 		kinds: ["settings"],
-		args: { positionals: [{ name: "section", required: false }] },
+		args: {
+			positionals: [
+				{ name: "area", required: false },
+				{ name: "group", required: false },
+			],
+		},
 		fromArgs(parsed) {
 			if (parsed.error) return { kind: "usage-error", command: "settings", reason: parsed.error };
-			const section = parsed.positionals[0];
-			if (section === undefined) return { kind: "settings" };
-			if (!isSettingsSectionId(section)) {
-				const known = SETTINGS_SECTIONS.map((entry) => entry.id).join(", ");
-				return { kind: "usage-error", command: "settings", reason: `Unknown section: ${section} (one of ${known})` };
+			const area = parsed.positionals[0];
+			if (area === undefined) return { kind: "settings" };
+			if (!isSettingsAreaId(area)) {
+				return {
+					kind: "usage-error",
+					command: "settings",
+					reason: `Unknown area: ${area} (one of ${SETTINGS_AREA_IDS.join(", ")})`,
+				};
 			}
-			return { kind: "settings", section };
+			return { kind: "settings", area, ...(parsed.positionals[1] ? { group: parsed.positionals[1] } : {}) };
 		},
 		handle(command, ctx) {
-			if (command.kind === "settings") ctx.openSettings(command.section, command.rowId);
+			if (command.kind === "settings") ctx.openSettings(command.area, command.group);
 		},
 	},
 	{
 		name: "resume",
 		description: "Resume a past session",
-		group: "Sessions",
+		group: "Session",
 		kinds: ["resume"],
 		args: {},
 		fromArgs: fromArgsOrUsage("resume", { kind: "resume" }),
@@ -1651,7 +1914,7 @@ export const BUILTIN_SLASH_COMMANDS: ReadonlyArray<BuiltinSlashCommand> = [
 	{
 		name: "new",
 		description: "Start a fresh session",
-		group: "Sessions",
+		group: "Session",
 		kinds: ["new"],
 		args: {},
 		fromArgs: fromArgsOrUsage("new", { kind: "new" }),
@@ -1662,7 +1925,7 @@ export const BUILTIN_SLASH_COMMANDS: ReadonlyArray<BuiltinSlashCommand> = [
 	{
 		name: "handoff",
 		description: "Hand this session's working state to a fresh session for a stated goal",
-		group: "Sessions",
+		group: "Session",
 		kinds: ["handoff", "handoff-usage"],
 		args: {
 			positionals: [{ name: "goal", required: true, rest: true }],
@@ -1685,7 +1948,7 @@ export const BUILTIN_SLASH_COMMANDS: ReadonlyArray<BuiltinSlashCommand> = [
 	{
 		name: "tree",
 		description: "Open session tree navigator",
-		group: "Sessions",
+		group: "Session",
 		kinds: ["tree"],
 		args: {},
 		fromArgs: fromArgsOrUsage("tree", { kind: "tree" }),
@@ -1696,7 +1959,7 @@ export const BUILTIN_SLASH_COMMANDS: ReadonlyArray<BuiltinSlashCommand> = [
 	{
 		name: "fork",
 		description: "Fork from an assistant turn",
-		group: "Sessions",
+		group: "Session",
 		kinds: ["fork"],
 		args: {},
 		fromArgs: fromArgsOrUsage("fork", { kind: "fork" }),
@@ -1707,7 +1970,7 @@ export const BUILTIN_SLASH_COMMANDS: ReadonlyArray<BuiltinSlashCommand> = [
 	{
 		name: "export",
 		description: "Export a self-contained HTML transcript by default; a .md path writes Markdown",
-		group: "Sessions",
+		group: "Session",
 		kinds: ["export"],
 		args: {
 			positionals: [{ name: "path", required: false }],
@@ -1779,6 +2042,32 @@ const COMMAND_SHAPED_TOKEN = /^[A-Za-z][A-Za-z0-9:-]*$/u;
  */
 const COMMAND_ESCAPE = "\\/";
 
+const RETIRED_COMMAND_HINTS: Readonly<Record<string, string>> = Object.freeze({
+	status: "Use the footer or Alt+U for status; /cost, /context, and /fleet inspect their own domains.",
+	receipts: "Use /view or /view verify <run-id>.",
+	"context-init": "Use /context init.",
+	"context-clear": "Use /context reset for project context or /new for a fresh session.",
+	"context-view": "Use /context.",
+	compact: "Use /context compact [instructions].",
+	skills: "Use /skill or /resources skills.",
+	exit: "Use /quit.",
+	config: "Use /settings.",
+	ctx: "Use /context.",
+	models: "Use /model.",
+	clear: "Use /new for a fresh session or /context reset for project context.",
+	library: "Use /resources library [kind].",
+	prompts: "Use /resources prompts.",
+	extensions: "Use /resources extensions.",
+	interop: "Use /agents connect.",
+	targets: "Use /settings targets.",
+	"scoped-models": "Use /settings chat model-picker.",
+});
+
+function retiredCommandHint(token: string): string | undefined {
+	if (/^skills?:[^\s]+$/u.test(token)) return "Use /skill <name> [task].";
+	return RETIRED_COMMAND_HINTS[token];
+}
+
 /** Pure slash-command parser: no I/O, no side effects. Walks the registry in order. */
 export function parseSlashCommand(input: string): SlashCommand {
 	const trimmed = input.trim();
@@ -1808,6 +2097,12 @@ export function dispatchSlashCommand(command: SlashCommand, ctx: SlashCommandCon
 		return "accepted";
 	}
 	if (command.kind === "unknown-command") {
+		const retiredHint = retiredCommandHint(command.token);
+		if (retiredHint) {
+			ctx.notice("error", `/${command.token} is retired and did not run. ${retiredHint}`);
+			ctx.render();
+			return "rejected";
+		}
 		// The registry does not own the token, but a prompt template might. The
 		// parser stays pure, so the lookup happens here, and only for a spelling
 		// that matched no command: `/name` is how every other agent invokes the
@@ -1849,18 +2144,55 @@ export interface CommandReferenceEntry {
 	subcommandDescriptions?: Readonly<Record<string, string>>;
 }
 
+const COMMAND_ORDER = [
+	"run",
+	"fleet",
+	"delegate",
+	"council",
+	"oracle",
+	"btw",
+	"share",
+	"skill",
+	"agents",
+	"tasks",
+	"context",
+	"memory",
+	"view",
+	"panes",
+	"cost",
+	"decisions",
+	"resources",
+	"help",
+	"model",
+	"thinking",
+	"output",
+	"settings",
+	"new",
+	"resume",
+	"handoff",
+	"fork",
+	"tree",
+	"export",
+	"archive",
+	"quit",
+] as const;
+const COMMAND_ORDER_INDEX = new Map<string, number>(COMMAND_ORDER.map((name, index) => [name, index]));
+
 export function commandReference(): ReadonlyArray<CommandReferenceEntry> {
-	return BUILTIN_SLASH_COMMANDS.filter((entry) => entry.hidden !== true).map((entry) => {
-		const usage = usageLine(entry)
-			.replace(/^\nusage:\s*/, "")
-			.replace(/\n$/, "");
-		return {
-			name: entry.name,
-			usage,
-			description: entry.description,
-			group: entry.group,
-			...(entry.args ? { args: entry.args } : {}),
-			...(entry.subcommandDescriptions ? { subcommandDescriptions: entry.subcommandDescriptions } : {}),
-		};
-	});
+	return BUILTIN_SLASH_COMMANDS.filter((entry) => entry.hidden !== true)
+		.slice()
+		.sort((a, b) => (COMMAND_ORDER_INDEX.get(a.name) ?? 99) - (COMMAND_ORDER_INDEX.get(b.name) ?? 99))
+		.map((entry) => {
+			const usage = usageLine(entry)
+				.replace(/^\nusage:\s*/, "")
+				.replace(/\n$/, "");
+			return {
+				name: entry.name,
+				usage,
+				description: entry.description,
+				group: entry.group,
+				...(entry.args ? { args: entry.args } : {}),
+				...(entry.subcommandDescriptions ? { subcommandDescriptions: entry.subcommandDescriptions } : {}),
+			};
+		});
 }