@mediamonks/canopy-cli 0.7.21 → 0.7.23

package/dist/dev-BFPlhkzp.mjs

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

package/dist/{dev-CNqx_53I.mjs → dev-XULukupE.mjs}

@@ -37,7 +37,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-Bij9OUMk.mjs");
+	const { missingSecretNames, readDevVars, workerDevPlugin } = await import("./dev-worker-BDMjExps.mjs");
 	const secrets = readDevVars(flags.dir);
 	const email = siteConfig().email;
 	const plugin = workerDevPlugin({
@@ -165,7 +165,7 @@ async function devRemote(flags, slug) {
 async function devLocal(flags, slug) {
 	let dump;
 	if (flags.pull) {
-		const { fetchProjectDump } = await import("./local-CsSP4Vpt.mjs");
+		const { fetchProjectDump } = await import("./local-BjsuI1IB.mjs");
 		console.log(`Pulling a fresh export of ${slug}${flags.staging ? " [staging]" : ""}…`);
 		dump = await fetchProjectDump(slug, flags.staging ? "staging" : "live");
 	}
@@ -180,7 +180,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-CsSP4Vpt.mjs");
+	const { createSandbox } = await import("./local-BjsuI1IB.mjs");
 	const sandbox = await createSandbox({
 		slug,
 		persistDir: join(flags.dir, ".canopy", "local"),

package/dist/{dev-worker-Bij9OUMk.mjs → dev-worker-BDMjExps.mjs}

@@ -1,4 +1,4 @@
-import "./src-BKKAEkbH.mjs";
+import "./src-BPKfY9IN.mjs";
 import { readFileSync } from "node:fs";
 import { relative, resolve, sep } from "node:path";
 //#region ../data-plane/src/worker-request.ts
@@ -25,6 +25,39 @@ const IDENTITY_STAMP_HEADERS = [
 	"x-canopy-user-email",
 	"x-canopy-user-name"
 ];
+/** Cookies that authenticate to Canopy itself — the monk session and the client-page session. */
+const CANOPY_COOKIE_NAMES = /* @__PURE__ */ new Set(["canopy_session", "canopy_client"]);
+/**
+* Strip Canopy's own credentials from a request before untrusted project code
+* sees it (R-01).
+*
+* The visitor's session cookie arrives with every request the gateway
+* dispatches, and a bundle that can read it can replay it against the platform
+* as that person — against the control plane, and against other projects' data
+* on the api host. It is a credential, so the host keeps it in closure scope
+* like the raw DB and blob handles, and hands the bundle a redacted request.
+*
+* Redaction is surgical on purpose: an app's own cookies and its own
+* Authorization scheme survive, because those belong to the app. Only
+* `canopy_session` / `canopy_client` and a `cnpy_` bearer are removed.
+*
+* `env.CANOPY.fetch` still authenticates as the visitor — the host passes it
+* the unredacted headers — so nothing about the platform-facing behaviour
+* changes; the credential simply stops being reachable from bundle code.
+*/
+function redactCanopyCredentials(headers) {
+	const cookie = headers.get("cookie");
+	if (cookie !== null) {
+		const kept = cookie.split(";").filter((part) => {
+			const name = part.split("=")[0]?.trim() ?? "";
+			return name !== "" && !CANOPY_COOKIE_NAMES.has(name);
+		}).join(";").trim();
+		if (kept === "") headers.delete("cookie");
+		else headers.set("cookie", kept);
+	}
+	if (headers.get("authorization")?.startsWith("Bearer cnpy_")) headers.delete("authorization");
+	return headers;
+}
 /**
 * Strip what must never travel upstream and stamp who is calling. Common to
 * every host; says nothing about credentials.
@@ -331,6 +364,7 @@ function workerDevPlugin(options) {
 						}));
 						return;
 					}
+					redactCanopyCredentials(request.headers);
 					await sendResponse(res, await worker.fetch(request, env));
 				})().catch((err) => {
 					if (err instanceof Error) server.ssrFixStacktrace(err);

package/dist/docs/cli-login.md

@@ -24,6 +24,8 @@ canopy login --json                # machine-readable status for agents/CI
 2. You finish signing in **in the browser** — your password never passes through the CLI. When OneLogin hands control back, the browser shows a small "You're signed in" page and you can return to the terminal. The sign-in waits up to 5 minutes; the hand-back uses local port `8976`, so if another program holds that port the login fails with a clear message.
 3. The CLI stores a token for **every** site (`main`, `staging`, `gcp-pilot`), not just the one you picked, in `~/.canopy/config.json` — readable only by your user account.
 
+Each token is labelled with your machine's hostname and expires after 30 days. The dashboard's **Account** page (your avatar → Account) lists every machine you have signed in from and lets you revoke any of them; `canopy logout` revokes this machine's tokens for you.
+
 One login therefore covers all sites; `--profile` only decides which one commands target by default. If minting fails for a non-active site you get a warning but login still succeeds; if it fails for your **active** profile the command errors and asks you to re-run.
 
 ## Examples

package/dist/docs/cli-logout.md

@@ -1,25 +1,28 @@
 ---
 title: canopy logout
-description: Sign out of Canopy by removing all locally stored CLI tokens.
+description: Sign out of Canopy — revoke your CLI tokens on every site and forget them locally.
 ---
 
-`canopy logout` signs you out on this machine by forgetting every stored CLI token. Use it on a shared machine, or when you want a clean slate before logging in as someone else.
+`canopy logout` signs you out on this machine: it revokes the CLI token stored for every site on the platform, then forgets them in `~/.canopy/config.json`. Use it on a shared machine, or when you want a clean slate before logging in as someone else.
 
 ## Usage
 
 ```bash
 canopy logout
+canopy logout --local     # forget the tokens here, but leave them valid on the platform
 ```
 
 ## Arguments & flags
 
-None. Logout is deliberately all-or-nothing: it clears the tokens for **every** site (`main`, `staging`, `gcp-pilot`) at once — there is no per-profile logout, so the global `--profile` flag has no effect here.
+- `--local` — only remove the tokens from this machine; nothing is called on the server. The tokens stay valid until they expire (30 days after login), and you can still revoke them from the dashboard's **Account** page.
+
+Logout is deliberately all-or-nothing: it signs out of **every** site (`main`, `staging`, `gcp-pilot`) at once — there is no per-profile logout, so the global `--profile` flag has no effect here.
 
 ## Details
 
-The command is local-only: it removes every stored token from `~/.canopy/config.json` and prints a confirmation. Nothing is called on the server, so the tokens themselves aren't revoked — they simply age out at their normal expiry. Your active-site choice stays in the file, so the next `canopy login` picks up where you left off.
+For each site with a stored token, the command asks the platform to revoke that token, so it stops working everywhere immediately — not just on this machine. Then the file is cleaned up. If a site cannot be reached, the local copy is still removed and the command tells you which tokens it could not revoke; those keep working until they expire, or until you revoke them from the dashboard's **Account** page (your avatar → Account), which lists every machine you have signed in from.
 
-If no token was stored to begin with, it prints `Not logged in.` and exits successfully.
+Your active-site choice stays in the file, so the next `canopy login` picks up where you left off. If no token was stored to begin with, it prints `Not logged in.` and exits successfully.
 
 ## Examples
 
@@ -27,6 +30,6 @@ If no token was stored to begin with, it prints `Not logged in.` and exits succe
 canopy logout
 ```
 
-Removes all site tokens from `~/.canopy/config.json`; subsequent commands that need the API will ask you to run `canopy login`.
+Revokes all site tokens on the platform and removes them from `~/.canopy/config.json`; subsequent commands that need the API will ask you to run `canopy login`.
 
 See also [canopy login](https://docs.canopy.website/cli/login) and [canopy whoami](https://docs.canopy.website/cli/whoami).

package/dist/docs/index.json

@@ -77,11 +77,6 @@
           "title": "CLI command reference",
           "summary": "Every canopy command, its flags, and what it does."
         },
-        {
-          "slug": "notifications",
-          "title": "Slack notifications",
-          "summary": "Canopy DMs you about your reports and projects — replies, new reports, blocked fetches, budget hits, failing schedules — and answers questions when you ask."
-        },
         {
           "slug": "static-serving",
           "title": "How static files are served",
@@ -122,13 +117,18 @@
         {
           "slug": "platform-ai-usage",
           "title": "AI access & usage",
-          "summary": "Projects talk to AI models through the platform — no API keys to manage, a hard daily budget per project, and full visibility of spend."
+          "summary": "Projects talk to AI models through the platform — no API keys to manage, hard per-project budgets, and full visibility of spend."
         },
         {
           "slug": "platform-google",
           "title": "Google",
           "summary": "Let your project work with Google data — Sheets, Docs, Calendar, Drive, Gmail — without handling any OAuth yourself."
         },
+        {
+          "slug": "platform-slack",
+          "title": "Slack",
+          "summary": "Give your project its own Slack bot — Canopy creates and manages the app, your code handles the events."
+        },
         {
           "slug": "platform-members-and-access",
           "title": "Members & access",
@@ -139,11 +139,26 @@
           "title": "Feedback & bug reports",
           "summary": "A built-in feedback widget on every project, a ticket-lite inbox behind it, and a CLI that lets agents work the backlog."
         },
+        {
+          "slug": "platform-notifications",
+          "title": "Notifications",
+          "summary": "Canopy DMs you on Slack about your reports and projects — replies, new reports, blocked fetches, budget hits, failing schedules."
+        },
+        {
+          "slug": "platform-assistant",
+          "title": "The Canopy assistant",
+          "summary": "Ask questions about your projects and the platform in plain language — in Slack, or from the button in the corner of the docs and the dashboard."
+        },
         {
           "slug": "platform-client-access",
           "title": "Client access",
           "summary": "Share a project with clients who have no Monks account — a shared password unlocks that one project's URL and nothing else."
         },
+        {
+          "slug": "platform-security-headers",
+          "title": "Browser security",
+          "summary": "The security headers the platform adds to your app's pages and files, what they block, and the two switches in Settings."
+        },
         {
           "slug": "platform-sites-and-profiles",
           "title": "Sites & profiles",
@@ -174,7 +189,7 @@
         {
           "slug": "cli-logout",
           "title": "canopy logout",
-          "summary": "Sign out of Canopy by removing all locally stored CLI tokens."
+          "summary": "Sign out of Canopy — revoke your CLI tokens on every site and forget them locally."
         },
         {
           "slug": "cli-create",
@@ -323,6 +338,11 @@
           "title": "Google",
           "summary": "Call Google APIs as the project's connected account or as the visitor's own — the platform holds the OAuth."
         },
+        {
+          "slug": "sdk-slack",
+          "title": "Slack",
+          "summary": "Handle your bot's events and slash commands in your worker, and post to Slack as the bot — no tokens in project code."
+        },
         {
           "slug": "sdk-services",
           "title": "Services",

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

@@ -1,11 +1,11 @@
 ---
 title: AI access & usage
-description: Projects talk to AI models through the platform — no API keys to manage, a hard daily budget per project, and full visibility of spend.
+description: Projects talk to AI models through the platform — no API keys to manage, hard per-project budgets, and full visibility of spend.
 ---
 
 Canopy projects can call AI models without you ever handling an API key. The
 platform routes every request through its own metered gateway, tracks what
-each project spends, and enforces a hard daily budget — so a runaway loop in
+each project spends, and enforces hard budgets — so a runaway loop in
 a vibecoded app becomes a capped bill and a visible chart, not a surprise
 invoice.
 
@@ -26,9 +26,26 @@ const reply = await canopy.ai.chat({
   default — ask for a model outside the list and the API tells you what _is_
   available.
 - **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
+  [the AI SDK page](https://docs.canopy.website/sdk/ai). Models that read PDFs and images get the real
+  document, not a text extraction.
 - **An OpenAI-compatible endpoint.** `canopy.ai.endpoint()` returns a base
   URL and model list you can plug into ecosystem tools (like the Vercel AI
   SDK) — same key handling, same budget, same tracking.
+- **Provider-native endpoints.** For provider-specific capabilities —
+  Anthropic prompt caching and PDF citations, OpenAI's Responses API — point
+  an official SDK at the native base URLs from `canopy.ai.endpoint()`. Same
+  budget and tracking as everything else; see [the AI SDK page](https://docs.canopy.website/sdk/ai).
+
+## Request size
+
+A single chat request — prompt, inline base64 attachments, and referenced
+blobs together — can be up to **8 MB**. Base64 makes files about a third
+larger than they are on disk, so that fits roughly a 6 MB document per
+request. Bigger requests answer with a `chat_too_large` error (HTTP 413)
+before anything is sent to a model. Providers also have their own per-file
+limits, which are typically above this.
 
 ## Your data and the model providers
 
@@ -41,16 +58,25 @@ This applies to every way your project reaches AI — `canopy.ai.chat()`,
 streaming, and the OpenAI-compatible endpoint all go through the same gateway
 to the same accounts.
 
-## The daily budget
+## Budgets: a daily limit and a monthly cap
+
+Every project has two AI budgets in USD, enforced from the same spend ledger
+the dashboard displays — so what you see and what's enforced can never
+disagree:
+
+- **A daily limit** (default $5) catches runaway loops. Cross it and AI
+  calls answer `ai_budget_exceeded` until midnight UTC; everything resets
+  the next day.
+- **A monthly cap** (default $20) is the real spending ceiling. Cross it and
+  AI calls pause until the calendar month rolls over.
 
-Every project has a daily AI budget in USD. When a project's spend for the
-day crosses it, further AI calls answer with an `ai_budget_exceeded` error
-until the day rolls over. The budget is enforced from the same spend ledger
-the dashboard displays, so what you see and what's enforced can never
-disagree.
+The error names which one tripped. The Usage tab shows spend against both.
+If a project genuinely needs more headroom, a Canopy admin can raise either
+budget from that same tab — ask in the project's feedback or reach out to
+the platform team.
 
-> **Note:** Hitting the cap doesn't break the rest of your app — pages, data, and files keep working. Only AI
-> calls pause until the next day.
+> **Note:** Hitting a budget doesn't break the rest of your app — pages, data, and files keep working. Only AI
+> calls pause until the window rolls over.
 
 ## The Usage tab
 

package/dist/docs/platform-assistant.md

@@ -0,0 +1,50 @@
+---
+title: The Canopy assistant
+description: Ask questions about your projects and the platform in plain language — in Slack, or from the button in the corner of the docs and the dashboard.
+---
+
+Canopy has an assistant that answers questions about **your projects** and
+**how the platform works**. It reads the same things you can see — your
+projects, their deploys, reports, AI spend, egress log and schedules — plus
+these docs, and answers with a link to the guide it answered from.
+
+It can only read. It never deploys, rolls back, changes settings or touches
+your data; asked to, it points you at the dashboard or the `canopy` CLI.
+
+## Where to ask
+
+**In the docs and the dashboard.** The floating button in the bottom-right
+corner opens a choice: send feedback, or ask the assistant. Pick the second
+and type your question. The page you're on sets the context, so on a project's
+dashboard page "how many deploys today?" already knows which project you mean.
+
+Your conversation survives a reload — come back to the tab an hour later and
+it's still there. **New chat** clears it and starts over. Only one
+conversation is kept, and it lives in your own browser.
+
+**In Slack.** DM **Canopy**, or mention **@Canopy** in a channel. Same
+assistant, same answers. In a channel linked to a project it knows which
+project you mean; replying in a report's notification thread, it knows which
+report. See [Notifications](https://docs.canopy.website/platform/notifications).
+
+## What it's good at
+
+- **"Why is my fetch failing?"** — it checks the egress log and tells you
+  which host was blocked, and where to allow it.
+- **"What happened on my project today?"** — deploys, new reports, status
+  changes.
+- **"How do I promote staging to live?"** — it looks it up in these docs
+  rather than guessing.
+- **"What's the context on this report?"** — the body, the trail, and the
+  triage notes you're allowed to see.
+
+## What it can't do
+
+- **Change anything.** Read-only, by design.
+- **See projects you can't.** Every lookup runs as you: a project you're not
+  on simply doesn't resolve.
+- **Answer questions about your app's own content.** It knows Canopy and your
+  projects on it — not what's inside them.
+
+It runs on a small daily budget shared by everyone. On the rare day that runs
+out, it says so and comes back the next.

package/dist/docs/platform-client-access.md

@@ -36,8 +36,11 @@ it** card:
 2. Send the client the project URL and the password.
 
 To change the password, set a new one — previously handed-out passwords stop
-working for new sign-ins. To turn client access off entirely, remove the
-password from the same card; visitors are back to Monks-only immediately.
+working, and every browser that unlocked the project with the old one is
+signed out on its next visit and asked for the new password. To turn client
+access off entirely, remove the password from the same card, or switch the
+mode back to Monks only; either way, visitors are back to Monks-only
+immediately, unlocked browsers included.
 
 > **Warning:** A shared password is deliberately lightweight protection — right for work-in-progress previews,
 > wrong for anything sensitive. Anyone who has it can view the app and share it further, so rotate

package/dist/docs/platform-feedback.md

@@ -18,6 +18,9 @@ boards.
 
 - Appears only for **signed-in Monks**. Client-password visitors never see it —
   the platform doesn't even send them the script.
+- On Canopy's own pages (these docs and the dashboard) the same button also
+  opens [the assistant](https://docs.canopy.website/platform/assistant); on your project it is a feedback
+  widget and nothing else.
 - On by default for every project. Turn it off per project in
   **Settings → Feedback widget**; the change applies on the next page load.
 - Submissions are always identified (your company sign-in), so there's no

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

@@ -61,11 +61,34 @@ Turning it off again is the same toggle.
 > **Note:** Collaborators-only gates the **live app**. Management access (settings, data, deploys) is always
 > members-only, regardless of this toggle.
 
-## Platform admins and the Users page
-
-Platform admins get an extra **Users** page in the dashboard listing everyone
-on Canopy — name, email, and when they first signed in — with a one-click way
-to grant or remove admin. Accounts are created automatically on first
-OneLogin sign-in; there is nothing to provision.
+## Platform admins and the Admin page
+
+Platform admins get an extra **Admin** page in the dashboard. Its **Users**
+tab lists everyone on Canopy — name, email, when they first and last signed
+in — with a one-click way to grant or remove admin and to sign someone out
+everywhere. Its **Sessions** tab lists every live CLI sign-in on the site:
+who, from which machine, and when it was last used, each revocable on the
+spot. Accounts are created automatically on first OneLogin sign-in; there is
+nothing to provision.
+
+## Your sign-ins, and signing out everywhere
+
+A Canopy sign-in lives in two places: the browser session from OneLogin, and
+the CLI tokens `canopy login` stores on each machine (one per site). Your
+**Account** page — open the avatar menu in the dashboard header — lists the
+machines you have signed in from, with when each token was last used, and lets
+you revoke any of them. Revoking a token is what `canopy logout` does for the
+machine it runs on.
+
+**Sign out everywhere** on the same page ends every browser session and every
+CLI sign-in of yours on that site at once, this one included. Reach for it
+when a laptop goes missing or you signed in somewhere you shouldn't have; the
+next request from any of those places meets the sign-in page. Deploy tokens
+used by CI belong to their projects, not to you, and keep working — revoke
+those from the project's Deploys tab if they were on the lost machine too.
+
+Platform admins have the same button for any user on the **Admin** page, which
+is how someone who leaves the company is signed out of Canopy before their
+open sessions would have expired on their own.
 
 - [Client access](https://docs.canopy.website/platform/client-access) — Share work-in-progress with clients who don't have a Monks account.

package/dist/docs/{notifications.md → platform-notifications.md}

@@ -1,6 +1,6 @@
 ---
-title: Slack notifications
-description: Canopy DMs you about your reports and projects — replies, new reports, blocked fetches, budget hits, failing schedules — and answers questions when you ask.
+title: Notifications
+description: Canopy DMs you on Slack about your reports and projects — replies, new reports, blocked fetches, budget hits, failing schedules.
 ---
 
 Canopy sends you Slack DMs when something on the platform needs your
@@ -51,6 +51,10 @@ for that it points you at the dashboard or the CLI. In a channel that's
 linked to a project, it already knows which project you mean; replying in a
 report's notification thread, it knows which report.
 
+The same assistant answers from the button in the corner of these docs and
+the dashboard, if you'd rather not switch to Slack — see
+[The Canopy assistant](https://docs.canopy.website/platform/assistant).
+
 ## If DMs don't arrive
 
 The bot finds you by your work email. If your Slack account uses a different

package/dist/docs/platform-security-headers.md

@@ -0,0 +1,53 @@
+---
+title: Browser security
+description: The security headers the platform adds to your app's pages and files, what they block, and the two switches in Settings.
+---
+
+Every project on Canopy shares one sign-in, so a script that manages to run
+inside one app is a script running next to every other app a visitor can open.
+To keep that from mattering, the platform adds a small set of browser security
+headers to the pages and files it serves for you. You don't configure anything
+to get them, and most projects never notice they're there.
+
+## What your pages get
+
+- **A Content-Security-Policy.** Scripts may load from your own app and from
+  any `https://` address, so CDNs and hosted libraries keep working. Inline
+  `<script>` blocks that are part of your deployed HTML keep working too — the
+  platform reads them at serve time and allows exactly those. What's blocked:
+  inline event handlers such as `onclick="…"`, `javascript:` links, plugins
+  (`<object>`, `<embed>`), scripts loaded over plain `http://`, and inline
+  scripts that were _not_ in your deploy — which is what an injected script
+  usually is.
+- **No embedding by other sites.** Your pages can only be shown in an iframe by
+  your own app.
+- **A referrer policy and HTTPS pinning.** Other sites see your origin but not
+  your full URLs, and browsers remember to always use HTTPS.
+
+## The two switches
+
+Both live on the project's **Settings → Security** page, and both take effect
+on the next page load — no redeploy.
+
+- **Content-Security-Policy** — on by default. Turn it off if your app depends
+  on something the policy blocks and you can't change it: an inline `onclick`,
+  a `javascript:` link, a library that writes `<script>` tags into the page at
+  runtime, or a backend route that renders HTML with its own inline scripts.
+  Check the browser console first — a blocked script shows up there with the
+  directive that stopped it.
+- **Allow embedding in other sites** — off by default. Turn it on when another
+  site needs to show this app in an iframe.
+
+Backend-rendered pages (a worker route that returns HTML) receive the framing
+and referrer headers but no script policy, because the platform only hashes
+inline scripts it knows came from a deploy.
+
+## Files you store
+
+Files saved with `canopy.blob` are served from your app's address, with the
+content type you gave them. Images, video, audio, fonts, plain text, CSV, JSON
+and PDF display normally. SVGs display too, but sandboxed — fine in an
+`<img>`, and harmless if someone opens the URL directly. Anything a browser
+would treat as a page — HTML, XML, scripts, or files with an unknown type —
+downloads instead of rendering. If you want to show user-uploaded HTML, render
+it inside your own page rather than linking to the stored file.

package/dist/docs/platform-slack.md

@@ -0,0 +1,87 @@
+---
+title: Slack
+description: Give your project its own Slack bot — Canopy creates and manages the app, your code handles the events.
+---
+
+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
+code never sees a bot token, a signing secret, or a webhook — it exports a
+handler and calls `canopy.slack`, both covered in
+[the SDK reference](https://docs.canopy.website/sdk/slack).
+
+Everything on this page happens on the project's **Services** tab.
+
+## One-time: your configuration token
+
+Creating Slack apps requires a Slack _app configuration token_, which is
+personal — it belongs to you, in one workspace. You set it up once and every
+project you manage shares it:
+
+1. Go to [api.slack.com/apps](https://api.slack.com/apps) and pick the
+   workspace your bots should live in — **that choice is baked into the
+   token**, and it's where every app you create will land.
+2. Under "Your App Configuration Tokens", generate a token and copy the
+   **refresh token** (the one starting `xoxe-1-`). The access token isn't
+   needed.
+3. Paste it into the token section of any project's Services tab and save.
+
+Canopy validates it against Slack, stores it encrypted, and keeps it fresh
+from then on — this is genuinely one-time. If it ever stops working (for
+example, it was revoked), existing bots keep running; only app-settings
+changes pause until you paste a fresh one.
+
+To create bots in a different workspace — a client's, say — generate a token
+for that workspace and save it. One workspace at a time per person.
+
+## Creating the app
+
+Name the bot, pick its features, create. Every app comes with a bot that can
+be invited to channels, post messages, and send people direct messages — the
+notification baseline, no options needed. On top of that:
+
+- **AI assistant** — people can chat with the bot: by @-mentioning it in
+  channels, in direct messages, and in Slack's assistant pane. Without it
+  the bot only sends; nobody can talk back. One caveat from Slack's side:
+  once on, it can't be turned off again.
+- **Slash commands** — each becomes a workspace command handled by your
+  backend. Command names aren't reserved per app, so pick ones another app
+  in the workspace isn't already using.
+
+## Installing to the workspace
+
+Creating the app doesn't put it in the workspace — installing does, and
+that's a human step by design: you approve the bot's permissions on Slack's
+own screen. Click **Install to workspace** and follow it through.
+
+If your workspace requires admin approval for new apps, the first attempt
+becomes an approval request instead. Once the admin approves (Slack DMs you
+about it), either come back and click install again, or use the install
+link Slack itself offers — both complete the same way. A Slack-side install
+only works into the workspace the app already belongs to.
+
+The same button reappears whenever you change features in a way that needs
+new permissions — the card shows a clear warning when saved changes are
+waiting on a reinstall. Feature changes that don't widen permissions apply
+immediately.
+
+## Day to day
+
+- **The status line** shows where the app is installed and when Slack last
+  delivered something — the quickest "is it wired up" check.
+- **Enabled** is the kill switch: off, Slack traffic is accepted and
+  dropped, nothing reaches your code, and outbound sends are refused. The
+  app stays installed; flip it back anytime.
+- **Remove Slack app** deletes the app from the workspace too — bot,
+  commands, history access, all of it.
+
+Every message your project sends through the bot is counted per day, so a
+runaway loop is visible.
+
+## Local development
+
+Slack needs a public URL to deliver to, so `canopy dev` can't receive
+events or commands. Test inbound handling on a deployed project — a scratch
+project with a scratch bot works well — and unit-test your handler directly.
+Outbound (`canopy.slack.api`) works from `canopy dev` like any other SDK
+call.