magus-cli 7.4.1 → 7.5.0

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,36 @@ 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 { 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 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 +57,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 +139,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)) {
@@ -179,39 +170,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,
@@ -312,26 +270,6 @@ export async function runInstallCommand(
 		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 +295,47 @@ 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);
+	const current = await activeProfile(projectPath);
+	const activeId =
+		flags.profile ??
+		current ??
+		(await pickActiveProfile(profileIds, flags.yes));
+	if (activeId) {
+		// 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}`);
+		printActivationNotes(switched.activation);
 	}
 
-	// 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",
-	);
+	// 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), {
+		report: (line) => console.log(noteLine(line)),
+	});
+	await installBins(closure.bins);
 
-	const activeId =
-		flags.profile ?? (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));
-		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);
+		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

@@ -10,7 +10,7 @@ import type { ThemeMode } from "@opentui/core";
 import { SettingsParseError } from "../services/settings-file.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 +102,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 +176,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":
@@ -227,9 +249,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 +266,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

package/src/cli/update.ts

@@ -48,9 +48,20 @@ import {
 	clearMarketplaceCache,
 	getAvailablePlugins,
 } from "../services/plugin-manager.js";
+import {
+	recordRefetchedSkills,
+	trackFetchedSkills,
+	updatableSkills,
+} from "../services/profile-activate.js";
+import { activeProfile } from "../services/profile-live.js";
+import { skillFolder } from "../services/profile-skills.js";
+import {
+	suggestedProfile,
+	switchHint,
+	withCliBookkeeping,
+} from "../services/profile-state.js";
 import { resolveProfile } from "../services/resolver.js";
 import { getInstalledSkillNames } from "../services/skills-manager.js";
-import { activeProfile } from "../services/symlink-manager.js";
 import { REAL_TOOL_PROBE_IO, probeTools } from "../services/tool-probe.js";
 // The apply half lives in services/ so the TUI runs the SAME code — see the
 // header of update-engine.ts for what drifted while it did not.
@@ -197,7 +208,7 @@ export async function runUpdateCommand(
 	//
 	// BOTH `--check` and `--dry-run` are read-only here. An earlier version let
 	// `--dry-run` activate, reasoning that a preview needs a real profile to
-	// report against — but activating writes symlinks and edits a TRACKED
+	// report against — but activating writes config files and edits a TRACKED
 	// `.gitignore`, and `--dry-run` promises to write nothing and exit 0. A
 	// preview that mutates the repo is not a preview.
 	//
@@ -207,7 +218,7 @@ export async function runUpdateCommand(
 	// preview result rather than an error.
 	//
 	// NAMING A PROFILE SKIPS THE GATE. `magus update lean` says which profile to
-	// update, and updating it needs the manifest, not the symlink — installs go
+	// update, and updating it needs the manifest, not the marker — installs go
 	// to project scope either way. Gating it would refuse a question the user
 	// already answered on the command line, and would break `magus update lean`
 	// and `--check lean` in CI, both of which worked before this gate existed.
@@ -254,7 +265,7 @@ export async function runUpdateCommand(
 	if (!resolvedId) {
 		console.error(
 			failLine(
-				`No active profile. Run \`magus profile switch <${profileIds.join("|")}>\`.`,
+				`No active profile. Run ${switchHint(profileIds, suggestedProfile(current))}.`,
 			),
 		);
 		return 1;
@@ -414,11 +425,18 @@ export async function runUpdateCommand(
 
 	// ---- plan ----------------------------------------------------------------
 
+	// Skills go into the live `.claude/skills/`, so only the ACTIVE profile's,
+	// and never over a custom skill folder.
+	const skillRefs = await updatableSkills(
+		projectPath,
+		targetId,
+		closure.skills,
+	);
 	const plan: UpdatePlan = {
 		profileId: targetId,
 		plugins: planPluginUpdates(closure.plugins, catalog),
 		bins: planBinUpdates(closure.bins, toolFacts),
-		skills: planSkillUpdates(closure.skills, installedSkills),
+		skills: planSkillUpdates(skillRefs, installedSkills),
 		binSpecs: new Map(closure.bins.map((b) => [b.name, b])),
 	};
 
@@ -575,9 +593,28 @@ export async function runUpdateCommand(
 	console.log("");
 	applyLive.start((tick) => applyFrame(state, tick, Date.now()));
 
-	const outcome = await applyPlan(plan, projectPath, { report: reporter });
+	// `claude plugin install --scope project` records each install in the live
+	// settings.json — for a profile that may not be the active one. The marker
+	// is flagged while that runs; in `finally` the re-fetched skill folders are
+	// recorded with their new contents, then the live config is reconciled:
+	// the user's own edits in the meantime are kept, the install's records are
+	// discarded, and an interrupted run leaves the flag for the next command.
+	const reconciledLines: string[] = [];
+	// Only the skills this run actually fetched get new hashes: one it did
+	// not fetch and someone edited meanwhile must still read as edited.
+	const skills = trackFetchedSkills(skillRefs, reporter);
+	const outcome = await withCliBookkeeping(
+		projectPath,
+		() => applyPlan(plan, projectPath, { report: skills.report }),
+		{
+			beforeReconcile: () =>
+				recordRefetchedSkills(projectPath, skills.fetched()),
+			report: (line) => reconciledLines.push(line),
+		},
+	);
 
 	applyLive.stop();
+	for (const line of reconciledLines) console.log(noteLine(line));
 
 	const { failed } = outcome;