@mediamonks/canopy-cli 0.4.5 → 0.5.0

package/README.md

@@ -0,0 +1,43 @@
+# @mediamonks/canopy-cli
+
+`canopy` — create, develop, deploy and manage Canopy projects from the
+terminal.
+
+```
+canopy login                      # OneLogin browser PKCE flow → CLI token
+canopy create / projects / delete
+canopy dev [--local [--pull]]     # remote-first dev, or the offline sandbox
+canopy deploy [--no-build]        # authorize → signed upload → complete
+canopy rollback / deploys / download
+canopy db pull | snapshot | snapshots | restore
+canopy token create | list | revoke
+canopy usage / docs / whoami / logout
+```
+
+Control-plane calls go through `src/api.ts` (`/control/v1` on the active
+site's `api.` host, bearer token — `CANOPY_DEPLOY_TOKEN` in CI wins over the
+login token); database safety runs on the data plane (`apiDataRequest` with
+`X-Canopy-Project`). `canopy deploy` streams bundle bytes straight to
+`/data/v1/uploads/:grant` under a short-lived signed grant — they never
+transit the control plane (docs/09-plane-split.md D-d). Multi-site profiles:
+docs/10-cli-sites.md.
+
+`canopy dev` proxies `/_api` to the platform with a 12-hour project-scoped
+dev token; `--local` boots the PGlite + filesystem sandbox (`src/local.ts`),
+mounting the exact `@mediamonks/canopy-data-plane` routers the platform
+serves — Postgres-dialect, matching the Postgres targets. ai/services still
+proxy to the real platform when logged in.
+
+## Working on it
+
+The globally-installed `canopy` is the **published npm release** — it will
+not exercise your changes. Build and use the local symlink instead:
+
+```
+vp pack          # in packages/cli (or `vp run dev` for --watch)
+canopy-dev …     # symlink to packages/cli/dist/index.mjs
+```
+
+Tests: `vp test` (includes the sandbox end-to-end suite against real
+PGlite). Publish via the staged workflow (root CLAUDE.md), after the SDK
+when `workspace:*` moved.

package/dist/{db-PpaU3V-B.mjs → db-BW1ZolWn.mjs}

@@ -1,5 +1,5 @@
-import { c as withContext, i as unwrap, n as reportErrors, r as requireTty, s as apiRequest } from "./ui-D1DXoDN1.mjs";
-import { i as resolveProject, n as projectFlagArgs } from "./project-DKbgJACM.mjs";
+import { a as projectFlagArgs, s as resolveProject } from "./site-BJjoePQS.mjs";
+import { i as unwrap, l as withContext, n as reportErrors, o as apiDataRequest, r as requireTty } from "./ui-DThlyHgo.mjs";
 import { defineCommand } from "citty";
 import { readFileSync, writeFileSync } from "node:fs";
 import * as p from "@clack/prompts";
