@mediamonks/canopy-cli 0.7.12 → 0.7.13

package/dist/docs/sdk.md

@@ -0,0 +1,126 @@
+---
+title: Using the SDK
+description: One typed client for auth, data, files, AI, and services — no keys, no connection strings, the platform authenticates for you.
+---
+
+`@mediamonks/canopy` is a thin, typed client over the platform's project API.
+One `createCanopy()` call gives you five modules — `auth`, `db`, `blob`, `ai`,
+and `services` — and that is the entire surface. There are no API keys,
+connection strings, or environment variables to manage: every call rides the
+session the platform already established before your code ran.
+
+The same code works everywhere your project runs — in the browser during
+`canopy dev`, in the deployed site, and in a project's backend worker.
+
+## Getting the SDK
+
+You usually don't install anything. The `spa` and `worker` templates ship with
+`@mediamonks/canopy` in `package.json`; the `static` template imports the same
+bundle straight from the platform, untyped but always version-matched to the
+API:
+
+```ts
+// spa / worker templates (typed, from npm)
+import { createCanopy } from "@mediamonks/canopy";
+
+// static template (untyped, served by the platform)
+import { createCanopy } from "/_api/data/v1/sdk.js";
+```
+
+## createCanopy(config)
+
+`createCanopy` takes an optional config object and returns the client:
+
+```ts
+import { createCanopy } from "@mediamonks/canopy";
+
+const canopy = createCanopy();
+// canopy.auth, canopy.db, canopy.blob, canopy.ai, canopy.services
+```
+
+| Option    | Type           | Default        | What it does                                                                                                          |
+| --------- | -------------- | -------------- | --------------------------------------------------------------------------------------------------------------------- |
+| `baseUrl` | `string`       | `"/_api"`      | Base URL of the platform data API. The default is same-origin, so it works untouched in the browser.                  |
+| `token`   | `string`       | none           | A project-scoped `cnpy_` token sent as a bearer on every request — for scripts and CI running outside Canopy hosting. |
+| `fetch`   | `typeof fetch` | global `fetch` | Override how requests are sent — a backend worker passes its platform service binding here.                           |
+
+In the browser no config is needed. In a backend worker (the `worker`
+template), the platform is reachable through the `CANOPY` service binding, so
+create the client per request with that binding's fetch:
+
+```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();
+  return c.json({ message: `Hello from the backend, ${user.name}!` });
+});
+```
+
+Outside Canopy hosting — a local Node script, a CI job — there is no session
+and no service binding. Mint a dev token (`canopy dev` does this for you, or
+`POST /control/v1/projects/:slug/dev-token`) and pass it with the platform's
+API host:
+
+```ts
+const canopy = createCanopy({
+  baseUrl: "https://api.canopy.website",
+  token: process.env.CANOPY_TOKEN, // a project-scoped cnpy_ token
+});
+```
+
+## One instance, shared
+
+In the browser, create the client once and import it everywhere. The scaffolds
+do this in `src/canopy.ts`:
+
+```ts
+// src/canopy.ts
+import { createCanopy } from "@mediamonks/canopy";
+
+export const canopy = createCanopy();
+```
+
+## Error handling
+
+Any call that fails throws a `CanopyError` (exported from the package). It
+extends `Error` with the HTTP `status` of the failed request; `message` carries
+the response body when the platform sent one:
+
+```ts
+import { CanopyError } from "@mediamonks/canopy";
+
+try {
+  await canopy.db.collection("todos").insert({ title: "hi", done: false });
+} catch (err) {
+  if (err instanceof CanopyError && err.status === 403) {
+    // e.g. a viewer hitting a write — show a friendly message
+  }
+  throw err;
+}
+```
+
+Two read calls are deliberately soft instead: `collection.get(id)` and
+`blob.get(key)` resolve to `null` for a missing document or object rather than
+throwing.
+
+## Where it runs
+
+The client is plain `fetch` underneath, so behavior is identical across
+environments:
+
+- **Browser, deployed** — calls go to same-origin `/_api`; the platform
+  authenticated the visitor before your page loaded, and the session cookie
+  rides along automatically.
+- **Browser, `canopy dev`** — the dev server proxies `/_api` to the platform
+  with your CLI login, so local code talks to your project's real data.
+- **Backend worker** — pass the `CANOPY` service binding's fetch (shown
+  above); the incoming request's identity carries through, so `auth.user()`
+  and per-project budgets behave exactly as in the browser.
+
+## Modules
+
+- [Auth](https://docs.canopy.website/sdk/auth) — who is signed in, and ending sessions.
+- [Database](https://docs.canopy.website/sdk/database) — document collections, plus a raw SQL escape hatch.
+- [Files](https://docs.canopy.website/sdk/files) — private blob storage under the project's prefix.
+- [AI](https://docs.canopy.website/sdk/ai) — metered, budget-capped LLM access.
+- [Services](https://docs.canopy.website/sdk/services) — curated internal data services.

package/dist/docs/staging.md

@@ -0,0 +1,106 @@
+---
+title: Staging & promoting
+description: Deploy to a safe copy of your project first — own database cloned from live — then promote the exact same version.
+---
+
+Every project can have a **staging channel**: a second, private copy of the
+app with its own database (cloned from live), its own files, and its own
+backend, served at
+
+```
+https://staging-dot-<slug>.canopy.website
+```
+
+behind the same sign-in as the live site. Deploy there first, click around
+against real-shaped data, then **promote** — the exact version you tested
+becomes live, nothing is rebuilt.
+
+You don't set anything up. The first staged deploy creates the channel and
+copies the live database into it.
+
+## The workflow
+
+```bash
+canopy deploy --staging   # build + deploy to staging (created on first use)
+canopy open --staging     # check it in the browser
+canopy promote            # happy? make that version live
+```
+
+`canopy deploy --staging` is the normal deploy in every way — same build, same
+versioning — except the result serves on the staging URL and the live site is
+untouched. Versions share one sequence: if live is at v7 and you stage v8,
+promoting makes that same v8 live.
+
+`canopy promote` is not a redeploy: the platform re-uses the exact files and
+backend bundle you staged. If migrations were rehearsed on staging, they replay
+against the live database first (with an automatic snapshot), then the pointer
+flips.
+
+## Testing schema migrations
+
+This is the staging channel's superpower. Because the staging database starts
+as a copy of live, a migration that works there will behave the same way on
+the real thing:
+
+```bash
+canopy deploy --staging      # pending migrations apply to the STAGING database
+# … verify the app against the migrated copy …
+canopy promote               # the same migrations replay against live, then v goes live
+```
+
+A migration that fails on staging costs you nothing — live never saw it. See
+[Schema migrations](https://docs.canopy.website/guides/migrations) for the migration system itself.
+
+## Staging an older version
+
+Any version in the deploy history can be pointed at the staging channel —
+from the dashboard's deploy list (the **Stage** action, next to Rollback) or
+with `canopy staging use v3`. Like rollback, it's a pointer move: nothing is
+rebuilt, and live is untouched. Handy for comparing an old build against the
+staging data, or re-testing a version before promoting it.
+
+## Keeping staging fresh
+
+Staging data drifts as you test. Re-clone it from live anytime:
+
+```bash
+canopy staging sync          # replace staging data with a fresh copy of live
+canopy staging status        # what's staged vs live
+```
+
+Writes on staging never flow back to live — promote moves code and schema, not
+data.
+
+## What's shared, what's separate
+
+Separate per channel: the database, uploaded files, and the backend worker.
+Shared with live: members, secrets, the client password, schedules (they run
+against live only), and the AI budget — staging traffic counts against the
+same cap.
+
+## Developing against staging data
+
+Remote dev can point at the staging database instead of live — useful while a
+schema is in flux:
+
+```bash
+canopy dev --staging
+```
+
+## Cleaning up
+
+```bash
+canopy staging destroy       # removes the staging database, files and backend
+```
+
+Live is untouched, and the next `canopy deploy --staging` recreates the channel
+from a fresh copy. The dashboard's Settings tab has the same controls, the
+Overview tab shows what's staged with a Promote button, and a Live/Staging
+toggle above the Data and Files tabs browses either channel's data.
+
+## Staging vs version previews
+
+Version preview URLs (`v12-dot-<slug>`) show an old **frontend** against the
+**live** data — good for comparing builds. The staging channel is the full
+package: candidate frontend, candidate backend, and its own database. Use
+previews to look backwards, staging to look forwards.

package/dist/docs/static-serving.md

@@ -0,0 +1,323 @@
+---
+title: How static files are served
+description: The full path a browser request takes to a deployed file.
+---
+
+This explains the full path a browser request takes to receive a deployed
+project's `index.html` and its assets (JS/CSS/images/fonts), and reviews that
+path from a **security** and a **performance** angle.
+
+Everything a visitor sees is a _deployed_ build stored in R2 — the platform
+serves pre-built static files. (When a project has a backend worker, `/api/*`
+requests dispatch to it — Workers for Platforms on Cloudflare, Cloud Run on
+GCP; everything else is still static serving.)
+
+Asset serving is the hottest **data-plane** path (see
+[`docs/09-plane-split.md`](../09-plane-split.md)): it lives at
+`/data/v1/assets/*`, and the URL carries no project slug — the gateway stamps
+which project the request is for.
+
+## The request path
+
+A request to `https://<slug>.canopy.<domain>/some/path` flows through two
+Workers and one R2 bucket:
+
+```
+Browser
+  │  GET https://dashboard.canopy.example.com/assets/app-a1b2.js
+  ▼
+canopy-gateway  (apps/gateway/src/index.ts)
+  │  1. Parse <slug> (and optional pinned version) from the hostname
+  │  2. Enforce auth — OneLogin session cookie, or client-password cookie
+  │  3. Rewrite path → /data/v1/assets/<path>  (+ ?v=<n> if pinned),
+  │     stamping X-Canopy-Project: <slug> + an internal JWT vouching for it
+  ▼  env.API.fetch(...)  (service binding, no public hop)
+canopy-api  (apps/api/src/routes/assets.ts)
+  │  4. Resolve the project from the stamp + which version is live
+  │  5. Sanitize the asset path; directory index, else SPA fallback
+  │  6. R2 GET  deploys/<project-id>/<version>/<path>
+  ▼
+R2 bucket "canopy-assets"
+```
+
+### 1–3. Gateway: hostname, auth, path rewrite
+
+[`apps/gateway/src/index.ts`](../../apps/gateway/src/index.ts) is the front door
+for every `*.canopy.<domain>` request.
+
+- **Hostname → slug + version.** `parseHost()`
+  ([`index.ts`](../../apps/gateway/src/index.ts)) splits the first DNS label.
+  A plain `dashboard` resolves to that project's _live_ version; a
+  `v12-dot-dashboard` prefix pins version 12 of the **frontend only** — auth,
+  client access, and the data plane still resolve to the real project, so an old
+  build previews against _current_ data rather than forking it.
+- **Auth before any project bytes.** No asset is served unauthenticated. A
+  request must carry either a valid OneLogin session cookie (verified via a
+  shared `SESSION_SECRET`) or — on client-enabled projects — a scope-limited
+  client-password cookie. Missing both: client-enabled projects get the password
+  page ([`client.ts`](../../apps/gateway/src/client.ts)), everything else
+  redirects to OneLogin. Collaborators-only projects additionally turn
+  non-members away with a members-only page before any dispatch.
+- **Path rewrite + project stamp.** Once authorized, the gateway rewrites the
+  request to the data plane and forwards it over a **service binding**
+  (`env.API.fetch`), never a public URL
+  ([`index.ts`](../../apps/gateway/src/index.ts)). The URL carries no slug —
+  the project travels as a header the gateway vouches for:
+
+  ```ts
+  const assetUrl = new URL(request.url);
+  assetUrl.pathname = `/data/v1/assets${url.pathname}`;
+  if (version !== null) assetUrl.searchParams.set("v", String(version));
+  const assetRequest = new Request(assetUrl, request);
+  assetRequest.headers.delete("x-canopy-project");
+  assetRequest.headers.set("x-canopy-project", slug);
+  assetRequest.headers.set("x-canopy-internal", await createInternalJwt(env.SESSION_SECRET));
+  return env.API.fetch(assetRequest);
+  ```
+
+  The caller's cookie travels along, so canopy-api re-verifies it independently,
+  and canopy-api trusts the `X-Canopy-Project` stamp only when the accompanying
+  internal JWT verifies.
+
+`/_api/*` requests are handled separately, forwarded to the API before the
+session wall so the SDK gets JSON 401s instead of login HTML. The plane is the
+path: `/_api/control/v1/*` forwards untouched, `/_api/data/v1/*` gets the same
+project stamp as asset requests.
+
+### 4–6. API: version resolution, path sanitizing, R2 read
+
+The serving handler is `GET /data/v1/assets/*` in
+[`apps/api/src/routes/assets.ts`](../../apps/api/src/routes/assets.ts).
+
+- **Project + status.** Resolves the project from the gateway's vouched stamp
+  only (`vouchedProject` — never a query string), via a cached
+  `ProjectSnapshot` from the `ProjectDirectory`
+  ([`src/directory.ts`](../../apps/api/src/directory.ts)) — the data plane
+  never queries the control database directly. Unknown → 404 placeholder;
+  paused (`status !== "active"`) → a "paused" placeholder page. Viewability is
+  company-wide by default; projects marked **collaborators-only**
+  (`members_only`) turn non-members away with a 403 placeholder
+  (`checkAppAccess`, [`src/access.ts`](../../apps/api/src/access.ts)).
+- **Which version.** `?v=<n>` pins an exact version (must exist in the
+  project's deploy history, else 404 — it never silently falls back to live);
+  otherwise the snapshot's `liveAssetVersion` is served, which falls back to
+  the max deployed version for legacy rows with a NULL pointer.
+- **Path → R2 key.** The tail after `/assets/` is sanitized (see Security)
+  and mapped to the R2 key `deploys/<project-id>/<version>/<path>`; the root
+  path serves `index.html`.
+- **Directory index + SPA fallback**: the exact asset is read first. On a
+  miss, an extensionless path is probed for its own directory index — `/feeds/`
+  serves `feeds/index.html` (multi-page static exports), and the slash-less
+  `/feeds` 301-redirects to `/feeds/` so the page's relative URLs resolve.
+  Only when no directory index exists does the request fall back to the root
+  `index.html`, so client-side routes (`/settings`, `/projects/42`) still all
+  resolve to the SPA entry point. Both the fallback `index.html` and the
+  per-path probe results are served from per-version caches (see
+  [Performance](#performance-review)), so a deep-linked route doesn't pay a
+  second R2 read on every request.
+
+### How assets are stored & versioned
+
+`canopy deploy` uses a two-step signed upload
+([`docs/09-plane-split.md`](../09-plane-split.md) D-d): the **control plane**
+authorizes the deploy (`POST /control/v1/projects/:slug/deploys`,
+[`deploys.ts`](../../apps/api/src/routes/deploys.ts)) and issues a short-lived
+signed grant; the CLI PUTs each file to the **data plane**
+(`PUT /data/v1/uploads/:grant`,
+[`data-plane.ts`](../../apps/api/src/routes/data-plane.ts)); a completion call
+(`POST …/deploys/:version/complete`) validates the staged bundle and records
+the version. Bundle bytes never transit the control plane.
+
+- Each file is written to R2 at `deploys/<project-id>/<version>/<path>` with its
+  `contentType` stored as R2 `httpMetadata` by the upload endpoint.
+- The bucket is `canopy-assets`, bound as `ASSETS`
+  ([`apps/api/wrangler.main.jsonc`](../../apps/api/wrangler.main.jsonc)).
+- **Immutable, append-only versioning.** A deploy bumps the version and writes a
+  new prefix; the `deployments` row commits at completion _before_
+  `live_asset_version` moves, so a half-uploaded deploy is never served (an
+  abandoned grant leaves only unreferenced staged bytes). Rollback
+  (`POST …/deploys/:version/rollback`,
+  [`deploys.ts`](../../apps/api/src/routes/deploys.ts)) just repoints
+  `live_asset_version` at an existing version — instant, nothing copied, nothing
+  deleted, and any version can be made live again. Old versions keep their bytes
+  and their identity, which is what makes `v<n>-dot-` preview hosts work.
+- Project deletion purges the whole `deploys/<project-id>/` prefix (plus blobs
+  and snapshots) so no R2 residue remains
+  ([`projects.ts`](../../apps/api/src/routes/projects.ts)).
+
+The browser SDK itself is served by the platform, not from a deploy bundle:
+`GET /_api/data/v1/sdk.js` returns an inlined bundle
+([`data-plane.ts`](../../apps/api/src/routes/data-plane.ts)) so scaffolded
+projects need no `npm install`.
+
+---
+
+## Security review
+
+### What's solid
+
+- **Nothing is public.** Every asset request passes the gateway auth wall
+  (OneLogin session or client-password cookie) before any project bytes are
+  read, and the gateway→API hop is a private service binding, not an internet
+  URL. This is the north-star "never public URLs" guarantee.
+- **Path-traversal defense.** `safeAssetPath()`
+  ([`assets.ts`](../../apps/api/src/routes/assets.ts)) rejects on both
+  ingest (the upload endpoint) and serve: strips a leading `./` or `/`, then
+  rejects empty paths, paths over 512 chars, and any path containing `\`, `//`,
+  `\0`, or a `.`/`..`/empty segment. A malicious key can't escape the
+  `deploys/<project-id>/<version>/` prefix, and one project can never read
+  another's bytes because the prefix is keyed by the resolved project id.
+- **Tenant isolation by key prefix and by stamp.** The R2 key always embeds the
+  resolved `project.id`, so cross-project reads are structurally impossible even
+  if a path slipped through. Serving resolves its project from the gateway's
+  vouched `X-Canopy-Project` stamp alone — never a query parameter — so a
+  crafted query string can't render one project's pages under another's host.
+- **Content-Type is fixed at deploy time**, from an allowlist keyed by extension
+  (`contentTypeFor()`, [`assets.ts`](../../apps/api/src/routes/assets.ts)),
+  and stored as R2 metadata by the upload endpoint. Serving echoes that stored
+  type; unknown extensions become `application/octet-stream` (download, not
+  execute). The type is never derived from request input at serve time.
+- **Deploy bundle limits.** Max 500 files and 25 MB total
+  ([`storage-keys.ts`](../../apps/api/src/storage-keys.ts)), enforced per file
+  at upload and re-checked over the staged inventory at completion; a bundle
+  must contain `index.html` or completion is rejected — bounds the blast radius
+  of a bad upload. Upload grants are HMAC-signed, project- and version-bound,
+  and expire after 15 minutes ([`upload-grant.ts`](../../apps/api/src/upload-grant.ts)).
+- **Password page escapes untrusted input.** `escapeHtml()` and the same-site
+  `safeLocalPath()`/`safeReturnTo()` guards prevent reflected-XSS and open-redirect
+  via the `returnTo` parameter
+  ([`client.ts`](../../apps/gateway/src/client.ts),
+  [`index.ts`](../../apps/gateway/src/index.ts)).
+- **Version pinning can't leak data.** A `v<n>-dot-` host pins only _which
+  frontend build_ is served; auth, client-access, and all `/_api` data-plane
+  calls resolve to the real project (the stamp names the real slug),
+  so an old build cannot be used to read a different project's data.
+
+### Gaps / things to weigh
+
+These are observations, not known incidents — worth a conscious decision:
+
+1. **No hardening response headers.** Served assets carry `content-type`, `etag`,
+   and `cache-control` only ([`assets.ts`](../../apps/api/src/routes/assets.ts)).
+   There is **no** `X-Content-Type-Options: nosniff`, no `Content-Security-Policy`,
+   no `X-Frame-Options`/`frame-ancestors`, no `Referrer-Policy`, and no HSTS. For
+   an app platform serving arbitrary user HTML/JS on shared `*.canopy.<domain>`
+   subdomains, the most impactful additions are:
+   - `X-Content-Type-Options: nosniff` — cheap, prevents MIME-sniffing of e.g. a
+     user-uploaded file into script.
+   - `frame-ancestors`/`X-Frame-Options` — clickjacking, and stops one canopy
+     subdomain from framing another.
+   - A default `Content-Security-Policy` (even a permissive one) as a baseline.
+     Note projects run against a shared cookie domain, so cross-subdomain
+     concerns (cookie scoping, framing) matter more here than on an isolated
+     site.
+2. **`text/html` is served for deployed HTML with the session cookie present.**
+   That's by design (auth-gated apps), but it means any XSS in a deployed project
+   runs on a `*.canopy.<domain>` origin that shares the session-cookie domain.
+   The session cookie's flags (HttpOnly/SameSite/Secure) in
+   [`session.ts`](../../apps/gateway/src/session.ts) are the mitigation to keep an
+   eye on; per-project origin isolation would be the stronger fix.
+3. **SPA fallback returns `index.html` with 200 for unknown paths**, including
+   things that look like missing assets (`/assets/typo.js` → HTML). That's normal
+   SPA behavior but can mask 404s and, combined with #1, is another reason
+   `nosniff` matters (an HTML body served where a script was expected).
+4. **Serving is company-wide readable by default.** Any authenticated monk can
+   view any active project unless it opts into collaborators-only
+   (`members_only`, enforced in [`assets.ts`](../../apps/api/src/routes/assets.ts)
+   via `checkAppAccess`). The default is an intentional product decision (see
+   docs/02-decisions.md), not a bug — but it means "authenticated" ≠
+   "authorized for this specific project" on the read path unless the project
+   tightens it.
+
+---
+
+## Performance review
+
+### What helps
+
+- **Split caching policy by type** ([`assets.ts`](../../apps/api/src/routes/assets.ts)):
+
+  ```ts
+  "cache-control": type.startsWith("text/html")
+    ? "no-cache"                 // HTML always revalidates → new deploys show up
+    : "private, max-age=3600",   // hashed subresources cache for 1h
+  ```
+
+  HTML revalidates so a fresh deploy is picked up immediately; hashed JS/CSS/font
+  assets cache in the browser for an hour. This is the right shape for a
+  content-hashed SPA build.
+
+- **ETags** (`"v<version>-<path>"`, [`assets.ts`](../../apps/api/src/routes/assets.ts))
+  give a stable validator per version+path, so revalidation of `no-cache` HTML
+  can come back as a cheap `304`. Because the etag encodes the version, a rollback
+  or new deploy changes the validator and busts caches correctly.
+- **Instant deploys and rollbacks.** Serving reads a pointer
+  (`live_asset_version`); deploy/rollback move the pointer without copying bytes,
+  so there's no propagation delay and no rebuild.
+- **Service-binding hop.** Gateway→API is an in-Cloudflare service binding, not a
+  public fetch, so there's no extra internet round-trip or TLS handshake between
+  the two Workers.
+
+### Bottlenecks / opportunities
+
+1. **`max-age=3600` is modest for hashed assets.** Content-hashed filenames (the
+   Vite default) can safely use `public, max-age=31536000, immutable`. The current
+   value is `private` (see #2) and only an hour, so returning visitors refetch
+   more than necessary. Consider keying on filename hash pattern or a deploy-time
+   flag to mark truly immutable assets.
+2. **`private` prevents any shared/edge caching.** Because assets are auth-gated
+   and served `private`, they can't be cached by Cloudflare's CDN or any shared
+   proxy — every cache miss goes Worker→R2. For an auth-walled platform that's a
+   deliberate trade (privacy over edge-cache hit rate), but it means R2 latency is
+   on the critical path for every uncached request. If per-project caching is ever
+   wanted, the Cache API keyed by (project, version, path) inside the Worker would
+   let you cache without making anything public.
+3. **No compression / `Content-Encoding`.** The handler streams R2 bytes as-is
+   with no gzip/brotli negotiation and ignores `Accept-Encoding`. Cloudflare may
+   apply compression at the edge for eligible content types, but nothing is stored
+   pre-compressed and the Worker doesn't negotiate it. For large JS bundles,
+   storing brotli-precompressed variants (or relying on and verifying edge
+   compression) is worth measuring.
+4. **Range requests / streaming media.** The handler returns the full R2 object
+   body and doesn't honor `Range`. Fine for a bundled SPA; if projects ever serve
+   large video/audio, add `Range` support (R2 supports ranged `get`).
+
+### Addressed — in-worker caches
+
+Two former bottlenecks are now handled by best-effort, per-isolate caches
+(a performance layer only — never a source of truth; a cold isolate just reads
+D1/R2):
+
+- **SPA fallback no longer double-reads R2.** The serve path reads the exact
+  asset once; on a miss it falls back to `index.html` served from a per-`(project,
+version)` cache ([`asset-cache.ts`](../../apps/api/src/asset-cache.ts)). Because a
+  deployed version's bytes are immutable, that entry is cached indefinitely
+  (count-bounded), so the second R2 read is paid **once per version**, not once
+  per deep-linked route. Verified by a test that serves three client routes and
+  asserts a single `index.html` read.
+- **Project state is cached per slug** as a `ProjectSnapshot` in the
+  `ProjectDirectory` ([`src/directory.ts`](../../apps/api/src/directory.ts) —
+  the generalization of the old metadata cache), sparing the hot path its
+  control-DB queries. Since this data _does_ change, deploy, rollback, and
+  delete call `invalidateSnapshot()` so a write is reflected immediately on the
+  same isolate; a short TTL (5 s) is only a backstop for a write that lands on
+  a different isolate than the next read.
+
+---
+
+## Quick reference
+
+| Concern                     | Where                                                                          | Notes                                                                  |
+| --------------------------- | ------------------------------------------------------------------------------ | ---------------------------------------------------------------------- |
+| Front door / auth / routing | [`apps/gateway/src/index.ts`](../../apps/gateway/src/index.ts)                 | Hostname→slug, auth wall, `/data/v1/assets` rewrite + project stamp    |
+| Client-password page        | [`apps/gateway/src/client.ts`](../../apps/gateway/src/client.ts)               | HTML-escaped, same-site returnTo                                       |
+| Asset serve handler         | [`apps/api/src/routes/assets.ts`](../../apps/api/src/routes/assets.ts)         | Version resolve, path sanitize, SPA fallback, headers                  |
+| Project snapshots           | [`apps/api/src/directory.ts`](../../apps/api/src/directory.ts)                 | `ProjectDirectory` cache (5 s TTL), invalidated on write               |
+| index.html cache            | [`apps/api/src/asset-cache.ts`](../../apps/api/src/asset-cache.ts)             | Per-version, immutable bytes, count-bounded                            |
+| Path sanitizing             | [`assets.ts`](../../apps/api/src/routes/assets.ts)                             | `safeAssetPath()` — traversal defense, shared with the upload endpoint |
+| Content-Type allowlist      | [`assets.ts`](../../apps/api/src/routes/assets.ts)                             | Fixed at deploy, stored in R2 metadata                                 |
+| Deploy authorize / complete | [`apps/api/src/routes/deploys.ts`](../../apps/api/src/routes/deploys.ts)       | Signed grant, 500 files / 25 MB, pointer moves last                    |
+| Upload bytes                | [`apps/api/src/routes/data-plane.ts`](../../apps/api/src/routes/data-plane.ts) | `PUT /data/v1/uploads/:grant`, grant is the credential                 |
+| Rollback                    | [`deploys.ts`](../../apps/api/src/routes/deploys.ts)                           | Repoints `live_asset_version`                                          |
+| R2 bucket binding           | [`apps/api/wrangler.main.jsonc`](../../apps/api/wrangler.main.jsonc)           | `ASSETS` → `canopy-assets`                                             |
+| SDK serving                 | [`apps/api/src/routes/data-plane.ts`](../../apps/api/src/routes/data-plane.ts) | `/_api/data/v1/sdk.js`, `public, max-age=300`                          |

package/dist/docs/troubleshooting.md

@@ -0,0 +1,102 @@
+---
+title: Troubleshooting
+description: Common errors and how to resolve them.
+---
+
+## `command not found: canopy`
+
+The CLI isn't installed or isn't on your PATH. Install it:
+
+```bash
+npm install -g @mediamonks/canopy-cli
+```
+
+If it installs but still isn't found, your npm global bin directory isn't on your
+PATH. Run `npm bin -g` to find it and add that directory to your PATH.
+
+## `Not logged in — run canopy login`
+
+You have no valid CLI token. Run `canopy login` and finish the sign-in in the
+browser. Check status with `canopy whoami`.
+
+## `Session expired — run canopy login again`
+
+Your token expired. Just run `canopy login` again.
+
+## The browser didn't open during login
+
+`canopy login` prints the sign-in URL as a fallback — open it manually in a
+browser on the **same machine** as the CLI (login uses a local loopback
+redirect, so it must be the same machine).
+
+## `Port 8976 is in use`
+
+A previous login attempt is still holding the callback port. Close it (or wait a
+moment) and retry `canopy login`.
+
+## Login hangs and never completes
+
+Login only works when the CLI runs on the machine whose browser you're using
+(the redirect goes to `127.0.0.1`). It cannot complete on a remote/headless box.
+Run it on your own laptop.
+
+## `Deploy token rejected`
+
+The `CANOPY_DEPLOY_TOKEN` was revoked or is wrong. Create a new one with
+`canopy token create` (or in the dashboard) and update your CI secret.
+
+## `not_supported_on_target` (501)
+
+Some features are platform-target-specific: a site whose platform target
+doesn't support a feature (for example per-project worker backends, dashboard
+schedules, or secret injection) answers this error, and the dashboard hides
+those panels. It's not a failure of your project — the feature doesn't exist
+on the target your platform runs on.
+
+## `ai_budget_exceeded` (429)
+
+The project hit its daily AI budget cap. The cap is enforced before every AI
+call; it resets the next day, or a maintainer can raise the project's budget in
+the dashboard.
+
+## `egress_denied` (403)
+
+An outbound `fetch` from your worker was blocked by the platform's egress
+guard: `host <hostname> is not on the project allowlist`. Outbound requests
+are deny-by-default — only platform infrastructure and the hosts on your
+project's own allowlist get through. Add the host and retry (running workers
+pick the change up without a deploy):
+
+```bash
+canopy egress allow api.example.com
+```
+
+or use dashboard Settings → Outbound hosts. Details and entry rules:
+[Outbound requests](https://docs.canopy.website/platform/egress). Calls made through the SDK /
+`env.CANOPY.fetch` don't count as egress and are unaffected.
+
+## The worker returns errors and you can't see why
+
+Read its console output instead of adding diagnostic endpoints:
+
+```bash
+canopy logs --since 15m
+```
+
+`console.log` / `console.error` from your deployed worker, straight in the
+terminal; `--follow` tails it live while you reproduce the problem. See
+[canopy logs](https://docs.canopy.website/cli/logs). (On sites without worker log capture the command
+answers `not_supported_on_target`.)
+
+## Docs are stale
+
+`canopy docs` caches the platform's docs. Force a refresh:
+
+```bash
+canopy docs <topic> --refresh
+```
+
+## Still stuck?
+
+Run the failing command again and share its full output. `canopy whoami` and
+`canopy --version` are useful to include.

package/dist/{docs-DxB7NhZs.mjs → docs-BBMVxVta.mjs}

@@ -1,7 +1,7 @@
-import { t as version } from "./package-CDLufecy.mjs";
+import { t as version } from "./package-vJXq4RNN.mjs";
 import { n as siteConfig } from "./site-BUlQR117.mjs";
 import { i as latestKnownVersion, r as compareSemver } from "./version-check-CcsA1QjI.mjs";
-import { n as reportErrors } from "./ui-2mrJcjYC.mjs";
+import { n as reportErrors } from "./ui-B1Px5y7q.mjs";
 import { defineCommand } from "citty";
 import { existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";