clivly 0.4.1 → 0.7.0

package/index.mjs

@@ -1,16 +1,116 @@
 #!/usr/bin/env node
-import { t as CANONICAL_FIELDS } from "./entity-config-D3YpQB0z.mjs";
-import "./mapping-score-CPPvwoZC.mjs";
-import { matchesConcept, requiredFieldsFor, scoreFieldMap, scoreRelationships, suggestCursorField, toFieldMap } from "./core-entity-heuristics.mjs";
-import { t as createClivlySDK } from "./sdk-DdzBxgMx.mjs";
+import { t as CANONICAL_FIELDS } from "./entity-config-va2bkH5o.mjs";
+import "./core-entity-config.mjs";
+import "./mapping-score-C68uAqGB.mjs";
+import { matchesConcept, requiredFieldsFor, scoreFieldMap, scoreRelationships, suggestCursorField, toFieldMap } from "./internal-entity-heuristics.mjs";
+import "./core-entity-heuristics.mjs";
+import "./core-mapping-score.mjs";
+import { t as createClivlySDK } from "./sdk-C_1sGiH8.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 { homedir, hostname } from "node:os";
-import { delimiter, dirname, isAbsolute, join, relative, resolve } from "node:path";
+import { delimiter, dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
 import { createInterface } from "node:readline/promises";
-import { fileURLToPath, pathToFileURL } from "node:url";
 import { createJiti } from "jiti";
+import { fileURLToPath, pathToFileURL } from "node:url";
+//#region src/load-config.ts
+const CONFIG_HINT = "Expected clivly.config.ts at your app root exporting `createClivlySDK({...})`.";
+function resolveConfigPath(cwd, configPath) {
+	return resolve(cwd, configPath ?? "clivly.config.ts");
+}
+/**
+* Load the config and return its default export, checking it carries the method
+* the caller needs. The check is by capability rather than by type: the config
+* is the developer's own SDK instance, and a clear "this isn't an SDK instance"
+* beats a TypeError deep inside a command.
+*/
+/**
+* The first meaningful line of an error message. jiti reports a failed
+* resolution with a multi-line "Require stack:" dump naming Clivly's own
+* internal files — noise that tells the developer nothing about their app and
+* buries the one line that does.
+*/
+function firstLine(message) {
+	return message.split("\n")[0]?.trim() ?? "";
+}
+/**
+* Describe why the config failed to load, in one line the developer can act on.
+*
+* A config that fails its own schema validation throws a zod error carrying
+* structured `issues`, but whose `message` is a multi-line JSON dump — its
+* first line is a bare "[", so `firstLine` alone reduced the entire diagnosis
+* to a single bracket. Render the issues as `path: message` instead, which is
+* what actually names the entity to fix. Anything else keeps the require-stack
+* trimming `firstLine` exists for.
+*/
+function describeLoadError(error) {
+	const issues = error.issues;
+	if (Array.isArray(issues) && issues.length > 0) return issues.map((raw) => {
+		const issue = raw;
+		const path = Array.isArray(issue.path) ? issue.path.join(".") : "";
+		const message = typeof issue.message === "string" ? issue.message : "invalid value";
+		return path ? `${path}: ${message}` : message;
+	}).join("; ");
+	return firstLine(error?.message ?? String(error));
+}
+async function loadConfigSdk(path, requiredMethod) {
+	const jiti = createJiti(import.meta.url);
+	let mod;
+	try {
+		mod = await jiti.import(path);
+	} catch (error) {
+		throw new Error(describeLoadError(error));
+	}
+	const sdk = mod.default ?? mod;
+	if (typeof sdk?.[requiredMethod] !== "function") throw new Error("default export is not a Clivly SDK instance");
+	return sdk;
+}
+//#endregion
+//#region src/cli-config.ts
+const CLI_CONFIG_NAMES = [
+	"clivly.cli.ts",
+	"clivly.cli.js",
+	"clivly.cli.mjs"
+];
+/** The app's CLI config, or null when it has none — which is the normal case. */
+function resolveCliConfigPath(cwd) {
+	for (const name of CLI_CONFIG_NAMES) {
+		const path = join(cwd, name);
+		if (existsSync(path)) return path;
+	}
+	return null;
+}
+function readEnvFiles(config) {
+	const envFiles = config.envFiles;
+	if (envFiles === void 0) return;
+	if (!Array.isArray(envFiles)) throw new Error("clivly.cli.ts: envFiles must be an array of paths, e.g. [\"../server/.env\"]");
+	if (envFiles.some((entry) => typeof entry !== "string")) throw new Error("clivly.cli.ts: every envFiles entry must be a string");
+	return envFiles;
+}
+/**
+* Load `clivly.cli.ts` if the app has one.
+*
+* A malformed config throws rather than being silently ignored: a developer who
+* wrote `envFiles` and sees nothing happen has no way to tell the difference
+* between "not supported" and "I typed it wrong", and the symptom they get
+* instead is a missing API key several steps later.
+*/
+async function loadCliConfig(cwd) {
+	const path = resolveCliConfigPath(cwd);
+	if (!path) return null;
+	let mod;
+	try {
+		mod = await createJiti(import.meta.url).import(path);
+	} catch (error) {
+		throw new Error(`clivly.cli.ts: ${describeLoadError(error)}`);
+	}
+	const config = mod?.default ?? mod;
+	if (typeof config !== "object" || config === null || Array.isArray(config)) throw new Error("clivly.cli.ts must export an object as its default export");
+	const envFiles = readEnvFiles(config);
+	return envFiles ? { envFiles } : {};
+}
+//#endregion
 //#region src/detect.ts
 const FRAMEWORK_MARKERS = [
 	{
@@ -152,7 +252,7 @@ function detectDevCommand(scripts, explicit) {
 	return null;
 }
 const OVERRIDE_FAILURE_CAUSES = {
-	unauthorized: "CLIVLY_API_KEY is invalid for this workspace/backend.",
+	unauthorized: "CLIVLY_SECRET_KEY is invalid for this workspace/backend.",
 	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."
 };
@@ -200,7 +300,7 @@ async function runDev(options) {
 		return 0;
 	}
 	if (!options.apiKey) {
-		deps.out("CLIVLY_API_KEY is not set — cannot register the tunnel URL. Set it and re-run.");
+		deps.out("CLIVLY_SECRET_KEY is not set — cannot register the tunnel URL. Set it and re-run.");
 		return 1;
 	}
 	const app = command ? deps.spawnApp(command) : null;
@@ -279,16 +379,275 @@ async function probeModule(opts) {
 		}
 		for (const [moduleKey, value] of Object.entries(mod)) if (opts.match(value)) return {
 			moduleKey,
-			importPath: toImportPath(candidate, opts.cwd)
+			importPath: toImportPath(candidate, opts.cwd, opts.graph)
 		};
 	}
 	return null;
 }
 //#endregion
+//#region src/workspace-graph.ts
+const WINDOWS_SEP$2 = /\\/g;
+const MODULE_EXT$1 = /\.(ts|tsx|js|jsx|mjs|cjs|cts|mts)$/;
+const BRACE_GROUP = /\{([^{}]*)\}/;
+const MAX_GLOB_DEPTH = 8;
+const IGNORED_DIRS = /* @__PURE__ */ new Set([
+	"node_modules",
+	"dist",
+	"build",
+	"coverage"
+]);
+function isDirectory$1(path) {
+	try {
+		return statSync(path).isDirectory();
+	} catch {
+		return false;
+	}
+}
+const CONVENTIONAL_ENTRIES = [
+	"src/index.ts",
+	"src/index.tsx",
+	"index.ts",
+	"index.tsx",
+	"src/index.js",
+	"index.js"
+];
+function readPackageManifest(dir) {
+	const path = join(dir, "package.json");
+	if (!existsSync(path)) return null;
+	try {
+		return JSON.parse(readFileSync(path, "utf8"));
+	} catch {
+		return null;
+	}
+}
+function parentDir$1(dir) {
+	const parent = dirname(dir);
+	return parent === dir ? null : parent;
+}
+/**
+* The workspace globs declared at `dir`, from either `package.json#workspaces`
+* (npm, yarn, bun) or `pnpm-workspace.yaml` (pnpm). Negations are dropped —
+* they only ever narrow the set, and treating one as a literal path would
+* invent a package directory named `!something`.
+*/
+function readWorkspaceGlobs(dir) {
+	const manifest = readPackageManifest(dir);
+	const declared = Array.isArray(manifest?.workspaces) ? manifest.workspaces : manifest?.workspaces?.packages;
+	if (Array.isArray(declared) && declared.length > 0) return declared.filter((glob) => !glob.startsWith("!"));
+	const pnpmPath = join(dir, "pnpm-workspace.yaml");
+	if (!existsSync(pnpmPath)) return [];
+	try {
+		return readFileSync(pnpmPath, "utf8").split("\n").map((line) => line.trim()).filter((line) => line.startsWith("- ")).map((line) => line.slice(2).trim().replace(/^['"]|['"]$/g, "")).filter((glob) => glob.length > 0 && !glob.startsWith("!"));
+	} catch {
+		return [];
+	}
+}
+/**
+* `{apps,packages}/*` -> [`apps/*`, `packages/*`].
+*
+* Expands one group per pass and recurses, so nested and repeated groups all
+* resolve. A manifest that declares a brace glob is a workspace like any other,
+* and failing to expand it silently yields an empty graph — which downgrades
+* every generated specifier to the relative form this module exists to avoid.
+*/
+function expandBraces(pattern) {
+	const group = BRACE_GROUP.exec(pattern);
+	if (!group) return [pattern];
+	return (group[1] ?? "").split(",").flatMap((option) => expandBraces(pattern.replace(group[0], option.trim())));
+}
+function childDirectories(dir) {
+	try {
+		return readdirSync(dir, { withFileTypes: true }).filter((entry) => entry.isDirectory() && !(IGNORED_DIRS.has(entry.name) || entry.name.startsWith("."))).map((entry) => join(dir, entry.name));
+	} catch {
+		return [];
+	}
+}
+/** `dir` and every directory beneath it, up to `depth` levels down. */
+function withDescendants(dir, depth) {
+	if (depth <= 0) return [dir];
+	return [dir, ...childDirectories(dir).flatMap((child) => withDescendants(child, depth - 1))];
+}
+/** Resolve the remaining glob segments against the directories matched so far. */
+function matchSegments(dirs, segments) {
+	const [segment, ...rest] = segments;
+	if (segment === void 0) return dirs;
+	let next;
+	if (segment === "**") next = dirs.flatMap((dir) => withDescendants(dir, MAX_GLOB_DEPTH));
+	else if (segment === "*") next = dirs.flatMap(childDirectories);
+	else next = dirs.map((dir) => join(dir, segment)).filter(isDirectory$1);
+	return matchSegments(next, rest);
+}
+/**
+* Expand one workspace glob into the package directories it names.
+*
+* Handles exact paths, `*`, `**`, and brace groups — the shapes that actually
+* appear in pnpm/npm/yarn/bun manifests. `node_modules` and dot-directories are
+* never descended into: a dependency's own package.json is not a workspace
+* member, and treating one as such would put a third-party name in the graph.
+*/
+function expandWorkspaceGlob(root, pattern) {
+	return expandBraces(pattern).flatMap((expanded) => matchSegments([root], expanded.split("/").filter((segment) => segment.length > 0))).filter((dir) => existsSync(join(dir, "package.json")));
+}
+/**
+* Walk up from `start` looking for the directory that declares workspace globs.
+* Stops *before* `boundary` (the user's home directory by default) so a stray
+* manifest above the project is never mistaken for a workspace root.
+*/
+function findWorkspaceRoot(start, boundary = homedir()) {
+	const stop = resolve(boundary);
+	let current = resolve(start);
+	while (current !== stop) {
+		if (readWorkspaceGlobs(current).length > 0) return current;
+		const parent = parentDir$1(current);
+		if (!parent) return null;
+		current = parent;
+	}
+	return null;
+}
+/**
+* Build the package graph containing `start`, or null when `start` is not inside
+* a workspace (the single-package case, where relative imports are correct).
+*/
+function loadWorkspaceGraph(start, boundary = homedir()) {
+	const root = findWorkspaceRoot(start, boundary);
+	if (!root) return null;
+	const seen = /* @__PURE__ */ new Set();
+	const packages = [];
+	for (const pattern of readWorkspaceGlobs(root)) for (const dir of expandWorkspaceGlob(root, pattern)) {
+		const absolute = resolve(dir);
+		if (seen.has(absolute)) continue;
+		seen.add(absolute);
+		const name = readPackageManifest(absolute)?.name;
+		if (typeof name === "string" && name.length > 0) packages.push({
+			dir: absolute,
+			name
+		});
+	}
+	return {
+		root,
+		packages
+	};
+}
+/**
+* The workspace package that owns `absPath`.
+*
+* Compares against `dir + sep` so a sibling sharing a name prefix
+* (`packages/database-legacy` vs `packages/database`) can't match, and returns
+* the longest match so a nested package beats its parent.
+*/
+function findPackageContaining(graph, absPath) {
+	if (!graph) return null;
+	const target = resolve(absPath);
+	let best = null;
+	for (const pkg of graph.packages) {
+		const withSep = pkg.dir.endsWith(sep) ? pkg.dir : `${pkg.dir}${sep}`;
+		if ((target === pkg.dir || target.startsWith(withSep)) && (!best || pkg.dir.length > best.dir.length)) best = pkg;
+	}
+	return best;
+}
+/** The first string buried in an `exports` value, following conditions in order. */
+function firstExportString(value) {
+	if (typeof value === "string") return value;
+	if (typeof value !== "object" || value === null || Array.isArray(value)) return null;
+	for (const nested of Object.values(value)) {
+		const found = firstExportString(nested);
+		if (found) return found;
+	}
+	return null;
+}
+function isFile(path) {
+	try {
+		return statSync(path).isFile();
+	} catch {
+		return false;
+	}
+}
+/**
+* The file a bare import of this package resolves to, or null if we can't tell.
+*
+* Null rather than a guess on purpose: an entry declared in the manifest but
+* absent on disk (a `dist/` build that hasn't run) would otherwise make `init`
+* generate an import of a file that does not exist.
+*/
+function resolvePackageEntry(packageDir) {
+	const manifest = readPackageManifest(packageDir);
+	const declared = [
+		firstExportString((manifest?.exports)?.["."]),
+		manifest?.module,
+		manifest?.main
+	].filter((entry) => typeof entry === "string");
+	for (const entry of [...declared, ...CONVENTIONAL_ENTRIES]) {
+		const candidate = resolve(packageDir, entry);
+		if (isFile(candidate)) return candidate;
+	}
+	return null;
+}
+/**
+* Whether `./subpath` is something an importer outside the package may request.
+*
+* A package with no `exports` field uses legacy resolution, where any file is
+* reachable. Once `exports` exists it is an allow-list: Node and TypeScript's
+* `bundler`/`node16` resolution both reject anything it does not name, so
+* emitting such a specifier scaffolds a config that cannot compile.
+*/
+function exportsAllowSubpath(packageDir, subpath) {
+	const exports = readPackageManifest(packageDir)?.exports;
+	if (exports === void 0 || exports === null) return true;
+	if (typeof exports !== "object" || Array.isArray(exports)) return false;
+	const request = `./${subpath}`;
+	return Object.keys(exports).some((key) => {
+		if (!key.startsWith(".")) return false;
+		const star = key.indexOf("*");
+		if (star === -1) return key === request;
+		const prefix = key.slice(0, star);
+		const suffix = key.slice(star + 1);
+		return request.length >= prefix.length + suffix.length && request.startsWith(prefix) && request.endsWith(suffix);
+	});
+}
+/**
+* The specifier that imports `absPath` from outside its package: the bare name
+* when the file is the package entry, `name/subpath` when the package's
+* `exports` permits that subpath, and **null** when it does not.
+*
+* Null is the honest answer rather than a specifier that looks right and fails
+* to resolve. The common shape that hits it is a package exporting only `"."`
+* while the Drizzle instance lives in `src/db.ts` — callers should fall back to
+* a relative import, or ask the developer via `--db-import` / `--auth-import`.
+*/
+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, "");
+	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 MODULE_EXT = /\.(ts|js|mjs|cts|mts)$/;
-function toImportPath(schemaPath, cwd) {
+/**
+* Turn an absolute module path into the specifier the generated config imports
+* it by. Every import `init` emits — schema, db instance, auth instance — is
+* minted here, so this is the one place the monorepo fix has to land.
+*
+* "/app/src/db/schema.ts" (cwd "/app") -> "./src/db/schema"
+*
+* With a workspace `graph`, a file owned by a *different* workspace package
+* becomes a package specifier instead: a schema in `packages/database` imports
+* as `@acme/database`, not `../../packages/database/src/index`. The relative
+* form escapes the app's tsconfig rootDir and sidesteps the package boundary the
+* repo already maintains, which is what made generated configs unusable in
+* shared-package layouts.
+*
+* A file inside the app itself still gets a relative specifier — the app is a
+* workspace package too, and importing it by its own name would be a cycle.
+*/
+function toImportPath(schemaPath, cwd, graph) {
+	const owner = findPackageContaining(graph ?? null, schemaPath);
+	if (owner && resolve(owner.dir) !== resolve(cwd)) {
+		const specifier = toPackageSpecifier(owner, schemaPath);
+		if (specifier) return specifier;
+	}
 	const rel = relative(cwd, schemaPath).replace(WINDOWS_SEP$1, "/").replace(MODULE_EXT, "");
 	return rel.startsWith(".") ? rel : `./${rel}`;
 }
@@ -365,7 +724,7 @@ async function discoverSchema(opts) {
 	const mod = await loadSchemaModule(opts.schemaPath, load);
 	const drizzle = await load("drizzle-orm");
 	const pgCore = await loadPgCoreRuntime(load);
-	const importPath = toImportPath(opts.schemaPath, opts.cwd);
+	const importPath = toImportPath(opts.schemaPath, opts.cwd, opts.graph);
 	const tables = [];
 	let db = null;
 	for (const [moduleKey, value] of Object.entries(mod)) {
@@ -387,6 +746,7 @@ async function discoverSchema(opts) {
 	if (db === null) db = await probeModule({
 		candidates: siblingDbCandidates(opts.schemaPath),
 		cwd: opts.cwd,
+		graph: opts.graph,
 		load,
 		match: isDrizzleDb
 	});
@@ -539,7 +899,7 @@ function isEntrypoint(argv1, moduleUrl, realpath = realpathSync) {
 //#endregion
 //#region src/load-env.ts
 const LINE = /^\s*(?:export\s+)?([A-Za-z_][A-Za-z0-9_]*)\s*=(.*)$/;
-const NEWLINE = /\r?\n/;
+const NEWLINE$1 = /\r?\n/;
 const ESCAPED_NEWLINE = /\\n/g;
 const ESCAPED_CARRIAGE = /\\r/g;
 const TRAILING_COMMENT = /\s#/;
@@ -551,7 +911,7 @@ const TRAILING_COMMENT = /\s#/;
 */
 function parseEnv(content) {
 	const out = {};
-	for (const rawLine of content.split(NEWLINE)) {
+	for (const rawLine of content.split(NEWLINE$1)) {
 		const line = rawLine.trimStart();
 		if (line === "" || line.startsWith("#")) continue;
 		const match = LINE.exec(line);
@@ -576,15 +936,26 @@ function parseValue(raw) {
 /**
 * Load `.env` then `.env.local` from `cwd` into `env` (default `process.env`),
 * WITHOUT overriding anything already set. Precedence, strongest first:
-* real environment (shell) > `.env.local` > `.env`. This mirrors the framework
-* convention developers already expect (Next.js, Vite), so pointing
-* `CLIVLY_API_URL` at a staging host from the shell still wins over the file.
+* real environment (shell) > explicit `options.files` > `.env.local` > `.env`.
+* The conventional part mirrors what developers already expect (Next.js, Vite),
+* so pointing `CLIVLY_API_URL` at a staging host from the shell still wins.
+*
+* Explicit files exist for split workspaces, where the app that holds
+* `clivly.config.ts` is not the package that holds the credentials. Reading
+* them here — in the CLI process — is what keeps that need out of
+* `clivly.config.ts`, which the app imports and which therefore has to survive
+* an edge runtime with no filesystem.
 */
-function loadEnv(cwd, env = process.env) {
+function loadEnv(cwd, env = process.env, options = {}) {
 	const files = [];
 	const merged = {};
-	for (const name of [".env", ".env.local"]) {
-		const path = join(cwd, name);
+	const candidates = [
+		".env",
+		".env.local",
+		...options.files ?? []
+	];
+	for (const name of candidates) {
+		const path = resolve(cwd, name);
 		if (!existsSync(path)) continue;
 		files.push(name);
 		try {
@@ -602,6 +973,15 @@ function loadEnv(cwd, env = process.env) {
 	};
 }
 //#endregion
+//#region src/secret-key-env.ts
+const SECRET_KEY_ENV = "CLIVLY_SECRET_KEY";
+const LEGACY_SECRET_KEY_ENV = "CLIVLY_API_KEY";
+function readSecretKeyEnv(env) {
+	const next = env[SECRET_KEY_ENV];
+	if (next && next.length > 0) return next;
+	return env[LEGACY_SECRET_KEY_ENV];
+}
+//#endregion
 //#region src/login.ts
 const POLL_INTERVAL_MS = 2e3;
 const POLL_BACKOFF_MULTIPLIER = 1.5;
@@ -613,7 +993,7 @@ const MASK_VISIBLE_CHARS = 4;
 const MASK_PREFIX = "••••";
 function maskSecret(value) {
 	if (value.length <= MASK_VISIBLE_CHARS) return MASK_PREFIX;
-	return `${MASK_PREFIX}${value.slice(-MASK_VISIBLE_CHARS)}`;
+	return `${MASK_PREFIX}${value.slice(-4)}`;
 }
 async function createPairingSession(apiUrl, deps, rotate) {
 	const res = await deps.fetchImpl(`${apiUrl}/clivly/cli/pair`, {
@@ -625,7 +1005,7 @@ async function createPairingSession(apiUrl, deps, rotate) {
 		})
 	});
 	if (res.status === 404) {
-		deps.out("clivly login isn't available yet on this server — CLI pairing is not enabled. Ask whoever runs your Clivly backend to enable it, or set CLIVLY_API_KEY / CLIVLY_SYNC_TRIGGER_SECRET manually.");
+		deps.out("clivly login isn't available yet on this server — CLI pairing is not enabled. Ask whoever runs your Clivly backend to enable it, or set CLIVLY_SECRET_KEY / CLIVLY_SYNC_TRIGGER_SECRET manually.");
 		return { exitCode: 1 };
 	}
 	if (!res.ok) {
@@ -698,9 +1078,9 @@ async function confirmWorkspace(deps, credentials) {
 }
 function credentialEntries(credentials) {
 	return [{
-		key: "CLIVLY_API_KEY",
+		key: SECRET_KEY_ENV,
 		value: credentials.apiKey,
-		comment: "Org API key — Settings → API keys"
+		comment: "Org secret key — Settings → API keys"
 	}, {
 		key: "CLIVLY_SYNC_TRIGGER_SECRET",
 		value: credentials.triggerSecret,
@@ -714,7 +1094,7 @@ function writeCredentials(options, credentials) {
 	deps.writeEnv(options.cwd, result.contents);
 	deps.out("\nLogin successful.\n");
 	const valuesByKey = {
-		CLIVLY_API_KEY: credentials.apiKey,
+		[SECRET_KEY_ENV]: credentials.apiKey,
 		CLIVLY_SYNC_TRIGGER_SECRET: credentials.triggerSecret
 	};
 	for (const entry of entries) if (result.skipped.includes(entry.key)) deps.out(`  • ${entry.key} already set — skipped (pass --force to overwrite)`);
@@ -807,32 +1187,42 @@ function buildEntity(table, concept, todos) {
 		idField
 	};
 }
-function placeholderContact(todos) {
-	todos.push("No contact table detected. Filled in a placeholder — set `source`, `fields`, and the fromDrizzle table below, then run `clivly doctor`.");
-	return {
-		moduleKey: "contacts",
-		tableName: "contacts",
-		concept: "contact",
-		fields: {
-			name: "name",
-			email: "email"
-		},
-		cursorField: "updatedAt",
-		idField: null
-	};
-}
 function hasMappedFields(entity) {
 	return Object.keys(entity.fields).length > 0;
 }
-function planInit(schema) {
+/** A table by its SQL name or its schema-module export name — either is what a developer would type. */
+function findTable(tables, name) {
+	return tables.find((table) => table.tableName === name || table.moduleKey === name) ?? null;
+}
+/**
+* Which table serves each concept: an explicit override when given, else the
+* heuristic pick.
+*
+* Split out of `planInit` because resolving two independent overrides, each with
+* its own unknown-name path, is most of the branching — and keeps `planInit`
+* inside the cognitive-complexity budget.
+*/
+function selectTables(tables, overrides, todos) {
+	const heuristic = selectEntities(tables);
+	const pick = (flag, fallback, label) => {
+		if (!flag) return fallback;
+		const found = findTable(tables, flag);
+		if (!found) todos.push(`--${label}-table "${flag}" is not a table in this schema.`);
+		return found;
+	};
+	const contact = pick(overrides.contactTable, heuristic.contact, "contact");
+	const company = pick(overrides.companyTable, heuristic.company, "company");
+	return {
+		contact,
+		company: company?.tableName === contact?.tableName ? null : company
+	};
+}
+function planInit(schema, overrides = {}) {
 	const todos = [];
-	const { contact: contactTable, company: companyTable } = selectEntities(schema.tables);
-	let contact = contactTable ? buildEntity(contactTable, "contact", todos) : placeholderContact(todos);
-	let contactDetected = contactTable !== null;
-	if (!hasMappedFields(contact)) {
-		contact = placeholderContact(todos);
-		contactDetected = false;
-	}
+	const { contact: contactTable, company: companyTable } = selectTables(schema.tables, overrides, todos);
+	const built = contactTable ? buildEntity(contactTable, "contact", todos) : null;
+	const contact = built && hasMappedFields(built) ? built : null;
+	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);
@@ -841,7 +1231,7 @@ function planInit(schema) {
 			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.`);
 	}
-	if (contactTable) {
+	if (contactTable && contact) {
 		const scored = scoreRelationships(toScoredTable(contactTable), schema.tables.map(toScoredTable));
 		const top = scored[0];
 		const runnerUp = scored[1];
@@ -856,16 +1246,16 @@ function planInit(schema) {
 		db: schema.db,
 		contact,
 		company,
-		todos,
-		contactDetected
+		tableNames: schema.tables.map((table) => table.tableName),
+		todos
 	};
 }
 //#endregion
 //#region src/render-config.ts
 const CLIVLY_ENV_KEYS = [
 	{
-		key: "CLIVLY_API_KEY",
-		comment: "Org API key — Settings → API keys"
+		key: "CLIVLY_SECRET_KEY",
+		comment: "Org secret key — Settings → API keys"
 	},
 	{
 		key: "CLIVLY_SYNC_TRIGGER_URL",
@@ -874,10 +1264,6 @@ const CLIVLY_ENV_KEYS = [
 	{
 		key: "CLIVLY_SYNC_TRIGGER_SECRET",
 		comment: "Signing secret — Integrations → Remote sync"
-	},
-	{
-		key: "CLIVLY_VERIFY_TOKEN",
-		comment: "Bearer token Clivly presents to /clivly/auth/verify"
 	}
 ];
 function renderFields(fields) {
@@ -912,10 +1298,9 @@ function renderDbExpr(plan) {
 }
 function renderImports(plan) {
 	const lines = [
-		"import { createClivlySDK } from \"clivly/sdk\";",
+		"import { createClivlySDK, defineClivlyConfig } from \"clivly/sdk\";",
 		"import { fromDrizzle } from \"clivly/drizzle\";",
-		"import { defineClivlyConfig } from \"clivly/core\";",
-		"import { discoverFromDrizzle } from \"clivly/core/drizzle\";",
+		"import { discoverFromDrizzle } from \"clivly/drizzle\";",
 		`import * as schema from "${plan.importPath}";`
 	];
 	if (!plan.db) lines.push(`import { db } from "${fallbackDbImportPath(plan.importPath)}"; // TODO: point at your Drizzle instance`);
@@ -941,7 +1326,7 @@ ${entities.join(",\n")},
 });
 
 export default createClivlySDK({
-  apiKey: process.env.CLIVLY_API_KEY!,
+  apiKey: process.env.CLIVLY_SECRET_KEY ?? process.env.CLIVLY_API_KEY!,
   entities,
   // Every table in your Drizzle schema, so the Clivly dashboard can offer them
   // all when you add a mapping — not just the ones wired up as sources below.
@@ -954,7 +1339,8 @@ ${sources.join(",\n")},
     url: process.env.CLIVLY_SYNC_TRIGGER_URL,
     secret: process.env.CLIVLY_SYNC_TRIGGER_SECRET,
   },
-  verifyToken: process.env.CLIVLY_VERIFY_TOKEN,
+  // verifyToken is optional and only needed once a Clivly Cloud consumer calls
+  // your /clivly/auth/verify endpoint; leave it unset otherwise.
 });
 `;
 }
@@ -1040,23 +1426,28 @@ const TS_EXTENSION = /\.ts$/;
 const ROUTE_PATHS = {
 	nextjs: {
 		tick: "app/api/clivly/tick/route.ts",
-		verify: "app/api/clivly/auth/verify/route.ts"
+		verify: "app/api/clivly/auth/verify/route.ts",
+		session: "app/api/clivly/widget/session/route.ts"
 	},
 	"tanstack-start": {
 		tick: "src/routes/api/clivly/tick.ts",
-		verify: "src/routes/api/clivly/auth/verify.ts"
+		verify: "src/routes/api/clivly/auth/verify.ts",
+		session: "src/routes/api/clivly/widget/session.ts"
 	},
 	sveltekit: {
 		tick: "src/routes/api/clivly/tick/+server.ts",
-		verify: "src/routes/api/clivly/auth/verify/+server.ts"
+		verify: "src/routes/api/clivly/auth/verify/+server.ts",
+		session: "src/routes/api/clivly/widget/session/+server.ts"
 	},
 	remix: {
 		tick: "app/routes/api.clivly.tick.ts",
-		verify: "app/routes/api.clivly.auth.verify.ts"
+		verify: "app/routes/api.clivly.auth.verify.ts",
+		session: "app/routes/api.clivly.widget.session.ts"
 	},
 	nuxt: {
 		tick: "server/api/clivly/tick.ts",
-		verify: "server/api/clivly/auth/verify.ts"
+		verify: "server/api/clivly/auth/verify.ts",
+		session: "server/api/clivly/widget/session.ts"
 	},
 	unknown: null
 };
@@ -1086,14 +1477,27 @@ function renderAuthPreamble(routeFilePath, auth) {
 	lines.push("", auth.body);
 	return lines.join("\n");
 }
-function renderBody(framework, importPath, verify, auth, routeFilePath) {
-	const preamble = verify ? `import clivly from "${importPath}";
+function renderPreamble(kind, importPath, auth, routeFilePath) {
+	if (kind === "session") return `import { createChatSessionHandler } from "clivly/sdk";
+
+const handler = createChatSessionHandler({
+  apiKey: process.env.CLIVLY_SECRET_KEY ?? process.env.CLIVLY_API_KEY ?? "",
+  allowedOrigins: [
+    // TODO: add the origins your widget loads from, e.g. "https://example.com"
+  ],
+});
+`;
+	if (kind === "verify") return `import clivly from "${importPath}";
 ${renderAuthPreamble(routeFilePath, auth)}
 const handler = clivly.createAuthVerifyHandler(resolveUser);
-` : `import clivly from "${importPath}";
+`;
+	return `import clivly from "${importPath}";
 
 const handler = clivly.createClivlyHandler();
 `;
+}
+function renderBody(framework, importPath, kind, auth, routeFilePath) {
+	const preamble = renderPreamble(kind, importPath, auth, routeFilePath);
 	switch (framework) {
 		case "nextjs": return `${preamble}
 export const POST = (request: Request) => handler(request);
@@ -1125,7 +1529,7 @@ export default defineEventHandler((event) => handler(toWebRequest(event)));
 }
 function renderRouteFile(framework, kind, auth = renderAuthWiring("unknown")) {
 	const path = routePath(framework, kind);
-	let body = renderBody(framework, configImport(path), kind === "verify", auth, path);
+	let body = renderBody(framework, configImport(path), kind, auth, path);
 	if (framework === "tanstack-start") {
 		const url = `/${path.replace(TANSTACK_ROUTE_PREFIX, "").replace(TS_EXTENSION, "")}`;
 		body = body.replace("__ROUTE__", url);
@@ -1154,11 +1558,21 @@ function planScaffold(framework) {
 		...COMMON_FILES
 	];
 }
+function planWidgetScaffold(framework) {
+	const paths = ROUTE_PATHS[framework];
+	if (!paths) return [];
+	return [{
+		path: paths.session,
+		description: "Clivly chat-session route (createChatSessionHandler) — add allowedOrigins",
+		owned: true
+	}];
+}
 //#endregion
 //#region src/plan-mutations.ts
-function fileAction(present, force) {
-	if (!present) return "create";
-	return force ? "overwrite" : "skip";
+function fileAction(existing, next, force) {
+	if (existing === null) return "create";
+	if (existing === next) return "unchanged";
+	return force ? "overwrite" : "conflict";
 }
 function hasKey(content, key) {
 	return new RegExp(`^\\s*${key}=`, "m").test(content);
@@ -1170,11 +1584,14 @@ function planFiles(args) {
 		const kind = path.includes("verify") ? "verify" : "tick";
 		return renderRouteFile(args.framework, kind, args.authWiring);
 	};
-	for (const file of planScaffold(args.framework)) mutations.push({
-		path: file.path,
-		contents: render(file.path),
-		action: fileAction(args.exists(join(args.cwd, file.path)), args.force)
-	});
+	for (const file of planScaffold(args.framework)) {
+		const contents = render(file.path);
+		mutations.push({
+			path: file.path,
+			contents,
+			action: fileAction(args.readFile(join(args.cwd, file.path)), contents, args.force)
+		});
+	}
 	return mutations;
 }
 function envAction(addedCount, existingLength) {
@@ -1197,6 +1614,16 @@ function planMutations(args) {
 		env: planEnv(args)
 	};
 }
+function planWidgetMutations(args) {
+	return planWidgetScaffold(args.framework).map((file) => {
+		const contents = renderRouteFile(args.framework, "session");
+		return {
+			path: file.path,
+			contents,
+			action: fileAction(args.readFile(join(args.cwd, file.path)), contents, args.force)
+		};
+	});
+}
 //#endregion
 //#region src/probe-auth.ts
 const AUTH_MODULE_PATHS = [
@@ -1228,59 +1655,6 @@ function probeAuthInstance(cwd, load) {
 	});
 }
 //#endregion
-//#region src/load-config.ts
-const CONFIG_HINT = "Expected clivly.config.ts at your app root exporting `createClivlySDK({...})`.";
-function resolveConfigPath(cwd, configPath) {
-	return resolve(cwd, configPath ?? "clivly.config.ts");
-}
-/**
-* Load the config and return its default export, checking it carries the method
-* the caller needs. The check is by capability rather than by type: the config
-* is the developer's own SDK instance, and a clear "this isn't an SDK instance"
-* beats a TypeError deep inside a command.
-*/
-/**
-* The first meaningful line of an error message. jiti reports a failed
-* resolution with a multi-line "Require stack:" dump naming Clivly's own
-* internal files — noise that tells the developer nothing about their app and
-* buries the one line that does.
-*/
-function firstLine(message) {
-	return message.split("\n")[0]?.trim() ?? "";
-}
-/**
-* Describe why the config failed to load, in one line the developer can act on.
-*
-* A config that fails its own schema validation throws a zod error carrying
-* structured `issues`, but whose `message` is a multi-line JSON dump — its
-* first line is a bare "[", so `firstLine` alone reduced the entire diagnosis
-* to a single bracket. Render the issues as `path: message` instead, which is
-* what actually names the entity to fix. Anything else keeps the require-stack
-* trimming `firstLine` exists for.
-*/
-function describeLoadError(error) {
-	const issues = error.issues;
-	if (Array.isArray(issues) && issues.length > 0) return issues.map((raw) => {
-		const issue = raw;
-		const path = Array.isArray(issue.path) ? issue.path.join(".") : "";
-		const message = typeof issue.message === "string" ? issue.message : "invalid value";
-		return path ? `${path}: ${message}` : message;
-	}).join("; ");
-	return firstLine(error?.message ?? String(error));
-}
-async function loadConfigSdk(path, requiredMethod) {
-	const jiti = createJiti(import.meta.url);
-	let mod;
-	try {
-		mod = await jiti.import(path);
-	} catch (error) {
-		throw new Error(describeLoadError(error));
-	}
-	const sdk = mod.default ?? mod;
-	if (typeof sdk?.[requiredMethod] !== "function") throw new Error("default export is not a Clivly SDK instance");
-	return sdk;
-}
-//#endregion
 //#region src/push-schema.ts
 async function runPushSchema(options) {
 	const out = options.out ?? ((line) => process.stdout.write(line));
@@ -1349,11 +1723,40 @@ function defaultReadDrizzleConfigSchema(cwd) {
 	}
 	return null;
 }
+/**
+* Resolve a `--schema` value that names a workspace package rather than a file.
+*
+* Matches the longest package name that prefixes the specifier, so both
+* `@acme/database` and `@acme/database/src/schema.ts` work. Returns `undefined`
+* when nothing matched (caller falls back to path handling) and `null` when a
+* package matched but its entry could not be resolved — those are different
+* outcomes and the caller reports them differently.
+*/
+function resolveFromWorkspace(specifier, graph, deps) {
+	const pkg = graph.packages.filter((pkg) => specifier === pkg.name || specifier.startsWith(`${pkg.name}/`)).sort((a, b) => b.name.length - a.name.length)[0];
+	if (!pkg) return;
+	if (specifier === pkg.name) return deps.resolveEntry(pkg.dir);
+	const subpath = specifier.slice(pkg.name.length + 1);
+	const candidate = resolve(pkg.dir, subpath);
+	return deps.exists(candidate) ? candidate : deps.resolveEntry(pkg.dir);
+}
 function resolveSchemaPath(opts) {
 	const exists = opts.deps?.exists ?? existsSync;
 	const readSchema = opts.deps?.readDrizzleConfigSchema ?? defaultReadDrizzleConfigSchema;
+	const resolveEntry = opts.deps?.resolvePackageEntry ?? resolvePackageEntry;
 	const toAbs = (p) => isAbsolute(p) ? p : resolve(opts.cwd, p);
-	if (opts.flag) return toAbs(opts.flag);
+	if (opts.flag) {
+		const asPath = toAbs(opts.flag);
+		if (exists(asPath)) return asPath;
+		if (opts.graph) {
+			const fromWorkspace = resolveFromWorkspace(opts.flag, opts.graph, {
+				exists,
+				resolveEntry
+			});
+			if (fromWorkspace !== void 0) return fromWorkspace;
+		}
+		return asPath;
+	}
 	const fromConfig = readSchema(opts.cwd);
 	if (fromConfig) return toAbs(fromConfig);
 	for (const candidate of COMMON_PATHS) {
@@ -1364,17 +1767,8 @@ function resolveSchemaPath(opts) {
 }
 //#endregion
 //#region src/resolve-target-app.ts
-function readPackageJson(dir) {
-	const path = join(dir, "package.json");
-	if (!existsSync(path)) return null;
-	try {
-		return JSON.parse(readFileSync(path, "utf8"));
-	} catch {
-		return null;
-	}
-}
 function packageDeps(dir) {
-	const pkg = readPackageJson(dir);
+	const pkg = readPackageManifest(dir);
 	return {
 		...pkg?.dependencies,
 		...pkg?.devDependencies
@@ -1398,41 +1792,6 @@ function findNearestPackageDir(start, boundary) {
 		current = parent;
 	}
 }
-function readWorkspaceGlobs(dir) {
-	const pkg = readPackageJson(dir);
-	const workspaces = Array.isArray(pkg?.workspaces) ? pkg.workspaces : pkg?.workspaces?.packages;
-	if (Array.isArray(workspaces) && workspaces.length > 0) return workspaces;
-	const pnpmWorkspacePath = join(dir, "pnpm-workspace.yaml");
-	if (!existsSync(pnpmWorkspacePath)) return [];
-	try {
-		return readFileSync(pnpmWorkspacePath, "utf8").split("\n").map((line) => line.trim()).filter((line) => line.startsWith("- ")).map((line) => line.slice(2).trim().replace(/^['"]|['"]$/g, "")).filter((glob) => glob.length > 0 && !glob.startsWith("!"));
-	} catch {
-		return [];
-	}
-}
-function expandWorkspaceGlob(root, pattern) {
-	if (pattern.endsWith("/*")) {
-		const base = join(root, pattern.slice(0, -2));
-		if (!existsSync(base)) return [];
-		try {
-			return readdirSync(base, { withFileTypes: true }).filter((entry) => entry.isDirectory()).map((entry) => join(base, entry.name)).filter((dir) => existsSync(join(dir, "package.json")));
-		} catch {
-			return [];
-		}
-	}
-	const exact = join(root, pattern);
-	return existsSync(join(exact, "package.json")) ? [exact] : [];
-}
-function findWorkspaceRoot(start, boundary) {
-	let current = resolve(start);
-	while (true) {
-		if (current === boundary) return null;
-		if (readWorkspaceGlobs(current).length > 0) return current;
-		const parent = parentDir(current);
-		if (!parent) return null;
-		current = parent;
-	}
-}
 function uniquePaths(paths) {
 	return [...new Set(paths.map((path) => resolve(path)))];
 }
@@ -1488,7 +1847,7 @@ function resolveTargetApp(start, boundary = homedir()) {
 }
 //#endregion
 //#region src/status-ladder.ts
-const SATISFYING = new Set(["pass", "warn"]);
+const SATISFYING = /* @__PURE__ */ new Set(["pass", "warn"]);
 function unmetPrerequisites(stage, satisfied) {
 	return (stage.needs ?? []).filter((id) => !satisfied.has(id));
 }
@@ -1538,10 +1897,118 @@ function ladderExitCode(results) {
 	return results.every((result) => result.state !== "fail" && result.state !== "pending") ? 0 : 1;
 }
 //#endregion
+//#region src/edge-safety.ts
+const NODE_BUILTINS = /* @__PURE__ */ new Set([
+	"assert",
+	"buffer",
+	"child_process",
+	"cluster",
+	"crypto",
+	"dns",
+	"events",
+	"fs",
+	"http",
+	"http2",
+	"https",
+	"module",
+	"net",
+	"os",
+	"path",
+	"perf_hooks",
+	"process",
+	"readline",
+	"stream",
+	"timers",
+	"tls",
+	"url",
+	"util",
+	"v8",
+	"vm",
+	"worker_threads",
+	"zlib"
+]);
+const SIDE_EFFECT_MODULES = [/^dotenv\/config$/, /^dotenv\/lib\/env-options$/];
+const IMPORT_FROM = /(?:^|\s)(?:import|export)\b[^"']*from\s*["']([^"']+)["']/;
+const BARE_IMPORT = /^\s*import\s*["']([^"']+)["']\s*;?\s*$/;
+const REQUIRE_CALL = /\brequire\s*\(\s*["']([^"']+)["']\s*\)/;
+const NEWLINE = /\r?\n/;
+const MODULE_SCOPE_CALL = /^([A-Za-z_$][\w$.]*)\s*\(/;
+const ALLOWED_CALLS = /* @__PURE__ */ new Set([
+	"export",
+	"return",
+	"if",
+	"for",
+	"while"
+]);
+const SIDE_EFFECT_CALLS = /^(dotenv\.config|config|configDotenv|fileURLToPath|readFileSync|require|process\.chdir)$/;
+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.";
+function isNodeBuiltin(specifier) {
+	if (specifier.startsWith("node:")) return true;
+	return NODE_BUILTINS.has(specifier.split("/")[0] ?? "");
+}
+function stripComment(line) {
+	const trimmed = line.trimStart();
+	if (trimmed.startsWith("//") || trimmed.startsWith("*")) return "";
+	return line;
+}
+function specifierIssue(specifier, line) {
+	if (SIDE_EFFECT_MODULES.some((pattern) => pattern.test(specifier))) return {
+		code: "module_scope_side_effect",
+		detail: `imports "${specifier}" for its side effect`,
+		hint: ENV_HINT,
+		line
+	};
+	if (isNodeBuiltin(specifier)) return {
+		code: "node_builtin_in_edge_config",
+		detail: `imports "${specifier}", which does not exist on an edge runtime`,
+		hint: ENV_HINT,
+		line
+	};
+	return null;
+}
+function callIssue(source, line) {
+	const name = MODULE_SCOPE_CALL.exec(source)?.[1];
+	if (!name || ALLOWED_CALLS.has(name) || !SIDE_EFFECT_CALLS.test(name)) return null;
+	return {
+		code: "module_scope_side_effect",
+		detail: `calls ${name}() at module scope`,
+		hint: ENV_HINT,
+		line
+	};
+}
+/**
+* Every reason `source` would fail to import on an edge runtime, in line order.
+* An empty array means the config is safe to import from the app.
+*/
+function analyzeEdgeSafety(source) {
+	const issues = [];
+	source.split(NEWLINE).forEach((rawLine, index) => {
+		const line = stripComment(rawLine);
+		if (line.trim() === "") return;
+		const lineNumber = index + 1;
+		const specifier = BARE_IMPORT.exec(line)?.[1] ?? IMPORT_FROM.exec(line)?.[1] ?? REQUIRE_CALL.exec(line)?.[1];
+		if (specifier) {
+			const issue = specifierIssue(specifier, lineNumber);
+			if (issue) issues.push(issue);
+			return;
+		}
+		const call = callIssue(line, lineNumber);
+		if (call) issues.push(call);
+	});
+	return issues;
+}
+//#endregion
 //#region src/status-stages.ts
+function defaultReadConfigSource(path) {
+	try {
+		return readFileSync(path, "utf8");
+	} catch {
+		return null;
+	}
+}
 const REASON_HINT = {
 	ok: "",
-	invalid_api_key: "The key was rejected (401). Check CLIVLY_API_KEY.",
+	invalid_api_key: "The key was rejected (401). Check CLIVLY_SECRET_KEY (or legacy CLIVLY_API_KEY).",
 	forbidden: "The key is valid but lacks access to this org (403).",
 	rate_limited: "Rate limited (429). Wait a moment and retry.",
 	server_error: "Clivly returned a server error (5xx). Retry shortly.",
@@ -1554,12 +2021,12 @@ const apiKeyStage = {
 	run(ctx) {
 		if (ctx.apiKey) return Promise.resolve({
 			state: "pass",
-			detail: "CLIVLY_API_KEY is set."
+			detail: "Secret key is set."
 		});
 		return Promise.resolve({
 			state: "fail",
-			detail: "CLIVLY_API_KEY is not set.",
-			hint: "Copy your API key from Settings → API keys into .env."
+			detail: "Secret key is not set.",
+			hint: "Copy your secret key from Settings → API keys into CLIVLY_SECRET_KEY in .env."
 		});
 	}
 };
@@ -1600,12 +2067,38 @@ const configStage = {
 		}
 	}
 };
-const LADDER_OWNED_CHECKS = new Set(["API key present", "Heartbeat"]);
+const LADDER_OWNED_CHECKS = /* @__PURE__ */ new Set(["API key present", "Heartbeat"]);
 /** The full ladder, in the order a developer completes setup. */
 const STATUS_STAGES = [
 	apiKeyStage,
 	heartbeatStage,
 	configStage,
+	{
+		id: "runtime",
+		label: "clivly.config is edge-safe",
+		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);
+			if (issues.length === 0) return Promise.resolve({
+				state: "pass",
+				detail: "no Node-only code at module scope"
+			});
+			return Promise.resolve({
+				state: "fail",
+				detail: issues.map((issue) => issue.detail).join("; "),
+				hint: issues[0]?.hint,
+				sub: issues.map((issue) => ({
+					label: `${issue.code} (line ${issue.line})`,
+					ok: false,
+					detail: issue.detail
+				}))
+			});
+		}
+	},
 	{
 		id: "setup-checks",
 		label: "Setup checks",
@@ -1653,7 +2146,11 @@ function defaultLoadSdk(path) {
 const ALIAS_STAGE_IDS = {
 	status: STATUS_STAGES.map((stage) => stage.id),
 	ping: ["api-key", "heartbeat"],
-	doctor: ["config", "setup-checks"],
+	doctor: [
+		"config",
+		"runtime",
+		"setup-checks"
+	],
 	connect: [
 		"api-key",
 		"heartbeat",
@@ -1712,6 +2209,14 @@ function flagValue(argv, flag) {
 	const index = argv.indexOf(flag);
 	return index >= 0 ? argv[index + 1] : void 0;
 }
+function flagValues(argv, flag) {
+	const values = [];
+	for (const [index, entry] of argv.entries()) {
+		const value = entry === flag ? argv[index + 1] : void 0;
+		if (value !== void 0 && !value.startsWith("--")) values.push(value);
+	}
+	return values;
+}
 const KNOWN_COMMANDS = [
 	"init",
 	"status",
@@ -1723,17 +2228,17 @@ const KNOWN_COMMANDS = [
 function editDistance(a, b) {
 	const m = a.length;
 	const n = b.length;
-	const prev = Array.from({ length: n + 1 }, (_, i) => i);
-	const curr = Array.from({ length: n + 1 }, () => 0);
+	let prev = Array.from({ length: n + 1 }, (_, i) => i);
+	let curr = Array.from({ length: n + 1 }, () => 0);
 	for (let i = 1; i <= m; i++) {
 		curr[0] = i;
 		for (let j = 1; j <= n; j++) {
 			const cost = a[i - 1] === b[j - 1] ? 0 : 1;
-			curr[j] = Math.min(prev[j] + 1, curr[j - 1] + 1, prev[j - 1] + cost);
+			curr[j] = Math.min((prev[j] ?? 0) + 1, (curr[j - 1] ?? 0) + 1, (prev[j - 1] ?? 0) + cost);
 		}
-		for (let j = 0; j <= n; j++) prev[j] = curr[j];
+		[prev, curr] = [curr, prev];
 	}
-	return curr[n];
+	return prev[n] ?? 0;
 }
 function nearestCommand(input) {
 	let best;
@@ -1759,6 +2264,59 @@ function readDeps(cwd) {
 		return {};
 	}
 }
+const ADD_USAGE = "Usage: clivly add widget [--force] [--dry-run]";
+const defaultAddDeps = {
+	out: (line) => process.stdout.write(line),
+	readFile: (path) => existsSync(path) ? readFileSync(path, "utf8") : null,
+	writeFile: (path, contents) => {
+		mkdirSync(dirname(path), { recursive: true });
+		writeFileSync(path, contents, "utf8");
+	},
+	readDeps
+};
+function runAdd(argv, cwd, deps = defaultAddDeps) {
+	const target = argv[0];
+	if (target !== "widget") {
+		deps.out(`${target ? `Unknown target "${target}". ` : "Missing target. "}Only \`widget\` is supported.\n${ADD_USAGE}\n`);
+		return 1;
+	}
+	const framework = detectFramework(deps.readDeps(cwd));
+	if (framework === "unknown") {
+		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 force = argv.includes("--force");
+	const dryRun = argv.includes("--dry-run");
+	const files = planWidgetMutations({
+		framework,
+		cwd,
+		force,
+		readFile: (path) => deps.readFile(path)
+	});
+	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) {
+		if (dryRun) {
+			deps.out(`  ${file.action.padEnd(9)} ${file.path}\n`);
+			continue;
+		}
+		if (file.action === "conflict") {
+			deps.out(`  ! ${file.path} differs from what Clivly would write — left alone (--force to overwrite)\n`);
+			continue;
+		}
+		if (file.action === "unchanged") {
+			deps.out(`  unchanged ${file.path} (already up to date)\n`);
+			continue;
+		}
+		deps.writeFile(join(cwd, file.path), file.contents);
+		deps.out(`  ${file.action.padEnd(9)} ${file.path}\n`);
+	}
+	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`);
+	}
+	return 0;
+}
 function readOwnVersion() {
 	const req = createRequire(import.meta.url);
 	for (const rel of ["./package.json", "../package.json"]) try {
@@ -1766,6 +2324,35 @@ function readOwnVersion() {
 		if (pkg.name === "clivly" && pkg.version) return pkg.version;
 	} catch {}
 }
+/**
+* Parse a `--db-import` / `--auth-import` value into a discovery-shaped override.
+*
+*   `@acme/database`          -> importPath "@acme/database", moduleKey <fallback>
+*   `@acme/database#database` -> importPath "@acme/database", moduleKey "database"
+*
+* The optional `#exportName` suffix exists because a specifier alone doesn't say
+* which export holds the instance. Guessing wrong emits an import of a name that
+* isn't there, so the flag lets the developer say it outright while keeping the
+* conventional name as the default.
+*/
+function importOverride(flag, fallbackModuleKey) {
+	const trimmed = flag?.trim();
+	if (!trimmed) return null;
+	const separator = trimmed.lastIndexOf("#");
+	const importPath = separator === -1 ? trimmed : trimmed.slice(0, separator);
+	const moduleKey = separator === -1 ? "" : trimmed.slice(separator + 1);
+	if (importPath.length === 0) return null;
+	return {
+		importPath,
+		moduleKey: moduleKey || fallbackModuleKey
+	};
+}
+function authInstanceFromFlag(flag) {
+	return importOverride(flag, "auth");
+}
+function defaultReadFile(path) {
+	return existsSync(path) ? readFileSync(path, "utf8") : null;
+}
 function defaultReadEnv(cwd) {
 	const path = join(cwd, ".env");
 	return existsSync(path) ? readFileSync(path, "utf8") : "";
@@ -1777,18 +2364,27 @@ function defaultIsInteractive() {
 	return Boolean(process.stdin.isTTY) && Boolean(process.stdout.isTTY) && !process.env.CI;
 }
 function resolveInitDeps(options) {
+	const loadGraph = options.loadWorkspaceGraph ?? loadWorkspaceGraph;
+	const graphCache = /* @__PURE__ */ new Map();
+	const graphFor = (cwd) => {
+		if (!graphCache.has(cwd)) graphCache.set(cwd, loadGraph(cwd));
+		return graphCache.get(cwd) ?? null;
+	};
 	return {
 		out: options.out ?? ((line) => process.stdout.write(line)),
 		readDepsFn: options.readDeps ?? readDeps,
+		graphFor,
 		resolvePath: options.resolveSchemaPath ?? ((cwd) => resolveSchemaPath({
 			cwd,
-			flag: options.schemaFlag
+			flag: options.schemaFlag,
+			graph: graphFor(cwd)
 		})),
 		discover: options.discoverSchema ?? ((schemaPath, cwd) => discoverSchema({
 			schemaPath,
-			cwd
+			cwd,
+			graph: graphFor(cwd)
 		})),
-		configExists: options.configExists ?? existsSync,
+		readFile: options.readFile ?? defaultReadFile,
 		writeConfig: options.writeConfig ?? ((path, contents) => {
 			mkdirSync(dirname(path), { recursive: true });
 			writeFileSync(path, contents, "utf8");
@@ -1799,7 +2395,7 @@ function resolveInitDeps(options) {
 		readEnv: options.readEnv ?? defaultReadEnv,
 		readOwnVersion: options.readOwnVersion ?? readOwnVersion,
 		writeEnv: options.writeEnv ?? defaultWriteEnv,
-		isInteractive: options.isInteractive ?? defaultIsInteractive,
+		isInteractive: options.yes ? () => false : options.isInteractive ?? defaultIsInteractive,
 		login: options.login ?? ((cwd) => runLogin({
 			apiUrl: process.env.CLIVLY_API_URL ?? "https://api.clivly.com",
 			cwd,
@@ -1823,7 +2419,7 @@ async function acquireSchema(options, deps) {
 	const orm = detectOrm(appDeps);
 	const auth = detectAuth(appDeps);
 	deps.framework = framework;
-	deps.authWiring = renderAuthWiring(auth, auth === "better-auth" ? await deps.probeAuth(options.cwd) : null);
+	deps.authWiring = renderAuthWiring(auth, auth === "better-auth" ? authInstanceFromFlag(options.authImportFlag) ?? await deps.probeAuth(options.cwd) : null);
 	out("\nClivly init\n");
 	out(`  Framework: ${FRAMEWORK_LABELS[framework]}\n`);
 	out(`  ORM:       ${orm}\n`);
@@ -1873,14 +2469,18 @@ function mutationsFor(options, deps, plan) {
 		framework: deps.framework,
 		authWiring: deps.authWiring,
 		plan,
-		exists: deps.configExists,
+		readFile: deps.readFile,
 		readEnv: deps.readEnv
 	});
 }
 function applyMutations(options, deps, mutations) {
 	for (const file of mutations.files) {
-		if (file.action === "skip") {
-			deps.out(`  • ${file.path} exists — skipped (pass --force to overwrite)\n`);
+		if (file.action === "unchanged") {
+			deps.out(`  · ${file.path} already up to date\n`);
+			continue;
+		}
+		if (file.action === "conflict") {
+			deps.out(`  ! ${file.path} differs from what init would write — left alone (--diff to see, --force to overwrite)\n`);
 			continue;
 		}
 		deps.writeConfig(join(options.cwd, file.path), file.contents);
@@ -1893,29 +2493,42 @@ function applyMutations(options, deps, mutations) {
 	deps.writeEnv(options.cwd, mutations.env.contents);
 	deps.out("  ✓ .env placeholders\n");
 }
-function previewMutations(deps, mutations) {
+const DIFF_CONTEXT_LIMIT = 40;
+function renderDiff(existing, next) {
+	const before = existing.split("\n");
+	const after = next.split("\n");
+	const lines = [];
+	for (const line of before.filter((l) => !after.includes(l))) lines.push(`      - ${line}`);
+	for (const line of after.filter((l) => !before.includes(l))) lines.push(`      + ${line}`);
+	return lines.length > DIFF_CONTEXT_LIMIT ? [...lines.slice(0, DIFF_CONTEXT_LIMIT), `      … ${lines.length - DIFF_CONTEXT_LIMIT} more lines`] : lines;
+}
+function previewMutations(deps, mutations, options) {
 	const { out } = deps;
 	out("\nDry run — nothing was written.\n\n");
 	for (const file of mutations.files) {
-		const verb = {
-			create: "create",
-			overwrite: "overwrite",
-			skip: "skip"
-		}[file.action];
 		const lines = file.contents.split("\n").length;
-		const suffix = file.action === "skip" ? " (exists — pass --force to overwrite)" : ` (${lines} lines)`;
-		out(`  ${verb.padEnd(9)} ${file.path}${suffix}\n`);
+		const suffix = {
+			conflict: " (differs — --diff to see, --force to overwrite)",
+			create: ` (${lines} lines)`,
+			overwrite: ` (${lines} lines)`,
+			unchanged: " (already up to date)"
+		}[file.action];
+		out(`  ${file.action.padEnd(9)} ${file.path}${suffix}\n`);
+		if (options.diff && file.action === "conflict") {
+			const existing = deps.readFile(join(options.cwd, file.path)) ?? "";
+			for (const line of renderDiff(existing, file.contents)) out(`${line}\n`);
+		}
 	}
 	if (mutations.env.addedKeys.length === 0) out("  skip      .env (every CLIVLY_* key already present)\n");
 	else {
 		out(`  ${mutations.env.action.padEnd(9)} .env\n`);
 		for (const key of mutations.env.addedKeys) out(`              + ${key}=\n`);
 	}
-	out("\nRe-run without --dry-run to apply.\n");
+	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) {
 	out("\nNext steps:\n");
-	out(loginRan ? "  1. Credentials written by `clivly login`\n" : "  1. Add CLIVLY_API_KEY to .env — create one in the Clivly dashboard\n     under Integrations → Create API Key (or Settings → API keys)\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("  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;
@@ -1923,7 +2536,7 @@ function printNextSteps(out, authComplete, loginRan) {
 	out(`  ${step}. Run \`clivly status\` to see where you are\n`);
 }
 function credentialsMissing(envContents) {
-	return !isKeySet(envContents, "CLIVLY_API_KEY");
+	return !(isKeySet(envContents, "CLIVLY_SECRET_KEY") || isKeySet(envContents, "CLIVLY_API_KEY"));
 }
 function pairingSkipReason(options, deps) {
 	if (options.noLogin) return "--no-login";
@@ -1941,9 +2554,12 @@ 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);
-	if (options.dryRun) {
+	if (options.dryRun || options.diff) {
 		out(`\nWould install (${pm}): ${packages.join(", ")}\n`);
-		previewMutations(deps, mutations);
+		previewMutations(deps, mutations, {
+			cwd: options.cwd,
+			diff: options.diff
+		});
 		return 0;
 	}
 	const result = await deps.install({
@@ -1959,11 +2575,11 @@ async function scaffold(options, deps, plan) {
 		const skipReason = pairingSkipReason(options, deps);
 		if (skipReason) {
 			out(`\nSkipped browser pairing (${skipReason}).\n`);
-			out("  Run `clivly login` from a terminal to write CLIVLY_API_KEY and CLIVLY_SYNC_TRIGGER_SECRET.\n");
+			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);
-	return plan.contactDetected ? 0 : 1;
+	return 0;
 }
 function normalizeAppRoot(options) {
 	const resolution = (options.resolveTargetApp ?? resolveTargetApp)(options.cwd);
@@ -1993,9 +2609,45 @@ async function runInit(options) {
 	const deps = resolveInitDeps(resolvedOptions);
 	const acquired = await acquireSchema(resolvedOptions, deps);
 	if ("code" in acquired) return acquired.code;
-	const plan = planInit(acquired);
-	printPlan(deps.out, plan);
-	return scaffold(resolvedOptions, deps, plan);
+	const dbOverride = importOverride(resolvedOptions.dbImportFlag, "db");
+	const plan = planInit(dbOverride ? {
+		...acquired,
+		db: dbOverride
+	} : acquired, {
+		contactTable: resolvedOptions.contactTableFlag,
+		companyTable: resolvedOptions.companyTableFlag
+	});
+	const { contact } = plan;
+	if (!contact) {
+		printNoContactGuidance(deps.out, plan, resolvedOptions);
+		return resolvedOptions.dryRun ? 0 : 1;
+	}
+	const renderable = {
+		...plan,
+		contact
+	};
+	printPlan(deps.out, renderable);
+	return scaffold(resolvedOptions, deps, renderable);
+}
+/**
+* What to do when no contact entity could be mapped. Lists the tables actually
+* discovered and the flag that picks one, so the next command succeeds rather
+* than leaving the developer to guess.
+*/
+function printNoContactGuidance(out, plan, options) {
+	out("No usable contact entity\n\n");
+	for (const todo of plan.todos) out(`  • ${todo}\n`);
+	if (plan.tableNames.length === 0) {
+		out(`\n  No tables were found in ${plan.importPath}.\n`);
+		out("  Check that --schema points at a module exporting Drizzle tables.\n\n");
+		return;
+	}
+	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`);
+	out("  Nothing was written — Clivly needs one entity before a config can load.\n\n");
 }
 function hasCloudflaredOnPath() {
 	const pathEnv = process.env.PATH ?? "";
@@ -2155,16 +2807,30 @@ function runInitFromArgv(argv, cwd) {
 		cwd,
 		force: argv.includes("--force"),
 		dryRun: argv.includes("--dry-run"),
+		diff: argv.includes("--diff"),
+		yes: argv.includes("--yes"),
 		noLogin: argv.includes("--no-login"),
 		openBrowser: !argv.includes("--no-browser"),
-		schemaFlag: flagValue(argv, "--schema")
+		schemaFlag: flagValue(argv, "--schema"),
+		dbImportFlag: flagValue(argv, "--db-import"),
+		authImportFlag: flagValue(argv, "--auth-import"),
+		contactTableFlag: flagValue(argv, "--contact-table"),
+		companyTableFlag: flagValue(argv, "--company-table")
 	});
 }
 async function main(argv) {
 	const [command, ...rest] = argv;
-	loadEnv(process.cwd());
+	let cliEnvFiles = [];
+	try {
+		cliEnvFiles = (await loadCliConfig(process.cwd()))?.envFiles ?? [];
+	} catch (error) {
+		process.stderr.write(`${error.message}\n`);
+		return 1;
+	}
+	loadEnv(process.cwd(), process.env, { files: [...cliEnvFiles, ...flagValues(rest, "--env-file")] });
 	switch (command) {
 		case "init": return await runInitFromArgv(rest, process.cwd());
+		case "add": return runAdd(rest, process.cwd());
 		case "push-schema": return await runPushSchema({
 			cwd: process.cwd(),
 			configPath: flagValue(rest, "--config")
@@ -2174,14 +2840,14 @@ async function main(argv) {
 		case "doctor":
 		case "connect": return await runStatus({
 			cwd: process.cwd(),
-			apiKey: process.env.CLIVLY_API_KEY,
+			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 = process.env.CLIVLY_API_KEY;
+			const apiKey = readSecretKeyEnv(process.env);
 			const apiUrl = flagValue(rest, "--api-url") ?? process.env.CLIVLY_API_URL ?? "https://api.clivly.com";
 			return await runDev({
 				cwd: process.cwd(),
@@ -2209,7 +2875,7 @@ async function main(argv) {
 		case void 0:
 		case "help":
 		case "--help":
-			process.stdout.write("clivly — embed a CRM in your app\n\nUsage:\n  clivly init [--force] [--dry-run] [--schema <path>] [--no-login] [--no-browser]   Scaffold Clivly (config, routes, .env) for your app\n  clivly status [--verbose] [--config <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_API_KEY / CLIVLY_SYNC_TRIGGER_SECRET to .env\n  clivly --version                Print the installed clivly version\n");
+			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");
 			return 0;
 		default: {
 			process.stdout.write(`Unknown command: ${command}\n`);
@@ -2224,4 +2890,4 @@ if (isEntrypoint(process.argv[1], import.meta.url)) main(process.argv.slice(2)).
 	process.exitCode = code;
 });
 //#endregion
-export { main, nearestCommand, runInit, runInitFromArgv };
+export { credentialsMissing, main, nearestCommand, runAdd, runInit, runInitFromArgv };