@mediamonks/canopy-cli 0.1.0 → 0.2.0

package/dist/docs/ci.md

@@ -0,0 +1,48 @@
+---
+title: CI and deploy tokens
+summary: Push-to-main deploys using a project-scoped deploy token.
+---
+
+# CI and deploy tokens
+
+Interactive `canopy login` is for humans at a terminal. For automated deploys
+(GitHub Actions, etc.) use a **deploy token**: a project-scoped credential that
+can deploy that one project and nothing else.
+
+## Create a token
+
+From inside the project directory:
+
+```bash
+canopy token create --name "GitHub Actions"
+```
+
+This prints the token **once** — copy it immediately and store it as a CI secret
+(e.g. `CANOPY_DEPLOY_TOKEN`). It is not shown again.
+
+Manage tokens:
+
+```bash
+canopy token list
+canopy token revoke <id>
+```
+
+## Use it in CI
+
+The CLI picks up `CANOPY_DEPLOY_TOKEN` from the environment and uses it instead
+of an interactive login. A minimal GitHub Actions step:
+
+```yaml
+- run: npm install -g @mediamonks/canopy-cli
+- run: canopy deploy --build
+  env:
+    CANOPY_DEPLOY_TOKEN: ${{ secrets.CANOPY_DEPLOY_TOKEN }}
+```
+
+No `canopy login` step is needed — the token is the credential.
+
+## Notes
+
+- A deploy token can only deploy its own project. If it strays to another
+  project's resources, the platform rejects it.
+- Revoke a token the moment it might be exposed; create a fresh one to replace it.

package/dist/docs/cli.md

@@ -0,0 +1,67 @@
+---
+title: CLI command reference
+summary: Every canopy command, its flags, and what it does.
+---
+
+# CLI command reference
+
+Run `canopy <command> --help` for the authoritative flags of any command. This
+is the overview.
+
+## Auth
+
+- `canopy login` — sign in via OneLogin (opens the browser; finish there).
+  Add `--json` for machine-readable status output (for agents/CI).
+- `canopy whoami` — show the current login and token expiry.
+- `canopy logout` — forget the local CLI token.
+
+## Projects
+
+- `canopy create [name]` — create and register a project.
+  - `--slug <slug>` — URL slug (defaults to a slugified name).
+  - `--template <id>` — `static` | `spa` | `worker` (picker when omitted).
+  - `--scaffold` — write `./<slug>/` from the starter template.
+- `canopy projects` — list your projects. `--all` includes ones you can't edit.
+- `canopy delete [slug]` — full teardown of a project. `--yes` skips the
+  type-the-slug confirmation.
+
+## Develop
+
+- `canopy dev` — run the project locally against live platform data.
+  - `--port <port>` — dev server port.
+  - `--local` — offline sandbox (Miniflare D1/R2 under `.canopy/local/`).
+  - `--pull` — hydrate the sandbox from a fresh prod export first (with `--local`).
+
+## Deploy
+
+- `canopy deploy` — build and deploy the project.
+  - `--build` — run the `canopy.json` build command first.
+- `canopy rollback [version]` — make an earlier deploy live again, e.g. `v3`
+  (picked from history when omitted). `--dir <path>` to target another directory.
+- `canopy open` — open the deployed project in your browser.
+
+## Data
+
+- `canopy db pull` — download a fresh SQL dump. `--out <file>` to name it.
+- `canopy db snapshot` — store a dump server-side (restorable anytime).
+- `canopy db snapshots` — list stored snapshots.
+- `canopy db restore [file]` — replace ALL project data from a `.sql` file or
+  `--snapshot <key>`. `--yes` skips the confirmation. **Destructive.**
+
+## CI / deploy tokens
+
+- `canopy token create` — create a project-scoped deploy token for CI.
+  `--name "<label>"` to label it.
+- `canopy token list` — list the project's deploy tokens.
+- `canopy token revoke <id>` — revoke a token.
+
+See `canopy docs ci` for wiring push-to-main deploys.
+
+## Maintenance
+
+- `canopy upgrade` — update the CLI to the latest version. `--version <v>` pins a
+  release; `--pm <npm|pnpm|yarn|bun>` overrides the package-manager guess.
+  Upgrading also refreshes the installed Canopy agent skill.
+- `canopy docs [topic]` — list docs, or print one. `--refresh` re-fetches from
+  the platform.
+- `canopy skill install` — (re)install the Canopy agent skill into this repo.

