@zitadel/cli 0.1.0-alpha.9 → 1.0.0-alpha.20

package/dist/commands/doctor.mjs

@@ -1,15 +1,18 @@
-import { C as isObject, E as ZitadelError, a as DEFAULT_LOCAL_SERVER_PORT, b as publicCliCommand, c as checkLocalServerHealth, l as defaultLocalServerImageForCliVersion, m as readRuntimeMetadata, p as localServerUrl, s as assertLocalStateWritable, t as BaseCommand } from "../oclif-B7lBzh3R.mjs";
-import { i as issuerFromPort, t as createOrca } from "../orca-U142Wrau.mjs";
-import { a as readZitadelConfig, i as readRendererId, o as readZitadelSecret, r as readDevelopmentIssuer, t as hasZitadelConfig } from "../project-Cd0L3PtM.mjs";
-import { n as listenersForPort } from "../ports-B09RjuHx.mjs";
-import { d as assertServerPackageAvailable, o as imageAvailable, r as dockerAvailable } from "../docker-CnGQK3ZK.mjs";
-import { n as dockerUnavailableMessage, t as dockerRuntimeGuidance } from "../docker-guidance-ypN3IM3o.mjs";
-import { t as discoverManagedRuntimeProcesses } from "../processes-Cw8TO1SY.mjs";
+import { E as ZitadelError, S as isObject, a as DEFAULT_LOCAL_SERVER_PORT, c as checkLocalServerHealth, h as readRuntimeMetadata, j as publicCliCommand, l as defaultLocalServerImageForCliVersion, m as localServerUrl, s as assertLocalStateWritable, t as BaseCommand } from "../oclif-CanO3zdt.mjs";
+import { n as claimCommand, r as claimState, t as claimAction } from "../claim-state-DlfD6Res.mjs";
+import { s as issuerFromPort, t as createOrca } from "../orca-BzQIQqzt.mjs";
+import { a as readProjectServer, c as readZitadelConfig, i as readPreset, l as readZitadelSecret, o as readRendererId, r as readDevelopmentIssuer, s as readUseCase, t as hasZitadelConfig } from "../project-CHhot85s.mjs";
+import { i as updateScaffold, t as SCHEMAS_DIR } from "../user-schema-DTuOsdKE.mjs";
+import { c as writeScaffoldManifest, n as detectPackageManager, o as hashScaffoldFile, s as readScaffoldManifest, t as addExactCommandFor } from "../package-manager-DFdLcDx1.mjs";
+import { d as assertServerPackageAvailable, o as imageAvailable, r as dockerAvailable } from "../docker-DcRGTOJa.mjs";
+import { n as dockerRuntimeGuidance, r as dockerUnavailableMessage, t as listenersForPort } from "../ports-BM20XIZb.mjs";
+import { t as discoverManagedRuntimeProcesses } from "../processes-DKHPkU8O.mjs";
+import { chmod, readFile, readdir, rm, stat, writeFile } from "node:fs/promises";
+import { join } from "node:path";
 import { Flags } from "@oclif/core";
 import consola from "consola";
