@mediamonks/canopy-cli 0.7.7 → 0.7.9

package/dist/{db-D3RKaLVU.mjs → db-8Etjmzxh.mjs}

@@ -1,6 +1,6 @@
 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-CpdtK7mt.mjs";
-import { n as migrateProject, r as readMigrationFiles, t as describeMigrateResult } from "./migrations-DpWHuqkQ.mjs";
+import { i as unwrap, n as reportErrors, o as apiDataRequest, r as requireTty, u as withContext } from "./ui-2mrJcjYC.mjs";
+import { n as migrateProject, r as readMigrationFiles, t as describeMigrateResult } from "./migrations-C-5x6SYf.mjs";
 import { defineCommand } from "citty";
 import { readFileSync, writeFileSync } from "node:fs";
 import * as p from "@clack/prompts";

package/dist/{deploy-ClioT9ZC.mjs → deploy-y75cgauK.mjs}

@@ -1,6 +1,6 @@
 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-CpdtK7mt.mjs";
-import { n as migrateProject, r as readMigrationFiles, t as describeMigrateResult } from "./migrations-DpWHuqkQ.mjs";
+import { c as apiRequest, i as unwrap, n as reportErrors, o as apiDataRequest, s as apiDownload, u as withContext } from "./ui-2mrJcjYC.mjs";
+import { n as migrateProject, r as readMigrationFiles, t as describeMigrateResult } from "./migrations-C-5x6SYf.mjs";
 import { defineCommand } from "citty";
 import { mkdtempSync, readFileSync, readdirSync, rmSync, statSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";

package/dist/dev-BYxSHUH6.mjs

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

package/dist/{dev-BbAVZcAR.mjs → dev-DtoZrexp.mjs}

@@ -1,8 +1,9 @@
 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-CpdtK7mt.mjs";
-import { r as readMigrationFiles } from "./migrations-DpWHuqkQ.mjs";
+import { a as ApiError, c as apiRequest, n as reportErrors, u as withContext } from "./ui-2mrJcjYC.mjs";
+import { r as readMigrationFiles } from "./migrations-C-5x6SYf.mjs";
 import { createRequire } from "node:module";
 import { defineCommand } from "citty";
+import { existsSync } from "node:fs";
 import { join } from "node:path";
 import { pathToFileURL } from "node:url";
 //#region src/dev.ts
@@ -15,6 +16,56 @@ function rewriteApiPath(path) {
 	return path.slice(5);
 }
 /**
+* What raw SQL through the worker's env.DB speaks (D15): the canopy.json lock
+* wins, then the engine actually answering — PGlite in the --local sandbox
+* (local.ts's default), the site's own database otherwise.
+*/
+function workerDialect(flags) {
+	if (flags.dialect !== void 0) return flags.dialect;
+	if (flags.local) return "postgres";
+	return siteConfig().cloud === "gcp" ? "postgres" : "sqlite";
+}
+/**
+* The project's own backend worker, served by the dev server the way the
+* gateway serves it in production (dev-worker.ts). Returns the plugin plus
+* the notice lines to print, or undefined when the project has no worker.
+*/
+async function workerPlugin(flags, slug) {
+	const entry = tryReadCanopyJson(flags.dir)?.worker;
+	if (entry === void 0) return void 0;
+	if (!existsSync(join(flags.dir, entry))) {
+		console.log(`note: canopy.json points "worker" at ${entry}, which does not exist — skipping.`);
+		return;
+	}
+	const { missingSecretNames, readDevVars, workerDevPlugin } = await import("./dev-worker-BZgtEM9V.mjs");
+	const secrets = readDevVars(flags.dir);
+	const email = siteConfig().email;
+	const plugin = workerDevPlugin({
+		dir: flags.dir,
+		entry,
+		slug,
+		channel: flags.staging ? "staging" : "live",
+		secrets,
+		user: email ? {
+			sub: "local-dev",
+			email,
+			name: "Local Dev"
+		} : null,
+		dialect: workerDialect(flags)
+	});
+	const notes = [`  /api/* is served by ${entry} (edit and refresh; no build step)`];
+	if (Object.keys(secrets).length > 0) notes.push(`  worker secrets from .dev.vars: ${Object.keys(secrets).sort().join(", ")}`);
+	const missing = missingSecretNames(((await apiRequest("GET", `/projects/${slug}/secrets`).catch(() => void 0))?.secrets ?? []).map((s) => s.key), Object.keys(secrets));
+	if (missing.length > 0) {
+		notes.push(`  set in the dashboard but not in .dev.vars: ${missing.join(", ")}`);
+		notes.push("  (dashboard values are never downloaded — add local ones to .dev.vars)");
+	}
+	return {
+		plugin,
+		notes
+	};
+}
+/**
 * Load Vite's `createServer`, preferring the Vite installed in the *project*
 * over the copy bundled with the CLI. `bundled` reports which one we got.
 *
@@ -43,7 +94,7 @@ async function loadCreateServer(dir) {
 		};
 	}
 }
-async function startVite(flags, serverOverrides) {
+async function startVite(flags, serverOverrides, extraPlugins = []) {
 	const { createServer, bundled } = await loadCreateServer(flags.dir);
 	const plugins = [{
 		name: "canopy-platform-api-external",
@@ -61,7 +112,7 @@ async function startVite(flags, serverOverrides) {
 	});
 	const server = await createServer({
 		root: flags.dir,
-		plugins,
+		plugins: [...plugins, ...extraPlugins],
 		server: {
 			port: flags.port,
 			...serverOverrides
@@ -84,6 +135,7 @@ function devTokenContext(slug) {
 async function devRemote(flags, slug) {
 	const { token, expires_at } = await withContext(apiRequest("POST", `/projects/${slug}/dev-token`), devTokenContext(slug));
 	const { apiUrl } = siteConfig();
+	const worker = await workerPlugin(flags, slug);
 	const server = await startVite(flags, { proxy: { "/_api": {
 		target: apiUrl,
 		changeOrigin: true,
@@ -92,7 +144,7 @@ async function devRemote(flags, slug) {
 			...flags.staging ? { "x-canopy-channel": "staging" } : {}
 		},
 		rewrite: rewriteApiPath
-	} } });
+	} } }, worker ? [worker.plugin] : []);
 	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)");
@@ -105,6 +157,7 @@ async function devRemote(flags, slug) {
 		console.log("  migrations apply on `canopy deploy`, never from dev — use --local");
 		console.log("  while the schema is in flux");
 	}
+	for (const note of worker?.notes ?? []) console.log(note);
 	console.log("");
 	server.printUrls();
 	console.log(`\n  Dev token expires ${expires_at} — restart canopy dev after that.`);
@@ -112,7 +165,7 @@ async function devRemote(flags, slug) {
 async function devLocal(flags, slug) {
 	let dump;
 	if (flags.pull) {
-		const { fetchProjectDump } = await import("./local-BHxSZwUT.mjs");
+		const { fetchProjectDump } = await import("./local-C5AhA4GM.mjs");
 		console.log(`Pulling a fresh export of ${slug}${flags.staging ? " [staging]" : ""}…`);
 		dump = await fetchProjectDump(slug, flags.staging ? "staging" : "live");
 	}
@@ -127,7 +180,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-BHxSZwUT.mjs");
+	const { createSandbox } = await import("./local-C5AhA4GM.mjs");
 	const sandbox = await createSandbox({
 		slug,
 		persistDir: join(flags.dir, ".canopy", "local"),
@@ -176,6 +229,7 @@ async function devLocal(flags, slug) {
 		headers: { authorization: `Bearer ${remote.token}` },
 		rewrite: rewriteApiPath
 	};
+	const worker = await workerPlugin(flags, slug);
 	const server = await startVite(flags, { proxy: {
 		...remoteEntry && {
 			"/_api/data/v1/ai": remoteEntry,
@@ -185,7 +239,7 @@ async function devLocal(flags, slug) {
 			target: `http://127.0.0.1:${apiAddress.port}`,
 			rewrite: (path) => path
 		}
-	} });
+	} }, worker ? [worker.plugin] : []);
 	server.httpServer?.once("close", () => {
 		apiServer.close();
 		sandbox.dispose();
@@ -197,6 +251,7 @@ async function devLocal(flags, slug) {
 	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");
 	console.log(remote ? "  ai/services pass through to the platform (metered as usual)" : "  ai/services answer 501 until you log in and restart");
+	for (const note of worker?.notes ?? []) console.log(note);
 	console.log("");
 	server.printUrls();
 }

package/dist/dev-worker-BZgtEM9V.mjs

@@ -0,0 +1,313 @@
+import { readFileSync } from "node:fs";
+import { relative, resolve, sep } from "node:path";
+//#region src/dev-worker.ts
+/**
+* Paths that belong to the worker rather than the SPA — the gateway's rule
+* (apps/gateway/src/backend.ts), kept identical so a route that works in dev
+* is reachable in production.
+*/
+function isWorkerPath(pathname) {
+	return pathname === "/api" || pathname.startsWith("/api/");
+}
+/** The manual schedule tick, mirroring the shim's own path (docs/07). */
+const SCHEDULED_PATH = "/__canopy/scheduled";
+/**
+* `.dev.vars` — local-only worker secrets, the wrangler-shaped file the repo
+* already gitignores.
+*
+* Deliberately NOT "pull the dashboard's secrets": there is no way to read a
+* stored value back (apps/api/src/routes/secrets.ts lists names and
+* timestamps only — values are AES-GCM at rest and injected into the worker
+* runtime, nowhere else), and adding one would put every project's live
+* third-party credentials on every laptop that runs `canopy dev`. North star
+* principle 3, secure by default: a dev secret is a local secret.
+*/
+function parseDevVars(text) {
+	const out = {};
+	for (const raw of text.split(/\r?\n/)) {
+		const line = raw.trim();
+		if (line === "" || line.startsWith("#")) continue;
+		const withoutExport = line.startsWith("export ") ? line.slice(7).trim() : line;
+		const eq = withoutExport.indexOf("=");
+		if (eq <= 0) continue;
+		const key = withoutExport.slice(0, eq).trim();
+		if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(key)) continue;
+		let value = withoutExport.slice(eq + 1).trim();
+		if (value.startsWith("\"") && value.endsWith("\"") && value.length >= 2 || value.startsWith("'") && value.endsWith("'") && value.length >= 2) value = value.slice(1, -1);
+		out[key] = value;
+	}
+	return out;
+}
+/** Reads `.dev.vars` from the project dir; {} when there is none. */
+function readDevVars(dir) {
+	try {
+		return parseDevVars(readFileSync(resolve(dir, ".dev.vars"), "utf8"));
+	} catch {
+		return {};
+	}
+}
+/** Dashboard secret names the local `.dev.vars` doesn't define. */
+function missingSecretNames(remote, local) {
+	const have = new Set(local);
+	return remote.filter((name) => !have.has(name)).sort();
+}
+/**
+* Port of the shim's rewriteCanopyUrl: a worker may call
+* `CANOPY.fetch("/db/todos")`, `"/data/v1/db/todos"` or the `/_api/…` form the
+* browser SDK uses — all three land on the same data-plane path.
+*/
+function rewriteCanopyUrl(raw, base) {
+	const root = base.replace(/\/$/, "");
+	let path;
+	let search = "";
+	try {
+		const url = new URL(raw, "http://canopy.local");
+		path = url.pathname;
+		search = url.search;
+	} catch {
+		path = raw.startsWith("/") ? raw : `/${raw}`;
+	}
+	if (path.startsWith("/_api/")) path = path.slice(5);
+	if (!path.startsWith("/data/v1/") && !path.startsWith("/control/v1/")) path = `/data/v1${path.startsWith("/") ? path : `/${path}`}`;
+	return root + path + search;
+}
+/**
+* env.CANOPY.fetch — the same rewriting the shim does, delivered through the
+* dev server's `/_api` mount so the running mode decides what answers.
+* Credentials stay in the proxy; nothing here carries a token.
+*/
+function createCanopyFetch(apiBase, slug, channel, fetchImpl = fetch) {
+	return async (input, init) => {
+		const url = rewriteCanopyUrl(typeof input === "string" ? input : input instanceof URL ? input.href : input.url, apiBase());
+		const headers = new Headers(input instanceof Request ? input.headers : init?.headers);
+		headers.delete("host");
+		headers.delete("x-canopy-user-sub");
+		headers.delete("x-canopy-user-email");
+		headers.delete("x-canopy-user-name");
+		headers.delete("authorization");
+		headers.delete("cookie");
+		headers.set("x-canopy-project", slug);
+		if (channel === "staging") headers.set("x-canopy-channel", "staging");
+		const method = (input instanceof Request ? input.method : init?.method) ?? "GET";
+		const body = input instanceof Request ? input.body : init?.body;
+		const outbound = {
+			method,
+			headers,
+			body: body ?? void 0,
+			redirect: input instanceof Request ? input.redirect : init?.redirect
+		};
+		if (body) outbound.duplex = "half";
+		return fetchImpl(url, outbound);
+	};
+}
+/**
+* env.DB over the data plane's raw-SQL escape hatch — the deployed worker
+* holds a direct D1/Postgres handle, which a laptop has no credential for, so
+* dev routes the same statements through `/db/sql` (the legacy uncapped shape
+* the SDK uses). Reads are identical; writes report `rowCount: 0` because that
+* shape returns rows, not a change count.
+*/
+function createDevDb(canopyFetch, dialect) {
+	return {
+		dialect,
+		query: async (text, params = []) => {
+			const response = await canopyFetch("/data/v1/db/sql", {
+				method: "POST",
+				headers: { "content-type": "application/json" },
+				body: JSON.stringify({
+					query: text,
+					params
+				})
+			});
+			if (!response.ok) {
+				const detail = await response.text();
+				throw new Error(`env.DB query failed (HTTP ${response.status}): ${detail.slice(0, 300)}`);
+			}
+			const rows = await response.json();
+			return {
+				rows,
+				rowCount: rows.length
+			};
+		}
+	};
+}
+/** env.BLOB over the data plane's blob routes, for the same reason as env.DB. */
+function createDevBlob(canopyFetch, prefix) {
+	const path = (key) => `/data/v1/blob/${encodeURIComponent(key)}`;
+	return {
+		prefix,
+		put: async (key, body, contentType) => {
+			const response = await canopyFetch(path(key), {
+				method: "PUT",
+				headers: { "content-type": contentType ?? "application/octet-stream" },
+				body
+			});
+			if (!response.ok) throw new Error(`env.BLOB put failed (HTTP ${response.status})`);
+		},
+		get: async (key) => {
+			const response = await canopyFetch(path(key));
+			if (response.status === 404) return null;
+			if (!response.ok) throw new Error(`env.BLOB get failed (HTTP ${response.status})`);
+			const contentType = response.headers.get("content-type") ?? void 0;
+			const bytes = new Uint8Array(await response.arrayBuffer());
+			return contentType ? {
+				body: bytes,
+				contentType
+			} : { body: bytes };
+		},
+		list: async (sub) => {
+			const response = await canopyFetch(`/data/v1/blob${sub ? `?prefix=${encodeURIComponent(sub)}` : ""}`);
+			if (!response.ok) throw new Error(`env.BLOB list failed (HTTP ${response.status})`);
+			return (await response.json()).map(({ key, size }) => ({
+				key,
+				size
+			}));
+		},
+		delete: async (key) => {
+			const response = await canopyFetch(path(key), { method: "DELETE" });
+			if (!response.ok) throw new Error(`env.BLOB delete failed (HTTP ${response.status})`);
+		}
+	};
+}
+/** Gateway-stamped identity, honored in dev too so a request can pose as one. */
+function userFromHeaders(headers, fallback) {
+	const sub = (headers.get("x-canopy-user-sub") ?? "").trim();
+	if (!sub) return fallback;
+	return {
+		sub,
+		email: (headers.get("x-canopy-user-email") ?? "").trim(),
+		name: (headers.get("x-canopy-user-name") ?? "").trim()
+	};
+}
+/**
+* The env object the worker sees, in the shim's own key order: secrets first,
+* platform keys after, so a stray `.dev.vars` entry can never shadow
+* `CANOPY`/`DB`/`USER` (the dashboard rejects those names outright —
+* apps/api/src/secrets.ts isReservedSecretKey).
+*/
+function buildWorkerEnv(options, request, parts) {
+	const blobPrefix = `projects/${options.slug}/`;
+	return {
+		...options.secrets,
+		CANOPY: { fetch: parts.canopyFetch },
+		DB: parts.db,
+		BLOB: parts.blob,
+		USER: userFromHeaders(request.headers, options.user),
+		PROJECT_SLUG: options.slug,
+		BLOB_PREFIX: blobPrefix,
+		CANOPY_CHANNEL: options.channel
+	};
+}
+/**
+* Host to reach the dev server on from inside this process. Vite's default
+* bind is `localhost`, which on this machine is IPv6-only — a hardcoded
+* 127.0.0.1 gets ECONNREFUSED — so the bound address decides.
+*/
+function loopbackHost(bound) {
+	if (bound === "" || bound === "::" || bound === "0.0.0.0") return "127.0.0.1";
+	return bound.includes(":") ? `[${bound}]` : bound;
+}
+/** Vite-root-relative URL for ssrLoadModule ("worker/index.ts" → "/worker/index.ts"). */
+function entryModuleId(dir, entry) {
+	return `/${relative(resolve(dir), resolve(dir, entry)).split(sep).join("/")}`;
+}
+async function toRequest(req, origin) {
+	const headers = new Headers();
+	for (const [name, value] of Object.entries(req.headers)) {
+		if (value === void 0) continue;
+		for (const one of Array.isArray(value) ? value : [value]) headers.append(name, one);
+	}
+	const method = req.method ?? "GET";
+	let body;
+	if (method !== "GET" && method !== "HEAD") {
+		const chunks = [];
+		for await (const chunk of req) chunks.push(chunk);
+		const buffer = Buffer.concat(chunks);
+		if (buffer.length > 0) body = new Uint8Array(buffer);
+	}
+	return new Request(`${origin}${req.url ?? "/"}`, {
+		method,
+		headers,
+		body
+	});
+}
+async function sendResponse(res, response) {
+	const headers = {};
+	for (const [name, value] of response.headers) headers[name] = value;
+	res.writeHead(response.status, headers);
+	res.end(Buffer.from(await response.arrayBuffer()));
+}
+/**
+* Serves the project's worker from the Vite dev server. Installed `pre` so
+* `/api/*` is answered before Vite's SPA fallback claims it — the same
+* precedence the gateway gives the worker over static assets.
+*/
+function workerDevPlugin(options) {
+	const moduleId = entryModuleId(options.dir, options.entry);
+	let apiBase = "";
+	const canopyFetch = createCanopyFetch(() => apiBase, options.slug, options.channel);
+	return {
+		name: "canopy-project-worker",
+		configureServer(server) {
+			const load = async () => {
+				const handler = (await server.ssrLoadModule(moduleId)).default;
+				if (!handler || typeof handler.fetch !== "function") throw new Error(`${options.entry} must default-export an object with fetch() (Workers shape).`);
+				return handler;
+			};
+			server.middlewares.use((req, res, next) => {
+				const path = (req.url ?? "/").split("?")[0] ?? "/";
+				const scheduled = path === SCHEDULED_PATH;
+				if (!isWorkerPath(path) && !scheduled) return next();
+				(async () => {
+					const address = server.httpServer?.address();
+					if (apiBase === "" && address != null && typeof address === "object") apiBase = `http://${loopbackHost(address.address)}:${address.port}/_api`;
+					const request = await toRequest(req, `http://${req.headers.host ?? "localhost"}`);
+					const worker = await load();
+					const env = buildWorkerEnv(options, request, {
+						canopyFetch,
+						db: createDevDb(canopyFetch, options.dialect),
+						blob: createDevBlob(canopyFetch, `projects/${options.slug}/`)
+					});
+					if (scheduled) {
+						if (req.method !== "POST") return next();
+						if (typeof worker.scheduled !== "function") {
+							await sendResponse(res, Response.json({
+								error: "no_scheduled_handler",
+								detail: "export scheduled() next to fetch"
+							}, { status: 501 }));
+							return;
+						}
+						const body = await request.json().catch(() => ({}));
+						const name = typeof body.name === "string" ? body.name : "";
+						if (!name) {
+							await sendResponse(res, Response.json({ error: "missing_name" }, { status: 400 }));
+							return;
+						}
+						env.USER = null;
+						await worker.scheduled({
+							name,
+							cron: typeof body.cron === "string" ? body.cron : "",
+							scheduledTime: typeof body.scheduledTime === "number" ? body.scheduledTime : Date.now(),
+							type: "scheduled"
+						}, env);
+						await sendResponse(res, Response.json({
+							ok: true,
+							name
+						}));
+						return;
+					}
+					await sendResponse(res, await worker.fetch(request, env));
+				})().catch((err) => {
+					if (err instanceof Error) server.ssrFixStacktrace(err);
+					console.error("worker request failed", err);
+					sendResponse(res, Response.json({
+						error: "worker_error",
+						detail: err instanceof Error ? err.message : String(err)
+					}, { status: 500 })).catch(() => res.end());
+				});
+			});
+		}
+	};
+}
+//#endregion
+export { missingSecretNames, readDevVars, workerDevPlugin };