package/dist/docs/data.md

@@ -0,0 +1,49 @@
+---
+title: Working with project data
+summary: Pulling, snapshotting, and restoring your project database.
+---
+
+# Working with project data
+
+Each Canopy project gets its own database (D1) and blob storage (R2). Your app
+reads and writes them through the Canopy SDK at runtime; the CLI gives you tools
+to manage the data around it.
+
+## Download a dump
+
+```bash
+canopy db pull                 # writes <slug>-<timestamp>.sql
+canopy db pull --out data.sql  # choose the filename
+```
+
+A plain SQL dump you can inspect, diff, or keep as a backup.
+
+## Snapshots (server-side backups)
+
+```bash
+canopy db snapshot     # store a dump on the platform
+canopy db snapshots    # list stored snapshots
+```
+
+Snapshots live on the platform and can be restored at any time — handy before a
+risky change.
+
+## Restore — destructive
+
+Restoring **replaces ALL project data**:
+
+```bash
+canopy db restore backup.sql          # from a local dump
+canopy db restore --snapshot <key>    # from a server-side snapshot
+```
+
+You'll be asked to type the project slug to confirm. `--yes` skips that prompt —
+use it only in scripts you trust.
+
+## Safe workflow for agents
+
+Before any destructive data change:
+
+1. `canopy db snapshot` — take a restore point.
+2. Make the change (or test it first with `canopy dev --local --pull`).
+3. If something goes wrong, `canopy db restore --snapshot <key>`.

package/dist/docs/deploy.md

@@ -0,0 +1,50 @@
+---
+title: Deploying a project
+summary: How canopy deploy builds, uploads, and makes a version live.
+---
+
+# Deploying a project
+
+From inside a project directory:
+
+```bash
+canopy deploy
+```
+
+This uploads your built assets to the platform, creates a new immutable deploy
+version, and makes it live. Each deploy is versioned (`v1`, `v2`, …).
+
+## Building first
+
+If your project needs a build step (React SPA, anything with a bundler), declare
+the build command in `canopy.json` and pass `--build`:
+
+```bash
+canopy deploy --build
+```
+
+`--build` runs the project's configured build command before uploading. Without
+it, `canopy deploy` uploads whatever is already built (or the static files as-is
+for a `static` project).
+
+## Rolling back
+
+Every deploy is kept, so you can instantly revert:
+
+```bash
+canopy rollback          # pick a version from history
+canopy rollback v3       # make v3 live again
+```
+
+Rollback re-points the live version at an existing deploy — it does not rebuild.
+
+## Seeing the live site
+
+```bash
+canopy open
+```
+
+## Deploying from CI
+
+For automated push-to-main deploys, use a deploy token instead of an interactive
+login — see `canopy docs ci`.

package/dist/docs/dev.md