-import { join } from "node:path";
-import { chmod, readFile, stat, writeFile } from "node:fs/promises";
-import "@zitadel/api/generated/endpoints/zitadelNextGen.zod";
+import semver from "semver";
+import { schemaConfigSchema } from "@zitadel/config/schemas";
 //#region src/commands/doctor/checks/types.ts
 /**
 * Base class for checks: subclasses declare `name`, `path`, and a success
@@ -35,7 +38,11 @@ var AbstractSanityCheck = class {
 				name: this.name,
 				status: "fail",
 				message: error instanceof Error ? error.message : String(error),
-				path: this.path
+				path: this.path,
+				...error instanceof ZitadelError ? {
+					code: error.code,
+					...error.hint === void 0 ? {} : { hint: error.hint }
+				} : {}
 			};
 		}
 	}
@@ -147,46 +154,47 @@ var FrameworkCheck = class extends AbstractSanityCheck {
 //#endregion
 //#region src/commands/doctor/patch-context.ts
 /**
-* Reconstructs a {@link PatchContext} from the on-disk project (config, secret)
-* plus fresh framework detection, so a patcher repair can rebuild its plan.
-* Used by the dependency check's `fix`, which reclaims the framework-specific
-* SDK package via `patcher.repair`. The user schema and flow definition are
-* server-owned and no longer scaffolded locally, so nothing here reads them.
+* Reconstructs a {@link PatchContext} from the on-disk project (config,
+* secret, scaffold manifest) plus fresh framework detection, so a patcher
+* repair can rebuild its plan. Used by the doctor checks' `fix` paths.
+* `preset`/`useCase` come back from `zitadel.json` and
+* `scaffoldedFramework` from the scaffold manifest, so the rebuilt plan
+* matches what setup originally emitted (a fresh-scaffolded app's home page
+* is part of the plan again, for example). Schema and flow config are
+* user-editable sync resources, not patcher inputs, so nothing here reads
+* them.
 */
 async function loadPatchContext(cwd, orca, cliVersion) {
 	const config = await readZitadelConfig(cwd);
 	const secret = await readZitadelSecret(cwd);
 	const framework = await orca.detect(cwd);
+	const scaffold = await readScaffoldManifest(cwd);
 	return {
 		framework,
 		rendererId: readRendererId(config),
 		issuer: await resolveIssuer(cwd, config, framework),
 		server: typeof config.server === "string" ? config.server : "",
 		cliVersion,
+		scaffoldedFramework: scaffold?.scaffolded_framework,
+		posture: scaffold?.posture ?? "page",
+		preset: readPreset(config),
+		useCase: readUseCase(config),
 		project: {
 			id: secret.project_id,
-			projectSecret: secret.project_secret,
-			previewSecret: secret.preview_secret,
-			previewOrigins: secret.preview_origins,
-			createdAt: secret.created_at
+			project_secret: secret.project_secret,
+			preview_secret: secret.preview_secret,
+			preview_origins: secret.preview_origins,
+			created_at: secret.created_at
 		}
 	};
 }
 async function resolveIssuer(cwd, config, facts) {
 	const fromConfig = readDevelopmentIssuer(config);
 	if (fromConfig && fromConfig.length > 0) return fromConfig;
-	const state = await readState(cwd);
-	if (typeof state?.dev_port === "number") return issuerFromPort(state.dev_port);
+	const scaffold = await readScaffoldManifest(cwd);
+	if (typeof scaffold?.dev_port === "number") return issuerFromPort(scaffold.dev_port);
 	return facts.url;
 }
-async function readState(cwd) {
-	try {
-		const contents = await readFile(join(cwd, ".zitadel/state.json"), "utf8");
-		return JSON.parse(contents);
-	} catch {
-		return;
-	}
-}
 //#endregion
 //#region src/commands/doctor/checks/dependency.ts
 /**
@@ -204,23 +212,391 @@ var DependencyCheck = class extends AbstractSanityCheck {
 		if (![...Object.keys(pkg.dependencies ?? {}), ...Object.keys(pkg.devDependencies ?? {})].some((name) => name.startsWith("@zitadel"))) throw new Error("no @zitadel* dependency found in package.json");
 	}
 	/**
-	* Repairs by reclaiming the patcher's managed artifacts: rebuilds the
+	* Repairs by re-applying the patcher's managed artifacts: rebuilds the
 	* `PatchContext` from disk and calls `patcher.repair`, which re-adds the
 	* SDK dependency via its `add-dep` op. The exact package name is framework
 	* + renderer specific and known only to the patcher (which deliberately
 	* hides its file-op plan behind the family-neutral `Patcher` interface),
-	* so going through `repair` is the only sanctioned path.
+	* so going through `repair` is the only sanctioned path. Missing-only:
+	* the repair restores absent managed files as a side effect but never
+	* overwrites an existing one, edited or not.
 	*/
 	async fix(ctx) {
 		const patchCtx = await loadPatchContext(ctx.cwd, ctx.orca, ctx.cliVersion);
 		await ctx.orca.patcherFor(patchCtx.framework.id).repair(patchCtx, {
 			cwd: ctx.cwd,
 			dryRun: ctx.dryRun,
-			force: true
+			force: false,
+			missingOnly: true
 		});
 	}
 };
 //#endregion
