@mediamonks/canopy-cli 0.6.0 → 0.7.1

package/dist/{db-BpnjQUkF.mjs → db-BkUmbGgx.mjs}

@@ -1,6 +1,6 @@
-import { c as resolveProject, o as projectFlagArgs } from "./site-DQnysZ3W.mjs";
-import { i as unwrap, l as withContext, n as reportErrors, o as apiDataRequest, r as requireTty } from "./ui-BhzMeKQl.mjs";
-import { n as migrateProject, r as readMigrationFiles, t as describeMigrateResult } from "./migrations-B0kJarjr.mjs";
+import { c as resolveProject, o as projectFlagArgs } from "./site-BUlQR117.mjs";
+import { i as unwrap, l as withContext, n as reportErrors, o as apiDataRequest, r as requireTty } from "./ui-D8HxX0Ng.mjs";
+import { n as migrateProject, r as readMigrationFiles, t as describeMigrateResult } from "./migrations-I1adj0z2.mjs";
 import { defineCommand } from "citty";
 import { readFileSync, writeFileSync } from "node:fs";
 import * as p from "@clack/prompts";
@@ -18,6 +18,14 @@ import * as p from "@clack/prompts";
 * The project comes from canopy.json in the current directory, or
 * --project <slug>.
 */
+/** Shared flag: operate on the staging channel's database (docs/14). */
+const stagingFlagArgs = { staging: {
+	type: "boolean",
+	default: false,
+	description: "Target the staging channel's database instead of live"
+} };
+const channelOf = (args) => args.staging ? "staging" : "live";
+const channelNote = (args) => args.staging ? " [staging]" : "";
 const formatSize = (bytes) => bytes < 1024 * 1024 ? `${(bytes / 1024).toFixed(1)} kB` : `${(bytes / 1024 / 1024).toFixed(1)} MB`;
 const dbCommand = defineCommand({
 	meta: {
@@ -32,6 +40,7 @@ const dbCommand = defineCommand({
 			},
 			args: {
 				...projectFlagArgs,
+				...stagingFlagArgs,
 				out: {
 					type: "string",
 					description: "Output file (defaults to <slug>-<timestamp>.sql)"
@@ -41,9 +50,9 @@ const dbCommand = defineCommand({
 				const { slug } = resolveProject(args);
 				const out = args.out ?? `${slug}-${(/* @__PURE__ */ new Date()).toISOString().slice(0, 19).replaceAll(/[:T]/g, "-")}.sql`;
 				const spin = p.spinner();
-				spin.start(`Exporting ${slug}…`);
+				spin.start(`Exporting ${slug}${channelNote(args)}…`);
 				try {
-					const { url } = await apiDataRequest("POST", "/db/export", slug);
+					const { url } = await apiDataRequest("POST", "/db/export", slug, void 0, void 0, channelOf(args));
 					const download = await fetch(url);
 					if (!download.ok) throw new Error(`Download failed (HTTP ${download.status}).`);
 					const sql = Buffer.from(await download.arrayBuffer());
@@ -60,14 +69,17 @@ const dbCommand = defineCommand({
 				name: "snapshot",
 				description: "Store a dump server-side (restorable anytime)"
 			},
-			args: projectFlagArgs,
+			args: {
+				...projectFlagArgs,
+				...stagingFlagArgs
+			},
 			run: reportErrors("db snapshot", async ({ args }) => {
 				const { slug } = resolveProject(args);
 				const spin = p.spinner();
-				spin.start(`Snapshotting ${slug}…`);
+				spin.start(`Snapshotting ${slug}${channelNote(args)}…`);
 				let created;
 				try {
-					({snapshot: created} = await apiDataRequest("POST", "/db/snapshots", slug));
+					({snapshot: created} = await apiDataRequest("POST", "/db/snapshots", slug, void 0, void 0, channelOf(args)));
 				} catch (err) {
 					spin.error("Snapshot failed.");
 					throw err;
@@ -81,10 +93,13 @@ const dbCommand = defineCommand({
 				name: "snapshots",
 				description: "List stored snapshots"
 			},
-			args: projectFlagArgs,
+			args: {
+				...projectFlagArgs,
+				...stagingFlagArgs
+			},
 			run: reportErrors("db snapshots", async ({ args }) => {
 				const { slug } = resolveProject(args);
-				const { snapshots } = await apiDataRequest("GET", "/db/snapshots", slug);
+				const { snapshots } = await apiDataRequest("GET", "/db/snapshots", slug, void 0, void 0, channelOf(args));
 				if (snapshots.length === 0) {
 					console.log(`No snapshots for ${slug} yet — run \`canopy db snapshot\`.`);
 					return;
@@ -99,6 +114,7 @@ const dbCommand = defineCommand({
 			},
 			args: {
 				...projectFlagArgs,
+				...stagingFlagArgs,
 				file: {
 					type: "positional",
 					description: "Local .sql dump to restore from",
@@ -120,7 +136,7 @@ const dbCommand = defineCommand({
 				let snapshotKey = args.snapshot;
 				if (!snapshotKey && !file) {
 					requireTty("pass a local .sql dump or --snapshot <key>.");
-					const { snapshots } = await apiDataRequest("GET", "/db/snapshots", slug);
+					const { snapshots } = await apiDataRequest("GET", "/db/snapshots", slug, void 0, void 0, channelOf(args));
 					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}`,
@@ -133,15 +149,15 @@ const dbCommand = defineCommand({
 				}
 				if (!args.yes) {
 					requireTty("pass --yes to restore without confirmation.");
-					if (unwrap(await p.text({ message: `Restore will REPLACE all current data in "${slug}" with ${snapshotKey ?? file}. Type the slug to confirm.` })).trim() !== slug) {
+					if (unwrap(await p.text({ message: `Restore will REPLACE all current data in "${slug}"${channelNote(args)} with ${snapshotKey ?? file}. Type the slug to confirm.` })).trim() !== slug) {
 						p.cancel("Aborted.");
 						return;
 					}
 				}
 				const restoreContext = { action: `restore "${slug}" from ${snapshotKey ?? file}` };
-				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}.`);
+				if (snapshotKey) await withContext(apiDataRequest("POST", "/db/restore", slug, { snapshot: snapshotKey }, void 0, channelOf(args)), restoreContext);
+				else if (file) await withContext(apiDataRequest("POST", "/db/restore", slug, readFileSync(file, "utf8"), "application/sql", channelOf(args)), restoreContext);
+				p.log.success(`Restored ${slug}${channelNote(args)}.`);
 			})
 		}),
 		migrate: defineCommand({
@@ -151,6 +167,7 @@ const dbCommand = defineCommand({
 			},
 			args: {
 				...projectFlagArgs,
+				...stagingFlagArgs,
 				plan: {
 					type: "boolean",
 					default: false,
@@ -162,17 +179,17 @@ const dbCommand = defineCommand({
 				const files = readMigrationFiles(dir);
 				if (files === void 0) throw new Error("No migrations directory configured — set \"migrations\" in canopy.json (e.g. {\"migrations\": \"./migrations\"}, pointing at your drizzle-kit output).");
 				if (args.plan) {
-					const result = await withContext(migrateProject(slug, files, true), { action: `plan migrations for "${slug}"` });
+					const result = await withContext(migrateProject(slug, files, true, channelOf(args)), { action: `plan migrations for "${slug}"${channelNote(args)}` });
 					if (result.pending.length === 0) console.log(`Nothing pending (${result.applied.length} applied previously).`);
 					else for (const name of result.pending) console.log(`pending ${name}`);
 					for (const line of describeMigrateResult(result)) console.log(line);
 					return;
 				}
 				const spin = p.spinner();
-				spin.start(`Migrating ${slug}…`);
+				spin.start(`Migrating ${slug}${channelNote(args)}…`);
 				let result;
 				try {
-					result = await withContext(migrateProject(slug, files), { action: `migrate "${slug}"` });
+					result = await withContext(migrateProject(slug, files, false, channelOf(args)), { action: `migrate "${slug}"${channelNote(args)}` });
 				} catch (err) {
 					spin.error("Migrate failed.");
 					throw err;

package/dist/{deploy-DdSSL227.mjs → deploy-BcczXlSQ.mjs}

@@ -1,6 +1,6 @@
-import { a as projectDirArgs, c as resolveProject, l as tryReadCanopyJson, n as siteConfig, o as projectFlagArgs, s as projectUrl } from "./site-DQnysZ3W.mjs";
-import { c as apiRequest, i as unwrap, l as withContext, n as reportErrors, o as apiDataRequest, s as apiDownload } from "./ui-BhzMeKQl.mjs";
-import { n as migrateProject, r as readMigrationFiles, t as describeMigrateResult } from "./migrations-B0kJarjr.mjs";
+import { a as projectDirArgs, c as resolveProject, l as stagingUrl, n as siteConfig, o as projectFlagArgs, s as projectUrl, u as tryReadCanopyJson } from "./site-BUlQR117.mjs";
+import { c as apiRequest, i as unwrap, l as withContext, n as reportErrors, o as apiDataRequest, s as apiDownload } from "./ui-D8HxX0Ng.mjs";
+import { n as migrateProject, r as readMigrationFiles, t as describeMigrateResult } from "./migrations-I1adj0z2.mjs";
 import { defineCommand } from "citty";
 import { mkdtempSync, readFileSync, readdirSync, rmSync, statSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
@@ -108,10 +108,16 @@ const deployCommand = defineCommand({
 			default: true,
 			description: "Apply pending schema migrations before the version goes live",
 			negativeDescription: "Skip migrations, deploy the code only"
+		},
+		staging: {
+			type: "boolean",
+			default: false,
+			description: "Deploy to the project's staging channel (created on first use, database cloned from live)"
 		}
 	},
 	run: reportErrors("deploy", async ({ args }) => {
 		const { dir, slug } = resolveProject(args);
+		const channel = args.staging ? "staging" : "live";
 		const config = tryReadCanopyJson(dir) ?? {};
 		if (config.build && args.build) await runBuild(config.build, dir);
 		const migrations = args.migrate ? readMigrationFiles(dir) : void 0;
@@ -154,22 +160,28 @@ const deployCommand = defineCommand({
 		const source = process.env["GITHUB_ACTIONS"] ? { "x-canopy-source": "github-action" } : {};
 		const spin = p.spinner();
 		const workerNote = workerBytes ? " + worker" : "";
-		spin.start(`Deploying ${files.length} files${workerNote} (${(total / 1024).toFixed(0)} kB) → ${slug}`);
+		const channelNote = channel === "staging" ? " [staging]" : "";
+		spin.start(`Deploying ${files.length} files${workerNote} (${(total / 1024).toFixed(0)} kB) → ${slug}${channelNote}`);
 		let result;
 		let migrateResult;
+		let stagingCreated = false;
 		try {
-			const { upload } = await withContext(apiRequest("POST", `/projects/${slug}/deploys`, { worker: workerBytes !== null }, void 0, source), { action: `deploy "${slug}"` });
+			const { upload } = await withContext(apiRequest("POST", `/projects/${slug}/deploys`, {
+				worker: workerBytes !== null,
+				channel
+			}, void 0, source), { action: `deploy "${slug}"` });
+			stagingCreated = upload.stagingCreated === true;
 			const uploads = [...files, ...workerBytes ? [{
 				path: WORKER_BUNDLE_PATH,
 				data: workerBytes
 			}] : []];
 			await uploadFiles(upload.grant, uploads);
 			if (migrations !== void 0 && migrations.length > 0) {
-				spin.message(`Applying schema migrations → ${slug}`);
+				spin.message(`Applying schema migrations → ${slug}${channelNote}`);
 				try {
-					migrateResult = await withContext(migrateProject(slug, migrations), { action: `migrate "${slug}"` });
+					migrateResult = await withContext(migrateProject(slug, migrations, false, channel), { action: `migrate "${slug}"${channelNote}` });
 				} catch (err) {
-					spin.error("Deploy aborted — migrations failed; the live version is unchanged.");
+					spin.error(channel === "staging" ? "Deploy aborted — migrations failed on staging; live is unaffected." : "Deploy aborted — migrations failed; the live version is unchanged.");
 					throw err;
 				}
 			}
@@ -179,10 +191,68 @@ const deployCommand = defineCommand({
 			throw err;
 		}
 		const backend = result.worker?.serviceUrl ? ` · backend ${result.worker.serviceUrl}` : "";
-		spin.stop(`Live: ${projectUrl(slug)} (v${result.version})${backend}`);
+		if (channel === "staging") {
+			spin.stop(`Staging: ${stagingUrl(slug)} (v${result.version})${backend}`);
+			if (stagingCreated) console.log("  staging channel created — database cloned from live");
+			console.log(`  happy with it? \`canopy promote\` makes v${result.version} live`);
+		} else spin.stop(`Live: ${projectUrl(slug)} (v${result.version})${backend}`);
 		if (migrateResult !== void 0) for (const line of describeMigrateResult(migrateResult)) console.log(`  ${line}`);
 	})
 });
+const promoteCommand = defineCommand({
+	meta: {
+		name: "promote",
+		description: "Make the staged version live (migrations replay against live first)"
+	},
+	args: {
+		version: {
+			type: "positional",
+			description: "Version to promote, e.g. v3 (defaults to the staged version)",
+			required: false
+		},
+		...projectFlagArgs,
+		dir: {
+			type: "string",
+			description: "Project directory (defaults to the current directory)"
+		},
+		yes: {
+			type: "boolean",
+			default: false,
+			description: "Skip the confirmation prompt"
+		}
+	},
+	run: reportErrors("promote", async ({ args }) => {
+		const { slug } = resolveProject(args);
+		let target;
+		if (args.version !== void 0) {
+			if (!/^v?\d+$/.test(args.version)) throw new Error(`Invalid version "${args.version}" — expected a number like 3 or v3.`);
+			target = Number(args.version.replace(/^v/, ""));
+		} else {
+			const { staging } = await apiRequest("GET", `/projects/${slug}/staging`);
+			if (!staging.provisioned || staging.version === null) throw new Error(`Nothing staged for "${slug}" — run \`canopy deploy --staging\` first, or pass a version explicitly.`);
+			target = staging.version;
+		}
+		if (!args.yes && process.stdin.isTTY) {
+			if (!unwrap(await p.confirm({ message: `Promote v${target} of "${slug}" to live? Pending migrations replay against the live database first (snapshot taken automatically).` }))) {
+				p.cancel("Aborted.");
+				return;
+			}
+		}
+		const spin = p.spinner();
+		spin.start(`Promoting ${slug} v${target} → live`);
+		let result;
+		try {
+			({live: result} = await withContext(apiRequest("POST", `/projects/${slug}/deploys/${target}/promote`), { action: `promote "${slug}" v${target}` }));
+		} catch (err) {
+			spin.error("Promote failed — the live version is unchanged.");
+			throw err;
+		}
+		const backend = result.worker?.serviceUrl ? ` · backend ${result.worker.serviceUrl}` : "";
+		spin.stop(`Live: ${projectUrl(slug)} (v${result.version}, was v${result.previous ?? "?"})${backend}`);
+		for (const name of result.migrationsApplied) console.log(`  applied ${name}`);
+		if (result.snapshot !== void 0) console.log(`  pre-promote snapshot: ${result.snapshot} (canopy db restore --snapshot …)`);
+	})
+});
 const UPLOAD_CONCURRENCY = 8;
 /** PUT each file to /data/v1/uploads/<grant> — the grant is the credential. */
 async function uploadFiles(grant, files) {
@@ -218,7 +288,7 @@ async function pickVersion(deploys, live, message, initial) {
 const rollbackCommand = defineCommand({
 	meta: {
 		name: "rollback",
-		description: "Make an earlier deploy live again (pick from history)"
+		description: "Make an earlier deploy live again, backend included (pick from history)"
 	},
 	args: {
 		version: {
@@ -251,7 +321,8 @@ const rollbackCommand = defineCommand({
 		}
 		console.log(`Rolling back ${slug} to v${target}`);
 		const { live: result } = await apiRequest("POST", `/projects/${slug}/deploys/${target}/rollback`);
-		console.log(`Live: ${projectUrl(slug)} (v${result.version}, was v${result.previous ?? "?"})`);
+		const worker = result.worker ? ` · worker v${result.worker.version}` : "";
+		console.log(`Live: ${projectUrl(slug)} (v${result.version}, was v${result.previous ?? "?"})${worker}`);
 	})
 });
 const downloadCommand = defineCommand({
@@ -302,4 +373,4 @@ const downloadCommand = defineCommand({
 	})
 });
 //#endregion
-export { deployCommand, downloadCommand, rollbackCommand };
+export { deployCommand, downloadCommand, promoteCommand, rollbackCommand };

package/dist/dev-CvtoGFW0.mjs

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

package/dist/{dev-OxeYndd1.mjs → dev-DvyKHe2d.mjs}

@@ -1,6 +1,6 @@
-import { a as projectDirArgs, c as resolveProject, i as projectDialect, l as tryReadCanopyJson, n as siteConfig } from "./site-DQnysZ3W.mjs";
-import { a as ApiError, c as apiRequest, l as withContext, n as reportErrors } from "./ui-BhzMeKQl.mjs";
-import { r as readMigrationFiles } from "./migrations-B0kJarjr.mjs";
+import { a as projectDirArgs, c as resolveProject, i as projectDialect, n as siteConfig, u as tryReadCanopyJson } from "./site-BUlQR117.mjs";
+import { a as ApiError, c as apiRequest, l as withContext, n as reportErrors } from "./ui-D8HxX0Ng.mjs";
+import { r as readMigrationFiles } from "./migrations-I1adj0z2.mjs";
 import { createRequire } from "node:module";
 import { defineCommand } from "citty";
 import { join } from "node:path";
@@ -87,13 +87,21 @@ async function devRemote(flags, slug) {
 	const server = await startVite(flags, { proxy: { "/_api": {
 		target: apiUrl,
 		changeOrigin: true,
-		headers: { authorization: `Bearer ${token}` },
+		headers: {
+			authorization: `Bearer ${token}`,
+			...flags.staging ? { "x-canopy-channel": "staging" } : {}
+		},
 		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");
-	console.log("   on a local copy instead: `canopy dev --local --pull`)");
-	if (tryReadCanopyJson(flags.dir)?.migrations) {
+	if (flags.staging) {
+		console.log(`\n  ${slug} — remote-first dev against the STAGING channel's data`);
+		console.log("  (live data is untouched; `canopy staging sync` re-clones it from live)");
+	} else {
+		console.log(`\n  ${slug} — remote-first dev against LIVE project data`);
+		console.log("  (worried about a risky change? `canopy db snapshot` first, or work");
+		console.log("   on a local copy instead: `canopy dev --local --pull`)");
+	}
+	if (tryReadCanopyJson(flags.dir)?.migrations && !flags.staging) {
 		console.log("  migrations apply on `canopy deploy`, never from dev — use --local");
 		console.log("  while the schema is in flux");
 	}
@@ -104,9 +112,9 @@ async function devRemote(flags, slug) {
 async function devLocal(flags, slug) {
 	let dump;
 	if (flags.pull) {
-		const { fetchProjectDump } = await import("./local-D9OVEHDg.mjs");
-		console.log(`Pulling a fresh export of ${slug}…`);
-		dump = await fetchProjectDump(slug);
+		const { fetchProjectDump } = await import("./local-C47tmhl7.mjs");
+		console.log(`Pulling a fresh export of ${slug}${flags.staging ? " [staging]" : ""}…`);
+		dump = await fetchProjectDump(slug, flags.staging ? "staging" : "live");
 	}
 	let remote;
 	try {
@@ -119,7 +127,7 @@ async function devLocal(flags, slug) {
 		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-D9OVEHDg.mjs");
+	const { createSandbox } = await import("./local-C47tmhl7.mjs");
 	const sandbox = await createSandbox({
 		slug,
 		persistDir: join(flags.dir, ".canopy", "local"),
@@ -212,18 +220,25 @@ const devCommand = defineCommand({
 			type: "boolean",
 			default: false,
 			description: "Hydrate the sandbox from a fresh prod export first (requires --local)"
+		},
+		staging: {
+			type: "boolean",
+			default: false,
+			description: "Point remote dev at the staging channel's data (or pull the staging dump with --local --pull)"
 		}
 	},
 	run: reportErrors("dev", async ({ args }) => {
 		const port = args.port === void 0 ? void 0 : Number(args.port);
 		if (port !== void 0 && !Number.isInteger(port)) throw new Error(`Invalid --port=${args.port}`);
 		if (args.pull && !args.local) throw new Error("--pull only makes sense with --local (remote dev already sees live data).");
+		if (args.staging && args.local && !args.pull) throw new Error("--staging with --local needs --pull (it selects which dump hydrates the sandbox).");
 		const { dir, slug } = resolveProject(args);
 		const flags = {
 			dir,
 			port,
 			local: args.local,
 			pull: args.pull,
+			staging: args.staging,
 			dialect: projectDialect(dir)
 		};
 		await (flags.local ? devLocal(flags, slug) : devRemote(flags, slug));

package/dist/docs/deploy.md

@@ -29,6 +29,19 @@ output directory (or the static files as-is for a `static` project):
 canopy deploy --no-build
 ```
 
+## Trying it on staging first
+
+Nervous about a change — especially one with schema migrations or backend
+code? Deploy it to the project's staging channel first, then promote the exact
+same version once it checks out:
+
+```bash
+canopy deploy --staging   # own URL, own database (a copy of live)
+canopy promote            # make that version live
+```
+
+See [Staging & promoting](https://docs.canopy.website/guides/staging).
+
 ## Rolling back
 
 Every deploy is kept, so you can instantly revert:
@@ -38,7 +51,8 @@ canopy rollback          # pick a version from history
 canopy rollback v3       # make v3 live again
 ```
 
-Rollback re-points the live version at an existing deploy — it does not rebuild.
+Rollback re-points the live version at an existing deploy — it does not
+rebuild, and the project's backend rolls back with it.
 
 ## Downloading a version
 

package/dist/docs/migrations.md

@@ -146,6 +146,23 @@ export const db = drizzle(async (sql, params, method) => {
 (On a postgres site use `drizzle-orm/pg-proxy` the same way; in a GCP project
 worker, `env.DB.query(text, params)` fits `pg-proxy` directly.)
 
+## Rehearsing on staging
+
+The safest way to try a migration is on the project's staging channel — a
+private copy of the app whose database starts as a clone of live:
+
+```bash
+canopy deploy --staging   # pending migrations apply to the STAGING database
+# … verify against the migrated copy …
+canopy promote            # the same migrations replay against live, then the version flips
+```
+
+A migration that fails on staging costs nothing; at promote time the live
+database gets its own pre-promote snapshot before anything applies.
+`canopy db migrate --staging` (and `--plan`) target the staging database
+directly, and `canopy staging sync` re-clones live when you want to rehearse
+again on fresh data. See [Staging & promoting](https://docs.canopy.website/guides/staging).
+
 ## What deliberately doesn't work
 
 - **`drizzle-kit push` / `migrate` / `studio` / `introspect`** — these need a

package/dist/docs/staging.md

@@ -0,0 +1,106 @@
+---
+title: Staging & promoting
+description: Deploy to a safe copy of your project first — own database cloned from live — then promote the exact same version.
+---
+
+Every project can have a **staging channel**: a second, private copy of the
+app with its own database (cloned from live), its own files, and its own
+backend, served at
+
+```
+https://staging-dot-<slug>.canopy.website
+```
+
+behind the same sign-in as the live site. Deploy there first, click around
+against real-shaped data, then **promote** — the exact version you tested
+becomes live, nothing is rebuilt.
+
+You don't set anything up. The first staged deploy creates the channel and
+copies the live database into it.
+
+## The workflow
+
+```bash
+canopy deploy --staging   # build + deploy to staging (created on first use)
+canopy open --staging     # check it in the browser
+canopy promote            # happy? make that version live
+```
+
+`canopy deploy --staging` is the normal deploy in every way — same build, same
+versioning — except the result serves on the staging URL and the live site is
+untouched. Versions share one sequence: if live is at v7 and you stage v8,
+promoting makes that same v8 live.
+
+`canopy promote` is not a redeploy: the platform re-uses the exact files and
+backend bundle you staged. If migrations were rehearsed on staging, they replay
+against the live database first (with an automatic snapshot), then the pointer
+flips.
+
+## Testing schema migrations
+
+This is the staging channel's superpower. Because the staging database starts
+as a copy of live, a migration that works there will behave the same way on
+the real thing:
+
+```bash
+canopy deploy --staging      # pending migrations apply to the STAGING database
+# … verify the app against the migrated copy …
+canopy promote               # the same migrations replay against live, then v goes live
+```
+
+A migration that fails on staging costs you nothing — live never saw it. See
+[Schema migrations](https://docs.canopy.website/guides/migrations) for the migration system itself.
+
+## Staging an older version
+
+Any version in the deploy history can be pointed at the staging channel —
+from the dashboard's deploy list (the **Stage** action, next to Rollback) or
+with `canopy staging use v3`. Like rollback, it's a pointer move: nothing is
+rebuilt, and live is untouched. Handy for comparing an old build against the
+staging data, or re-testing a version before promoting it.
+
+## Keeping staging fresh
+
+Staging data drifts as you test. Re-clone it from live anytime:
+
+```bash
+canopy staging sync          # replace staging data with a fresh copy of live
+canopy staging status        # what's staged vs live
+```
+
+Writes on staging never flow back to live — promote moves code and schema, not
+data.
+
+## What's shared, what's separate
+
+Separate per channel: the database, uploaded files, and the backend worker.
+Shared with live: members, secrets, the client password, schedules (they run
+against live only), and the AI budget — staging traffic counts against the
+same cap.
+
+## Developing against staging data
+
+Remote dev can point at the staging database instead of live — useful while a
+schema is in flux:
+
+```bash
+canopy dev --staging
+```
+
+## Cleaning up
+
+```bash
+canopy staging destroy       # removes the staging database, files and backend
+```
+
+Live is untouched, and the next `canopy deploy --staging` recreates the channel
+from a fresh copy. The dashboard's Settings tab has the same controls, the
+Overview tab shows what's staged with a Promote button, and a Live/Staging
+toggle above the Data and Files tabs browses either channel's data.
+
+## Staging vs version previews
+
+Version preview URLs (`v12-dot-<slug>`) show an old **frontend** against the
+**live** data — good for comparing builds. The staging channel is the full
+package: candidate frontend, candidate backend, and its own database. Use
+previews to look backwards, staging to look forwards.

package/dist/{docs-Cept8t_3.mjs → docs-2cUEug69.mjs}

@@ -1,5 +1,5 @@
-import { n as siteConfig } from "./site-DQnysZ3W.mjs";
-import { n as reportErrors } from "./ui-BhzMeKQl.mjs";
+import { n as siteConfig } from "./site-BUlQR117.mjs";
+import { n as reportErrors } from "./ui-D8HxX0Ng.mjs";
 import { defineCommand } from "citty";
 import { existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";

package/dist/index.mjs

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
-import { t as version } from "./package-D1wDsLSU.mjs";
-import { r as siteHeaderLine, t as setInvocationProfile } from "./site-DQnysZ3W.mjs";
+import { t as version } from "./package-WhBa4V15.mjs";
+import { r as siteHeaderLine, t as setInvocationProfile } from "./site-BUlQR117.mjs";
 import { i as runRefresh, r as notifyOfUpdate } from "./version-check-Cuh6HaLX.mjs";
 import { defineCommand, runMain } from "citty";
 //#region src/index.ts
@@ -73,24 +73,26 @@ const main = defineCommand({
 		description: "canopy — create and deploy vibecoded projects"
 	},
 	subCommands: {
-		login: () => import("./login-Cb8D8a1Z.mjs").then((m) => m.loginCommand),
-		whoami: () => import("./login-Cb8D8a1Z.mjs").then((m) => m.whoamiCommand),
-		logout: () => import("./login-Cb8D8a1Z.mjs").then((m) => m.logoutCommand),
-		create: () => import("./projects-CoGh8m9A.mjs").then((m) => m.createCommand),
-		init: () => import("./projects-CoGh8m9A.mjs").then((m) => m.initCommand),
-		projects: () => import("./projects-CoGh8m9A.mjs").then((m) => m.projectsCommand),
-		delete: () => import("./projects-CoGh8m9A.mjs").then((m) => m.deleteCommand),
-		dev: () => import("./dev-DV5ud7AJ.mjs").then((m) => m.devCommand),
-		deploy: () => import("./deploy-DdSSL227.mjs").then((m) => m.deployCommand),
-		rollback: () => import("./deploy-DdSSL227.mjs").then((m) => m.rollbackCommand),
-		download: () => import("./deploy-DdSSL227.mjs").then((m) => m.downloadCommand),
-		token: () => import("./token-CWgp_Lqe.mjs").then((m) => m.tokenCommand),
-		db: () => import("./db-BpnjQUkF.mjs").then((m) => m.dbCommand),
-		usage: () => import("./usage-CYQRLXwf.mjs").then((m) => m.usageCommand),
-		open: () => import("./open-BmgYBSdR.mjs").then((m) => m.openCommand),
-		docs: () => import("./docs-Cept8t_3.mjs").then((m) => m.docsCommand),
-		skill: () => import("./skill-192EdixC.mjs").then((m) => m.skillCommand),
-		upgrade: () => import("./upgrade-BrHSSg2e.mjs").then((m) => m.upgradeCommand),
+		login: () => import("./login-ByD0hcxu.mjs").then((m) => m.loginCommand),
+		whoami: () => import("./login-ByD0hcxu.mjs").then((m) => m.whoamiCommand),
+		logout: () => import("./login-ByD0hcxu.mjs").then((m) => m.logoutCommand),
+		create: () => import("./projects-CSH7KsPi.mjs").then((m) => m.createCommand),
+		init: () => import("./projects-CSH7KsPi.mjs").then((m) => m.initCommand),
+		projects: () => import("./projects-CSH7KsPi.mjs").then((m) => m.projectsCommand),
+		delete: () => import("./projects-CSH7KsPi.mjs").then((m) => m.deleteCommand),
+		dev: () => import("./dev-CvtoGFW0.mjs").then((m) => m.devCommand),
+		deploy: () => import("./deploy-BcczXlSQ.mjs").then((m) => m.deployCommand),
+		promote: () => import("./deploy-BcczXlSQ.mjs").then((m) => m.promoteCommand),
+		staging: () => import("./staging-9bvgl2B5.mjs").then((m) => m.stagingCommand),
+		rollback: () => import("./deploy-BcczXlSQ.mjs").then((m) => m.rollbackCommand),
+		download: () => import("./deploy-BcczXlSQ.mjs").then((m) => m.downloadCommand),
+		token: () => import("./token-nieJV1w7.mjs").then((m) => m.tokenCommand),
+		db: () => import("./db-BkUmbGgx.mjs").then((m) => m.dbCommand),
+		usage: () => import("./usage-qqPtkDtT.mjs").then((m) => m.usageCommand),
+		open: () => import("./open-DD9oa-Ho.mjs").then((m) => m.openCommand),
+		docs: () => import("./docs-2cUEug69.mjs").then((m) => m.docsCommand),
+		skill: () => import("./skill-Di9GQYYx.mjs").then((m) => m.skillCommand),
+		upgrade: () => import("./upgrade-CZwo05Tz.mjs").then((m) => m.upgradeCommand),
 		logs: planned("logs", "Tail worker logs", "2")
 	}
 });

package/dist/{local-D9OVEHDg.mjs → local-C47tmhl7.mjs}

@@ -1,5 +1,5 @@
-import { o as apiDataRequest } from "./ui-BhzMeKQl.mjs";
-import { n as rewriteApiPath } from "./dev-OxeYndd1.mjs";
+import { o as apiDataRequest } from "./ui-D8HxX0Ng.mjs";
+import { n as rewriteApiPath } from "./dev-DvyKHe2d.mjs";
 import { createRequire } from "node:module";
 import { existsSync, mkdirSync, readFileSync, readdirSync, rmSync, statSync, writeFileSync } from "node:fs";
 import { dirname, join, relative, sep } from "node:path";
@@ -1002,8 +1002,8 @@ function resolveSdkBundle() {
 	return bundle;
 }
 /** Downloads a fresh SQL dump of the project's production database (pull-only sync). */
-async function fetchProjectDump(slug) {
-	const { url } = await apiDataRequest("POST", "/db/export", slug);
+async function fetchProjectDump(slug, channel = "live") {
+	const { url } = await apiDataRequest("POST", "/db/export", slug, void 0, void 0, channel);
 	const download = await fetch(url);
 	if (!download.ok) throw new Error(`Dump download failed (HTTP ${download.status}).`);
 	return download.text();

package/dist/{login-Cb8D8a1Z.mjs → login-ByD0hcxu.mjs}

@@ -1,5 +1,5 @@
-import { _ as isProfileId, d as listBakedProfiles, f as readConfigFile, g as getBakedProfile, h as writeConfigFile, m as upsertProfileAuth, n as siteConfig, p as setActiveProfile, u as clearAllProfileTokens } from "./site-DQnysZ3W.mjs";
-import { n as reportErrors, t as openBrowser } from "./ui-BhzMeKQl.mjs";
+import { _ as getBakedProfile, d as clearAllProfileTokens, f as listBakedProfiles, g as writeConfigFile, h as upsertProfileAuth, m as setActiveProfile, n as siteConfig, p as readConfigFile, v as isProfileId } from "./site-BUlQR117.mjs";
+import { n as reportErrors, t as openBrowser } from "./ui-D8HxX0Ng.mjs";
 import { defineCommand } from "citty";
 import * as p from "@clack/prompts";
 import { createHash, randomBytes } from "node:crypto";

package/dist/{migrations-B0kJarjr.mjs → migrations-I1adj0z2.mjs}

@@ -1,5 +1,5 @@
-import { l as tryReadCanopyJson } from "./site-DQnysZ3W.mjs";
-import { o as apiDataRequest } from "./ui-BhzMeKQl.mjs";
+import { u as tryReadCanopyJson } from "./site-BUlQR117.mjs";
+import { o as apiDataRequest } from "./ui-D8HxX0Ng.mjs";
 import { readFileSync, readdirSync } from "node:fs";
 import { join, resolve } from "node:path";
 //#region src/migrations.ts
@@ -30,12 +30,12 @@ function readMigrationFiles(dir) {
 		sql: readFileSync(join(migrationsDir, entry.name), "utf8")
 	})).sort((a, b) => a.name < b.name ? -1 : a.name > b.name ? 1 : 0);
 }
-/** Run (or dry-run) the project's migrations against its live database. */
-function migrateProject(slug, migrations, plan = false) {
+/** Run (or dry-run) the project's migrations against a channel's database. */
+function migrateProject(slug, migrations, plan = false, channel = "live") {
 	return apiDataRequest("POST", "/db/migrate", slug, {
 		migrations,
 		plan
-	});
+	}, void 0, channel);
 }
 /** One-line-per-fact summary shared by `db migrate` and the deploy step. */
 function describeMigrateResult(result) {

package/dist/{open-BmgYBSdR.mjs → open-DD9oa-Ho.mjs}

@@ -1,5 +1,5 @@
-import { a as projectDirArgs, c as resolveProject, s as projectUrl } from "./site-DQnysZ3W.mjs";
-import { n as reportErrors, t as openBrowser } from "./ui-BhzMeKQl.mjs";
+import { a as projectDirArgs, c as resolveProject, l as stagingUrl, s as projectUrl } from "./site-BUlQR117.mjs";
+import { n as reportErrors, t as openBrowser } from "./ui-D8HxX0Ng.mjs";
 import { defineCommand } from "citty";
 //#region src/open.ts
 /**
@@ -11,10 +11,17 @@ const openCommand = defineCommand({
 		name: "open",
 		description: "Open the deployed project in your browser"
 	},
-	args: projectDirArgs,
+	args: {
+		...projectDirArgs,
+		staging: {
+			type: "boolean",
+			default: false,
+			description: "Open the staging channel instead of live"
+		}
+	},
 	run: reportErrors("open", async ({ args }) => {
 		const { slug } = resolveProject(args);
-		const url = projectUrl(slug);
+		const url = args.staging ? stagingUrl(slug) : projectUrl(slug);
 		console.log(`Opening ${url}`);
 		openBrowser(url);
 	})

package/dist/{package-D1wDsLSU.mjs → package-WhBa4V15.mjs}

@@ -1,4 +1,4 @@
 //#region package.json
-var version = "0.6.0";
+var version = "0.7.1";
 //#endregion
 export { version as t };

package/dist/{projects-CoGh8m9A.mjs → projects-CSH7KsPi.mjs}

@@ -1,5 +1,5 @@
-import { l as tryReadCanopyJson, n as siteConfig, s as projectUrl } from "./site-DQnysZ3W.mjs";
-import { c as apiRequest, i as unwrap, n as reportErrors, r as requireTty } from "./ui-BhzMeKQl.mjs";
+import { n as siteConfig, s as projectUrl, u as tryReadCanopyJson } from "./site-BUlQR117.mjs";
+import { c as apiRequest, i as unwrap, n as reportErrors, r as requireTty } from "./ui-D8HxX0Ng.mjs";
 import { defineCommand } from "citty";
 import { existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync } from "node:fs";
 import { join, relative, resolve, sep } from "node:path";

package/dist/{site-DQnysZ3W.mjs → site-BUlQR117.mjs}

@@ -175,6 +175,12 @@ function projectUrl(slug) {
 	if (apiHost === "run.app" || apiHost.endsWith(".run.app") || apiHost.startsWith("api.")) throw new Error("Cannot derive the project URL. Set projectDomain (baked profile or CANOPY_PROJECT_DOMAIN).");
 	return `https://${slug}.${apiHost.split(".").slice(-2).join(".")}`;
 }
+/** The staging channel's URL (docs/14): the first label becomes `staging-dot-<slug>`. */
+function stagingUrl(slug) {
+	const url = new URL(projectUrl(slug));
+	url.hostname = `staging-dot-${url.hostname}`;
+	return url.origin;
+}
 /** canopy.json parsed if present; undefined when the file is missing. */
 function tryReadCanopyJson(dir) {
 	let raw;
@@ -258,4 +264,4 @@ function siteHeaderLine(cliVersion) {
 	return `canopy ${cliVersion} · ${c.envOverride || !c.profileId ? c.apiUrl : `${c.profileId} (${c.projectDomain ?? new URL(c.apiUrl).hostname})`}`;
 }
 //#endregion
-export { isProfileId as _, projectDirArgs as a, resolveProject as c, listBakedProfiles as d, readConfigFile as f, getBakedProfile as g, writeConfigFile as h, projectDialect as i, tryReadCanopyJson as l, upsertProfileAuth as m, siteConfig as n, projectFlagArgs as o, setActiveProfile as p, siteHeaderLine as r, projectUrl as s, setInvocationProfile as t, clearAllProfileTokens as u };
+export { getBakedProfile as _, projectDirArgs as a, resolveProject as c, clearAllProfileTokens as d, listBakedProfiles as f, writeConfigFile as g, upsertProfileAuth as h, projectDialect as i, stagingUrl as l, setActiveProfile as m, siteConfig as n, projectFlagArgs as o, readConfigFile as p, siteHeaderLine as r, projectUrl as s, setInvocationProfile as t, tryReadCanopyJson as u, isProfileId as v };

package/dist/skill/canopy/SKILL.md

@@ -89,6 +89,8 @@ truth and never go stale.
   current directory; add `--no-scaffold` to link an app you already have.
 - Run locally: `canopy dev` (live data) or `canopy dev --local` (offline sandbox)
 - Deploy: `canopy deploy` (add `--build` if the project has a build step)
+- Test first on staging: `canopy deploy --staging` → verify → `canopy promote`
+  (own database cloned from live; `canopy staging status | sync | destroy`)
 - Roll back: `canopy rollback`
 - Open the live site: `canopy open`
 - Manage data: `canopy db pull | snapshot | snapshots | restore | migrate`
@@ -110,6 +112,10 @@ confusing failures:
   deploy; `canopy dev --local` applies to the sandbox on boot).
 - Never edit an applied migration (the platform refuses edited history) and
   never reference `_canopy_*` tables.
+- **Schema change? Rehearse it on staging.** `canopy deploy --staging` applies
+  pending migrations to the staging database (a clone of live) — verify the
+  app there, then `canopy promote` replays them against live and flips the
+  version. Never promote with failing checks.
 
 ## Choosing a starter template (`canopy create` / `canopy init`)
 

package/dist/{skill-192EdixC.mjs → skill-Di9GQYYx.mjs}

@@ -1,5 +1,5 @@
-import { t as version } from "./package-D1wDsLSU.mjs";
-import { n as reportErrors } from "./ui-BhzMeKQl.mjs";
+import { t as version } from "./package-WhBa4V15.mjs";
+import { n as reportErrors } from "./ui-D8HxX0Ng.mjs";
 import { defineCommand } from "citty";
 import { cpSync, existsSync, mkdirSync, rmSync, symlinkSync, writeFileSync } from "node:fs";
 import { join, relative } from "node:path";

package/dist/staging-9bvgl2B5.mjs

@@ -0,0 +1,155 @@
+import { c as resolveProject, l as stagingUrl, o as projectFlagArgs, s as projectUrl } from "./site-BUlQR117.mjs";
+import { c as apiRequest, i as unwrap, l as withContext, n as reportErrors, r as requireTty } from "./ui-D8HxX0Ng.mjs";
+import { defineCommand } from "citty";
+import * as p from "@clack/prompts";
+//#region src/staging.ts
+/**
+* canopy staging status | sync | destroy — the project's staging channel
+* (docs/14): its own database (a clone of live), blob prefix and backend
+* worker, served at staging-dot-<slug>.<domain>. Created lazily by
+* `canopy deploy --staging`; promoted with `canopy promote`.
+*/
+const fetchStatus = (slug) => apiRequest("GET", `/projects/${slug}/staging`);
+const stagingCommand = defineCommand({
+	meta: {
+		name: "staging",
+		description: "Staging channel: status, use, sync, destroy"
+	},
+	subCommands: {
+		status: defineCommand({
+			meta: {
+				name: "status",
+				description: "Show the staging channel's state"
+			},
+			args: projectFlagArgs,
+			run: reportErrors("staging status", async ({ args }) => {
+				const { slug } = resolveProject(args);
+				const { staging } = await fetchStatus(slug);
+				if (!staging.provisioned) {
+					console.log(`No staging channel for ${slug} — create one with \`canopy deploy --staging\`.`);
+					return;
+				}
+				console.log(`Staging: ${stagingUrl(slug)}`);
+				console.log(`  staged   v${staging.version ?? "— (nothing deployed yet)"}` + (staging.hasWorker ? " (with backend)" : ""));
+				console.log(`  live     v${staging.live ?? "—"}  ${projectUrl(slug)}`);
+				if (staging.version !== null && staging.version !== staging.live) console.log(`  \`canopy promote\` makes v${staging.version} live`);
+			})
+		}),
+		use: defineCommand({
+			meta: {
+				name: "use",
+				description: "Serve an existing version on the staging channel (pick from history)"
+			},
+			args: {
+				version: {
+					type: "positional",
+					description: "Version to stage, e.g. v3 (picked from a list when omitted)",
+					required: false
+				},
+				...projectFlagArgs
+			},
+			run: reportErrors("staging use", async ({ args }) => {
+				const { slug } = resolveProject(args);
+				let target;
+				if (args.version !== void 0) {
+					if (!/^v?\d+$/.test(args.version)) throw new Error(`Invalid version "${args.version}" — expected a number like 3 or v3.`);
+					target = Number(args.version.replace(/^v/, ""));
+				} else {
+					requireTty("pass a version, e.g. `canopy staging use v3`.");
+					const { deploys, live, staging: staged } = await apiRequest("GET", `/projects/${slug}/deploys`);
+					if (deploys.length === 0) throw new Error("This project has no deploys yet.");
+					target = unwrap(await p.select({
+						message: "Version to serve on staging",
+						options: deploys.map((deploy) => ({
+							value: deploy.version,
+							label: `v${deploy.version}  ${deploy.created_at}  (${deploy.source})`,
+							hint: deploy.version === staged ? "staged" : deploy.version === live ? "live" : void 0
+						}))
+					}));
+				}
+				const { staging: result } = await withContext(apiRequest("POST", `/projects/${slug}/deploys/${target}/stage`), {
+					action: `stage "${slug}" v${target}`,
+					fixes: {
+						staging_not_provisioned: "This project has no staging channel yet — create one in the dashboard's Settings, or with `canopy deploy --staging`.",
+						already_staged: `v${target} is already the staged version.`
+					}
+				});
+				console.log(`Staging: ${stagingUrl(slug)} (v${result.version}, was v${result.previous ?? "—"})`);
+			})
+		}),
+		sync: defineCommand({
+			meta: {
+				name: "sync",
+				description: "Re-clone the live database into staging (staging data is replaced)"
+			},
+			args: {
+				...projectFlagArgs,
+				yes: {
+					type: "boolean",
+					default: false,
+					description: "Skip the confirmation prompt"
+				}
+			},
+			run: reportErrors("staging sync", async ({ args }) => {
+				const { slug } = resolveProject(args);
+				if (!args.yes) {
+					requireTty("pass --yes to sync without confirmation.");
+					if (!unwrap(await p.confirm({ message: `Replace "${slug}"'s STAGING data with a fresh copy of live?` }))) {
+						p.cancel("Aborted.");
+						return;
+					}
+				}
+				const spin = p.spinner();
+				spin.start(`Cloning live → staging for ${slug}…`);
+				try {
+					await withContext(apiRequest("POST", `/projects/${slug}/staging/sync`), {
+						action: `sync staging for "${slug}"`,
+						fixes: { staging_not_provisioned: "This project has no staging channel yet — `canopy deploy --staging` creates one (already cloned from live)." }
+					});
+				} catch (err) {
+					spin.error("Sync failed.");
+					throw err;
+				}
+				spin.stop(`Staging database now matches live for ${slug}.`);
+			})
+		}),
+		destroy: defineCommand({
+			meta: {
+				name: "destroy",
+				description: "Tear the staging channel down (database, files, backend — live is untouched)"
+			},
+			args: {
+				...projectFlagArgs,
+				yes: {
+					type: "boolean",
+					default: false,
+					description: "Skip the type-the-slug confirmation"
+				}
+			},
+			run: reportErrors("staging destroy", async ({ args }) => {
+				const { slug } = resolveProject(args);
+				if (!args.yes) {
+					requireTty("pass --yes to destroy without confirmation.");
+					if (unwrap(await p.text({ message: `This deletes "${slug}"'s staging database, files and backend (live is untouched). Type the slug to confirm.` })).trim() !== slug) {
+						p.cancel("Aborted.");
+						return;
+					}
+				}
+				const spin = p.spinner();
+				spin.start(`Destroying staging for ${slug}…`);
+				try {
+					await withContext(apiRequest("DELETE", `/projects/${slug}/staging`), {
+						action: `destroy staging for "${slug}"`,
+						fixes: { staging_not_provisioned: "This project has no staging channel." }
+					});
+				} catch (err) {
+					spin.error("Destroy failed.");
+					throw err;
+				}
+				spin.stop(`Staging channel removed for ${slug}. \`canopy deploy --staging\` recreates it.`);
+			})
+		})
+	}
+});
+//#endregion
+export { stagingCommand };

package/dist/templates/spa/AGENTS.md

@@ -30,6 +30,10 @@ the [Canopy dashboard](https://dashboard.thanarie.dev).
   writes never reach the platform. Prefer it for destructive experiments.
 - `canopy deploy` — builds (`npm run build`) and publishes `dist/`; live
   (behind company login) at https://{{slug}}.thanarie.dev.
+- Risky change (schema migration, backend rework)? `canopy deploy --staging`
+  first — a private copy with its own database cloned from live — verify, then
+  `canopy promote` ships the exact tested version. Never promote with failing
+  checks.
 
 ## Boundaries
 

package/dist/templates/static/AGENTS.md

@@ -29,6 +29,10 @@ the [Canopy dashboard](https://dashboard.thanarie.dev).
   writes never reach the platform. Prefer it for destructive experiments.
 - `canopy deploy` — publish; live (behind company login) at
   https://{{slug}}.thanarie.dev.
+- Risky change (schema migration, backend rework)? `canopy deploy --staging`
+  first — a private copy with its own database cloned from live — verify, then
+  `canopy promote` ships the exact tested version. Never promote with failing
+  checks.
 
 ## Boundaries
 

package/dist/templates/worker/AGENTS.md

@@ -42,6 +42,10 @@ the [Canopy dashboard](https://dashboard.thanarie.dev).
 - Defining your own tables (raw `sql()` / Drizzle)? Use the migrations flow —
   `canopy docs migrations`. Never invent a `DATABASE_URL` (none exists):
   generate migrations locally, and `canopy deploy` applies them.
+- Risky change (schema migration, backend rework)? `canopy deploy --staging`
+  first — a private copy with its own database cloned from live — verify, then
+  `canopy promote` ships the exact tested version. Never promote with failing
+  checks.
 
 ## Boundaries
 

package/dist/{token-CWgp_Lqe.mjs → token-nieJV1w7.mjs}

@@ -1,5 +1,5 @@
-import { a as projectDirArgs, c as resolveProject, o as projectFlagArgs } from "./site-DQnysZ3W.mjs";
-import { c as apiRequest, n as reportErrors } from "./ui-BhzMeKQl.mjs";
+import { a as projectDirArgs, c as resolveProject, o as projectFlagArgs } from "./site-BUlQR117.mjs";
+import { c as apiRequest, n as reportErrors } from "./ui-D8HxX0Ng.mjs";
 import { defineCommand } from "citty";
 const tokenCommand = defineCommand({
 	meta: {

package/dist/{ui-BhzMeKQl.mjs → ui-D8HxX0Ng.mjs}

@@ -1,4 +1,4 @@
-import { n as siteConfig } from "./site-DQnysZ3W.mjs";
+import { n as siteConfig } from "./site-BUlQR117.mjs";
 import { spawn } from "node:child_process";
 import { cancel, isCancel } from "@clack/prompts";
 //#region src/api.ts
@@ -211,13 +211,14 @@ async function apiDownload(path) {
 * unscoped; the target project rides as X-Canopy-Project and the api. gateway
 * re-vouches it (docs/10-cli-sites.md D17).
 */
-async function apiDataRequest(method, path, projectSlug, body, rawContentType) {
+async function apiDataRequest(method, path, projectSlug, body, rawContentType, channel) {
 	const { apiUrl, token, isDeployToken } = credentials();
 	const response = await fetch(`${apiUrl}/data/v1${path}`, {
 		method,
 		headers: {
 			authorization: `Bearer ${token}`,
 			"x-canopy-project": projectSlug,
+			...channel === "staging" ? { "x-canopy-channel": "staging" } : {},
 			...body === void 0 ? {} : { "content-type": rawContentType ?? "application/json" }
 		},
 		body: body === void 0 ? void 0 : rawContentType !== void 0 ? body : JSON.stringify(body)

package/dist/{upgrade-BrHSSg2e.mjs → upgrade-CZwo05Tz.mjs}

@@ -1,5 +1,5 @@
 import { t as PACKAGE_NAME } from "./version-check-Cuh6HaLX.mjs";
-import { n as reportErrors } from "./ui-BhzMeKQl.mjs";
+import { n as reportErrors } from "./ui-D8HxX0Ng.mjs";
 import { defineCommand } from "citty";
 import { spawn } from "node:child_process";
 import { fileURLToPath } from "node:url";
@@ -112,7 +112,7 @@ const upgradeCommand = defineCommand({
 		const spec = `${PACKAGE_NAME}@${args.version ?? "latest"}`;
 		const command = pmCommand(pm);
 		const cmd = installArgs(pm, spec);
-		const { skillInstalled } = await import("./skill-192EdixC.mjs");
+		const { skillInstalled } = await import("./skill-Di9GQYYx.mjs");
 		const refreshSkill = skillInstalled(process.cwd());
 		console.log(`Upgrading via ${command}: ${command} ${cmd.join(" ")}`);
 		await run(command, cmd);

package/dist/{usage-CYQRLXwf.mjs → usage-qqPtkDtT.mjs}

@@ -1,5 +1,5 @@
-import { c as resolveProject, o as projectFlagArgs } from "./site-DQnysZ3W.mjs";
-import { c as apiRequest, l as withContext, n as reportErrors } from "./ui-BhzMeKQl.mjs";
+import { c as resolveProject, o as projectFlagArgs } from "./site-BUlQR117.mjs";
+import { c as apiRequest, l as withContext, n as reportErrors } from "./ui-D8HxX0Ng.mjs";
 import { defineCommand } from "citty";
 //#region src/usage.ts
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mediamonks/canopy-cli",
-  "version": "0.6.0",
+  "version": "0.7.1",
   "description": "Canopy CLI — create, develop and deploy Canopy projects.",
   "bin": {
     "canopy": "./dist/index.mjs"
@@ -20,8 +20,8 @@
     "esbuild": "^0.28.1",
     "hono": "^4.8.0",
     "vite-server": "npm:vite@^7",
-    "@mediamonks/canopy-data-plane": "0.0.2",
-    "@mediamonks/canopy": "0.0.3"
+    "@mediamonks/canopy": "0.0.3",
+    "@mediamonks/canopy-data-plane": "0.0.2"
   },
   "devDependencies": {
     "@types/node": "^26.1.1",

package/dist/dev-DV5ud7AJ.mjs

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