@@ -41,7 +41,7 @@ const dbCommand = defineCommand({
 				const spin = p.spinner();
 				spin.start(`Exporting ${slug}…`);
 				try {
-					const { url } = await apiRequest("POST", `/projects/${slug}/export`);
+					const { url } = await apiDataRequest("POST", "/db/export", slug);
 					const download = await fetch(url);
 					if (!download.ok) throw new Error(`Download failed (HTTP ${download.status}).`);
 					const sql = Buffer.from(await download.arrayBuffer());
@@ -65,7 +65,7 @@ const dbCommand = defineCommand({
 				spin.start(`Snapshotting ${slug}…`);
 				let created;
 				try {
-					({snapshot: created} = await apiRequest("POST", `/projects/${slug}/snapshots`));
+					({snapshot: created} = await apiDataRequest("POST", "/db/snapshots", slug));
 				} catch (err) {
 					spin.error("Snapshot failed.");
 					throw err;
@@ -82,7 +82,7 @@ const dbCommand = defineCommand({
 			args: projectFlagArgs,
 			run: reportErrors("db snapshots", async ({ args }) => {
 				const { slug } = resolveProject(args);
-				const { snapshots } = await apiRequest("GET", `/projects/${slug}/snapshots`);
+				const { snapshots } = await apiDataRequest("GET", "/db/snapshots", slug);
 				if (snapshots.length === 0) {
 					console.log(`No snapshots for ${slug} yet — run \`canopy db snapshot\`.`);
 					return;
@@ -118,7 +118,7 @@ const dbCommand = defineCommand({
 				let snapshotKey = args.snapshot;
 				if (!snapshotKey && !file) {
 					requireTty("pass a local .sql dump or --snapshot <key>.");
-					const { snapshots } = await apiRequest("GET", `/projects/${slug}/snapshots`);
+					const { snapshots } = await apiDataRequest("GET", "/db/snapshots", slug);
 					if (snapshots.length === 0) throw new Error(`No snapshots for ${slug} — run \`canopy db snapshot\` first, or pass a local .sql dump.`);
 					snapshotKey = unwrap(await p.select({
 						message: `Snapshot to restore into ${slug}`,
@@ -137,11 +137,8 @@ const dbCommand = defineCommand({
 					}
 				}
 				const restoreContext = { action: `restore "${slug}" from ${snapshotKey ?? file}` };
-				if (snapshotKey) await withContext(apiRequest("POST", `/projects/${slug}/restore`, { snapshot: snapshotKey }), restoreContext);
-				else if (file) {
-					const sql = readFileSync(file, "utf8");
-					await withContext(apiRequest("POST", `/projects/${slug}/restore`, sql, "application/sql"), restoreContext);
-				}
+				if (snapshotKey) await withContext(apiDataRequest("POST", "/db/restore", slug, { snapshot: snapshotKey }), restoreContext);
+				else if (file) await withContext(apiDataRequest("POST", "/db/restore", slug, readFileSync(file, "utf8"), "application/sql"), restoreContext);
 				p.log.success(`Restored ${slug}.`);
 			})
 		})

package/dist/{deploy-B064KXtr.mjs → deploy-alC2--pZ.mjs}

@@ -1,19 +1,54 @@
-import { c as withContext, i as unwrap, n as reportErrors, o as apiDownload, s as apiRequest } from "./ui-D1DXoDN1.mjs";
-import { a as tryReadCanopyJson, i as resolveProject, n as projectFlagArgs, r as projectUrl, t as projectDirArgs } from "./project-DKbgJACM.mjs";
+import { a as projectFlagArgs, c as tryReadCanopyJson, i as projectDirArgs, n as siteConfig, o as projectUrl, s as resolveProject } from "./site-BJjoePQS.mjs";
+import { c as apiRequest, i as unwrap, l as withContext, n as reportErrors, s as apiDownload } from "./ui-DThlyHgo.mjs";
 import { defineCommand } from "citty";
-import { spawn } from "node:child_process";
-import { readFileSync, readdirSync, statSync, writeFileSync } from "node:fs";
+import { mkdtempSync, readFileSync, readdirSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
 import { join, relative, resolve } from "node:path";
+import { spawn } from "node:child_process";
 import * as p from "@clack/prompts";
+import * as esbuild from "esbuild";
+//#region src/worker-bundle.ts
+/**
+* Bundle a project's `worker/` entry for deploy (G6).
+* Output is a single ESM file uploaded as `_canopy/worker.mjs`.
+*/
+async function bundleWorker(projectDir, entry) {
+	const abs = resolve(projectDir, entry);
+	const outDir = mkdtempSync(join(tmpdir(), "canopy-worker-"));
+	const outfile = join(outDir, "worker.mjs");
+	try {
+		await esbuild.build({
+			entryPoints: [abs],
+			outfile,
+			bundle: true,
+			platform: "neutral",
+			format: "esm",
+			target: "es2022",
+			packages: "bundle",
+			logLevel: "silent"
+		});
+		return new Uint8Array(readFileSync(outfile));
+	} finally {
+		rmSync(outDir, {
+			recursive: true,
+			force: true
+		});
+	}
+}
+//#endregion
 //#region src/deploy.ts
 /**
-* canopy deploy — build (optional), bundle the output directory as multipart
-* form-data and POST it to the control plane; the deploy is live immediately
-* (docs/04-roadmap.md Phase 1 item 3).
+* canopy deploy — build (optional), then the signed-upload flow
+* (docs/09-plane-split.md D-d): the control plane authorizes the deploy and
+* issues a short-lived grant, each file PUTs straight to the data plane, and
+* a completion call makes the version live. Bundle bytes never transit the
+* control plane.
 *
 * Reads canopy.json in the project root:
 *   { "slug": "my-app", "dist": ".", "build": "npm run build" }
 */
+/** Must match apps/api/src/routes/deploys.ts WORKER_BUNDLE_PATH. */
+const WORKER_BUNDLE_PATH = "_canopy/worker.mjs";
 const IGNORED = /* @__PURE__ */ new Set([
 	"canopy.json",
 	"AGENTS.md",
@@ -77,25 +112,70 @@ const deployCommand = defineCommand({
 			throw new Error(`Output directory not found: ${distDir}`);
 		}
 		if (paths.length === 0) throw new Error(`Nothing to deploy in ${distDir}.`);
-		const form = new FormData();
+		const files = [];
 		let total = 0;
 		for (const path of paths) {
 			const data = readFileSync(path);
 			total += data.byteLength;
-			form.append(relative(distDir, path).replaceAll("\\", "/"), new Blob([data]));
+			files.push({
+				path: relative(distDir, path).replaceAll("\\", "/"),
+				data
+			});
+		}
+		let workerBytes = null;
+		if (config.worker) {
+			const spinWorker = p.spinner();
+			spinWorker.start(`Bundling worker ${config.worker}`);
+			try {
+				workerBytes = await bundleWorker(dir, config.worker);
+				total += workerBytes.byteLength;
+				spinWorker.stop(`Worker bundle ${(workerBytes.byteLength / 1024).toFixed(1)} kB`);
+			} catch (err) {
+				spinWorker.error("Worker bundle failed.");
+				throw err;
+			}
 		}
+		const source = process.env["GITHUB_ACTIONS"] ? { "x-canopy-source": "github-action" } : {};
 		const spin = p.spinner();
-		spin.start(`Deploying ${paths.length} files (${(total / 1024).toFixed(0)} kB) → ${slug}`);
+		const workerNote = workerBytes ? " + worker" : "";
+		spin.start(`Deploying ${files.length} files${workerNote} (${(total / 1024).toFixed(0)} kB) → ${slug}`);
 		let result;
 		try {
-			({deploy: result} = await withContext(apiRequest("POST", `/projects/${slug}/deploys`, form, void 0, process.env["GITHUB_ACTIONS"] ? { "x-canopy-source": "github-action" } : void 0), { action: `deploy "${slug}"` }));
+			const { upload } = await withContext(apiRequest("POST", `/projects/${slug}/deploys`, { worker: workerBytes !== null }, void 0, source), { action: `deploy "${slug}"` });
+			const uploads = [...files, ...workerBytes ? [{
+				path: WORKER_BUNDLE_PATH,
+				data: workerBytes
+			}] : []];
+			await uploadFiles(upload.grant, uploads);
+			({deploy: result} = await withContext(apiRequest("POST", `/projects/${slug}/deploys/${upload.version}/complete`, { grant: upload.grant }, void 0, source), { action: `deploy "${slug}"` }));
 		} catch (err) {
 			spin.error("Deploy failed.");
 			throw err;
 		}
-		spin.stop(`Live: ${projectUrl(slug)} (v${result.version})`);
+		const backend = result.worker?.serviceUrl ? ` · backend ${result.worker.serviceUrl}` : "";
+		spin.stop(`Live: ${projectUrl(slug)} (v${result.version})${backend}`);
 	})
 });
+const UPLOAD_CONCURRENCY = 8;
+/** PUT each file to /data/v1/uploads/<grant> — the grant is the credential. */
+async function uploadFiles(grant, files) {
+	const { apiUrl } = siteConfig();
+	const queue = [...files];
+	async function worker() {
+		for (let file = queue.shift(); file; file = queue.shift()) {
+			const url = `${apiUrl}/data/v1/uploads/${encodeURIComponent(grant)}?path=${encodeURIComponent(file.path)}`;
+			const res = await fetch(url, {
+				method: "PUT",
+				body: Buffer.from(file.data)
+			});
+			if (!res.ok) {
+				const payload = await res.json().catch(() => ({}));
+				throw new Error(`Upload of ${file.path} failed (HTTP ${res.status}${payload.error ? `, ${payload.error}` : ""}).`);
+			}
+		}
+	}
+	await Promise.all(Array.from({ length: UPLOAD_CONCURRENCY }, worker));
+}
 /** Show the deploy history and ask which version to act on. */
 async function pickVersion(deploys, live, message, initial) {
 	return unwrap(await p.select({

package/dist/dev-BJ5xEwqW.mjs

@@ -0,0 +1,2 @@
+import { t as devCommand } from "./dev-CQQhMOoD.mjs";
+export { devCommand };

package/dist/{dev-CuvlJpcO.mjs → dev-CQQhMOoD.mjs}

@@ -1,22 +1,17 @@
-import { a as ApiError, c as withContext, l as readConfig, n as reportErrors, s as apiRequest } from "./ui-D1DXoDN1.mjs";
-import { i as resolveProject, t as projectDirArgs } from "./project-DKbgJACM.mjs";
+import { i as projectDirArgs, n as siteConfig, s as resolveProject } from "./site-BJjoePQS.mjs";
+import { a as ApiError, c as apiRequest, l as withContext, n as reportErrors } from "./ui-DThlyHgo.mjs";
 import { createRequire } from "node:module";
 import { defineCommand } from "citty";
 import { join } from "node:path";
 import { pathToFileURL } from "node:url";
 //#region src/dev.ts
 /**
-* Mirror the gateway's project-host rewrite (apps/gateway/src/index.ts):
-* strip /_api, then scope bare data-plane module paths onto this project.
-* Control-plane paths (and /v1/sdk.js) pass through untouched.
+* Mirror the gateway (apps/gateway/src/index.ts): strip /_api and forward.
+* The plane is the path — no per-module rewriting; project scope rides on
+* the dev token (remote) or is implicit in the sandbox (local).
 */
-function rewriteApiPath(path, slug) {
-	const queryStart = path.indexOf("?");
-	const query = queryStart === -1 ? "" : path.slice(queryStart);
-	let pathname = (queryStart === -1 ? path : path.slice(0, queryStart)).slice(5);
-	const dataPlane = /^\/v1\/(db|blob|ai|services)(\/.*)?$/.exec(pathname);
-	if (dataPlane) pathname = `/v1/projects/${slug}/${dataPlane[1]}${dataPlane[2] ?? ""}`;
-	return pathname + query;
+function rewriteApiPath(path) {
+	return path.slice(5);
 }
 /**
 * Load Vite's `createServer`, preferring the Vite installed in the *project*
@@ -87,12 +82,12 @@ function devTokenContext(slug) {
 }
 async function devRemote(flags, slug) {
 	const { token, expires_at } = await withContext(apiRequest("POST", `/projects/${slug}/dev-token`), devTokenContext(slug));
-	const { apiUrl } = readConfig();
+	const { apiUrl } = siteConfig();
 	const server = await startVite(flags, { proxy: { "/_api": {
 		target: apiUrl,
 		changeOrigin: true,
 		headers: { authorization: `Bearer ${token}` },
-		rewrite: (path) => rewriteApiPath(path, slug)
+		rewrite: rewriteApiPath
 	} } });
 	console.log(`\n  ${slug} — remote-first dev against LIVE project data`);
 	console.log("  (worried about a risky change? `canopy db snapshot` first, or work");
@@ -103,7 +98,7 @@ async function devRemote(flags, slug) {
 async function devLocal(flags, slug) {
 	let dump;
 	if (flags.pull) {
-		const { fetchProjectDump } = await import("./local-B3dyT2fh.mjs");
+		const { fetchProjectDump } = await import("./local-C5-GWJcx.mjs");
 		console.log(`Pulling a fresh export of ${slug}…`);
 		dump = await fetchProjectDump(slug);
 	}
@@ -111,18 +106,18 @@ async function devLocal(flags, slug) {
 	try {
 		const { token } = await withContext(apiRequest("POST", `/projects/${slug}/dev-token`), devTokenContext(slug));
 		remote = {
-			target: readConfig().apiUrl,
+			target: siteConfig().apiUrl,
 			token
 		};
 	} catch (err) {
 		const reason = err instanceof ApiError ? err.explain().why : String(err);
 		console.log(`Note: ai/services will be unavailable — could not reach the platform (${reason}).`);
 	}
-	const { createSandbox } = await import("./local-B3dyT2fh.mjs");
+	const { createSandbox } = await import("./local-C5-GWJcx.mjs");
 	const sandbox = await createSandbox({
 		slug,
 		persistDir: join(flags.dir, ".canopy", "local"),
-		email: readConfig().email
+		email: siteConfig().email
 	});
 	if (dump !== void 0) {
 		await sandbox.applyDump(dump);
@@ -159,20 +154,23 @@ async function devLocal(flags, slug) {
 		target: remote.target,
 		changeOrigin: true,
 		headers: { authorization: `Bearer ${remote.token}` },
-		rewrite: (path) => rewriteApiPath(path, slug)
+		rewrite: rewriteApiPath
 	};
 	const server = await startVite(flags, { proxy: {
 		...remoteEntry && {
-			"/_api/v1/ai": remoteEntry,
-			"/_api/v1/services": remoteEntry
+			"/_api/data/v1/ai": remoteEntry,
+			"/_api/data/v1/services": remoteEntry
 		},
-		"/_api": { target: `http://127.0.0.1:${apiAddress.port}` }
+		"/_api": {
+			target: `http://127.0.0.1:${apiAddress.port}`,
+			rewrite: (path) => path
+		}
 	} });
 	server.httpServer?.once("close", () => {
 		apiServer.close();
 		sandbox.dispose();
 	});
-	console.log(`\n  ${slug} — LOCAL sandbox (Miniflare D1/R2 in .canopy/local/)`);
+	console.log(`\n  ${slug} — LOCAL sandbox (PGlite + filesystem blobs in .canopy/local/)`);
 	console.log("  data is yours alone: db and blob writes never reach the platform");
 	if (dump === void 0) console.log("  (want prod data? restart with --pull to hydrate from a fresh export)");
 	console.log("  blobs are not pulled — the local blob store starts empty");
@@ -194,7 +192,7 @@ const devCommand = defineCommand({
 		local: {
 			type: "boolean",
 			default: false,
-			description: "Local-data sandbox (Miniflare D1/R2 under .canopy/local/) instead of live data"
+			description: "Local-data sandbox (PGlite + blobs under .canopy/local/) instead of live data"
 		},
 		pull: {
 			type: "boolean",

package/dist/docs/ci.md

@@ -34,15 +34,19 @@ of an interactive login. A minimal GitHub Actions step:
 
 ```yaml
 - run: npm install -g @mediamonks/canopy-cli
-- run: canopy deploy --build
+- run: canopy deploy
   env:
     CANOPY_DEPLOY_TOKEN: ${{ secrets.CANOPY_DEPLOY_TOKEN }}
 ```
 
+(`canopy deploy` runs the project's `canopy.json` build command by default;
+pass `--no-build` if CI already built the output directory.)
+
 No `canopy login` step is needed — the token is the credential.
 
 ## Notes
 
-- A deploy token can only deploy its own project. If it strays to another
+- A deploy token can only deploy its own project — it reaches that project's
+  deploy endpoints and upload grants and nothing else. If it strays to another
   project's resources, the platform rejects it.
 - Revoke a token the moment it might be exposed; create a fresh one to replace it.

package/dist/docs/cli.md

@@ -35,13 +35,16 @@ is the overview.
 
 - `canopy dev` — run the project locally against live platform data.
   - `--port <port>` — dev server port.
-  - `--local` — offline sandbox (Miniflare D1/R2 under `.canopy/local/`).
+  - `--local` — offline sandbox (PGlite + filesystem blobs under `.canopy/local/`).
   - `--pull` — hydrate the sandbox from a fresh prod export first (with `--local`).
 
 ## Deploy
 
-- `canopy deploy` — build and deploy the project.
-  - `--build` — run the `canopy.json` build command first.
+- `canopy deploy` — build and deploy the project (the `canopy.json` build
+  command runs first by default).
+  - `--no-build` — skip the build, deploy the output directory as-is.
+  - `--project <slug>` — deploy any directory, overriding (or without) a
+    `canopy.json`.
 - `canopy rollback [version]` — make an earlier deploy live again, e.g. `v3`
   (picked from history when omitted). `--dir <path>` to target another directory.
 - `canopy download [version]` — download a deploy's assets as a zip, e.g. `v3`
@@ -56,6 +59,8 @@ is the overview.
 - `canopy db snapshots` — list stored snapshots.
 - `canopy db restore [file]` — replace ALL project data from a `.sql` file or
   `--snapshot <key>`. `--yes` skips the confirmation. **Destructive.**
+- `canopy usage` — AI spend and storage for the project (same data as the
+  dashboard Usage tab). `--project <slug>` / `--json` for agents.
 
 ## CI / deploy tokens
 

package/dist/docs/data.md

@@ -5,9 +5,10 @@ summary: Pulling, snapshotting, and restoring your project database.
 
 # Working with project data
 
-Each Canopy project gets its own database (D1) and blob storage (R2). Your app
-reads and writes them through the Canopy SDK at runtime; the CLI gives you tools
-to manage the data around it.
+Each Canopy project gets its own database and blob storage (D1 and R2 on the
+Cloudflare target; Postgres and GCS on GCP). Your app reads and writes them
+through the Canopy SDK at runtime; the CLI gives you tools to manage the data
+around it.
 
 ## Collections in your app (SDK)
 
@@ -24,7 +25,24 @@ digits, and underscores only (`^[a-z][a-z0-9_]*$`). `blog_posts` is fine;
 > `Invalid collection name "BlogPosts" — use lowercase letters, digits and underscores.`
 
 Use `snake_case` for multi-word names. This mirrors the collection name straight
-into SQLite storage, so keeping it lowercase avoids case-sensitivity surprises.
+into the underlying database, so keeping it lowercase avoids case-sensitivity
+surprises.
+
+## Dialects and raw SQL
+
+The document API above is portable — it behaves the same on every platform
+target. Raw SQL is not: `canopy.db.sql()` passes your statement through
+untranslated, so it speaks whatever the target's database speaks. Ask the
+platform which that is:
+
+```ts
+await canopy.db.dialect(); // "sqlite" | "postgres"
+```
+
+Parameterize with `?` on sqlite and `$1` on postgres. One more per-target
+difference: `collection().search()` is real full-text search (FTS5) on sqlite
+targets, and a plain substring match on postgres targets — different matches,
+no ranking.
 
 ## Download a dump
 

package/dist/docs/deploy.md

@@ -14,19 +14,23 @@ canopy deploy
 This uploads your built assets to the platform, creates a new immutable deploy
 version, and makes it live. Each deploy is versioned (`v1`, `v2`, …).
 
+Under the hood a deploy is three steps: the platform authorizes it and issues a
+short-lived signed upload grant, the CLI uploads each file directly against
+that grant, and a completion call checks the bundle and makes the new version
+live. You only ever run `canopy deploy` — but it means a half-uploaded deploy
+is never served.
+
 ## Building first
 
 If your project needs a build step (React SPA, anything with a bundler), declare
-the build command in `canopy.json` and pass `--build`:
+the build command in `canopy.json` — `canopy deploy` runs it automatically
+before uploading. To skip the build and upload whatever is already in the
+output directory (or the static files as-is for a `static` project):
 
 ```bash
-canopy deploy --build
+canopy deploy --no-build
 ```
 
-`--build` runs the project's configured build command before uploading. Without
-it, `canopy deploy` uploads whatever is already built (or the static files as-is
-for a `static` project).
-
 ## Rolling back
 
 Every deploy is kept, so you can instantly revert:

package/dist/docs/dev.md

@@ -20,14 +20,15 @@ develop against realistic state.
 ## Offline sandbox
 
 To develop without touching live data — for example on a plane, or before you
-trust a destructive change — use a local sandbox backed by Miniflare:
+trust a destructive change — use a local sandbox backed by PGlite (embedded
+Postgres) and a filesystem blob store:
 
 ```bash
 canopy dev --local
 ```
 
-This creates local D1 and R2 under `.canopy/local/` in your project. The sandbox
-starts empty.
+This creates local Postgres data and blobs under `.canopy/local/` in your
+project. The sandbox starts empty.
 
 To seed the sandbox from a fresh copy of production data first:
 
@@ -37,6 +38,12 @@ canopy dev --local --pull
 
 `.canopy/local/` is disposable — delete it to reset the sandbox.
 
+One caveat: the sandbox database is Postgres, so raw `canopy.db.sql()` speaks
+the postgres dialect there, while your deployed project speaks whatever its
+platform target speaks (`canopy.db.dialect()` tells you — sqlite on
+Cloudflare). Collections (`canopy.db.collection(...)`) behave the same in both,
+so this only matters for hand-written SQL — see `canopy docs data`.
+
 ## Which mode should an agent use?
 
 - Iterating on UI or read-only features → `canopy dev` (live data, realistic).