@iowarp/clio-coder 0.3.9 → 0.4.1

package/src/cli/modes/print.ts

@@ -365,7 +365,7 @@ async function recordHeadlessMainAgentReceipt(input: {
 		staticCompositionHash: snapshot.staticCompositionHash,
 		promptSignature: snapshot.promptSignature,
 		toolSignature: snapshot.toolSignature,
-		clioVersion: readClioVersion(),
+		clioCoderVersion: readClioVersion(),
 		piMonoVersion: readPiMonoVersion(),
 		platform: process.platform,
 		nodeVersion: process.version,

package/src/cli/panes.ts

@@ -0,0 +1,35 @@
+import { printError } from "./shared.js";
+import { runToolsCommand } from "./tools.js";
+
+const HELP = `clio-coder panes install [--force] [--json]
+
+Install the pane multiplexer Clio drives. This is an alias for
+\`clio-coder tools install herdr\`; the toolchain command is where every pinned
+external program is managed, and \`clio-coder tools status herdr\` explains
+which copy Clio would run.
+`;
+
+/**
+ * The user-facing verb for the pane layer's one setup step.
+ *
+ * Panes are the feature; herdr is the program behind it. Naming the program in
+ * a command an operator types is a leak, so the alias exists and routes to the
+ * generic installer rather than the reverse.
+ */
+export async function runPanesCommand(argv: ReadonlyArray<string> = []): Promise<number> {
+	if (argv.includes("--help") || argv.includes("-h")) {
+		process.stdout.write(HELP);
+		return 0;
+	}
+	const [subcommand, ...rest] = argv;
+	if (subcommand === undefined) {
+		process.stdout.write(HELP);
+		return 2;
+	}
+	if (subcommand !== "install") {
+		printError(`unknown panes command: ${subcommand}`);
+		process.stderr.write(HELP);
+		return 2;
+	}
+	return runToolsCommand(["install", "herdr", ...rest]);
+}

package/src/cli/reset.ts

@@ -15,7 +15,7 @@ Each level clears exactly the root (or file) it names and nothing else.
 Levels (combinable except --all):
   --state       state root only (default). Holds every session transcript, so a
                 reset is the end of resume, /view, and the audit behind them.
-  --data        data root only: memory, evidence, evals (durable products)
+  --data        data root only: memory, evidence, evals, vendored tools (durable products)
   --cache       cache root only
   --auth        credentials.yaml only
   --config      settings.yaml only
@@ -42,7 +42,10 @@ Safety:
 const ROOT_NOTES: Readonly<Record<string, string>> = {
 	state:
 		"the state root holds every session transcript and the audit trail beside it; resume and /view lose their history",
-	data: "the data root holds durable products (memory, evidence, evals)",
+	// Vendored tools are named because they are the one durable product a reset
+	// cannot regenerate from anything local: getting them back is a download.
+	data:
+		"the data root holds durable products (memory, evidence, evals, and any vendored external tools, which a reinstall re-downloads)",
 };
 
 interface ParsedResetArgs {
@@ -128,7 +131,7 @@ function report(label: string, path: string): void {
  * `scratch/`, and every dispatch artifact written since that sentence was
  * typed. A list nobody has to maintain cannot drift from what the removal takes.
  */
-export function rootContents(path: string): string[] {
+function rootContents(path: string): string[] {
 	let entries: Dirent[];
 	try {
 		entries = readdirSync(path, { withFileTypes: true });

package/src/cli/run.ts

@@ -11,6 +11,7 @@ import { createContextDomainModule } from "../domains/context/runtime.js";
 import type { DispatchContract, DispatchRequest } from "../domains/dispatch/contract.js";
 import { agentRoleFactsResolver, requestExecutionRole } from "../domains/dispatch/execution-role.js";
 import { createDispatchDomainModule } from "../domains/dispatch/index.js";
+import { configureRunEventJournal } from "../domains/dispatch/run-event-journal.js";
 import type { RunReceipt } from "../domains/dispatch/types.js";
 import { ensureClioState, LifecycleDomainModule } from "../domains/lifecycle/index.js";
 import {
@@ -147,7 +148,7 @@ async function assemblePrompt(parsed: RunCliArgs): Promise<{
  * path, not a skill package, or validation failure such as a missing
  * description). Exported for contracts tests.
  */
-export function explicitSkillPathErrors(skillPaths: ReadonlyArray<string>): string[] {
+function explicitSkillPathErrors(skillPaths: ReadonlyArray<string>): string[] {
 	const errors: string[] = [];
 	for (const skillPath of skillPaths) {
 		const list = loadSkills({ disableDiscovery: true, explicitSkillPaths: [skillPath] });
@@ -158,6 +159,45 @@ export function explicitSkillPathErrors(skillPaths: ReadonlyArray<string>): stri
 	return errors;
 }
 
+/**
+ * The TUI's verdict for a command-shaped token the registry does not own,
+ * applied to a headless task. Returns the refusal message, or null when the
+ * task is not an unknown command.
+ *
+ * `parseSlashCommand` is the canonical shape test and the canonical registry
+ * walk, so a token that is one word of letters, digits, hyphens, or colons and
+ * names no command lands here exactly as it does in the editor. Prose keeps
+ * reaching the model: an absolute path such as `/home/user/notes` carries a
+ * separator and is not one word, and `\/tmp is full` is the same escape the
+ * editor honors.
+ *
+ * A prompt template claims the token before the refusal does. Only membership
+ * is checked, not expansion: a template that exists but refuses (an untrusted
+ * project root, an unreadable body) has its own message, which the headless
+ * boot path already prints from the expansion itself. Deciding that here would
+ * duplicate the trust rules and put two refusals on one token.
+ *
+ * Both modules are imported lazily, so a task that does not start with a slash
+ * pays for neither. The laziness is a startup-cost choice and nothing more: for
+ * bundle partitioning a dynamic import is worse than a static one, because a
+ * dynamically imported module becomes a chunk split point by itself. What keeps
+ * this edge safe is the other end. `slash-commands.ts` is a declared CLI seam
+ * whose own imports stay off the interactive render graph, so reaching it does
+ * not make this file a second reacher of the chunk the instant shell's Stage 0
+ * closure sits on. Boundaries rule6 in `tests/boundaries/check-boundaries.ts`
+ * holds both halves of that.
+ */
+async function unknownSlashCommandRefusal(task: string): Promise<string | null> {
+	if (!task.trim().startsWith("/")) return null;
+	const { parseSlashCommand } = await import("../interactive/slash-commands.js");
+	const command = parseSlashCommand(task);
+	if (command.kind !== "unknown-command") return null;
+	const { loadPromptTemplates } = await import("../domains/resources/index.js");
+	const templates = loadPromptTemplates({ cwd: process.cwd() });
+	if (templates.items.some((template) => template.name === command.token)) return null;
+	return `/${command.token} is not a command. Type /help for the list.`;
+}
+
 export async function runClioRun(
 	args: ReadonlyArray<string>,
 	options: { apiKey?: string; noContextFiles?: boolean; noSkills?: boolean; skillPaths?: ReadonlyArray<string> } = {},
@@ -218,6 +258,15 @@ export async function runClioRun(
 			if (!assembled) return 2;
 
 			if (parsed.agentId === undefined) {
+				// A mistyped slash command is a usage error, not a task. Refusing it
+				// here keeps it from booting a session and spending a model turn on a
+				// command that was never run, which is what the TUI has always done
+				// and what docs/extensions-and-sharing.md documents for both surfaces.
+				const slashRefusal = await unknownSlashCommandRefusal(assembled.prompt);
+				if (slashRefusal !== null) {
+					process.stderr.write(`clio-coder run: ${slashRefusal}\n`);
+					return 2;
+				}
 				// An explicit --target override is a one-run target; a missing id is an
 				// operator config error, not an assistant response. Reject it before the
 				// headless turn so the resolver diagnostic never streams to stdout as a
@@ -314,13 +363,22 @@ async function runDispatch(
 		createDispatchDomainModule({
 			getSettings: () => effectiveSettings,
 			autonomyOverride: parsed.autonomy !== undefined,
+			// This path iterates `handle.events` itself and builds no dispatch
+			// event registry, so the domain is the only thing that can write the
+			// run's durable transcript.
+			journalRunEvents: true,
 		}),
 		LifecycleDomainModule,
 	]);
 	const config = loaded.getContract<ConfigContract>("config");
 	const baseSettings = config?.get() ?? readSettings();
-	effectiveSettings =
-		parsed.autonomy === undefined ? baseSettings : { ...structuredClone(baseSettings), autonomy: parsed.autonomy };
+	// Install `panes.journal` the same way the interactive composition root
+	// does. The journal never reads settings.yaml itself: it sits on the
+	// dispatch event path, where a settings read would be both a cost and a
+	// throw site.
+	configureRunEventJournal(baseSettings.fleet.history.journal);
+	effectiveSettings = structuredClone(baseSettings);
+	if (parsed.autonomy !== undefined) effectiveSettings.safety.autonomy = parsed.autonomy;
 	const dispatch = loaded.getContract<DispatchContract>("dispatch");
 	if (!dispatch) {
 		process.stderr.write("dispatch domain unavailable\n");
@@ -336,19 +394,15 @@ async function runDispatch(
 			return 1;
 		}
 		const settings = effectiveSettings;
-		const profileTargetId = parsed.agentProfile ? settings.workers?.profiles?.[parsed.agentProfile]?.target : undefined;
+		const profileTargetId = parsed.agentProfile ? settings.fleet?.profiles?.[parsed.agentProfile]?.target : undefined;
 		const runtimeByTarget = new Map(settings.targets.map((target) => [target.id, target.runtime] as const));
 		const runtimeTargetId = parsed.agentRuntime
-			? [settings.workers?.default, ...Object.values(settings.workers?.profiles ?? {})].find(
+			? [settings.fleet?.default, ...Object.values(settings.fleet?.profiles ?? {})].find(
 					(profile) => profile?.target && runtimeByTarget.get(profile.target) === parsed.agentRuntime,
 				)?.target
 			: undefined;
 		const targetId =
-			parsed.target ??
-			profileTargetId ??
-			runtimeTargetId ??
-			settings.workers?.default?.target ??
-			settings.orchestrator?.target;
+			parsed.target ?? profileTargetId ?? runtimeTargetId ?? settings.fleet?.default?.target ?? settings.chat?.target;
 		const target = targetId ? providers.getTarget(targetId) : null;
 		const runtime = target ? providers.getRuntime(target.runtime) : null;
 		if (!target || !runtime) {
@@ -383,7 +437,7 @@ async function runDispatch(
 	if (skillPaths.length > 0) dispatchReq.skillPaths = skillPaths;
 	try {
 		const settings = effectiveSettings;
-		if (settings.skills?.trustProjectCompatRoots) {
+		if (settings.integrations.projectResources?.trustProjectImports) {
 			dispatchReq.trustProjectCompatRoots = true;
 		}
 	} catch {
@@ -393,8 +447,8 @@ async function runDispatch(
 	let memorySection = "";
 	try {
 		const records = loadMemoryRecordsSync(clioDataDir());
-		const boundProfileName = parsed.agentProfile ?? effectiveSettings.workers.agentBindings[parsed.agentId];
-		const boundProfile = boundProfileName ? effectiveSettings.workers.profiles[boundProfileName] : undefined;
+		const boundProfileName = parsed.agentProfile ?? effectiveSettings.fleet.agentProfiles[parsed.agentId];
+		const boundProfile = boundProfileName ? effectiveSettings.fleet.profiles[boundProfileName] : undefined;
 		const configuredRuntime = (targetId: string | null | undefined): string | undefined =>
 			effectiveSettings.targets.find((target) => target.id === targetId)?.runtime;
 		const profileRuntimeId = configuredRuntime(boundProfile?.target);

package/src/cli/share.ts

@@ -233,7 +233,7 @@ export function runShareCommand(argv: ReadonlyArray<string>): number {
 				const archive = plan.archive;
 				if (archive) {
 					process.stdout.write(
-						`archive: ${archive.manifest.format} clio=${archive.manifest.clioVersion} files=${archive.files.length} created=${archive.manifest.createdAt}\n`,
+						`archive: ${archive.manifest.format} clio-coder=${archive.manifest.clioCoderVersion} files=${archive.files.length} created=${archive.manifest.createdAt}\n`,
 					);
 				}
 			}

package/src/cli/skills-eval.ts

@@ -311,7 +311,7 @@ type EvalArm = "baseline" | "treatment" | "judge";
  *
  * @internal Exported for contract tests.
  */
-export function armRunArgs(
+function armRunArgs(
 	arm: EvalArm,
 	prompt: string,
 	options: { target?: string | undefined; skillBaseDir?: string | undefined } = {},
@@ -335,7 +335,7 @@ export function armRunArgs(
  *
  * @internal Exported for contract tests.
  */
-export function permissionWallReason(arm: EvalArm, run: CapturedRun): string | null {
+function permissionWallReason(arm: EvalArm, run: CapturedRun): string | null {
 	const haystack = `${run.transcript}\n${run.finalText}`;
 	let blocked = 0;
 	let at = haystack.indexOf(HEADLESS_PERMISSION_DENIED_MARKER);
@@ -360,7 +360,7 @@ function unmeasuredBullets(scenario: SkillEvalScenario, reason: string): ScoredB
  *
  * @internal Exported for contract tests.
  */
-export function evalChildEnv(allowNetwork: boolean, env: NodeJS.ProcessEnv = process.env): NodeJS.ProcessEnv {
+function evalChildEnv(allowNetwork: boolean, env: NodeJS.ProcessEnv = process.env): NodeJS.ProcessEnv {
 	const childEnv: NodeJS.ProcessEnv = { ...env };
 	if (allowNetwork) Reflect.deleteProperty(childEnv, NO_NETWORK_TOOLS_ENV);
 	else childEnv[NO_NETWORK_TOOLS_ENV] = "1";
@@ -378,7 +378,7 @@ export function evalChildEnv(allowNetwork: boolean, env: NodeJS.ProcessEnv = pro
  * the catalog answers only for a name no root installed, which is the skill
  * author's case in this repository.
  */
-export function resolveSkillBaseDir(
+function resolveSkillBaseDir(
 	nameOrPath: string,
 	cwd: string,
 ): { baseDir: string | null; origin?: string; error?: string } {
@@ -442,7 +442,7 @@ async function runScenario(
 	// Published per-scenario figure: monotonic so a clock correction during a
 	// long sweep cannot land in one row's wall time.
 	const scenarioStart = performance.now();
-	const workspace = await mkdtemp(join(tmpdir(), "clio-skill-eval-seed-"));
+	const workspace = await mkdtemp(join(tmpdir(), "clio-coder-skill-eval-seed-"));
 	let runWorkspaces: MaterializedSkillEvalWorkspaces | null = null;
 	try {
 		if (workspaceOverride !== null) await copyWorkspace(workspaceOverride, workspace);
@@ -570,7 +570,7 @@ export interface MaterializedSkillEvalWorkspaces {
  * cooperative model, not as an isolation guarantee.
  */
 async function armWorkspace(created: string[]): Promise<string> {
-	const root = await mkdtemp(join(tmpdir(), "clio-skill-eval-"));
+	const root = await mkdtemp(join(tmpdir(), "clio-coder-skill-eval-"));
 	created.push(root);
 	const workspace = join(root, "workspace");
 	await mkdir(workspace, { recursive: true });
@@ -578,7 +578,7 @@ async function armWorkspace(created: string[]): Promise<string> {
 }
 
 /** @internal Exported for contract tests. */
-export async function materializeSkillEvalWorkspaces(seedWorkspace: string): Promise<MaterializedSkillEvalWorkspaces> {
+async function materializeSkillEvalWorkspaces(seedWorkspace: string): Promise<MaterializedSkillEvalWorkspaces> {
 	const created: string[] = [];
 	try {
 		const baseline = await armWorkspace(created);
@@ -814,7 +814,7 @@ function loadsSkillBody(tool: string, args: unknown): boolean {
 }
 
 /** @internal Exported for contract tests. */
-export function parseRunStdout(stdout: string): { sessionId: string | null; transcript: string; finalText: string } {
+function parseRunStdout(stdout: string): { sessionId: string | null; transcript: string; finalText: string } {
 	let sessionId: string | null = null;
 	const lines: string[] = [];
 	let finalText = "";
@@ -938,7 +938,7 @@ function judgeVerdictAbsenceReason(judge: CapturedRun): string {
 }
 
 /** Exported for contracts tests. */
-export function parseJudgeVerdicts(scenario: SkillEvalScenario, judge: CapturedRun): ScoredBullet[] {
+function parseJudgeVerdicts(scenario: SkillEvalScenario, judge: CapturedRun): ScoredBullet[] {
 	const parsed = extractBulletsObject(judge.finalText) ?? extractBulletsObject(judge.transcript);
 	// No verdict object anywhere in the judge run. The scenario was not scored,
 	// which is a fact about the judge, so every bullet stays unmeasured rather
@@ -982,7 +982,7 @@ export function parseJudgeVerdicts(scenario: SkillEvalScenario, judge: CapturedR
  * content, so this walks candidate `{` openers around the first "bullets" key
  * and balance-scans to the matching close brace.
  */
-export function extractBulletsObject(text: string): Record<string, unknown> | null {
+function extractBulletsObject(text: string): Record<string, unknown> | null {
 	const stripped = text.replace(/```(?:json)?/g, "");
 	const bulletsAt = stripped.indexOf('"bullets"');
 	if (bulletsAt < 0) return null;
@@ -1085,7 +1085,7 @@ function synthesizeArtifact(
 		evalId,
 		taskFile: evalsPath,
 		taskFileHash: contentHash,
-		clio: evalClioProvenance(),
+		clioCoder: evalClioProvenance(),
 		environment: evalEnvironmentProvenance(),
 		target: target ?? null,
 		model: null,

package/src/cli/skills-inventory.ts

@@ -0,0 +1,185 @@
+/**
+ * Fixed machine-readable projection of this installation's installed skills.
+ *
+ * `skills list --json` already emits a machine-readable listing, and a GUI host
+ * reading it gets two things wrong. Without `--all` it sees only the skills the
+ * model may load, which is `trusted && !disableModelInvocation`, so a surface
+ * rendering trust and invocability off that payload prints "trusted" and
+ * "allowed" on every row and structurally cannot print anything else. And the
+ * rows it does get are the full loaded records, carrying the SKILL.md body, the
+ * file path, the base directory, and two content hashes, so every consumer has
+ * to re-derive the same redaction.
+ *
+ * This command answers both. It loads once, reports every installed skill
+ * whether or not the model can reach it, says which ones it can, and carries
+ * only fields that are safe by construction. It is a separate subcommand rather
+ * than a flag on `skills inspect`, because that one names a skill and a fixed
+ * read a host may run must take no identifier at all.
+ *
+ * Held back deliberately: the skill body, its file path, its base directory,
+ * both hashes, the install and registry URLs, and the free-text loader
+ * diagnostics. Whether a skill has an upstream to update from crosses; where
+ * that upstream is does not.
+ *
+ * Marketplace discovery is deliberately not here. `library list --json` already
+ * folds `discoverMarketplaceSkills` into its catalog, so every installable
+ * skill already crosses through that read, and a second one would report the
+ * same rows under a different name.
+ */
+
+import {
+	loadSkills,
+	type ResourceDiagnostic,
+	type Skill,
+	type SkillCatalogInvalidReason,
+	skillCatalogValidity,
+} from "../domains/resources/index.js";
+
+/** Wire bound on the emitted skill list. */
+const MAX_SKILLS_INVENTORY_SKILLS = 64;
+/** Wire bound on each skill's declared tool policy. */
+const MAX_SKILLS_INVENTORY_TOOLS = 32;
+
+const TOOL_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._:-]*$/;
+
+type SkillAuditState = "pass" | "warn" | "fail" | "unknown" | "not-reported";
+
+interface SkillsInventoryDiagnosticCounts {
+	readonly errors: number;
+	readonly warnings: number;
+	readonly collisions: number;
+}
+
+interface SkillsInventorySkill {
+	readonly name: string;
+	readonly description: string;
+	readonly scope: string;
+	readonly source: string;
+	/** Whether the skill's root is trusted enough for the model to see it at all. */
+	readonly trusted: boolean;
+	/** Whether the skill's own frontmatter permits model invocation. */
+	readonly modelInvocable: boolean;
+	/**
+	 * The effective answer, which is both of the above.
+	 *
+	 * Reported rather than left to be inferred because it is the fact an
+	 * operator is actually asking about, and because a listing filtered to it
+	 * cannot state it.
+	 */
+	readonly modelVisible: boolean;
+	readonly precedence: number;
+	readonly diagnostics: SkillsInventoryDiagnosticCounts;
+	/** Tools the skill narrows itself to. The harness intersects these with host policy. */
+	readonly allowedTools: readonly string[];
+	readonly disallowedTools: readonly string[];
+	/** True when a dispatched worker installed this, rather than the operator. */
+	readonly installedByWorker: boolean;
+	/** True when provenance records an upstream, so `skills update` has something to fetch. */
+	readonly updatable: boolean;
+	readonly audit: SkillAuditState;
+	readonly installedAt: string | null;
+	readonly updatedAt: string | null;
+}
+
+interface SkillsInventorySnapshot {
+	readonly version: 1;
+	readonly generatedAt: string;
+	/** The verdict `skills validate` reaches, from the rule both callers share. */
+	readonly valid: boolean;
+	readonly invalidReason: SkillCatalogInvalidReason | null;
+	/** Every installed skill the loader resolved, before the wire bound. */
+	readonly total: number;
+	/** How many of those the model may actually load by name. */
+	readonly modelVisible: number;
+	readonly diagnostics: SkillsInventoryDiagnosticCounts;
+	readonly skills: readonly SkillsInventorySkill[];
+	readonly skillsTruncated: boolean;
+}
+
+const AUDIT_STATES: ReadonlySet<string> = new Set(["pass", "warn", "fail", "unknown"]);
+
+function countDiagnostics(diagnostics: ReadonlyArray<ResourceDiagnostic>): SkillsInventoryDiagnosticCounts {
+	let errors = 0;
+	let warnings = 0;
+	let collisions = 0;
+	for (const diag of diagnostics) {
+		if (diag.type === "error") errors += 1;
+		else if (diag.type === "collision") collisions += 1;
+		else warnings += 1;
+	}
+	return { errors, warnings, collisions };
+}
+
+/**
+ * Tool names are already-crossing identifiers: the agent catalog carries the
+ * same class. They are re-enforced structurally here anyway, because a skill's
+ * frontmatter is operator-authored and the loader does not hold it to a shape.
+ */
+function toolPolicy(value: ReadonlyArray<string> | undefined): string[] {
+	if (value === undefined) return [];
+	const tools: string[] = [];
+	for (const tool of value) {
+		if (tools.length >= MAX_SKILLS_INVENTORY_TOOLS) break;
+		if (typeof tool !== "string" || tool.length > 64 || !TOOL_PATTERN.test(tool)) continue;
+		if (!tools.includes(tool)) tools.push(tool);
+	}
+	return tools;
+}
+
+function timestamp(value: string | undefined): string | null {
+	if (value === undefined) return null;
+	const parsed = Date.parse(value);
+	return Number.isFinite(parsed) ? new Date(parsed).toISOString() : null;
+}
+
+function projectSkill(skill: Skill): SkillsInventorySkill {
+	const provenance = skill.provenance;
+	const audit = provenance?.audit;
+	return {
+		name: skill.name,
+		description: skill.description,
+		scope: skill.scope,
+		source: skill.source,
+		trusted: skill.trusted,
+		modelInvocable: !skill.disableModelInvocation,
+		modelVisible: skill.trusted && !skill.disableModelInvocation,
+		precedence: skill.precedence,
+		diagnostics: countDiagnostics(skill.diagnostics),
+		allowedTools: toolPolicy(skill.allowedTools),
+		disallowedTools: toolPolicy(skill.disallowedTools),
+		installedByWorker: provenance?.installedBy === "worker",
+		// The URL itself is a host-side fact; that one exists is what tells the
+		// operator whether an update has anywhere to come from.
+		updatable: provenance?.installUrl !== undefined || provenance?.registryUrl !== undefined,
+		audit: audit !== undefined && AUDIT_STATES.has(audit) ? (audit as SkillAuditState) : "not-reported",
+		installedAt: timestamp(provenance?.installedAt),
+		updatedAt: timestamp(provenance?.updatedAt),
+	};
+}
+
+function skillsInventorySnapshot(now: () => number = Date.now, cwd: string = process.cwd()): SkillsInventorySnapshot {
+	const list = loadSkills({ cwd });
+	const validity = skillCatalogValidity(list);
+	const projected = list.items.map(projectSkill);
+	const skills = projected.slice(0, MAX_SKILLS_INVENTORY_SKILLS);
+	return {
+		version: 1,
+		generatedAt: new Date(now()).toISOString(),
+		valid: validity.ok,
+		invalidReason: validity.reason,
+		total: projected.length,
+		modelVisible: projected.filter((skill) => skill.modelVisible).length,
+		diagnostics: countDiagnostics(list.diagnostics),
+		skills,
+		skillsTruncated: skills.length < projected.length,
+	};
+}
+
+export function runSkillsInventory(args: ReadonlyArray<string>): number {
+	if (args.length !== 1 || args[0] !== "--json") {
+		process.stderr.write("clio-coder skills inventory: usage: clio-coder skills inventory --json\n");
+		return 2;
+	}
+	process.stdout.write(`${JSON.stringify(skillsInventorySnapshot(), null, 2)}\n`);
+	return 0;
+}

package/src/cli/skills.ts

@@ -8,6 +8,7 @@ import {
 	type ResourceDiagnostic,
 	type Skill,
 	type SkillUpdateReport,
+	skillCatalogValidity,
 	updateSkills,
 } from "../domains/resources/index.js";
 import { formatColumns, printError, printOk } from "./shared.js";
@@ -18,6 +19,7 @@ Manage local Clio and Agent Skills-compatible skills.
 
 Commands:
   clio-coder skills list [--json] [--all]
+  clio-coder skills inventory --json
   clio-coder skills search <query> [--json]
   clio-coder skills inspect <name> [--json]
   clio-coder skills validate [path] [--json]
@@ -27,6 +29,10 @@ Commands:
   clio-coder skills sync [--force]
   clio-coder skills eval <name|path> [--scenario <id>] [--target <id>] [--workspace <path>] [--timeout <seconds>] [--trust-fixtures] [--allow-network] [--json]
 
+inventory is the fixed machine-readable read a GUI host may run. Unlike a bare
+list it reports every installed skill, not only the ones the model may load, and
+says which are which; it carries no body, path, hash, or install URL.
+
 search covers installed skills plus the local marketplace: CLIO_CODER_SKILL_CATALOG_DIR,
 a repo skills/ catalog, or the catalog and skill-marketplace.json index the
 installed clio-coder package carries. Installing from the shipped catalog copies
@@ -249,6 +255,12 @@ function validationLoad(pathArg: string | undefined): ReturnType<typeof loadSkil
 }
 
 export async function runSkillsCommand(argv: ReadonlyArray<string>): Promise<number> {
+	// Routed before the shared parser so the fixed read stays exactly fixed: no
+	// skills flag can reach it, and no flag it does not name can be spent on it.
+	if (argv[0] === "inventory") {
+		const { runSkillsInventory } = await import("./skills-inventory.js");
+		return runSkillsInventory(argv.slice(1));
+	}
 	let parsed: Parsed;
 	try {
 		parsed = parse(argv);
@@ -365,19 +377,10 @@ export async function runSkillsCommand(argv: ReadonlyArray<string>): Promise<num
 				return 2;
 			}
 			const list = validationLoad(pathArg);
-			// A scanned file that produced no loaded skill is malformed, and a
-			// collision drops a skill: both make the catalog invalid, as does any
-			// hard error. Benign warnings (name/path mismatch, name format,
-			// description length) attach to a file that still loaded, so their path
-			// is among the loaded skills and they do not fail validation.
-			const loadedPaths = new Set(list.items.map((skill) => skill.filePath));
-			const hasInvalidDiagnostic = list.diagnostics.some(
-				(diag) =>
-					diag.type === "error" ||
-					diag.type === "collision" ||
-					(diag.type === "warning" && diag.path !== undefined && !loadedPaths.has(diag.path)),
-			);
-			const ok = list.items.length > 0 && !hasInvalidDiagnostic;
+			// The rule itself lives in the loader, because `skills inspect --json`
+			// reports the same verdict to a GUI host and a verdict that drifts
+			// between the terminal and the browser is worse than no verdict.
+			const { ok } = skillCatalogValidity(list);
 			if (parsed.json) {
 				process.stdout.write(`${JSON.stringify({ ok, skills: list.items, diagnostics: list.diagnostics }, null, 2)}\n`);
 			} else {