@mediamonks/canopy-cli 0.4.5 → 0.5.1

package/dist/docs/static-serving.md

@@ -0,0 +1,318 @@
+# How static files are served
+
+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. On Cloudflare
+there is no origin server running the project's code — the platform serves
+pre-built static files. (On the GCP target, `/api/*` requests dispatch to a
+per-project Cloud Run backend; everything else is still static serving. On
+Cloudflare, per-project workers remain a Phase 2 TODO and the capability is
+gated off.)
+
+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; a per-project origin isolation (Phase 2 dev workers) 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

@@ -47,6 +47,20 @@ Run it on your own laptop.
 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: on the Cloudflare target,
+per-project worker backends, dashboard schedules, and secret injection are not
+available and answer this error (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.
+
 ## Docs are stale
 
 `canopy docs` caches the platform's docs. Force a refresh:

package/dist/{docs-UYzmzpz-.mjs → docs-DvSPpSIR.mjs}

@@ -1,4 +1,5 @@
-import { l as readConfig, n as reportErrors } from "./ui-D1DXoDN1.mjs";
+import { n as siteConfig } from "./site-BJjoePQS.mjs";
+import { n as reportErrors } from "./ui-DThlyHgo.mjs";
 import { defineCommand } from "citty";
 import { existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
@@ -7,7 +8,7 @@ import { fileURLToPath } from "node:url";
 //#region src/docs.ts
 /**
 * canopy docs — user/agent-facing guides, served live by the platform
-* (GET /v1/docs) so they never go stale, with a local cache and a bundled
+* (GET /control/v1/docs) so they never go stale, with a local cache and a bundled
 * snapshot as offline fallbacks.
 *
 * The platform requires a login for docs (internal platform), so fetches carry
@@ -45,7 +46,7 @@ function parseFrontmatter(raw) {
 }
 /** Bearer header from the deploy token (CI) or the CLI login, if either exists. */
 function authHeaders() {
-	const token = process.env["CANOPY_DEPLOY_TOKEN"] || readConfig().token;
+	const token = process.env["CANOPY_DEPLOY_TOKEN"] || siteConfig().token;
 	return token ? { authorization: `Bearer ${token}` } : {};
 }
 async function fetchRes(url) {
@@ -114,9 +115,9 @@ function bodyFromFallback(slug) {
 	if (file && existsSync(file)) return parseFrontmatter(readFileSync(file, "utf8")).body;
 }
 async function listTopics(refresh) {
-	const { apiUrl } = readConfig();
+	const { apiUrl } = siteConfig();
 	if (refresh || !cacheFresh()) {
-		const data = await fetchJson(`${apiUrl}/v1/docs`);
+		const data = await fetchJson(`${apiUrl}/control/v1/docs`);
 		if (data?.topics) {
 			writeCache("index.json", JSON.stringify({
 				fetchedAt: (/* @__PURE__ */ new Date()).toISOString(),
@@ -128,9 +129,9 @@ async function listTopics(refresh) {
 	return topicsFromFallback();
 }
 async function readTopic(slug, refresh) {
-	const { apiUrl } = readConfig();
+	const { apiUrl } = siteConfig();
 	if (refresh || !existsSync(join(cacheDir, `${slug}.md`))) {
-		const body = await fetchText(`${apiUrl}/v1/docs/${encodeURIComponent(slug)}`);
+		const body = await fetchText(`${apiUrl}/control/v1/docs/${encodeURIComponent(slug)}`);
 		if (body !== void 0) {
 			writeCache(`${slug}.md`, body);
 			return body;

package/dist/index.mjs

@@ -1,6 +1,7 @@
 #!/usr/bin/env node
-import { t as version } from "./package-Bnu23N0A.mjs";
-import { i as runRefresh, r as notifyOfUpdate } from "./version-check-CoWgQs2h.mjs";
+import { t as version } from "./package-CHoZKzaw.mjs";
+import { r as siteHeaderLine, t as setInvocationProfile } from "./site-BJjoePQS.mjs";
+import { i as runRefresh, r as notifyOfUpdate } from "./version-check-Cuh6HaLX.mjs";
 import { defineCommand, runMain } from "citty";
 //#region src/index.ts
 /**
@@ -15,12 +16,43 @@ import { defineCommand, runMain } from "citty";
 *   token create|list|revoke   deploy tokens for CI               [phase 2]
 *   db pull|snapshot|restore                                      [phase 2]
 *   logs                  tail the project's worker logs          [phase 2]
+*   usage                 AI spend + storage for a project        [phase 1]
 *   open                  open the deployed project / dashboard   [phase 1]
 */
 if (process.env["CANOPY_UPDATE_REFRESH"] === "1") {
 	await runRefresh();
 	process.exit(0);
 }
+/**
+* Global `--profile <id>` / `--profile=<id>` (docs/10-cli-sites.md).
+* `login` declares its own `--profile` arg — leave it on argv for citty.
+*/
+function takeGlobalProfile(argv) {
+	if (argv[2] === "login") {
+		const i = argv.indexOf("--profile");
+		if (i !== -1 && argv[i + 1]) return argv[i + 1];
+		return argv.find((a) => a.startsWith("--profile="))?.slice(10);
+	}
+	const out = [];
+	let profile;
+	for (let i = 0; i < argv.length; i++) {
+		const arg = argv[i];
+		if (arg === "--profile" && argv[i + 1]) {
+			profile = argv[++i];
+			continue;
+		}
+		if (arg.startsWith("--profile=")) {
+			profile = arg.slice(10);
+			continue;
+		}
+		out.push(arg);
+	}
+	if (profile !== void 0) process.argv = out;
+	return profile;
+}
+const profileFlag = takeGlobalProfile(process.argv);
+if (profileFlag) setInvocationProfile(profileFlag);
+else if (process.env["CANOPY_PROFILE"]) setInvocationProfile(process.env["CANOPY_PROFILE"]);
 /** A roadmap command that has not landed yet (docs/04-roadmap.md). */
 function planned(name, description, phase) {
 	return defineCommand({
@@ -41,27 +73,29 @@ const main = defineCommand({
 		description: "canopy — create and deploy vibecoded projects"
 	},
 	subCommands: {
-		login: () => import("./login-DdNc9OjU.mjs").then((m) => m.loginCommand),
-		whoami: () => import("./login-DdNc9OjU.mjs").then((m) => m.whoamiCommand),
-		logout: () => import("./login-DdNc9OjU.mjs").then((m) => m.logoutCommand),
-		create: () => import("./projects-CK4DNxgZ.mjs").then((m) => m.createCommand),
-		init: () => import("./projects-CK4DNxgZ.mjs").then((m) => m.initCommand),
-		projects: () => import("./projects-CK4DNxgZ.mjs").then((m) => m.projectsCommand),
-		delete: () => import("./projects-CK4DNxgZ.mjs").then((m) => m.deleteCommand),
-		dev: () => import("./dev-BYv6BmcI.mjs").then((m) => m.devCommand),
-		deploy: () => import("./deploy-B064KXtr.mjs").then((m) => m.deployCommand),
-		rollback: () => import("./deploy-B064KXtr.mjs").then((m) => m.rollbackCommand),
-		download: () => import("./deploy-B064KXtr.mjs").then((m) => m.downloadCommand),
-		token: () => import("./token-yuwQTQB8.mjs").then((m) => m.tokenCommand),
-		db: () => import("./db-PpaU3V-B.mjs").then((m) => m.dbCommand),
-		open: () => import("./open-CBuZBJlv.mjs").then((m) => m.openCommand),
-		docs: () => import("./docs-UYzmzpz-.mjs").then((m) => m.docsCommand),
-		skill: () => import("./skill-h7QlCMhc.mjs").then((m) => m.skillCommand),
-		upgrade: () => import("./upgrade-sXoqYLRu.mjs").then((m) => m.upgradeCommand),
+		login: () => import("./login-BO6abf40.mjs").then((m) => m.loginCommand),
+		whoami: () => import("./login-BO6abf40.mjs").then((m) => m.whoamiCommand),
+		logout: () => import("./login-BO6abf40.mjs").then((m) => m.logoutCommand),
+		create: () => import("./projects-ijfe7Ffx.mjs").then((m) => m.createCommand),
+		init: () => import("./projects-ijfe7Ffx.mjs").then((m) => m.initCommand),
+		projects: () => import("./projects-ijfe7Ffx.mjs").then((m) => m.projectsCommand),
+		delete: () => import("./projects-ijfe7Ffx.mjs").then((m) => m.deleteCommand),
+		dev: () => import("./dev-BJ5xEwqW.mjs").then((m) => m.devCommand),
+		deploy: () => import("./deploy-alC2--pZ.mjs").then((m) => m.deployCommand),
+		rollback: () => import("./deploy-alC2--pZ.mjs").then((m) => m.rollbackCommand),
+		download: () => import("./deploy-alC2--pZ.mjs").then((m) => m.downloadCommand),
+		token: () => import("./token-BeF9zczg.mjs").then((m) => m.tokenCommand),
+		db: () => import("./db-BW1ZolWn.mjs").then((m) => m.dbCommand),
+		usage: () => import("./usage-DQpH7A3X.mjs").then((m) => m.usageCommand),
+		open: () => import("./open-DnlYDqrU.mjs").then((m) => m.openCommand),
+		docs: () => import("./docs-DvSPpSIR.mjs").then((m) => m.docsCommand),
+		skill: () => import("./skill-CW0QSbAJ.mjs").then((m) => m.skillCommand),
+		upgrade: () => import("./upgrade-CGz1yzsW.mjs").then((m) => m.upgradeCommand),
 		logs: planned("logs", "Tail worker logs", "2")
 	}
 });
 if (process.argv[2] !== "upgrade") notifyOfUpdate(version);
+if (process.argv[2] && process.argv[2] !== "--help" && process.argv[2] !== "-h") console.error(siteHeaderLine(version));
 await runMain(main);
 //#endregion
 export {};