@mediamonks/canopy-cli 0.7.5 → 0.7.7

package/dist/docs/cli-logout.md

@@ -0,0 +1,32 @@
+---
+title: canopy logout
+description: Sign out of Canopy by removing all locally stored CLI tokens.
+---
+
+`canopy logout` signs you out on this machine by forgetting every stored CLI token. Use it on a shared machine, or when you want a clean slate before logging in as someone else.
+
+## Usage
+
+```bash
+canopy logout
+```
+
+## Arguments & flags
+
+None. Logout is deliberately all-or-nothing: it clears the tokens for **every** site (`main`, `staging`, `gcp-pilot`) at once — there is no per-profile logout, so the global `--profile` flag has no effect here.
+
+## Details
+
+The command is local-only: it removes every stored token from `~/.canopy/config.json` and prints a confirmation. Nothing is called on the server, so the tokens themselves aren't revoked — they simply age out at their normal expiry. Your active-site choice stays in the file, so the next `canopy login` picks up where you left off.
+
+If no token was stored to begin with, it prints `Not logged in.` and exits successfully.
+
+## Examples
+
+```bash
+canopy logout
+```
+
+Removes all site tokens from `~/.canopy/config.json`; subsequent commands that need the API will ask you to run `canopy login`.
+
+See also [canopy login](https://docs.canopy.website/cli/login) and [canopy whoami](https://docs.canopy.website/cli/whoami).

package/dist/docs/cli-logs.md

@@ -0,0 +1,57 @@
+---
+title: canopy logs
+description: Read your project worker's logs (console output) from the terminal — no cloud console access needed.
+---
+
+`canopy logs` prints what your project's worker wrote to `console.log` / `console.error`. Reach for it when the worker misbehaves — a 500, an unexpected 403, a schedule that "did nothing" — instead of adding diagnostic endpoints and redeploying. The same output lives in the dashboard under the project's **Logs** tab.
+
+Logs are available on every site that runs workers. On a site where the platform can't read worker output, the command says so honestly instead of guessing. One caveat on Cloudflare-hosted sites: log capture starts with a project's next deploy after 2026-08-19 — a worker that hasn't been redeployed since then has nothing to show yet.
+
+## Usage
+
+```bash
+canopy logs [--project <slug>] [--staging] [--since 1h] [--limit 100] [--follow] [--json]
+```
+
+## Arguments & flags
+
+- `--project <slug>` — project slug. Defaults to the `canopy.json` in the current directory.
+- `--staging` — read the staging channel's worker instead of live. Default `false`.
+- `--since <when>` — how far back to read: a duration like `30s`, `15m`, `2h`, `1d`, or a timestamp. Default `1h`.
+- `--limit <n>` — max entries to print, 1–1000. Default `100`.
+- `--follow` / `-f` — keep polling for new entries every few seconds until you Ctrl-C.
+- `--json` — print entries as JSON lines (`{ ts, severity, text }`) instead of formatted text.
+
+## How it works
+
+Every request your worker handles captures its stdout/stderr; `canopy logs` reads that capture through the platform (project members only — there's no direct cloud access to grant or leak). Entries print oldest-first as:
+
+```
+SEVERITY  timestamp  text
+```
+
+`console.error` output is tagged `ERROR` and `console.warn` is `WARNING`; `console.log` stays `DEFAULT`. Text is verbatim — whatever the worker logged, including multi-line JSON. Thrown errors show up too: an uncaught exception in a request handler becomes one `ERROR` entry with the full stack trace (and the request answers a 500), so a crashing endpoint is diagnosable from the log alone.
+
+It's read-only and stdout-clean: entries go to stdout for piping, everything else to stderr.
+
+## Examples
+
+```bash
+canopy logs --since 15m
+```
+
+The last quarter hour of worker output for the project in the current directory.
+
+```bash
+canopy logs -f
+```
+
+Watch logs live while you exercise the app — the closest thing to a terminal attached to your deployed worker.
+
+```bash
+canopy logs --staging --since 1d --json | jq -r 'select(.severity == "ERROR") | .text'
+```
+
+Just yesterday's errors from the staging worker, for a script or an agent.
+
+See also [Troubleshooting](https://docs.canopy.website/guides/troubleshooting) for what to do with what you find, and [canopy staging](https://docs.canopy.website/cli/staging) for the staging channel.

package/dist/docs/cli-open.md

@@ -0,0 +1,41 @@
+---
+title: canopy open
+description: Open the deployed project in your browser.
+---
+
+`canopy open` opens the project's live URL in your default browser — the quickest way to look at what's actually deployed, typically right after a `canopy deploy`.
+
+## Usage
+
+```bash
+canopy open [dir] [--project <slug>]
+```
+
+## Arguments & flags
+
+- `--staging` — open the [staging channel](https://docs.canopy.website/guides/staging) (`staging-dot-<slug>`) instead of the live site.
+
+- `[dir]` — project directory to read `canopy.json` from. Defaults to the current directory.
+- `--project <slug>` — project slug, overriding `canopy.json`.
+
+## How it works
+
+The command resolves the project slug, builds the live URL from the active site's project domain (projects are served at `https://<slug>.<site domain>`), prints the URL, and opens it in your default browser. Which domain that is depends on the active profile — `--profile staging` opens the project on the staging site, not production.
+
+It does not deploy, check, or wait for anything: if the project has never been deployed, the browser simply lands on whatever the platform serves for an empty project. To open the dashboard instead, use the URL printed by [canopy projects](https://docs.canopy.website/cli/projects).
+
+## Examples
+
+```bash
+canopy deploy && canopy open
+```
+
+Ship and eyeball: deploys the current directory's project, then opens the freshly-live site.
+
+```bash
+canopy open --project my-app --profile staging
+```
+
+Opens `my-app` as served by the staging site, regardless of what the current directory pins.
+
+See also [canopy deploy](https://docs.canopy.website/cli/deploy) and [Sites & profiles](https://docs.canopy.website/platform/sites-and-profiles).

package/dist/docs/cli-projects.md

@@ -0,0 +1,43 @@
+---
+title: canopy projects
+description: List your Canopy projects with their status, role, and live URLs.
+---
+
+`canopy projects` lists the projects you can work on for the current site — one line each with slug, status, your role, live URL, and name. It's the quickest way to recall a slug, check what you have access to, or confirm you're on the site you think you are.
+
+## Usage
+
+```bash
+canopy projects
+canopy projects --all
+canopy --profile staging projects
+```
+
+## Arguments & flags
+
+- `--all` — include projects you can't edit. By default the list shows only projects where you're an owner or editor (admins always see everything, since they can edit everything).
+- `--profile <site>` — global flag (or `CANOPY_PROFILE`): each site has its own project registry, so listing on `staging` shows a completely different set than `main`.
+
+## Details
+
+The command fetches your project list from the platform and prints one aligned row per project: slug, status, your role (`owner` / `editor`; for `--all` rows you can't edit it shows the owner's email instead, and admins see `admin`), the live URL, and the display name.
+
+With nothing to show, the message distinguishes the two cases: no projects exist at all (`run canopy create`), or none are yours — in which case it mentions how many `--all` would reveal.
+
+The CLI version and active site are printed on stderr, keeping stdout clean for piping — handy since the output is stable, column-aligned text.
+
+## Examples
+
+```bash
+canopy projects
+```
+
+Shows your own projects on your default site, e.g. to grab a slug for `canopy init` or `canopy delete`.
+
+```bash
+canopy projects --all
+```
+
+Shows every project on the site, with owner emails for the ones you can't edit — useful for finding who to ask for access.
+
+See also [canopy create](https://docs.canopy.website/cli/create), [canopy init](https://docs.canopy.website/cli/init), and [Members & access](https://docs.canopy.website/platform/members-and-access).

package/dist/docs/cli-promote.md

@@ -0,0 +1,44 @@
+---
+title: canopy promote
+description: Make the staged version live — migrations replay against the live database first, then the exact staged artifacts go live.
+---
+
+`canopy promote` takes what you verified on the [staging channel](https://docs.canopy.website/guides/staging)
+and makes it live. It is not a redeploy: the platform re-uses the exact files
+and backend bundle of the staged version, so what you tested is what ships.
+
+## Usage
+
+```bash
+canopy promote                  # promote the currently staged version
+canopy promote v8               # promote a specific version
+canopy promote --yes            # skip the confirmation (CI)
+```
+
+## Arguments & flags
+
+- `[version]` — the version to make live, as `8` or `v8`. Defaults to whatever
+  is currently staged; errors when nothing is staged and no version is given.
+- `--project <slug>` — project slug, overriding `canopy.json`.
+- `--dir <path>` — project directory (defaults to the current directory).
+- `--yes` — skip the confirmation prompt.
+- `--profile <site>` / `CANOPY_PROFILE` — which site to promote on.
+
+## What happens, in order
+
+1. **Migrations replay against live.** Any schema migrations you rehearsed on
+   staging are still pending in the live database's journal — they apply now,
+   with an automatic pre-promote snapshot taken first. A migration failure
+   aborts the promote: the live version never flips, old code keeps running,
+   and the output names the snapshot and the restore command.
+2. **The staged backend goes live.** If the version shipped a worker, the
+   platform redeploys that exact bundle with live bindings.
+3. **The pointer flips.** The staged version becomes the live version.
+
+The output confirms the live URL, the promoted version, any migrations that
+applied, and the snapshot key.
+
+Promotion is also a button on the dashboard's Overview tab.
+
+See also [canopy deploy](https://docs.canopy.website/cli/deploy) (`--staging`), [canopy staging](https://docs.canopy.website/cli/staging),
+and [Staging & promoting](https://docs.canopy.website/guides/staging).

package/dist/docs/cli-rollback.md

@@ -0,0 +1,45 @@
+---
+title: canopy rollback
+description: Make an earlier deploy live again by moving the live pointer to a previous version.
+---
+
+`canopy rollback` switches the project's live version back to an earlier deploy. Reach for it when a deploy went wrong and you want the last good version serving again in seconds — no rebuild, no re-upload.
+
+## Usage
+
+```bash
+canopy rollback                 # pick a version from the deploy history
+canopy rollback v3              # make v3 live directly
+canopy rollback --project my-app 3
+```
+
+## Arguments & flags
+
+- `[version]` — the deploy version to make live, as `3` or `v3`. Optional: when omitted on an interactive terminal you get a picker showing the full deploy history (version, timestamp, source, and which one is currently live), preselecting the version just before the live one. On a non-TTY run with no version, the CLI rolls back to `live - 1` automatically.
+- `--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's deployment to roll back.
+
+## How it works
+
+Every deploy is stored immutably as a numbered version; "live" is just a pointer to one of them. Rolling back moves that pointer — no files are rebuilt, uploaded, or deleted. Projects with a custom backend also get their backend rolled to the bundle matching the target version, so frontend and backend stay in step. The command prints the target, asks the platform to repoint, and confirms with the live URL, the now-live version, and the version that was live before.
+
+Because versions are never destroyed, rolling back is symmetric: "roll forward" is simply `canopy rollback <newer-version>` — pass the number of the newer deploy you want live again. Picking the version that's already live is an error, and a project with fewer than two deploys has nothing to roll back to.
+
+Deploy history is also visible in the dashboard, where the same rollback is a button.
+
+## Examples
+
+```bash
+canopy rollback
+```
+
+Shows the deploy history for the project in the current directory and lets you pick — the entry before the live one is preselected.
+
+```bash
+canopy rollback v7 --project client-site --profile main
+```
+
+Directly repoints `client-site` on the main site to version 7 — works the same whether v7 is older or newer than what's live.
+
+See also [canopy deploy](https://docs.canopy.website/cli/deploy), [canopy download](https://docs.canopy.website/cli/download), and [Deploys & rollbacks](https://docs.canopy.website/platform/deploys-and-rollbacks).

package/dist/docs/cli-skill.md

@@ -0,0 +1,39 @@
+---
+title: canopy skill
+description: Install the Canopy agent skill into a repo so coding agents know how to drive the platform.
+---
+
+`canopy skill install` writes the Canopy agent skill into the current repository, teaching AI coding agents (Claude Code and others) how to use the platform: checking install and login state, creating vs. initializing projects, choosing templates, reading `canopy docs` before guessing, and treating `db restore`, `delete`, and deploys with appropriate care.
+
+## Usage
+
+```bash
+canopy skill install
+```
+
+`install` is currently the only subcommand.
+
+## Arguments & flags
+
+None — it always installs into the repository at the current working directory.
+
+## How it works
+
+The skill files ship inside the CLI package, so installing needs no network. Two paths are written:
+
+- `.agents/skills/canopy/` — the source of truth, in the tool-neutral `.agents/` tree so any agent tooling can read it (no vendor lock-in).
+- `.claude/skills/canopy` — a **symlink** to the `.agents/` copy, so Claude Code picks the skill up. Where symlinks aren't available (e.g. Windows without developer mode), the CLI falls back to a real copy and says so.
+
+Installation is a clean replace: any existing skill directory is removed first, and the installed copy is stamped with the CLI version that wrote it. That stamp is how the skill stays fresh — [`canopy upgrade`](https://docs.canopy.website/cli/upgrade) detects an installed skill in the repo and re-runs `canopy skill install` with the new CLI, so the skill always matches the CLI version in use. If that auto-refresh ever fails, re-run `canopy skill install` yourself.
+
+Commit the `.agents/` directory (and the `.claude/` link) so teammates and CI agents get the skill with the repo.
+
+## Examples
+
+```bash
+canopy skill install
+```
+
+From a repo root: installs the skill, prints where the files went and whether `.claude/skills/canopy` is a symlink or a copy, and suggests trying `canopy docs`.
+
+See also [canopy docs](https://docs.canopy.website/cli/docs) — the always-current documentation the skill points agents at — and [canopy upgrade](https://docs.canopy.website/cli/upgrade).

package/dist/docs/cli-staging.md

@@ -0,0 +1,54 @@
+---
+title: canopy staging
+description: Inspect, refresh, or tear down the project's staging channel.
+---
+
+`canopy staging` manages the project's [staging channel](https://docs.canopy.website/guides/staging) — the
+safe copy created by the first `canopy deploy --staging`.
+
+## Usage
+
+```bash
+canopy staging status           # what's staged, what's live, the staging URL
+canopy staging use v3           # serve an existing version on staging
+canopy staging sync             # replace staging data with a fresh copy of live
+canopy staging destroy          # remove the staging channel entirely
+```
+
+## Subcommands
+
+### `status`
+
+Shows whether the channel exists, which version is staged (and whether it has
+a backend), which version is live, and the staging URL. When the staged version
+differs from live it reminds you that `canopy promote` makes it live.
+
+### `use`
+
+Points the staging channel at any version in the deploy history — the reverse
+of [canopy promote](https://docs.canopy.website/cli/promote), and the staging twin of
+[canopy rollback](https://docs.canopy.website/cli/rollback). A pointer move: nothing is uploaded or
+rebuilt, and the version's backend (if any) is redeployed to the staging
+worker. Omit the version on a terminal to pick from the history. Requires the
+staging channel to exist; it applies no migrations, so an old version runs
+against staging's current schema (the same caveat version previews have).
+
+### `sync`
+
+Re-clones the live database over the staging one. Staging data is replaced —
+live is only read. Use it to re-rehearse a migration on fresh data, or when
+test writes have made staging drift too far. Asks for confirmation on a
+terminal; `--yes` skips it.
+
+### `destroy`
+
+Deletes the staging database, staged files, and the staging backend. Live is
+untouched. The deploy history keeps its records, and the next
+`canopy deploy --staging` recreates the channel from a fresh copy of live.
+Requires typing the slug to confirm; `--yes` skips it.
+
+All three take `--project <slug>` to target a project outside the current
+directory, and `--profile <site>` / `CANOPY_PROFILE` for the site.
+
+See also [canopy deploy](https://docs.canopy.website/cli/deploy), [canopy promote](https://docs.canopy.website/cli/promote), and
+[Staging & promoting](https://docs.canopy.website/guides/staging).

package/dist/docs/cli-token.md

@@ -0,0 +1,47 @@
+---
+title: canopy token
+description: Create, list, and revoke project-scoped deploy tokens for CI and push-to-main deploys.
+---
+
+`canopy token` manages deploy tokens: standing `cnpy_` bearer credentials that can do exactly one thing — deploy one specific project. You reach for it when setting up CI (typically GitHub Actions deploying on every push to main) so the runner never needs a personal login.
+
+## Usage
+
+```bash
+canopy token create --name "GitHub Actions"
+canopy token list
+canopy token revoke <id>
+```
+
+## 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` for which site the token belongs to.
+
+- `create` — mint a new deploy token for the project.
+  - `--name <label>` — a label shown in the dashboard, e.g. `"GitHub Actions"`. Optional but recommended so you can tell tokens apart later.
+- `list` — show the project's deploy tokens: id, name, creation time, and who created them. Token values are never shown here.
+- `revoke <id>` — delete a token by its id (from `canopy token list`). Deploys using it stop working immediately.
+
+## How it works
+
+`create` prints the token plaintext **exactly once** — the platform stores only a hash, so copy it right away. The token is scoped to a single project on a single site: it can deploy that project and nothing else, which makes it safe to hand to a CI system.
+
+To use it in CI, put the value in the `CANOPY_DEPLOY_TOKEN` environment variable — the CLI checks it before the login token, so `canopy deploy` works on a runner with no `canopy login`. For GitHub Actions, add it as the repo secret `CANOPY_DEPLOY_TOKEN` (`gh secret set CANOPY_DEPLOY_TOKEN`, or Settings → Secrets); pushes to main then deploy via the project's `canopy-deploy.yml` workflow.
+
+If a deploy fails with a rejected token, it was likely revoked — create a fresh one here or in the dashboard (Settings → Deploy tokens) and update the secret. Losing a token is never a problem: revoke the old id and mint a new one.
+
+## Examples
+
+```bash
+canopy token create --name "GitHub Actions"
+```
+
+Prints a new `cnpy_` token once, with instructions for storing it as the `CANOPY_DEPLOY_TOKEN` repo secret.
+
+```bash
+canopy token list --project my-app
+```
+
+Shows every deploy token for `my-app` so you can spot stale ones and revoke them by id.
+
+See also [canopy deploy](https://docs.canopy.website/cli/deploy) and the [CI guide](https://docs.canopy.website/guides/ci).

package/dist/docs/cli-upgrade.md

@@ -0,0 +1,43 @@
+---
+title: canopy upgrade
+description: Update the Canopy CLI to the latest published version, using the installer that put it there.
+---
+
+`canopy upgrade` reinstalls the CLI globally at the latest published version. You'll usually run it because the CLI told you to: when a newer release exists, commands print a one-line `Update available: … Run 'canopy upgrade' to update.` hint on stderr.
+
+## Usage
+
+```bash
+canopy upgrade
+canopy upgrade --version 0.5.0
+canopy upgrade --pm npm
+```
+
+## Arguments & flags
+
+- `--version <x.y.z>` — install this exact version instead of `latest` (also how you downgrade).
+- `--pm <installer>` — which installer to use: `vp`, `npm`, `pnpm`, `yarn`, or `bun`. Auto-detected by default.
+
+## How it works
+
+The CLI shells out to a package manager rather than replacing files itself, so global prefixes, permissions, and lockfiles stay the installer's concern. It detects which installer owns the running binary from the binary's own path (Vite+, pnpm, bun, and yarn each keep globals in a recognizable place) and defaults to npm otherwise. The detection matters: a Vite+-installed `canopy` upgraded via plain `npm install -g` would land in npm's separate prefix and leave the active binary untouched — `--pm` overrides the guess when it's wrong.
+
+The command prints the exact install command it runs, streams the installer's output, and suggests `canopy --version` to confirm. If the repo you're in has the [Canopy agent skill](https://docs.canopy.website/cli/skill) installed, the upgrade finishes by running the **new** CLI's `canopy skill install` to keep the skill in sync (with a warning, not a failure, if that step can't run).
+
+The passive hint that leads you here is a once-a-day background check of the npm registry, cached in `~/.canopy/version-check.json`. It never blocks or slows a command, stays silent in CI and piped output, and can be disabled with `CANOPY_NO_UPDATE_CHECK=1`. The hint itself is suppressed while you're running `upgrade`.
+
+## Examples
+
+```bash
+canopy upgrade
+```
+
+Detects that the CLI was installed with, say, Vite+ and runs `vp install -g @mediamonks/canopy-cli@latest`, then refreshes the repo's agent skill if one is installed.
+
+```bash
+canopy upgrade --version 0.5.0 --pm npm
+```
+
+Pins a specific release through npm — useful to roll back a release or to correct a wrong auto-detection.
+
+See also [canopy skill](https://docs.canopy.website/cli/skill) and [Installing the CLI](https://docs.canopy.website/cli).

package/dist/docs/cli-usage.md

@@ -0,0 +1,43 @@
+---
+title: canopy usage
+description: Show a project's AI spend, storage footprint, and deploy count from the terminal.
+---
+
+`canopy usage` prints what a project is consuming — the same data as the dashboard's Usage tab, without leaving the terminal. Reach for it when you want to know what the AI features are costing, how big the database and blob store have grown, or which version is live.
+
+## Usage
+
+```bash
+canopy usage [--project <slug>] [--json]
+```
+
+## Arguments & flags
+
+- `--project <slug>` — project slug. Defaults to the `canopy.json` in the current directory.
+- `--json` — print the raw JSON (same shape as the dashboard Usage API) instead of the formatted report. Default `false`.
+
+## How it works
+
+The command resolves the project, fetches its usage from the platform, and prints a report covering (by default) the last 30 days:
+
+- **AI** — total spend in USD, request count, and tokens in/out, with a per-model breakdown (top 8 models). If AI usage data isn't available for the project, the report says so with the reason. A note appears when the window held more requests than were summarized.
+- **Storage** — database size and table count, and blob storage total bytes and object count (each shown as `—` when the project has none).
+- **Deploys** — how many deploys the project has had, and which version is currently live.
+
+It's read-only: nothing is changed, and no confirmation is needed. With `--json`, the report goes to stdout as `{ slug, usage }` for scripts and agents; the human view is plain text either way.
+
+## Examples
+
+```bash
+canopy usage
+```
+
+From inside a project directory: prints the AI spend, storage, and deploy summary for the project pinned in `canopy.json`.
+
+```bash
+canopy usage --project my-app --json | jq .usage.ai.costUsd
+```
+
+Pulls one number — the project's AI spend over the window — for a script or a quick answer.
+
+See also [AI usage](https://docs.canopy.website/platform/ai-usage) for how spend is measured, and [canopy projects](https://docs.canopy.website/cli/projects) to find a slug.

package/dist/docs/cli-whoami.md

@@ -0,0 +1,46 @@
+---
+title: canopy whoami
+description: Show which account and site the CLI is currently talking to, and whether your token is still valid.
+---
+
+`canopy whoami` prints the login the CLI would use right now: your email, the API it points at, and your token's expiry. Reach for it when a command fails with an auth error, or to double-check which site you're about to act on.
+
+## Usage
+
+```bash
+canopy whoami
+canopy --profile staging whoami   # check a specific site's token
+```
+
+## Arguments & flags
+
+- `--profile <site>` — global flag (or `CANOPY_PROFILE`): check the token for a specific site instead of your resolved default. Each site has its own token, so being logged in on `main` says nothing about `staging`.
+
+## Details
+
+The command is fully offline — it only reads `~/.canopy/config.json`, no network calls. For the resolved profile it prints:
+
+- your email (as recorded at login),
+- the cloud the site runs on, when known,
+- the API URL the CLI targets,
+- the token expiry — either `Token expires <date>` or a loud `Token EXPIRED` line telling you to run `canopy login` again.
+
+The active site and CLI version are printed on stderr as a header line by every command, `whoami` included. If no token is stored for the resolved profile, the command exits with an error suggesting `canopy login`.
+
+Note that expiry is checked against the stored timestamp only; a token can also be revoked server-side, in which case `whoami` looks fine but API commands fail.
+
+## Examples
+
+```bash
+canopy whoami
+```
+
+Prints your email, API URL, and token expiry for your default site — a quick sanity check before a deploy.
+
+```bash
+canopy --profile gcp-pilot whoami
+```
+
+Verifies you also hold a (non-expired) token for the GCP pilot site before targeting it.
+
+See also [canopy login](https://docs.canopy.website/cli/login) and [Sites & profiles](https://docs.canopy.website/platform/sites-and-profiles).

package/dist/docs/developers-agents-and-ai.md

@@ -0,0 +1,95 @@
+---
+title: Building with agents
+description: Teach your coding agent Canopy — the agent skill, offline docs, template guardrails, and prompts that work.
+---
+
+Canopy is built to be driven by coding agents. Three pieces make that work:
+an installable agent skill, docs the CLI carries offline, and guardrail files
+every new project ships with. Set them up once and your agent knows how to
+scaffold, run, deploy, and manage data without guessing.
+
+## Install the skill
+
+From your project (or any repo the agent works in):
+
+```bash
+canopy skill install
+```
+
+This writes the skill to the tool-neutral `.agents/skills/canopy/` tree and
+symlinks `.claude/skills/canopy` to it, so Claude Code picks it up while other
+agents read `.agents/`. `canopy upgrade` refreshes it alongside the CLI.
+
+The skill teaches an agent to:
+
+- **Check install and login first** — `canopy --version`, `canopy whoami`,
+  and how to run `canopy login` correctly (hand the browser sign-in to the
+  human; never touch credentials).
+- **Read docs before acting** — prefer `canopy docs <topic>` and
+  `canopy <command> --help` over guessing flags.
+- **Choose the right starter** — `spa` for anything real (typed SDK),
+  `static` only for trivial pages, `worker` when server-side code is needed —
+  and use `canopy init <slug>` (never `canopy create`) for a project that
+  already exists.
+- **Respect safety rules** — confirm before deploys, snapshot before
+  `canopy db restore`, treat `canopy delete` as destructive.
+
+## Offline docs for agents
+
+The CLI ships the full platform documentation and keeps it fresh from the
+platform, so an agent can read it without a browser — even before signing in:
+
+```bash
+canopy docs            # list all topics
+canopy docs deploy     # print one topic
+canopy docs cli --refresh   # force a re-fetch from the platform
+```
+
+Topics mirror the [guides](https://docs.canopy.website/guides/getting-started) on this site:
+`getting-started`, `cli`, `dev`, `deploy`, `data`, `ci`, `troubleshooting`,
+and more.
+
+## Template guardrails
+
+Every scaffolded project includes an `AGENTS.md` (the agent-facing README)
+that encodes the platform's boundaries, so an agent starting cold in the repo
+already knows the rules:
+
+- **Don't add auth** — the platform authenticates every request first.
+- **Don't store secrets** in the repo or browser code; set them in the
+  dashboard, and only a backend worker reads them.
+- **No SSR, no custom servers, no external databases** — data goes through
+  `canopy.db` and `canopy.blob`.
+- `canopy dev` uses **live** project data: snapshot before risky writes, or
+  use `canopy dev --local` for an offline sandbox where writes never reach
+  the platform.
+
+## Prompts that work
+
+With the skill installed, these are safe, copy-pasteable asks — each maps to
+commands the skill and docs actually cover:
+
+```text
+Set up Canopy in this repo: check the CLI is installed and I'm logged in,
+then install the Canopy skill and skim `canopy docs getting-started`.
+```
+
+```text
+Create a new Canopy project for a team lunch-voting app (spa template),
+run it locally with `canopy dev`, and build the first version of the UI.
+```
+
+```text
+Deploy this project to Canopy, then open the live site so I can check it.
+If anything looks wrong, roll back to the previous version.
+```
+
+```text
+Take a database snapshot, then pull the production data with
+`canopy db pull` and use the dump to reproduce the bug locally with
+`canopy dev --local --pull`.
+```
+
+> **Note:** Deploys go live behind company sign-in and restores replace all project data — a well-behaved
+> agent will confirm both with you first. That caution comes from the skill; keep it installed and
+> current.