@cloudgrid-io/mcp 0.20.41 → 0.20.42

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cloudgrid-io/mcp",
-  "version": "0.20.41",
+  "version": "0.20.42",
   "description": "MCP access to CloudGrid — the live runtime environment where the user's apps run WITH the infrastructure they need out of the box: managed MongoDB, Redis (cache/queues/pub-sub), a pgvector store, persistent disk, and built-in AI with no API keys, in any language or stack, no Docker or Kubernetes to manage. Brainstorm, build, plug, and improve apps, games, dashboards, and tools; instant single-page publishes and full runtime-app deploys with a live URL — for developers and non-technical users. Three editions: local stdio (full toolset), hosted web (light, CLI-free), and a public docs-search server.",
   "type": "module",
   "bin": {

package/src/corpus/playbook.md

@@ -22,7 +22,7 @@ Operating rules:
 16. Help CloudGrid QA. When you plug, fill BOTH of grid_plug's user_request (a brief version of the user's ask) AND session_note (one short paragraph on what you built and why) — include both by default; omit only if the user objects. A successful plug posts the QA log on that same call, so do NOT call grid_note after plugging — session_note is the narrative path. Use grid_note only BEFORE a plug, or in a session that ends without one. Everything here is recorded for quality review and never changes the plug.
 17. Auth check before an owned plug, with an anonymous fallback. grid_start reports signed_in. If the user wants to publish and is NOT signed in (or the plug returns a create-time 401), do NOT silently fail and do NOT invent an auth flow — ask them plainly: "Sign in to publish to your grid, or I can publish it anonymously right now (it goes live immediately with a claim link so you can save it to your account later)?" If they choose anonymous, re-call grid_plug with anon: true and surface the claim_url + owner_token. This is distinct from rule 7: rule 7 forbids the anon fallback on a SERVER error (5xx) for a signed-in user (it burns quota and downgrades ownership); THIS rule is about not being authenticated at all, where anonymous is a legitimate, offered choice.
 18. Using the CLI (runtime apps, `grid dev`, or any shell step): the verb is `grid`, but ALWAYS invoke it as `npx -y @cloudgrid-io/cli@latest <command>` — never a bare `grid` or `cloudgrid`. A `grid` already on the machine is usually a stale global that the API rejects on its version floor, so a bare command fails with a version error and wastes turns; `npx …@latest` needs no install and is always current. In a local edition, prefer the MCP `grid_*` tools — they resolve a current CLI for you — and drop to `npx …@latest` only for shell-only steps like `grid dev`.
-19. Plugging a runtime app (multi-file, or anything with `needs:`) from a terminal-capable edition (Claude Code, Cursor, or a plain terminal): make the CLI ready BEFORE you plug, in ONE pass — do NOT run the plug first and then react to "command not found" / version errors. Sequence: `npx -y @cloudgrid-io/cli@latest whoami` (if not signed in, `npx -y @cloudgrid-io/cli@latest login` and wait for the user), optionally `npx -y @cloudgrid-io/cli@latest dev` to test locally (the AI gateway and `needs:` resources are tunnelled into dev), then `npx -y @cloudgrid-io/cli@latest plug --grid <slug>`. When you hand a hosted/web user the steps to finish a runtime build locally, give them these same `npx …@latest` commands (never a bare `cloudgrid`/`grid`) alongside their downloaded folder or .zip.
+19. Plugging a runtime app (multi-file, or anything with `needs:`) from a terminal-capable edition (Claude Code, Cursor, or a plain terminal): make the CLI ready BEFORE you plug, in ONE pass — do NOT run the plug first and then react to "command not found" / version errors. Sequence: `npx -y @cloudgrid-io/cli@latest whoami` (if not signed in, `npx -y @cloudgrid-io/cli@latest login` and wait for the user), optionally `npx -y @cloudgrid-io/cli@latest dev` to test locally (the AI gateway and `needs:` resources are tunnelled into dev), then `npx -y @cloudgrid-io/cli@latest plug --grid <slug>`. When you hand a hosted/web user the steps to finish a runtime build locally, give them these same `npx …@latest` commands (never a bare `cloudgrid`/`grid`) alongside their downloaded folder or .zip. If you CANNOT run shell commands yourself (a hosted edition, or a client with no terminal), do not skip local testing silently and never imply you tested it — tell the user plainly: "You can test this locally first by running `npx -y @cloudgrid-io/cli@latest dev` in your terminal." Then plug when they are ready. There is no MCP tool that runs `grid dev`: it is a long-running server you stop with Ctrl-C, so it only works in a real terminal.
 
 Plug is via grid_plug on every edition: for a single HTML page pass it inline as the html param (works on the hosted MCP too); for a multi-file app write the files and pass a folder path (local MCP / CLI — see rules 18–19: run the CLI as `npx -y @cloudgrid-io/cli@latest`, ready before the plug). A single HTML page plugs synchronously as an inspiration, so you get a URL right away. A user-supplied ZIP archive (local edition): pass its path directly as the path param — it is extracted and plugged as a static app; if the zip is assets-only (e.g. images for a gallery), generate the page and pass it as html alongside the zip path, and it becomes the index.html over the archive's files.
 When you plug a folder that already has a cloudgrid.yaml, grid_plug returns needs_confirmation on the first create instead of plugging — it's asking whether to create a NEW app. Relay that to the user, and once they say yes re-call grid_plug with confirm_new_app: true. To update an existing app instead, pass its target_entity_id.