+//#region src/commands/doctor/checks/dependency-version.ts
+/**
+* Verifies that exactly-pinned `@zitadel/*` dependencies match this CLI's own
+* version. The packages publish as one lockstep train, and the scaffold pins
+* the SDK at the CLI's version — but the CLI floats (`npx @zitadel/cli@alpha`)
+* while the app's pin stays put, so a newer CLI can restore files or write
+* guidance that references SDK entry points the older pinned SDK does not
+* ship (e.g. a subpath export added a train later). A mismatch therefore
+* *warns* with the exact remedy instead of leaving the skew to surface as a
+* module-not-found in the app.
+*
+* Only exact semver pins are compared: ranges, dist-tags, and `file:`/
+* `workspace:` specifiers express a deliberate resolution choice the check
+* cannot second-guess.
+*
+* Implements {@link SanityCheck} directly: the abstract base's verify-throws
+* contract can only express pass/fail, and a version skew is advisory — the
+* app keeps working on its pinned train until the user upgrades.
+*/
+var DependencyVersionCheck = class {
+	name = "dependency-version";
+	path = "package.json";
+	async run(ctx) {
+		const base = {
+			name: this.name,
+			path: this.path
+		};
+		if (semver.valid(ctx.cliVersion) === null) return {
+			...base,
+			status: "pass",
+			message: `CLI version ${ctx.cliVersion} is not an exact release; skipping the pin comparison`
+		};
+		let pkg;
+		try {
+			pkg = JSON.parse(await readFile(join(ctx.cwd, "package.json"), "utf8"));
+		} catch {
+			return {
+				...base,
+				status: "pass",
+				message: "no package.json to compare pins against"
+			};
+		}
+		const exact = Object.entries({
+			...pkg.dependencies ?? {},
+			...pkg.devDependencies ?? {}
+		}).filter(([name]) => name.startsWith("@zitadel/")).filter(([, version]) => semver.valid(version.trim()) !== null);
+		const mismatched = exact.filter(([, version]) => !semver.eq(version.trim(), ctx.cliVersion));
+		if (mismatched.length > 0) {
+			const remedy = addExactCommandFor(await detectPackageManager(ctx.cwd), mismatched.map(([name]) => `${name}@${ctx.cliVersion}`)).display;
+			return {
+				...base,
+				status: "warn",
+				message: `${mismatched.map(([name, version]) => `${name}@${version}`).join(", ")} does not match this CLI's version (${ctx.cliVersion}); scaffolded files and guidance target the CLI's train — update with \`${remedy}\``,
+				details: {
+					mismatched: mismatched.map(([name, version]) => ({
+						name,
+						declared: version,
+						expected: ctx.cliVersion
+					})),
+					remedy_command: remedy
+				}
+			};
+		}
+		return {
+			...base,
+			status: "pass",
+			message: exact.length > 0 ? `Zitadel package pins match the CLI version (${exact.length} compared)` : "no exactly-pinned Zitadel packages to compare"
+		};
+	}
+	/**
+	* No auto-fix: repair's dependency op is deliberately additive-only (it
+	* never rewrites a version the user declared), so the repair ships as the
+	* package-manager-aware install command in `details.remedy_command` — the
+	* doctor command surfaces it in the envelope's `next_commands` — with the
+	* same command quoted in the warn message for human readers.
+	*/
+	async fix(_ctx) {}
+};
+//#endregion
+//#region src/commands/doctor/checks/managed-files.ts
+/**
+* Verifies the scaffolded app files still exist: the ones `zitadel setup`
+* wrote per the scaffold manifest in `.zitadel/state.json`, or — for apps
+* scaffolded before the manifest existed — the patcher's current template
+* expectations minus conditionally-written files. A missing *infrastructure*
+* file (request boundary, provider, type declarations) breaks the auth
+* integration and fails the check; a missing *presentation* page only warns.
+* Edited and user-adopted files pass — they are the intended customization
+* paths — and are labelled in `details` for visibility.
+*
+* Implements {@link SanityCheck} directly rather than via the abstract base:
+* the base's `verify`-throws contract can only express pass/fail, and this
+* check needs the `warn` outcome.
+*/
+var ManagedFilesCheck = class {
+	name = "managed-files";
+	async run(ctx) {
+		const manifest = await readScaffoldManifest(ctx.cwd);
+		const evaluated = manifest ? await evaluateManifest(ctx.cwd, manifest) : await evaluateTemplates(ctx);
+		if (!evaluated) return {
+			name: this.name,
+			status: "warn",
+			message: "Could not enumerate scaffolded app files (framework or renderer unresolved); skipping the file check"
+		};
+		const { mode, rows } = evaluated;
+		const wiring = await probeConfigWiring(ctx);
+		const actions = await resolveArtifacts(ctx);
+		const boundaries = actions ? await detectBoundaryConflicts(actions, ctx.cwd, manifest) : [];
+		const missing = rows.filter((row) => row.state === "missing");
+		const missingInfrastructure = missing.filter((row) => row.class === "infrastructure");
+		const detachedInfrastructure = wiring.filter((s) => s.state === "detached" && s.wiring === "infrastructure");
+		const detachedConvenience = wiring.filter((s) => s.state === "detached" && s.wiring === "convenience");
+		const unverifiable = wiring.filter((s) => s.state === "unknown");
+		const conflicts = boundaries.filter((b) => b.disposition === "conflict");
+		const removable = boundaries.filter((b) => b.disposition === "removable");
+		const details = {
+			mode,
+			files: rows,
+			...wiring.length > 0 ? { config_wiring: wiring } : {},
+			...boundaries.length > 0 ? { boundary_conflicts: boundaries } : {}
+		};
+		const failures = [];
+		if (missingInfrastructure.length > 0) failures.push(`missing scaffolded infrastructure file(s): ${listPaths(missingInfrastructure)}`);
+		if (detachedInfrastructure.length > 0) failures.push(`detached managed config wiring: ${detachedInfrastructure.map((s) => s.path).join(", ")}`);
+		for (const conflict of conflicts) failures.push(`conflicting request boundaries: ${conflict.retired} is user-modified while the current templates use ${conflict.current} — migrate your changes and remove one of them manually`);
+		if (failures.length > 0) return {
+			name: this.name,
+			status: "fail",
+			message: failures.join("; "),
+			details
+		};
+		const warnings = [];
+		if (missing.length > 0) warnings.push(`missing scaffolded page(s): ${listPaths(missing)}`);
+		if (detachedConvenience.length > 0) warnings.push(`unapplied managed config edit(s): ${detachedConvenience.map((s) => s.path).join(", ")}`);
+		if (unverifiable.length > 0) warnings.push(`unverifiable managed config wiring (manual review required): ${unverifiable.map((s) => s.reason ? `${s.path} (${s.reason})` : s.path).join(", ")}`);
+		for (const leftover of removable) warnings.push(`retired boundary ${leftover.retired} left over from a template migration (doctor --fix removes it and installs ${leftover.current})`);
+		if (warnings.length > 0) return {
+			name: this.name,
+			status: "warn",
+			message: warnings.join("; "),
+			details
+		};
+		return {
+			name: this.name,
+			status: "pass",
+			message: `Scaffolded app files are present (${rows.length} tracked${wiring.length > 0 ? `, ${wiring.length} wiring${wiring.length === 1 ? "" : "s"} verified` : ""}${mode === "template" ? ", from templates" : ""})`,
+			details
+		};
+	}
+	/**
+	* Restores missing managed files via the patcher's missing-only repair —
+	* existing files, edited or adopted, are never overwritten — then refreshes
+	* the manifest hashes of the files the repair brought back so they classify
+	* as pristine again. The restored bytes come from the *current* templates,
+	* which may differ from what the original CLI version wrote; the re-hash
+	* records that honestly. On a pre-manifest app (template mode) a successful
+	* repair also materializes the manifest from the marker-bearing files now
+	* on disk, completing the migration ADR 042 promises — adopted files stay
+	* the user's and are not recorded.
+	*/
+	async fix(ctx) {
+		const manifest = await readScaffoldManifest(ctx.cwd);
+		const missingBefore = manifest ? await missingManifestPaths(ctx.cwd, manifest) : [];
+		const patchCtx = await loadPatchContext(ctx.cwd, ctx.orca, ctx.cliVersion);
+		const patcher = ctx.orca.patcherFor(patchCtx.framework.id);
+		const actions = patcher.artifacts({
+			framework: patchCtx.framework,
+			rendererId: patchCtx.rendererId
+		});
+		const boundaries = await detectBoundaryConflicts(actions, ctx.cwd, manifest);
+		const excludePaths = boundaries.filter((b) => b.disposition === "conflict").map((b) => b.current);
+		const removed = [];
+		if (!ctx.dryRun) {
+			for (const boundary of boundaries) if (boundary.disposition === "removable") {
+				await rm(join(ctx.cwd, boundary.retired), { force: true });
+				removed.push(boundary.retired);
+			}
+		}
+		await patcher.repair(patchCtx, {
+			cwd: ctx.cwd,
+			dryRun: ctx.dryRun,
+			force: false,
+			missingOnly: true,
+			...excludePaths.length > 0 ? { excludePaths } : {}
+		});
+		if (ctx.dryRun) return;
+		if (!manifest) {
+			await materializeManifest(ctx, patchCtx);
+			return;
+		}
+		if (missingBefore.length === 0 && removed.length === 0) return;
+		const current = new Set(actions.markedFiles);
+		const conditional = new Set(actions.conditionalFiles ?? []);
+		const files = {};
+		for (const [path, entry] of Object.entries(manifest.files)) {
+			const contents = await readIfExists(join(ctx.cwd, path));
+			if (contents === void 0 && !current.has(path)) continue;
+			files[path] = contents !== void 0 && missingBefore.includes(path) ? {
+				...entry,
+				hash: hashScaffoldFile(contents)
+			} : entry;
+		}
+		for (const path of actions.markedFiles) {
+			if (files[path] || conditional.has(path)) continue;
+			const contents = await readIfExists(join(ctx.cwd, path));
+			if (contents !== void 0 && contents.includes("// zitadel-cli: managed-file v1")) files[path] = {
+				hash: hashScaffoldFile(contents),
+				class: actions.fileClasses?.[path] ?? "presentation"
+			};
+		}
+		await updateScaffold(ctx.cwd, {
+			...manifest,
+			files
+		});
+	}
+};
+async function detectBoundaryConflicts(actions, cwd, manifest) {
+	const conflicts = [];
+	for (const [current, retiredPaths] of Object.entries(actions.retiredAlternates ?? {})) for (const retired of retiredPaths) {
+		const contents = await readIfExists(join(cwd, retired));
+		if (contents === void 0) continue;
+		const entry = manifest?.files[retired];
+		const pristine = entry !== void 0 && contents.includes("// zitadel-cli: managed-file v1") && hashScaffoldFile(contents) === entry.hash;
+		conflicts.push({
+			current,
+			retired,
+			disposition: pristine ? "removable" : "conflict"
+		});
+	}
+	return conflicts;
+}
+/**
+* Probe the patcher's managed config wirings (dev proxy merges, route
+* registrations). Needs the full patch context (project secret et al) to
+* rebuild the plan; when that fails — missing secret, undetectable
+* framework — the probe is skipped silently and the responsible check
+* reports the real problem.
+*/
+async function probeConfigWiring(ctx) {
+	try {
+		const patchCtx = await loadPatchContext(ctx.cwd, ctx.orca, ctx.cliVersion);
+		return await ctx.orca.patcherFor(patchCtx.framework.id).verify(patchCtx, { cwd: ctx.cwd });
+	} catch {
+		return [];
+	}
+}
+/**
+* Migration path for apps scaffolded before the manifest existed: after a
+* template-mode repair, record the marker-bearing managed files now on disk
+* so the next doctor run gets exact manifest-mode verification instead of
+* template guessing (and its Next-major / template-growth misclassification
+* risk). Marker-less (adopted) files and conditionally-scaffolded ones are
+* deliberately absent.
+*
+* The manifest is only finalized when every current *infrastructure* file is
+* present and recordable (marker-bearing): materializing during an
+* unresolved boundary conflict — or over an adopted boundary — would write a
+* manifest that tracks no request boundary at all, and deleting the boundary
+* later would go undetected. Until then the app stays on the template
+* fallback, whose presence checks keep enforcing the boundary. Best-effort:
+* an unreadable state file leaves the app in template mode, same as before.
+*/
+async function materializeManifest(ctx, patchCtx) {
+	try {
+		const actions = ctx.orca.patcherFor(patchCtx.framework.id).artifacts({
+			framework: patchCtx.framework,
+			rendererId: patchCtx.rendererId
+		});
+		const conditional = new Set(actions.conditionalFiles ?? []);
+		const marked = [];
+		for (const path of actions.markedFiles) {
+			if (conditional.has(path)) continue;
+			const contents = await readIfExists(join(ctx.cwd, path));
+			if (contents !== void 0 && contents.includes("// zitadel-cli: managed-file v1")) marked.push(path);
+		}
+		if (!actions.markedFiles.filter((path) => actions.fileClasses?.[path] === "infrastructure" && !conditional.has(path)).every((path) => marked.includes(path))) return;
+		await writeScaffoldManifest({
+			cwd: ctx.cwd,
+			actions,
+			written: marked
+		});
+	} catch {}
+}
+async function evaluateManifest(cwd, manifest) {
+	const rows = [];
+	for (const [path, entry] of Object.entries(manifest.files)) {
+		const contents = await readIfExists(join(cwd, path));
+		rows.push({
+			path,
+			class: entry.class,
+			state: stateFor(contents, entry.hash)
+		});
+	}
+	return {
+		mode: "manifest",
+		rows
+	};
+}
+/**
+* Fallback for apps scaffolded before the manifest existed: derive the
+* expected set from the patcher's current templates. Conditionally-written
+* files (e.g. the framework home page) are excluded — without a manifest
+* there is no way to know whether setup ever wrote them. Presence-only:
+* no recorded hash means `pristine` vs `edited` cannot be told apart.
+*/
+async function evaluateTemplates(ctx) {
+	const actions = await resolveArtifacts(ctx);
+	if (!actions) return;
+	const conditional = new Set(actions.conditionalFiles ?? []);
+	const rows = [];
+	for (const path of actions.markedFiles) {
+		if (conditional.has(path)) continue;
+		const contents = await readIfExists(join(ctx.cwd, path));
+		rows.push({
+			path,
+			class: actions.fileClasses?.[path] ?? "presentation",
+			state: stateFor(contents, void 0)
+		});
+	}
+	return {
+		mode: "template",
+		rows
+	};
+}
+/**
+* Resolves the patcher artifacts the same way `eject` does, tolerating every
+* failure with `undefined`: a broken framework detection, an unreadable
+* config, or an unresolvable renderer are reported by their own checks —
+* this one only degrades to "cannot enumerate".
+*/
+async function resolveArtifacts(ctx) {
+	const framework = await ctx.orca.tryDetect(ctx.cwd);
+	if (!framework) return;
+	try {
+		const config = await readZitadelConfig(ctx.cwd).catch(() => ({}));
+		return ctx.orca.patcherFor(framework.id).artifacts({
+			framework,
+			rendererId: readRendererId(config)
+		});
+	} catch {
+		return;
+	}
+}
+function stateFor(contents, hash) {
+	if (contents === void 0) return "missing";
+	if (!contents.includes("// zitadel-cli: managed-file v1")) return "adopted";
+	if (hash === void 0) return "managed";
+	return hashScaffoldFile(contents) === hash ? "pristine" : "edited";
+}
+async function missingManifestPaths(cwd, manifest) {
+	const missing = [];
+	for (const path of Object.keys(manifest.files)) if (await readIfExists(join(cwd, path)) === void 0) missing.push(path);
+	return missing;
+}
+async function readIfExists(path) {
+	try {
+		return await readFile(path, "utf8");
+	} catch {
+		return;
+	}
+}
+function listPaths(rows) {
+	return rows.map((row) => row.path).join(", ");
+}
+//#endregion
 //#region src/commands/doctor/checks/project-match.ts
 /** Verifies `.zitadel/secret`'s project_id matches `zitadel.json`'s project. */
 var ProjectMatchCheck = class extends AbstractSanityCheck {
@@ -235,6 +611,137 @@ var ProjectMatchCheck = class extends AbstractSanityCheck {
 	}
 };
 //#endregion
