clivly 0.9.1 → 0.9.3

package/index.mjs

@@ -1,8 +1,8 @@
 #!/usr/bin/env node
-import { t as CANONICAL_FIELDS } from "./entity-config-D08zAeFY.mjs";
+import { t as CANONICAL_FIELDS } from "./entity-config-kUHri9yA.mjs";
 import "./mapping-score-C68uAqGB.mjs";
 import { matchesConcept, requiredFieldsFor, scoreFieldMap, scoreRelationships, suggestCursorField, toFieldMap } from "./internal-entity-heuristics.mjs";
-import { t as createClivlySDK } from "./sdk-BvRD2jAp.mjs";
+import { t as createClivlySDK } from "./sdk-CZNXBsgA.mjs";
 import { createRequire } from "node:module";
 import { spawn } from "node:child_process";
 import { accessSync, constants, existsSync, mkdirSync, readFileSync, readdirSync, realpathSync, statSync, watch, writeFileSync } from "node:fs";
@@ -477,7 +477,7 @@ async function probeModule(opts) {
 }
 //#endregion
 //#region src/workspace-graph.ts
-const WINDOWS_SEP$2 = /\\/g;
+const WINDOWS_SEP$3 = /\\/g;
 const MODULE_EXT$1 = /\.(ts|tsx|js|jsx|mjs|cjs|cts|mts)$/;
 const BRACE_GROUP = /\{([^{}]*)\}/;
 const MAX_GLOB_DEPTH = 8;