@@ -0,0 +1,44 @@
+---
+title: Local development
+summary: Running a project locally against live or sandboxed data.
+---
+
+# Local development
+
+From inside a project directory:
+
+```bash
+canopy dev
+```
+
+By default `canopy dev` runs your project locally but talks to **live platform
+data** (your project's real database, blobs, and AI). This is the fastest way to
+develop against realistic state.
+
+- `--port <port>` — choose the dev-server port.
+
+## Offline sandbox
+
+To develop without touching live data — for example on a plane, or before you
+trust a destructive change — use a local sandbox backed by Miniflare:
+
+```bash
+canopy dev --local
+```
+
+This creates local D1 and R2 under `.canopy/local/` in your project. The sandbox
+starts empty.
+
+To seed the sandbox from a fresh copy of production data first:
+
+```bash
+canopy dev --local --pull
+```
+
+`.canopy/local/` is disposable — delete it to reset the sandbox.
+
+## Which mode should an agent use?
+
+- Iterating on UI or read-only features → `canopy dev` (live data, realistic).
+- Testing writes, migrations, or anything destructive → `canopy dev --local`
+  (optionally `--pull` to start from real data).

package/dist/docs/getting-started.md

@@ -0,0 +1,100 @@
+---
+title: Getting started
+summary: Install the CLI, sign in with OneLogin, and ship your first project.
+---
+
+# Getting started with Canopy
+
+Canopy is Monks' managed platform for vibecoded projects. You build a small web
+app, and Canopy hosts it, gives it a database, blob storage, and AI — no
+infrastructure to manage.
+
+This guide is written so an AI coding agent (Claude, Cursor, etc.) can follow it
+on your behalf. Everything runs through one command-line tool: `canopy`.
+
+## 1. Install the CLI
+
+The CLI is published on npm. Install it globally:
+
+```bash
+npm install -g @mediamonks/canopy-cli
+```
+
+Confirm it's on your PATH:
+
+```bash
+canopy --version
+```
+
+If `npm` isn't available, install Node.js 20+ first (https://nodejs.org), then
+re-run the install.
+
+## 2. Sign in
+
+Canopy authenticates through Monks' OneLogin. Run:
+
+```bash
+canopy login
+```
+
+This opens your browser. **Finish the sign-in there** — the CLI waits for the
+browser to redirect back, then stores a token in `~/.canopy/config.json`.
+
+> If you are an agent: run `canopy login`, then stop and tell the human to
+> complete the sign-in in the browser window that just opened. Never ask for or
+> type the user's password or any codes yourself.
+
+Check who you are at any time:
+
+```bash
+canopy whoami
+```
+
+## 3. Create a project
+
+```bash
+canopy create
+```
+
+This prompts for a name and a starter template, scaffolds a runnable project
+directory, and registers the project on the platform. To skip the prompts:
+
+```bash
+canopy create "My App" --scaffold --template static
+```
+
+## 4. Run it locally
+
+```bash
+cd my-app
+canopy dev
+```
+
+Your project runs against live platform data by default. For an offline sandbox
+with local data, use `canopy dev --local`.
+
+## 5. Deploy
+
+```bash
+canopy deploy
+```
+
+Then open the live site:
+
+```bash
+canopy open
+```
+
+## Where to go next
+
+Everything the CLI can do is documented and available offline. List the topics:
+
+```bash
+canopy docs
+```
+
+Read one, e.g.:
+
+```bash
+canopy docs deploy
+```

package/dist/docs/troubleshooting.md

@@ -0,0 +1,61 @@
+---
+title: Troubleshooting
+summary: Common errors and how to resolve them.
+---
+
+# Troubleshooting
+
+## `command not found: canopy`
+
+The CLI isn't installed or isn't on your PATH. Install it:
+
+```bash
+npm install -g @mediamonks/canopy-cli
+```
+
+If it installs but still isn't found, your npm global bin directory isn't on your
+PATH. Run `npm bin -g` to find it and add that directory to your PATH.
+
+## `Not logged in — run canopy login`
+
+You have no valid CLI token. Run `canopy login` and finish the sign-in in the
+browser. Check status with `canopy whoami`.
+
+## `Session expired — run canopy login again`
+
+Your token expired. Just run `canopy login` again.
+
+## The browser didn't open during login
+
+`canopy login` prints the sign-in URL as a fallback — open it manually in a
+browser on the **same machine** as the CLI (login uses a local loopback
+redirect, so it must be the same machine).
+
+## `Port 8976 is in use`
+
+A previous login attempt is still holding the callback port. Close it (or wait a
+moment) and retry `canopy login`.
+
+## Login hangs and never completes
+
+Login only works when the CLI runs on the machine whose browser you're using
+(the redirect goes to `127.0.0.1`). It cannot complete on a remote/headless box.
+Run it on your own laptop.
+
+## `Deploy token rejected`
+
+The `CANOPY_DEPLOY_TOKEN` was revoked or is wrong. Create a new one with
+`canopy token create` (or in the dashboard) and update your CI secret.
+
+## Docs are stale
+
+`canopy docs` caches the platform's docs. Force a refresh:
+
+```bash
+canopy docs <topic> --refresh
+```
+
+## Still stuck?
+
+Run the failing command again and share its full output. `canopy whoami` and
+`canopy --version` are useful to include.

package/dist/docs-C3aOAx_A.mjs

@@ -0,0 +1,179 @@
+import { t as readConfig } from "./config-C-z7st1X.mjs";
+import { n as reportErrors } from "./ui-C8VuPzGp.mjs";
+import { defineCommand } from "citty";
+import { existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+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
+* snapshot as offline fallbacks.
+*
+* The platform requires a login for docs (internal platform), so fetches carry
+* the CLI token when there is one; without it we simply fall back to the
+* bundled snapshot, so `canopy docs` still works before sign-in.
+*
+* Resolution order for content:
+*   1. platform (unless a fresh cache exists and --refresh wasn't passed)
+*   2. local cache (~/.canopy/docs-cache/)
+*   3. bundled snapshot shipped with the CLI (dist/docs, repo docs/guides in dev)
+*/
+const cacheDir = join(homedir(), ".canopy", "docs-cache");
+const indexPath = join(cacheDir, "index.json");
+const CACHE_TTL_MS = 3600 * 1e3;
+const FETCH_TIMEOUT_MS = 4e3;
+/** The bundled snapshot dir: dist/docs when published, repo docs/guides in dev. */
+function bundledDocsDir() {
+	const base = fileURLToPath(new URL(".", import.meta.url));
+	for (const candidate of [join(base, "docs"), join(base, "..", "..", "..", "docs", "guides")]) if (existsSync(candidate)) return candidate;
+}
+/** Parse `---\ntitle: …\nsummary: …\n---\n<body>` frontmatter. */
+function parseFrontmatter(raw) {
+	const match = /^---\n([\s\S]*?)\n---\n?([\s\S]*)$/.exec(raw);
+	if (!match?.[1] || match[2] === void 0) return { body: raw.trim() };
+	const meta = {};
+	for (const line of match[1].split("\n")) {
+		const kv = /^([a-zA-Z0-9_-]+):\s*(.*)$/.exec(line);
+		if (kv?.[1]) meta[kv[1]] = (kv[2] ?? "").trim();
+	}
+	return {
+		title: meta["title"],
+		summary: meta["summary"],
+		body: match[2].trim()
+	};
+}
+/** 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;
+	return token ? { authorization: `Bearer ${token}` } : {};
+}
+async function fetchRes(url) {
+	try {
+		const controller = new AbortController();
+		const timer = setTimeout(() => controller.abort(), FETCH_TIMEOUT_MS);
+		const res = await fetch(url, {
+			signal: controller.signal,
+			headers: {
+				accept: "*/*",
+				...authHeaders()
+			}
+		});
+		clearTimeout(timer);
+		return res;
+	} catch {
+		return;
+	}
+}
+async function fetchJson(url) {
+	const res = await fetchRes(url);
+	return res?.ok ? await res.json() : void 0;
+}
+async function fetchText(url) {
+	const res = await fetchRes(url);
+	return res?.ok ? await res.text() : void 0;
+}
+function cacheFresh() {
+	try {
+		const { fetchedAt } = JSON.parse(readFileSync(indexPath, "utf8"));
+		return fetchedAt !== void 0 && Date.now() - Date.parse(fetchedAt) < CACHE_TTL_MS;
+	} catch {
+		return false;
+	}
+}
+function writeCache(file, content) {
+	try {
+		mkdirSync(cacheDir, { recursive: true });
+		writeFileSync(join(cacheDir, file), content);
+	} catch {}
+}
+/** Topics from cache, else from the bundled snapshot's frontmatter. */
+function topicsFromFallback() {
+	try {
+		const cached = JSON.parse(readFileSync(indexPath, "utf8"));
+		if (cached.topics?.length) return cached.topics;
+	} catch {}
+	const dir = bundledDocsDir();
+	if (!dir) return [];
+	return readdirSync(dir).filter((f) => f.endsWith(".md")).map((f) => {
+		const slug = f.replace(/\.md$/, "");
+		const { title, summary } = parseFrontmatter(readFileSync(join(dir, f), "utf8"));
+		return {
+			slug,
+			title: title ?? slug,
+			summary: summary ?? ""
+		};
+	});
+}
+/** A single doc's body from cache, else from the bundled snapshot. */
+function bodyFromFallback(slug) {
+	const cached = join(cacheDir, `${slug}.md`);
+	if (existsSync(cached)) return readFileSync(cached, "utf8");
+	const dir = bundledDocsDir();
+	const file = dir && join(dir, `${slug}.md`);
+	if (file && existsSync(file)) return parseFrontmatter(readFileSync(file, "utf8")).body;
+}
+async function listTopics(refresh) {
+	const { apiUrl } = readConfig();
+	if (refresh || !cacheFresh()) {
+		const data = await fetchJson(`${apiUrl}/v1/docs`);
+		if (data?.topics) {
+			writeCache("index.json", JSON.stringify({
+				fetchedAt: (/* @__PURE__ */ new Date()).toISOString(),
+				...data
+			}));
+			return data.topics;
+		}
+	}
+	return topicsFromFallback();
+}
+async function readTopic(slug, refresh) {
+	const { apiUrl } = readConfig();
+	if (refresh || !existsSync(join(cacheDir, `${slug}.md`))) {
+		const body = await fetchText(`${apiUrl}/v1/docs/${encodeURIComponent(slug)}`);
+		if (body !== void 0) {
+			writeCache(`${slug}.md`, body);
+			return body;
+		}
+	}
+	return bodyFromFallback(slug);
+}
+const docsCommand = defineCommand({
+	meta: {
+		name: "docs",
+		description: "Read the Canopy guides (offline-capable)"
+	},
+	args: {
+		topic: {
+			type: "positional",
+			required: false,
+			description: "Topic to print (omit to list)"
+		},
+		refresh: {
+			type: "boolean",
+			default: false,
+			description: "Re-fetch from the platform"
+		}
+	},
+	run: reportErrors("docs", async ({ args }) => {
+		const refresh = args.refresh;
+		const topic = args.topic;
+		if (!topic) {
+			const topics = await listTopics(refresh);
+			if (topics.length === 0) throw new Error("No docs available — check your connection, or reinstall the CLI.");
+			const width = Math.max(...topics.map((t) => t.slug.length));
+			console.log("Canopy docs — run `canopy docs <topic>`:\n");
+			for (const t of topics) console.log(`  ${t.slug.padEnd(width)}  ${t.summary}`);
+			return;
+		}
+		const body = await readTopic(topic, refresh);
+		if (body === void 0) {
+			const known = (await listTopics(false)).map((t) => t.slug).join(", ");
+			throw new Error(`No doc "${topic}".${known ? ` Available: ${known}.` : ""}`);
+		}
+		console.log(body);
+	})
+});
+//#endregion
+export { docsCommand };

