clivly 0.8.0 → 0.9.1

package/README.md

@@ -1,91 +1,158 @@
 # clivly
 
-Configure and integrate [Clivly](https://clivly.com) — the CRM that lives inside
-your app.
+The consolidated public package for [Clivly](https://clivly.com) — the CRM that
+lives inside your app. It is two things in one install:
 
-For the full integration path, including when to use `start()` versus
-`runScheduled()` / `createClivlyHandler()`, see the
-[connecting to Clivly Cloud guide](https://github.com/amani-joseph/clivly.com/blob/master/docs/guides/connecting-to-clivly-cloud.md).
+- **A CLI** (`npx clivly …`) that scaffolds your integration, pairs your machine
+  with a workspace, and diagnoses the setup.
+- **A runtime**, imported from typed subpaths (`clivly/sdk`, `clivly/drizzle`,
+  `clivly/vite`, `clivly/auth/*`).
 
-## Usage
+> **The canonical end-to-end integration guide is
+> [Connecting to Clivly Cloud](https://github.com/amani-joseph/clivly.com/blob/master/docs/guides/connecting-to-clivly-cloud.md).**
+> This README is the command-level reference.
+
+## Prerequisites
+
+| Requirement | Version / note |
+| --- | --- |
+| Node.js | **≥ 22** |
+| An existing app | The CLI scaffolds into a project you already have |
+| Drizzle ORM | Required for `clivly init` to generate a config. Prisma/Kysely/raw-SQL projects hand-write a `fetchPage` source instead |
+| `cloudflared` on `PATH` | Only for `clivly dev` |
+
+## Installation
 
 ```bash
 npm install clivly
+```
+
+Published on npm's `latest` tag. Once installed, `npx clivly …` uses your local
+copy rather than re-fetching. Use `@next` only when deliberately testing a
+prerelease cut.
 
-npx clivly init          # scaffold config, routes and .env, then pair this machine
-npx clivly login         # pair this machine and write your credentials to .env
-npx clivly status        # check your setup, step by step
-npx clivly dev           # tunnel localhost so remote sync can reach you
-npx clivly push-schema   # report your schema to Clivly without deploying
+## Five-minute quick start
+
+```bash
+npm install clivly
+npx clivly init      # scaffold config + routes + .env, then pair this machine
+npx clivly status    # check every setup step until they all pass
 ```
 
-`ping` and `doctor` remain as aliases that run subsets of the `status` ladder.
+`clivly init` writes exactly three files (plus `.env` keys) — a
+`clivly.config.ts` you own, and two route files Clivly owns. It creates no
+database tables and does not modify your ORM schema.
 
-Clivly's stable packages publish on npm's `latest` tag. Once installed, the
-`npx clivly …` commands above use your local copy. Use `@next` only when you
-are intentionally testing a prerelease cut.
+---
 
-## Imports
+## Commands
 
-`clivly` is the consolidated public package. The CLI remains available as
-`npx clivly`, while application code imports from typed subpaths:
+| Command | What it does |
+| --- | --- |
+| [`clivly init`](#clivly-init) | Scaffold config, routes and env placeholders for your app |
+| [`clivly login`](#clivly-login) | Pair this machine and write credentials to your env file |
+| [`clivly status`](#clivly-status) | Check your setup, step by step. Read-only |
+| [`clivly add widget`](#clivly-add-widget) | Scaffold the chat-session route |
+| [`clivly push-schema`](#clivly-push-schema) | Report your schema to Clivly without deploying |
+| [`clivly dev`](#clivly-dev) | Tunnel localhost so remote sync can reach you |
+| `clivly --version` | Print the installed `clivly` version |
+| [`clivly ping` / `connect` / `doctor`](#deprecated-aliases) | Deprecated aliases running parts of `status` |
 
-```ts
-import { createClivlySDK, defineClivlyConfig } from "clivly/sdk";
-import { fromDrizzle } from "clivly/drizzle";
-import { clivlyVite } from "clivly/vite";
-import { createClerkAuthAdapter } from "clivly/auth/clerk";
-import { createWorkOSAuthAdapter } from "clivly/auth/workos";
-import { createBetterAuthAdapter } from "clivly/auth/better-auth";
+Every command accepts `--help` (or `-h`), which **describes without acting**.
+
+---
+
+### `clivly init`
+
+```bash
+npx 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>]
 ```
 
-Provider and framework integrations use optional peer dependencies.
-**Supported auth providers: Clerk, WorkOS, and BetterAuth.** Install only
-what your app actually uses, such as `drizzle-orm`, `vite`, `@clerk/backend`,
-`@workos-inc/node`, or `better-auth`.
+Detects your framework, ORM, auth adapter and app layout, then scaffolds:
+
+| File | Owned by Clivly |
+| --- | --- |
+| `clivly.config.ts` | No — yours to edit |
+| The tick route for your framework | Yes — `--force` to overwrite |
+| The auth-verify route for your framework | Yes — `--force` to overwrite |
+
+Plus `CLIVLY_SECRET_KEY`, `CLIVLY_SYNC_TRIGGER_URL` and
+`CLIVLY_SYNC_TRIGGER_SECRET` placeholders in your env file.
+
+| Flag | Purpose |
+| --- | --- |
+| `--dry-run` | Show what would be written; write nothing |
+| `--diff` | Show a diff for files that already exist |
+| `--force` | Overwrite the files Clivly owns |
+| `--yes` | Skip prompts |
+| `--no-login` | Skip browser pairing |
+| `--no-browser` | Pair, but print the URL instead of opening it |
+| `--schema <path\|package>` | Where your Drizzle tables live |
+| `--db-import <specifier>` | Where the Drizzle instance lives, when it is not beside the schema. Accepts `@acme/database#database` to name the export |
+| `--auth-import <specifier>` | Where your better-auth instance lives. Same `#exportName` form. Overrides on-disk probing, which cannot see across a package boundary |
+| `--contact-table <name>` | Use this table as the contact entity, skipping the naming heuristics |
+| `--company-table <name>` | Same for companies |
+
+`--contact-table` and `--company-table` accept either the SQL table name or the
+name it is exported under in your schema module — whichever you have in front of
+you.
+
+When `init` finishes and `CLIVLY_SECRET_KEY` is still empty, it hands you
+straight into `clivly login` so you don't end up staring at a blank env file.
+That step is interactive, so it is skipped automatically when there is no TTY or
+when `CI` is set.
+
+#### Framework support
+
+Route scaffolding exists for these five. Anywhere else, mount the handler
+yourself — it is a plain `(Request) => Promise<Response>`.
+
+| Framework | Tick route written |
+| --- | --- |
+| Next.js | `app/api/clivly/tick/route.ts` (or `src/app/…`) |
+| TanStack Start | `src/routes/api/clivly/tick.ts` |
+| SvelteKit | `src/routes/api/clivly/tick/+server.ts` |
+| Remix | `app/routes/api.clivly.tick.ts` |
+| Nuxt | `server/api/clivly/tick.ts` |
+
+Plain Vue apps can still integrate Clivly, but they need a manual server layer
+for the tick route unless they are on Nuxt.
+
+#### ORM support
 
-`clivly init` detects your framework from `package.json`, locates your Drizzle
-schema, and generates a `clivly.config.ts` that maps likely contact and company
-tables. The init command currently generates config for Drizzle only; Prisma and
-Kysely projects should use a hand-written `fetchPage` source for now.
+`init` generates a config for **Drizzle only**. Prisma and Kysely projects
+integrate through a hand-written `fetchPage` source — see the
+[Non-Drizzle sources](https://github.com/amani-joseph/clivly.com/blob/master/docs/guides/connecting-to-clivly-cloud.md#non-drizzle-sources)
+section of the guide.
 
 Use `--schema` when your Drizzle schema is not in a common location or in
-`drizzle.config.ts`. Re-run with `--force` to overwrite an existing config.
+`drizzle.config.ts`.
 
-### Monorepos
+#### Monorepos
 
 In a workspace, `init` reads your `pnpm-workspace.yaml` (or `workspaces` array)
-and imports anything owned by a *sibling* package by **package name** rather than
-by a relative path that climbs out of your app:
+and imports anything owned by a *sibling* package by **package name** rather
+than by a relative path that climbs out of your app:
 
 ```ts
 import * as schema from "@acme/database"; // not "../../packages/database/src/index"
 ```
 
-`--schema` accepts a package specifier as well as a path, so all of these work:
+`--schema` accepts a package specifier as well as a path:
 
 ```bash
-clivly init --schema @acme/database                  # the package entry
-clivly init --schema @acme/database/src/schema.ts    # a subpath inside it
-clivly init --schema ./src/db/schema.ts              # a plain path (unchanged)
+npx clivly init --schema @acme/database                  # the package entry
+npx clivly init --schema @acme/database/src/schema.ts    # a subpath inside it
+npx clivly init --schema ./src/db/schema.ts              # a plain path
 ```
 
 A real file always wins over a same-named package, so existing relative paths
 keep their meaning.
 
-| Flag | Purpose |
-| --- | --- |
-| `--schema <path\|package>` | Where your Drizzle tables live. |
-| `--db-import <specifier>` | Where the Drizzle instance lives, when it isn't beside the schema. Accepts `@acme/database#database` to name the export. |
-| `--auth-import <specifier>` | Where your better-auth instance lives. Same `#exportName` form. Overrides on-disk probing, which cannot see across a package boundary. |
-| `--contact-table <name>` | Use this table as the contact entity, skipping the naming heuristics. |
-| `--company-table <name>` | Same for companies. |
-
-`--contact-table` and `--company-table` accept either the SQL table name or the
-name it is exported under in your schema module — whichever you have in front of
-you.
-
-### When no contact entity can be found
+#### When no contact entity can be found
 
 `init` **writes nothing** rather than scaffolding a config that cannot compile.
 Clivly needs one entity before a config will load, and it will not invent one:
@@ -103,73 +170,67 @@ No usable contact entity
   Nothing was written — Clivly needs one entity before a config can load.
 ```
 
-First-class route scaffolding currently exists for:
+---
 
-- Next.js
-- TanStack Start
-- SvelteKit
-- Remix
-- Nuxt
-
-Vue.js apps can still integrate Clivly, but they usually need a manual server
-layer for the tick route unless they are using Nuxt.
-
-When `init` finishes and `CLIVLY_SECRET_KEY` is still empty, it hands you straight
-into `clivly login` so you don't end up staring at a blank `.env`. That step is
-interactive, so it is skipped automatically when there is no TTY or when `CI` is
-set — and you can always turn it off yourself:
-
-```bash
-npx clivly init --no-login     # scaffold only; pair later with `clivly login`
-npx clivly init --no-browser   # pair, but print the URL instead of opening it
-```
-
-## `clivly login`
+### `clivly login`
 
 ```bash
 npx clivly login [--force] [--rotate] [--api-url <url>] [--no-browser]
 ```
 
 Pairs this machine with a Clivly workspace and writes `CLIVLY_SECRET_KEY` and
-`CLIVLY_SYNC_TRIGGER_SECRET` into your project's `.env`. It creates a pairing
+`CLIVLY_SYNC_TRIGGER_SECRET` into your project's env file. It creates a pairing
 session, prints (and by default opens) an approval link, and waits while you
 approve it in a signed-in browser. The approval link is always printed, so an
 SSH or headless session can be approved by opening the link elsewhere.
 
-- `--no-browser` — print the approval URL without opening a browser.
-- `--force` — overwrite `.env` values that already have a real value. Without
-  it, existing values are kept and reported as skipped; an empty placeholder
-  (`CLIVLY_SECRET_KEY=`) is always filled in.
-- `--rotate` — rotate the workspace's remote-sync trigger secret instead of
-  revealing the current one. Your already-deployed host app will stop receiving
-  sync triggers until you redeploy it with the new secret.
+| Flag | Effect |
+| --- | --- |
+| `--no-browser` | Print the approval URL without opening a browser |
+| `--force` | Overwrite env values that already have a real value. Without it, existing values are kept and reported as skipped; an empty placeholder (`CLIVLY_SECRET_KEY=`) is always filled in |
+| `--rotate` | Rotate the workspace's remote-sync trigger secret instead of revealing the current one. **Your already-deployed app stops receiving sync triggers until you redeploy it with the new secret** |
+| `--api-url <url>` | Point at a non-default backend |
 
 Before anything is written, the CLI prints which workspace approved the pairing
 and asks you to confirm. Declining writes nothing and exits non-zero. In a
-non-interactive run (no TTY, or `CI` set) the workspace is still printed but
-you are not prompted, so scripted pairing cannot hang.
+non-interactive run (no TTY, or `CI` set) the workspace is still printed but you
+are not prompted, so scripted pairing cannot hang.
 
-The pairing endpoints are feature-flagged server-side
-(`CLIVLY_CLI_PAIRING_ENABLED`); if the backend you point at has not enabled
-them, `clivly login` says so and exits non-zero.
+#### Which env file gets written
+
+The CLI follows your framework's convention. This is not cosmetic on Workers:
+wrangler reads `.dev.vars` and nothing else, so credentials written to `.env`
+would never load.
 
-**Clivly Cloud has pairing enabled**, so `clivly login` is the normal path there.
-The flag defaults to `false`, so a self-hosted backend must opt in.
+| Framework | Env file |
+| --- | --- |
+| Next.js | `.env.local` |
+| TanStack Start, SvelteKit, Remix, Nuxt | `.env` |
+| Hono on Cloudflare Workers | `.dev.vars` |
+| Anything else | `.env` |
 
-### Manual credential path
+#### Pairing availability
 
-If pairing is unavailable — a self-hosted backend with the flag off, or a
-restricted environment — every credential can be set by hand. Nothing about the
-CLI requires pairing.
+The pairing endpoints are feature-flagged server-side
+(`CLIVLY_CLI_PAIRING_ENABLED`). **Clivly Cloud has pairing enabled**, so
+`clivly login` is the normal path there. The flag defaults to `false`, so a
+self-hosted backend must opt in — otherwise `clivly login` says so and exits
+non-zero.
+
+#### Manual credential path
+
+If pairing is unavailable, every credential can be set by hand. Nothing about
+the CLI requires pairing.
 
 | Value | Where to get it | Notes |
 | --- | --- | --- |
-| `CLIVLY_SECRET_KEY` | Dashboard → **Settings → API keys** → Create | **Shown once.** Copy it immediately; you cannot retrieve it later, only regenerate. Regenerating **revokes the previous key**, so redeploy after rotating. The legacy name `CLIVLY_API_KEY` is still accepted as a fallback. |
-| `CLIVLY_SYNC_TRIGGER_SECRET` | Dashboard → **Integrations → Remote sync** | Must match the value in your app's env exactly. A mismatch surfaces as a `401` on the signed trigger. |
-| `CLIVLY_SYNC_TRIGGER_URL` | Your own deployment | The public URL of your mounted tick route, e.g. `https://app.example.com/api/clivly/tick`. Optional until you deploy — push-only setups can leave it unset. |
+| `CLIVLY_SECRET_KEY` | Dashboard → **Connect app**, or **Settings → API keys** | **Shown once.** Copy it immediately; you cannot retrieve it later, only regenerate. Regenerating **revokes the previous key**, so redeploy after rotating. The legacy name `CLIVLY_API_KEY` is still accepted as a fallback |
+| `CLIVLY_SYNC_TRIGGER_SECRET` | Dashboard → **Integrations → Remote sync** | Must match the value in your app's env exactly. A mismatch surfaces as a `401` on the signed trigger |
+| `CLIVLY_SYNC_TRIGGER_URL` | Your own deployment | The public URL of your mounted tick route, e.g. `https://app.example.com/api/clivly/tick`. Optional until you deploy — push-only setups can leave it unset |
+| `CLIVLY_PUBLISHABLE_KEY` | Same place as the secret key | Only needed for the chat widget. Safe to expose in client code |
 
-Write them into the `.env` of the package that imports `clivly`, then re-run
-`clivly status` to confirm each rung goes green.
+Write them into the env file of the package that imports `clivly`, then re-run
+`clivly status` to confirm each step goes green.
 
 > **Running your own Clivly backend?** `CLIVLY_TRIGGER_SECRET_WRAPPING_KEY` (a
 > 32-byte hex key) is a **hard production prerequisite** for pairing. The
@@ -177,17 +238,71 @@ Write them into the `.env` of the package that imports `clivly`, then re-run
 > server, `clivly login` fails with a 500 at the moment it would hand over
 > credentials. Set it before enabling `CLIVLY_CLI_PAIRING_ENABLED`.
 
-## `clivly status`
+---
+
+### `clivly status`
 
 ```bash
-npx clivly status [--verbose] [--config <path>]
+npx clivly status [--verbose] [--config <path>] [--env-file <path>]
 ```
 
-Walks your setup one rung at a time — credentials, config, schema, sources,
-connectivity — and stops at the first thing that isn't ready, telling you what
-to do about it. This is the command to reach for when something isn't working.
+Walks your setup one step at a time and stops at the first thing that isn't
+ready, telling you what to do about it. **This is the command to reach for when
+something isn't working.** It is read-only and writes nothing.
 
-## `clivly dev`
+The ladder: credential → Clivly reachable → `clivly.config` loads →
+`clivly.config` is edge-safe → setup checks → sync trigger URL.
+
+| Flag | Effect |
+| --- | --- |
+| `--verbose` | Show every check, including those that passed |
+| `--config <path>` | Path to `clivly.config.ts` (needed in a monorepo) |
+| `--env-file <path>` | Extra env file to load. Repeatable; later files win |
+
+```bash
+npx clivly status --config ./apps/web/clivly.config.ts
+npx clivly status --env-file ../server/.env
+```
+
+Env precedence, strongest first: **real environment → `--env-file` / the
+`envFiles` array in `clivly.cli.ts` → `.env.local` → `.env`**.
+
+---
+
+### `clivly add widget`
+
+```bash
+npx clivly add widget [--force] [--dry-run]
+```
+
+Writes the route that mints chat-widget sessions, for your detected framework
+(e.g. `app/api/clivly/widget/session/route.ts` on Next.js). Idempotent.
+
+It creates **no widget record** — that lives in the Clivly dashboard under
+**Settings → Chat widget**. See
+[Adding the chat widget](https://github.com/amani-joseph/clivly.com/blob/master/docs/guides/adding-the-chat-widget.md)
+for the full flow.
+
+| Flag | Effect |
+| --- | --- |
+| `--dry-run` | Show what would be written; write nothing |
+| `--force` | Overwrite the route if it already exists |
+
+---
+
+### `clivly push-schema`
+
+```bash
+npx clivly push-schema [--config <path>]
+```
+
+Sends your discovered tables and columns to Clivly so the dashboard can offer
+them for mapping — without deploying your app. Reads your config; writes nothing
+locally. **Table and column names only; never row data.**
+
+---
+
+### `clivly dev`
 
 ```bash
 npx clivly dev [--port <n>] [--api-url <url>] [--route-path <path>] [-- <cmd>]
@@ -196,50 +311,131 @@ npx clivly dev [--port <n>] [--api-url <url>] [--route-path <path>] [-- <cmd>]
 Opens a `cloudflared` tunnel to your local app and registers it with Clivly for
 the length of the session, so remote sync can reach `localhost` while you
 develop. Your dev server is detected from `package.json` scripts, or pass it
-explicitly after `--`. Needs `cloudflared` on `PATH` and `CLIVLY_SECRET_KEY` set.
-The override is cleared when the process exits; remote sync is otherwise
+explicitly after `--`. Needs `cloudflared` on `PATH` and `CLIVLY_SECRET_KEY`
+set. The override is cleared when the process exits; remote sync is otherwise
 deploy-only.
 
-## `clivly ping` / `clivly doctor`
+```bash
+npx clivly dev --port 3000 -- npm run dev
+```
+
+It also watches `clivly.config.ts` and tells you when it changes. It cannot
+reload it for you — the config belongs to your app's process, not to the CLI.
+
+If registration fails, the warning names the cause: an invalid key, a backend
+without the endpoint enabled, an HTTP status Clivly returned, or a genuine
+network failure. Your app keeps running either way, and outbound sync (your app
+→ Clivly) is unaffected — only dashboard-triggered sync needs the tunnel.
+
+| Flag | Effect |
+| --- | --- |
+| `--port <n>` | Local port your app listens on |
+| `--route-path <path>` | Path to your mounted tick route |
+| `--api-url <url>` | Point at a non-default backend |
+
+---
+
+### Deprecated aliases
+
+`ping`, `connect` and `doctor` each run part of the `status` ladder. They still
+work, and are kept because output and docs have recommended them — but prefer
+`clivly status`, which runs the whole ladder and tells you which step you are on.
+
+| Alias | Equivalent scope |
+| --- | --- |
+| `clivly ping` | Credential + reachability |
+| `clivly connect` | The above, plus config and trigger URL |
+| `clivly doctor` | Config, setup checks and edge safety |
 
-`clivly ping` reads `CLIVLY_SECRET_KEY` from the environment, sends one heartbeat, and prints a clear ✅/❌ with the resolved org or the failure reason — so you can confirm a connection from the terminal without writing any code. Point it at a non-default backend with `--api-url <url>` (or `CLIVLY_API_URL`).
+Each prints a deprecation notice, then the steps it covers, renumbered to its own
+scope:
 
 ```bash
-CLIVLY_SECRET_KEY=sk_live_… npx clivly ping
-#
-# Clivly ping
-#   ✅ Connected to Clivly
-#      Org: Acme (org_1)
+$ npx clivly ping
+`clivly ping` is a deprecated alias that runs part of `clivly status`. Prefer `clivly status`.
+
+Clivly status
+  ✅ Step 1 of 2 · API key present — Secret key is set.
+  ✅ Step 2 of 2 · Clivly reachable — Reached org: acme (org_1)
 ```
 
-`clivly doctor` loads your config and runs the same read-only checks as
-`await clivly.doctor()`: API key, entity config, sources, Drizzle cursor/id
-columns, sample fetch, and heartbeat.
+`clivly doctor` runs the same read-only checks as `await clivly.doctor()` in
+code: API key present, entities configured, sources configured, concept
+coverage, Drizzle cursor/id columns, sample fetch, mapping dry-run,
+custom-object slugs, heartbeat, and namespace reachability.
 
-```bash
-npx clivly doctor
-npx clivly doctor --config ./apps/web/clivly.config.ts
+---
+
+## Runtime imports
+
+`clivly` is the consolidated public package. Application code imports from typed
+subpaths:
+
+```ts
+import { createClivlySDK, defineClivlyConfig } from "clivly/sdk";
+import { fromDrizzle, discoverFromDrizzle } from "clivly/drizzle";
+import { clivlyVite } from "clivly/vite";
+import { createClerkAuthAdapter } from "clivly/auth/clerk";
+import { createWorkOSAuthAdapter } from "clivly/auth/workos";
+import { createBetterAuthAdapter } from "clivly/auth/better-auth";
 ```
 
+> **Never `import` from the bare `clivly` specifier.** The package root is the
+> CLI binary — it imports `node:fs` and `node:child_process` at module scope, so
+> importing it from app code drags the whole CLI into your bundle and throws at
+> import time on Workers and other edge runtimes.
+
+Provider and framework integrations use **optional peer dependencies**. Install
+only what your app actually uses:
+
+| Subpath | Peer dependency |
+| --- | --- |
+| `clivly/drizzle` | `drizzle-orm` |
+| `clivly/vite` | `vite` |
+| `clivly/auth/clerk` | `@clerk/backend` |
+| `clivly/auth/workos` | `@workos-inc/node` |
+| `clivly/auth/better-auth` | none — you pass your own `betterAuth({...})` instance |
+
+`clivly/core/*` is deprecated in favour of `clivly/internal/*`. It still
+resolves, and emits a one-time `process.emitWarning` naming the replacement (so
+it stays off stdout and cannot corrupt machine-readable CLI output). See
+[STABILITY.md](https://github.com/amani-joseph/clivly.com/blob/master/STABILITY.md).
+
+---
+
+## Common errors
+
+| Symptom | Fix |
+| --- | --- |
+| Generated code doesn't match these docs | `npx clivly --version` — an older installed version is the usual cause |
+| `init` refuses to write, "No usable contact entity" | Pass `--contact-table <name>` |
+| `init` cannot find your schema | Pass `--schema <path\|package>` |
+| `init` scaffolded a `db` import that doesn't resolve | The probe cannot evaluate a db module that throws without `DATABASE_URL`. Fix the `TODO(clivly)` import path it left, or pass `--db-import` |
+| `clivly login` exits non-zero, pairing unavailable | The backend has `CLIVLY_CLI_PAIRING_ENABLED` off. Use the manual credential path above |
+| `clivly dev` cannot start | Install `cloudflared`, or set `CLIVLY_SYNC_TRIGGER_URL` to a tunnel you run yourself |
+| Credentials written but the app never loads them | Wrong env file for your framework — see the table under `clivly login` |
+
+The full troubleshooting table is in the
+[integration guide](https://github.com/amani-joseph/clivly.com/blob/master/docs/guides/connecting-to-clivly-cloud.md#8-common-errors-and-troubleshooting).
+
+---
+
 ## Telemetry
 
 **Clivly collects no telemetry.** The CLI makes network requests only to the
 Clivly API you point it at, and only to do what you asked: pairing, heartbeats,
 schema pushes, and status checks. No usage analytics, no crash reporting, no
-phone-home. See [SECURITY.md](https://github.com/amani-joseph/clivly.com/blob/master/SECURITY.md#telemetry).
-
-## More docs
-
-- Onboarding guide:
-  [connecting to Clivly Cloud](https://github.com/amani-joseph/clivly.com/blob/master/docs/guides/connecting-to-clivly-cloud.md)
-- Adding the chat widget:
-  [guide](https://github.com/amani-joseph/clivly.com/blob/master/docs/guides/adding-the-chat-widget.md)
-- Security policy:
-  [SECURITY.md](https://github.com/amani-joseph/clivly.com/blob/master/SECURITY.md)
-- SDK docs:
-  [`@clivly/sdk` README](https://github.com/amani-joseph/clivly.com/blob/master/packages/sdk/README.md)
-- Release notes:
-  [CHANGELOG](https://github.com/amani-joseph/clivly.com/blob/master/CHANGELOG.md)
+phone-home. See
+[SECURITY.md](https://github.com/amani-joseph/clivly.com/blob/master/SECURITY.md#telemetry).
+
+## Related documentation
+
+- **[Connecting to Clivly Cloud](https://github.com/amani-joseph/clivly.com/blob/master/docs/guides/connecting-to-clivly-cloud.md)** — the canonical end-to-end guide
+- [Adding the chat widget](https://github.com/amani-joseph/clivly.com/blob/master/docs/guides/adding-the-chat-widget.md)
+- [`@clivly/sdk` README](https://github.com/amani-joseph/clivly.com/blob/master/packages/sdk/README.md) — the runtime API surface
+- [STABILITY.md](https://github.com/amani-joseph/clivly.com/blob/master/STABILITY.md) — import tiers
+- [SECURITY.md](https://github.com/amani-joseph/clivly.com/blob/master/SECURITY.md)
+- [CHANGELOG.md](https://github.com/amani-joseph/clivly.com/blob/master/CHANGELOG.md)
 
 ## License
 

package/core-drizzle.cjs

@@ -1,8 +1,10 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
 const require_deprecate_subpath = require("./deprecate-subpath-B9ngvizt.cjs");
-const require_drizzle = require("./drizzle-DiReZf6d.cjs");
+const require_drizzle = require("./drizzle-bfjVzYR6.cjs");
 require("./internal-drizzle.cjs");
 //#region src/core-drizzle.ts
 require_deprecate_subpath.warnDeprecatedSubpath("clivly/core/drizzle", "clivly/internal/drizzle");
 //#endregion
+exports.buildColumnsMeta = require_drizzle.buildColumnsMeta;
+exports.buildUniqueConstraints = require_drizzle.buildUniqueConstraints;
 exports.discoverFromDrizzle = require_drizzle.discoverFromDrizzle;

package/core-drizzle.d.cts

@@ -1,2 +1,3 @@
-import { t as discoverFromDrizzle } from "./drizzle-DmeKSqeF.cjs";
-export { discoverFromDrizzle };
+import { n as buildUniqueConstraints, r as discoverFromDrizzle, t as buildColumnsMeta } from "./drizzle-jz0lrAgl.cjs";
+import "./internal-drizzle.cjs";
+export { buildColumnsMeta, buildUniqueConstraints, discoverFromDrizzle };

package/core-drizzle.d.mts

@@ -1,2 +1,3 @@
-import { t as discoverFromDrizzle } from "./drizzle-CFOr9dU9.mjs";
-export { discoverFromDrizzle };
+import { n as buildUniqueConstraints, r as discoverFromDrizzle, t as buildColumnsMeta } from "./drizzle-DooDUGqO.mjs";
+import "./internal-drizzle.mjs";
+export { buildColumnsMeta, buildUniqueConstraints, discoverFromDrizzle };

package/core-drizzle.mjs

@@ -1,7 +1,7 @@
 import { t as warnDeprecatedSubpath } from "./deprecate-subpath-CmvZtCpE.mjs";
-import { t as discoverFromDrizzle } from "./drizzle-B89tLo4T.mjs";
+import { n as buildUniqueConstraints, r as discoverFromDrizzle, t as buildColumnsMeta } from "./drizzle-3kvhkwO7.mjs";
 import "./internal-drizzle.mjs";
 //#region src/core-drizzle.ts
 warnDeprecatedSubpath("clivly/core/drizzle", "clivly/internal/drizzle");
 //#endregion
-export { discoverFromDrizzle };
+export { buildColumnsMeta, buildUniqueConstraints, discoverFromDrizzle };

package/core-entity-config.cjs

@@ -1,5 +1,5 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-const require_entity_config = require("./entity-config-D87rV-tE.cjs");
+const require_entity_config = require("./entity-config-nuXge6rY.cjs");
 //#region src/core-entity-config.ts
 require("./deprecate-subpath-B9ngvizt.cjs").warnDeprecatedSubpath("clivly/core/entity-config", "clivly/internal/entity-config");
 //#endregion
@@ -11,6 +11,7 @@ exports.MATERIALIZING_CONCEPTS = require_entity_config.MATERIALIZING_CONCEPTS;
 exports.defineClivlyConfig = require_entity_config.defineClivlyConfig;
 exports.entitiesConfigSchema = require_entity_config.entitiesConfigSchema;
 exports.filterSchema = require_entity_config.filterSchema;
+exports.projectionFields = require_entity_config.projectionFields;
 exports.relationshipSchema = require_entity_config.relationshipSchema;
 exports.relationshipsSchema = require_entity_config.relationshipsSchema;
 exports.validateEntitiesConfig = require_entity_config.validateEntitiesConfig;

package/core-entity-config.d.cts

@@ -1,2 +1,2 @@
-import { C as validateEntitiesConfig, S as relationshipsSchema, _ as RelationshipsMap, a as ClivlyEntitiesConfig, b as filterSchema, c as ConfigValidationResult, d as FilterExpr, f as FilterValue, g as RelationshipVia, h as RelationshipSpec, i as ClivlyConfigError, l as CrmConcept, m as MaterializingConcept, n as CRM_CONCEPTS, o as ClivlyEntityConfig, p as MATERIALIZING_CONCEPTS, r as CUSTOM_CONCEPT, s as ConfigValidationError, t as CANONICAL_FIELDS, u as DiscoveredSchemaTable, v as defineClivlyConfig, x as relationshipSchema, y as entitiesConfigSchema } from "./entity-config-DoUCXtq5.cjs";
-export { CANONICAL_FIELDS, CRM_CONCEPTS, CUSTOM_CONCEPT, ClivlyConfigError, ClivlyEntitiesConfig, ClivlyEntityConfig, ConfigValidationError, ConfigValidationResult, CrmConcept, DiscoveredSchemaTable, FilterExpr, FilterValue, MATERIALIZING_CONCEPTS, MaterializingConcept, RelationshipSpec, RelationshipVia, RelationshipsMap, defineClivlyConfig, entitiesConfigSchema, filterSchema, relationshipSchema, relationshipsSchema, validateEntitiesConfig };
+import { C as filterSchema, D as validateEntitiesConfig, E as relationshipsSchema, S as entitiesConfigSchema, T as relationshipSchema, _ as MaterializingConcept, a as ClivlyEntitiesConfig, b as RelationshipsMap, c as ClivlyEntityConfigInput, d as CrmConcept, f as DiscoveredColumnMeta, g as MATERIALIZING_CONCEPTS, h as FilterValue, i as ClivlyConfigError, l as ConfigValidationError, m as FilterExpr, n as CRM_CONCEPTS, o as ClivlyEntitiesConfigInput, p as DiscoveredSchemaTable, r as CUSTOM_CONCEPT, s as ClivlyEntityConfig, t as CANONICAL_FIELDS, u as ConfigValidationResult, v as RelationshipSpec, w as projectionFields, x as defineClivlyConfig, y as RelationshipVia } from "./entity-config-fKQhimtD.cjs";
+export { CANONICAL_FIELDS, CRM_CONCEPTS, CUSTOM_CONCEPT, ClivlyConfigError, ClivlyEntitiesConfig, ClivlyEntitiesConfigInput, ClivlyEntityConfig, ClivlyEntityConfigInput, ConfigValidationError, ConfigValidationResult, CrmConcept, DiscoveredColumnMeta, DiscoveredSchemaTable, FilterExpr, FilterValue, MATERIALIZING_CONCEPTS, MaterializingConcept, RelationshipSpec, RelationshipVia, RelationshipsMap, defineClivlyConfig, entitiesConfigSchema, filterSchema, projectionFields, relationshipSchema, relationshipsSchema, validateEntitiesConfig };

package/core-entity-config.d.mts

@@ -1,2 +1,2 @@
-import { C as validateEntitiesConfig, S as relationshipsSchema, _ as RelationshipsMap, a as ClivlyEntitiesConfig, b as filterSchema, c as ConfigValidationResult, d as FilterExpr, f as FilterValue, g as RelationshipVia, h as RelationshipSpec, i as ClivlyConfigError, l as CrmConcept, m as MaterializingConcept, n as CRM_CONCEPTS, o as ClivlyEntityConfig, p as MATERIALIZING_CONCEPTS, r as CUSTOM_CONCEPT, s as ConfigValidationError, t as CANONICAL_FIELDS, u as DiscoveredSchemaTable, v as defineClivlyConfig, x as relationshipSchema, y as entitiesConfigSchema } from "./entity-config-DoUCXtq5.mjs";
-export { CANONICAL_FIELDS, CRM_CONCEPTS, CUSTOM_CONCEPT, ClivlyConfigError, ClivlyEntitiesConfig, ClivlyEntityConfig, ConfigValidationError, ConfigValidationResult, CrmConcept, DiscoveredSchemaTable, FilterExpr, FilterValue, MATERIALIZING_CONCEPTS, MaterializingConcept, RelationshipSpec, RelationshipVia, RelationshipsMap, defineClivlyConfig, entitiesConfigSchema, filterSchema, relationshipSchema, relationshipsSchema, validateEntitiesConfig };
+import { C as filterSchema, D as validateEntitiesConfig, E as relationshipsSchema, S as entitiesConfigSchema, T as relationshipSchema, _ as MaterializingConcept, a as ClivlyEntitiesConfig, b as RelationshipsMap, c as ClivlyEntityConfigInput, d as CrmConcept, f as DiscoveredColumnMeta, g as MATERIALIZING_CONCEPTS, h as FilterValue, i as ClivlyConfigError, l as ConfigValidationError, m as FilterExpr, n as CRM_CONCEPTS, o as ClivlyEntitiesConfigInput, p as DiscoveredSchemaTable, r as CUSTOM_CONCEPT, s as ClivlyEntityConfig, t as CANONICAL_FIELDS, u as ConfigValidationResult, v as RelationshipSpec, w as projectionFields, x as defineClivlyConfig, y as RelationshipVia } from "./entity-config-fKQhimtD.mjs";
+export { CANONICAL_FIELDS, CRM_CONCEPTS, CUSTOM_CONCEPT, ClivlyConfigError, ClivlyEntitiesConfig, ClivlyEntitiesConfigInput, ClivlyEntityConfig, ClivlyEntityConfigInput, ConfigValidationError, ConfigValidationResult, CrmConcept, DiscoveredColumnMeta, DiscoveredSchemaTable, FilterExpr, FilterValue, MATERIALIZING_CONCEPTS, MaterializingConcept, RelationshipSpec, RelationshipVia, RelationshipsMap, defineClivlyConfig, entitiesConfigSchema, filterSchema, projectionFields, relationshipSchema, relationshipsSchema, validateEntitiesConfig };