@mediamonks/canopy-cli 0.7.10 → 0.7.12

package/dist/docs/static-serving.md

@@ -1,318 +0,0 @@
----
-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, SPA-fallback to index.html
-  │  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),
-  defaulting to `index.html`, and mapped to the R2 key
-  `deploys/<project-id>/<version>/<path>`.
-- **SPA fallback + read**: the exact asset is read first, and any miss falls
-  back to `index.html`, so client-side routes (`/settings`, `/projects/42`) all
-  resolve to the SPA entry point. The fallback `index.html` is served from a
-  per-version cache (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

@@ -1,102 +0,0 @@
----
-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/skill/canopy/SKILL.md

@@ -1,160 +0,0 @@
----
-name: canopy
-description: >-
-  Build, run, and deploy projects on Canopy — Monks' managed platform for
-  vibecoded apps (hosting + database + blob storage + AI). Use this whenever the
-  user wants to create a Canopy project, run/deploy one, manage its data or
-  deploy tokens, or asks how to use the `canopy` CLI. All platform docs are
-  available offline via `canopy docs`.
----
-
-# Canopy
-
-Canopy is Monks' managed platform for vibecoded projects. Everything is driven
-by one CLI: **`canopy`**. This skill tells you how to drive it; the CLI itself
-carries the full, always-current documentation.
-
-## First: is the CLI installed and signed in?
-
-Run these before anything else, in order:
-
-```bash
-canopy --version   # is the CLI installed?
-canopy whoami      # is there a valid login?
-```
-
-- **`canopy --version` fails / command not found** → install it:
-
-  ```bash
-  npm install -g @mediamonks/canopy-cli
-  ```
-
-  (Needs Node.js 20+. If `npm` is missing, tell the user to install Node first.)
-
-- **`canopy whoami` says not logged in / expired** → run:
-  ```bash
-  canopy login
-  ```
-  This opens the user's browser. **Then STOP and tell the user to complete the
-  sign-in in their browser.** The command waits for them and finishes on its own.
-  - Never ask for or type the user's password, OneLogin codes, or any
-    credentials yourself.
-  - Login only works on the user's own machine (it uses a `127.0.0.1` redirect).
-    If you're on a remote/headless box, tell the user — it can't complete there.
-  - `canopy login --json` gives machine-readable status if you need to parse it.
-
-Skip login if `canopy whoami` already shows a valid, unexpired token.
-
-## Then: offer to build their first project
-
-Once the CLI is installed and signed in, **do not just print a list of
-commands and stop.** The person following the getting-started prompt is often
-non-technical and expects you to drive. Take the lead:
-
-1. Ask them, in plain language, whether they'd like to create their first
-   Canopy project now — and **what it's about** (what should it do, who's it
-   for). Ask one short question at a time; wait for the answer.
-2. From their answer, pick a sensible name and template (see the template
-   guidance below — default to `spa` for anything beyond a trivial page), then
-   scaffold it for them non-interactively, e.g.
-   `canopy create "Their App Name" --template spa`.
-3. `cd` into the new folder, then keep going — build the thing they described,
-   running `canopy dev` to preview and `canopy docs`/`canopy <cmd> --help`
-   whenever you need platform details.
-
-Only fall back to handing them raw commands if they say they'd rather do it
-themselves. The goal is a working first project, not a command cheat-sheet.
-
-## Then: read the docs for whatever you're doing
-
-The CLI ships the full documentation and keeps it fresh from the platform. List
-the topics and read the relevant one _before_ running unfamiliar commands:
-
-```bash
-canopy docs            # list all topics
-canopy docs deploy     # print one topic
-```
-
-The listing is grouped by section: guides (`getting-started`, `deploy`, `dev`,
-`data`, `ci`, `troubleshooting`, …), platform feature pages (`platform-*`), a
-per-command CLI reference (`cli-<command>`, plus `cli` for the one-page
-overview), and the SDK reference (`sdk-*`). Always prefer `canopy docs` and
-`canopy <command> --help` over guessing flags — they are the source of truth
-and never go stale.
-
-## Command map (quick orientation — see `canopy docs cli` for detail)
-
-- Create a **new** project: `canopy create`
-- Set up a folder for an **existing** project (e.g. made in the dashboard):
-  `canopy init <slug>` — never use `canopy create` for a project that already
-  exists; that would register a duplicate. `canopy init <slug> .` targets the
-  current directory; add `--no-scaffold` to link an app you already have.
-- Run locally: `canopy dev` (live data) or `canopy dev --local` (offline sandbox)
-- Deploy: `canopy deploy` (add `--build` if the project has a build step)
-- Test first on staging: `canopy deploy --staging` → verify → `canopy promote`
-  (own database cloned from live; `canopy staging status | sync | destroy`)
-- Roll back: `canopy rollback`
-- Open the live site: `canopy open`
-- Manage data: `canopy db pull | snapshot | snapshots | restore | migrate`
-- Work bug reports & feedback: `canopy feedback list | show | comment | status | report`
-  — see `canopy docs platform-feedback` for the triage and reporting loops
-- CI credentials: `canopy token create | list | revoke`
-
-## Custom tables & migrations (devs; Drizzle recommended)
-
-The document API (`canopy.db.collection(…)`) needs no schema — prefer it. When
-a project defines its **own tables** (raw `canopy.db.sql()` / Drizzle), use the
-migrations flow — read `canopy docs migrations` first. The rules that prevent
-confusing failures:
-
-- Pin `"dialect"` and `"migrations"` in `canopy.json`; put ordered `.sql`
-  files in that directory (Drizzle: `npx drizzle-kit generate` writes them).
-- **There is no `DATABASE_URL` and never will be.** Never run
-  `drizzle-kit push`/`migrate`/`studio` or Drizzle's runtime `migrate()` —
-  generating is local, applying is Canopy's job: `canopy deploy` applies
-  pending migrations automatically (`canopy db migrate` applies without a
-  deploy; `canopy dev --local` applies to the sandbox on boot).
-- Never edit an applied migration (the platform refuses edited history) and
-  never reference `_canopy_*` tables.
-- **Schema change? Rehearse it on staging.** `canopy deploy --staging` applies
-  pending migrations to the staging database (a clone of live) — verify the
-  app there, then `canopy promote` replays them against live and flips the
-  version. Never promote with failing checks.
-
-## Choosing a starter template (`canopy create` / `canopy init`)
-
-Both `canopy create` and `canopy init` scaffold from the same three templates.
-**`static` is the default, but reach
-for it only when the app is genuinely trivial** — a page or two with light SDK
-use. Its SDK is served untyped from the platform (`/_api/data/v1/sdk.js`): no
-autocomplete, no type-checking, mistakes only show up in the browser.
-
-Prefer **`spa`** the moment either is true — which covers most real projects:
-
-- **You lean on the SDK** (`db` queries, `blob`, `ai` — anything past a stray
-  `auth.user()`). `spa` installs the SDK from npm (`@mediamonks/canopy`), fully
-  typed, so the compiler catches mistakes as you write them.
-- **The app will grow.** `spa` is Vite + React + TypeScript, giving components,
-  routing, and state a real home; `static` has no build step to organise into.
-
-Use **`worker`** when you need server-side backend code — e.g. calling an
-external API with a secret the browser can't hold, or running scheduled jobs.
-It's `spa` plus Hono-style handlers in `worker/`; `canopy deploy` publishes
-the frontend and the worker together.
-
-Non-interactive: `canopy create "My App" --template spa`. **When unsure between
-`static` and `spa`, pick `spa`.**
-
-## Safety rules
-
-- **Destructive commands** — `canopy db restore` and `canopy delete` wipe data.
-  Confirm intent with the user first, and take a `canopy db snapshot` before
-  restores.
-- **Deploys are public.** `canopy deploy` makes a version live. Confirm before
-  deploying unless the user clearly asked you to.
-- Keep the CLI current: `canopy upgrade` (this also refreshes this skill).
-- **A `canopy` command itself failing?** First rule out user error (re-read
-  `canopy docs troubleshooting` and the command's `--help`). If the platform
-  really misbehaved, check `canopy feedback mine` for a duplicate, then file it:
-  `canopy feedback report "<what happened>" --command "<the command>" --error "<output>"`
-  — it reaches the platform team directly (no `--project` needed).

package/dist/templates/spa/.github/workflows/canopy-deploy.yml

@@ -1,34 +0,0 @@
-# Deploy to Canopy on every push to main. GitHub's runners are the build
-# farm — the platform owns no build infrastructure.
-#
-# Needs a CANOPY_DEPLOY_TOKEN repo secret: create a deploy token in the
-# dashboard (project → Settings → Deploy tokens) or with `canopy token
-# create`, then add it via `gh secret set CANOPY_DEPLOY_TOKEN` or the repo's
-# Settings → Secrets. Until the secret is set, this workflow skips itself
-# instead of failing the build.
-name: Deploy to Canopy
-
-on:
-  push:
-    branches: [main]
-
-jobs:
-  deploy:
-    runs-on: ubuntu-latest
-    env:
-      CANOPY_DEPLOY_TOKEN: ${{ secrets.CANOPY_DEPLOY_TOKEN }}
-    steps:
-      - uses: actions/checkout@v4
-      - uses: actions/setup-node@v4
-        with:
-          node-version: 22
-      - name: Install dependencies
-        if: env.CANOPY_DEPLOY_TOKEN != ''
-        run: |
-          if [ -f package-lock.json ]; then npm ci; else npm install; fi
-      - name: Deploy
-        if: env.CANOPY_DEPLOY_TOKEN != ''
-        run: npm exec --yes @mediamonks/canopy-cli deploy
-      - name: Skipped (no deploy token)
-        if: env.CANOPY_DEPLOY_TOKEN == ''
-        run: echo "CANOPY_DEPLOY_TOKEN secret not set — skipping deploy."

package/dist/templates/spa/AGENTS.md

@@ -1,47 +0,0 @@
-# {{name}} — a Canopy React SPA
-
-A Vite + React single-page app on [Canopy](https://dashboard.thanarie.dev),
-Monks' managed platform for internal projects. Everything is served behind
-company login; there is no infrastructure to manage and none should be added.
-
-## Canopy skill
-
-The full SDK reference (auth, db, blob, ai) and platform guardrails ship as an
-agent skill, kept out of this scaffold so it stays current. Install it before
-building features:
-
-```
-npx skills add mediamonks/canopy
-```
-
-If that fails the skill isn't published yet — the SDK surface is documented on
-the [Canopy dashboard](https://dashboard.thanarie.dev).
-
-## Working on this project
-
-- A standard Vite + React + TypeScript app; `npm install` once, then develop
-  with `canopy dev` (it runs Vite with this project's `vite.config.ts` and
-  proxies `/_api` to the platform).
-- The SDK comes from npm (`@mediamonks/canopy`) — the shared instance lives in
-  `src/canopy.ts`.
-- `canopy dev` uses LIVE project data: read freely, but take a
-  `canopy db snapshot` before risky data changes.
-- `canopy dev --local [--pull]` — offline sandbox with local data instead;
-  writes never reach the platform. Prefer it for destructive experiments.
-- `canopy deploy` — builds (`npm run build`) and publishes `dist/`; live
-  (behind company login) at https://{{slug}}.thanarie.dev.
-- Risky change (schema migration, backend rework)? `canopy deploy --staging`
-  first — a private copy with its own database cloned from live — verify, then
-  `canopy promote` ships the exact tested version. Never promote with failing
-  checks.
-
-## Boundaries
-
-- Do not add auth — the platform authenticates every request before it
-  reaches this app.
-- Do not store secrets anywhere in this project, and never call external APIs
-  that need them from the browser — all backend needs go through the Canopy
-  SDK (`canopy.auth`, `canopy.db`, `canopy.blob`, `canopy.ai`).
-- Frontend only: no SSR, no custom servers, no databases outside `canopy.db`.
-  (Need backend code? Recreate on the `worker` template, or ask the Canopy
-  team.)