@mediamonks/canopy-cli 0.7.12 → 0.7.14

package/dist/docs/platform-feedback.md

@@ -0,0 +1,119 @@
+---
+title: Feedback & bug reports
+description: A built-in feedback widget on every project, a ticket-lite inbox behind it, and a CLI that lets agents work the backlog.
+---
+
+Every Canopy project gets an in-app feedback channel without writing a line of
+code: signed-in Monks see a small floating button on the live app, pick **Bug**
+or **Feedback**, type what happened, and send. The report lands in the
+project's **Feedback tab** on the dashboard, with everything an investigator
+needs captured automatically — page URL, the deploy version that served it,
+viewport, and recent console errors.
+
+It is deliberately **not** a ticketing product: an item has a status, an
+append-only comment trail, and nothing else. No assignees, priorities, or
+boards.
+
+## The widget
+
+- Appears only for **signed-in Monks**. Client-password visitors never see it —
+  the platform doesn't even send them the script.
+- On by default for every project. Turn it off per project in
+  **Settings → Feedback widget**; the change applies on the next page load.
+- Submissions are always identified (your company sign-in), so there's no
+  anonymous spam and no reporter field to fill in.
+- The widget also shows your own previous reports for that project with their
+  current status.
+- A page can reshape the chooser with meta tags — this docs site does exactly
+  that: `<meta name="canopy-feedback-kinds" content="docs,feedback">` swaps
+  "Bug" for "Docs issue", and `canopy-feedback-prompt` replaces the textarea
+  placeholder. Kinds are limited to `bug`, `feedback`, `docs`.
+
+## Screenshots
+
+A screenshot is often the whole report, so you can attach up to six to any
+report:
+
+- **In the widget:** click **Attach screenshot**, or paste one straight from
+  the clipboard into the message box, or drop an image on the panel. Thumbnails
+  show what will be sent, and each one can be removed before you hit Send.
+- **On the dashboard:** the same three ways, from the report itself — so you can
+  add a picture to a report after filing it, or to a comment as you write it
+  ("here's what it looks like after the fix"). Click any thumbnail for the full
+  image, then use the arrow keys to page through the rest.
+- **From the CLI:** `canopy feedback report "…" --attach ./shot.png`, or
+  `canopy feedback attach <id> ./after-fix.png` for a report that already
+  exists. `canopy feedback show <id> --download <dir>` saves a report's
+  screenshots so an agent can look at them.
+
+PNG, JPEG, WebP and GIF, up to 5 MB each. Large screenshots are scaled down in
+your browser before they're sent, so a full-screen retina capture goes up small
+without you doing anything. Screenshots are visible to the same people as the
+report itself, and are deleted with it.
+
+## The inbox
+
+Project members triage reports on the **Feedback tab**:
+
+- Statuses: `investigate → investigated → accepted → in_progress → resolved`,
+  plus `declined`.
+- Everything arrives as **investigate** — nobody has looked at it yet. An agent
+  can pick those up, work out what is actually going on, and write the findings
+  on the report as **investigated**.
+- **`accepted` means a person said "build this."** It is the one status an
+  agent should never reach for on its own.
+- The order is a suggestion, not a track. Accept something straight away, skip
+  the investigation, or decline it at any point.
+- Every status change and comment is recorded on the item's trail.
+- A comment can be marked **internal** (the toggle next to the comment box):
+  visible to project members and admins only, never the reporter. That's the
+  place for stack traces, query plans, and other working notes that would only
+  confuse the person who filed the report — screenshots attached to an
+  internal note stay internal too.
+- Reporters follow their submissions on the **Reports page** (dashboard
+  header) and can comment on or withdraw their own items; only project
+  members change statuses.
+
+## Working the backlog with an agent
+
+Because the CLI exposes the inbox, "look into the new reports" and "work
+through the accepted feedback" are both prompts, not processes:
+
+```bash
+canopy feedback list --status investigate      # what nobody has looked at yet
+canopy feedback show <id>                      # body + captured context + trail
+canopy feedback status <id> investigated \
+  --comment "root cause: the upload grant expires too early"
+canopy feedback list --status accepted         # what a person asked for
+canopy feedback status <id> resolved --comment "fixed in v42"
+```
+
+`investigated` always carries the findings — the note is required, because a
+report that claims someone looked into it and shows nothing is worse than an
+untouched one. Then it waits: **accepting is the person's call**, so an agent
+sets `accepted` only when the person it is working with says to build the
+thing.
+
+`show` includes the deploy version that served the page when the bug was
+reported — reproduce against that, not whatever is live now. A report worth
+pushing back on gets `status <id> declined` with a comment saying why.
+
+## Reporting problems with Canopy itself
+
+When a `canopy` command fails while you (or your agent) are building a
+project, file it against the **platform inbox** — not your own project:
+
+```bash
+canopy feedback report "deploy failed after upload" \
+  --command "canopy deploy --staging" --error "upload_grant_expired …"
+```
+
+With no `--project`, the report goes to the platform team automatically, with
+your CLI version, site, and the project you were working on attached. Before
+filing: rule out user error first (`canopy docs troubleshooting`,
+`vp env doctor` for toolchain issues), and skim `canopy feedback mine` to
+avoid filing the same issue twice.
+
+## CLI reference
+
+See [canopy feedback](https://docs.canopy.website/cli/feedback) for every subcommand and flag.

package/dist/docs/platform-google.md

@@ -0,0 +1,213 @@
+---
+title: Google
+description: Let your project work with Google data — Sheets, Docs, Calendar, Drive, Gmail — without handling any OAuth yourself.
+---
+
+Your project can work with Google data in two different ways, and the
+difference matters: as **the project's own account**, or as **each visitor's
+own account**.
+
+Either way there is no OAuth setup to do. No Cloud project, no consent screen,
+no client ID or secret, no redirect URLs, no tokens to store or refresh. Canopy
+holds all of that.
+
+## The project's own account
+
+The owner connects one Google account on the project's **Services** tab and
+picks what it may do. Everything the project sends to Google then happens as
+that account — including scheduled jobs that run when nobody is signed in. A
+shared team account is usually a better choice than a personal one.
+
+This account is **only usable from your backend code**:
+
+```ts
+// in your worker
+const doc = await canopy.google.project().fetch("https://docs.googleapis.com/v1/documents/<id>");
+```
+
+Pages cannot use it at all. That is deliberate: it is one person's real
+account, and anything a page can call, any visitor can call from their browser
+console. When your pages need something from it, put a route in your backend
+that returns just that — you decide what to expose.
+
+> **Note:** Only the project owner can connect or disconnect this account.
+
+## Each visitor's own account
+
+Visitors can connect their own Google account to your project, and your pages
+can then work with _their_ data — their calendar, their documents. They consent
+themselves, and it only ever acts as them.
+
+First, on the **Services** tab, tick what your app is allowed to ask visitors
+for. Your app can never request more than that.
+
+Then, from your pages:
+
+```ts
+const google = canopy.google.user();
+
+// On load: has this visitor connected, and what came back from a connect?
+const result = google.consumeConnectResult(); // toast this, if not null
+const status = await google.status();
+
+if (!status.connected) {
+  // A full-page trip to Google, then straight back to this page.
+  google.connect(["calendar"]);
+}
+
+const events = await google.fetch(
+  "https://www.googleapis.com/calendar/v3/calendars/primary/events",
+);
+```
+
+`connect()` leaves the page, so put the button somewhere without unsaved work.
+When the visitor comes back, `status()` is the reliable answer to "are they
+connected" — `consumeConnectResult()` just tells you how the trip that _just_
+happened went, so you can show a message.
+
+Google asks the visitor for exactly the permissions you passed. Nothing your
+project holds elsewhere carries over into what they see.
+
+Your backend can use a visitor's connection too, while handling that visitor's
+request — same `canopy.google.user()`, same account. It cannot in a scheduled
+job, because then nobody is signed in.
+
+> **Note:** Visitors need a Monks account to connect. People visiting with a project password cannot connect
+> their own Google account.
+
+## What a connection can reach
+
+Permissions are grouped by product — Sheets, Docs, Slides, Calendar, Drive,
+Gmail, Directory, Tasks, Forms, Meet — and most come in a reading and a
+read-and-write form. Pick the narrowest that does the job: a page that shows a
+spreadsheet wants **read spreadsheets**, not read and write.
+
+A few are narrower than they first look, and are usually the right answer —
+the full list is below:
+
+| Instead of               | Consider                                                                                   |
+| ------------------------ | ------------------------------------------------------------------------------------------ |
+| Read and write events    | **Availability only** — find free slots without seeing what any meeting is                 |
+| Read and write events    | **Its own calendar** — a separate calendar your project owns, never touching the account's |
+| Files this project makes | **Its own config folder** — a hidden folder nothing else can see                           |
+
+A call to anything that wasn't ticked is refused before it reaches Google, and
+so is a write using a reading-only permission.
+
+Drive is deliberately limited to files your project created or that someone
+explicitly opened with it — connecting Drive does not expose a whole Drive.
+
+### Wider permissions
+
+A few permissions read broadly across an account — a whole mailbox, meeting
+recordings. Those are switched off until a Canopy admin unlocks them for your
+project, and the picker shows them greyed out with the reason. Ask if you need
+one. Others are listed as _under consideration_: they exist, we haven't opened
+them yet.
+
+## Every permission
+
+Grouped the way the picker groups them. Pick the narrowest row that does
+the job — most products offer a reading-only version, and a write using a
+reading-only permission is refused before it reaches Google.
+
+**Sheets**
+
+| Permission                  | What it allows                                              |
+| --------------------------- | ----------------------------------------------------------- |
+| Read spreadsheets           | Read spreadsheets the account can open. Cannot change them. |
+| Read and write spreadsheets | Read and change spreadsheets the account can open.          |
+
+**Docs**
+
+| Permission               | What it allows                                           |
+| ------------------------ | -------------------------------------------------------- |
+| Read documents           | Read documents the account can open. Cannot change them. |
+| Read and write documents | Read and change documents the account can open.          |
+
+**Slides**
+
+| Permission                   | What it allows                                               |
+| ---------------------------- | ------------------------------------------------------------ |
+| Read presentations           | Read presentations the account can open. Cannot change them. |
+| Read and write presentations | Build and change presentations the account can open.         |
+
+**Calendar**
+
+| Permission                                   | What it allows                                                                      |
+| -------------------------------------------- | ----------------------------------------------------------------------------------- |
+| Availability only                            | See when the account is free or busy, never what the meetings are.                  |
+| Read events                                  | Read events on the account's calendars. Cannot change them.                         |
+| Read and write events                        | Read and manage events on the account's calendars.                                  |
+| Its own calendar                             | A separate calendar this project creates and owns. Never touches the account's own. |
+| Manage all calendars _(under consideration)_ | Full control of every calendar, including creating and deleting them.               |
+
+**Drive**
+
+| Permission                                    | What it allows                                                                |
+| --------------------------------------------- | ----------------------------------------------------------------------------- |
+| Files this project makes                      | Create files, and reopen the ones this project made or someone picked for it. |
+| Its own config folder                         | A hidden folder only this project can see. Invisible in the account's Drive.  |
+| Recordings and transcripts **(wider access)** | Read the recordings and transcripts Meet saved to Drive.                      |
+| Read the whole Drive _(under consideration)_  | Read and download every file the account can see.                             |
+| Read all file names _(under consideration)_   | Names and metadata of every file the account can see, without contents.       |
+| Full Drive access _(under consideration)_     | Read, change and delete every file the account can see.                       |
+
+**Gmail**
+
+| Permission                                     | What it allows                                                   |
+| ---------------------------------------------- | ---------------------------------------------------------------- |
+| Send mail                                      | Send mail as the account. Cannot read the mailbox.               |
+| Read mail **(wider access)**                   | Read the account's mail. Cannot send, change or delete anything. |
+| Read and organise mail _(under consideration)_ | Read, label and archive mail. Cannot permanently delete.         |
+
+**Directory**
+
+| Permission                                        | What it allows                                                       |
+| ------------------------------------------------- | -------------------------------------------------------------------- |
+| Look people up                                    | Search the organisation's directory for colleagues.                  |
+| Read personal contacts                            | Read the account's own contacts.                                     |
+| Read org users and groups _(under consideration)_ | Admin view of every user and group. Only works for Workspace admins. |
+
+**Tasks**
+
+| Permission           | What it allows                     |
+| -------------------- | ---------------------------------- |
+| Read tasks           | Read the account's task lists.     |
+| Read and write tasks | Create, change and complete tasks. |
+
+**Forms**
+
+| Permission          | What it allows                                           |
+| ------------------- | -------------------------------------------------------- |
+| Read form structure | Read a form's questions and settings, not its responses. |
+| Build forms         | Create and change forms.                                 |
+| Read responses      | Read what people submitted. Often personal information.  |
+
+**Meet**
+
+| Permission                  | What it allows                                             |
+| --------------------------- | ---------------------------------------------------------- |
+| Meetings this project makes | Create meeting links and read details of the ones it made. |
+
+## When a connection stops working
+
+Google grants end on their own sometimes: someone changes their password,
+removes Canopy from their account permissions, or the connection sits unused
+for six months. Calls then fail asking for a reconnect. For the project's
+account, the owner reconnects on the Services tab; for a visitor's, show the
+connect button again. Nothing else needs changing.
+
+Disconnecting also tells Google the grant is over, so access stops immediately
+rather than lingering. Visitors can drop their own connection with
+`canopy.google.user().disconnect()`.
+
+## Local development
+
+`canopy dev` uses the real connections, so Google works the same on your
+machine as in production — including with `--local`. There is nothing to set up
+locally, and no localhost URLs to register.
+
+Because it is real, calls in development touch real data. Sending mail really
+sends it. If that matters, connect a test account on your project's staging
+channel and develop against that.

package/dist/docs/platform-members-and-access.md

@@ -0,0 +1,71 @@
+---
+title: Members & access
+description: Everything on Canopy sits behind Monks sign-in. Collaborators manage a project; other Monks can view the live app — unless you tighten it.
+---
+
+Nothing on Canopy is reachable by the anonymous internet. Every project URL
+and the dashboard itself sit behind Monks OneLogin — visitors sign in with
+their company account before they see anything. On top of that wall, each
+project has its own roster that decides who can _manage_ it and, optionally,
+who can _view_ it.
+
+## The default: any Monk can look, members can manage
+
+Out of the box:
+
+- **Any signed-in Monk** can open a project's live URL and see the app. The
+  project also appears in the company-wide list on the dashboard.
+- **Only the project's members** (and platform admins) can open its
+  management pages — deploy history, data browser, usage, and settings.
+
+That default fits most internal work: colleagues can try what you built, but
+nobody outside the team can touch its data or settings.
+
+## Roles
+
+- **Owner** — the person who created the project. Owners govern it: they
+  invite and remove collaborators, change access settings, and can delete
+  the project.
+- **Collaborator** — invited teammates. They can do day-to-day work — deploy,
+  roll back, browse and edit data, manage schedules and secrets — but not
+  delete the project or manage its roster.
+- **Platform admin** — can manage any project from the dashboard. Admins keep
+  governance access, but they do not silently bypass a collaborators-only
+  live app (see below).
+
+## Inviting collaborators
+
+Open the project's **Settings** tab and use the **Collaborators** card. A
+searchable people picker finds anyone who has signed in to Canopy; adding
+them takes effect immediately. Owners (and admins) can also remove people
+from the same card.
+
+## Collaborators-only mode
+
+Sometimes "any Monk can look" is too open — payroll prototypes, sensitive
+client work, unfinished things you'd rather not demo by accident. Flip on
+**Settings → Who at Monks can open it → Restrict to collaborators** and the
+live app is limited to the project's roster:
+
+- Other Monks who open the URL get a clear "limited to its collaborators"
+  page instead of the app.
+- The project still appears in the company list — it isn't hidden, just
+  closed.
+- Platform admins can still manage the project in the dashboard, but they
+  must add themselves as collaborators if they need to open the live app.
+- [Client password access](https://docs.canopy.website/platform/client-access), if you've enabled
+  it, is unaffected — the two controls are independent.
+
+Turning it off again is the same toggle.
+
+> **Note:** Collaborators-only gates the **live app**. Management access (settings, data, deploys) is always
+> members-only, regardless of this toggle.
+
+## Platform admins and the Users page
+
+Platform admins get an extra **Users** page in the dashboard listing everyone
+on Canopy — name, email, and when they first signed in — with a one-click way
+to grant or remove admin. Accounts are created automatically on first
+OneLogin sign-in; there is nothing to provision.
+
+- [Client access](https://docs.canopy.website/platform/client-access) — Share work-in-progress with clients who don't have a Monks account.

package/dist/docs/platform-project-data.md

@@ -0,0 +1,76 @@
+---
+title: Project data
+description: Every project gets its own private database and file storage — browse it in the dashboard, snapshot it before risky changes, and pull it locally.
+---
+
+Every Canopy project comes with its own private database and file storage,
+created automatically the moment the project exists. There are no connection
+strings to configure and no servers to run — your app reads and writes through
+the Canopy SDK, and no other project can ever see your data.
+
+## The Data tab and the data explorer
+
+Open a project in the dashboard and the **Data** tab shows what your app has
+stored — every collection and table at a glance — plus the door into the
+**data explorer**, a full-page workspace for actually digging in:
+
+- **Schema sidebar** — collections and tables, each expandable to its
+  columns (types, primary keys) and indexes.
+- **Browse** — click any table or collection to page through it with real
+  totals, sort by any column, and stack filters (equals, contains,
+  comparisons, null checks) without writing SQL. Click a row for the full
+  record, JSON pretty-printed. Export the current page as CSV or JSON.
+- **SQL console** — a real editor with syntax highlighting and autocomplete
+  fed by your schema. Run with <kbd>⌘⏎</kbd>, see row counts and timing,
+  recall earlier queries from history, and hit **Explain** to see the query
+  plan.
+
+The console is **read-only by default** — the platform rejects anything but
+reads until you flip the writes toggle, so exploring production data is safe
+by design. The explorer is fixed to the channel (live or staging) you opened
+it from; to look at the other one, go back to the Data tab and switch there.
+
+The **Files** tab next to it lists the project's blob storage — the uploads
+and files your app has saved.
+
+## Snapshots and restores
+
+The Data tab's **Data safety** card is your undo button for data:
+
+- **Snapshot** stores a full dump of the database on the platform. Take one
+  before a risky change — a big import, a cleanup script, letting an agent
+  loose on production data.
+- **Restore** replaces the project's current data with a snapshot. This is
+  destructive by design (that's the point), so the dashboard asks you to
+  confirm.
+- **Export** downloads a dump to your machine.
+
+Snapshots live server-side and stay available until you delete the project,
+so you can restore from days ago, not just from your last session.
+
+> **Warning:** Restoring replaces **all** current data with the snapshot's contents. Take a fresh snapshot first
+> if there's anything recent you might want back.
+
+## The same tools from the terminal
+
+Everything above is also available to you (and your coding agent) via the CLI:
+
+```bash
+canopy db pull        # download a fresh SQL dump
+canopy db snapshot    # store a dump server-side
+canopy db snapshots   # list stored snapshots
+canopy db restore     # replace project data with a snapshot
+```
+
+`canopy db pull` is also how you develop against realistic data: pull a dump,
+then run `canopy dev --local --pull` for a throwaway sandbox seeded with it.
+
+## Portable by default, SQL when you need it
+
+The SDK's document API (`canopy.db.collection(...)`) behaves the same
+everywhere Canopy runs. Raw SQL via `canopy.db.sql()` passes straight through
+to the underlying database — SQLite on the Cloudflare sites, Postgres on the
+GCP pilot — so anything that database supports works. Your code can ask
+`canopy.db.dialect()` which one it's talking to.
+
+- [Working with project data](https://docs.canopy.website/guides/data) — Collection naming rules, dialects and raw SQL, dumps, and restore workflows in depth.

package/dist/docs/platform-schedules.md

@@ -0,0 +1,90 @@
+---
+title: Schedules
+description: Run named cron jobs in your project's backend — configured in the dashboard, so you can change the cadence without redeploying.
+---
+
+Schedules let a project do things on a clock: send a daily digest, refresh a
+cache every hour, tick a counter every minute. You define **named jobs** in
+the dashboard, and the platform wakes your project's backend at the right
+times — your code only decides what each job does.
+
+> **Note:** Schedules need a project with a custom backend. Per-project backends run on the **main** site and
+> the **GCP pilot** site. On sites without backend support the Schedules section doesn't appear in
+> Settings, and the API answers `not_supported_on_target`.
+
+## Defining a schedule
+
+In the dashboard, open the project's **Settings → Schedules**. Each schedule
+has:
+
+- a **name** (like `daily-digest`) — this is what your code switches on;
+- a **cron expression** — standard 5-field cron, always in **UTC**;
+- an **enabled** toggle, so you can pause a job without deleting it.
+
+A project can have up to **5 schedules**, and the shortest interval is one
+minute. Each row also shows its last run and, if it failed, the error — so
+you can see at a glance whether a job is healthy.
+
+You can also trigger a schedule manually from the dashboard, which is the
+quickest way to test a handler without waiting for the clock.
+
+## Handling schedules in your code
+
+Your project's worker exports a `scheduled` handler next to its normal
+`fetch` handler, and switches on the job's name:
+
+```ts
+export default {
+  async fetch(request, env, ctx) {
+    return app.fetch(request, env, ctx);
+  },
+
+  async scheduled(event, env, ctx) {
+    switch (event.name) {
+      case "daily-digest":
+        await sendDigest(env);
+        break;
+      default:
+        console.warn("unknown schedule", event.name);
+    }
+  },
+};
+```
+
+`event.name` is the name you gave the schedule in the dashboard, `event.cron`
+is the expression that fired, and `event.scheduledTime` is when it fired.
+Inside the handler your code has the same environment as an HTTP request —
+secrets, the project database, and blob storage all work the same way.
+
+## Data access without a signed-in user
+
+A scheduled run has no browser session attached, but `canopy.db`, `canopy.blob`
+and `canopy.ai` still work: the platform seals a **project-scoped worker
+token** into your backend on every deploy, and calls through the platform
+fall back to it whenever the request carries no user credential. You don't
+configure or see this token — it's minted, rotated (every deploy replaces
+it), and revoked with the project automatically, and it only ever reaches
+your own project's data.
+
+The one thing that behaves differently is identity: `canopy.auth.user()`
+resolves with `kind: "worker"` and empty `id`/`email`/`name` — there is no
+one signed in during a cron tick, and your code should treat that as "no
+user", not as an error.
+
+## Why the name matters
+
+Switch on `event.name`, not on the cron string. The dashboard is the source
+of truth for _when_ a job runs, so you can change `daily-digest` from 6:00 to
+7:30 — or pause it — without touching code or redeploying. The name is the
+stable contract between the dashboard and your handler.
+
+## Things to know
+
+- **Cron runs as the project, not as a person.** Data access works (see
+  above), but there is no signed-in user — `auth.user()` answers with
+  `kind: "worker"` and no identity.
+- **All times are UTC.** `0 6 * * *` is 6:00 UTC, not local time.
+- **Failures are visible.** A run that throws records its error on the
+  schedule row in Settings, so silent breakage doesn't stay silent.
+
+- [Infrastructure](https://docs.canopy.website/guides/infrastructure) — What runs where — assets, backends, databases — across the Canopy sites.

package/dist/docs/platform-sites-and-profiles.md

@@ -0,0 +1,61 @@
+---
+title: Sites & profiles
+description: Canopy runs as more than one installation. Most people only ever use main — here's what the others are and how the CLI keeps them straight.
+---
+
+Canopy isn't a single installation: the same platform runs as a few separate
+**sites**, each with its own domain, its own projects, and its own data.
+Unless someone told you otherwise, **you're on `main` and can stop reading
+here** — the rest of this page explains what the other sites are for and how
+the CLI targets them.
+
+## The sites
+
+| Site        | Project URLs          | What it's for                                     |
+| ----------- | --------------------- | ------------------------------------------------- |
+| `main`      | `*.canopy.website`    | The real platform. Your projects live here.       |
+| `staging`   | `*.thanarie.dev`      | The platform team's testbed for platform changes. |
+| `gcp-pilot` | `*.canopy.monks.zone` | A pilot running on Google Cloud.                  |
+
+Sites are fully separate: a project on `main` doesn't exist on `staging`, and
+signing in to one doesn't create anything on another. They can also differ in
+what they support — the dashboard simply hides features a site can't honor,
+and the API says `not_supported_on_target` if asked directly.
+
+## What a profile is
+
+A **profile** is the CLI's name for a site. `canopy login` signs you in once
+via OneLogin and stores a credential for every site in one go; the profile
+just picks which one a command talks to.
+
+Three things decide the effective profile, in order:
+
+1. `--profile <id>` on the command (or the `CANOPY_PROFILE` environment
+   variable) — one-off override.
+2. The `"profile"` pinned in the project's `canopy.json` — set when the
+   project was created, so a checkout always targets the site it belongs to.
+3. Your default active profile — `main` unless you chose otherwise at login.
+
+Every command prints the site it's talking to in its header line, and
+`canopy whoami` shows your email, active profile, and API host — so there's
+never a mystery about where a deploy just went.
+
+```bash
+canopy whoami                          # who am I, on which site?
+canopy --profile gcp-pilot deploy      # one command against the pilot
+```
+
+## When you'd actually care
+
+- **Never, usually.** Day-to-day work on your own projects is all `main`,
+  and the `canopy.json` pin keeps it that way without any flags.
+- **Trying backend features.** Custom backends and
+  [schedules](https://docs.canopy.website/platform/schedules) currently run on `gcp-pilot`, so
+  experiments with those happen there.
+- **Helping test platform changes.** If the platform team asks you to check
+  something on `staging`, `--profile staging` points any command at it.
+
+> **Note:** Deploying to a different site publishes a **separate copy** of the project there — it doesn't move
+> or mirror the one on `main`. Each site keeps its own versions, data, and members.
+
+- [CLI reference](https://docs.canopy.website/guides/cli) — Every canopy command, including login, whoami, and the --profile flag.