@mediamonks/canopy-cli 0.7.5 → 0.7.7

package/dist/docs/overview-use-cases.md

@@ -0,0 +1,76 @@
+---
+title: Use cases
+description: What kinds of projects belong on Canopy — and which ones should live somewhere else.
+---
+
+Canopy is built for many small projects, not one big one. It shines when you
+want to get an idea in front of colleagues or a client quickly, with real data
+and real AI behind it, without asking anyone to set up infrastructure.
+
+## Good fits
+
+**Client-facing prototypes.** You're pitching a concept and want the client to
+click through something real, not a slide deck. Build it with your agent,
+deploy it, and share the link with a project password — the client sees a
+working app without needing a Monks account, and nobody else on the internet
+can.
+
+**Internal tools.** A small utility your team needs: a content checker, a
+campaign asset tracker, a review queue. It sits behind Monks sign-in
+automatically, saves its data to its own database, and stays available without
+anyone babysitting a server.
+
+**Demos and experiments with AI.** You want to show what a model can do with
+your workflow — a summarizer, a brief generator, a chat over project material.
+Canopy gives the project AI access with a hard spend cap, so an enthusiastic
+demo (or a runaway loop) can never turn into a scary bill.
+
+**Microsites that need data or uploads.** A small site for a workshop, an
+internal survey, a moodboard collector. Structured data and file uploads work
+through simple calls — no database setup, and uploaded files are never left
+publicly exposed.
+
+**Projects with client or project data.** Canopy projects may hold real client
+material. Each project's data is isolated — its own database, its own storage
+space — and everything sits behind sign-in, so work-in-progress with real
+content is a normal use, not an exception.
+
+### A few concrete scenarios
+
+- A strategist vibecoding a pitch prototype over a weekend, sharing it Monday
+  behind a client password.
+- A producer building a tracker the whole team uses daily, with teammates
+  invited as collaborators.
+- A developer prototyping an AI-assisted workflow with a custom backend,
+  scheduled jobs, and secrets — still inside platform auth and budgets.
+
+## Not a fit
+
+Canopy has deliberate anti-goals. If your project is one of these, it belongs
+on another platform from day one:
+
+- **Public production apps.** Nothing on Canopy is reachable without OneLogin
+  or a project password. A public marketing site, a consumer app, or anything
+  meant for anonymous visitors can't live here.
+- **Apps that need production guarantees.** There are no SLAs, no autoscaling,
+  no multi-region hosting. If downtime would be a real incident, you need
+  dedicated hosting.
+- **Arbitrary server stacks.** Canopy is not a general-purpose cloud — no
+  bring-your-own database, no arbitrary long-running servers or containers.
+  Projects use the platform's building blocks.
+- **Data pipelines and integration hubs.** Canopy can talk to existing internal
+  services, but it's not the place where data warehousing or pipelines live.
+
+> **Note:** The rule of thumb: Canopy is the greenhouse, not the forest. When a project proves itself and
+> needs scale, guarantees, or a public audience, it graduates — exporting its code, database, and
+> files cleanly to dedicated hosting.
+
+## Not sure?
+
+If your project mostly needs to be seen by Monks or a specific client, saves a
+modest amount of data, and would benefit from shipping this week instead of
+this quarter — it's probably a Canopy project. If in doubt, start on Canopy;
+graduation is a supported path, not a rewrite.
+
+- [What is Canopy?](https://docs.canopy.website/overview/what-is-canopy) — The platform in plain language — who it's for and what's managed.
+- [FAQ](https://docs.canopy.website/overview/faq) — Who can see my project, what happens when a deploy breaks, and more.

package/dist/docs/overview-what-is-canopy.md

@@ -0,0 +1,75 @@
+---
+title: What is Canopy?
+description: A fully managed home for vibecoded Monks projects — hosting, sign-in, data, files, and AI, all set up before your first prompt.
+---
+
+Canopy is where Monks put the projects they vibecode with AI tools. You describe
+an idea, your AI agent builds it, and Canopy runs it — with sign-in, a database,
+file storage, and AI access already wired up and safe before you write (or
+prompt) a single line.
+
+Think of it as a greenhouse: a protected place where small projects can grow
+quickly. When one proves its value, it can graduate to its own dedicated home —
+nothing is trapped here.
+
+## Who it's for
+
+Canopy serves two kinds of builders on one platform:
+
+- **Vibers** — producers, designers, PMs, and strategists who build with AI
+  agents. The platform is your guardrail: you can't accidentally publish
+  something to the open internet, leak a file, or run up a runaway AI bill,
+  because the safe path is the only path.
+- **Coders** — developers who want the same paved road (auth, database, storage
+  arranged for them) plus escape hatches like raw SQL and their own backend
+  code when they need more control.
+
+If you can prompt an AI coding agent, you can ship on Canopy.
+
+## What "fully managed" means
+
+You never touch infrastructure. The platform team owns and operates everything
+behind the scenes, so for you it looks like this:
+
+- **Hosting.** Every project gets its own web address on `canopy.website`. You
+  don't set up servers, domains, or certificates.
+- **Sign-in, always on.** Every project sits behind Monks OneLogin
+  automatically. Any Monk can open it by default; you can tighten access to
+  collaborators only, or add a shared password so clients without a Monks
+  account can see work-in-progress. Nothing on Canopy is ever truly public.
+- **Data and files.** Each project has its own private database and file
+  storage. No tables to design, no migrations, no connection strings — and no
+  other project can see your data.
+- **AI with guardrails.** Projects can talk to the major AI models through the
+  platform, with a hard spend cap per project and full visibility of what
+  you've spent.
+- **Deploys.** Putting a new version online is one step — from the terminal,
+  from the dashboard, or automatically when code lands in your repository. Every
+  deploy becomes a version you can preview and roll back to.
+
+> **Note:** Curious how a project moves from idea to live URL? See [How it works](https://docs.canopy.website/overview/how-it-works).
+
+## What you need to get access
+
+- **A Monks account.** You sign in to everything — the dashboard and every
+  project — with OneLogin. Your Canopy account is created automatically the
+  first time you sign in.
+- **The dashboard.** [dashboard.canopy.website](https://dashboard.canopy.website)
+  is where you see your projects, invite teammates, browse data, check usage,
+  and manage settings.
+- **The Canopy CLI (optional but usual).** A small command-line tool your AI
+  agent uses to create, preview, and deploy projects. The
+  [getting started guide](https://docs.canopy.website/guides/getting-started) walks you through
+  installing it and connecting your coding agent — the agent does most of the
+  typing for you.
+
+## What Canopy is not
+
+Canopy is deliberately not a production hosting platform. There are no uptime
+guarantees, no autoscaling, and nothing reachable by the anonymous public
+internet. Projects that outgrow the greenhouse graduate: they export cleanly
+(code, database, files) and move to dedicated hosting. See
+[Use cases](https://docs.canopy.website/overview/use-cases) for what belongs here and what doesn't.
+
+- [How it works](https://docs.canopy.website/overview/how-it-works) — The life of a project, from creation to rollback, in plain words.
+- [Getting started](https://docs.canopy.website/guides/getting-started) — Install the CLI, sign in, and ship your first project.

package/dist/docs/platform-ai-usage.md

@@ -0,0 +1,65 @@
+---
+title: AI access & usage
+description: Projects talk to AI models through the platform — no API keys to manage, a hard daily budget per project, and full visibility of spend.
+---
+
+Canopy projects can call AI models without you ever handling an API key. The
+platform routes every request through its own metered gateway, tracks what
+each project spends, and enforces a hard daily budget — so a runaway loop in
+a vibecoded app becomes a capped bill and a visible chart, not a surprise
+invoice.
+
+## What your app gets
+
+The SDK exposes AI as a first-class building block:
+
+```ts
+const reply = await canopy.ai.chat({
+  messages: [{ role: "user", content: "Summarize this note…" }],
+});
+```
+
+- **No keys in your code.** Requests authenticate as the project; the
+  platform holds the provider credentials.
+- **A curated model list.** Each site enables a set of models
+  (`provider/model`, e.g. `anthropic/claude-haiku-4-5`) with a sensible
+  default — ask for a model outside the list and the API tells you what _is_
+  available.
+- **Streaming** via `canopy.ai.chatStream()` for chat-style UIs.
+- **An OpenAI-compatible endpoint.** `canopy.ai.endpoint()` returns a base
+  URL and model list you can plug into ecosystem tools (like the Vercel AI
+  SDK) — same key handling, same budget, same tracking.
+
+## The daily budget
+
+Every project has a daily AI budget in USD. When a project's spend for the
+day crosses it, further AI calls answer with an `ai_budget_exceeded` error
+until the day rolls over. The budget is enforced from the same spend ledger
+the dashboard displays, so what you see and what's enforced can never
+disagree.
+
+> **Note:** Hitting the cap doesn't break the rest of your app — pages, data, and files keep working. Only AI
+> calls pause until the next day.
+
+## The Usage tab
+
+Open a project in the dashboard and the **Usage** tab shows where it stands:
+
+- **LLM spend** — estimated cost, request count, and tokens over the recent
+  window, broken down by model and by day.
+- **Activity** — page loads today and over the last 7 days, plus when the
+  project was last visited. A quick answer to "is anyone actually using
+  this?"
+- **Storage & deploys** — database size, blob storage footprint, and how many
+  versions have shipped.
+
+## From the terminal
+
+`canopy usage` prints the same view without leaving your shell:
+
+```bash
+canopy usage          # AI spend, activity, storage, deploys
+canopy usage --json   # machine-readable, for agents and scripts
+```
+
+- [Getting started](https://docs.canopy.website/guides/getting-started) — Create a project and let your coding agent wire up AI, data, and files.

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

@@ -0,0 +1,53 @@
+---
+title: Client access
+description: Share a project with clients who have no Monks account — a shared password unlocks that one project's URL and nothing else.
+---
+
+Everything on Canopy normally requires a Monks sign-in — which is exactly
+right until you want a client to see work-in-progress. Client access solves
+that: you set a shared password on a project, send the client the URL and the
+password, and they're in. No account creation, no invitations, no exceptions
+punched through the platform for anyone else.
+
+## How it works
+
+With client access enabled, a visitor without a Monks session who opens the
+project's URL gets a simple password page instead of the SSO redirect. Enter
+the right password and the app loads; Monks can still click through to
+company sign-in from the same page.
+
+The unlock is deliberately narrow:
+
+- **One project only.** The password grants access to that project's own
+  subdomain and nothing else — it can't be used on any other project or on
+  the dashboard.
+- **The live app only.** Clients see what a signed-in viewer would see. They
+  never get the dashboard, the data browser, deploy history, or settings.
+- **It expires.** Access is a temporary session on that browser; when it
+  lapses, the password page comes back.
+
+## Enabling it
+
+Open the project's **Settings** tab and use the **Client access** 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.
+2. Send the client the project URL and the password.
+
+To change the password, set a new one — previously handed-out passwords stop
+working for new sign-ins. To turn client access off entirely, remove the
+password from the same card; visitors are back to Monks-only immediately.
+
+> **Warning:** A shared password is deliberately lightweight protection — right for work-in-progress previews,
+> wrong for anything sensitive. Anyone who has it can view the app and share it further, so rotate
+> it when a review round ends.
+
+## Playing well with other access controls
+
+Client access is independent of
+[collaborators-only mode](https://docs.canopy.website/platform/members-and-access): you can lock
+the app down for Monks outside the team while a client with the password
+still gets in. That combination — "the client and the project team, nobody
+else" — is a common setup during a review phase.
+
+- [Members & access](https://docs.canopy.website/platform/members-and-access) — Who can view and who can manage a project, and how to tighten it.

package/dist/docs/platform-deploys-and-rollbacks.md

@@ -0,0 +1,93 @@
+---
+title: Deploys & rollbacks
+description: Every deploy is a numbered version you can preview, download, and make live again — rolling back is instant and loses nothing.
+---
+
+Every time you publish a project, Canopy records it as a numbered version —
+v1, v2, v3, and so on. The live site is simply a pointer at one of those
+versions. That one idea powers everything on this page: previews, rollbacks,
+and downloads are all just different ways of looking at (or pointing at) a
+version that already exists.
+
+## What a deploy contains
+
+A deploy is the built files of your app — the HTML, JavaScript, CSS, and other
+assets your build produces. Projects with a custom backend also ship their
+worker code in the same deploy, so frontend and backend always move together
+as one version.
+
+A deploy only goes live after every file has been uploaded and validated. A
+connection that drops halfway never leaves your project in a broken state —
+the previous version keeps serving until the new one is complete.
+
+## Ways to deploy
+
+- **From the terminal** — `canopy deploy` builds your project and publishes a
+  new version. This is what your coding agent runs. See the
+  [deploy guide](https://docs.canopy.website/guides/deploy) for details.
+- **From the dashboard** — on the project's Overview tab, upload a new version
+  by dragging in a zip, a folder, or loose files. No command line required.
+- **Automatically from CI** — create a project-scoped deploy token, add it to
+  your repository's secrets, and merging to `main` ships a new version on its
+  own. See [CI and deploy tokens](https://docs.canopy.website/guides/ci).
+
+The dashboard's deploy history shows every version with who published it and
+where it came from (CLI, dashboard, or CI).
+
+## Rolling back
+
+If a deploy goes wrong, point the site back at an earlier version. Rollback
+moves the live pointer — nothing is copied, rebuilt, or deleted, so it takes
+effect immediately and every version keeps its identity. Projects with a
+custom backend roll their backend back to the matching version too.
+
+- **Dashboard** — open the project's Overview tab and pick the version to make
+  live from the deploy history.
+- **CLI**:
+
+```bash
+canopy rollback        # pick a version from a list
+canopy rollback v3     # make v3 live directly
+```
+
+You can also "roll forward": after reverting to v3, making v5 live again is
+the same one-step operation. Any version in the history can be live.
+
+## The staging channel
+
+Beyond previews, every project can have a full **staging channel**: a staged
+version served at `https://staging-dot-<slug>.canopy.website` with its own
+database (a copy of live), its own files, and its own backend. Deploy there
+with `canopy deploy --staging` (or the dashboard's upload dialog), verify, and
+**promote** — the exact staged version becomes live, schema migrations
+replaying against the live database first. See
+[Staging & promoting](https://docs.canopy.website/guides/staging).
+
+## Previewing any version
+
+Every version has its own stable preview URL, so you can open an old build
+next to the current one without touching what's live:
+
+```
+https://v12-dot-<slug>.canopy.website
+```
+
+Preview URLs sit behind the same sign-in as the live site — they're for
+comparing builds and reviewing history, not for sharing something different
+from what access settings allow. A preview shows an old frontend against the
+live data; for a full candidate environment (frontend + backend + own
+database) use the staging channel above.
+
+## Downloading a version
+
+You can download the exact files behind any past version as a zip — handy for
+comparing builds or restoring something by hand:
+
+- **Dashboard** — from the version's entry in the deploy history.
+- **CLI** — `canopy download`, which lets you pick a version.
+
+Downloads are limited to the project's members; the deploy bundle is your
+source, not the public site.
+
+- [Deploying](https://docs.canopy.website/guides/deploy) — Build commands, canopy.json, and what canopy deploy does step by step.
+- [CI and deploy tokens](https://docs.canopy.website/guides/ci) — Ship a new version automatically on every push to main.

package/dist/docs/platform-egress.md

@@ -0,0 +1,75 @@
+---
+title: Outbound requests
+description: Which external hosts your project's backend may fetch — a per-project allowlist you manage yourself.
+---
+
+Outbound `fetch` from a project's backend worker is **deny-by-default**: the
+platform only lets requests through to platform infrastructure (your database,
+files, AI, the Canopy API) and to the hosts on your project's own
+**egress allowlist**. Anything else is answered locally with a 403
+`egress_denied` — the request never leaves the runtime.
+
+That default is deliberate: a thousand idle vibecoded projects should not be
+able to call arbitrary internet hosts. When your project genuinely needs an
+external API, you allow that host yourself — no platform-team ticket.
+
+> **Note:** Enforcement applies on every target. On GCP the runtime answers the 403 itself; on Cloudflare the
+> platform vets each outbound request outside your worker. Same rule, same error, one allowlist.
+
+## Allowing a host
+
+CLI, from the project directory:
+
+```bash
+canopy egress allow generativelanguage.googleapis.com
+canopy egress list
+canopy egress remove generativelanguage.googleapis.com
+```
+
+Or in the dashboard: **Settings → Outbound hosts**.
+
+Changes apply to the **running** workers within moments — the platform re-rolls
+the project's services with the new list, no deploy needed. Live and staging
+share one list, like secrets: the staging worker is the same code and needs the
+same hosts.
+
+## What an entry looks like
+
+- A bare hostname: `api.example.com` — matches exactly that host.
+- A subdomain wildcard: `*.googleapis.com` — matches any subdomain
+  (`storage.googleapis.com`, `a.b.googleapis.com`) but **not** the apex
+  `googleapis.com`.
+
+Hostnames only: no IP addresses, CIDR ranges, ports, schemes, or paths, and no
+`*` catch-all. Entries are case-insensitive; unicode names are stored in their
+punycode form. A project can list up to **32** hosts.
+
+## What doesn't count as egress
+
+Everything you reach through the SDK — `canopy.db`, `canopy.blob`,
+`canopy.ai`, and `env.CANOPY.fetch` — goes through the platform and is always
+allowed. The allowlist only governs direct `fetch` calls from your worker code
+to the outside world. (Frontend code in the browser is unaffected — this is
+about the worker.)
+
+## When a request is denied
+
+The blocked `fetch` resolves (in ~2ms, no network attempt) with status 403 and
+body:
+
+```json
+{ "error": "egress_denied", "detail": "host api.example.com is not on the project allowlist" }
+```
+
+Allow the host and retry — see the
+[troubleshooting entry](https://docs.canopy.website/guides/troubleshooting#egress_denied-403).
+
+## Recently blocked hosts
+
+You don't have to guess what got denied: the runtime reports every blocked
+host back to the platform, and they show up as **Recently blocked** in
+Settings → Outbound hosts (and in `canopy egress list`), with how often and
+how recently each was hit. One click on **Allow** puts the host on the list
+and clears it from the blocked section. Hosts that keep a low profile drop
+off — the list remembers the 50 most recent — and allowing a host removes its
+blocked entry immediately.

package/dist/docs/platform-feedback.md

@@ -0,0 +1,79 @@
+---
+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`.
+
+## The inbox
+
+Project members triage reports on the **Feedback tab**:
+
+- Statuses: `new → accepted → in_progress → resolved`, plus `declined`.
+  **`accepted` means "this is valid — an agent may pick it up."**
+- Every status change and comment is recorded on the item's trail.
+- 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, "work through the accepted feedback" is a
+prompt, not a process:
+
+```bash
+canopy feedback list --status accepted        # what a human marked valid
+canopy feedback show <id>                     # body + captured context + trail
+canopy feedback comment <id> "root cause: …"  # append findings
+canopy feedback status <id> resolved --comment "fixed in v42"
+```
+
+`show` includes the deploy version that served the page when the bug was
+reported — reproduce against that, not whatever is live now. An agent that
+investigates but can't fix should `comment` its findings and leave the status
+for a human; one that pushes back should `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-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 → Collaborators only** 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,66 @@
+---
+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
+
+Open a project in the dashboard and the **Data** tab shows what your app has
+stored:
+
+- **Collections** — the document-style data your app writes with
+  `canopy.db.collection(...)`. Pick a collection and page through its rows.
+- **Tables** — a browser for the underlying database tables, for when your
+  app uses raw SQL or you want to see exactly what's on disk.
+- **SQL console** — run a query directly against the project's database from
+  the browser. Useful for quick checks and one-off fixes.
+
+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.