clivly 0.8.0 → 0.9.1

package/index.mjs

@@ -1,16 +1,82 @@
 #!/usr/bin/env node
-import { t as CANONICAL_FIELDS } from "./entity-config-va2bkH5o.mjs";
+import { t as CANONICAL_FIELDS } from "./entity-config-D08zAeFY.mjs";
 import "./mapping-score-C68uAqGB.mjs";
 import { matchesConcept, requiredFieldsFor, scoreFieldMap, scoreRelationships, suggestCursorField, toFieldMap } from "./internal-entity-heuristics.mjs";
-import { t as createClivlySDK } from "./sdk-C6WANW8M.mjs";
+import { t as createClivlySDK } from "./sdk-BvRD2jAp.mjs";
 import { createRequire } from "node:module";
 import { spawn } from "node:child_process";
-import { accessSync, constants, existsSync, mkdirSync, readFileSync, readdirSync, realpathSync, statSync, writeFileSync } from "node:fs";
+import { accessSync, constants, existsSync, mkdirSync, readFileSync, readdirSync, realpathSync, statSync, watch, writeFileSync } from "node:fs";
 import { homedir, hostname } from "node:os";
 import { delimiter, dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
 import { createInterface } from "node:readline/promises";
 import { createJiti } from "jiti";
 import { fileURLToPath, pathToFileURL } from "node:url";
+//#region ../core/src/env-file.ts
+const ENV_FILES = {
+	next: ".env.local",
+	"tanstack-start": ".env",
+	sveltekit: ".env",
+	remix: ".env",
+	nuxt: ".env",
+	"hono-workers": ".dev.vars"
+};
+/** The conventional env file for a framework. `.env` when we do not know. */
+function envFileFor(framework) {
+	return ENV_FILES[normalizeFramework(framework)] ?? ".env";
+}
+const ALIASES = {
+	next: "next",
+	nextjs: "next",
+	"next.js": "next",
+	"tanstack-start": "tanstack-start",
+	tanstack: "tanstack-start",
+	sveltekit: "sveltekit",
+	remix: "remix",
+	nuxt: "nuxt",
+	"hono-workers": "hono-workers",
+	hono: "hono-workers",
+	workers: "hono-workers"
+};
+/** The canonical id for a framework name, or null when unrecognised. */
+function normalizeFramework(framework) {
+	if (!framework) return null;
+	return ALIASES[framework.toLowerCase()] ?? null;
+}
+/**
+* Which env file to actually write to.
+*
+* Prefers a file that already holds the key over the conventional one: a
+* project that has been running with credentials in `.env` must not suddenly
+* get a second copy in `.env.local`, leaving two files disagreeing and the
+* stale one still loading. Convention applies to new setups, not to a working
+* one someone already has.
+*/
+function resolveEnvFile(input) {
+	const conventional = envFileFor(input.framework);
+	if (input.existing.includes(conventional)) return conventional;
+	return input.existing[0] ?? conventional;
+}
+//#endregion
+//#region src/app-layout.ts
+function resolveAppLayout(cwd, fileExists = existsSync) {
+	if (fileExists(join(cwd, "src", "app"))) return "src/app";
+	if (fileExists(join(cwd, "app"))) return "app";
+	return fileExists(join(cwd, "src")) ? "src/app" : "app";
+}
+function shadowedAppDirError(cwd, framework, plannedPaths, fileExists = existsSync) {
+	if (framework !== "nextjs") return null;
+	if (!plannedPaths.some((path) => path.startsWith("app/"))) return null;
+	if (!fileExists(join(cwd, "src", "app"))) return null;
+	return `This project has a src/app directory, so writing routes to app/ would shadow it.
+
+Next.js reads either app/ or src/app/, never both. A root app/ directory wins,
+and every route under src/app/ disappears from the build.
+
+Nothing was written. Please report this at https://github.com/amani-joseph/clivly/issues
+— Clivly should have detected the src/app layout automatically.
+`;
+}
+//#endregion
 //#region src/load-config.ts
 const CONFIG_HINT = "Expected clivly.config.ts at your app root exporting `createClivlySDK({...})`.";
 function resolveConfigPath(cwd, configPath) {
@@ -108,6 +174,14 @@ async function loadCliConfig(cwd) {
 	return envFiles ? { envFiles } : {};
 }
 //#endregion
+//#region src/dashboard-locations.ts
+/** Secret + publishable keys. The Connect dialog mints them and shows the secret once. */
+const CREDENTIALS_LOCATION = "Clivly dashboard → Connect app (or Settings → API keys)";
+/** The signing secret Clivly Cloud uses on sync-trigger callbacks. */
+const SYNC_SECRET_LOCATION = "Clivly dashboard → Integrations → Remote sync";
+/** Chat widget records and their allowed origins. */
+const WIDGET_LOCATION = "Clivly dashboard → Settings → Chat widget";
+//#endregion
 //#region src/detect.ts
 const FRAMEWORK_MARKERS = [
 	{
@@ -253,8 +327,19 @@ const OVERRIDE_FAILURE_CAUSES = {
 	not_enabled: "The target backend does not have the feature-flagged trigger-url endpoint enabled (likely the wrong backend, or the flag is off).",
 	unreachable: "Could not reach Clivly at the selected API base URL."
 };
-function overrideFailureMessage(kind) {
-	return `Warning: could not register the tunnel URL — ${OVERRIDE_FAILURE_CAUSES[kind]} Dashboard-triggered sync is unavailable this session. Your app is still running.`;
+/**
+* `status` is required in practice for `unexpected_response` and meaningless
+* for the others.
+*
+* Every non-401/404 status used to collapse into `unreachable`, so the CLI told
+* developers it "could not reach Clivly" while Clivly was answering. That is
+* not a wording nit: when neon-http broke these endpoints in production the CLI
+* discarded the one honest signal it had (HTTP 500) and sent people to check
+* their network and API URL, where nothing was wrong. A response is proof of
+* reachability — so say what came back.
+*/
+function overrideFailureMessage(kind, status) {
+	return `Warning: could not register the tunnel URL — ${kind === "unexpected_response" ? `Clivly answered HTTP ${status ?? "an error"} — the request reached Clivly but was rejected, so this is a Clivly-side or request problem rather than a network one.` : OVERRIDE_FAILURE_CAUSES[kind]} Dashboard-triggered sync is unavailable this session. Your app is still running.`;
 }
 function cloudflaredMissingMessage() {
 	return [
@@ -309,12 +394,16 @@ async function runDev(options) {
 		deps.out(`Tunnel: ${triggerUrl}`);
 		const result = await deps.register(triggerUrl).catch(() => UNREACHABLE_RESULT);
 		if (result.ok) deps.out("Dashboard-triggered sync now points at this local session.");
-		else deps.out(overrideFailureMessage(result.kind));
+		else deps.out(overrideFailureMessage(result.kind, result.status));
 	});
+	const stopWatching = deps.watchConfig?.(options.cwd, () => {
+		deps.out("clivly.config.ts changed — restart your app for it to take effect.");
+	}) ?? null;
 	return await new Promise((resolve) => {
 		const shutdown = async (code) => {
 			if (shuttingDown) return;
 			shuttingDown = true;
+			stopWatching?.();
 			tunnel.kill();
 			app?.kill();
 			if (!(await deps.clear().catch(() => UNREACHABLE_RESULT)).ok) deps.out("Warning: could not clear the tunnel override on exit.");
@@ -336,7 +425,18 @@ const HTTP_NOT_FOUND = 404;
 function kindForStatus(status) {
 	if (status === HTTP_UNAUTHORIZED) return "unauthorized";
 	if (status === HTTP_NOT_FOUND) return "not_enabled";
-	return "unreachable";
+	return "unexpected_response";
+}
+function failureFor(status) {
+	const kind = kindForStatus(status);
+	return kind === "unexpected_response" ? {
+		ok: false,
+		kind,
+		status
+	} : {
+		ok: false,
+		kind
+	};
 }
 async function registerTunnelOverride(deps) {
 	const res = await (deps.fetchImpl ?? globalThis.fetch)(`${deps.apiUrl}${TRIGGER_URL_PATH}`, {
@@ -348,10 +448,7 @@ async function registerTunnelOverride(deps) {
 		body: JSON.stringify({ url: deps.triggerUrl })
 	});
 	if (res.ok) return { ok: true };
-	return {
-		ok: false,
-		kind: kindForStatus(res.status)
-	};
+	return failureFor(res.status);
 }
 async function clearTunnelOverride(deps) {
 	const res = await (deps.fetchImpl ?? globalThis.fetch)(`${deps.apiUrl}${TRIGGER_URL_PATH}`, {
@@ -359,10 +456,7 @@ async function clearTunnelOverride(deps) {
 		headers: { authorization: `Bearer ${deps.apiKey}` }
 	});
 	if (res.ok) return { ok: true };
-	return {
-		ok: false,
-		kind: kindForStatus(res.status)
-	};
+	return failureFor(res.status);
 }
 //#endregion
 //#region src/probe-module.ts
@@ -687,6 +781,30 @@ function buildFkByColumn(pgCore, drizzle, table) {
 	} catch {}
 	return fkByColumn;
 }
+function buildUniqueConstraints(pgCore, table) {
+	if (!pgCore) return;
+	const keys = [];
+	try {
+		const config = pgCore.getTableConfig(table);
+		for (const column of config.columns ?? []) if (column.isUnique || column.primary) keys.push([column.name]);
+		for (const pk of config.primaryKeys ?? []) keys.push(pk.columns.map((c) => c.name));
+		for (const constraint of config.uniqueConstraints ?? []) keys.push(constraint.columns.map((c) => c.name));
+		for (const index of config.indexes ?? []) {
+			if (!index.config?.unique) continue;
+			const columns = (index.config.columns ?? []).map((c) => c?.name).filter((name) => Boolean(name));
+			if (columns.length > 0) keys.push(columns);
+		}
+	} catch {
+		return;
+	}
+	const seen = /* @__PURE__ */ new Set();
+	return keys.filter((key) => {
+		const id = [...key].sort().join("\0");
+		if (seen.has(id) || key.length === 0) return false;
+		seen.add(id);
+		return true;
+	});
+}
 function toDiscoveredColumn(key, col, fkByColumn) {
 	let type;
 	try {
@@ -734,10 +852,12 @@ async function discoverSchema(opts) {
 		if (drizzle.is(value, drizzle.Table)) {
 			const fkByColumn = buildFkByColumn(pgCore, drizzle, value);
 			const columns = Object.entries(drizzle.getTableColumns(value)).map(([key, col]) => toDiscoveredColumn(key, col, fkByColumn));
+			const uniqueConstraints = buildUniqueConstraints(pgCore, value);
 			tables.push({
 				moduleKey,
 				tableName: drizzle.getTableName(value),
-				columns
+				columns,
+				...uniqueConstraints === void 0 ? {} : { uniqueConstraints }
 			});
 			continue;
 		}
@@ -767,6 +887,29 @@ async function discoverSchema(opts) {
 	};
 }
 //#endregion
+//#region src/engine-check.ts
+const MAJOR = /^v?(\d+)/;
+const FIRST_NUMBER = /(\d+)/;
+function currentMajor(version) {
+	const match = MAJOR.exec(version);
+	return match ? Number(match[1]) : null;
+}
+function requiredMajor(range) {
+	if (!range) return null;
+	const match = FIRST_NUMBER.exec(range);
+	return match ? Number(match[1]) : null;
+}
+function engineError(currentVersion, enginesRange) {
+	const have = currentMajor(currentVersion);
+	const need = requiredMajor(enginesRange);
+	if (have === null || need === null || have >= need) return null;
+	return `Clivly requires Node.js ${need} or newer. You are running ${currentVersion}.
+
+Upgrade with \`nvm install ${need}\` (or your version manager of choice), then re-run.
+Set CLIVLY_SKIP_ENGINE_CHECK=1 to run anyway — expect unrelated-looking failures.
+`;
+}
+//#endregion
 //#region src/env-file.ts
 const REGEX_METACHARACTERS = /[.*+?^${}()|[\]\\]/g;
 function escapeForRegExp(key) {
@@ -851,6 +994,123 @@ function upsertEnvValues(existing, entries, options = {}) {
 	};
 }
 //#endregion
+//#region src/help.ts
+const ROOT_HELP = `clivly — embed a CRM in your app
+
+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 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
+
+Deprecated aliases — each runs part of \`clivly status\` and still works:
+  clivly ping                     credential + reachability
+  clivly connect                  the above, plus config and trigger URL
+  clivly doctor                   config, setup checks and edge safety
+
+Prefer \`clivly status\`: it runs the whole ladder and tells you which step you
+are on. The aliases are kept because output and docs have recommended them.
+
+Run \`clivly <command> --help\` for details on a command.
+`;
+const COMMAND_HELP = {
+	init: `clivly init — scaffold Clivly into this app
+
+Usage:
+  clivly init [--force] [--dry-run] [--diff] [--yes] [--no-login] [--no-browser]
+              [--schema <path|package>] [--db-import <specifier>]
+              [--auth-import <specifier>] [--contact-table <table>]
+              [--company-table <table>]
+
+Scaffolds clivly.config.ts, the Clivly route files, and .env placeholders.
+Detects your framework, ORM, auth adapter and app layout from the project.
+
+Options:
+  --dry-run            Show what would be written; write nothing
+  --diff               Show a diff for files that already exist
+  --force              Overwrite files Clivly owns
+  --yes                Skip prompts
+  --no-login           Skip browser pairing
+  --schema <p>         Path or package holding your ORM schema
+  --db-import <s>      Module specifier exporting your database instance
+  --auth-import <s>    Module specifier exporting your auth instance
+  --contact-table <t>  Table to map as contacts
+  --company-table <t>  Table to map as companies
+`,
+	add: `clivly add widget — scaffold the chat-session route
+
+Usage:
+  clivly add widget [--force] [--dry-run]
+
+Writes the route that mints chat-widget sessions. Creates no widget record —
+that lives in the Clivly dashboard.
+
+Options:
+  --dry-run   Show what would be written; write nothing
+  --force     Overwrite the route if it already exists
+`,
+	status: `clivly status — check your setup, step by step
+
+Usage:
+  clivly status [--verbose] [--config <path>] [--env-file <path>]
+
+Runs the setup ladder: credential, reachability, config load, edge-safety,
+setup checks, sync trigger. Read-only — writes nothing.
+
+Options:
+  --verbose         Show every check, including those that passed
+  --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
+
+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.
+`,
+	dev: `clivly dev — tunnel localhost so remote sync can reach you
+
+Usage:
+  clivly dev [--port <n>] [--api-url <url>] [--route-path <path>] [-- <cmd>]
+
+Opens a tunnel to your local app and points Clivly's sync trigger at it.
+Everything after \`--\` runs as your app's dev command.
+
+Options:
+  --port <n>          Local port your app listens on
+  --route-path <path> Path to your mounted tick route
+`,
+	login: `clivly login — pair this machine with Clivly
+
+Usage:
+  clivly login [--force] [--rotate] [--api-url <url>] [--no-browser]
+
+Opens a browser to approve this machine, then writes CLIVLY_SECRET_KEY and
+CLIVLY_SYNC_TRIGGER_SECRET to .env.
+
+Options:
+  --force       Re-pair even if credentials already exist
+  --rotate      Replace the existing credentials
+  --no-browser  Print the URL instead of opening a browser
+`
+};
+function isHelpRequest(argv) {
+	for (const arg of argv) {
+		if (arg === "--") return false;
+		if (arg === "--help" || arg === "-h") return true;
+	}
+	return false;
+}
+function helpFor(command) {
+	if (!command) return ROOT_HELP;
+	return COMMAND_HELP[command] ?? ROOT_HELP;
+}
+//#endregion
 //#region src/install.ts
 const defaultRun = (command, args, cwd) => new Promise((resolvePromise, reject) => {
 	const child = spawn(command, args, {
@@ -1090,11 +1350,11 @@ function credentialEntries(credentials) {
 	return [{
 		key: SECRET_KEY_ENV,
 		value: credentials.apiKey,
-		comment: "Org secret key — Settings → API keys"
+		comment: `Org secret key — ${CREDENTIALS_LOCATION}`
 	}, {
 		key: "CLIVLY_SYNC_TRIGGER_SECRET",
 		value: credentials.triggerSecret,
-		comment: "Signing secret — Integrations → Remote sync"
+		comment: `Signing secret — ${SYNC_SECRET_LOCATION}`
 	}];
 }
 function writeCredentials(options, credentials) {
@@ -1181,12 +1441,19 @@ function chooseSyncFields(table, todos) {
 		idField
 	};
 }
+const SPLIT_NAME_COLUMNS = /* @__PURE__ */ new Set([
+	"first_name",
+	"firstname",
+	"given_name"
+]);
 function buildEntity(table, concept, todos) {
 	const canonical = CANONICAL_FIELDS[concept];
 	const suggested = toFieldMap(scoreFieldMap(concept, toScoredTable(table)));
 	const fields = {};
 	for (const [key, column] of Object.entries(suggested)) if (canonical.includes(key)) fields[key] = column;
 	for (const required of requiredFieldsFor(concept)) if (!fields[required]) todos.push(`Could not map required ${concept} field "${required}" on "${table.tableName}" — add it manually.`);
+	const nameColumn = fields.name?.toLowerCase();
+	if (nameColumn && SPLIT_NAME_COLUMNS.has(nameColumn)) todos.push(`Mapped ${concept} "name" to "${fields.name}" on "${table.tableName}" — that is the given name only. Clivly mirrors one column per field, so add a full-name column if you want surnames.`);
 	const { cursorField, idField } = chooseSyncFields(table, todos);
 	return {
 		moduleKey: table.moduleKey,
@@ -1235,8 +1502,10 @@ function planInit(schema, overrides = {}) {
 	if (built && !contact) todos.push(`"${built.tableName}" was chosen as the contact entity but none of its columns could be mapped to name/email.`);
 	let company = null;
 	if (companyTable) {
-		const candidate = buildEntity(companyTable, "company", todos);
+		const candidateTodos = [];
+		const candidate = buildEntity(companyTable, "company", candidateTodos);
 		if (hasMappedFields(candidate)) {
+			todos.push(...candidateTodos);
 			company = candidate;
 			if (matchesConcept(companyTable.tableName, "contact")) todos.push(`"${companyTable.tableName}" matches both contact and company naming — assigned to company. Swap it to your contact entity if that's wrong.`);
 		} else todos.push(`"${companyTable.tableName}" looked like a company but no fields could be mapped — left it out. Add it to \`entities\` once you know which columns map to name/domain.`);
@@ -1257,15 +1526,99 @@ function planInit(schema, overrides = {}) {
 		contact,
 		company,
 		tableNames: schema.tables.map((table) => table.tableName),
+		contactCandidates: rankContactCandidates(schema.tables),
 		todos
 	};
 }
+const CONTACT_COLUMN_EVIDENCE = [
+	{
+		label: "email",
+		names: ["email", "email_address"],
+		weight: 3
+	},
+	{
+		label: "phone",
+		names: [
+			"phone",
+			"phone_number",
+			"mobile"
+		],
+		weight: 2
+	},
+	{
+		label: "first name",
+		names: [
+			"first_name",
+			"firstname",
+			"given_name"
+		],
+		weight: 2
+	},
+	{
+		label: "last name",
+		names: [
+			"last_name",
+			"lastname",
+			"surname",
+			"family_name"
+		],
+		weight: 2
+	},
+	{
+		label: "name",
+		names: [
+			"name",
+			"full_name",
+			"display_name"
+		],
+		weight: 1
+	}
+];
+const NAME_MATCH_WEIGHT = 4;
+/**
+* Rank the schema's tables by how much they look like people, best first.
+*
+* Used only on the failure path, where detection found nothing mappable and the
+* developer has to choose. `init` previously suggested `tableNames[0]` — the
+* first table in schema order — so a rental app was told to map its `lease`
+* table as contacts. Wrong guidance is worse than none: it is confident, and
+* the developer has no way to see it is wrong.
+*
+* Deliberately evidence-based rather than name-based alone, so a table whose
+* name Clivly has never heard of still surfaces on the strength of its columns.
+*/
+function rankContactCandidates(tables) {
+	return tables.map((table) => {
+		const columns = new Set(table.columns.flatMap((c) => [c.dbName.toLowerCase(), c.key.toLowerCase()]));
+		const reasons = [];
+		let score = 0;
+		if (matchesConcept(table.tableName, "contact")) {
+			score += NAME_MATCH_WEIGHT;
+			reasons.push("the name looks like a people table");
+		}
+		for (const evidence of CONTACT_COLUMN_EVIDENCE) {
+			const hit = evidence.names.find((name) => columns.has(name));
+			if (hit) {
+				score += evidence.weight;
+				reasons.push(hit);
+			}
+		}
+		return {
+			reasons,
+			score,
+			table: table.tableName
+		};
+	}).filter((candidate) => candidate.score > 0).sort((a, b) => b.score - a.score || a.table.localeCompare(b.table)).map(({ reasons, table }) => ({
+		reasons,
+		table
+	}));
+}
 //#endregion
 //#region src/render-config.ts
 const CLIVLY_ENV_KEYS = [
 	{
 		key: "CLIVLY_SECRET_KEY",
-		comment: "Org secret key — Settings → API keys"
+		comment: `Org secret key — ${CREDENTIALS_LOCATION}`
 	},
 	{
 		key: "CLIVLY_SYNC_TRIGGER_URL",
@@ -1273,7 +1626,7 @@ const CLIVLY_ENV_KEYS = [
 	},
 	{
 		key: "CLIVLY_SYNC_TRIGGER_SECRET",
-		comment: "Signing secret — Integrations → Remote sync"
+		comment: `Signing secret — ${SYNC_SECRET_LOCATION}`
 	}
 ];
 function renderFields(fields) {
@@ -1302,6 +1655,28 @@ function renderDbExpr(plan) {
 	if (!plan.db) return "db";
 	return dbIsInSchemaModule(plan) ? `schema.${plan.db.moduleKey}` : plan.db.moduleKey;
 }
+const TRAILING_SCHEMA_SEGMENT = /\/schema(\/index)?$/;
+/**
+* Where the `db` instance most likely lives, given where the schema was found.
+*
+* Only reached when discovery could not confirm one. Discovery *evaluates* a
+* candidate module and duck-types its exports for `.select`, which is the right
+* check but fails for the most common real-world db module: `drizzle(process.
+* env.DATABASE_URL!)` throws at import time when the env var is absent, and it
+* is absent precisely when a developer is running `clivly init` for the first
+* time. So the probe misses, through no fault of the project.
+*
+* The old fallback emitted `<YOUR_DB_MODULE>` — not a module specifier, not
+* valid TypeScript, and invisible until the config failed to load at runtime.
+* A best-guess relative path is strictly better: right for the conventional
+* layout (`lib/db/schema.ts` beside `lib/db/index.ts`), and when it is wrong it
+* is a module-not-found error at build time, naming a real path the developer
+* can correct.
+*/
+function guessDbImportPath(schemaImportPath) {
+	const trimmed = schemaImportPath.replace(TRAILING_SCHEMA_SEGMENT, "");
+	return trimmed === schemaImportPath || trimmed === "." || trimmed === "" ? "./db" : trimmed;
+}
 function renderImports(plan) {
 	const lines = [
 		"import { createClivlySDK, defineClivlyConfig } from \"clivly/sdk\";",
@@ -1309,8 +1684,10 @@ function renderImports(plan) {
 		"import { discoverFromDrizzle } from \"clivly/drizzle\";",
 		`import * as schema from "${plan.importPath}";`
 	];
-	if (!plan.db) lines.push("import { db } from \"<YOUR_DB_MODULE>\"; // TODO(clivly): replace with the path to your Drizzle `db` instance — NOT your schema file");
-	else if (!dbIsInSchemaModule(plan)) lines.push(`import { ${plan.db.moduleKey} } from "${plan.db.importPath}";`);
+	if (plan.db === null) {
+		const guess = guessDbImportPath(plan.importPath);
+		lines.push(`import { db } from "${guess}"; // TODO(clivly): verify this path points at your Drizzle \`db\` instance — NOT your schema file`);
+	} else if (!dbIsInSchemaModule(plan)) lines.push(`import { ${plan.db.moduleKey} } from "${plan.db.importPath}";`);
 	return lines.join("\n");
 }
 function renderTodoHeader(todos) {
@@ -1428,6 +1805,83 @@ function renderAuthWiring(auth, authInstance = null) {
 	}
 }
 //#endregion
+//#region src/tsconfig-alias.ts
+const LEADING_DOT_SLASH$1 = /^\.\//;
+const TRAILING_WILDCARD = /\/?\*$/;
+const TRAILING_SLASH = /\/$/;
+const BLOCK_COMMENT = /\/\*[\s\S]*?\*\//g;
+const LINE_COMMENT = /(^|[^:])\/\/.*$/gm;
+const TRAILING_COMMA = /,(\s*[}\]])/g;
+/**
+* `compilerOptions` from a tsconfig's text, or null when it cannot be read.
+*
+* tsconfig is JSONC — comments and trailing commas are legal and common, and
+* `JSON.parse` rejects both. Stripping them is enough here: this only ever reads
+* two string-valued fields, so the cost of being wrong is falling back to a
+* relative import, which already works.
+*/
+function parseTsconfig(source) {
+	try {
+		const stripped = source.replace(BLOCK_COMMENT, "").replace(LINE_COMMENT, "$1").replace(TRAILING_COMMA, "$1");
+		return JSON.parse(stripped).compilerOptions ?? null;
+	} catch {
+		return null;
+	}
+}
+/**
+* Strip a leading "./" and any trailing wildcard so two paths can be compared.
+*
+* `"./*"` — an alias rooted at the app itself — must reduce to the empty string,
+* not to a stray `"*"`; that is the mapping which makes a root-level
+* clivly.config alias-reachable.
+*/
+function normalize(value) {
+	return value.replace(LEADING_DOT_SLASH$1, "").replace(TRAILING_WILDCARD, "").replace(TRAILING_SLASH, "");
+}
+/**
+* The alias specifier that reaches `target`, or null when none does.
+*
+* `target` is app-root-relative and extensionless, e.g. `lib/auth` or
+* `clivly.config`. Only wildcard patterns are considered — an exact mapping
+* names one module and is not a prefix anything else can be rebased onto.
+*
+* Longest prefix wins, so `"@components/*": ["./src/components/*"]` beats
+* `"@/*": ["./src/*"]` for a module under `src/components`, matching how
+* TypeScript itself resolves.
+*/
+function aliasFor(input) {
+	if (!input.paths) return null;
+	const target = normalize(input.target);
+	let best = null;
+	for (const [pattern, targets] of Object.entries(input.paths)) {
+		if (!pattern.endsWith("/*")) continue;
+		const prefix = pattern.slice(0, -2);
+		for (const mapped of targets) {
+			const base = baseReaching(mapped, target);
+			if (base === null) continue;
+			const rest = base === "" ? target : target.slice(base.length + 1);
+			if (!best || base.length > best.length) best = {
+				alias: `${prefix}/${rest}`,
+				length: base.length
+			};
+		}
+	}
+	return best?.alias ?? null;
+}
+/**
+* The normalized base of `mapped` when it contains `target`, else null.
+*
+* A prefix must end at a segment boundary — `src` must not match `srcinternal`,
+* a different directory — and the target must be strictly inside the base, since
+* a wildcard needs a remainder to substitute.
+*/
+function baseReaching(mapped, target) {
+	if (!mapped.endsWith("/*")) return null;
+	const base = normalize(mapped);
+	if (base === "") return target === "" ? null : "";
+	return target.startsWith(`${base}/`) ? base : null;
+}
+//#endregion
 //#region src/scaffold.ts
 const TANSTACK_ROUTE_PREFIX = /^src\/routes\//;
 const TS_EXTENSION = /\.ts$/;
@@ -1459,10 +1913,14 @@ const ROUTE_PATHS = {
 	},
 	unknown: null
 };
-function routePath(framework, kind) {
+function applyLayout(framework, path, layout) {
+	if (framework !== "nextjs" || layout === "app") return path;
+	return `src/${path}`;
+}
+function routePath(framework, kind, layout = "app") {
 	const paths = ROUTE_PATHS[framework];
 	if (!paths) throw new Error(`No route path for framework: ${framework}`);
-	return paths[kind];
+	return applyLayout(framework, paths[kind], layout);
 }
 const WINDOWS_SEP = /\\/g;
 const LEADING_DOT_SLASH = /^\.\//;
@@ -1470,22 +1928,27 @@ function configImport(routeFilePath) {
 	const rel = relative(dirname(routeFilePath), "clivly.config").replace(WINDOWS_SEP, "/");
 	return rel.startsWith(".") ? rel : `./${rel}`;
 }
-function hostImportPath(routeFilePath, appRelative) {
+function hostImportPath(routeFilePath, appRelative, paths) {
 	const fromRoot = appRelative.replace(LEADING_DOT_SLASH, "");
+	const alias = aliasFor({
+		paths,
+		target: fromRoot
+	});
+	if (alias) return alias;
 	const rel = relative(dirname(routeFilePath), fromRoot).replace(WINDOWS_SEP, "/");
 	return rel.startsWith(".") ? rel : `./${rel}`;
 }
-function renderAuthPreamble(routeFilePath, auth) {
+function renderAuthPreamble(routeFilePath, auth, paths) {
 	const lines = [...auth.imports];
 	if (auth.hostImport) {
 		if (auth.hostImport.todo) lines.push(`// ${auth.hostImport.todo}`);
-		const path = hostImportPath(routeFilePath, auth.hostImport.path);
+		const path = hostImportPath(routeFilePath, auth.hostImport.path, paths);
 		lines.push(`import { ${auth.hostImport.binding} } from "${path}";`);
 	}
 	lines.push("", auth.body);
 	return lines.join("\n");
 }
-function renderPreamble(kind, importPath, auth, routeFilePath) {
+function renderPreamble(kind, importPath, auth, paths, routeFilePath) {
 	if (kind === "session") return `import { createChatSessionHandler } from "clivly/sdk";
 
 const handler = createChatSessionHandler({
@@ -1496,7 +1959,7 @@ const handler = createChatSessionHandler({
 });
 `;
 	if (kind === "verify") return `import clivly from "${importPath}";
-${renderAuthPreamble(routeFilePath, auth)}
+${renderAuthPreamble(routeFilePath, auth, paths)}
 const handler = clivly.createAuthVerifyHandler(resolveUser);
 `;
 	return `import clivly from "${importPath}";
@@ -1504,8 +1967,8 @@ const handler = clivly.createAuthVerifyHandler(resolveUser);
 const handler = clivly.createClivlyHandler();
 `;
 }
-function renderBody(framework, importPath, kind, auth, routeFilePath) {
-	const preamble = renderPreamble(kind, importPath, auth, routeFilePath);
+function renderBody(framework, importPath, kind, auth, routeFilePath, paths) {
+	const preamble = renderPreamble(kind, importPath, auth, paths, routeFilePath);
 	switch (framework) {
 		case "nextjs": return `${preamble}
 export const POST = (request: Request) => handler(request);
@@ -1535,9 +1998,9 @@ export default defineEventHandler((event) => handler(toWebRequest(event)));
 		default: throw new Error(`No route template for framework: ${framework}`);
 	}
 }
-function renderRouteFile(framework, kind, auth = renderAuthWiring("unknown")) {
-	const path = routePath(framework, kind);
-	let body = renderBody(framework, configImport(path), kind, auth, path);
+function renderRouteFile(framework, kind, auth = renderAuthWiring("unknown"), layout = "app", paths) {
+	const path = routePath(framework, kind, layout);
+	let body = renderBody(framework, configImport(path), kind, auth, path, paths);
 	if (framework === "tanstack-start") {
 		const url = `/${path.replace(TANSTACK_ROUTE_PREFIX, "").replace(TS_EXTENSION, "")}`;
 		body = body.replace("__ROUTE__", url);
@@ -1549,28 +2012,28 @@ const COMMON_FILES = [{
 	description: "Your Clivly configuration",
 	owned: false
 }];
-function planScaffold(framework) {
+function planScaffold(framework, layout = "app") {
 	const paths = ROUTE_PATHS[framework];
 	if (!paths) return [];
 	return [
 		{
-			path: paths.tick,
+			path: applyLayout(framework, paths.tick, layout),
 			description: "Clivly sync-trigger route (createClivlyHandler)",
 			owned: true
 		},
 		{
-			path: paths.verify,
+			path: applyLayout(framework, paths.verify, layout),
 			description: "Clivly auth-verify route (createAuthVerifyHandler) — finish resolveUser",
 			owned: true
 		},
 		...COMMON_FILES
 	];
 }
-function planWidgetScaffold(framework) {
+function planWidgetScaffold(framework, layout = "app") {
 	const paths = ROUTE_PATHS[framework];
 	if (!paths) return [];
 	return [{
-		path: paths.session,
+		path: applyLayout(framework, paths.session, layout),
 		description: "Clivly chat-session route (createChatSessionHandler) — add allowedOrigins",
 		owned: true
 	}];
@@ -1590,9 +2053,9 @@ function planFiles(args) {
 	const render = (path) => {
 		if (path === "clivly.config.ts") return renderInitConfig(args.plan);
 		const kind = path.includes("verify") ? "verify" : "tick";
-		return renderRouteFile(args.framework, kind, args.authWiring);
+		return renderRouteFile(args.framework, kind, args.authWiring, args.layout, parseTsconfig(args.readFile(join(args.cwd, "tsconfig.json")) ?? "")?.paths);
 	};
-	for (const file of planScaffold(args.framework)) {
+	for (const file of planScaffold(args.framework, args.layout)) {
 		const contents = render(file.path);
 		mutations.push({
 			path: file.path,
@@ -1623,8 +2086,8 @@ function planMutations(args) {
 	};
 }
 function planWidgetMutations(args) {
-	return planWidgetScaffold(args.framework).map((file) => {
-		const contents = renderRouteFile(args.framework, "session");
+	return planWidgetScaffold(args.framework, args.layout).map((file) => {
+		const contents = renderRouteFile(args.framework, "session", void 0, args.layout);
 		return {
 			path: file.path,
 			contents,
@@ -1949,7 +2412,17 @@ const ALLOWED_CALLS = /* @__PURE__ */ new Set([
 	"while"
 ]);
 const SIDE_EFFECT_CALLS = /^(dotenv\.config|config|configDotenv|fileURLToPath|readFileSync|require|process\.chdir)$/;
+const NATIVE_PACKAGES = /* @__PURE__ */ new Set([
+	"bcrypt",
+	"better-sqlite3",
+	"canvas",
+	"node-gyp",
+	"pg-native",
+	"sharp",
+	"sqlite3"
+]);
 const ENV_HINT = "Move it to clivly.cli.ts (`envFiles`) or pass --env-file — the CLI reads those in Node, so your config stays edge-safe.";
+const NATIVE_HINT = "A compiled binary cannot load on an edge runtime — this is the \"Could not locate the bindings file\" / ERR_DLOPEN_FAILED failure. Import your db lazily inside a function, or use a driver that speaks HTTP (e.g. @neondatabase/serverless) in the config.";
 function isNodeBuiltin(specifier) {
 	if (specifier.startsWith("node:")) return true;
 	return NODE_BUILTINS.has(specifier.split("/")[0] ?? "");
@@ -1966,6 +2439,12 @@ function specifierIssue(specifier, line) {
 		hint: ENV_HINT,
 		line
 	};
+	if (NATIVE_PACKAGES.has(specifier.split("/")[0] ?? "")) return {
+		code: "native_module_in_edge_config",
+		detail: `imports "${specifier}", which ships a compiled binary`,
+		hint: NATIVE_HINT,
+		line
+	};
 	if (isNodeBuiltin(specifier)) return {
 		code: "node_builtin_in_edge_config",
 		detail: `imports "${specifier}", which does not exist on an edge runtime`,
@@ -2005,8 +2484,56 @@ function analyzeEdgeSafety(source) {
 	});
 	return issues;
 }
+/** Every relative specifier `source` imports, in first-seen order, deduped. */
+function relativeImports(source) {
+	const seen = /* @__PURE__ */ new Set();
+	for (const rawLine of source.split(NEWLINE)) {
+		const line = stripComment(rawLine);
+		const specifier = BARE_IMPORT.exec(line)?.[1] ?? IMPORT_FROM.exec(line)?.[1] ?? REQUIRE_CALL.exec(line)?.[1];
+		if (specifier?.startsWith(".")) seen.add(specifier);
+	}
+	return [...seen];
+}
+/**
+* Edge-safety for the config *and* the modules it imports directly.
+*
+* The dominant real-world shape is a clean-looking config with
+* `import { db } from "./lib/db"`, where the problem is one hop away and
+* invisible to a scan that reads only the config file.
+*
+* One hop, not more: each additional level multiplies the files read for a
+* shrinking return, and the config's own imports are where a host app puts its
+* database. Bare specifiers are never followed — resolving into node_modules is
+* a different job with different failure modes, and the denylist already covers
+* the packages that matter.
+*
+* `readModule` returns source text, or null when the module cannot be read;
+* unreadable is not a finding, since a scan is not a build.
+*/
+function analyzeConfigTree(input) {
+	const issues = analyzeEdgeSafety(input.source);
+	for (const specifier of relativeImports(input.source)) {
+		const source = input.readModule(specifier);
+		if (source === null) continue;
+		for (const issue of analyzeEdgeSafety(source)) issues.push({
+			...issue,
+			module: specifier
+		});
+	}
+	return issues;
+}
 //#endregion
 //#region src/status-stages.ts
+const MODULE_CANDIDATES = [
+	".ts",
+	".tsx",
+	".js",
+	".mjs",
+	".cjs",
+	"/index.ts",
+	"/index.js",
+	""
+];
 function defaultReadConfigSource(path) {
 	try {
 		return readFileSync(path, "utf8");
@@ -2021,10 +2548,11 @@ const REASON_HINT = {
 	rate_limited: "Rate limited (429). Wait a moment and retry.",
 	server_error: "Clivly returned a server error (5xx). Retry shortly.",
 	client_error: "The request was rejected (4xx). Check your configuration.",
+	server_too_old: "This Clivly server is older than your CLI and has no /clivly/sdk/ping. Upgrade the server, or pin the CLI to match it.",
 	network_error: "Could not reach Clivly. Check your network or --api-url."
 };
 const apiKeyStage = {
-	id: "api-key",
+	id: "credential",
 	label: "API key present",
 	run(ctx) {
 		if (ctx.apiKey) return Promise.resolve({
@@ -2034,20 +2562,29 @@ const apiKeyStage = {
 		return Promise.resolve({
 			state: "fail",
 			detail: "Secret key is not set.",
-			hint: "Copy your secret key from Settings → API keys into CLIVLY_SECRET_KEY in .env."
+			hint: `Copy your secret key from ${CREDENTIALS_LOCATION} into CLIVLY_SECRET_KEY in .env.`
 		});
 	}
 };
-const heartbeatStage = {
-	id: "heartbeat",
+const reachabilityStage = {
+	id: "application",
 	label: "Clivly reachable",
 	needs: [apiKeyStage.id],
 	async run(ctx) {
 		const result = await ctx.connect(ctx.apiKey, ctx.apiUrl);
-		if (result.ok) return {
-			state: "pass",
-			detail: `Reached org: ${result.org?.name ?? "(unnamed org)"}${result.org?.id ? ` (${result.org.id})` : ""}`
-		};
+		if (result.ok) {
+			const name = result.org?.name ?? "(unnamed org)";
+			const id = result.org?.id ? ` (${result.org.id})` : "";
+			if (result.appLastSeenAt === null) return {
+				state: "warn",
+				detail: `Reached org: ${name}${id} — your app has not connected yet`,
+				hint: "Start your app with the Clivly SDK mounted; it will appear in the dashboard within a minute."
+			};
+			return {
+				state: "pass",
+				detail: `Reached org: ${name}${id}`
+			};
+		}
 		const status = result.status === null ? "no response" : `HTTP ${result.status}`;
 		return {
 			state: "fail",
@@ -2075,22 +2612,76 @@ const configStage = {
 		}
 	}
 };
-const LADDER_OWNED_CHECKS = /* @__PURE__ */ new Set(["API key present", "Heartbeat"]);
+const LADDER_OWNED_CHECKS = /* @__PURE__ */ new Set(["API key present", "Clivly reachable"]);
+const sdkChecksStage = {
+	id: "setup-checks",
+	label: "Setup checks",
+	needs: [configStage.id],
+	async run(ctx) {
+		const owned = (await ctx.sdk.doctor()).checks.filter((check) => !LADDER_OWNED_CHECKS.has(check.name));
+		const counted = owned.filter((check) => !check.skipped);
+		const passed = counted.filter((check) => check.ok).length;
+		const ok = counted.every((check) => check.ok);
+		const warned = counted.filter((check) => check.warn).length;
+		const summary = warned > 0 ? `${passed} of ${counted.length} passed, ${warned} with warnings` : `${passed} of ${counted.length} passed`;
+		return {
+			state: ok ? "pass" : "fail",
+			detail: summary,
+			sub: owned.map((check) => ({
+				label: check.name,
+				ok: check.ok,
+				skipped: check.skipped,
+				warn: check.warn,
+				detail: check.detail
+			}))
+		};
+	}
+};
+const triggerUrlStage = {
+	id: "trigger-url",
+	label: "Sync trigger URL",
+	needs: [configStage.id],
+	run(ctx) {
+		const url = ctx.sdk?.syncTrigger?.url;
+		if (url) return Promise.resolve({
+			state: "pass",
+			detail: url
+		});
+		return Promise.resolve({
+			state: "warn",
+			detail: "Not set — remote sync cannot call back into this app.",
+			hint: "Set CLIVLY_SYNC_TRIGGER_URL once the app is deployed. For local development run `clivly dev` — it opens a tunnel and registers the URL for you. Push-only setups can ignore this."
+		});
+	}
+};
 /** The full ladder, in the order a developer completes setup. */
 const STATUS_STAGES = [
 	apiKeyStage,
-	heartbeatStage,
+	reachabilityStage,
 	configStage,
 	{
 		id: "runtime",
 		label: "clivly.config is edge-safe",
+		needs: [configStage.id],
 		run(ctx) {
 			const source = (ctx.readConfigSource ?? defaultReadConfigSource)(ctx.configPath);
 			if (source === null) return Promise.resolve({
 				state: "skip",
 				detail: "config not readable"
 			});
-			const issues = analyzeEdgeSafety(source);
+			const read = ctx.readConfigSource ?? defaultReadConfigSource;
+			const base = dirname(ctx.configPath);
+			const issues = analyzeConfigTree({
+				source,
+				readModule: (specifier) => {
+					const target = resolve(base, specifier);
+					for (const candidate of MODULE_CANDIDATES) {
+						const found = read(`${target}${candidate}`);
+						if (found !== null) return found;
+					}
+					return null;
+				}
+			});
 			if (issues.length === 0) return Promise.resolve({
 				state: "pass",
 				detail: "no Node-only code at module scope"
@@ -2107,43 +2698,8 @@ const STATUS_STAGES = [
 			});
 		}
 	},
-	{
-		id: "setup-checks",
-		label: "Setup checks",
-		needs: [configStage.id],
-		async run(ctx) {
-			const owned = (await ctx.sdk.doctor()).checks.filter((check) => !LADDER_OWNED_CHECKS.has(check.name));
-			const counted = owned.filter((check) => !check.skipped);
-			const passed = counted.filter((check) => check.ok).length;
-			return {
-				state: counted.every((check) => check.ok) ? "pass" : "fail",
-				detail: `${passed} of ${counted.length} passed`,
-				sub: owned.map((check) => ({
-					label: check.name,
-					ok: check.ok,
-					skipped: check.skipped,
-					detail: check.detail
-				}))
-			};
-		}
-	},
-	{
-		id: "trigger-url",
-		label: "Sync trigger URL",
-		needs: [configStage.id],
-		run(ctx) {
-			const url = ctx.sdk?.syncTrigger?.url;
-			if (url) return Promise.resolve({
-				state: "pass",
-				detail: url
-			});
-			return Promise.resolve({
-				state: "warn",
-				detail: "Not set — remote sync cannot call back into this app.",
-				hint: "Set CLIVLY_SYNC_TRIGGER_URL once the app is deployed. For local development run `clivly dev` — it opens a tunnel and registers the URL for you. Push-only setups can ignore this."
-			});
-		}
-	}
+	sdkChecksStage,
+	triggerUrlStage
 ];
 function defaultLoadSdk(path) {
 	return loadConfigSdk(path, "doctor");
@@ -2153,15 +2709,15 @@ function defaultLoadSdk(path) {
 /** Stage ids each legacy command maps onto. */
 const ALIAS_STAGE_IDS = {
 	status: STATUS_STAGES.map((stage) => stage.id),
-	ping: ["api-key", "heartbeat"],
+	ping: ["credential", "application"],
 	doctor: [
 		"config",
 		"runtime",
 		"setup-checks"
 	],
 	connect: [
-		"api-key",
-		"heartbeat",
+		"credential",
+		"application",
 		"config",
 		"trigger-url"
 	]
@@ -2177,9 +2733,9 @@ const defaultConnect = (apiKey, apiUrl) => createClivlySDK({
 	apiKey,
 	apiUrl,
 	retry: { maxAttempts: 1 }
-}).connect();
+}).ping();
 function subMark(sub) {
-	if (sub.skipped) return "⚠️ ";
+	if (sub.skipped || sub.warn) return "⚠️ ";
 	return sub.ok ? "✅" : "❌";
 }
 function renderStage(result, verbose, out) {
@@ -2187,7 +2743,7 @@ function renderStage(result, verbose, out) {
 	const detail = result.detail ? ` — ${result.detail}` : "";
 	out(`  ${MARK[result.state]} ${step} · ${result.label}${detail}\n`);
 	for (const sub of result.sub ?? []) {
-		if (!(verbose || sub.skipped || !sub.ok)) continue;
+		if (!(verbose || sub.skipped || sub.warn || !sub.ok)) continue;
 		const subDetail = sub.detail ? ` — ${sub.detail}` : "";
 		out(`       ${subMark(sub)} ${sub.label}${subDetail}\n`);
 	}
@@ -2213,6 +2769,12 @@ async function runStatus(options) {
 }
 //#endregion
 //#region src/index.ts
+const ENV_FILE_CANDIDATES = [
+	".env",
+	".env.local",
+	".dev.vars"
+];
+const CONFIG_WATCH_DEBOUNCE_MS = 150;
 function flagValue(argv, flag) {
 	const index = argv.indexOf(flag);
 	return index >= 0 ? argv[index + 1] : void 0;
@@ -2231,7 +2793,10 @@ const KNOWN_COMMANDS = [
 	"push-schema",
 	"dev",
 	"login",
-	"help"
+	"help",
+	"ping",
+	"doctor",
+	"connect"
 ];
 function editDistance(a, b) {
 	const m = a.length;
@@ -2274,6 +2839,7 @@ function readDeps(cwd) {
 }
 const ADD_USAGE = "Usage: clivly add widget [--force] [--dry-run]";
 const defaultAddDeps = {
+	fileExists: existsSync,
 	out: (line) => process.stdout.write(line),
 	readFile: (path) => existsSync(path) ? readFileSync(path, "utf8") : null,
 	writeFile: (path, contents) => {
@@ -2293,14 +2859,21 @@ function runAdd(argv, cwd, deps = defaultAddDeps) {
 		deps.out("Couldn't detect your framework from package.json. `clivly add widget` supports Next.js, TanStack Start, SvelteKit, Remix, and Nuxt.\n");
 		return 1;
 	}
+	const layout = resolveAppLayout(cwd, deps.fileExists);
 	const force = argv.includes("--force");
 	const dryRun = argv.includes("--dry-run");
 	const files = planWidgetMutations({
 		framework,
 		cwd,
 		force,
+		layout,
 		readFile: (path) => deps.readFile(path)
 	});
+	const shadowing = shadowedAppDirError(cwd, framework, files.map((file) => file.path), deps.fileExists);
+	if (shadowing) {
+		deps.out(shadowing);
+		return 1;
+	}
 	deps.out(`\nClivly add widget — ${FRAMEWORK_LABELS[framework]}\n\n`);
 	if (dryRun) deps.out("Dry run — nothing was written.\n\n");
 	for (const file of files) {
@@ -2321,7 +2894,7 @@ function runAdd(argv, cwd, deps = defaultAddDeps) {
 	}
 	if (!dryRun) {
 		const sessionPath = files[0]?.path ?? "";
-		deps.out(`\nNext steps:\n  1. Add your site origins to allowedOrigins in ${sessionPath}\n  2. Create the widget + set allowed origins in the Clivly dashboard (Settings → Chat widget)\n  3. Embed it: <ClivlyChatWidget widgetId="…" />\n`);
+		deps.out(`\nNext steps:\n  1. Add your site origins to allowedOrigins in ${sessionPath}\n  2. Create the widget + set allowed origins at ${WIDGET_LOCATION}\n  3. Embed it: <ClivlyChatWidget widgetId="…" />\n`);
 	}
 	return 0;
 }
@@ -2332,6 +2905,13 @@ function readOwnVersion() {
 		if (pkg.name === "clivly" && pkg.version) return pkg.version;
 	} catch {}
 }
+function readOwnEngines() {
+	const req = createRequire(import.meta.url);
+	for (const rel of ["./package.json", "../package.json"]) try {
+		const pkg = req(rel);
+		if (pkg.name === "clivly") return pkg.engines?.node;
+	} catch {}
+}
 /**
 * Parse a `--db-import` / `--auth-import` value into a discovery-shaped override.
 *
@@ -2361,12 +2941,24 @@ function authInstanceFromFlag(flag) {
 function defaultReadFile(path) {
 	return existsSync(path) ? readFileSync(path, "utf8") : null;
 }
+function resolveEnvPath(cwd) {
+	const framework = detectFramework(readDeps(cwd));
+	return join(cwd, resolveEnvFile({
+		existing: ENV_FILE_CANDIDATES.filter((name) => {
+			const path = join(cwd, name);
+			if (!existsSync(path)) return false;
+			const contents = readFileSync(path, "utf8");
+			return isKeySet(contents, "CLIVLY_SECRET_KEY") || isKeySet(contents, "CLIVLY_API_KEY");
+		}),
+		framework
+	}));
+}
 function defaultReadEnv(cwd) {
-	const path = join(cwd, ".env");
+	const path = resolveEnvPath(cwd);
 	return existsSync(path) ? readFileSync(path, "utf8") : "";
 }
 function defaultWriteEnv(cwd, contents) {
-	writeFileSync(join(cwd, ".env"), contents, "utf8");
+	writeFileSync(resolveEnvPath(cwd), contents, "utf8");
 }
 function defaultIsInteractive() {
 	return Boolean(process.stdin.isTTY) && Boolean(process.stdout.isTTY) && !process.env.CI;
@@ -2393,6 +2985,8 @@ function resolveInitDeps(options) {
 			graph: graphFor(cwd)
 		})),
 		readFile: options.readFile ?? defaultReadFile,
+		fileExists: options.fileExists ?? existsSync,
+		resolveAppLayout: options.resolveAppLayout ?? resolveAppLayout,
 		writeConfig: options.writeConfig ?? ((path, contents) => {
 			mkdirSync(dirname(path), { recursive: true });
 			writeFileSync(path, contents, "utf8");
@@ -2413,6 +3007,7 @@ function resolveInitDeps(options) {
 			rotate: false
 		})),
 		framework: "unknown",
+		layout: "app",
 		authWiring: renderAuthWiring("unknown")
 	};
 }
@@ -2427,11 +3022,15 @@ async function acquireSchema(options, deps) {
 	const orm = detectOrm(appDeps);
 	const auth = detectAuth(appDeps);
 	deps.framework = framework;
-	deps.authWiring = renderAuthWiring(auth, auth === "better-auth" ? authInstanceFromFlag(options.authImportFlag) ?? await deps.probeAuth(options.cwd) : null);
+	const layout = deps.resolveAppLayout(options.cwd, deps.fileExists);
+	deps.layout = layout;
 	out("\nClivly init\n");
+	deps.authWiring = renderAuthWiring(auth, auth === "better-auth" ? authInstanceFromFlag(options.authImportFlag) ?? await deps.probeAuth(options.cwd) : null);
 	out(`  Framework: ${FRAMEWORK_LABELS[framework]}\n`);
 	out(`  ORM:       ${orm}\n`);
-	out(`  Auth:      ${auth}${deps.authWiring.complete ? " (wired)" : ""}\n\n`);
+	out(`  Auth:      ${auth}${deps.authWiring.complete ? " (wired)" : ""}\n`);
+	if (framework === "nextjs") out(`  Layout:    ${layout}\n`);
+	out("\n");
 	if (orm !== "drizzle") {
 		out(`clivly init currently generates config for Drizzle only. Detected ORM: ${orm}\n`);
 		return { code: 1 };
@@ -2475,6 +3074,7 @@ function mutationsFor(options, deps, plan) {
 		cwd: options.cwd,
 		force: options.force,
 		framework: deps.framework,
+		layout: deps.layout,
 		authWiring: deps.authWiring,
 		plan,
 		readFile: deps.readFile,
@@ -2534,14 +3134,15 @@ function previewMutations(deps, mutations, options) {
 	}
 	out(options.diff ? "\nRe-run without --diff to apply; --force to overwrite the files marked conflict.\n" : "\nRe-run without --dry-run to apply.\n");
 }
-function printNextSteps(out, authComplete, loginRan) {
+function printNextSteps(out, authComplete, loginRan, envFile) {
 	out("\nNext steps:\n");
-	out(loginRan ? "  1. Credentials written by `clivly login`\n" : "  1. Add CLIVLY_SECRET_KEY to .env — create one in the Clivly dashboard\n     under Integrations → Create API Key (or Settings → API keys)\n     (the legacy CLIVLY_API_KEY is still accepted)\n");
+	out(loginRan ? "  1. Credentials written by `clivly login`\n" : `  1. Add CLIVLY_SECRET_KEY to ${envFile} — create one at\n     ${CREDENTIALS_LOCATION}\n     (the legacy CLIVLY_API_KEY is still accepted)\n`);
 	out("  2. Set CLIVLY_SYNC_TRIGGER_URL to your public tick route\n");
 	out("     Local dev? Run `clivly dev` to open a tunnel, or skip this step until you deploy (remote sync is deploy-only locally).\n");
 	const step = authComplete ? 3 : 4;
 	if (!authComplete) out("  3. Finish resolveUser in the auth/verify route\n");
 	out(`  ${step}. Run \`clivly status\` to see where you are\n`);
+	out("\nAfter editing clivly.config.ts, restart your app — it loads the config\nat boot, so a running server keeps using the old one.\n");
 }
 function credentialsMissing(envContents) {
 	return !(isKeySet(envContents, "CLIVLY_SECRET_KEY") || isKeySet(envContents, "CLIVLY_API_KEY"));
@@ -2562,6 +3163,11 @@ async function scaffold(options, deps, plan) {
 	const pm = deps.detectPackageManager(options.cwd);
 	const packages = [resolveRuntimeInstallSpec(deps), ...deps.authWiring.packages];
 	const mutations = mutationsFor(options, deps, plan);
+	const shadowing = shadowedAppDirError(options.cwd, deps.framework, mutations.files.map((file) => file.path), deps.fileExists);
+	if (shadowing) {
+		out(shadowing);
+		return 1;
+	}
 	if (options.dryRun || options.diff) {
 		out(`\nWould install (${pm}): ${packages.join(", ")}\n`);
 		previewMutations(deps, mutations, {
@@ -2586,7 +3192,7 @@ async function scaffold(options, deps, plan) {
 			out("  Run `clivly login` from a terminal to write CLIVLY_SECRET_KEY and CLIVLY_SYNC_TRIGGER_SECRET.\n");
 		} else loginRan = await deps.login(options.cwd) === 0;
 	}
-	printNextSteps(out, deps.authWiring.complete, loginRan);
+	printNextSteps(out, deps.authWiring.complete, loginRan, envFileFor(detectFramework(deps.readDepsFn(options.cwd))));
 	return 0;
 }
 function normalizeAppRoot(options) {
@@ -2653,8 +3259,18 @@ function printNoContactGuidance(out, plan, options) {
 	out(`\n  Tables in ${plan.importPath}:\n`);
 	for (const name of plan.tableNames) out(`    ${name}\n`);
 	const schemaArg = options.schemaFlag ? ` --schema ${options.schemaFlag}` : "";
-	out("\n  Pick the one that holds your people and re-run:\n");
-	out(`    clivly init${schemaArg} --contact-table ${plan.tableNames[0]}\n\n`);
+	const best = plan.contactCandidates[0];
+	if (best) {
+		out(`\n  Best guess: ${best.table} — ${best.reasons.join(", ")}\n`);
+		const runnerUp = plan.contactCandidates.slice(1, 3).map((candidate) => candidate.table);
+		if (runnerUp.length > 0) out(`  Also possible: ${runnerUp.join(", ")}\n`);
+		out("\n  Confirm it and re-run:\n");
+		out(`    clivly init${schemaArg} --contact-table ${best.table}\n\n`);
+		return;
+	}
+	out("\n  Nothing here looks like a people table — no email, phone or name\n");
+	out("  columns turned up. Pick the one that holds your people and re-run:\n");
+	out(`    clivly init${schemaArg} --contact-table ${plan.tableNames[0] ?? "<table>"}\n\n`);
 	out("  Nothing was written — Clivly needs one entity before a config can load.\n\n");
 }
 function hasCloudflaredOnPath() {
@@ -2750,6 +3366,22 @@ function defaultDevDeps(options) {
 		},
 		out: (line) => {
 			process.stdout.write(`${line}\n`);
+		},
+		watchConfig: (cwd, onChange) => {
+			const target = resolveConfigPath(cwd);
+			try {
+				let timer = null;
+				const watcher = watch(target, () => {
+					if (timer) clearTimeout(timer);
+					timer = setTimeout(onChange, CONFIG_WATCH_DEBOUNCE_MS);
+				});
+				return () => {
+					if (timer) clearTimeout(timer);
+					watcher.close();
+				};
+			} catch {
+				return null;
+			}
 		}
 	};
 }
@@ -2828,6 +3460,21 @@ function runInitFromArgv(argv, cwd) {
 }
 async function main(argv) {
 	const [command, ...rest] = argv;
+	if (command === "-h" || command === "--help" || isHelpRequest(rest)) {
+		process.stdout.write(helpFor(command));
+		return 0;
+	}
+	if (command === "--version" || command === "-v") {
+		process.stdout.write(`${readOwnVersion() ?? "unknown"}\n`);
+		return 0;
+	}
+	if (!process.env.CLIVLY_SKIP_ENGINE_CHECK) {
+		const engineProblem = engineError(process.version, readOwnEngines());
+		if (engineProblem) {
+			process.stderr.write(engineProblem);
+			return 1;
+		}
+	}
 	let cliEnvFiles = [];
 	try {
 		cliEnvFiles = (await loadCliConfig(process.cwd()))?.envFiles ?? [];
@@ -2846,14 +3493,16 @@ async function main(argv) {
 		case "status":
 		case "ping":
 		case "doctor":
-		case "connect": return await runStatus({
-			cwd: process.cwd(),
-			apiKey: readSecretKeyEnv(process.env),
-			apiUrl: flagValue(rest, "--api-url") ?? process.env.CLIVLY_API_URL,
-			configPath: flagValue(rest, "--config"),
-			only: ALIAS_STAGE_IDS[command],
-			verbose: rest.includes("--verbose")
-		});
+		case "connect":
+			if (command !== "status") process.stderr.write(`\`clivly ${command}\` is a deprecated alias that runs part of \`clivly status\`. Prefer \`clivly status\`.\n`);
+			return await runStatus({
+				cwd: process.cwd(),
+				apiKey: readSecretKeyEnv(process.env),
+				apiUrl: flagValue(rest, "--api-url") ?? process.env.CLIVLY_API_URL,
+				configPath: flagValue(rest, "--config"),
+				only: ALIAS_STAGE_IDS[command],
+				verbose: rest.includes("--verbose")
+			});
 		case "dev": {
 			const apiKey = readSecretKeyEnv(process.env);
 			const apiUrl = flagValue(rest, "--api-url") ?? process.env.CLIVLY_API_URL ?? "https://api.clivly.com";
@@ -2876,14 +3525,11 @@ async function main(argv) {
 			openBrowser: !rest.includes("--no-browser"),
 			deps: defaultLoginDeps()
 		});
-		case "--version":
-		case "-v":
-			process.stdout.write(`${readOwnVersion() ?? "unknown"}\n`);
-			return 0;
 		case void 0:
+			process.stdout.write(ROOT_HELP);
+			return 0;
 		case "help":
-		case "--help":
-			process.stdout.write("clivly — embed a CRM in your app\n\nUsage:\n  clivly init [--force] [--dry-run] [--diff] [--yes] [--no-login] [--no-browser]\n              [--schema <path|package>] [--db-import <specifier>] [--auth-import <specifier>]\n                                Scaffold Clivly (config, routes, .env) for your app\n  clivly add widget [--force] [--dry-run]   Scaffold the chat-session route\n  clivly status [--verbose] [--config <path>] [--env-file <path>]   Check your setup, step by step\n  clivly push-schema [--config <path>]   Report your schema to Clivly without deploying\n  clivly dev [--port <n>] [--api-url <url>] [--route-path <path>] [-- <cmd>]   Tunnel localhost for remote sync\n  clivly login [--force] [--rotate] [--api-url <url>] [--no-browser]   Pair this machine and write CLIVLY_SECRET_KEY / CLIVLY_SYNC_TRIGGER_SECRET to .env\n  clivly --version                Print the installed clivly version\n");
+			process.stdout.write(helpFor(rest[0]));
 			return 0;
 		default: {
 			process.stdout.write(`Unknown command: ${command}\n`);