package/dist/index.mjs

@@ -1,9 +1,7 @@
 #!/usr/bin/env node
+import { t as version } from "./package-OcWG7JAW.mjs";
 import { i as runRefresh, r as notifyOfUpdate } from "./version-check-CoWgQs2h.mjs";
 import { defineCommand, runMain } from "citty";
-//#region package.json
-var version = "0.1.0";
-//#endregion
 //#region src/index.ts
 /**
 * canopy — the Canopy CLI.
@@ -43,9 +41,9 @@ const main = defineCommand({
 		description: "canopy — create and deploy vibecoded projects"
 	},
 	subCommands: {
-		login: () => import("./login-DsWvYc8C.mjs").then((m) => m.loginCommand),
-		whoami: () => import("./login-DsWvYc8C.mjs").then((m) => m.whoamiCommand),
-		logout: () => import("./login-DsWvYc8C.mjs").then((m) => m.logoutCommand),
+		login: () => import("./login-Dif9Y32q.mjs").then((m) => m.loginCommand),
+		whoami: () => import("./login-Dif9Y32q.mjs").then((m) => m.whoamiCommand),
+		logout: () => import("./login-Dif9Y32q.mjs").then((m) => m.logoutCommand),
 		create: () => import("./projects-DJT_mJDR.mjs").then((m) => m.createCommand),
 		projects: () => import("./projects-DJT_mJDR.mjs").then((m) => m.projectsCommand),
 		delete: () => import("./projects-DJT_mJDR.mjs").then((m) => m.deleteCommand),
@@ -55,7 +53,9 @@ const main = defineCommand({
 		token: () => import("./token-rTD9jxPZ.mjs").then((m) => m.tokenCommand),
 		db: () => import("./db-CtUG4vfG.mjs").then((m) => m.dbCommand),
 		open: () => import("./open-xLiGUz_W.mjs").then((m) => m.openCommand),
-		upgrade: () => import("./upgrade-TbMOjkLY.mjs").then((m) => m.upgradeCommand),
+		docs: () => import("./docs-C3aOAx_A.mjs").then((m) => m.docsCommand),
+		skill: () => import("./skill-jbmERP1X.mjs").then((m) => m.skillCommand),
+		upgrade: () => import("./upgrade-Y8ejvoeg.mjs").then((m) => m.upgradeCommand),
 		logs: planned("logs", "Tail worker logs", "2")
 	}
 });

package/dist/{login-DsWvYc8C.mjs → login-Dif9Y32q.mjs}

@@ -79,10 +79,26 @@ const loginCommand = defineCommand({
 		name: "login",
 		description: "Sign in to Canopy via OneLogin"
 	},
-	run: reportErrors("login", () => login())
+	args: { json: {
+		type: "boolean",
+		default: false,
+		description: "Emit machine-readable status to stdout (for agents/CI)"
+	} },
+	run: reportErrors("login", async ({ args }) => {
+		const json = args.json;
+		try {
+			await login(json);
+		} catch (err) {
+			if (json) console.log(JSON.stringify({
+				status: "error",
+				message: err instanceof Error ? err.message : String(err)
+			}));
+			throw err;
+		}
+	})
 });
-async function login() {
-	p.intro("canopy login");
+async function login(json) {
+	if (!json) p.intro("canopy login");
 	const config = readConfig();
 	const { issuer, cliClientId, apiUrl } = config;
 	if (cliClientId.includes("REPLACE")) throw new Error("The CLI's OneLogin app is not configured yet (set CANOPY_OIDC_CLIENT_ID or packages/cli/src/config.ts).");
@@ -102,18 +118,24 @@ async function login() {
 		code_challenge_method: "S256"
 	}).toString();
 	const authorizeHref = authorizeUrl.toString();
-	p.note(`If nothing opens, visit:\n${authorizeHref}`, "Opening OneLogin in your browser");
 	openBrowser(authorizeHref);
-	const spin = p.spinner();
-	spin.start("Waiting for you to sign in in the browser…");
+	const spin = json ? void 0 : p.spinner();
+	if (json) console.log(JSON.stringify({
+		status: "waiting",
+		url: authorizeHref
+	}));
+	else {
+		p.note(`If nothing opens, visit:\n${authorizeHref}`, "Opening OneLogin in your browser");
+		spin?.start("Waiting for you to sign in in the browser…");
+	}
 	let code;
 	try {
 		code = await waitForCallback(state);
 	} catch (err) {
-		spin.error("Sign-in failed.");
+		spin?.error("Sign-in failed.");
 		throw err;
 	}
-	spin.stop("Signed in with OneLogin.");
+	spin?.stop("Signed in with OneLogin.");
 	const tokenRes = await fetch(discovery.token_endpoint, {
 		method: "POST",
 		headers: { "content-type": "application/x-www-form-urlencoded" },
@@ -141,7 +163,12 @@ async function login() {
 		tokenExpiresAt: expires_at,
 		email: user.email
 	});
-	p.outro(`Logged in as ${user.name} <${user.email}> (token expires ${expires_at}).`);
+	if (json) console.log(JSON.stringify({
+		status: "ok",
+		email: user.email,
+		expiresAt: expires_at
+	}));
+	else p.outro(`Logged in as ${user.name} <${user.email}> (token expires ${expires_at}).`);
 }
 //#endregion
 export { loginCommand, logoutCommand, whoamiCommand };

package/dist/package-OcWG7JAW.mjs

@@ -0,0 +1,4 @@
+//#region package.json
+var version = "0.2.0";
+//#endregion
+export { version as t };

package/dist/skill/canopy/SKILL.md

@@ -0,0 +1,80 @@
+---
+name: canopy
+description: >-
+  Build, run, and deploy projects on Canopy — Monks' managed platform for
+  vibecoded apps (hosting + database + blob storage + AI). Use this whenever the
+  user wants to create a Canopy project, run/deploy one, manage its data or
+  deploy tokens, or asks how to use the `canopy` CLI. All platform docs are
+  available offline via `canopy docs`.
+---
+
+# Canopy
+
+Canopy is Monks' managed platform for vibecoded projects. Everything is driven
+by one CLI: **`canopy`**. This skill tells you how to drive it; the CLI itself
+carries the full, always-current documentation.
+
+## First: is the CLI installed and signed in?
+
+Run these before anything else, in order:
+
+```bash
+canopy --version   # is the CLI installed?
+canopy whoami      # is there a valid login?
+```
+
+- **`canopy --version` fails / command not found** → install it:
+
+  ```bash
+  npm install -g @mediamonks/canopy-cli
+  ```
+
+  (Needs Node.js 20+. If `npm` is missing, tell the user to install Node first.)
+
+- **`canopy whoami` says not logged in / expired** → run:
+  ```bash
+  canopy login
+  ```
+  This opens the user's browser. **Then STOP and tell the user to complete the
+  sign-in in their browser.** The command waits for them and finishes on its own.
+  - Never ask for or type the user's password, OneLogin codes, or any
+    credentials yourself.
+  - Login only works on the user's own machine (it uses a `127.0.0.1` redirect).
+    If you're on a remote/headless box, tell the user — it can't complete there.
+  - `canopy login --json` gives machine-readable status if you need to parse it.
+
+Skip login if `canopy whoami` already shows a valid, unexpired token.
+
+## Then: read the docs for whatever you're doing
+
+The CLI ships the full documentation and keeps it fresh from the platform. List
+the topics and read the relevant one _before_ running unfamiliar commands:
+
+```bash
+canopy docs            # list all topics
+canopy docs deploy     # print one topic
+```
+
+Available topics include: `getting-started`, `cli` (full command reference),
+`deploy`, `dev`, `data`, `ci`, `troubleshooting`. Always prefer `canopy docs`
+and `canopy <command> --help` over guessing flags — they are the source of
+truth and never go stale.
+
+## Command map (quick orientation — see `canopy docs cli` for detail)
+
+- Create a project: `canopy create`
+- Run locally: `canopy dev` (live data) or `canopy dev --local` (offline sandbox)
+- Deploy: `canopy deploy` (add `--build` if the project has a build step)
+- Roll back: `canopy rollback`
+- Open the live site: `canopy open`
+- Manage data: `canopy db pull | snapshot | snapshots | restore`
+- CI credentials: `canopy token create | list | revoke`
+
+## Safety rules
+
+- **Destructive commands** — `canopy db restore` and `canopy delete` wipe data.
+  Confirm intent with the user first, and take a `canopy db snapshot` before
+  restores.
+- **Deploys are public.** `canopy deploy` makes a version live. Confirm before
+  deploying unless the user clearly asked you to.
+- Keep the CLI current: `canopy upgrade` (this also refreshes this skill).

package/dist/skill-jbmERP1X.mjs

@@ -0,0 +1,84 @@
+import { t as version } from "./package-OcWG7JAW.mjs";
+import { n as reportErrors } from "./ui-C8VuPzGp.mjs";
+import { defineCommand } from "citty";
+import { cpSync, existsSync, mkdirSync, rmSync, symlinkSync, writeFileSync } from "node:fs";
+import { join, relative } from "node:path";
+import { fileURLToPath } from "node:url";
+//#region src/skill.ts
+/**
+* canopy skill install — write the Canopy agent skill into the current repo.
+*
+* To avoid vendor lock-in the skill lives in the tool-neutral `.agents/skills/`
+* tree, and `.claude/skills/canopy` is a symlink to it (so Claude Code picks it
+* up while other agents can read `.agents/`). The skill files are bundled with
+* the CLI (dist/skill in the published package, packages/cli/skill in dev), so
+* `canopy upgrade` re-runs this to keep the installed skill in sync.
+*/
+const SKILL_NAME = "canopy";
+const AGENTS_REL = join(".agents", "skills", SKILL_NAME);
+const CLAUDE_REL = join(".claude", "skills", SKILL_NAME);
+const STAMP = ".canopy-skill-version";
+/** The bundled skill source: dist/skill/canopy published, packages/cli/skill in dev. */
+function bundledSkillDir() {
+	const base = fileURLToPath(new URL(".", import.meta.url));
+	for (const candidate of [join(base, "skill", SKILL_NAME), join(base, "..", "skill", SKILL_NAME)]) if (existsSync(join(candidate, "SKILL.md"))) return candidate;
+	throw new Error("Skill files not found — the CLI build is incomplete (missing skill/).");
+}
+/** Point `.claude/skills/canopy` at the `.agents` copy; copy as a fallback. */
+function linkClaude(root) {
+	const linkPath = join(root, CLAUDE_REL);
+	const target = relative(join(root, ".claude", "skills"), join(root, AGENTS_REL));
+	mkdirSync(join(root, ".claude", "skills"), { recursive: true });
+	rmSync(linkPath, {
+		recursive: true,
+		force: true
+	});
+	try {
+		symlinkSync(target, linkPath, "dir");
+		return "symlink";
+	} catch {
+		cpSync(join(root, AGENTS_REL), linkPath, { recursive: true });
+		return "copy";
+	}
+}
+/** Install/refresh the skill under `root`. Returns the absolute `.agents` path. */
+function installSkill(root) {
+	const source = bundledSkillDir();
+	const agentsDir = join(root, AGENTS_REL);
+	rmSync(agentsDir, {
+		recursive: true,
+		force: true
+	});
+	mkdirSync(agentsDir, { recursive: true });
+	cpSync(source, agentsDir, { recursive: true });
+	writeFileSync(join(agentsDir, STAMP), `${version}\n`);
+	return {
+		agentsDir,
+		claudeMode: linkClaude(root)
+	};
+}
+/** Is a Canopy skill already installed under `root`? (Used by `canopy upgrade`.) */
+function skillInstalled(root) {
+	return existsSync(join(root, AGENTS_REL, "SKILL.md"));
+}
+const skillCommand = defineCommand({
+	meta: {
+		name: "skill",
+		description: "Manage the Canopy agent skill in this repo"
+	},
+	subCommands: { install: () => defineCommand({
+		meta: {
+			name: "install",
+			description: "Install/refresh the Canopy skill (.agents + .claude)"
+		},
+		run: reportErrors("skill install", async () => {
+			const { claudeMode } = installSkill(process.cwd());
+			console.log(`Installed the Canopy skill (v${version}):`);
+			console.log(`  .agents/skills/${SKILL_NAME}/   (source of truth)`);
+			console.log(claudeMode === "symlink" ? `  .claude/skills/${SKILL_NAME}    → symlink to .agents` : `  .claude/skills/${SKILL_NAME}    (copy — symlinks unavailable here)`);
+			console.log("\nYour agent can now use Canopy. Try: canopy docs");
+		})
+	}) }
+});
+//#endregion
+export { skillCommand, skillInstalled };

