@mediamonks/canopy-cli 0.7.12 → 0.7.14

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

@@ -1,6 +1,6 @@
 import { c as resolveProject, o as projectFlagArgs } from "./site-BUlQR117.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 { i as unwrap, n as reportErrors, o as apiDataRequest, r as requireTty, u as withContext } from "./ui-B1Px5y7q.mjs";
+import { n as migrateProject, r as readMigrationFiles, t as describeMigrateResult } from "./migrations-C6EcKD6a.mjs";
 import { defineCommand } from "citty";
 import { readFileSync, writeFileSync } from "node:fs";
 import * as p from "@clack/prompts";

package/dist/{deploy-B1WrPq5W.mjs → deploy-CnxJ4TE6.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, 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 { c as apiRequest, i as unwrap, n as reportErrors, o as apiDataRequest, s as apiDownload, u as withContext } from "./ui-B1Px5y7q.mjs";
+import { n as migrateProject, r as readMigrationFiles, t as describeMigrateResult } from "./migrations-C6EcKD6a.mjs";
 import { defineCommand } from "citty";
 import { mkdtempSync, readFileSync, readdirSync, rmSync, statSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";

package/dist/dev-BqLvttKc.mjs

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

package/dist/{dev-BnUYGQQm.mjs → dev-CyJT6EfQ.mjs}

@@ -1,6 +1,6 @@
 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, n as reportErrors, u as withContext } from "./ui-2mrJcjYC.mjs";
-import { r as readMigrationFiles } from "./migrations-C-5x6SYf.mjs";
+import { a as ApiError, c as apiRequest, n as reportErrors, u as withContext } from "./ui-B1Px5y7q.mjs";
+import { r as readMigrationFiles } from "./migrations-C6EcKD6a.mjs";
 import { createRequire } from "node:module";
 import { defineCommand } from "citty";
 import { existsSync } from "node:fs";
@@ -165,7 +165,7 @@ async function devRemote(flags, slug) {
 async function devLocal(flags, slug) {
 	let dump;
 	if (flags.pull) {
-		const { fetchProjectDump } = await import("./local-BGRd_FMZ.mjs");
+		const { fetchProjectDump } = await import("./local-BQxsp-ZQ.mjs");
 		console.log(`Pulling a fresh export of ${slug}${flags.staging ? " [staging]" : ""}…`);
 		dump = await fetchProjectDump(slug, flags.staging ? "staging" : "live");
 	}
@@ -180,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-BGRd_FMZ.mjs");
+	const { createSandbox } = await import("./local-BQxsp-ZQ.mjs");
 	const sandbox = await createSandbox({
 		slug,
 		persistDir: join(flags.dir, ".canopy", "local"),

package/dist/docs/ci.md

@@ -0,0 +1,50 @@
+---
+title: CI and deploy tokens
+description: Push-to-main deploys using a project-scoped deploy token.
+---
+
+Interactive `canopy login` is for humans at a terminal. For automated deploys
+(GitHub Actions, etc.) use a **deploy token**: a project-scoped credential that
+can deploy that one project and nothing else.
+
+## Create a token
+
+From inside the project directory:
+
+```bash
+canopy token create --name "GitHub Actions"
+```
+
+This prints the token **once** — copy it immediately and store it as a CI secret
+(e.g. `CANOPY_DEPLOY_TOKEN`). It is not shown again.
+
+Manage tokens:
+
+```bash
+canopy token list
+canopy token revoke <id>
+```
+
+## Use it in CI
+
+The CLI picks up `CANOPY_DEPLOY_TOKEN` from the environment and uses it instead
+of an interactive login. A minimal GitHub Actions step:
+
+```yaml
+- run: npm install -g @mediamonks/canopy-cli
+- 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 — 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-create.md

@@ -0,0 +1,46 @@
+---
+title: canopy create
+description: Register a new project on Canopy and scaffold it locally from a starter template.
+---
+
+`canopy create` is the start of every new project: it registers the project on Canopy (claiming its slug and live URL) and scaffolds a runnable starter into `./<slug>/`. Everything is prompted for interactively, or passable as flags for scripted use.
+
+## Usage
+
+```bash
+canopy create                             # fully interactive
+canopy create "My Portfolio" --slug my-portfolio --template spa
+canopy create existing-app --no-scaffold  # register only, no files written
+```
+
+## Arguments & flags
+
+- `<name>` — the project's display name. Multi-word names work unquoted (every positional joins the name). Prompted for when omitted on a TTY.
+- `--slug <slug>` — the URL slug; the project will live at `https://<slug>.<site-domain>`. Lowercase letters, digits and dashes only. Defaults to a slugified version of the name (prompted on a TTY).
+- `--template <id>` — starter to scaffold: `static` (plain HTML/CSS/JS, no build step, untyped SDK from the platform — simplest apps), `spa` (Vite + React + TypeScript with the typed SDK from npm — best for real SDK use or growth), or `worker` (`spa` plus a backend worker in `worker/` — for server-side code: secrets, schedules, calling external APIs). A picker appears when omitted on a TTY; `static` is the default otherwise.
+- `--scaffold` / `--no-scaffold` — whether to write `./<slug>/` from the template. When neither is given, the CLI scaffolds unless the current directory already has a `canopy.json` (in which case it assumes you're registering an existing app and only registers).
+- `--profile <site>` — global flag (or `CANOPY_PROFILE`): which site to create the project on. The chosen profile is pinned into the scaffolded `canopy.json`.
+
+## How it works
+
+The project is registered with the platform first — this is what reserves the slug and creates the entry you'll see in `canopy projects` and the dashboard. Taken, reserved, or invalid slugs fail here with an actionable error, before anything touches disk.
+
+With scaffolding on, the CLI then copies the template into `./<slug>/` (refusing if that directory already exists), substituting the name and slug into the files, and writes a `canopy.json` containing the slug and the profile pin. Templates ship a README, an `AGENTS.md`, and a `.gitignore`; the `spa` template also needs an `npm install` before `canopy dev`. With `--no-scaffold`, nothing is written — an existing `canopy.json` is left untouched, and you're told to add one if the directory has none.
+
+The live URL is printed at the end, but it only serves content after your first `canopy deploy`.
+
+## Examples
+
+```bash
+canopy create
+```
+
+Walks you through name, slug, and template, registers the project, and scaffolds a ready-to-run starter with next steps printed.
+
+```bash
+canopy create "Team Retro Board" --slug retro-board --template spa
+```
+
+Registers `retro-board`, scaffolds a React SPA into `./retro-board/`, and tells you to `npm install` then `canopy dev`.
+
+To set up a local folder for a project that already exists on Canopy, use [canopy init](https://docs.canopy.website/cli/init) instead. See also [canopy projects](https://docs.canopy.website/cli/projects) and [canopy delete](https://docs.canopy.website/cli/delete).

package/dist/docs/cli-db.md

@@ -0,0 +1,86 @@
+---
+title: canopy db
+description: Pull, snapshot, list, restore, and migrate a project's database from the terminal.
+---
+
+`canopy db` is the data-safety toolbox: export the project database as SQL, store restorable snapshots server-side, restore from either, and apply schema migrations. The project comes from `canopy.json` in the current directory, or from `--project <slug>` on any subcommand.
+
+The habit that makes restores safe: **always `canopy db snapshot` before `canopy db restore`**. A restore replaces everything, and a snapshot taken seconds earlier is your undo button.
+
+## Usage
+
+```bash
+canopy db pull [--out <file>] [--project <slug>]
+canopy db snapshot [--project <slug>]
+canopy db snapshots [--project <slug>]
+canopy db restore [file.sql] [--snapshot <key>] [--yes] [--project <slug>]
+canopy db migrate [--plan] [--project <slug>]
+```
+
+All subcommands accept `--project <slug>` (overrides `canopy.json` in the
+current directory), and `--staging` to operate on the
+[staging channel's](https://docs.canopy.website/guides/staging) database instead of live — its snapshots
+live in their own history, and `db migrate --staging` is the migration
+rehearsal.
+
+### canopy db pull
+
+Downloads a fresh SQL dump of the project database to a local file.
+
+- `--out <file>` — output path. Defaults to `<slug>-<timestamp>.sql` in the current directory.
+
+The platform exports the database and hands the CLI a download URL; the CLI fetches it and writes the file, reporting its size. Use this for local inspection, ad-hoc backups, or as input to a later `db restore`.
+
+### canopy db snapshot
+
+Stores a dump **server-side**, restorable anytime from the CLI or the dashboard. No flags beyond `--project`. On success it prints the snapshot key and size, plus the exact `canopy db restore --snapshot <key>` command to bring it back. Take one before every restore, schema experiment, or bulk data change.
+
+### canopy db snapshots
+
+Lists stored snapshots for the project — one line per snapshot with its key, size, and creation time. If there are none yet, it points you at `canopy db snapshot`.
+
+### canopy db restore
+
+Replaces **all** current project data from a snapshot or a local `.sql` file.
+
+- `[file.sql]` — positional: a local SQL dump to restore from.
+- `--snapshot <key>` — a server-side snapshot key to restore from instead.
+- `--yes` — skip the confirmation (default `false`).
+
+Behavior:
+
+1. With neither a file nor `--snapshot`, and on an interactive terminal, it fetches the stored snapshots and lets you pick one. On a non-TTY you must pass a source explicitly.
+2. Unless `--yes` is passed, it asks you to **type the project slug** to confirm — a deliberate speed bump, since restore is destructive. A non-TTY without `--yes` errors instead of guessing.
+3. The chosen snapshot or file replaces the entire database, and the CLI confirms `Restored <slug>.`
+
+### canopy db migrate
+
+Applies pending schema migrations to the project's **live** database, without deploying. Requires a `"migrations"` directory in `canopy.json` (for example your `drizzle-kit generate` output — see the [migrations guide](https://docs.canopy.website/guides/migrations)).
+
+- `--plan` — dry run: lists what would apply, touches nothing.
+
+Migration files are ordered `.sql` files, applied in filename order and journaled in the database, so each file applies exactly once. The platform stores an automatic **pre-migrate snapshot** before applying anything — a botched migration is one `canopy db restore` away. Files that were already applied must not be edited afterwards (write a new migration instead); the platform refuses edited history.
+
+Normally you won't run this yourself: `canopy deploy` applies pending migrations automatically so schema and code ship together. `canopy db migrate` exists for applying schema changes without a deploy, and for CI.
+
+## Examples
+
+```bash
+canopy db snapshot && canopy db pull
+```
+
+Belt and braces before risky work: a server-side snapshot you can restore from the dashboard, plus a local dump on disk.
+
+```bash
+canopy db restore --snapshot snap-2026-08-11-1200 --yes --project my-app
+```
+
+Non-interactive restore (for scripts): restores the named snapshot into `my-app` without the typed confirmation — only sensible right after taking it.
+
+```bash
+canopy db restore seed.sql
+```
+
+Loads a local dump — for example a seed file — after the type-the-slug confirmation.
+
+See also the [Data guide](https://docs.canopy.website/guides/data) and [Project data](https://docs.canopy.website/platform/project-data) for how the database, snapshots, and blobs fit together.

package/dist/docs/cli-delete.md

@@ -0,0 +1,44 @@
+---
+title: canopy delete
+description: Permanently delete a Canopy project — its deploys, database, and files.
+---
+
+`canopy delete` removes a project from Canopy entirely: the live site stops serving, and its deploy history, database, and stored files are torn down. It is not a pause or an archive — there is no undo, and nothing to restore from afterwards.
+
+## Usage
+
+```bash
+canopy delete my-project
+canopy delete my-project --yes   # skip the confirmation (scripts/agents)
+canopy delete                    # pick from a list of your projects
+```
+
+## Arguments & flags
+
+- `<slug>` — the project to delete. When omitted on a TTY, you pick from a list of projects you can actually delete (deleting is owner-level: owners see their own projects, admins see all).
+- `--yes` — skip the type-the-slug confirmation. Required on non-interactive runs; use with care, since it removes the last safeguard.
+- `--profile <site>` — global flag (or `CANOPY_PROFILE`): sites are independent, so make sure you're deleting on the site you mean. Deleting a project on `main` does not touch a same-named project on `staging`.
+
+## Details
+
+Without `--yes`, the CLI asks you to **type the slug back exactly** to confirm; anything else aborts with no changes. On a non-TTY, omitting `--yes` (or the slug) is an error rather than a hang.
+
+Once confirmed, the platform tears the project down completely: the project itself, its deploys (so rollback targets are gone too), its database, and its uploaded files. Your local project directory is **not** touched — the code on disk survives, only the platform side is destroyed. That local copy is your only remaining artifact, so if you might want the data later, pull a database snapshot first.
+
+Only project owners (and site admins) can delete; the platform refuses the request otherwise.
+
+## Examples
+
+```bash
+canopy delete old-prototype
+```
+
+Prompts you to type `old-prototype` to confirm, then tears the project down and prints a success line.
+
+```bash
+canopy delete scratch-test --yes --profile staging
+```
+
+Deletes without prompting — the pattern for cleaning up scratch projects in scripts, made explicit about which site it hits.
+
+See also [canopy projects](https://docs.canopy.website/cli/projects) to find slugs, and [Project data](https://docs.canopy.website/platform/project-data) for what a project stores.

package/dist/docs/cli-deploy.md

@@ -0,0 +1,58 @@
+---
+title: canopy deploy
+description: Build the project and push a new version live, from your machine or from CI.
+---
+
+`canopy deploy` builds your project (if `canopy.json` defines a build command), uploads the output directory, and makes the new version live at the project's URL. It's the same command whether you run it by hand or from a CI runner with a deploy token.
+
+## Usage
+
+```bash
+canopy deploy                       # build, upload, go live
+canopy deploy --no-build            # deploy the output directory as-is
+canopy deploy --project my-app ./out
+```
+
+## Arguments & flags
+
+- `[dir]` — project directory (defaults to the current directory).
+- `--project <slug>` — project slug, overriding `canopy.json`. With `--project`, a `canopy.json` is optional — you can deploy any static directory; when one exists it still supplies `build` and `dist`.
+- `--build` / `--no-build` — run the `canopy.json` build command first (default on). Use `--no-build` when the output is already built, e.g. a CI step that built earlier.
+- `--migrate` / `--no-migrate` — apply pending schema migrations before the new version goes live (default on; only does anything when `canopy.json` configures a `"migrations"` directory — see the [migrations guide](https://docs.canopy.website/guides/migrations)).
+- `--staging` — deploy to the project's [staging channel](https://docs.canopy.website/guides/staging) instead of live: created on first use with a copy of the live database, served at `staging-dot-<slug>`, promoted with [canopy promote](https://docs.canopy.website/cli/promote). Pending migrations apply to the _staging_ database (the rehearsal). Not to be confused with `--profile staging`, which picks a whole different site.
+- `--profile <site>` / `CANOPY_PROFILE` — which site to deploy to (`main`, `staging`, …). Always pass it explicitly when the target matters; a `canopy.json` profile pin is the fallback.
+
+## How it works
+
+1. **Build.** If `canopy.json` has a `build` command and you didn't pass `--no-build`, it runs in the project directory with your shell; a non-zero exit aborts the deploy.
+2. **Collect files.** Everything under the `dist` directory from `canopy.json` (default: the project directory itself) is gathered, skipping `canopy.json`, `README.md`, `AGENTS.md`, `CLAUDE.md`, `.gitignore`, `.DS_Store`, and any dot-directories plus `.git`, `node_modules`, and `.claude`. An empty or missing output directory is an error.
+3. **Bundle the backend (if any).** When `canopy.json` names a `worker` entry, that backend code is bundled into a single file (dependencies included) and ships in the same version as the static files — frontend and backend always move together.
+4. **Upload.** The files upload in parallel; the new version is staged alongside the old one, so the live site keeps serving until everything has arrived.
+5. **Migrate (if configured).** With a `"migrations"` directory in `canopy.json`, pending schema migrations apply now — after the bundle is staged, before the version flips — so the incoming code never runs against the old schema. The platform stores an automatic pre-migrate snapshot first. If a migration fails, the deploy aborts and the live version is unchanged; the error names the snapshot to restore if needed.
+6. **Go live.** The platform validates the staged version and switches the site over to it in one step. The upload must contain an `index.html` at the top level — the deploy is rejected otherwise — so double-check `dist` points at the folder that actually holds `index.html`. On success the CLI prints the live URL and version number (plus the backend service URL for worker projects).
+
+Deploys are versioned and immutable: nothing overwrites an old version, so [canopy rollback](https://docs.canopy.website/cli/rollback) can always take you back.
+
+**CI.** Set the `CANOPY_DEPLOY_TOKEN` environment variable to a project-scoped deploy token (from [canopy token create](https://docs.canopy.website/cli/token)) and `canopy deploy` works with no `canopy login` — the token can deploy exactly one project and nothing else. Deploys from GitHub Actions are tagged with their source in the deploy history.
+
+## Examples
+
+```bash
+canopy deploy
+```
+
+From a project directory: runs the build from `canopy.json`, uploads the `dist` output, and prints the live URL with the new version number.
+
+```bash
+canopy deploy --profile staging
+```
+
+Same project, deployed to the staging site instead of the profile pinned in `canopy.json`.
+
+```bash
+CANOPY_DEPLOY_TOKEN=cnpy_… canopy deploy --no-build
+```
+
+A CI step deploying already-built output with a deploy token — no interactive login involved.
+
+See also [canopy rollback](https://docs.canopy.website/cli/rollback), [canopy token](https://docs.canopy.website/cli/token), the [deploy guide](https://docs.canopy.website/guides/deploy), and [CI setup](https://docs.canopy.website/guides/ci).

package/dist/docs/cli-dev.md

@@ -0,0 +1,82 @@
+---
+title: canopy dev
+description: Run your project locally with a Vite dev server, against live platform data or a local sandbox.
+---
+
+`canopy dev` starts a Vite dev server for the project directory and wires up `/_api` so the SDK works exactly as it does in production. By default it's remote-first: your local pages talk to the **live** platform API and see the same data the deployed app sees. When you'd rather experiment on a disposable copy, `--local` swaps in a sandbox on your machine.
+
+## Usage
+
+```bash
+canopy dev                      # remote-first: live project data
+canopy dev --local              # local sandbox: your data stays on your machine
+canopy dev --local --pull       # sandbox hydrated from a fresh prod export
+```
+
+## Arguments & flags
+
+- `[dir]` — project directory (defaults to the current directory). Needs a `canopy.json` unless you pass `--project`.
+- `--project <slug>` — project slug, overriding the `canopy.json` in the target directory.
+- `--port <n>` — dev server port (Vite picks one when omitted).
+- `--local` — use the local-data sandbox instead of live data. Default off.
+- `--pull` — hydrate the sandbox from a fresh export of the project's production database first. Only valid with `--local`; the command errors otherwise (remote dev already sees live data).
+- `--staging` — point remote dev at the [staging channel's](https://docs.canopy.website/guides/staging) data instead of live (the safe remote target while a schema is in flux), or, with `--local --pull`, hydrate the sandbox from the staging dump.
+- `--profile <site>` / `CANOPY_PROFILE` — which site the dev token and API calls target. Projects usually pin a profile in `canopy.json`.
+
+## How it works
+
+**Remote-first (default).** The CLI mints a short-lived, project-scoped dev token from the platform, then starts Vite with a proxy: every `/_api/*` request is forwarded to the real platform API with that token attached. The token stays inside the proxy — browser code never holds a credential. When the token expires (the expiry is printed at startup), restart `canopy dev`. Because you're on live data, the startup banner suggests `canopy db snapshot` before risky changes, or switching to `--local --pull`.
+
+**Local sandbox (`--local`).** Database, file, and auth requests are answered entirely on your machine, from a sandbox stored under `.canopy/local/` in the project directory — no database to install, and writes never reach the platform. The sandbox behaves the same as the real API, so code that works locally works deployed. Two things still go remote: `ai` and `services` calls go through to the real platform (metered as usual) when you're logged in — fully offline, they return errors until you log in and restart.
+
+**Matching your site's SQL dialect.** The document API (`canopy.db.collection(…)`) behaves identically everywhere, but raw `canopy.db.sql()` speaks the deployment target's dialect — SQLite on Cloudflare-backed sites, Postgres on GCP-backed ones (see [dialect()](https://docs.canopy.website/guides/data)). The sandbox defaults to Postgres. If your project uses raw SQL written for a SQLite site, lock the dialect in `canopy.json`:
+
+```json
+{ "slug": "my-project", "dialect": "sqlite" }
+```
+
+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`.
+
+A few practical notes:
+
+- If your project ships its own Vite (the spa and worker scaffolds do), `canopy dev` uses that install and merges your `vite.config`; the `/_api` proxy always wins. The no-build static scaffold falls back to the CLI's bundled Vite.
+- If the slug in `canopy.json` isn't registered on Canopy (or your account can't access it), the dev-token lookup fails with instructions to either fix the slug or create the project in the dashboard.
+
+## Examples
+
+```bash
+canopy dev
+```
+
+Serves the current directory and proxies `/_api` to the live project — good for day-to-day work where you want real data.
+
+```bash
+canopy dev --local --pull --port 3000
+```
+
+Pulls a fresh copy of production data into `.canopy/local/`, then serves the app on port 3000 against that copy — safe for destructive experiments.
+
+See also [canopy deploy](https://docs.canopy.website/cli/deploy) and the [local development guide](https://docs.canopy.website/guides/dev).

package/dist/docs/cli-docs.md

@@ -0,0 +1,47 @@
+---
+title: canopy docs
+description: Read the Canopy docs from the terminal — live from the platform, with offline fallbacks.
+---
+
+`canopy docs` lists and prints the full Canopy documentation in the terminal — the same content as this site, section by section: the overview, the guides, the platform pages, and the CLI and SDK references. It's built for agents and humans alike: the content is served live by the platform so it never goes stale, but the command still works offline and before you've ever signed in.
+
+## Usage
+
+```bash
+canopy docs                 # list all topics
+canopy docs <topic>         # print one topic
+canopy docs <topic> --refresh
+```
+
+## Arguments & flags
+
+- `[topic]` — positional: the topic slug to print. Omit it to list every topic with a one-line summary, grouped by section. Guides keep bare slugs (`deploy`, `staging`); other sections prefix theirs (`sdk-database`, `cli-deploy`, `platform-schedules`).
+- `--refresh` — re-fetch from the platform, bypassing the local cache. Default `false`.
+
+## How it works
+
+Content resolves in a fixed fallback order:
+
+1. **Platform** — fetched live (topics are cached for an hour; `--refresh` forces a fetch). Requests carry your CLI token or `CANOPY_DEPLOY_TOKEN` when one exists, since platform docs require a login.
+2. **Local cache** — `~/.canopy/docs-cache/`, filled by every successful platform fetch.
+3. **Bundled snapshot** — a copy of the docs shipped inside the CLI package itself.
+
+That last step is why `canopy docs` works with no network and no login: a fresh install always has the bundled snapshot, and it only gets fresher from there. Fetches time out after a few seconds and fall through silently, so a flaky connection degrades to slightly older docs rather than an error.
+
+Asking for an unknown topic errors with the list of available slugs. Everything prints as plain Markdown to stdout, so it pipes cleanly into a pager or an agent's context.
+
+## Examples
+
+```bash
+canopy docs
+```
+
+Lists every topic with its summary — the starting point when you're not sure which guide covers what you're doing.
+
+```bash
+canopy docs deploy --refresh
+```
+
+Prints the deploy guide, guaranteed fresh from the platform rather than the hour-old cache.
+
+See also [canopy skill](https://docs.canopy.website/cli/skill), which teaches coding agents to reach for `canopy docs` on their own.

package/dist/docs/cli-download.md

@@ -0,0 +1,42 @@
+---
+title: canopy download
+description: Download the deployed files of any version of a project as a zip archive.
+---
+
+`canopy download` fetches the exact files a deploy is serving — the live version by default, or any version from the history — and writes them to a zip on your machine. Useful for recovering a project whose source you've lost, auditing what's actually live, or diffing two versions.
+
+## Usage
+
+```bash
+canopy download                     # the live version (or pick from history)
+canopy download v3                  # a specific version
+canopy download --project my-app --out backup.zip
+```
+
+## Arguments & flags
+
+- `[version]` — the deploy version to download, as `3` or `v3`. Optional: on an interactive terminal you get a picker over the deploy history with the live version preselected; on a non-TTY run the live version is taken automatically (an error if the project has no live version — pass one explicitly).
+- `--out <file>` — output file path. Defaults to `<slug>-v<version>.zip` in the current directory.
+- `--project <slug>` — project slug, overriding `canopy.json` in the target directory.
+- `--dir <path>` — project directory (defaults to the current directory).
+- `--profile <site>` / `CANOPY_PROFILE` — which site to download from.
+
+## How it works
+
+The CLI resolves the target version (argument, picker, or live), asks the platform for that deploy's assets as a zip, and writes the archive to `--out`. The zip contains the deployed bundle as uploaded — the static files, and for worker projects the bundled `_canopy/worker.mjs`. It does not include files [canopy deploy](https://docs.canopy.website/cli/deploy) skips (like `canopy.json` itself), nor your project's database or blobs — those are handled by the data tooling, not deploy versions. A project with no deploys yet has nothing to download.
+
+## Examples
+
+```bash
+canopy download
+```
+
+From a project directory: pick a version from history (live preselected) and get e.g. `my-app-v5.zip` next to you, with the written size reported.
+
+```bash
+canopy download v2 --project legacy-site --out /tmp/legacy-v2.zip
+```
+
+Grabs version 2 of another project without needing its directory, writing to an explicit path — handy before comparing it against what's live now.
+
+See also [canopy deploy](https://docs.canopy.website/cli/deploy), [canopy rollback](https://docs.canopy.website/cli/rollback), and [Deploys & rollbacks](https://docs.canopy.website/platform/deploys-and-rollbacks).

package/dist/docs/cli-egress.md

@@ -0,0 +1,37 @@
+---
+title: canopy egress
+description: Manage which outbound hosts the project's backend worker may fetch.
+---
+
+`canopy egress` manages the project's outbound-host allowlist. Worker `fetch`
+calls to hosts outside the list are denied (`egress_denied`) — see
+[Outbound requests](https://docs.canopy.website/platform/egress).
+
+## Usage
+
+```bash
+canopy egress list
+canopy egress allow api.example.com
+canopy egress allow "*.googleapis.com"
+canopy egress remove api.example.com
+```
+
+## Arguments & flags
+
+All subcommands resolve the project the usual way — `canopy.json` in the
+target directory, or `--project <slug>` to override — and honor the global
+`--profile <site>` / `CANOPY_PROFILE`.
+
+- `list` — print the allowed hosts, one per line.
+- `allow <host>` — add a hostname (or `*.` subdomain wildcard; quote it so the
+  shell doesn't expand the `*`).
+- `remove <host>` — remove an entry (as shown by `list`).
+
+## How it works
+
+The list lives on the platform, per project, shared by the live and staging
+channels — deliberately **not** in `canopy.json`, so a repo file can never
+widen egress silently on deploy. Changes re-roll the running workers
+immediately; no deploy is needed. Entries are validated server-side: bare
+hostnames or `*.` wildcards only, no IPs, ports, schemes, or paths, at most 32
+entries.

package/dist/docs/cli-feedback.md

@@ -0,0 +1,85 @@
+---
+title: canopy feedback
+description: Read and triage a project's feedback inbox, or file a bug/feedback report — against a project or against Canopy itself.
+---
+
+`canopy feedback` is the CLI side of [Feedback & bug reports](https://docs.canopy.website/platform/feedback):
+agents (and humans) pull reports, append findings, move statuses, and file new
+ones.
+
+## Usage
+
+```bash
+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
+
+Inbox commands (`list`, `show`, `comment`, `status`) resolve the project the
+usual way — `canopy.json` in the target directory, or `--project <slug>` — and
+require project membership. `list` and `show` take `--json` for
+machine-readable output.
+
+- `list [--status <s>] [--kind <k>]` — the project's inbox. Statuses:
+  `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> [--internal]` — append a comment (findings, questions,
+  updates). `--internal` (members only) keeps the note off the reporter's
+  view — for stack traces, table names, and other working detail that would
+  only confuse them.
+- `attach <id> <file> [--attach <more>] [--caption <text>] [--comment <text>] [--internal]` —
+  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". `--internal` makes that comment a
+  members-only note, screenshots included.
+- `status <id> <new-status> [--comment <note>]` — move the ticket; the
+  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>] [--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. 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
+
+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.
+
+Split your findings by audience: the status comment is what the **reporter**
+reads, so keep it plain ("the upload fails for files over 5 MB — looking into
+it"). The tech-loaded version — stack traces, table names, reproduction
+queries — goes in `comment <id> "<detail>" --internal`, which only project
+members see. An internal note counts as findings for `investigated`.
+
+**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.