@mediamonks/canopy-cli 0.5.1 → 0.7.0

package/dist/docs/infrastructure.md

@@ -1,4 +1,7 @@
-# Infrastructure as code & standing up a Cloudflare account
+---
+title: Infrastructure as code
+description: Terraform for the account-level Cloudflare pieces Canopy needs.
+---
 
 Canopy's Cloudflare footprint is small on purpose: almost everything
 per-project is provisioned at runtime by canopy-api (`apps/api/src/cf.ts`,
@@ -19,8 +22,8 @@ Scope of a fresh stand-up:
 
 1. the **platform workers** — `canopy-api` and `canopy-gateway` — deployed and
    healthy (these aren't optional; nothing works without them), and
-2. the **three core projects** — `dashboard`, `www`, `kitchen-sink` — re-created
-   and deployed _on_ the platform like any other project.
+2. the **four core projects** — `dashboard`, `www`, `docs`, `kitchen-sink` —
+   re-created and deployed _on_ the platform like any other project.
 
 Everyone else's projects are **not** carried over — a new account starts with
 an empty control-plane registry (see [Non-goals](#non-goals)).
@@ -39,8 +42,8 @@ config file per Cloudflare site (same names as CLI profiles). Deployed with
 is local `wrangler dev` only.
 
 **`canopy deploy`** (`canopy.json` in each project): the core projects
-(`dashboard`, `www`, `kitchen-sink`) — ordinary platform projects that
-dogfood the product, not infrastructure.
+(`dashboard`, `www`, `docs`, `kitchen-sink`) — ordinary platform projects
+that dogfood the product, not infrastructure.
 
 **Bootstrap scripts** (`infra/scripts/`): runtime API tokens, worker secrets,
 AI Gateway BYOK keys + spend rule.
@@ -53,9 +56,9 @@ enable paid Workers products. Plus OneLogin: redirect URIs for the new host
 ## Non-goals
 
 - **No project-data migration.** Per-project D1s, R2 blobs, and deploy history
-  stay in the old account. The new control-plane D1 is empty; the three core
-  projects are re-created from scratch (they hold no precious data — `www` and
-  `dashboard` are stateless, `kitchen-sink` is a demo), and everyone else's
+  stay in the old account. The new control-plane D1 is empty; the core
+  projects are re-created from scratch (they hold no precious data — `www`,
+  `dashboard`, and `docs` are stateless, `kitchen-sink` is a demo), and everyone else's
   projects are re-created as needed. (If that ever changes, the export/import
   primitives already exist in `apps/api/src/cf.ts` and `canopy db snapshot|restore`.)
 - **No Tofu management of Workers/secrets/per-project resources** — see the
@@ -95,10 +98,15 @@ export CLOUDFLARE_ACCOUNT_ID="<account_id>"   # required when you belong to >1 a
    (You can confirm via API once the bootstrap token exists — an empty zone is
    fine.)
 4. **R2** must work (creating a probe bucket is enough to confirm). **Workers
-   Paid** and **Workers for Platforms** are _not_ required for the current CF
-   platform path (no dispatch namespaces; `capabilities.workers` is false).
-   Enable them later when you actually need paid Worker limits or Phase-2
-   per-project Workers. **No Advanced Certificate Manager** — `*.canopy.website`
+   Paid + Workers for Platforms** are required for per-project workers
+   (Phase 2 item 1, D18): once the subscriptions are active, run
+   `infra/scripts/create-dispatch-namespace.sh` to create the
+   `canopy-projects` dispatch namespace (the `dispatch_namespaces` bindings in
+   `apps/api/wrangler.main.jsonc` and `apps/gateway/wrangler.main.jsonc` fail
+   to deploy without it), and make sure `CF_API_TOKEN` carries **Workers
+   Scripts Write** (re-mint with `create-api-tokens.sh` if it predates this).
+   A site without the binding still runs — workers/schedules/secrets simply
+   answer 501. **No Advanced Certificate Manager** — `*.canopy.website`
    is a single-level wildcard covered by free Universal SSL. (ACM would only
    be needed if nesting as `*.canopy.<some-other-domain>`.)
 
@@ -283,8 +291,8 @@ If you already configured these for `canopy.website` before the move, skip.
 
 ### 10. Log in, grant yourself admin, then deploy the core projects
 
-The three core projects are ordinary platform projects that dogfood the product.
-Two of their slugs (`dashboard`, `www`) are in `RESERVED_SLUGS`
+The four core projects are ordinary platform projects that dogfood the product.
+Three of their slugs (`dashboard`, `www`, `docs`) are in `RESERVED_SLUGS`
 (`apps/api/src/routes/projects.ts`), so **only an admin can create them** —
 hence the ordering here.
 
@@ -326,6 +334,10 @@ export CANOPY_PROJECT_PROTOCOL="https"
    canopy-dev --profile main create "Canopy" --slug www --no-scaffold
    canopy-dev --profile main deploy
 
+   cd ../docs
+   canopy-dev --profile main create "Canopy Docs" --slug docs --no-scaffold
+   canopy-dev --profile main deploy
+
    cd ../../examples/kitchen-sink
    canopy-dev --profile main create "Kitchen Sink" --slug kitchen-sink --no-scaffold
    # CF target: capabilities.workers = false — strip worker for this deploy
@@ -371,7 +383,7 @@ same as the old `thanarie.dev` setup). Client-password mode is the only
 anonymous path. Smoke through a real browser session:
 
 1. `https://dashboard.canopy.website` → OneLogin login works; the project list
-   shows all three under **Core projects**.
+   shows all four under **Core projects**.
 2. `https://www.canopy.website` → marketing site + `/changelog` render (after
    SSO).
 3. `https://kitchen-sink.canopy.website` → exercise `db`, `blob`, and `ai.chat`

package/dist/docs/migrations.md

@@ -0,0 +1,183 @@
+---
+title: Migrations & Drizzle
+description: Evolve your own tables with versioned SQL migrations — generated by Drizzle or written by hand — applied safely by canopy deploy.
+---
+
+The document API (`canopy.db.collection(…)`) needs no schema and no migrations —
+if it covers your project, skip this page. But developers who define their own
+tables through raw `canopy.db.sql()` eventually need to _change_ those tables,
+and that's what migrations are for: versioned `.sql` files in your repo,
+applied exactly once each, in order, by the platform.
+
+[Drizzle](https://orm.drizzle.team) is the recommended way to produce those
+files (a typed schema plus generated SQL), but the mechanism is ORM-agnostic —
+hand-written `.sql` files work identically.
+
+## How it works
+
+1. Your `canopy.json` names a migrations directory:
+
+   ```json
+   {
+     "slug": "my-app",
+     "dialect": "sqlite",
+     "migrations": "./migrations"
+   }
+   ```
+
+2. The directory holds ordered `.sql` files (`0000_init.sql`, `0001_add_email.sql`, …),
+   applied in filename order.
+
+3. The platform journals each applied file in the project database, so a file
+   applies **exactly once**, and takes an automatic **pre-migrate snapshot**
+   before applying anything — a bad migration is one
+   `canopy db restore` away.
+
+4. Three surfaces apply them:
+   - **`canopy deploy`** — the main path. Pending migrations apply after the new
+     bundle is staged and before it goes live, so schema and code ship
+     together and the new code never sees the old schema. A failure aborts the
+     deploy with the old version still live.
+   - **`canopy dev --local`** — the sandbox applies pending migrations on boot,
+     so local dev always matches the repo.
+   - **`canopy db migrate [--plan]`** — apply (or dry-run) without deploying.
+
+Remote-first `canopy dev` never applies migrations — it points at the
+production database, and schema changes belong to deploys. While a schema
+change is in flux, develop against `--local` (add `--pull` for a copy of real
+data).
+
+## The rules
+
+- **Never edit an applied migration.** The platform hashes each file and
+  refuses edited history — write a new migration instead. (This is how every
+  mainstream migration tool works.)
+- **Prefer additive changes** (new tables, new nullable columns), and do
+  removals in a _later_ release once nothing references the old shape. This
+  "expand/contract" habit makes every edge case boring.
+- **Don't touch `_canopy_*` tables.** They're the platform's (the document
+  store, the migration journal) — the platform rejects migrations that
+  reference them.
+- **There are no down-migrations.** Roll forward with a new migration, or
+  restore the automatic pre-migrate snapshot.
+
+## Setting up Drizzle
+
+Pin your dialect first — a Drizzle schema is written for one SQL flavor. Check
+what your project's site runs on (`await canopy.db.dialect()` or the
+[data guide](https://docs.canopy.website/guides/data)) and set `"dialect"` in `canopy.json`: `"sqlite"`
+on Cloudflare-backed sites, `"postgres"` on GCP-backed ones. That same field
+makes `canopy dev --local` run a matching local engine.
+
+Install the tools and describe your schema:
+
+```bash
+npm install drizzle-orm
+npm install -D drizzle-kit
+```
+
+```ts title="src/schema.ts"
+import { sqliteTable, text } from "drizzle-orm/sqlite-core";
+
+export const users = sqliteTable("users", {
+  id: text("id").primaryKey(),
+  email: text("email").notNull(),
+});
+```
+
+```ts title="drizzle.config.ts"
+import { defineConfig } from "drizzle-kit";
+
+export default defineConfig({
+  dialect: "sqlite", // match canopy.json "dialect" ("postgresql" for postgres)
+  schema: "./src/schema.ts",
+  out: "./migrations",
+});
+```
+
+(On a postgres site, import from `drizzle-orm/pg-core` and set
+`dialect: "postgresql"` — everything else is identical.)
+
+Generate a migration whenever the schema changes:
+
+```bash
+npx drizzle-kit generate
+```
+
+This is fully local — it diffs your schema files and writes `.sql` into
+`./migrations`. **No database connection is involved, ever.** Then
+`canopy deploy` (or `canopy db migrate`) applies it.
+
+## Querying with Drizzle
+
+Canopy never hands out connection strings — Drizzle talks to your data through
+the handles Canopy already provides.
+
+**In a project worker on a Cloudflare-backed site**, `env.DB` is a real D1
+handle:
+
+```ts title="worker/index.ts"
+import { drizzle } from "drizzle-orm/d1";
+import { users } from "../src/schema.ts";
+
+export default {
+  async fetch(request, env) {
+    const db = drizzle(env.DB);
+    const all = await db.select().from(users);
+    return Response.json(all);
+  },
+};
+```
+
+**In the browser (or anywhere the SDK runs)**, wrap `canopy.db.sql()` with
+Drizzle's proxy driver:
+
+```ts title="src/db.ts"
+import { drizzle } from "drizzle-orm/sqlite-proxy";
+import { canopy } from "./canopy.ts";
+
+export const db = drizzle(async (sql, params, method) => {
+  const rows = await canopy.db.sql<Record<string, unknown>>(sql, params);
+  const values = rows.map((row) => Object.values(row));
+  return { rows: method === "get" ? (values[0] ?? []) : values };
+});
+```
+
+(On a postgres site use `drizzle-orm/pg-proxy` the same way; in a GCP project
+worker, `env.DB.query(text, params)` fits `pg-proxy` directly.)
+
+## Rehearsing on staging
+
+The safest way to try a migration is on the project's staging channel — a
+private copy of the app whose database starts as a clone of live:
+
+```bash
+canopy deploy --staging   # pending migrations apply to the STAGING database
+# … verify against the migrated copy …
+canopy promote            # the same migrations replay against live, then the version flips
+```
+
+A migration that fails on staging costs nothing; at promote time the live
+database gets its own pre-promote snapshot before anything applies.
+`canopy db migrate --staging` (and `--plan`) target the staging database
+directly, and `canopy staging sync` re-clones live when you want to rehearse
+again on fresh data. See [Staging & promoting](https://docs.canopy.website/guides/staging).
+
+## What deliberately doesn't work
+
+- **`drizzle-kit push` / `migrate` / `studio` / `introspect`** — these need a
+  database connection, which Canopy never exposes. Generating is local;
+  applying is Canopy's job. Don't invent a `DATABASE_URL` — there isn't one.
+  For browsing data, use the dashboard's data browser or `canopy db pull`.
+- **Drizzle's runtime `migrate()`** — the platform journals migrations in its
+  own `_canopy_migrations` table; running Drizzle's applier would double-apply.
+- **Cross-dialect portability.** A project with a Drizzle schema is pinned to
+  its dialect. The document API remains the portable path.
+
+## Coexistence
+
+Your Drizzle tables live alongside the document store in the same project
+database. Snapshots, restore, `canopy db pull`, and the graduation export all
+operate on the whole database, so they cover your tables automatically — and
+since your schema history is in the repo and the journal travels with the
+data, a graduated project takes its full migration story with it.

package/dist/docs/porting-nextjs.md

@@ -0,0 +1,232 @@
+---
+title: Porting a Next.js app
+description: How to restructure a Next.js (App Router) project so it runs on Canopy.
+---
+
+Canopy can host a project that started life as a Next.js app — but not by
+running Next.js's server. This guide explains why, and walks through the
+restructuring: a **static frontend** plus an optional **backend worker on
+`/api/*`**, with the platform taking over auth, data, files, and AI.
+
+If your app barely uses Next's server side, the port is a day or two of work.
+If it leans heavily on server components, server actions, or ISR, read
+[When not to port](#when-not-to-port) first.
+
+## Why a lift-and-shift doesn't work
+
+Canopy deliberately hosts no arbitrary servers — that's what keeps a thousand
+idle projects free to run and safe to operate. Three consequences matter for
+Next.js:
+
+- **Every page is a static file.** The platform serves your deployed build
+  from storage; requests to `/`, `/about`, or any other page route never reach
+  project code (see [How static files are served](https://docs.canopy.website/guides/static-serving)).
+  Server-side rendering, React Server Components resolved per request,
+  and Incremental Static Regeneration have nowhere to run.
+- **The backend is one worker, reachable only under `/api/*`.** A project can
+  ship a single bundled module exporting `fetch()` (and optionally
+  `scheduled()`), and the platform routes `/api/*` requests to it. Server
+  actions — which POST to page routes — never reach it.
+- **Auth belongs to the platform.** Every request is already behind OneLogin
+  (or a project password) before your code runs. NextAuth, auth middleware,
+  and session handling come out of the ported app entirely.
+
+So the port is a restructure: the frontend becomes a static build, and
+whatever genuinely needs a server moves into the worker.
+
+## What a ported app looks like
+
+```
+my-app/
+├── canopy.json          ← slug, build command, dist folder, worker entry
+├── src/                 ← frontend (static build)
+├── worker/
+│   └── index.ts         ← backend: fetch handler for /api/*
+└── dist/                ← build output that gets deployed
+```
+
+```json
+{
+  "slug": "my-app",
+  "build": "npm run build",
+  "dist": "dist",
+  "worker": "worker/index.ts"
+}
+```
+
+One `canopy deploy` builds and ships both; frontend and backend always move
+together as a single version, with rollback.
+
+## Step 1 — take inventory
+
+List everything in the app that runs on the server. Each item lands in one of
+three buckets:
+
+| Next.js feature                                 | Where it goes on Canopy                                                          |
+| ----------------------------------------------- | -------------------------------------------------------------------------------- |
+| Pages, layouts, client components               | Static build (unchanged in spirit)                                               |
+| Server components fetching data at request time | Client-side fetching, or a worker endpoint                                       |
+| Route handlers (`app/api/*/route.ts`)           | Worker endpoints under `/api/*`                                                  |
+| Server actions                                  | Explicit worker endpoints, called with `fetch` from the client                   |
+| Middleware                                      | Usually deleted (auth is platform-provided); anything else moves into the worker |
+| NextAuth / auth middleware                      | Deleted — use `canopy.auth.user()` (client) or `env.USER` (worker)               |
+| Database (Prisma, Postgres, …)                  | `canopy.db` — per-project database, document API + SQL escape hatch              |
+| File uploads (S3, …)                            | `canopy.blob` — per-project file storage with signed downloads                   |
+| AI SDK / OpenAI client                          | `canopy.ai.chat()`, or point the Vercel AI SDK at `canopy.ai.endpoint()`         |
+| `NEXT_PUBLIC_*` env vars                        | Build-time env vars in your CI — the platform doesn't inject build config        |
+| Server-side env vars / secrets                  | Project secrets (dashboard Settings) — injected into the worker's `env`          |
+| Cron (`vercel.json` crons)                      | [Schedules](https://docs.canopy.website/platform/schedules) — delivered to the worker's `scheduled()`       |
+| ISR / `revalidate` / caching                    | Dropped — at internal-tool scale, fetch fresh or cache in the client             |
+| `next/image` optimization                       | Plain `<img>`, or optimize at build time                                         |
+| Custom domain                                   | Not available — projects live at `<slug>.canopy.<domain>` behind sign-in         |
+| Queues / background jobs                        | Not supported — restructure around request/response plus schedules               |
+
+If the last two rows are deal-breakers, stop here: see
+[When not to port](#when-not-to-port).
+
+## Step 2 — make the frontend static
+
+Two routes, pick one:
+
+**Static export (quickest).** Set `output: 'export'` in `next.config.js` and
+fix what breaks. You keep the App Router file layout and components, but lose
+everything request-time: no route handlers, no server actions, no dynamic
+route segments without `generateStaticParams`, no request-time server
+components (they still run — but once, at build time). `next build` writes a
+fully static site to `out/`; point `dist` at it. Set
+`images: { unoptimized: true }` since there's no image optimizer serving
+requests.
+
+**Rebuild as a Vite SPA (more idiomatic).** Canopy's templates and tooling
+assume a single-page app: one `index.html`, client-side routing, `canopy dev`
+for local development against real project data. If you're porting an app
+you'll keep evolving on Canopy — especially with an AI agent doing the work —
+converting pages to a React + Vite SPA usually pays for itself quickly, and
+agents handle this conversion well. Page routes become client routes (the
+platform serves `index.html` for unknown paths, so deep links work).
+
+Either way, data that pages used to fetch on the server now arrives one of two
+ways: fetched from the client through the SDK (`canopy.db`, `canopy.blob` —
+fine for most internal tools), or from your worker via `/api/*` when it needs
+server-side logic or secrets.
+
+## Step 3 — move the backend into a worker
+
+Route handlers and server actions become endpoints in one fetch handler.
+[Hono](https://hono.dev) is a natural fit and bundles cleanly:
+
+```ts
+// worker/index.ts
+import { createCanopy } from "@mediamonks/canopy";
+import { Hono } from "hono";
+
+type Env = {
+  CANOPY: { fetch: typeof fetch };
+  /** Signed-in monk, verified by the platform; null for cron. */
+  USER: { sub: string; email: string; name: string } | null;
+  /** Project secrets from dashboard Settings appear as plain keys. */
+  MY_API_KEY?: string;
+};
+
+const app = new Hono<{ Bindings: Env }>();
+
+// was: app/api/report/route.ts
+app.post("/api/report", async (c) => {
+  const user = c.env.USER;
+  if (!user) return c.json({ error: "unauthenticated" }, 401);
+
+  // The SDK works inside the worker through the CANOPY binding —
+  // same database and files the frontend sees, caller's identity attached.
+  const canopy = createCanopy({ fetch: c.env.CANOPY.fetch.bind(c.env.CANOPY) });
+  const rows = await canopy.db.collection("reports").find({ where: { owner: user.email } });
+  return c.json({ rows });
+});
+
+// was: a server action
+app.post("/api/submit", async (c) => {
+  const body = await c.req.json();
+  // …validate, write via canopy.db, call an external API with c.env.MY_API_KEY…
+  return c.json({ ok: true });
+});
+
+export default {
+  fetch: app.fetch.bind(app),
+  // was: vercel.json crons — configure in dashboard Settings → Schedules
+  async scheduled(event: { name: string }, env: Env) {
+    if (event.name === "nightly-report") {
+      // …
+    }
+  },
+};
+```
+
+Rules of the road for the worker:
+
+- It's **one bundled file** — dependencies are bundled in at deploy time, so
+  stick to packages that don't need Node built-ins or native modules.
+- **No filesystem, no long-lived state.** Persist through `canopy.db` and
+  `canopy.blob`.
+- **Outbound requests are controlled.** Calls to external APIs pass through a
+  platform-managed egress allowlist — if your project needs to call an
+  external host, ask the platform team to allow it.
+- Frontend calls are plain `fetch("/api/…")` — same origin, the platform
+  session cookie rides along automatically.
+
+## Step 4 — swap the data layer
+
+Replace the ORM and connection strings with the project's own database:
+
+- The paved road is the [document API](https://docs.canopy.website/sdk/database):
+  `canopy.db.collection("todos").insert(…)` / `find(…)` — schemaless JSON, no
+  migrations. For most internal tools this replaces Prisma models outright.
+- Relational shapes port via the SQL escape hatch, `canopy.db.sql()`, against
+  the same per-project database.
+- Existing data can be imported once: export from your old database, then load
+  it through the worker or the [SQL console](https://docs.canopy.website/guides/data) in the dashboard.
+
+Files move to [`canopy.blob`](https://docs.canopy.website/sdk/files) (uploads, listings, short-lived
+signed download URLs — nothing is ever publicly readable). AI calls move to
+[`canopy.ai`](https://docs.canopy.website/sdk/ai); if the app uses the Vercel AI SDK, point it at
+`canopy.ai.endpoint()` and it keeps working, now metered and budget-capped.
+
+## Step 5 — delete the auth
+
+This is the satisfying part. OneLogin fronts every request before your code
+runs, so the ported app removes sign-in pages, session handling, and auth
+middleware entirely:
+
+- **Client:** `canopy.auth.user()` returns the signed-in monk.
+- **Worker:** `env.USER` carries the verified identity (no round-trip).
+- Client-facing access without OneLogin is a per-project
+  [password](https://docs.canopy.website/platform/client-access), configured in Settings — not code.
+
+Authorization (who may do what _inside_ the app) stays yours, but it now keys
+off a verified identity instead of a homegrown session.
+
+## When not to port
+
+Be honest about fit before starting. Dedicated hosting is the better home
+when the app:
+
+- depends on **per-request SSR** for real reasons — SEO on public pages,
+  personalization at the edge, streaming server components as a core UX;
+- is built around **server actions and RSC data flow** so thoroughly that the
+  restructure is a rewrite;
+- needs a **custom domain or anonymous public access** — nothing on Canopy is
+  reachable without OneLogin or a project password;
+- needs **queues, background jobs, or long-running work**.
+
+That's not a workaround waiting to happen — it's the platform's design. Canopy
+optimizes for small internal tools; an app that genuinely needs a server is
+past greenhouse size (see [Use cases](https://docs.canopy.website/overview/use-cases)).
+
+## Checklist
+
+- [ ] Inventory server-side surface (RSC fetching, actions, route handlers, middleware, crons)
+- [ ] Frontend: `output: 'export'` or Vite SPA; fix dynamic segments and `next/image`
+- [ ] Worker: route handlers + server actions → `/api/*` endpoints in `worker/index.ts`
+- [ ] Data: ORM → `canopy.db`; uploads → `canopy.blob`; AI clients → `canopy.ai`
+- [ ] Delete NextAuth/middleware; read identity from `canopy.auth.user()` / `env.USER`
+- [ ] Secrets into dashboard Settings; `NEXT_PUBLIC_*` into your CI build
+- [ ] Crons into Settings → Schedules, handled in `scheduled()`
+- [ ] `canopy.json` with `build`, `dist`, `worker` — then `canopy deploy`

package/dist/docs/sdk-ai.md

@@ -0,0 +1,103 @@
+---
+title: AI
+description: Metered LLM access through the project's budget-capped gateway key — chat, streaming, and an OpenAI-compatible endpoint.
+---
+
+`canopy.ai` gives your project LLM access without any API keys in your code.
+Every request authenticates as the project and is metered against a hard
+per-project daily budget — spend and limits are covered in
+[AI access & usage](https://docs.canopy.website/platform/ai-usage).
+
+## ai.chat(options)
+
+One-shot chat completion. Takes a `ChatOptions` object, resolves to a
+`ChatResponse`:
+
+```ts
+const res = await canopy.ai.chat({
+  messages: [
+    { role: "system", content: "You are terse." },
+    { role: "user", content: "Say hi in five words." },
+  ],
+  model: "anthropic/claude-haiku-4-5", // optional
+  temperature: 0.7, // optional, 0–2
+  maxTokens: 256, // optional
+});
+
+res.message.content; // the assistant's reply
+res.model; // the model that actually answered
+res.usage; // { inputTokens: number, outputTokens: number }
+```
+
+**`ChatOptions`:**
+
+- `messages` — required, non-empty array of `{ role, content }`. `role` is
+  `"system" | "user" | "assistant"`; `content` is a non-empty string.
+- `model` — optional `"{provider}/{model}"` id. Omit it and the platform's
+  default model answers. Ask for a model whose provider isn't enabled and the
+  call fails with a message listing what _is_ available; `ai.endpoint()`
+  returns the full curated list.
+- `temperature` — optional number between 0 and 2.
+- `maxTokens` — optional integer, at least 1.
+
+**`ChatResponse`:** `{ message: ChatMessage, model: string, usage: { inputTokens, outputTokens } }`.
+`message.role` is `"assistant"`.
+
+## ai.chatStream(options)
+
+Same `ChatOptions`, but resolves to a `ReadableStream<Uint8Array>` of
+server-sent events — the raw SSE bytes of the completion, for chat-style UIs
+that render tokens as they arrive:
+
+```ts
+const stream = await canopy.ai.chatStream({
+  messages: [{ role: "user", content: "Count to five." }],
+});
+
+const decoder = new TextDecoder();
+let text = "";
+for await (const chunk of stream) {
+  text += decoder.decode(chunk, { stream: true });
+}
+```
+
+Each SSE event is a `data: {...}` line carrying an OpenAI-style completion
+chunk. If you'd rather not parse SSE yourself, use `ai.endpoint()` below and
+let an ecosystem client handle streaming for you.
+
+## ai.endpoint()
+
+Returns the project's OpenAI-compatible endpoint info:
+
+```ts
+const { baseUrl, models } = await canopy.ai.endpoint();
+// baseUrl — an OpenAI-compatible base URL
+// models  — the curated model list, "{provider}/{model}" ids; models[0] is the default
+```
+
+Point any OpenAI-compatible client — the Vercel AI SDK, an OpenAI SDK, a
+tool-calling loop — at `baseUrl`. It uses the same project key and counts
+against the same budget as `ai.chat()`:
+
+```ts
+import { createOpenAI } from "@ai-sdk/openai";
+
+const { baseUrl, models } = await canopy.ai.endpoint();
+const openai = createOpenAI({ baseURL: baseUrl, apiKey: "unused" });
+const model = openai(models[0]);
+```
+
+## Errors
+
+Failed calls throw `CanopyError` with the HTTP `status` and the response body
+as the `message`. Two worth handling:
+
+- **Budget exhausted** — status `429`, body contains
+  `"ai_budget_exceeded"`. The project hit its daily AI cap; AI calls resume
+  the next day (or after a maintainer raises the budget). Everything else in
+  your app keeps working.
+- **Invalid request** — status `400`, body contains `"invalid_chat"` and a
+  detail explaining which option was rejected.
+
+> **Note:** Budgets are enforced before every call, so a runaway loop becomes a capped bill — see [AI access
+> &amp; usage](https://docs.canopy.website/platform/ai-usage) for how spend is tracked and displayed.

package/dist/docs/sdk-auth.md

@@ -0,0 +1,57 @@
+---
+title: Auth
+description: Read who the platform signed in — you never build a login screen.
+---
+
+Authentication happens before your code runs: the platform gates every request
+to your project, so by the time a page loads or a worker route fires, there is
+always a signed-in user. You never build a login screen, store passwords, or
+check tokens — see [Members and access](https://docs.canopy.website/platform/members-and-access) for
+who gets in and how. `canopy.auth` only reports who the platform let in.
+
+## auth.user()
+
+Returns the authenticated user for the current session as a `CanopyUser`:
+
+```ts
+const user = await canopy.auth.user();
+// { id: "…", email: "ada@monks.com", name: "Ada Lovelace", kind: "monk" }
+```
+
+| Field   | Type                   | Meaning                                                                                                                |
+| ------- | ---------------------- | ---------------------------------------------------------------------------------------------------------------------- |
+| `id`    | `string`               | Stable subject from OneLogin — safe to key user data on.                                                               |
+| `email` | `string`               | The user's email address.                                                                                              |
+| `name`  | `string`               | Display name.                                                                                                          |
+| `kind`  | `"monk" \| "external"` | `"monk"` = signed in through OneLogin; `"external"` = a visitor who got in with the project's client password instead. |
+
+`kind: "external"` sessions come from client-password access — clients viewing
+a shared project without a Monks account. Branch on it when externals should
+see a trimmed-down experience:
+
+```ts
+const user = await canopy.auth.user();
+
+document.querySelector("h1")!.textContent = `Welcome, ${user.name}`;
+
+if (user.kind === "external") {
+  // Client viewer: hide internal tooling, show the presentation view.
+  document.querySelector("#admin-panel")?.remove();
+}
+```
+
+> **Warning:** Branching on `kind` in the browser is presentation, not security — anything your page can fetch, a
+> visitor can fetch. The platform's access rules are what actually protect data.
+
+## auth.logout()
+
+Ends the platform session for the current visitor. Their next request hits the
+login flow again:
+
+```ts
+await canopy.auth.logout();
+location.reload(); // next load re-authenticates
+```
+
+This signs out the browser session only — it does not touch your `canopy login`
+on the CLI.