package/dist/{upgrade-TbMOjkLY.mjs → upgrade-Y8ejvoeg.mjs}

@@ -48,14 +48,14 @@ function installArgs(pm, spec) {
 		];
 	}
 }
-function run(pm, args) {
+function run(command, args) {
 	return new Promise((resolve, reject) => {
-		const child = spawn(pm, args, {
+		const child = spawn(command, args, {
 			stdio: "inherit",
 			shell: process.platform === "win32"
 		});
-		child.on("error", (err) => reject(err.code === "ENOENT" ? /* @__PURE__ */ new Error(`\`${pm}\` was not found on your PATH — install it or pass --pm.`) : err));
-		child.on("close", (code) => code === 0 ? resolve() : reject(/* @__PURE__ */ new Error(`${pm} exited with code ${code ?? "unknown"}.`)));
+		child.on("error", (err) => reject(err.code === "ENOENT" ? /* @__PURE__ */ new Error(`\`${command}\` was not found on your PATH.`) : err));
+		child.on("close", (code) => code === 0 ? resolve() : reject(/* @__PURE__ */ new Error(`${command} exited with code ${code ?? "unknown"}.`)));
 	});
 }
 const upgradeCommand = defineCommand({
@@ -86,6 +86,13 @@ const upgradeCommand = defineCommand({
 		console.log(`Upgrading via ${pm}: ${pm} ${cmd.join(" ")}`);
 		await run(pm, cmd);
 		console.log(`\nDone. Run \`canopy --version\` to confirm.`);
+		const { skillInstalled } = await import("./skill-jbmERP1X.mjs");
+		if (skillInstalled(process.cwd())) {
+			console.log("Refreshing the Canopy agent skill in this repo…");
+			await run("canopy", ["skill", "install"]).catch((err) => {
+				console.warn(`Could not auto-refresh the skill (${err instanceof Error ? err.message : String(err)}). Run \`canopy skill install\` yourself.`);
+			});
+		}
 	})
 });
 //#endregion

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mediamonks/canopy-cli",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Canopy CLI — create, develop and deploy Canopy projects.",
   "bin": {
     "canopy": "./dist/index.mjs"
@@ -19,8 +19,8 @@
     "hono": "^4.8.0",
     "miniflare": "^4.20260714.0",
     "vite": "npm:@voidzero-dev/vite-plus-core@0.2.5",
-    "@mediamonks/canopy": "0.0.1",
-    "@mediamonks/canopy-data-plane": "0.0.1"
+    "@mediamonks/canopy-data-plane": "0.0.1",
+    "@mediamonks/canopy": "0.0.1"
   },
   "devDependencies": {
     "@types/node": "^26.1.1",