@@ -708,13 +708,13 @@ function exportsAllowSubpath(packageDir, subpath) {
 function toPackageSpecifier(pkg, absPath) {
 	const target = resolve(absPath);
 	if (resolvePackageEntry(pkg.dir) === target) return pkg.name;
-	const subpath = relative(pkg.dir, target).replace(WINDOWS_SEP$2, "/").replace(MODULE_EXT$1, "");
+	const subpath = relative(pkg.dir, target).replace(WINDOWS_SEP$3, "/").replace(MODULE_EXT$1, "");
 	if (subpath.length === 0) return pkg.name;
 	return exportsAllowSubpath(pkg.dir, subpath) ? `${pkg.name}/${subpath}` : null;
 }
 //#endregion
 //#region src/discover-schema.ts
-const WINDOWS_SEP$1 = /\\/g;
+const WINDOWS_SEP$2 = /\\/g;
 const MODULE_EXT = /\.(ts|js|mjs|cts|mts)$/;
 /**
 * Turn an absolute module path into the specifier the generated config imports
@@ -739,7 +739,7 @@ function toImportPath(schemaPath, cwd, graph) {
 		const specifier = toPackageSpecifier(owner, schemaPath);
 		if (specifier) return specifier;
 	}
-	const rel = relative(cwd, schemaPath).replace(WINDOWS_SEP$1, "/").replace(MODULE_EXT, "");
+	const rel = relative(cwd, schemaPath).replace(WINDOWS_SEP$2, "/").replace(MODULE_EXT, "");
 	return rel.startsWith(".") ? rel : `./${rel}`;
 }
 function isDirectory(path) {
@@ -1001,7 +1001,7 @@ Usage:
   clivly init [options]           Scaffold Clivly (config, routes, env file) for your app
   clivly add widget [options]     Scaffold the chat-session route
   clivly status [options]         Check your setup, step by step
-  clivly push-schema [options]    Report your schema to Clivly without deploying
+  clivly push-schema [options]    Push schema, custom objects and mappings to Clivly
   clivly dev [options]            Tunnel localhost so remote sync can reach you
   clivly login [options]          Pair this machine and write credentials to your env file
   clivly --version                Print the installed clivly version
@@ -1057,7 +1057,9 @@ Options:
 Usage:
   clivly status [--verbose] [--config <path>] [--env-file <path>]
 
-Runs the setup ladder: credential, reachability, config load, edge-safety,
+Prints two sections. "Workspace" is how far setup has got on Clivly's side,
+computed by the server so the terminal and the dashboard agree. "This project"
+runs the local ladder: credential, reachability, config load, edge-safety,
 setup checks, sync trigger. Read-only — writes nothing.
 
 Options:
@@ -1065,13 +1067,23 @@ Options:
   --config <path>   Path to clivly.config.ts
   --env-file <path> Extra env file to load
 `,
-	"push-schema": `clivly push-schema — report your schema without deploying
+	"push-schema": `clivly push-schema — push everything your config declares
 
 Usage:
   clivly push-schema [--config <path>]
 
-Sends your discovered tables to Clivly so the dashboard can offer them for
-mapping. Reads your config; writes nothing locally.
+Pushes three things to Clivly, without deploying your app:
+  1. Your table and column NAMES, so the dashboard can offer them for mapping.
+     Never row data — discovery is names only.
+  2. The custom object types you declared with \`objectType\`.
+  3. The mappings that make those objects actually receive rows.
+
+Reads your config; writes nothing locally. Safe to re-run — it reports what it
+created, updated, or left alone.
+
+Exits 1 if Clivly refuses your config, most often because an entity would
+overwrite a mapping edited in the dashboard. That makes it usable in CI as a
+schema gate.
 `,
 	dev: `clivly dev — tunnel localhost so remote sync can reach you
 
@@ -1153,6 +1165,46 @@ async function installPackages(options) {
 	}
 }
 //#endregion
+//#region src/install-needed.ts
+/** Exact `name@version` only. Anything else is left for the package manager. */
+const EXACT_VERSION = /^\d+\.\d+\.\d+(?:[-+][0-9A-Za-z.-]+)?$/;
+/**
+* Split `name@version`, tolerating scoped names where the leading `@` is part
+* of the name rather than a separator. Returns a null version for a bare name.
+*/
+function parseSpec(spec) {
+	const at = spec.lastIndexOf("@");
+	if (at <= 0) return {
+		name: spec,
+		version: null
+	};
+	return {
+		name: spec.slice(0, at),
+		version: spec.slice(at + 1)
+	};
+}
+/**
+* Which of `packages` still need installing.
+*
+* Deliberately conservative — a spec is only dropped when it is provably
+* satisfied. Tarball paths, `file:` specs and semver ranges are always kept:
+* the first two name no version to compare, and resolving the third needs a
+* semver implementation the CLI does not ship. Erring toward installing costs
+* a redundant install; erring the other way silently skips one the developer
+* asked for.
+*/
+function packagesNeedingInstall(packages, installedVersion) {
+	return packages.filter((spec) => {
+		if (spec.startsWith(".") || spec.startsWith("/") || spec.includes(":") || spec.includes("/") && !spec.startsWith("@")) return true;
+		const { name, version } = parseSpec(spec);
+		const present = installedVersion(name);
+		if (present === null) return true;
+		if (version === null) return false;
+		if (!EXACT_VERSION.test(version)) return true;
+		return present !== version;
+	});
+}
+//#endregion
 //#region src/is-entry.ts
 function isEntrypoint(argv1, moduleUrl, realpath = realpathSync) {
 	if (!argv1) return false;
@@ -1614,6 +1666,106 @@ function rankContactCandidates(tables) {
 	}));
 }
 //#endregion