+//#region src/lib/json-dir.ts
+/**
+* Read every `*.json` file under `absDir` and return each body as a plain
+* object. Files are read in lexical filename order so the result is
+* deterministic for downstream hashing and diffs. Each file is parsed by
+* `JSON.parse`; this function does **not** apply any schema validation —
+* unknown keys, forward-compatible fields, and `${VAR}` placeholders survive
+* intact. Callers that need a typed shape pass the result through their
+* resource's Zod schema.
+*
+* Returns an empty array when the directory is missing. Throws `E_VALIDATION`
+* `ZitadelError` on invalid JSON or when a file's root value is not an object.
+*
+* @param absDir - Absolute path to the directory to scan.
+*/
+async function readJsonDir(absDir) {
+	let entries;
+	try {
+		entries = await readdir(absDir);
+	} catch (error) {
+		if (typeof error === "object" && error !== null && "code" in error && error.code === "ENOENT") return [];
+		throw error;
+	}
+	const result = [];
+	for (const entry of entries.filter((name) => name.endsWith(".json")).sort()) {
+		const abs = join(absDir, entry);
+		let raw;
+		try {
+			raw = JSON.parse(await readFile(abs, "utf8"));
+		} catch {
+			throw new ZitadelError("E_VALIDATION", `${entry} is not valid JSON`);
+		}
+		if (typeof raw !== "object" || raw === null || Array.isArray(raw)) throw new ZitadelError("E_VALIDATION", `${entry} must contain a JSON object at the root`);
+		result.push(raw);
+	}
+	return result;
+}
+//#endregion
+//#region src/commands/doctor/checks/schema.ts
+/**
+* Verifies local schema config files round-trip through the canonical
+* `schemaConfigSchema` from `@zitadel/config/schemas` — the same Zod the
+* sync engine validates with, so doctor and `apply` can never disagree
+* about a file. The union enforces the `kind` discriminator
+* (`user-schema` / `schema-url`) and the `metaSchema`/`x-auth-methods`/etc.
+* fields the platform requires.
+*/
+var SchemaCheck = class extends AbstractSanityCheck {
+	name = "schema";
+	path = SCHEMAS_DIR;
+	summary = "User schemas are valid Zitadel schema bodies";
+	/**
+	* An empty `.zitadel/schemas/` is a warning, not a failure: projects
+	* created before editable config existed were seeded server-side and have
+	* no local schema files, and there is no safe auto-fix that could invent
+	* them. Only invalid files fail the check.
+	*/
+	async run(ctx) {
+		if ((await readJsonDir(join(ctx.cwd, ".zitadel/schemas"))).length === 0) return {
+			name: this.name,
+			status: "warn",
+			message: `No schema files found in ${SCHEMAS_DIR} — this project predates editable schema config or setup was interrupted. New projects scaffold editable defaults via \`zitadel setup\`.`,
+			path: this.path
+		};
+		return super.run(ctx);
+	}
+	async verify(ctx) {
+		const schemas = await readJsonDir(join(ctx.cwd, SCHEMAS_DIR));
+		for (const schema of schemas) {
+			const result = schemaConfigSchema.safeParse(schema);
+			if (!result.success) throw new Error(result.error.issues.map((issue) => `${issue.path.join(".") || "/"} ${issue.message}`).join("; "));
+		}
+	}
+};
+//#endregion
+//#region src/commands/doctor/checks/claim.ts
+/**
+* Reports whether the project is attached to a team, reading `claimed_at` and
+* `team_id` from `.zitadel/secret`.
+*
+* Always advisory, never a failure. An unattached project works exactly like an
+* attached one — same issuer, same users, same applications — so the only thing
+* missing is durability, which is the developer's call and not a defect. That
+* matters mechanically too: `doctor` turns any `fail` into a thrown
+* `E_VALIDATION`, so failing here would break every scripted `zitadel doctor`
+* against a project nobody had claimed yet.
+*
+* Implements {@link SanityCheck} directly rather than via the abstract base,
+* for the same reason `ManagedFilesCheck` does: the base's `verify`-throws
+* contract can only express pass/fail, and this check is only ever warn or
+* pass.
+*/
+var ClaimCheck = class {
+	name = "claim";
+	path = ".zitadel/secret";
+	async run(ctx) {
+		let state;
+		try {
+			state = claimState({
+				secret: await readZitadelSecret(ctx.cwd),
+				server: readProjectServer(await readZitadelConfig(ctx.cwd))
+			});
+		} catch {
+			return {
+				name: this.name,
+				status: "pass",
+				message: "Skipped: could not read the project files that record the owning team",
+				path: this.path
+			};
+		}
+		if (state.kind === "detached") return {
+			name: this.name,
+			status: "warn",
+			message: "This project is temporary until you attach it to a team. Run `zitadel claim` to make it permanent; nothing about the project changes.",
+			path: this.path
+		};
+		return {
+			name: this.name,
+			status: "pass",
+			message: state.kind === "attached" ? `Project is attached to team ${state.team_id}` : "Project is not on a server where teams apply",
+			path: this.path
+		};
+	}
+	/**
+	* Deliberately a no-op. `doctor --fix` calls `fix` on every non-passing
+	* check, but claiming requires a human to sign in through a browser, so there
+	* is nothing safe to automate here.
+	*/
+	async fix(_ctx) {}
+};
+//#endregion
 //#region src/commands/doctor/checks/index.ts
 /** Every diagnostic the `doctor` command runs, in display order. */
 const SANITY_CHECKS = [
@@ -244,8 +751,12 @@ const SANITY_CHECKS = [
 	new GitignoreCheck(),
 	new EnvExampleCheck(),
 	new FrameworkCheck(),
+	new SchemaCheck(),
 	new DependencyCheck(),
-	new ProjectMatchCheck()
+	new DependencyVersionCheck(),
+	new ManagedFilesCheck(),
+	new ProjectMatchCheck(),
+	new ClaimCheck()
 ];
 //#endregion
 //#region src/commands/doctor/index.ts
@@ -262,8 +773,9 @@ const LOCAL_RUNTIME_CHECK_NAMES = new Set([
 *
 * Runs every registered {@link SANITY_CHECKS} entry and emits the aggregate
 * result; if any check fails it throws `E_VALIDATION` carrying the full check
-* details. With `--fix`, each failing check first attempts its own repair (a
-* no-op for checks with no safe automatic remedy), then the battery re-runs.
+* details. With `--fix`, each check that did not pass — failed or warned —
+* first attempts its own repair (a no-op for checks with no safe automatic
+* remedy), then the battery re-runs.
 *
 * The `--fix` loop is best-effort: a repair that throws (e.g. a missing
 * prerequisite file the check itself would also flag) is logged at debug
@@ -273,7 +785,7 @@ const LOCAL_RUNTIME_CHECK_NAMES = new Set([
 var Doctor = class Doctor extends BaseCommand {
 	static description = "Verify local runtime and project state.";
 	static flags = {
-		fix: Flags.boolean({ description: "Re-apply missing managed files." }),
+		fix: Flags.boolean({ description: "Repair missing files and stale managed wiring." }),
 		image: Flags.string({ description: "Container image to check." }),
 		port: Flags.integer({
 			description: "Local HTTP port.",
@@ -311,7 +823,7 @@ var Doctor = class Doctor extends BaseCommand {
 		if (hasConfig && flags.fix) {
 			const before = await Promise.all(SANITY_CHECKS.map((check) => check.run(ctx)));
 			for (const [index, check] of SANITY_CHECKS.entries()) {
-				if (before[index]?.status !== "fail") continue;
+				if (before[index]?.status === "pass") continue;
 				try {
 					await check.fix(ctx);
 				} catch (error) {
@@ -324,6 +836,13 @@ var Doctor = class Doctor extends BaseCommand {
 		const failed = checks.filter((check) => check.status === "fail");
 		const warnings = checks.filter((check) => check.status === "warn");
 		const warningAdvice = advisoryForWarnings(warnings, this.meta.cliVersion);
+		this.recordTelemetry({
+			runtime: runtimeBackend,
+			checks_total: checks.length,
+			checks_failed: failed.length,
+			checks_warn: warnings.length,
+			failed_checks: failed.length > 0 ? failed.map((check) => check.name).join(",") : void 0
+		});
 		const data = {
 			title: failed.length > 0 ? "Zitadel doctor found issues." : warnings.length > 0 ? "Zitadel doctor passed with warnings." : "Zitadel doctor passed.",
 			ok: failed.length === 0,
@@ -339,7 +858,7 @@ var Doctor = class Doctor extends BaseCommand {
 		};
 		if (failed.length > 0) {
 			const advice = failureAdvice(failed, image, port, this.meta.cliVersion);
-			throw new ZitadelError(failed.some((check) => check.name === "port") ? "E_PORT_IN_USE" : "E_VALIDATION", "Zitadel doctor found issues", {
+			throw new ZitadelError(failed.some((check) => check.name === "port") ? "E_PORT_IN_USE" : failed.find((check) => check.code !== void 0)?.code ?? "E_VALIDATION", "Zitadel doctor found issues", {
 				hint: advice.hint,
 				nextCommands: advice.nextCommands,
 				details: data
@@ -375,15 +894,27 @@ function failureAdvice(failed, image, port, cliVersion) {
 	};
 	if (failedNames.has("port")) {
 		const fallbackPort = port === 8080 ? port + 1 : DEFAULT_LOCAL_SERVER_PORT;
+		const stopCommand = publicCliCommand("stop --all", cliVersion);
+		const retryCommand = publicCliCommand("doctor", cliVersion);
+		const alternatePortCommand = publicCliCommand(`doctor --port ${String(fallbackPort)}`, cliVersion);
 		return {
-			hint: `Port ${String(port)} is already in use. Stop the process using it, or choose another port for local Zitadel.`,
-			nextCommands: [publicCliCommand(`doctor --port ${String(fallbackPort)}`, cliVersion)]
+			hint: `Port ${String(port)} is already in use. Stop the process using it, run \`${stopCommand}\` for CLI-managed local runtimes, then rerun \`${retryCommand}\`; or choose another port with \`${alternatePortCommand}\`.`,
+			nextCommands: [
+				stopCommand,
+				retryCommand,
+				alternatePortCommand
+			]
 		};
 	}
 	if (failedNames.has("runtime")) return {
 		hint: "Existing local runtime metadata was found, but the local Zitadel server is not healthy. Start it again or reset stale local data.",
 		nextCommands: [publicCliCommand("start", cliVersion), publicCliCommand("reset --force", cliVersion)]
 	};
+	const typed = failed.find((check) => check.code !== void 0 && check.hint !== void 0);
+	if (typed?.hint !== void 0) return {
+		hint: typed.hint,
+		nextCommands: [publicCliCommand("doctor", cliVersion)]
+	};
 	if (failed.some((check) => !LOCAL_RUNTIME_CHECK_NAMES.has(check.name))) return {
 		hint: `Run \`${publicCliCommand("doctor --fix", cliVersion)}\` to re-apply missing managed files.`,
 		nextCommands: [publicCliCommand("doctor --fix", cliVersion)]
@@ -401,10 +932,19 @@ function advisoryForWarnings(warnings, cliVersion) {
 		nextActions.push(...advice.nextActions);
 		nextCommands.push(...advice.nextCommands);
 	}
+	if (warnings.some((check) => check.name === "claim")) {
+		nextActions.push(claimAction(cliVersion));
+		nextCommands.push(claimCommand(cliVersion));
+	}
 	if (hasManagedRuntimeProcesses(warnings.find((check) => check.name === "managed-runtime-processes"))) {
 		nextActions.push("Review other host-wide CLI-managed local Zitadel runtimes before starting a new one.");
 		nextCommands.push(publicCliCommand("stop --all", cliVersion));
 	}
+	const dependencyRemedy = remedyCommandOf(warnings.find((check) => check.name === "dependency-version"));
+	if (dependencyRemedy !== void 0) {
+		nextActions.push("Align the exactly-pinned @zitadel/* dependencies with the CLI version; scaffolded files and guidance target the CLI's train.");
+		nextCommands.push(dependencyRemedy);
+	}
 	if (nextActions.length === 0 && nextCommands.length === 0) return;
 	return {
 		nextActions: unique(nextActions),
@@ -520,6 +1060,19 @@ async function checkRuntime(runtime, runtimeBackend) {
 function formatListeners(listeners) {
 	return listeners.map((listener) => [listener.command ?? "unknown", listener.pid ? `pid ${String(listener.pid)}` : void 0].filter(Boolean).join(" ")).join(", ");
 }
+/**
+* A warning may carry its own repair as `details.remedy_command` (today: the
+* dependency-version check's package-manager-aware exact-pin install).
+* Surfacing that string keeps the structured advisory identical to the
+* command quoted in the warning's prose.
+*/
+function remedyCommandOf(check) {
+	if (check?.status !== "warn") return;
+	const details = check.details;
+	if (typeof details !== "object" || details === null) return;
+	const remedy = details.remedy_command;
+	return typeof remedy === "string" && remedy.length > 0 ? remedy : void 0;
+}
 function hasManagedRuntimeProcesses(check) {
 	if (!check || check.status !== "warn") return false;
 	const details = check.details;