@mediamonks/canopy-cli 0.7.20 → 0.7.22

package/dist/{dev-DtEwiNYi.mjs → dev-CNqx_53I.mjs}

@@ -37,7 +37,7 @@ async function workerPlugin(flags, slug) {
 		console.log(`note: canopy.json points "worker" at ${entry}, which does not exist — skipping.`);
 		return;
 	}
-	const { missingSecretNames, readDevVars, workerDevPlugin } = await import("./dev-worker-IWnHvQ1f.mjs");
+	const { missingSecretNames, readDevVars, workerDevPlugin } = await import("./dev-worker-Bij9OUMk.mjs");
 	const secrets = readDevVars(flags.dir);
 	const email = siteConfig().email;
 	const plugin = workerDevPlugin({
@@ -165,7 +165,7 @@ async function devRemote(flags, slug) {
 async function devLocal(flags, slug) {
 	let dump;
 	if (flags.pull) {
-		const { fetchProjectDump } = await import("./local-CKRZur_5.mjs");
+		const { fetchProjectDump } = await import("./local-CsSP4Vpt.mjs");
 		console.log(`Pulling a fresh export of ${slug}${flags.staging ? " [staging]" : ""}…`);
 		dump = await fetchProjectDump(slug, flags.staging ? "staging" : "live");
 	}
@@ -180,7 +180,7 @@ async function devLocal(flags, slug) {
 		const reason = err instanceof ApiError ? err.explain().why : String(err);
 		console.log(`Note: ai/services will be unavailable — could not reach the platform (${reason}).`);
 	}
-	const { createSandbox } = await import("./local-CKRZur_5.mjs");
+	const { createSandbox } = await import("./local-CsSP4Vpt.mjs");
 	const sandbox = await createSandbox({
 		slug,
 		persistDir: join(flags.dir, ".canopy", "local"),

package/dist/dev-D7v7WK9O.mjs

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

package/dist/{dev-worker-IWnHvQ1f.mjs → dev-worker-Bij9OUMk.mjs}

@@ -1,4 +1,4 @@
-import "./src-Bu4Ze32I.mjs";
+import "./src-BKKAEkbH.mjs";
 import { readFileSync } from "node:fs";
 import { relative, resolve, sep } from "node:path";
 //#region ../data-plane/src/worker-request.ts

package/dist/docs/cli-dev.md

@@ -29,7 +29,7 @@ canopy dev --local --pull       # sandbox hydrated from a fresh prod export
 
 **Local sandbox (`--local`).** Database, file, and auth requests are answered entirely on your machine, from a sandbox stored under `.canopy/local/` in the project directory — no database to install, and writes never reach the platform. The sandbox behaves the same as the real API, so code that works locally works deployed. Two things still go remote: `ai` and `services` calls go through to the real platform (metered as usual) when you're logged in — fully offline, they return errors until you log in and restart.
 
-**Matching your site's SQL dialect.** The document API (`canopy.db.collection(…)`) behaves identically everywhere, but raw `canopy.db.sql()` speaks the deployment target's dialect — SQLite on Cloudflare-backed sites, Postgres on GCP-backed ones (see [dialect()](https://docs.canopy.website/guides/data)). The sandbox defaults to Postgres. If your project uses raw SQL written for a SQLite site, lock the dialect in `canopy.json`:
+**Matching your site's SQL dialect.** The document API (`canopy.db.collection(…)`) behaves identically everywhere, but raw `canopy.db.sql()` speaks your site's dialect — SQLite or Postgres (see [dialect()](https://docs.canopy.website/guides/data)). The sandbox defaults to Postgres. If your project uses raw SQL written for a SQLite site, lock the dialect in `canopy.json`:
 
 ```json
 { "slug": "my-project", "dialect": "sqlite" }

package/dist/docs/cli-logs.md

@@ -5,7 +5,7 @@ description: Read your project worker's logs (console output) from the terminal
 
 `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.
+Logs are available on every site that runs backends. On a site where the platform can't read your backend's output, the command says so honestly instead of guessing. One caveat: on some sites log capture starts with a project's next deploy after 2026-08-19, so a backend that hasn't been redeployed since then has nothing to show yet.
 
 ## Usage
 

package/dist/docs/data.md

@@ -3,8 +3,8 @@ title: Working with project data
 description: Pulling, snapshotting, and restoring your project database.
 ---
 
-Each Canopy project gets its own database and blob storage (D1 and R2 on the
-Cloudflare target; Postgres and GCS on GCP). Your app reads and writes them
+Each Canopy project gets its own database and its own file storage. Your app
+reads and writes them
 through the Canopy SDK at runtime; the CLI gives you tools to manage the data
 around it.
 

package/dist/docs/dev.md

@@ -39,7 +39,7 @@ canopy dev --local --pull
 By default the sandbox runs PGlite (embedded Postgres), so raw
 `canopy.db.sql()` speaks the postgres dialect there, while your deployed
 project speaks whatever its platform target speaks (`canopy.db.dialect()`
-tells you — sqlite on Cloudflare). Collections (`canopy.db.collection(...)`)
+tells you). Collections (`canopy.db.collection(...)`)
 behave the same in both, so this only matters for hand-written SQL — see
 `canopy docs data`. If your project's raw SQL targets a sqlite site, lock the
 dialect in `canopy.json` (`"dialect": "sqlite"`) and the sandbox runs an

package/dist/docs/developers-architecture.md

@@ -42,8 +42,8 @@ fall back to `index.html`, so client-side routes like `/settings` work on a
 hard refresh without any configuration. Rollback just repoints "live" at an
 earlier version — instant, nothing rebuilt.
 
-The full path — including caching, version-pinned `v12-dot-<slug>` preview
-hosts, and the security review — is in
+The full picture — caching rules, deploy limits, and version-pinned
+`v12-dot-<slug>` preview hosts — is in
 [How static files are served](https://docs.canopy.website/guides/static-serving).
 
 ## The optional backend worker
@@ -63,44 +63,52 @@ a backend, declared in `canopy.json`:
 ```
 
 Requests under `/api/*` reach the worker (Hono-style handlers); everything
-else is still static serving. Three things to know:
+else is still static serving. A few things to know:
 
 - **Requests arrive authenticated.** The worker sits behind the same gateway
   wall as the frontend.
-- **Platform access goes through the same SDK**, via the `CANOPY` service
-  binding — same budgets, same data isolation as the browser:
+- **The caller is already identified.** `c.env.USER` is the signed-in person
+  (`null` during a scheduled run) — no round-trip needed:
 
   ```ts
-  app.get("/api/hello", async (c) => {
-    const canopy = createCanopy({ fetch: c.env.CANOPY.fetch.bind(c.env.CANOPY) });
-    const user = await canopy.auth.user();
+  app.get("/api/hello", (c) => {
+    const user = c.env.USER;
+    if (!user) return c.json({ error: "unauthenticated" }, 401);
     return c.json({ message: `Hello, ${user.name}!` });
   });
   ```
 
+- **Platform access goes through the same SDK**, via the `CANOPY` service
+  binding — same budgets, same data isolation as the browser:
+
+  ```ts
+  const canopy = createCanopy({ fetch: c.env.CANOPY.fetch.bind(c.env.CANOPY) });
+  const notes = await canopy.db.collection("notes").find();
+  ```
+
 - **Secrets and schedules come from the dashboard.** Secrets (Settings →
   Secrets) land as Workers-shaped bindings (`c.env.MY_API_KEY`, not
   `process.env`); dashboard Schedules invoke an exported
   `scheduled(event, env)` — switch on `event.name`.
 
-> **Warning:** Backend workers are capability-gated per target: today the GCP target runs them, while on
-> Cloudflare sites a worker deploy answers a clear "not supported yet". Frontend-only projects
-> deploy everywhere.
+> **Note:** Backends run on the `main` and `gcp-pilot` sites. On a site without backend support, a deploy that
+> includes one answers with a clear "not supported here" rather than failing obscurely;
+> frontend-only projects deploy everywhere.
 
 ## Where your data lives
 
 Every project gets its own database and its own blob-storage prefix. No other
 project can read them, and deleting the project tears everything down. The
-document API is portable across targets; raw SQL speaks the target's dialect
+document API works the same on every site; raw SQL speaks your site's dialect
 (`sqlite` or `postgres` — ask `canopy.db.dialect()`). Dumps, snapshots, and
 restores are CLI commands — see the [project data guide](https://docs.canopy.website/guides/data).
 
 ## Sites
 
 A _site_ is one installation of the whole platform. The CLI ships three
-profiles — `main` (canopy.website, Cloudflare), `staging` (thanarie.dev,
-Cloudflare), and `gcp-pilot` (canopy.monks.zone, GCP) — and always shows which
-one you're on. Projects pin theirs in `canopy.json`; `--profile` or
-`CANOPY_PROFILE` overrides per command. Most projects only ever use `main`.
-Target differences (dialect, full-text search, worker support) surface as
-capabilities, not separate APIs.
+profiles — `main`, `staging`, and `gcp-pilot` — and always shows which one
+you're on. Projects pin theirs in `canopy.json`; `--profile` or
+`CANOPY_PROFILE` overrides per command. Most projects only ever use `main`;
+see [sites and profiles](https://docs.canopy.website/platform/sites-and-profiles) for what the other two
+are. Where sites differ (SQL dialect, full-text search, backend support) it
+surfaces as a capability, not a separate API.

package/dist/docs/index.json

@@ -77,20 +77,10 @@
           "title": "CLI command reference",
           "summary": "Every canopy command, its flags, and what it does."
         },
-        {
-          "slug": "notifications",
-          "title": "Slack notifications",
-          "summary": "Canopy DMs you about your reports and projects — replies, new reports, blocked fetches, budget hits, failing schedules — and answers questions when you ask."
-        },
         {
           "slug": "static-serving",
           "title": "How static files are served",
-          "summary": "The full path a browser request takes to a deployed file."
-        },
-        {
-          "slug": "infrastructure",
-          "title": "Infrastructure as code",
-          "summary": "Terraform for the account-level Cloudflare pieces Canopy needs."
+          "summary": "Why every page is a file, and what that means for routing, caching, and deploys."
         },
         {
           "slug": "troubleshooting",
@@ -134,6 +124,11 @@
           "title": "Google",
           "summary": "Let your project work with Google data — Sheets, Docs, Calendar, Drive, Gmail — without handling any OAuth yourself."
         },
+        {
+          "slug": "platform-slack",
+          "title": "Slack",
+          "summary": "Give your project its own Slack bot — Canopy creates and manages the app, your code handles the events."
+        },
         {
           "slug": "platform-members-and-access",
           "title": "Members & access",
@@ -144,6 +139,16 @@
           "title": "Feedback & bug reports",
           "summary": "A built-in feedback widget on every project, a ticket-lite inbox behind it, and a CLI that lets agents work the backlog."
         },
+        {
+          "slug": "platform-notifications",
+          "title": "Notifications",
+          "summary": "Canopy DMs you on Slack about your reports and projects — replies, new reports, blocked fetches, budget hits, failing schedules."
+        },
+        {
+          "slug": "platform-assistant",
+          "title": "The Canopy assistant",
+          "summary": "Ask questions about your projects and the platform in plain language — in Slack, or from the button in the corner of the docs and the dashboard."
+        },
         {
           "slug": "platform-client-access",
           "title": "Client access",
@@ -328,6 +333,11 @@
           "title": "Google",
           "summary": "Call Google APIs as the project's connected account or as the visitor's own — the platform holds the OAuth."
         },
+        {
+          "slug": "sdk-slack",
+          "title": "Slack",
+          "summary": "Handle your bot's events and slash commands in your worker, and post to Slack as the bot — no tokens in project code."
+        },
         {
           "slug": "sdk-services",
           "title": "Services",

package/dist/docs/migrations.md

@@ -65,9 +65,9 @@ data).
 
 Pin your dialect first — a Drizzle schema is written for one SQL flavor. Check
 what your project's site runs on (`await canopy.db.dialect()` or the
-[data guide](https://docs.canopy.website/guides/data)) and set `"dialect"` in `canopy.json`: `"sqlite"`
-on Cloudflare-backed sites, `"postgres"` on GCP-backed ones. That same field
-makes `canopy dev --local` run a matching local engine.
+[data guide](https://docs.canopy.website/guides/data)) and set `"dialect"` in `canopy.json` to match —
+`"sqlite"` or `"postgres"`. That same field makes `canopy dev --local` run a
+matching local engine.
 
 Install the tools and describe your schema:
 
@@ -113,24 +113,30 @@ This is fully local — it diffs your schema files and writes `.sql` into
 Canopy never hands out connection strings — Drizzle talks to your data through
 the handles Canopy already provides.
 
-**In a project worker on a Cloudflare-backed site**, `env.DB` is a real D1
-handle:
+Both handles are query functions, so both fit Drizzle's **proxy driver** —
+`drizzle-orm/sqlite-proxy` on a sqlite site, `drizzle-orm/pg-proxy` on a
+postgres one. Match it to the `"dialect"` you pinned in `canopy.json`.
+
+**In your backend**, `env.DB` takes the statement and its parameters:
 
 ```ts title="worker/index.ts"
-import { drizzle } from "drizzle-orm/d1";
+import { drizzle } from "drizzle-orm/sqlite-proxy";
 import { users } from "../src/schema.ts";
 
 export default {
   async fetch(request, env) {
-    const db = drizzle(env.DB);
-    const all = await db.select().from(users);
-    return Response.json(all);
+    const db = drizzle(async (sql, params, method) => {
+      const { rows } = await env.DB.query(sql, params);
+      const values = rows.map((row) => Object.values(row));
+      return { rows: method === "get" ? (values[0] ?? []) : values };
+    });
+    return Response.json(await db.select().from(users));
   },
 };
 ```
 
-**In the browser (or anywhere the SDK runs)**, wrap `canopy.db.sql()` with
-Drizzle's proxy driver:
+**In the browser (or anywhere the SDK runs)**, wrap `canopy.db.sql()` the same
+way:
 
 ```ts title="src/db.ts"
 import { drizzle } from "drizzle-orm/sqlite-proxy";
@@ -143,9 +149,6 @@ export const db = drizzle(async (sql, params, method) => {
 });
 ```
 
-(On a postgres site use `drizzle-orm/pg-proxy` the same way; in a GCP project
-worker, `env.DB.query(text, params)` fits `pg-proxy` directly.)
-
 ## Rehearsing on staging
 
 The safest way to try a migration is on the project's staging channel — a

package/dist/docs/platform-assistant.md

@@ -0,0 +1,50 @@
+---
+title: The Canopy assistant
+description: Ask questions about your projects and the platform in plain language — in Slack, or from the button in the corner of the docs and the dashboard.
+---
+
+Canopy has an assistant that answers questions about **your projects** and
+**how the platform works**. It reads the same things you can see — your
+projects, their deploys, reports, AI spend, egress log and schedules — plus
+these docs, and answers with a link to the guide it answered from.
+
+It can only read. It never deploys, rolls back, changes settings or touches
+your data; asked to, it points you at the dashboard or the `canopy` CLI.
+
+## Where to ask
+
+**In the docs and the dashboard.** The floating button in the bottom-right
+corner opens a choice: send feedback, or ask the assistant. Pick the second
+and type your question. The page you're on sets the context, so on a project's
+dashboard page "how many deploys today?" already knows which project you mean.
+
+Your conversation survives a reload — come back to the tab an hour later and
+it's still there. **New chat** clears it and starts over. Only one
+conversation is kept, and it lives in your own browser.
+
+**In Slack.** DM **Canopy**, or mention **@Canopy** in a channel. Same
+assistant, same answers. In a channel linked to a project it knows which
+project you mean; replying in a report's notification thread, it knows which
+report. See [Notifications](https://docs.canopy.website/platform/notifications).
+
+## What it's good at
+
+- **"Why is my fetch failing?"** — it checks the egress log and tells you
+  which host was blocked, and where to allow it.
+- **"What happened on my project today?"** — deploys, new reports, status
+  changes.
+- **"How do I promote staging to live?"** — it looks it up in these docs
+  rather than guessing.
+- **"What's the context on this report?"** — the body, the trail, and the
+  triage notes you're allowed to see.
+
+## What it can't do
+
+- **Change anything.** Read-only, by design.
+- **See projects you can't.** Every lookup runs as you: a project you're not
+  on simply doesn't resolve.
+- **Answer questions about your app's own content.** It knows Canopy and your
+  projects on it — not what's inside them.
+
+It runs on a small daily budget shared by everyone. On the rare day that runs
+out, it says so and comes back the next.

package/dist/docs/platform-egress.md

@@ -13,8 +13,8 @@ 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.
+> **Note:** Enforcement happens outside your code, on every site — so the rule holds even if your project
+> tries to route around it. Same rule, same error, one allowlist.
 
 ## Allowing a host
 

package/dist/docs/platform-feedback.md

@@ -18,6 +18,9 @@ boards.
 
 - Appears only for **signed-in Monks**. Client-password visitors never see it —
   the platform doesn't even send them the script.
+- On Canopy's own pages (these docs and the dashboard) the same button also
+  opens [the assistant](https://docs.canopy.website/platform/assistant); on your project it is a feedback
+  widget and nothing else.
 - 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

package/dist/docs/{notifications.md → platform-notifications.md}

@@ -1,6 +1,6 @@
 ---
-title: Slack notifications
-description: Canopy DMs you about your reports and projects — replies, new reports, blocked fetches, budget hits, failing schedules — and answers questions when you ask.
+title: Notifications
+description: Canopy DMs you on Slack about your reports and projects — replies, new reports, blocked fetches, budget hits, failing schedules.
 ---
 
 Canopy sends you Slack DMs when something on the platform needs your
@@ -51,6 +51,10 @@ for that it points you at the dashboard or the CLI. In a channel that's
 linked to a project, it already knows which project you mean; replying in a
 report's notification thread, it knows which report.
 
+The same assistant answers from the button in the corner of these docs and
+the dashboard, if you'd rather not switch to Slack — see
+[The Canopy assistant](https://docs.canopy.website/platform/assistant).
+
 ## If DMs don't arrive
 
 The bot finds you by your work email. If your Slack account uses a different

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

@@ -69,8 +69,8 @@ then run `canopy dev --local --pull` for a throwaway sandbox seeded with 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.
+to the underlying database, so anything that database supports works. Which
+one your site runs — SQLite or Postgres — your code can ask with
+`canopy.db.dialect()`.
 
 - [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

@@ -100,4 +100,4 @@ stable contract between the dashboard and your handler.
 - **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.
+- [How the platform serves your project](https://docs.canopy.website/developers/architecture) — Where your backend runs, and what it can reach — the same environment a scheduled run gets.

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

@@ -15,7 +15,7 @@ the CLI targets them.
 | ----------- | --------------------- | ------------------------------------------------- |
 | `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.                  |
+| `gcp-pilot` | `*.canopy.monks.zone` | A pilot installation, used for evaluation work.   |
 
 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

package/dist/docs/platform-slack.md

@@ -0,0 +1,85 @@
+---
+title: Slack
+description: Give your project its own Slack bot — Canopy creates and manages the app, your code handles the events.
+---
+
+Your project can have its own Slack app: its own name and bot, in whatever
+workspace you choose. Canopy creates the app, keeps its settings in sync,
+holds every credential, and routes Slack's traffic to your backend. Your
+code never sees a bot token, a signing secret, or a webhook — it exports a
+handler and calls `canopy.slack`, both covered in
+[the SDK reference](https://docs.canopy.website/sdk/slack).
+
+Everything on this page happens on the project's **Services** tab.
+
+## One-time: your configuration token
+
+Creating Slack apps requires a Slack _app configuration token_, which is
+personal — it belongs to you, in one workspace. You set it up once and every
+project you manage shares it:
+
+1. Go to [api.slack.com/apps](https://api.slack.com/apps) and pick the
+   workspace your bots should live in — **that choice is baked into the
+   token**, and it's where every app you create will land.
+2. Under "Your App Configuration Tokens", generate a token and copy the
+   **refresh token** (the one starting `xoxe-1-`). The access token isn't
+   needed.
+3. Paste it into the token section of any project's Services tab and save.
+
+Canopy validates it against Slack, stores it encrypted, and keeps it fresh
+from then on — this is genuinely one-time. If it ever stops working (for
+example, it was revoked), existing bots keep running; only app-settings
+changes pause until you paste a fresh one.
+
+To create bots in a different workspace — a client's, say — generate a token
+for that workspace and save it. One workspace at a time per person.
+
+## Creating the app
+
+Name the bot, pick its features, create. Every app comes with a bot that can
+be invited to channels, post messages, and send people direct messages — the
+notification baseline, no options needed. On top of that:
+
+- **AI assistant** — people can chat with the bot: by @-mentioning it in
+  channels, in direct messages, and in Slack's assistant pane. Without it
+  the bot only sends; nobody can talk back. One caveat from Slack's side:
+  once on, it can't be turned off again.
+- **Slash commands** — each becomes a workspace command handled by your
+  backend. Command names aren't reserved per app, so pick ones another app
+  in the workspace isn't already using.
+
+## Installing to the workspace
+
+Creating the app doesn't put it in the workspace — installing does, and
+that's a human step by design: you approve the bot's permissions on Slack's
+own screen. Click **Install to workspace** and follow it through.
+
+If your workspace requires admin approval for new apps, the first attempt
+becomes an approval request instead. Once the admin approves (Slack DMs you
+about it), come back and click install again.
+
+The same button reappears whenever you change features in a way that needs
+new permissions — the card shows a clear warning when saved changes are
+waiting on a reinstall. Feature changes that don't widen permissions apply
+immediately.
+
+## Day to day
+
+- **The status line** shows where the app is installed and when Slack last
+  delivered something — the quickest "is it wired up" check.
+- **Enabled** is the kill switch: off, Slack traffic is accepted and
+  dropped, nothing reaches your code, and outbound sends are refused. The
+  app stays installed; flip it back anytime.
+- **Remove Slack app** deletes the app from the workspace too — bot,
+  commands, history access, all of it.
+
+Every message your project sends through the bot is counted per day, so a
+runaway loop is visible.
+
+## Local development
+
+Slack needs a public URL to deliver to, so `canopy dev` can't receive
+events or commands. Test inbound handling on a deployed project — a scratch
+project with a scratch bot works well — and unit-test your handler directly.
+Outbound (`canopy.slack.api`) works from `canopy dev` like any other SDK
+call.

package/dist/docs/sdk-files.md

@@ -37,8 +37,9 @@ Every upload (and every `list` entry) is described by a `BlobObject`:
 const blob = await canopy.blob.get("notes.txt");
 const text = await blob?.text();
 
-// getUrl(key) → Promise<{ url: string; expiresAt: string }>
+// getUrl(key, options?) → Promise<{ url: string; expiresAt: string }>
 const { url, expiresAt } = await canopy.blob.getUrl("avatars/arjan.png");
+const long = await canopy.blob.getUrl("packs/brand.zip", { expiresIn: 3600 });
 ```
 
 `get` returns the content as a standard `Blob`, typed with the MIME type it
@@ -52,6 +53,15 @@ links, media elements — and prefer `get` when your code needs the content.
 Request a fresh URL when you render rather than storing one: it expires at
 `expiresAt`.
 
+A URL lasts **10 minutes** by default. Pass `expiresIn` (seconds) when a link
+has to outlive that — a download a person starts later, or a sync tool that
+works through a batch of files without coming back for a new link each time.
+The platform caps a lifetime at **24 hours**; ask for more and you get 24
+hours rather than an error, so trust `expiresAt` over what you asked for. A
+lifetime that isn't a whole number of seconds above zero is rejected. Keep the
+window as short as the job needs — anyone holding the URL can download the
+file until it expires.
+
 ## Listing and deleting
 
 ```ts