magus-cli 7.4.1 → 7.5.1

package/src/cli/install.ts

@@ -1,18 +1,18 @@
 /**
  * `magus install [profile] [--check] [--yes]`
  *
- * Materialize a committed team profile from .claude/profiles.json onto this
- * machine: register marketplaces, install pinned plugins, install the binaries
- * plugins declare (requires.bin) plus the profile's cliTools, install skills,
- * collect required env, then activate the profile via symlinks.
+ * Put a committed team profile from .claude/profiles.json onto this machine:
+ * register marketplaces, activate the profile (render its settings.json,
+ * .mcp.json and models.json, install its skills), install its pinned plugins
+ * and the binaries plugins declare (requires.bin) plus the profile's cliTools,
+ * then collect required env.
  *
- * With no argument it installs the union of every profile's deps and
- * materializes them all (so `profile switch` needs no reinstall), then
- * activates one. `--check` is a read-only drift gate for CI. `--yes` skips
+ * With no argument it installs the union of every profile's deps (so `profile
+ * switch` needs no reinstall) and keeps the active profile active, asking only
+ * when none is. `--check` is a read-only version gate for CI. `--yes` skips
  * the confirmation prompt.
  */
 
-import path from "node:path";
 import { installPlugin, isClaudeAvailable } from "../services/claude-cli.js";
 import {
 	getLocalSettingsPath,
@@ -20,45 +20,41 @@ import {
 	readLocalSettings,
 	writeLocalSettings,
 } from "../services/claude-settings.js";
-import { ensureGitignoreEntries } from "../services/conventions-manager.js";
 import {
 	computeEnvStatus,
 	computeVersionDrift,
 	summarizeClosure,
 } from "../services/install-plan.js";
-import { validateManifest } from "../services/manifest.js";
+import { readManifest, validateManifest } from "../services/manifest.js";
 import { registerClosureMarketplaces } from "../services/marketplace-sync.js";
+import {
+	clearMarketplaceCache,
+	readInstalledVersionForScope,
+} from "../services/plugin-manager.js";
 import { reportDisplaced } from "../services/profile-activate.js";
-import { materializeProfile } from "../services/profile-materializer.js";
-import { detectProfileDrift } from "../services/profile-sync.js";
+import { activeProfile } from "../services/profile-live.js";
+import {
+	switchToProfile,
+	withCliBookkeeping,
+} from "../services/profile-state.js";
 import { resolveAllProfiles, resolveProfile } from "../services/resolver.js";
 import { SettingsParseError, writableMap } from "../services/settings-file.js";
-import { installSkill } from "../services/skills-manager.js";
-import {
-	PROFILE_GITIGNORE_ENTRIES,
-	activateProfile,
-	activeProfile,
-} from "../services/symlink-manager.js";
 import {
 	TOOLCHAIN_BOOTSTRAP,
 	binInstallCommand,
 	detectToolchains,
 } from "../services/toolchain.js";
-import type {
-	ProfileSkillRef,
-	ResolvedBin,
-	ResolvedClosure,
-	SkillInfo,
-} from "../types/index.js";
+import { bringLoadForward } from "../services/update-engine.js";
+import type { ResolvedBin, ResolvedClosure } from "../types/index.js";
 import { formatCommand, resolveExecutable } from "../utils/command-utils.js";
 import { runCommand, runShellScript } from "../utils/run.js";
-import { ensureManifest } from "./bootstrap.js";
+import { ensureManifest, printActivationNotes } from "./bootstrap.js";
 import { confirm, promptValue } from "./prompt.js";
+import { note as noteLine } from "./update-view.js";
 
 interface InstallFlags {
 	check: boolean;
 	yes: boolean;
-	force: boolean;
 	profile?: string;
 }
 
@@ -66,12 +62,11 @@ function parseArgs(args: string[]): InstallFlags {
 	return {
 		check: args.includes("--check"),
 		yes: args.includes("--yes") || args.includes("-y"),
-		force: args.includes("--force"),
 		profile: args.find((a) => !a.startsWith("-")),
 	};
 }
 
-// ── --check: read-only drift gate ───────────────────────────────────────────
+// ── --check: read-only version gate ─────────────────────────────────────────
 
 async function runCheck(
 	closure: ResolvedClosure,
@@ -149,9 +144,10 @@ async function ensureToolchains(
  * Project scope keeps the blast radius to this repo. The plugin *cache* is
  * global either way, so `profile switch` stays offline.
  *
- * Whatever the CLI writes into .claude/settings.json here is transient:
- * materialization rewrites that file from the manifest, and activation replaces
- * it with a symlink. The manifest stays authoritative.
+ * The CLI records each install in the live `.claude/settings.json`. That is
+ * its bookkeeping, not a change to the profile — with no argument this installs
+ * EVERY profile's plugins — so the caller runs this inside
+ * `withCliBookkeeping`, which renders the live files over it afterwards.
  */
 async function installPlugins(closure: ResolvedClosure): Promise<void> {
 	for (const pluginId of Object.keys(closure.plugins)) {
@@ -164,6 +160,41 @@ async function installPlugins(closure: ResolvedClosure): Promise<void> {
 	}
 }
 
+/**
+ * After the installs: every plugin must LOAD the version installed here, not
+ * an older one from a registry row this repository's other checkouts left
+ * first in line. Where it does not, the same stale-load repair `magus update`
+ * chains is run, and reported either way.
+ */
+async function bringLoadsForward(
+	pluginIds: readonly string[],
+	projectPath: string,
+): Promise<void> {
+	for (const pluginId of pluginIds) {
+		const here = await readInstalledVersionForScope(
+			pluginId,
+			"project",
+			projectPath,
+		);
+		if (!here) continue;
+		const forward = await bringLoadForward(pluginId, here, projectPath);
+		if (!forward) continue;
+		if (forward.ok) {
+			console.log(
+				`✓ ${pluginId}: Claude Code now loads v${here} here (${forward.rewritten} older record${
+					forward.rewritten === 1 ? "" : "s"
+				} moved forward)`,
+			);
+		} else {
+			console.warn(
+				`⚠ ${pluginId}: installed v${here}, but Claude Code still loads v${
+					forward.loaded ?? "an older version"
+				} here — ${forward.error ?? "the older records could not be moved forward"}`,
+			);
+		}
+	}
+}
+
 async function installBins(bins: ResolvedBin[]): Promise<void> {
 	for (const bin of bins) {
 		if (await resolveExecutable(bin.name)) {
@@ -179,39 +210,6 @@ async function installBins(bins: ResolvedBin[]): Promise<void> {
 	}
 }
 
-/** Map a manifest skill ref to the SkillInfo shape installSkill expects. */
-function toSkillInfo(ref: ProfileSkillRef): SkillInfo {
-	return {
-		id: `${ref.repo}/${ref.path}`,
-		name: ref.name,
-		source: {
-			label: ref.repo,
-			repo: ref.repo,
-			skillsPath: path.dirname(ref.path),
-		},
-		repoPath: ref.path,
-		gitBlobSha: "",
-		frontmatter: null,
-		installed: false,
-		installedScope: null,
-		hasUpdate: false,
-	};
-}
-
-async function installSkills(
-	skills: ProfileSkillRef[],
-	projectPath: string,
-): Promise<void> {
-	for (const ref of skills) {
-		try {
-			console.log(`+ skill ${ref.name}`);
-			await installSkill(toSkillInfo(ref), "project", projectPath);
-		} catch (e) {
-			console.warn(`⚠ skill ${ref.name}: ${(e as Error).message}`);
-		}
-	}
-}
-
 async function collectEnv(
 	closure: ResolvedClosure,
 	projectPath: string,
@@ -303,35 +301,18 @@ export async function runInstallCommand(
 		return 1;
 	}
 
-	// Closure: a single profile, or the union of all.
-	const closure = flags.profile
-		? await resolveProfile(manifest, flags.profile)
-		: await resolveAllProfiles(manifest);
+	// Closure: a single profile, or the union of all — with every plugin the
+	// enabled ones depend on.
+	const resolveClosure = () =>
+		flags.profile
+			? resolveProfile(manifest, flags.profile)
+			: resolveAllProfiles(manifest);
+	let closure = await resolveClosure();
 
 	if (flags.check) {
 		return runCheck(closure, manifest.strictVersions === true);
 	}
 
-	// Drift guard: refuse to clobber unsynced local edits to the active profile
-	// (materialize would overwrite them) unless --force is given.
-	if (!flags.force) {
-		const active = await activeProfile(projectPath);
-		if (active && (flags.profile === undefined || flags.profile === active)) {
-			const drift = await detectProfileDrift(active, projectPath);
-			if (drift.length > 0) {
-				console.error(
-					`Active profile "${active}" has unsynced local edits that install would overwrite:`,
-				);
-				for (const c of drift) console.error(`  ${c.kind}: ${c.detail}`);
-				console.error(
-					"\nRun `magus profile sync` to promote them into .claude/profiles.json,\n" +
-						"or re-run with --force to discard them.",
-				);
-				return 1;
-			}
-		}
-	}
-
 	// Plan
 	console.log(`\nPlan for ${flags.profile ?? "all profiles"}:`);
 	for (const line of summarizeClosure(closure)) console.log(`  ${line}`);
@@ -357,45 +338,68 @@ export async function runInstallCommand(
 
 	await ensureToolchains(closure, flags.yes);
 	await registerClosureMarketplaces(closure.marketplaces);
-	await installPlugins(closure);
-	await installBins(closure.bins);
-
-	// Materialize every profile (so `profile switch` needs no reinstall), then
-	// activate the target (or the sole/first profile).
-	//
-	// Every profile is materialized even when one was named: a profile arg scopes
-	// what gets *installed* and which becomes active, not which settings files
-	// exist. It also keeps the union below consistent across all of them — a
-	// profile left holding an older union would stop disabling plugins added
-	// since, silently making `switch` additive again.
-	const unionPluginIds = Object.keys(
-		(flags.profile ? await resolveAllProfiles(manifest) : closure).plugins,
-	);
-	for (const id of profileIds) {
-		const profileClosure = await resolveProfile(manifest, id);
-		await materializeProfile(id, profileClosure, projectPath, unionPluginIds);
+	// A marketplace added just now carries the plugin.json files that name
+	// each plugin's dependencies; resolve again so those are installed too.
+	clearMarketplaceCache();
+	const before = new Set(Object.keys(closure.plugins));
+	closure = await resolveClosure();
+	const found = Object.keys(closure.plugins).filter((id) => !before.has(id));
+	if (found.length > 0) {
+		console.log(
+			`Also installing what those plugins depend on: ${found.join(", ")}`,
+		);
+	}
+	const unreadable = closure.dependencies?.unreadable ?? [];
+	if (unreadable.length > 0) {
+		console.warn(
+			`⚠ Could not read the plugin.json of ${unreadable.join(", ")} — whatever ${
+				unreadable.length === 1 ? "it depends" : "they depend"
+			} on is not installed by this run`,
+		);
 	}
 
-	// Keep the generated dir + active-profile symlinks out of git before
-	// activating (source of truth is .claude/profiles.json).
-	await ensureGitignoreEntries(
-		path.join(projectPath, ".gitignore"),
-		PROFILE_GITIGNORE_ENTRIES,
-		"# magus: generated profile build output + active-profile symlinks",
-	);
-
+	const current = await activeProfile(projectPath);
 	const activeId =
-		flags.profile ?? (await pickActiveProfile(profileIds, flags.yes));
+		flags.profile ??
+		current ??
+		(await pickActiveProfile(profileIds, flags.yes));
 	if (activeId) {
-		// The reporter is not optional here. The first `install` in a project that
-		// had a hand-written .claude/settings.json moves it aside, and without
-		// this the move is invisible — the file is simply not where it was.
-		await activateProfile(activeId, projectPath, reportDisplaced(projectPath));
+		// The one switch path: what Claude Code wrote into the live config — or
+		// through an older layout's links — goes into the profile it was written
+		// under (or, if profiles.json no longer defines that one, into this one)
+		// before anything is rendered over it. The displacement reporter is not
+		// optional: a first `install` over a hand-written settings.json moves it
+		// aside, and the move must never be silent.
+		const switched = await switchToProfile(projectPath, activeId, {
+			onDisplace: reportDisplaced(projectPath),
+		});
+		for (const line of switched.lines) console.log(noteLine(line));
+		if (!switched.activation) {
+			for (const problem of switched.problems) console.error(problem);
+			return 1;
+		}
 		console.log(`\n✓ Active profile: ${activeId}`);
-		// Skills route through the now-active .claude/skills symlink.
-		const activeClosure = await resolveProfile(manifest, activeId);
-		await installSkills(activeClosure.skills, projectPath);
-		await collectEnv(activeClosure, projectPath, flags.yes);
+		printActivationNotes(switched.activation);
+	}
+
+	// The CLI's installs write enabledPlugins for every plugin installed — all
+	// profiles' when no profile was named. `withCliBookkeeping` flags the marker
+	// while they run and reconciles in `finally`: what the user changed in the
+	// meantime is kept, only the install's own records are discarded, and a
+	// Ctrl-C leaves the flag for the next command to do the same.
+	await withCliBookkeeping(projectPath, () => installPlugins(closure), {
+		installable: Object.keys(closure.plugins),
+		report: (line) => console.log(noteLine(line)),
+	});
+	await bringLoadsForward(Object.keys(closure.plugins), projectPath);
+	await installBins(closure.bins);
+
+	if (activeId) {
+		await collectEnv(
+			await resolveProfile(await readManifest(projectPath), activeId),
+			projectPath,
+			flags.yes,
+		);
 	}
 
 	console.log("\nDone.");

package/src/cli/models.ts

@@ -18,6 +18,7 @@ import {
 	presetLabel,
 	presetNames,
 } from "../data/models-presets.js";
+import { readManifest } from "../services/manifest.js";
 import {
 	loadMateCatalog,
 	stalenessNote,
@@ -40,7 +41,23 @@ import {
 	readModelsConfig,
 	readModelsStatus,
 } from "../services/models-manager.js";
-import { ensureManifest } from "./bootstrap.js";
+import { activeProfile } from "../services/profile-live.js";
+import { ensureManifest, requireActiveProfile } from "./bootstrap.js";
+
+/**
+ * A project with profiles must be ON one before routing is written: the
+ * routing is a property of the active profile. With none active this asks at a
+ * terminal and stops with the instruction anywhere else, rather than writing a
+ * plain models.json the next activation would replace.
+ */
+async function requireProfileWhenManaged(
+	projectPath: string,
+): Promise<boolean> {
+	const manifest = await readManifest(projectPath);
+	if (Object.keys(manifest.profiles).length === 0) return true;
+	if ((await activeProfile(projectPath)) !== null) return true;
+	return (await requireActiveProfile(projectPath, manifest)) !== null;
+}
 
 const HEADLINE: Record<ModelsState, string> = {
 	off: "off — no .claude/models.json, subagents inherit the session model",
@@ -206,6 +223,8 @@ async function runUse(projectPath: string, name?: string): Promise<number> {
 		return 1;
 	}
 
+	if (!(await requireProfileWhenManaged(projectPath))) return 1;
+
 	let result: Awaited<ReturnType<typeof applyModelPreset>>;
 	try {
 		result = await applyModelPreset({
@@ -247,6 +266,7 @@ async function runUse(projectPath: string, name?: string): Promise<number> {
 }
 
 async function runOff(projectPath: string): Promise<number> {
+	if (!(await requireProfileWhenManaged(projectPath))) return 1;
 	await clearModels(projectPath);
 	console.log(
 		"\n✓ Model tiers off. Subagents inherit the session model again.",

package/src/cli/profile.ts

@@ -1,29 +1,31 @@
 /**
- * `magus profile <list|show|switch|sync> [name]`
+ * `magus profile <list|show|switch|init> [name]`
  *
- * Inspect and switch between team profiles materialized under
- * `.claude/_profiles/`. Switching is cheap and offline — it just repoints the
- * shared-config symlinks. `sync` (Phase 5) promotes local drift back into the
- * committed manifest.
+ * Inspect and switch between the team profiles in `.claude/profiles.json`.
+ * Switching renders the chosen profile's settings.json, .mcp.json and
+ * models.json and installs its skills; anything Claude Code wrote into the
+ * live config first goes into the profile being left.
  */
 
-import path from "node:path";
-import fs from "fs-extra";
-import { ensureGitignoreEntries } from "../services/conventions-manager.js";
 import { checkBinaries, missingBinaries } from "../services/doctor-bins.js";
 import { summarizeClosure } from "../services/install-plan.js";
 import { getManifestPath, readManifest } from "../services/manifest.js";
 import { reportDisplaced } from "../services/profile-activate.js";
-import { syncProfile } from "../services/profile-sync.js";
+import { activeProfile, namedActiveProfile } from "../services/profile-live.js";
+import type { SkillInstaller } from "../services/profile-skills.js";
+import {
+	suggestedProfile,
+	switchHint,
+	switchToProfile,
+} from "../services/profile-state.js";
 import { resolveProfile } from "../services/resolver.js";
 import { SettingsParseError } from "../services/settings-file.js";
 import {
-	PROFILE_GITIGNORE_ENTRIES,
-	activateProfile,
-	activeProfile,
-	profileDir,
-} from "../services/symlink-manager.js";
-import { ensureManifest, reportUnparseable } from "./bootstrap.js";
+	ensureManifest,
+	printActivationNotes,
+	reportUnparseable,
+} from "./bootstrap.js";
+import { note as noteLine } from "./update-view.js";
 
 /**
  * Every subcommand reads `.claude/profiles.json`, and one that does not parse
@@ -58,11 +60,9 @@ async function dispatchProfileCommand(args: string[]): Promise<number> {
 				args.includes("--yes") || args.includes("-y"),
 				projectPath,
 			);
-		case "sync":
-			return syncActiveProfile(rest[0], projectPath);
 		default:
 			console.error(
-				`Unknown profile command "${sub}". Use: list | show <name> | switch <name> | init | sync`,
+				`Unknown profile command "${sub}". Use: list | show <name> | switch <name> | init`,
 			);
 			return 1;
 	}
@@ -83,7 +83,9 @@ export async function initProfile(
 		console.error(
 			`${getManifestPath(projectPath)} already defines: ${Object.keys(existing.profiles).join(", ")}`,
 		);
-		console.error("Use `magus profile sync` to promote local edits into it.");
+		console.error(
+			"Changes to the live config are recorded in the active profile automatically.",
+		);
 		return 1;
 	}
 	// `profile init` exists to create the manifest, so it is the one caller that
@@ -103,12 +105,18 @@ export async function listProfiles(projectPath: string): Promise<number> {
 	for (const id of ids) {
 		const entry = manifest.profiles[id];
 		const marker = id === active ? "●" : " ";
-		const materialized = (await fs.pathExists(profileDir(id, projectPath)))
-			? ""
-			: "  (not installed)";
-		console.log(`  ${marker} ${id} — ${entry.name}${materialized}`);
+		console.log(`  ${marker} ${id} — ${entry.name}`);
+	}
+	if (active) {
+		console.log(`\nActive: ${active}`);
+	} else {
+		const named = await namedActiveProfile(projectPath);
+		if (named) {
+			console.log(
+				`\nThe active profile is recorded as "${named.profile}", which is not defined above. Run: ${switchHint(ids, suggestedProfile(manifest))}`,
+			);
+		}
 	}
-	if (active) console.log(`\nActive: ${active}`);
 	return 0;
 }
 
@@ -137,42 +145,32 @@ export async function showProfile(
 export async function switchProfile(
 	name: string | undefined,
 	projectPath: string,
+	/** Skill installer seam; the real one fetches from GitHub. */
+	opts: { installSkill?: SkillInstaller } = {},
 ): Promise<number> {
 	if (!name) {
 		console.error("Usage: magus profile switch <name>");
 		return 1;
 	}
-	const manifest = await readManifest(projectPath);
-	if (!manifest.profiles[name]) {
-		console.error(
-			`Profile "${name}" not found. Available: ${Object.keys(manifest.profiles).join(", ")}`,
-		);
-		return 1;
-	}
-	if (!(await fs.pathExists(profileDir(name, projectPath)))) {
-		console.error(
-			`Profile "${name}" isn't installed yet. Run: magus install ${name}`,
-		);
+
+	// The one switch path, shared with the TUI's Profiles tab: edits go into
+	// the profile being LEFT (or, if it no longer exists, into this one), then
+	// this profile is rendered. A no-op absorb when the router's gate ran first.
+	const result = await switchToProfile(projectPath, name, {
+		onDisplace: reportDisplaced(projectPath),
+		installSkill: opts.installSkill,
+	});
+	for (const line of result.lines) console.log(noteLine(line));
+	if (result.problems.length > 0 || !result.activation) {
+		for (const problem of result.problems) console.error(problem);
 		return 1;
 	}
-
-	// In profile mode the source of truth is .claude/profiles.json; the
-	// generated dir AND the per-developer symlinks must stay out of git so
-	// switching profiles causes no churn.
-	await ensureGitignoreEntries(
-		path.join(projectPath, ".gitignore"),
-		PROFILE_GITIGNORE_ENTRIES,
-		"# magus: generated profile build output + active-profile symlinks",
-	);
-
-	// Switching between two already-active profiles displaces nothing — the paths
-	// are links magus owns. The FIRST switch in an unmanaged project displaces
-	// real files, and that is the run that must say so.
-	await activateProfile(name, projectPath, reportDisplaced(projectPath));
 	console.log(`✓ Switched to profile: ${name}`);
+	printActivationNotes(result.activation);
+	const manifest = await readManifest(projectPath);
 
 	// Verify the profile's binary deps are actually usable — the switch itself
-	// succeeds (symlinks are valid), but warn so "switched" isn't misleading.
+	// succeeds (the config is in place), but warn so "switched" is not misleading.
 	try {
 		const closure = await resolveProfile(manifest, name);
 		const missing = missingBinaries(await checkBinaries(closure.bins));
@@ -189,30 +187,3 @@ export async function switchProfile(
 	}
 	return 0;
 }
-
-export async function syncActiveProfile(
-	nameArg: string | undefined,
-	projectPath: string,
-): Promise<number> {
-	const name = nameArg ?? (await activeProfile(projectPath));
-	if (!name) {
-		console.error(
-			"No active profile to sync. Pass a name: magus profile sync <name>",
-		);
-		return 1;
-	}
-	try {
-		const { changes, wrote } = await syncProfile(name, projectPath);
-		if (!wrote) {
-			console.log(`Profile "${name}" is already in sync with the manifest.`);
-			return 0;
-		}
-		console.log(`Synced "${name}" → .claude/profiles.json:`);
-		for (const c of changes) console.log(`  ${c.kind}: ${c.detail}`);
-		console.log("\nReview the diff and commit .claude/profiles.json.");
-		return 0;
-	} catch (e) {
-		console.error((e as Error).message);
-		return 1;
-	}
-}

package/src/cli/router.ts

@@ -8,9 +8,10 @@
 
 import type { ThemeMode } from "@opentui/core";
 import { SettingsParseError } from "../services/settings-file.js";
+import { LiveFileRefusal } from "../services/tracked-live-files.js";
 import { checkForUpdates } from "../services/version-check.js";
 import { type ThemeEnv, parseThemeWord } from "../ui/theme-resolve.js";
-import { reportUnparseable } from "./bootstrap.js";
+import { profileGate, reportUnparseable } from "./bootstrap.js";
 import { runDoctorCommand } from "./doctor.js";
 import { runInstallCommand } from "./install.js";
 import { runModelsCommand } from "./models.js";
@@ -102,6 +103,9 @@ const SUBCOMMANDS = new Set([
 	"doctor",
 ]);
 
+/** Subcommands that read or write profile state, and so pass the gate first. */
+const PROFILE_GATED = new Set(["install", "update", "profile", "models"]);
+
 export async function route(
 	argv: string[],
 	version: string,
@@ -173,6 +177,25 @@ export async function route(
 		setThemeMode(mode);
 	}
 
+	// Every command that reads or writes profile state passes the same gate
+	// first: restore a lost marker, convert an older layout, absorb what Claude
+	// Code wrote into the live config, regenerate from a changed profiles.json.
+	// Read-only runs (`--check`, `--dry-run`) promise to write nothing, so they
+	// skip it. `doctor` runs it itself, to report what it did.
+	if (
+		command !== undefined &&
+		PROFILE_GATED.has(command) &&
+		!rest.includes("--check") &&
+		!rest.includes("--dry-run")
+	) {
+		const ok = await profileGate(process.cwd(), {
+			// Both of these fix a marker naming a missing profile by activating
+			// one that exists.
+			allowUnknown: command === "install" || command === "profile",
+		});
+		if (!ok) return HANDLED(1);
+	}
+
 	try {
 		switch (command) {
 			case "update":
@@ -201,6 +224,12 @@ export async function route(
 			reportUnparseable(error);
 			return HANDLED(1);
 		}
+		// A live file git tracks (or git could not say): nothing was written,
+		// and the message says what to do. A refusal, not a crash.
+		if (error instanceof LiveFileRefusal) {
+			console.error(error.message);
+			return HANDLED(1);
+		}
 		throw error;
 	}
 }
@@ -227,9 +256,9 @@ without one is offered adoption on first run. See docs/team-configuration.md.
   install [profile]  Install the profile's plugins, binaries, skills and env at
                      the manifest's PINNED versions, then activate it.
                      No argument installs every profile.
-    --check          Report drift only, write nothing (exits 1 in strict mode)
+    --check          Report version mismatches only, write nothing
+                     (exits 1 in strict mode)
     --yes, -y        Skip the confirmation prompt
-    --force          Discard unsynced local edits instead of refusing
   update [profile]   Keep the ACTIVE profile current: install whatever it
                      declares but this machine lacks, and advance anything
                      behind the version its marketplace publishes. Only the
@@ -244,10 +273,14 @@ without one is offered adoption on first run. See docs/team-configuration.md.
                      missing or known to be behind — the CI gate.
   profile list       Show every profile; ● marks the active one
   profile show <n>   Print a profile's fully resolved closure
-  profile switch <n> Repoint the active profile — offline, no reinstall
+  profile switch <n> Make <n> the active profile: render its settings.json,
+                     .mcp.json and models.json, install its skills
   profile init       Write .claude/profiles.json from this project's setup
-  profile sync       Promote local edits back into .claude/profiles.json
-  doctor             Check binary deps, profile symlinks, and conventions
+
+Changes Claude Code makes to .claude/settings.json or .mcp.json (a plugin
+installed, a setting changed) are changes to the active profile: every command
+above records them in .claude/profiles.json before it acts.
+  doctor             Check binary deps, the active profile, and conventions
     --fix            Apply the repairs it can make itself
 
 Per-subagent model routing — give each subagent its own model and effort. The