@mediamonks/canopy-cli 0.7.28 → 0.7.30

package/dist/ai-fAvjdjVX.mjs

@@ -0,0 +1,54 @@
+import { d as withContext, l as apiRequest, r as reportErrors } from "./ui-CeupNHNa.mjs";
+import { defineCommand } from "citty";
+//#region src/ai.ts
+/**
+* canopy ai models — the site's AI model list (OpenSpec change
+* ai-model-catalog): the auto/* aliases with what they resolve to, the
+* default, available models with prices, and legacy models with their
+* replacements. Site-wide, so it needs no linked project; `--profile` picks
+* the site. Agents should check this before naming a model in code.
+*/
+function perMTok(n) {
+	return `$${Number.isInteger(n) ? n : n.toFixed(2).replace(/0$/, "")}`;
+}
+function renderModels(site) {
+	const lines = ["Aliases (prefer these over model ids)"];
+	for (const alias of site.aliases) {
+		const target = alias.resolvesTo ?? "— (no model on this site)";
+		const tag = alias.id === site.default ? "  (default)" : "";
+		lines.push(`  ${alias.id.padEnd(12)} → ${target}${tag}`);
+	}
+	lines.push("", "Models (USD per 1M tokens, in / out)");
+	if (site.models.length === 0) lines.push("  none — AI is not enabled on this site");
+	const width = Math.max(0, ...site.models.map((m) => m.id.length));
+	for (const model of site.models) lines.push(`  ${model.id.padEnd(width)}  ${perMTok(model.inputPerMTok)} / ${perMTok(model.outputPerMTok)}`);
+	if (site.legacy.length > 0) {
+		lines.push("", "Legacy (still answered, by the replacement)");
+		const legacyWidth = Math.max(...site.legacy.map((m) => m.id.length));
+		for (const model of site.legacy) lines.push(`  ${model.id.padEnd(legacyWidth)} → ${model.replacement}`);
+	}
+	return lines.join("\n");
+}
+const aiCommand = defineCommand({
+	meta: {
+		name: "ai",
+		description: "AI models available to projects on this site"
+	},
+	subCommands: { models: defineCommand({
+		meta: {
+			name: "models",
+			description: "List the AI models and auto/* aliases this site offers"
+		},
+		args: { json: {
+			type: "boolean",
+			description: "Print raw JSON (same shape as GET /control/v1/ai/models)",
+			default: false
+		} },
+		run: reportErrors("ai models", async ({ args }) => {
+			const site = await withContext(apiRequest("GET", "/ai/models"), { action: "list the site's AI models" });
+			console.log(args.json ? JSON.stringify(site, null, 2) : renderModels(site));
+		})
+	}) }
+});
+//#endregion
+export { aiCommand };

package/dist/{db-DVMwCLlU.mjs → db-KTLn8J1u.mjs}

@@ -1,6 +1,6 @@
 import { c as resolveProject, o as projectFlagArgs } from "./site-DM2J10CB.mjs";
-import { a as unwrap, d as withContext, i as requireTty, l as apiRequest, r as reportErrors, s as apiDataRequest } from "./ui-DR-siu2S.mjs";
-import { n as migrateProject, r as readMigrationFiles, t as describeMigrateResult } from "./migrations-B9fXxMDj.mjs";
+import { a as unwrap, d as withContext, i as requireTty, l as apiRequest, r as reportErrors, s as apiDataRequest } from "./ui-CeupNHNa.mjs";
+import { n as migrateProject, r as readMigrationFiles, t as describeMigrateResult } from "./migrations-C8yRPJIX.mjs";
 import { defineCommand } from "citty";
 import { readFileSync, writeFileSync } from "node:fs";
 import * as p from "@clack/prompts";

package/dist/{deploy-CTMcwHhI.mjs → deploy-CBf44bvG.mjs}

@@ -1,6 +1,6 @@
 import { a as projectDirArgs, c as resolveProject, l as stagingUrl, n as siteConfig, o as projectFlagArgs, s as projectUrl, u as tryReadCanopyJson } from "./site-DM2J10CB.mjs";