+//#region src/config-import.ts
+const WINDOWS_SEP$1 = /\\/g;
+function configImport(generatedFilePath) {
+	const rel = relative(dirname(generatedFilePath), "clivly.config").replace(WINDOWS_SEP$1, "/");
+	return rel.startsWith(".") ? rel : `./${rel}`;
+}
+//#endregion
+//#region src/boot-hook.ts
+const BOOT_HOOK_PATHS = {
+	nextjs: "instrumentation.ts",
+	nuxt: "server/plugins/clivly.ts",
+	sveltekit: "src/hooks.server.ts",
+	"tanstack-start": null,
+	remix: null,
+	unknown: null
+};
+function bootHookPath(framework, layout) {
+	const path = BOOT_HOOK_PATHS[framework];
+	if (path === null) return null;
+	if (framework === "nextjs" && layout === "src/app") return `src/${path}`;
+	return path;
+}
+const FAILURE_NOTE = "Clivly never blocks your app from starting: a failed check-in is logged and retried on the next tick.";
+function nextjsHook(importPath) {
+	return `// Clivly boot hook. Next.js calls register() once when the server starts.
+// ${FAILURE_NOTE}
+export async function register() {
+	// The keep-alive loop is a setInterval, which does not survive on the edge
+	// runtime — it would stop ticking after the first response and the dashboard
+	// would show an app that checked in once and then went stale forever.
+	if (process.env.NEXT_RUNTIME !== "nodejs") {
+		return;
+	}
+	try {
+		const { default: clivly } = await import("${importPath}");
+		await clivly.start();
+	} catch (error) {
+		console.warn("[clivly] could not check in:", error);
+	}
+}
+`;
+}
+function nuxtHook(importPath) {
+	return `import clivly from "${importPath}";
+
+// Clivly boot hook. Nitro runs this once when the server starts.
+// ${FAILURE_NOTE}
+export default defineNitroPlugin(() => {
+	clivly.start().catch((error: unknown) => {
+		console.warn("[clivly] could not check in:", error);
+	});
+});
+`;
+}
+function sveltekitHook(importPath) {
+	return `import clivly from "${importPath}";
+
+// Clivly boot hook. This module is evaluated once when the server starts.
+// ${FAILURE_NOTE}
+clivly.start().catch((error: unknown) => {
+	console.warn("[clivly] could not check in:", error);
+});
+`;
+}
+const RENDERERS = {
+	nextjs: nextjsHook,
+	nuxt: nuxtHook,
+	sveltekit: sveltekitHook
+};
+function renderBootHook(framework, layout) {
+	const path = bootHookPath(framework, layout);
+	const render = RENDERERS[framework];
+	if (!(path && render)) throw new Error(`No standalone boot hook for framework: ${framework}`);
+	return render(configImport(path));
+}
+const NEXT_INSTRUMENTATION_STABLE_MAJOR = 15;
+const LEADING_MAJOR = /(\d+)/;
+/** Does this Next.js version range need the experimental flag to run our hook? */
+function nextNeedsInstrumentationFlag(versionRange) {
+	if (!versionRange) return false;
+	const major = LEADING_MAJOR.exec(versionRange);
+	if (!major?.[1]) return false;
+	return Number(major[1]) < NEXT_INSTRUMENTATION_STABLE_MAJOR;
+}
+const NEXT_INSTRUMENTATION_FLAG_STEP = `Your Next.js version reads instrumentation.ts only when it is switched on. Add this to next.config, or Clivly will never be told your app started:
+      experimental: { instrumentationHook: true }`;
+const REMIX_BOOT_STEP = `Start Clivly when your app boots. Add this near the top of app/entry.server.tsx:
+      import clivly from "./clivly.config";
+      clivly.start().catch((error) => console.warn("[clivly] could not check in:", error));`;
+/** The boot hook as a scaffold entry, or null when this framework is patched. */
+function planBootHook(framework, layout) {
+	const path = bootHookPath(framework, layout);
+	if (!path) return null;
+	return {
+		path,
+		description: "Clivly boot hook — starts check-in when your app runs",
+		owned: true
+	};
+}
+//#endregion
 //#region src/render-config.ts
 const CLIVLY_ENV_KEYS = [
 	{
@@ -1924,10 +2076,6 @@ function routePath(framework, kind, layout = "app") {
 }
 const WINDOWS_SEP = /\\/g;
 const LEADING_DOT_SLASH = /^\.\//;
-function configImport(routeFilePath) {
-	const rel = relative(dirname(routeFilePath), "clivly.config").replace(WINDOWS_SEP, "/");
-	return rel.startsWith(".") ? rel : `./${rel}`;
-}
 function hostImportPath(routeFilePath, appRelative, paths) {
 	const fromRoot = appRelative.replace(LEADING_DOT_SLASH, "");
 	const alias = aliasFor({
@@ -2015,6 +2163,7 @@ const COMMON_FILES = [{
 function planScaffold(framework, layout = "app") {
 	const paths = ROUTE_PATHS[framework];
 	if (!paths) return [];
+	const boot = planBootHook(framework, layout);
 	return [
 		{
 			path: applyLayout(framework, paths.tick, layout),
@@ -2026,6 +2175,7 @@ function planScaffold(framework, layout = "app") {
 			description: "Clivly auth-verify route (createAuthVerifyHandler) — finish resolveUser",
 			owned: true
 		},
+		...boot ? [boot] : [],
 		...COMMON_FILES
 	];
 }
@@ -2039,6 +2189,45 @@ function planWidgetScaffold(framework, layout = "app") {
 	}];
 }
 //#endregion
+//#region src/vite-boot-patch.ts
+/** Config filenames to look for, in precedence order. */
+const VITE_CONFIG_CANDIDATES = [
+	"vite.config.ts",
+	"vite.config.mts",
+	"vite.config.js",
+	"vite.config.mjs"
+];
+const PLUGIN_IMPORT = "import { clivlyVite } from \"clivly/vite\";";
+const CONFIG_IMPORT = "import clivly from \"./clivly.config\";";
+const PLUGIN_CALL = "clivlyVite(clivly)";
+const PLUGINS_ARRAY = /(^|[\s{,])plugins\s*:\s*\[/g;
+/** The last import line's end offset, so new imports land after the existing ones. */
+const IMPORT_LINE = /^\s*import\s.+?from\s+["'].+?["'];?\s*$/gm;
+function insertImports(source) {
+	const last = [...source.matchAll(IMPORT_LINE)].at(-1);
+	const block = `${PLUGIN_IMPORT}\n${CONFIG_IMPORT}`;
+	if (!last) return `${block}\n\n${source}`;
+	const at = (last.index ?? 0) + last[0].length;
+	return `${source.slice(0, at)}\n${block}${source.slice(at)}`;
+}
+/**
+* Add the Clivly Vite plugin to an existing config.
+*
+* Returns the patched source, or `null` when the config is already patched or
+* is not a shape we can edit safely.
+*/
+function patchViteConfig(source) {
+	if (source.includes(PLUGIN_CALL)) return null;
+	const matches = [...source.matchAll(PLUGINS_ARRAY)];
+	if (matches.length !== 1) return null;
+	const match = matches[0];
+	if (!match) return null;
+	const openBracketEnd = (match.index ?? 0) + match[0].length;
+	const rest = source.slice(openBracketEnd);
+	const separator = rest.startsWith("\n") ? "" : " ";
+	return insertImports(`${source.slice(0, openBracketEnd)}${PLUGIN_CALL},${separator}${rest}`);
+}
+//#endregion
 //#region src/plan-mutations.ts
 function fileAction(existing, next, force) {
 	if (existing === null) return "create";
@@ -2050,8 +2239,10 @@ function hasKey(content, key) {
 }
 function planFiles(args) {
 	const mutations = [];
+	const bootPath = bootHookPath(args.framework, args.layout);
 	const render = (path) => {
 		if (path === "clivly.config.ts") return renderInitConfig(args.plan);
+		if (bootPath !== null && path === bootPath) return renderBootHook(args.framework, args.layout);
 		const kind = path.includes("verify") ? "verify" : "tick";
 		return renderRouteFile(args.framework, kind, args.authWiring, args.layout, parseTsconfig(args.readFile(join(args.cwd, "tsconfig.json")) ?? "")?.paths);
 	};
@@ -2079,10 +2270,67 @@ function planEnv(args) {
 		action: envAction(addedKeys.length, existing.length)
 	};
 }
+function declaredNextVersion(args) {
+	const raw = args.readFile(join(args.cwd, "package.json"));
+	if (!raw) return;
+	let pkg = {};
+	try {
+		pkg = JSON.parse(raw);
+	} catch {
+		pkg = {};
+	}
+	return pkg.dependencies?.next ?? pkg.devDependencies?.next;
+}
+function planBootPatch(args) {
+	if (bootHookPath(args.framework, args.layout) !== null) return {
+		file: null,
+		manual: args.framework === "nextjs" && nextNeedsInstrumentationFlag(declaredNextVersion(args)) ? NEXT_INSTRUMENTATION_FLAG_STEP : null
+	};
+	if (args.framework === "remix") return {
+		file: null,
+		manual: REMIX_BOOT_STEP
+	};
+	if (args.framework !== "tanstack-start") return {
+		file: null,
+		manual: null
+	};
+	for (const candidate of VITE_CONFIG_CANDIDATES) {
+		const existing = args.readFile(join(args.cwd, candidate));
+		if (existing === null) continue;
+		const patched = patchViteConfig(existing);
+		if (patched === null) return existing.includes("clivlyVite(clivly)") ? {
+			file: {
+				path: candidate,
+				contents: existing,
+				action: "unchanged"
+			},
+			manual: null
+		} : {
+			file: null,
+			manual: `Add the Clivly plugin to ${candidate} so your app checks in when it runs:\n      import { clivlyVite } from "clivly/vite";\n      import clivly from "./clivly.config";\n      // then, inside defineConfig: plugins: [clivlyVite(clivly), …]`
+		};
+		return {
+			file: {
+				path: candidate,
+				contents: patched,
+				action: "patch"
+			},
+			manual: null
+		};
+	}
+	return {
+		file: null,
+		manual: null
+	};
+}
 function planMutations(args) {
+	const files = planFiles(args);
+	const boot = planBootPatch(args);
+	if (boot.file) files.push(boot.file);
 	return {
-		files: planFiles(args),
-		env: planEnv(args)
+		files,
+		env: planEnv(args),
+		manualSteps: boot.manual ? [boot.manual] : []
 	};
 }
 function planWidgetMutations(args) {
@@ -2096,6 +2344,49 @@ function planWidgetMutations(args) {
 	});
 }
 //#endregion
+//#region src/quiet-host-output.ts
+/**
+* Run `fn` with the process's stdout/stderr captured. Always restores the
+* original writers, including when `fn` throws — a leaked patch would silence
+* the whole CLI for the rest of the run.
+*/
+async function captureHostOutput(fn) {
+	const originals = {
+		stdout: process.stdout.write,
+		stderr: process.stderr.write
+	};
+	let output = "";
+	const capture = (chunk, encoding, callback) => {
+		output += typeof chunk === "string" ? chunk : Buffer.from(chunk).toString("utf8");
+		const done = typeof encoding === "function" ? encoding : callback;
+		if (typeof done === "function") done();
+		return true;
+	};
+	process.stdout.write = capture;
+	process.stderr.write = capture;
+	try {
+		return {
+			result: await fn(),
+			output
+		};
+	} catch (error) {
+		if (output.trim().length > 0 && error instanceof Error) error.message = `${error.message}\n${output.trim()}`;
+		throw error;
+	} finally {
+		process.stdout.write = originals.stdout;
+		process.stderr.write = originals.stderr;
+	}
+}
+/**
+* Run `fn` quietly, discarding whatever the host printed on success. On failure
+* the captured output is attached to the error's message, so the host's own
+* explanation is not lost.
+*/
+async function quietly(fn) {
+	const { result } = await captureHostOutput(fn);
+	return result;
+}
+//#endregion
 //#region src/probe-auth.ts
 const AUTH_MODULE_PATHS = [
 	"auth",
@@ -2118,15 +2409,32 @@ function defaultLoader(cwd) {
 	return (specifier) => jiti.import(specifier);
 }
 function probeAuthInstance(cwd, load) {
-	return probeModule({
+	return quietly(() => probeModule({
 		candidates: authInstanceCandidates(cwd),
 		cwd,
 		load: load ?? defaultLoader(cwd),
 		match: isBetterAuthInstance
-	});
+	}));
 }
 //#endregion
 //#region src/push-schema.ts
+/**
+* "1 mapping" / "3 mappings" — a count nobody has to decode. The plural is
+* explicit because appending "s" turns "entity" into "entitys".
+*/
+function countOf(n, singular, plural = `${singular}s`) {
+	return `${n} ${n === 1 ? singular : plural}`;
+}
+function reportSchema(report, out) {
+	const createdObjects = report.objectTypes.filter((o) => o.created);
+	if (createdObjects.length > 0) out(`  ✅ Created ${countOf(createdObjects.length, "custom object")}: ${createdObjects.map((o) => o.slug).join(", ")}.\n`);
+	else if (report.objectTypes.length > 0) out(`  ✅ ${countOf(report.objectTypes.length, "custom object")} already present.\n`);
+	const created = report.mappings.filter((m) => m.created);
+	const updated = report.mappings.filter((m) => m.updated);
+	if (created.length > 0) out(`  ✅ Mapped ${countOf(created.length, "entity", "entities")}: ${created.map((m) => m.entityKey).join(", ")}.\n`);
+	if (updated.length > 0) out(`  ✅ Updated ${countOf(updated.length, "mapping")}: ${updated.map((m) => m.entityKey).join(", ")}.\n`);
+	if (report.mappings.length > 0 && created.length === 0 && updated.length === 0) out(`  ✅ ${countOf(report.mappings.length, "mapping")} already match your config.\n`);
+}
 async function runPushSchema(options) {
 	const out = options.out ?? ((line) => process.stdout.write(line));
 	const path = resolveConfigPath(options.cwd, options.configPath);
@@ -2154,6 +2462,29 @@ async function runPushSchema(options) {
 	}
 	out("  ✅ Schema reported to Clivly.\n");
 	out("     Integration liveness and trigger URL were refreshed too.\n");
+	if (sdk.ensureSchema) {
+		let report;
+		try {
+			report = await sdk.ensureSchema();
+		} catch (error) {
+			out(`  ❌ Clivly refused your schema — ${error.message}\n`);
+			return 1;
+		}
+		if (report === null) {
+			out("  ⚠️  Could not declare the objects and mappings in your config.\n");
+			out("     Run `clivly status`, then `clivly push-schema` again.\n");
+		} else reportSchema(report, out);
+		out("     Open Integrations → Mapping to review them.\n");
+		return 0;
+	}
+	const ensured = await sdk.ensureCustomObjects?.();
+	if (ensured === null) {
+		out("  ⚠️  Could not create the custom objects your config declares.\n");
+		out("     Run `clivly status`, then `clivly push-schema` again.\n");
+	} else if (ensured && ensured.length > 0) {
+		const created = ensured.filter((o) => o.created);
+		out(created.length > 0 ? `  ✅ Created ${created.length} custom object(s): ${created.map((o) => o.slug).join(", ")}.\n` : `  ✅ ${ensured.length} custom object(s) already present.\n`);
+	}
 	out("     Open Integrations → Mapping to map your tables.\n");
 	return 0;
 }
@@ -2541,6 +2872,17 @@ function defaultReadConfigSource(path) {
 		return null;
 	}
 }
+/**
+* Ping Clivly at most once per command, memoised on the context.
+*
+* `clivly status` asks two questions of one response — "did this call reach
+* Clivly" and "how far has this workspace got" — and they must come from the
+* same answer, not two calls that could disagree.
+*/
+function pingOnce(ctx) {
+	ctx.pingResult ??= ctx.connect(ctx.apiKey, ctx.apiUrl);
+	return ctx.pingResult;
+}
 const REASON_HINT = {
 	ok: "",
 	invalid_api_key: "The key was rejected (401). Check CLIVLY_SECRET_KEY (or legacy CLIVLY_API_KEY).",
@@ -2552,7 +2894,7 @@ const REASON_HINT = {
 	network_error: "Could not reach Clivly. Check your network or --api-url."
 };
 const apiKeyStage = {
-	id: "credential",
+	id: "api-key",
 	label: "API key present",
 	run(ctx) {
 		if (ctx.apiKey) return Promise.resolve({
@@ -2567,11 +2909,11 @@ const apiKeyStage = {
 	}
 };
 const reachabilityStage = {
-	id: "application",
+	id: "reachable",
 	label: "Clivly reachable",
 	needs: [apiKeyStage.id],
 	async run(ctx) {
-		const result = await ctx.connect(ctx.apiKey, ctx.apiUrl);
+		const result = await pingOnce(ctx);
 		if (result.ok) {
 			const name = result.org?.name ?? "(unnamed org)";
 			const id = result.org?.id ? ` (${result.org.id})` : "";
@@ -2705,19 +3047,57 @@ function defaultLoadSdk(path) {
 	return loadConfigSdk(path, "doctor");
 }
 //#endregion
+//#region src/workspace-section.ts
+const MARK$1 = {
+	active: "⏳",
+	blocked: "🔒",
+	done: "✅",
+	failed: "❌",
+	skipped: "⏭️ "
+};
+/**
+* The workspace half of `clivly status`, rendered from what the server sent.
+*
+* This module decides nothing about a stage's state — it prints the verdict the
+* server computed. A CLI that computed its own would be a second ladder, which
+* is the drift this whole change removes.
+*
+* "Unavailable" and "nothing is set up" are deliberately different outcomes. An
+* old server, a rejected key and a dead network all mean we could not ask; none
+* of them means the workspace is empty.
+*/
+function workspaceSection(result) {
+	if (!result) return {
+		kind: "unavailable",
+		reason: "Could not reach Clivly."
+	};
+	if (!result.ok) return {
+		kind: "unavailable",
+		reason: result.status === null ? "Could not reach Clivly (no response)." : `Clivly rejected the request — ${result.reason} (HTTP ${result.status}).`
+	};
+	if (!result.workspace) return {
+		kind: "unavailable",
+		reason: "This Clivly server does not report setup progress. Upgrade the server to see it here."
+	};
+	return {
+		kind: "ladder",
+		lines: result.workspace.steps.map((step) => `  ${MARK$1[step.state]} ${step.label}${step.evidence ? `        ${step.evidence}` : ""}`)
+	};
+}
+//#endregion
 //#region src/status.ts
 /** Stage ids each legacy command maps onto. */
 const ALIAS_STAGE_IDS = {
 	status: STATUS_STAGES.map((stage) => stage.id),
-	ping: ["credential", "application"],
+	ping: ["api-key", "reachable"],
 	doctor: [
 		"config",
 		"runtime",
 		"setup-checks"
 	],
 	connect: [
-		"credential",
-		"application",
+		"api-key",
+		"reachable",
 		"config",
 		"trigger-url"
 	]
@@ -2734,8 +3114,19 @@ const defaultConnect = (apiKey, apiUrl) => createClivlySDK({
 	apiUrl,
 	retry: { maxAttempts: 1 }
 }).ping();
+/**
+* Exported for tests only — the rule it encodes is the point.
+*
+* A skipped check was never evaluated (nothing to check yet), which is not the
+* same as a warning: a warning is a working setup carrying real risk. Marking
+* "not applicable" with ⚠️ put a warning on every fresh install for something
+* the developer had not done wrong, which is exactly how people are trained to
+* stop reading warnings — the same reasoning `status-stages.ts` gives for
+* refusing to turn a stage red on a setup that works.
+*/
 function subMark(sub) {
-	if (sub.skipped || sub.warn) return "⚠️ ";
+	if (sub.skipped) return "⏭️ ";
+	if (sub.warn) return "⚠️ ";
 	return sub.ok ? "✅" : "❌";
 }
 function renderStage(result, verbose, out) {
@@ -2762,6 +3153,13 @@ async function runStatus(options) {
 	};
 	out("\nClivly status\n");
 	const results = await runLadder(stages, ctx);
+	if (selected.has("reachable")) {
+		const section = workspaceSection(ctx.pingResult ? await ctx.pingResult : null);
+		out("\nWorkspace\n");
+		if (section.kind === "ladder") for (const line of section.lines) out(`${line}\n`);
+		else out(`  ⚠️  ${section.reason}\n`);
+	}
+	out("\nThis project\n");
 	for (const result of results) renderStage(result, options.verbose ?? false, out);
 	const code = ladderExitCode(results);
 	if (code !== 0 && results.some((result) => result.state === "pending")) out("\nSetup is incomplete — finish the steps above and re-run.\n");
@@ -2791,6 +3189,7 @@ const KNOWN_COMMANDS = [
 	"init",
 	"status",
 	"push-schema",
+	"add",
 	"dev",
 	"login",
 	"help",
@@ -2898,6 +3297,14 @@ function runAdd(argv, cwd, deps = defaultAddDeps) {
 	}
 	return 0;
 }
+function readInstalledVersion(cwd, name) {
+	try {
+		const manifest = join(cwd, "node_modules", ...name.split("/"), "package.json");
+		return JSON.parse(readFileSync(manifest, "utf8")).version ?? null;
+	} catch {
+		return null;
+	}
+}
 function readOwnVersion() {
 	const req = createRequire(import.meta.url);
 	for (const rel of ["./package.json", "../package.json"]) try {
@@ -2995,6 +3402,7 @@ function resolveInitDeps(options) {
 		install: options.installPackages ?? installPackages,
 		probeAuth: options.probeAuthInstance ?? probeAuthInstance,
 		readEnv: options.readEnv ?? defaultReadEnv,
+		readInstalledVersion: options.readInstalledVersion ?? readInstalledVersion,
 		readOwnVersion: options.readOwnVersion ?? readOwnVersion,
 		writeEnv: options.writeEnv ?? defaultWriteEnv,
 		isInteractive: options.yes ? () => false : options.isInteractive ?? defaultIsInteractive,
@@ -3094,12 +3502,12 @@ function applyMutations(options, deps, mutations) {
 		deps.writeConfig(join(options.cwd, file.path), file.contents);
 		deps.out(`  ✓ ${file.path}\n`);
 	}
-	if (mutations.env.action === "skip") {
-		deps.out("  • .env already has every CLIVLY_* key — skipped\n");
-		return;
+	if (mutations.env.action === "skip") deps.out("  • .env already has every CLIVLY_* key — skipped\n");
+	else {
+		deps.writeEnv(options.cwd, mutations.env.contents);
+		deps.out("  ✓ .env placeholders\n");
 	}
-	deps.writeEnv(options.cwd, mutations.env.contents);
-	deps.out("  ✓ .env placeholders\n");
+	for (const step of mutations.manualSteps) deps.out(`\n  ! ${step}\n`);
 }
 const DIFF_CONTEXT_LIMIT = 40;
 function renderDiff(existing, next) {
@@ -3119,6 +3527,7 @@ function previewMutations(deps, mutations, options) {
 			conflict: " (differs — --diff to see, --force to overwrite)",
 			create: ` (${lines} lines)`,
 			overwrite: ` (${lines} lines)`,
+			patch: " (your file, plus the Clivly plugin)",
 			unchanged: " (already up to date)"
 		}[file.action];
 		out(`  ${file.action.padEnd(9)} ${file.path}${suffix}\n`);
@@ -3176,13 +3585,17 @@ async function scaffold(options, deps, plan) {
 		});
 		return 0;
 	}
-	const result = await deps.install({
-		cwd: options.cwd,
-		pm,
-		packages
-	});
-	if (result.ok) out(`Installed clivly (${pm})\n`);
-	else out(`Could not install automatically — run:\n  ${result.command}\n`);
+	const missing = packagesNeedingInstall(packages, (name) => deps.readInstalledVersion(options.cwd, name));
+	if (missing.length === 0) out(`Already installed (${pm}) — nothing to fetch\n`);
+	else {
+		const result = await deps.install({
+			cwd: options.cwd,
+			pm,
+			packages: missing
+		});
+		if (result.ok) out(`Installed clivly (${pm})\n`);
+		else out(`Could not install automatically — run:\n  ${result.command}\n`);
+	}
 	applyMutations(options, deps, mutations);
 	let loginRan = false;
 	if (credentialsMissing(mutations.env.contents)) {
@@ -3544,4 +3957,4 @@ if (isEntrypoint(process.argv[1], import.meta.url)) main(process.argv.slice(2)).
 	process.exitCode = code;
 });
 //#endregion
-export { credentialsMissing, main, nearestCommand, runAdd, runInit, runInitFromArgv };
+export { KNOWN_COMMANDS, credentialsMissing, main, nearestCommand, runAdd, runInit, runInitFromArgv };