package/dist/docs/cli-dev.md

@@ -37,6 +37,25 @@ canopy dev --local --pull       # sandbox hydrated from a fresh prod export
 
 With the lock in place, `--local` runs on an embedded SQLite engine instead — the same raw SQL, full-text search behavior, and `--pull` dumps as your deployed site. `"dialect": "postgres"` makes today's default explicit. Each engine keeps its own state under `.canopy/local/`, so switching the lock never corrupts data. The SQLite engine uses Node's built-in database and needs **Node 24+** (older Node builds lack full-text search); the CLI says so plainly if yours is older.
 
+**Your backend worker.** If `canopy.json` names a `worker` entry (the worker scaffold does), `canopy dev` serves it too: requests to `/api/*` go to your worker, everything else to the SPA — the same split the platform makes once you deploy. There's no build step; save the file and the next request runs the new code.
+
+Your worker gets the same `env` it gets in production: `env.CANOPY.fetch` for the SDK, `env.DB` and `env.BLOB` for raw database and file access, `env.USER` for the signed-in person, `env.PROJECT_SLUG`. They all follow the mode you're in — live project data by default, your sandbox under `--local`. Two differences worth knowing: `env.USER` is you (the account you logged in with), since there's no company login in front of a local server, and a write through `env.DB` reports no row count locally.
+
+To tick a schedule by hand, post its name to the same path the platform uses:
+
+```bash
+curl -X POST localhost:5173/__canopy/scheduled -d '{"name":"nightly-digest"}'
+```
+
+**Worker secrets.** Secrets you set in the dashboard are never downloaded — the platform can't hand a stored value back, and your laptop is not where a live API key belongs. Put local values in a `.dev.vars` file next to `canopy.json` instead:
+
+```
+STRIPE_KEY=sk_test_local
+SLACK_WEBHOOK="https://hooks.slack.com/services/…"
+```
+
+Your worker reads them exactly as it reads dashboard secrets (`c.env.STRIPE_KEY`). Keep `.dev.vars` out of git — the scaffolds already ignore it. At startup `canopy dev` lists the dashboard secret names your `.dev.vars` doesn't define, so you know what's still missing (names only, never values).
+
 **`--pull`.** Before the sandbox boots, the CLI requests a fresh SQL export of the project's production database and applies it locally. Sync is pull-only — nothing ever pushes back. Blobs are not pulled; the local blob store starts empty.
 
 **Schema migrations.** When `canopy.json` configures a `"migrations"` directory (see the [migrations guide](https://docs.canopy.website/guides/migrations)), the `--local` sandbox applies pending migrations on boot, so the local schema always matches the repo. Remote-first dev **never** applies migrations — it points at production, and schema changes ship with `canopy deploy`. While a schema change is in flux, work in `--local`.

package/dist/docs/cli-feedback.md

@@ -10,12 +10,16 @@ ones.
 ## Usage
 
 ```bash
-canopy feedback list --status accepted
+canopy feedback list --status investigate
 canopy feedback show <id>
 canopy feedback comment <id> "root cause: the upload grant expires too early"
+canopy feedback status <id> investigated --comment "root cause: the grant expires too early"
+canopy feedback list --status accepted
 canopy feedback status <id> resolved --comment "fixed in v42"
 canopy feedback mine
 canopy feedback report "canopy deploy exits 1 after upload" --command "canopy deploy"
+canopy feedback report "the header overlaps the logo" --attach ./shot.png
+canopy feedback attach <id> ./after-fix.png --comment "fixed — see the shot"
 ```
 
 ## Subcommands
@@ -26,26 +30,46 @@ require project membership. `list` and `show` take `--json` for
 machine-readable output.
 
 - `list [--status <s>] [--kind <k>]` — the project's inbox. Statuses:
-  `new`, `accepted`, `in_progress`, `resolved`, `declined`; kinds: `bug`,
-  `feedback`, `docs`.
-- `show <id>` — full detail: body, captured context (page URL, deploy
-  version, console errors — or CLI context), and the comment trail.
+  `investigate`, `investigated`, `accepted`, `in_progress`, `resolved`,
+  `declined`; kinds: `bug`, `feedback`, `docs`. (Reports filed before triage
+  statuses existed sit in `new`, which you can still filter for.)
+- `show <id> [--download <dir>]` — full detail: body, captured context (page
+  URL, deploy version, console errors — or CLI context), the screenshots on
+  the report, and the comment trail. `--download` saves the screenshots into
+  a directory so you can actually look at them.
 - `comment <id> <text>` — append a comment (findings, questions, updates).
+- `attach <id> <file> [--attach <more>] [--caption <text>] [--comment <text>]` —
+  add screenshots to an existing report. With `--comment`, the comment is
+  posted first and the screenshots hang off that trail entry — how you show
+  "here's what it looks like after the fix".
 - `status <id> <new-status> [--comment <note>]` — move the ticket; the
-  transition is recorded on the trail.
+  transition is recorded on the trail. Moving to `investigated` needs the
+  findings: pass `--comment`, or comment first.
 - `mine [--project <slug>] [--json]` — your own reports across all projects,
   with current statuses.
-- `report <text> [--kind bug|feedback] [--project <slug>] [--command <cmd>] [--error <output>]` —
+- `report <text> [--kind bug|feedback] [--project <slug>] [--command <cmd>] [--error <output>] [--attach <file>] [--caption <text>]` —
   file a new report. **Without `--project` it goes to the platform inbox**
   (Canopy itself) — the right target when a `canopy` command misbehaves. The
   CLI attaches its version, the active site, your platform, and the project
-  you were working in.
+  you were working in. Reports open as `investigate`; a project member may
+  pass `--status` to open one further along — `investigated` when the report
+  itself is the write-up of what you found, `accepted` when the person you are
+  working with asked for it.
 
 ## For agents
 
-The intended loop: a human marks items `accepted` on the dashboard; the agent
-runs `list --status accepted`, reproduces using the context in `show`
-(including the deploy version that served the page), comments findings, and
-resolves — or declines with a comment saying why. When a `canopy` command
-itself fails: rule out user error, check `canopy feedback mine` for a
-duplicate, then `report` with the exact command and error output.
+Two loops.
+
+**Investigate:** `list --status investigate` is everything nobody has looked at
+yet. Reproduce with the context in `show` (including the deploy version that
+served the page), then `status <id> investigated --comment "<what you found>"`.
+Stop there — say what it would take to fix and let the person decide.
+
+**Build:** `list --status accepted` is what a person has asked for. Do the
+work, then `resolve` with a note, or `declined` if it turns out to be a bad
+idea. Set `accepted` yourself only when the person you are working with told
+you to.
+
+When a `canopy` command itself fails: rule out user error, check
+`canopy feedback mine` for a duplicate, then `report` with the exact command
+and error output.

package/dist/docs/dev.md

@@ -46,6 +46,25 @@ dialect in `canopy.json` (`"dialect": "sqlite"`) and the sandbox runs an
 embedded SQLite engine instead, so the same SQL works locally and deployed —
 see [canopy dev](https://docs.canopy.website/cli/dev).
 
+## Backend worker
+
+Projects with a `worker` entry in `canopy.json` get their backend locally too:
+`/api/*` is served by your worker in both modes, with the same `env` it has in
+production (`env.CANOPY`, `env.DB`, `env.BLOB`, `env.USER`). Edit and refresh —
+there's no build step.
+
+Secrets are the one thing that doesn't come from the dashboard. Stored values
+are never downloadable, so put local ones in a `.dev.vars` file next to
+`canopy.json`:
+
+```
+STRIPE_KEY=sk_test_local
+```
+
+Your worker reads them the same way it reads dashboard secrets
+(`c.env.STRIPE_KEY`). `canopy dev` prints which dashboard secret names your
+`.dev.vars` is missing. Keep the file out of git — the scaffolds ignore it.
+
 ## Which mode should an agent use?
 
 - Iterating on UI or read-only features → `canopy dev` (live data, realistic).

package/dist/docs/overview-how-it-works.md

@@ -29,7 +29,8 @@ address exists as soon as the project does.
 Visitors to your project's URL hit OneLogin before they see anything. By
 default any Monk can open it. From the project's Settings you can tighten that
 to collaborators only, or add a shared client password so people outside Monks
-can view it. There is no "make it public" switch — that's by design.
+can view it. The password stays visible in Settings, so you can look it up and
+share it again later. There is no "make it public" switch — that's by design.
 
 ## Deploys create versions
 

package/dist/docs/platform-client-access.md

@@ -28,7 +28,8 @@ The unlock is deliberately narrow:
 
 ## Enabling it
 
-Open the project's **Settings** tab and use the **Client access** card:
+Open the project's **Settings** tab and use the **Who outside Monks can open
+it** card:
 
 1. Set a password. Pick something you're comfortable saying out loud on a
    call — it's a shared secret, not a personal credential.