-import { a as unwrap, c as apiDownload, d as withContext, l as apiRequest, r as reportErrors, s as apiDataRequest, t as formatDateTime } from "./ui-DR-siu2S.mjs";
-import { n as migrateProject, r as readMigrationFiles, t as describeMigrateResult } from "./migrations-B9fXxMDj.mjs";
+import { a as unwrap, c as apiDownload, d as withContext, l as apiRequest, r as reportErrors, s as apiDataRequest, t as formatDateTime } from "./ui-CeupNHNa.mjs";
+import { n as migrateProject, r as readMigrationFiles, t as describeMigrateResult } from "./migrations-C8yRPJIX.mjs";
 import { defineCommand } from "citty";
 import { mkdtempSync, readFileSync, readdirSync, rmSync, statSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";

package/dist/dev-DGCu9MjB.mjs

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

package/dist/{dev-BvjbJcse.mjs → dev-JlzMZJow.mjs}

@@ -1,7 +1,7 @@
 import { a as projectDirArgs, c as resolveProject, i as projectDialect, n as siteConfig, u as tryReadCanopyJson } from "./site-DM2J10CB.mjs";
-import { d as withContext, l as apiRequest, o as ApiError, r as reportErrors, t as formatDateTime } from "./ui-DR-siu2S.mjs";
-import { r as readMigrationFiles } from "./migrations-B9fXxMDj.mjs";
-import { n as stampWorkerHeaders } from "./src-CwSKZwNK.mjs";
+import { d as withContext, l as apiRequest, o as ApiError, r as reportErrors, t as formatDateTime } from "./ui-CeupNHNa.mjs";
+import { r as readMigrationFiles } from "./migrations-C8yRPJIX.mjs";
+import { n as stampWorkerHeaders } from "./src-C7zPhbxi.mjs";
 import { createRequire } from "node:module";
 import { defineCommand } from "citty";
 import { existsSync } from "node:fs";
@@ -38,7 +38,7 @@ async function workerPlugin(flags, slug) {
 		console.log(`note: canopy.json points "worker" at ${entry}, which does not exist — skipping.`);
 		return;
 	}
-	const { missingSecretNames, readDevVars, workerDevPlugin } = await import("./dev-worker-BerdPJ_U.mjs");
+	const { missingSecretNames, readDevVars, workerDevPlugin } = await import("./dev-worker-DjJGSUGj.mjs");
 	const secrets = readDevVars(flags.dir);
 	const email = siteConfig().email;
 	const plugin = workerDevPlugin({
@@ -146,6 +146,48 @@ function devProxyHeaders(token, slug, channel) {
 	});
 	return Object.fromEntries(headers);
 }
+/**
+* One request from Vite's /_api proxy into the --local sandbox. The response
+* body is streamed, not buffered — realtime subscriptions (docs/48) are
+* long-lived SSE responses — and a client that goes away aborts the sandbox
+* request and cancels its body, so the subscription is released.
+*/
+async function bridgeToSandbox(sandbox, req, res) {
+	const gone = new AbortController();
+	res.on("close", () => gone.abort());
+	const chunks = [];
+	for await (const chunk of req) chunks.push(chunk);
+	const body = Buffer.concat(chunks);
+	const headers = new Headers();
+	if (req.headers["content-type"]) headers.set("content-type", req.headers["content-type"]);
+	if (req.headers["accept"]) headers.set("accept", req.headers["accept"]);
+	const response = await sandbox.handle(new Request(`http://canopy.local${req.url ?? ""}`, {
+		method: req.method,
+		headers,
+		body: body.length === 0 ? void 0 : new Uint8Array(body),
+		signal: gone.signal
+	}));
+	if (gone.signal.aborted) {
+		await response.body?.cancel().catch(() => {});
+		return;
+	}
+	res.writeHead(response.status, Object.fromEntries(response.headers));
+	if (!response.body) {
+		res.end();
+		return;
+	}
+	const reader = response.body.getReader();
+	gone.signal.addEventListener("abort", () => void reader.cancel().catch(() => {}), { once: true });
+	try {
+		for (;;) {
+			const { done, value } = await reader.read();
+			if (done) break;
+			res.write(value);
+		}
+	} catch {} finally {
+		res.end();
+	}
+}
 async function devRemote(flags, slug) {
 	const { token, expires_at } = await withContext(apiRequest("POST", `/projects/${slug}/dev-token`), devTokenContext(slug));
 	const { apiUrl } = siteConfig();
@@ -176,7 +218,7 @@ async function devRemote(flags, slug) {
 async function devLocal(flags, slug) {
 	let dump;
 	if (flags.pull) {
-		const { fetchProjectDump } = await import("./local-laAZEDVJ.mjs");
+		const { fetchProjectDump } = await import("./local-BA_TPWpN.mjs");
 		console.log(`Pulling a fresh export of ${slug}${flags.staging ? " [staging]" : ""}…`);
 		dump = await fetchProjectDump(slug, flags.staging ? "staging" : "live");
 	}
@@ -191,7 +233,7 @@ async function devLocal(flags, slug) {
 		const reason = err instanceof ApiError ? err.explain().why : String(err);
 		console.log(`Note: ai/services will be unavailable — could not reach the platform (${reason}).`);
 	}
-	const { createSandbox } = await import("./local-laAZEDVJ.mjs");
+	const { createSandbox } = await import("./local-BA_TPWpN.mjs");
 	const sandbox = await createSandbox({
 		slug,
 		persistDir: join(flags.dir, ".canopy", "local"),
@@ -207,20 +249,7 @@ async function devLocal(flags, slug) {
 		const { applied } = await sandbox.applyMigrations(migrationFiles);
 		if (applied.length > 0) console.log(`Applied ${applied.length} pending migration(s): ${applied.join(", ")}`);
 	}
-	const handleApi = async (req, res) => {
-		const chunks = [];
-		for await (const chunk of req) chunks.push(chunk);
-		const body = Buffer.concat(chunks);
-		const headers = new Headers();
-		if (req.headers["content-type"]) headers.set("content-type", req.headers["content-type"]);
-		const response = await sandbox.handle(new Request(`http://canopy.local${req.url ?? ""}`, {
-			method: req.method,
-			headers,
-			body: body.length === 0 ? void 0 : new Uint8Array(body)
-		}));
-		res.writeHead(response.status, Object.fromEntries(response.headers));
-		res.end(Buffer.from(await response.arrayBuffer()));
-	};
+	const handleApi = (req, res) => bridgeToSandbox(sandbox, req, res);
 	const { createServer: createHttpServer } = await import("node:http");
 	const apiServer = createHttpServer((req, res) => {
 		handleApi(req, res).catch((err) => {
@@ -312,4 +341,4 @@ const devCommand = defineCommand({
 	})
 });
 //#endregion
-export { devProxyHeaders as n, rewriteApiPath as r, devCommand as t };
+export { rewriteApiPath as i, devCommand as n, devProxyHeaders as r, bridgeToSandbox as t };

package/dist/{dev-worker-BerdPJ_U.mjs → dev-worker-DjJGSUGj.mjs}

@@ -1,4 +1,4 @@
-import { n as stampWorkerHeaders, t as redactCanopyCredentials } from "./src-CwSKZwNK.mjs";
+import { n as stampWorkerHeaders, t as redactCanopyCredentials } from "./src-C7zPhbxi.mjs";
 import { readFileSync } from "node:fs";
 import { relative, resolve, sep } from "node:path";
 //#region src/dev-worker.ts

package/dist/docs/cli-ai.md

@@ -0,0 +1,43 @@
+---
+title: canopy ai models
+description: List the AI models and auto/* aliases your site offers, with prices.
+---
+
+`canopy ai models` shows which AI models projects on your site can use. Run it before you name a model in code: only names on this list work.
+
+## Usage
+
+```bash
+canopy ai models [--json]
+```
+
+## Arguments & flags
+
+- `--json`: print the raw JSON instead of the formatted list. Default `false`.
+- `--profile <id>`: which site to ask, as with every command.
+
+## How it works
+
+The list belongs to the site, not to a project, so the command works from any directory. It prints three parts:
+
+- **Aliases.** `auto/low`, `auto/mid` and `auto/high`, each with the model it answers with right now. The default (`auto/low`) is marked. Aliases follow newer models as they arrive, so prefer them over fixed model ids.
+- **Models.** Every model you can name, with its price per million input and output tokens.
+- **Legacy.** Retired models that still work, and the model that now answers for each.
+
+It's read-only. With `--json`, the output is ready for scripts and agents.
+
+## Examples
+
+```bash
+canopy ai models
+```
+
+Shows the aliases, models and prices for your active site.
+
+```bash
+canopy ai models --json | jq -r '.aliases[] | "\(.id) \(.resolvesTo)"'
+```
+
+Prints what each alias answers with right now.
+
+See also [AI](https://docs.canopy.website/sdk/ai) for calling models from your project, and [AI access & usage](https://docs.canopy.website/platform/ai-usage) for budgets and spend.

package/dist/docs/cli-db.md

@@ -53,6 +53,8 @@ Behavior:
 2. Unless `--yes` is passed, it asks you to **type the project slug** to confirm — a deliberate speed bump, since restore is destructive. A non-TTY without `--yes` errors instead of guessing.
 3. The chosen snapshot or file replaces the entire database, and the CLI confirms `Restored <slug>.`
 
+A dump only restores into a database of the same kind. Feeding a dump from a SQLite-based project to a Postgres-based one (or the other way round) is refused up front with `dump_dialect_mismatch`, before anything is wiped. Check with `canopy db pull` on both sides: a SQLite dump opens with a `PRAGMA` line, a Postgres dump with a `-- Canopy project dump (postgres)` banner. For a project that uses **document collections only**, the collection table has the same layout everywhere, so deleting that leading `PRAGMA` line makes a SQLite dump restore on Postgres. Custom tables need their column types adapted by hand.
+
 ### canopy db migrate
 
 Applies pending schema migrations to the project's **live** database, without deploying. Requires a `"migrations"` directory in `canopy.json` (for example your `drizzle-kit generate` output — see the [migrations guide](https://docs.canopy.website/guides/migrations)).

package/dist/docs/cli.md

@@ -60,6 +60,8 @@ has a full page per command.
   `--snapshot <key>`. `--yes` skips the confirmation. **Destructive.**
 - `canopy usage` — AI spend and storage for the project (same data as the
   dashboard Usage tab). `--project <slug>` / `--json` for agents.
+- `canopy ai models` — the AI models and `auto/*` aliases this site offers,
+  with prices. Works from any directory; `--json` for agents.
 
 ## CI / deploy tokens
 

package/dist/docs/index.json

@@ -276,6 +276,11 @@
           "title": "canopy usage",
           "summary": "Show a project's AI spend, storage footprint, and deploy count from the terminal."
         },
+        {
+          "slug": "cli-ai",
+          "title": "canopy ai models",
+          "summary": "List the AI models and auto/* aliases your site offers, with prices."
+        },
         {
           "slug": "cli-feedback",
           "title": "canopy feedback",
@@ -306,12 +311,12 @@
     {
       "key": "sdk",
       "title": "SDK reference",
-      "description": "The typed client your project code uses — auth, data, files, AI, services.",
+      "description": "The typed client your project code uses — auth, data, files, AI, email, notify, realtime, services.",
       "topics": [
         {
           "slug": "sdk",
           "title": "Using the SDK",
-          "summary": "One typed client for auth, data, files, AI, email, and services — no keys, no connection strings, the platform authenticates for you."
+          "summary": "One typed client for auth, data, files, AI, email, notify, realtime, and services — no keys, no connection strings, the platform authenticates for you."
         },
         {
           "slug": "sdk-auth",
@@ -338,6 +343,16 @@
           "title": "Email",
           "summary": "Send email from your project without a mail server or an API key — Monks recipients only, with a per-project daily quota and a sent log."
         },
+        {
+          "slug": "sdk-notify",
+          "title": "Notify",
+          "summary": "Post a Slack message from your project through the Canopy bot — to your linked channels or a colleague's DMs — with nothing to set up."
+        },
+        {
+          "slug": "sdk-realtime",
+          "title": "Realtime",
+          "summary": "Live updates between the people using your app — subscribe to a topic, publish to it, no backend needed."
+        },
         {
           "slug": "sdk-google",
           "title": "Google",

package/dist/docs/platform-ai-usage.md

@@ -21,10 +21,12 @@ const reply = await canopy.ai.chat({
 
 - **No keys in your code.** Requests authenticate as the project; the
   platform holds the provider credentials.
-- **A curated model list.** Each site enables a set of models
-  (`provider/model`, e.g. `anthropic/claude-haiku-4-5`) with a sensible
-  default — ask for a model outside the list and the API tells you what _is_
-  available.
+- **Pick a tier, not a model.** Name `auto/low` (the default), `auto/mid`, or
+  `auto/high` and the platform answers with the best current model for it.
+  You can also name a specific model from the site's list. `canopy ai models`
+  and the Models section on your project's Usage tab show it, with prices.
+  Names that aren't on the list are refused, and retired models keep working,
+  answered by their replacement, until you switch.
 - **Streaming** via `canopy.ai.chatStream()` for chat-style UIs.
 - **Documents and images.** Messages can attach files — reference something
   in the project's [blob storage](https://docs.canopy.website/sdk/blob) by key, or inline base64 — see

package/dist/docs/platform-members-and-access.md

@@ -35,10 +35,19 @@ nobody outside the team can touch its data or settings.
 
 ## Inviting collaborators
 
-Open the project's **Settings** tab and use the **Collaborators** card. A
-searchable people picker finds anyone who has signed in to Canopy; adding
-them takes effect immediately. Owners (and admins) can also remove people
-from the same card.
+Open the project's **Settings** tab and use the **Collaborators** card. Start
+typing a name or email: colleagues who have signed in to Canopy before show up
+as suggestions, and picking one adds them immediately.
+
+Someone who has never opened Canopy can be added too — type their full
+company email and choose **Invite by email**. They appear on the roster as
+**invited** and become a collaborator automatically the first time they sign
+in, whether that's opening the project's URL or running `canopy login`. Until
+then the invite grants nothing. You can withdraw a pending invite from the
+same card. Canopy doesn't send them a message, so let them know yourself.
+
+Only company addresses that can sign in to Canopy can be invited. Owners (and
+admins) can also remove people from the same card.
 
 ## Collaborators-only mode
 

package/dist/docs/platform-slack.md

@@ -3,6 +3,12 @@ title: Slack
 description: Give your project its own Slack bot — Canopy creates and manages the app, your code handles the events.
 ---
 
+> **A bot, or just a message?** If all your project needs is to post to a
+> channel or DM a colleague, skip this page: `canopy.notify.slack` does that
+> through the Canopy bot with nothing to set up. Read
+> [Notify](https://docs.canopy.website/sdk/notify). Come back here when people need to talk to your
+> bot, run slash commands, or see your project's own name and icon.
+
 Your project can have its own Slack app: its own name and bot, in whatever
 workspace you choose. Canopy creates the app, keeps its settings in sync,
 holds every credential, and routes Slack's traffic to your backend. Your

package/dist/docs/sdk-ai.md

@@ -8,6 +8,29 @@ Every request authenticates as the project and is metered against hard
 per-project budgets — spend, limits, and how prompts are handled by the
 model providers are covered in [AI access & usage](https://docs.canopy.website/platform/ai-usage).
 
+## Picking a model
+
+Name a quality tier instead of a model id, and the platform answers with the
+best current model for it:
+
+- `auto/low` — fast and cheap. The **default** when you leave `model` out.
+- `auto/mid` — a good balance for most product features.
+- `auto/high` — the most capable model, for hard reasoning and long documents.
+
+Each alias moves to newer models as they arrive, without a code change. You
+can also name a specific model from the site's list. Run
+`canopy ai models` to see the aliases, what each answers with right now, and
+every model with its price:
+
+```bash
+canopy ai models
+```
+
+Only names on that list work: anything else is refused with a `400` that lists
+what is available. When a model is retired, calls naming it keep working,
+answered by its replacement: `res.model` names the model that answered, and
+the response carries a `deprecation` notice (below) until you switch.
+
 ## ai.chat(options)
 
 One-shot chat completion. Takes a `ChatOptions` object, resolves to a
@@ -19,7 +42,7 @@ const res = await canopy.ai.chat({
     { role: "system", content: "You are terse." },
     { role: "user", content: "Say hi in five words." },
   ],
-  model: "anthropic/claude-haiku-4-5", // optional
+  model: "auto/mid", // optional — defaults to auto/low
   temperature: 0.7, // optional, 0–2
   maxTokens: 256, // optional
 });
@@ -34,10 +57,10 @@ res.usage; // { inputTokens: number, outputTokens: number }
 - `messages` — required, non-empty array of `{ role, content }`. `role` is
   `"system" | "user" | "assistant"`; `content` is a non-empty string, or an
   array of content parts to attach documents and images (below).
-- `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.
+- `model` — optional: an alias (`auto/low`, `auto/mid`, `auto/high`) or a
+  `"{provider}/{model}"` id from the site's list (`canopy ai models`). Omit it
+  and `auto/low` answers. A name that isn't on the list fails with a message
+  listing what _is_ available.
 - `temperature` — optional number between 0 and 2. Reasoning models (the
   GPT-5 family) only accept their default temperature, so the platform drops
   this setting for them rather than failing the call — it has effect on
@@ -52,7 +75,11 @@ res.usage; // { inputTokens: number, outputTokens: number }
 
 **`ChatResponse`:** `{ message, model, usage: { inputTokens, outputTokens } }`.
 `message.role` is `"assistant"` and `message.content` is always a plain
-string, whatever went in.
+string, whatever went in. `model` is the model that actually answered. When
+you named a retired model, the response also has
+`deprecation: { requested, replacement }`. Switch to the replacement or an
+alias. Streams and the endpoints below say the same with a `Deprecation:
+true` response header.
 
 ## Attaching documents and images
 
@@ -143,8 +170,10 @@ The compat endpoint speaks OpenAI's chat-completions dialect to every model —
 portable, but the lowest common denominator. When you want a provider's own
 protocol — Anthropic prompt caching, PDFs with citations, or OpenAI's
 Responses API — use the native base URLs from `endpoint()`. Requests pass
-through to the provider unchanged; auth, the model allowlist, the daily
-budget, and metering all still apply.
+through to the provider unchanged; auth, the model list, the daily budget,
+and metering all still apply. Aliases work here too: on the Anthropic endpoint
+`auto/mid` picks the best Claude model for that tier, on the OpenAI endpoint
+the best OpenAI one.
 
 ```ts
 import Anthropic from "@anthropic-ai/sdk";
@@ -152,7 +181,7 @@ import Anthropic from "@anthropic-ai/sdk";
 const { native } = await canopy.ai.endpoint();
 const anthropic = new Anthropic({ baseURL: native.anthropic, apiKey: "unused" });
 const msg = await anthropic.messages.create({
-  model: "claude-haiku-4-5", // bare or "anthropic/…" — must be on the curated list
+  model: "auto/mid", // an alias, or a model id from `canopy ai models` (bare or "anthropic/…")
   max_tokens: 1024,
   messages: [{ role: "user", content: "Hello" }],
 });
@@ -188,7 +217,9 @@ as the `message`. Two worth handling:
   or after a maintainer raises it). Everything else in your app keeps
   working.
 - **Invalid request** — status `400`, body contains `"invalid_chat"` and a
-  detail explaining which option was rejected.
+  detail explaining which option was rejected. A model that isn't on the
+  site's list lands here too, with the available aliases and models in the
+  detail.
 
 > **Note:** Budgets are enforced before every call, so a runaway loop becomes a capped bill — see [AI access
 > & usage](https://docs.canopy.website/platform/ai-usage) for how spend is tracked and displayed.

package/dist/docs/sdk-notify.md

@@ -0,0 +1,140 @@
+---
+title: Notify
+description: Post a Slack message from your project through the Canopy bot — to your linked channels or a colleague's DMs — with nothing to set up.
+---
+
+`canopy.notify` tells people things on your project's behalf. The Canopy bot,
+the one that already DMs you about reports and deploys, delivers the message
+and says which project sent it. There is no Slack app to create, no token, no
+install: it works the moment your project has something to say.
+
+Two rules are enforced by the platform, not by your code:
+
+- **You reach people your project has a relationship with.** Channels are the
+  ones a project member linked with `/canopy link`; people are Canopy users,
+  named by the email they sign in with. Nothing else is addressable.
+- **A daily quota per project**, 200 deliveries by default. Each person and
+  each channel a message goes to counts as one.
+
+## notify.slack(options)
+
+Resolves once the platform has queued the message:
+
+```ts
+// Every channel linked to the project.
+await canopy.notify.slack({ text: "Export finished: *1,204* rows." });
+
+// A colleague, and nobody else.
+await canopy.notify.slack({
+  to: "someone@monks.com",
+  text: "Your approval is needed on <https://…|request #42>.",
+});
+
+// People and the linked channels together.
+await canopy.notify.slack({ to: ["a@monks.com", "b@monks.com"], channels: true, text: "…" });
+```
+
+**`NotifySlackOptions`:**
+
+- `text` — required, up to 2000 characters of Slack mrkdwn. Bold, links and
+  `<@U…>` mentions work.
+- `to` — optional. One email or an array of up to 20, each the address a
+  Canopy user signs in with. Leave it out to post to the linked channels
+  instead.
+- `channels` — optional. With `to`, also post to the linked channels. Without
+  `to` it is always on.
+
+**Returns** `{ queued }`, the number of deliveries queued: people plus
+channels. Delivery happens right after, with retries if Slack is slow; the
+outcome shows on the project's Usage tab.
+
+## What the message looks like
+
+Every message opens with a line the platform writes: your project's name,
+linked to its dashboard page, and "sent by this project via Canopy". Your
+text follows as a new top-level message. Nothing threads onto earlier
+messages, and there are no buttons or blocks: this is a notification, not a
+conversation.
+
+If someone replies under it, the Canopy assistant answers that the message
+came from your project and that replies don't reach it. If you want replies
+to reach your code, you want [a bot of your own](https://docs.canopy.website/platform/slack).
+
+## Who receives it
+
+Channels get every message. People are protected the same way platform
+notifications protect them: a colleague who muted your project hears
+nothing, and anyone can turn off "Messages from projects" in their
+notification settings. Someone whose email has no Slack account is skipped.
+None of this is reported back to your code, so `queued` counts what was
+sent, not what arrived.
+
+An email that is not a Canopy user is refused outright, so you notice the
+typo. Everyone at Monks becomes a Canopy user by opening the dashboard once.
+
+## Linking a channel
+
+Type `/canopy link <your-project-slug>` in the channel, then invite `@Canopy`
+to it. The channel now receives the project's messages, and its activity
+too: reports, project events, deploys. Linked channels are listed under the
+project's **Services → Slack**, where any member can unlink one.
+
+Until a channel is linked, a send without `to` fails with a 404 rather than
+disappearing silently.
+
+## Sending from the backend
+
+Like email, this is meant for code that runs with nobody signed in: a
+[scheduled](https://docs.canopy.website/platform/schedules) job, a worker route reacting to a webhook.
+It authenticates as the project itself. Browser code cannot call it.
+
+```ts
+export default {
+  async scheduled(event, env) {
+    const canopy = createCanopy({ fetch: env.CANOPY.fetch.bind(env.CANOPY) });
+    const stale = await staleRequests(env.DB);
+    if (stale.length === 0) return;
+
+    await canopy.notify.slack({
+      text: `${stale.length} approval request${stale.length === 1 ? "" : "s"} waiting longer than a week.`,
+    });
+  },
+};
+```
+
+## Seeing what was sent
+
+The project's **Usage** tab shows today's count against the quota and the
+recent sends: when, to whom, the first line, and whether it was delivered.
+Only that first line is kept.
+
+## When it fails
+
+Every failure is a `CanopyError` with a status you can branch on:
+
+- **400** — the text is empty or too long, `to` has more than 20 entries, or
+  an address is not a Canopy user (`unknown_recipient`, naming it).
+- **404** — no `to` and no linked channel (`no_linked_channel`).
+- **429** — the project used its daily quota, or the platform-wide ceiling is
+  reached. Both reset at UTC midnight.
+- **501** — this Canopy site has no Canopy bot.
+
+```ts
+import { CanopyError } from "@mediamonks/canopy";
+
+try {
+  await canopy.notify.slack({ text });
+} catch (err) {
+  if (err instanceof CanopyError && err.status === 404) {
+    // Nobody has linked a channel yet — tell a member to run /canopy link.
+  }
+}
+```
+
+## What this is not
+
+This is not a bot. It cannot listen, answer, show buttons, run slash
+commands, post in a client's workspace or carry your project's name and
+icon. The moment you want any of that, give the project [its own Slack
+app](https://docs.canopy.website/platform/slack): a few minutes of setup, and `canopy.slack` does the
+rest.