@cloudgrid-io/mcp 0.9.1 → 0.11.0

package/README.md

@@ -66,44 +66,44 @@ It speaks MCP over stdio. Point any MCP client at the `cloudgrid-mcp` command.
 | `gridctl_claim` | `POST /api/v2/entities/:id/pickup` | Claim an anonymous drop into the signed-in account (the claim token IS the drop's owner token). Direct API. |
 | `gridctl_fork` | `POST /api/v2/runtimes/:id/fork` | Start a new entity from an existing runtime (lineage recorded). Needs sign-in. |
 | `gridctl_download` | `GET /api/v2/runtimes/:id/source` | Signed 15-minute source-bundle URLs. Needs sign-in. |
-| `cloudgrid_login` | `GET /auth/login` | Start a CLI-free sign-in; returns a URL to open. Direct API. |
-| `cloudgrid_login_status` | `GET /auth/status` | Finish the sign-in; saves the token to the shared CLI credentials. |
-| `cloudgrid_visibility` | `PATCH /api/v2/inspirations/<id>` | Change who can see a drop (private, space, authenticated, org, link). Needs sign-in. Direct API; also in the web edition. |
+| `gridctl_login` | `GET /auth/login` | Start a CLI-free sign-in; returns a URL to open. Direct API. |
+| `gridctl_login_status` | `GET /auth/status` | Finish the sign-in; saves the token to the shared CLI credentials. |
+| `gridctl_visibility` | `PATCH /api/v2/inspirations/<id>` | Change who can see a drop (private, space, authenticated, org, link). Needs sign-in. Direct API; also in the web edition. |
 
-`cloudgrid_drop`, `cloudgrid_claim`, `cloudgrid_visibility`, and the two
-`cloudgrid_login` tools do not wrap the CLI -- they call the API directly, so they
-also work in the web edition where no CLI exists. `cloudgrid_login` writes the same
+`gridctl_drop`, `gridctl_claim`, `gridctl_visibility`, and the two
+`gridctl_login` tools do not wrap the CLI -- they call the API directly, so they
+also work in the web edition where no CLI exists. `gridctl_login` writes the same
 `~/.cloudgrid/credentials` the CLI uses, so the two share one identity.
 
 ### CLI-wrapping tools (local edition only)
 
 | Tool | Wraps | Notes |
 |---|---|---|
-| `cloudgrid_init` | `cloudgrid init` | Register an app or agent; optionally seed a web service. |
-| `cloudgrid_logs` | `cloudgrid logs` | Snapshot of recent logs. Does not stream. Read-only. |
-| `cloudgrid_share` | `cloudgrid visibility set` | Set visibility, default link. |
-| `cloudgrid_feedback` | `cloudgrid feedback list` | Read the org feedback feed. Read-only. |
-| `cloudgrid_whoami` | `cloudgrid whoami` | Show the signed-in user and active org. Read-only. |
-| `cloudgrid_use` | `cloudgrid use` | Switch the active org. |
-| `cloudgrid_logout` | `cloudgrid logout` | Sign out and clear local credentials. Destructive. |
-| `cloudgrid_status` | `cloudgrid status` | Org dashboard or entity detail. Read-only. |
-| `cloudgrid_info` | `cloudgrid info` | Entity metadata. Read-only. |
-| `cloudgrid_get` | `cloudgrid get grids\|entities\|spaces` | List grids, entities, or spaces. Read-only. |
-| `cloudgrid_describe_grid` | `cloudgrid describe grid <slug>` | Grid detail. Read-only. |
-| `cloudgrid_pickup` | `cloudgrid pickup <name>` | Download an entity's source and bind the folder. |
-| `cloudgrid_rename` | `cloudgrid rename` | Rename an entity's display name. |
-| `cloudgrid_unplug` | `cloudgrid unplug` | Take an entity off the grid. Destructive; requires confirm. |
-| `cloudgrid_delete` | `cloudgrid delete entity` | Archive an inspiration. Destructive; requires confirm. |
-| `cloudgrid_rollback` | `cloudgrid rollback` | Rollback to a previous version. |
-| `cloudgrid_versions` | `cloudgrid versions` | List published versions. Read-only. |
-| `cloudgrid_env` | `cloudgrid env` | Get, set, or list environment variables. |
-| `cloudgrid_secrets` | `cloudgrid secrets` | Set or list secret names. Never returns secret values. |
-| `cloudgrid_scaffold` | `cloudgrid scaffold` | Generate starter files. |
-| `cloudgrid_doctor` | `cloudgrid doctor` | Run local diagnostics. Read-only. |
-| `cloudgrid_open` | `cloudgrid open --print` | Return the public URL. Does not open a browser. Read-only. |
-
-`cloudgrid_share` and `cloudgrid_visibility` overlap on purpose: `cloudgrid_share`
-wraps the CLI and defaults to `link`; `cloudgrid_visibility` is direct API, takes an
+| `gridctl_init` | `cloudgrid init` | Register an app or agent; optionally seed a web service. |
+| `gridctl_logs` | `cloudgrid logs` | Snapshot of recent logs. Does not stream. Read-only. |
+| `gridctl_share` | `cloudgrid visibility set` | Set visibility, default link. |
+| `gridctl_feedback` | `cloudgrid feedback list` | Read the org feedback feed. Read-only. |
+| `gridctl_whoami` | `cloudgrid whoami` | Show the signed-in user and active org. Read-only. |
+| `gridctl_use` | `cloudgrid use` | Switch the active org. |
+| `gridctl_logout` | `cloudgrid logout` | Sign out and clear local credentials. Destructive. |
+| `gridctl_status` | `cloudgrid status` | Org dashboard or entity detail. Read-only. |
+| `gridctl_info` | `cloudgrid info` | Entity metadata. Read-only. |
+| `gridctl_get` | `cloudgrid get grids\|entities\|spaces` | List grids, entities, or spaces. Read-only. |
+| `gridctl_describe_grid` | `cloudgrid describe grid <slug>` | Grid detail. Read-only. |
+| `gridctl_pickup` | `cloudgrid pickup <name>` | Download an entity's source and bind the folder. |
+| `gridctl_rename` | `cloudgrid rename` | Rename an entity's display name. |
+| `gridctl_unplug` | `cloudgrid unplug` | Take an entity off the grid. Destructive; requires confirm. |
+| `gridctl_delete` | `cloudgrid delete entity` | Archive an inspiration. Destructive; requires confirm. |
+| `gridctl_rollback` | `cloudgrid rollback` | Rollback to a previous version. |
+| `gridctl_versions` | `cloudgrid versions` | List published versions. Read-only. |
+| `gridctl_env` | `cloudgrid env` | Get, set, or list environment variables. |
+| `gridctl_secrets` | `cloudgrid secrets` | Set or list secret names. Never returns secret values. |
+| `gridctl_scaffold` | `cloudgrid scaffold` | Generate starter files. |
+| `gridctl_doctor` | `cloudgrid doctor` | Run local diagnostics. Read-only. |
+| `gridctl_open` | `cloudgrid open --print` | Return the public URL. Does not open a browser. Read-only. |
+
+`gridctl_share` and `gridctl_visibility` overlap on purpose: `gridctl_share`
+wraps the CLI and defaults to `link`; `gridctl_visibility` is direct API, takes an
 explicit scope, and defaults its target to the session's last drop -- it is the one
 the web edition gets.
 
@@ -113,7 +113,7 @@ All tools carry MCP annotations (`readOnlyHint`, `destructiveHint`,
 ## Test
 
 A smoke test spawns the server with a real MCP client, lists the tools, and calls
-the read-only `cloudgrid_feedback` tool end to end:
+the read-only `gridctl_feedback` tool end to end:
 
 ```
 cd mcp-server
@@ -127,5 +127,5 @@ It needs a logged-in CLI on `$PATH`.
 
 - Shells out with `execFile` and an argument array, so there is no shell and no
   injection surface.
-- `cloudgrid_logs` never uses `--follow`; a streaming call would never return.
+- `gridctl_logs` never uses `--follow`; a streaming call would never return.
 - Stateless. Each call is one CLI invocation.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cloudgrid-io/mcp",
-  "version": "0.9.1",
+  "version": "0.11.0",
   "description": "MCP server for CloudGrid. Three editions: a local stdio server (full toolset), a hosted web server (light, CLI-free toolset), and a public docs server (search_cloudgrid_documentation) over MCP Streamable HTTP.",
   "type": "module",
   "bin": {
@@ -20,6 +20,7 @@
     "test:error-reporting": "node test/error-reporting.test.mjs",
     "test:source": "node test/source-fetch.test.mjs",
     "test:app-with-data": "node test/app-with-data.test.mjs",
+    "test:self-describing": "node test/self-describing.test.mjs",
     "test:content": "node test/content-handling.test.mjs",
     "test:self-healing": "node test/self-healing.test.mjs",
     "test:grid-picker": "node test/grid-picker.test.mjs",

package/src/corpus/capability-map.md

@@ -0,0 +1,69 @@
+# Capability map — intent → template → capabilities → deploy
+
+This is the index an LLM uses to turn a user request into the right CloudGrid
+template, the way Superpowers matches a skill's `when:`. Match the request to a
+template by its `when:` triggers, adopt that template's `needs:`, then deploy:
+
+- **static → inspiration** (instant, any client / any edition) via `gridctl_drop`.
+- **anything needing `needs:` → runtime** (async build, **local edition** only)
+  via `gridctl_plug` on a linked folder.
+
+Fetch this doc any time with `gridctl_fetch("doc", "capability-map")`.
+
+## The 6 templates
+
+| Intent (match on `when:`) | Template | `needs:` | Deploy | Edition |
+|---|---|---|---|---|
+| landing page, marketing/product/hero page, coming-soon, waitlist, pricing, portfolio, link-in-bio, event page | `landing-page` | none | inspiration (instant) | all |
+| calculator, converter, generator, timer, quiz, interactive tool, mini-app, widget — computed client-side, no saved data | `web-app` | none | inspiration (instant) | all |
+| dashboard, metrics, KPIs, stats page, status board, charts, analytics view — display-only, static data baked in | `dashboard` | none | inspiration (instant) | all |
+| report, one-pager, summary, brief, whitepaper, case study, formatted document | `report` | none | inspiration (instant) | all |
+| slides, deck, pitch, presentation, slideshow | `presentation` (dir: `deck`) | none | inspiration (instant) | all |
+| to-do, task list, notes app, guestbook, CRUD app, a form that SAVES/STORES submissions, anything that PERSISTS data or shares state across users/sessions, sign-in/accounts | `app-with-data` | `database: true` | runtime (async, poll) | local |
+
+**Rule of thumb:** if the app must SAVE/remember data, share state across
+users/sessions, log in, or store submissions → it is persistent → `app-with-data`
+(runtime, local edition). Otherwise a static template deploys instantly anywhere.
+
+## The full `needs:` vocabulary (the whole menu)
+
+`needs:` is a MAP declaring infrastructure capabilities. Values are `true` or an
+engine hint. Cron is NOT a need — it is a **service type** (`type: cron` with
+`schedule` + `timezone`). See the cloudgrid.yaml reference §5, §12, §14.
+
+| `needs:` key | Provides | Injected env var(s) | Status |
+|---|---|---|---|
+| `database: true` | MongoDB primary datastore | `DATABASE_MONGODB_URL` (+legacy `MONGODB_URL`) | **Today via `requires: [mongodb]`** — `needs:` pending #1527 |
+| `cache: true` | Redis, LRU eviction | `CACHE_REDIS_URL` (+legacy `REDIS_URL`) | **Today via `requires: [redis]`** — `needs:` pending #1527 |
+| `kv: true` | Redis, no eviction | `KV_REDIS_URL` | Pending #1527 |
+| `queue: true` | Redis durable job queue | `QUEUE_REDIS_URL` | Pending #1527 |
+| `pubsub: true` | Redis pub/sub broadcast | `PUBSUB_REDIS_URL` | Pending #1527 |
+| `vector: pgvector` | pgvector embeddings DB | `VECTOR_PGVECTOR_URL` (+legacy `PGVECTOR_URL`) | Pending #1527 |
+| `object_storage: true` | GCS bucket | `OBJECT_STORAGE_GCS_BUCKET`, `OBJECT_STORAGE_GCS_REGION` | Pending #1527 |
+| `disk: true` | Persistent filesystem at `/data` | `DISK_PATH` | Pending #1527 |
+| `ai: true` | AI Gateway access | `AI_GATEWAY_URL` | **Today** (AI Gateway) |
+| `type: cron` (service) | Scheduled job (`schedule`, `timezone`) | — | Service type, not a need |
+
+### Injection status — today vs pending #1527
+
+- **Injects TODAY:** `database` and `cache` — but ONLY via the deprecated
+  `requires:` field (`requires: [mongodb]` → `MONGODB_URL`; `requires: [redis]`
+  → `REDIS_URL`). `needs:`-based provisioning does NOT inject anything on the
+  live deployer yet (bug #1527). `ai` (AI Gateway) is available today.
+- **Pending #1527:** `needs:`-based provisioning for everything — `vector`,
+  `queue`, `pubsub`, `kv`, `object_storage`, `disk`, and `needs: database` /
+  `needs: cache` once the deployer honors `needs:`.
+- **`needs:` and `requires:` cannot both be active** in one yaml — the validator
+  rejects the combination ("use one or the other"). So a DB template ships
+  `requires: [mongodb]` active with the canonical `needs: { database: true }`
+  shown only as a **comment** (and declared in the workflow frontmatter as
+  metadata), flipping to `needs:` when #1527 lands.
+
+## How to choose
+
+1. Read the request; match it against the workflow `when:` triggers above.
+2. Adopt that template's `needs:`. Persistence → `database`. (Future: scheduled →
+   `cron` service; semantic search / RAG → `vector` + `ai`.)
+3. Static (`needs: none`) → publish as an inspiration with `gridctl_drop`
+   (instant, any edition). Anything with a `needs:` → runtime, local edition,
+   `gridctl_plug` a linked folder, then poll to a live URL.

package/src/corpus/cookbook.md

@@ -74,7 +74,7 @@ curl -sS -X POST https://api.cloudgrid.io/api/v2/plug \
 The response includes `url` (the live link — use it verbatim), `entity_id`,
 `owner_token` (keep both to update the drop later), and `claim_url` (sign in
 before it expires to keep it). This is what the `cloudgrid-drop` skill and the
-`cloudgrid_drop` MCP tool do for you. It is anonymous and serves inspirations
+`gridctl_drop` MCP tool do for you. It is anonymous and serves inspirations
 only; a full app needs the signed-in `plug` flow above.
 
 ## Update your drop in place

package/src/corpus/install.md

@@ -113,7 +113,7 @@ https://github.com/cloudgrid-io/mcp/releases/latest/download/cloudgrid.mcpb
 
 The bundle carries the full local toolset (including the `cloudgrid` CLI), so deploy
 and secrets tools work without a separate install. Sign in from chat with the
-`cloudgrid_login` tool on first use.
+`gridctl_login` tool on first use.
 
 ## For agents
 

package/src/corpus/skill-claim.md

@@ -69,5 +69,5 @@ new_expires_at, role_granted: "owner", ... }`.
 ## Notes
 
 - One pickup claims one entity. To claim several, repeat with each entity id + token.
-- The MCP `cloudgrid_claim` tool does this for you, and remembers the entity id +
+- The MCP `gridctl_claim` tool does this for you, and remembers the entity id +
   token from the last anonymous drop so you can claim with no arguments.

package/src/corpus/skill-drop.md

@@ -78,7 +78,7 @@ A signed-in drop returns HTTP 202 with `entity_id`, `url`, `slug` + `grid` and n
 not compose it. The org is taken from the `X-CloudGrid-Org` header — there is no
 `org_slug` form field. If the user is a member of several orgs and the header is
 missing, the API replies with the list of orgs to choose from. The MCP
-`cloudgrid_drop` tool does this automatically when credentials are present.
+`gridctl_drop` tool does this automatically when credentials are present.
 
 ## Re-plug: update the same URL in place
 
@@ -120,7 +120,7 @@ Rules that matter:
 - An anonymous edit without a valid `owner_token` returns **401**.
 - Anonymous edits count against the same daily anonymous cap as creates.
 - Only re-plug when the user is iterating on an existing artifact. If they want a
-  separate new link, omit `target_entity_id` (the MCP `cloudgrid_drop` tool's
+  separate new link, omit `target_entity_id` (the MCP `gridctl_drop` tool's
   `fresh` flag does the same: it forces a new entity instead of updating).
 
 ## After the drop

package/src/corpus/skill-login.md

@@ -81,6 +81,6 @@ made an anonymous drop earlier, this is the moment to offer to claim it.
 
 - Enterprise single sign-on is not supported in this flow yet; those users sign in
   through the Console for now.
-- The MCP server exposes the same flow as `cloudgrid_login` and
-  `cloudgrid_login_status`, which handle the polling and the credentials write for
+- The MCP server exposes the same flow as `gridctl_login` and
+  `gridctl_login_status`, which handle the polling and the credentials write for
   you.

package/src/corpus/templates/app-with-data/cloudgrid.yaml

@@ -11,5 +11,9 @@ services:
   web:
     type: nextjs
     path: /
+# Canonical capability (metadata): this app needs a database.
+# When #1527 lands (deployer honors needs:), replace requires: with:
+#   needs:
+#     database: true
 requires:
   - mongodb

package/src/corpus/templates/app-with-data/index.md

@@ -53,10 +53,20 @@ services:
   web:
     type: nextjs
     path: /
+# Canonical capability (metadata): this app needs a database.
+# When #1527 lands (deployer honors needs:), replace requires: with:
+#   needs:
+#     database: true
 requires:
   - mongodb
 ```
 
+> **Capability:** this template's canonical need is `database: true` (see the
+> commented block above and the capability-map). The deployed yaml keeps
+> `requires: [mongodb]` because only `requires:` injects `MONGODB_URL` today
+> (#1527); `needs:` and `requires:` cannot co-exist active in the same yaml, so
+> the canonical `needs:` is shown only as a comment until the deployer honors it.
+
 ## services/web/package.json
 
 ```json

package/src/corpus/templates/dashboard/cloudgrid.yaml

@@ -0,0 +1,10 @@
+# static — deploys as an inspiration (instant, works on hosted) via gridctl_drop;
+# this yaml is only for plugging it as an OWNED static runtime (async, local
+# edition only). To publish the page, prefer gridctl_drop, not grid plug.
+#
+# needs: {}  # none — static, no infrastructure
+name: dashboard
+services:
+  web:
+    type: static
+    path: /

package/src/corpus/templates/dashboard/index.md

@@ -0,0 +1,30 @@
+# Template: dashboard (static)
+
+A single self-contained HTML dashboard. **No infrastructure** — no database, no backend,
+no `needs:`. State (if any) lives only in memory and is lost on refresh.
+
+## How it deploys
+
+To publish this page, use **`gridctl_drop`** (or `gridctl_plug` with the inline
+HTML): it deploys as an **inspiration** — instant, and works on the **hosted**
+edition (Claude Web) as well as local. The reference `cloudgrid.yaml` in this
+directory (`type: static`) is ONLY for plugging the page as an OWNED static
+runtime (async, local edition only); the fast path is `gridctl_drop`.
+
+The fillable HTML is the real template — fetch it with
+`gridctl_fetch("template", "dashboard")` and fill in the user's content.
+
+## cloudgrid.yaml (reference only)
+
+```yaml
+# static — deploys as an inspiration (instant, works on hosted) via gridctl_drop;
+# this yaml is only for plugging it as an OWNED static runtime (async, local
+# edition only). To publish the page, prefer gridctl_drop, not grid plug.
+#
+# needs: {}  # none — static, no infrastructure
+name: dashboard
+services:
+  web:
+    type: static
+    path: /
+```

package/src/corpus/templates/deck/cloudgrid.yaml

@@ -0,0 +1,10 @@
+# static — deploys as an inspiration (instant, works on hosted) via gridctl_drop;
+# this yaml is only for plugging it as an OWNED static runtime (async, local
+# edition only). To publish the page, prefer gridctl_drop, not grid plug.
+#
+# needs: {}  # none — static, no infrastructure
+name: deck
+services:
+  web:
+    type: static
+    path: /

package/src/corpus/templates/deck/index.md

@@ -0,0 +1,30 @@
+# Template: deck (static)
+
+A single self-contained HTML deck. **No infrastructure** — no database, no backend,
+no `needs:`. State (if any) lives only in memory and is lost on refresh.
+
+## How it deploys
+
+To publish this page, use **`gridctl_drop`** (or `gridctl_plug` with the inline
+HTML): it deploys as an **inspiration** — instant, and works on the **hosted**
+edition (Claude Web) as well as local. The reference `cloudgrid.yaml` in this
+directory (`type: static`) is ONLY for plugging the page as an OWNED static
+runtime (async, local edition only); the fast path is `gridctl_drop`.
+
+The fillable HTML is the real template — fetch it with
+`gridctl_fetch("template", "deck")` and fill in the user's content.
+
+## cloudgrid.yaml (reference only)
+
+```yaml
+# static — deploys as an inspiration (instant, works on hosted) via gridctl_drop;
+# this yaml is only for plugging it as an OWNED static runtime (async, local
+# edition only). To publish the page, prefer gridctl_drop, not grid plug.
+#
+# needs: {}  # none — static, no infrastructure
+name: deck
+services:
+  web:
+    type: static
+    path: /
+```

package/src/corpus/templates/landing-page/cloudgrid.yaml

@@ -0,0 +1,10 @@
+# static — deploys as an inspiration (instant, works on hosted) via gridctl_drop;
+# this yaml is only for plugging it as an OWNED static runtime (async, local
+# edition only). To publish the page, prefer gridctl_drop, not grid plug.
+#
+# needs: {}  # none — static, no infrastructure
+name: landing-page
+services:
+  web:
+    type: static
+    path: /

package/src/corpus/templates/landing-page/index.md

@@ -0,0 +1,30 @@
+# Template: landing-page (static)
+
+A single self-contained HTML landing-page. **No infrastructure** — no database, no backend,
+no `needs:`. State (if any) lives only in memory and is lost on refresh.
+
+## How it deploys
+
+To publish this page, use **`gridctl_drop`** (or `gridctl_plug` with the inline
+HTML): it deploys as an **inspiration** — instant, and works on the **hosted**
+edition (Claude Web) as well as local. The reference `cloudgrid.yaml` in this
+directory (`type: static`) is ONLY for plugging the page as an OWNED static
+runtime (async, local edition only); the fast path is `gridctl_drop`.
+
+The fillable HTML is the real template — fetch it with
+`gridctl_fetch("template", "landing-page")` and fill in the user's content.
+
+## cloudgrid.yaml (reference only)
+
+```yaml
+# static — deploys as an inspiration (instant, works on hosted) via gridctl_drop;
+# this yaml is only for plugging it as an OWNED static runtime (async, local
+# edition only). To publish the page, prefer gridctl_drop, not grid plug.
+#
+# needs: {}  # none — static, no infrastructure
+name: landing-page
+services:
+  web:
+    type: static
+    path: /
+```

package/src/corpus/templates/report/cloudgrid.yaml

@@ -0,0 +1,10 @@
+# static — deploys as an inspiration (instant, works on hosted) via gridctl_drop;
+# this yaml is only for plugging it as an OWNED static runtime (async, local
+# edition only). To publish the page, prefer gridctl_drop, not grid plug.
+#
+# needs: {}  # none — static, no infrastructure
+name: report
+services:
+  web:
+    type: static
+    path: /

package/src/corpus/templates/report/index.md

@@ -0,0 +1,30 @@
+# Template: report (static)
+
+A single self-contained HTML report. **No infrastructure** — no database, no backend,
+no `needs:`. State (if any) lives only in memory and is lost on refresh.
+
+## How it deploys
+
+To publish this page, use **`gridctl_drop`** (or `gridctl_plug` with the inline
+HTML): it deploys as an **inspiration** — instant, and works on the **hosted**
+edition (Claude Web) as well as local. The reference `cloudgrid.yaml` in this
+directory (`type: static`) is ONLY for plugging the page as an OWNED static
+runtime (async, local edition only); the fast path is `gridctl_drop`.
+
+The fillable HTML is the real template — fetch it with
+`gridctl_fetch("template", "report")` and fill in the user's content.
+
+## cloudgrid.yaml (reference only)
+
+```yaml
+# static — deploys as an inspiration (instant, works on hosted) via gridctl_drop;
+# this yaml is only for plugging it as an OWNED static runtime (async, local
+# edition only). To publish the page, prefer gridctl_drop, not grid plug.
+#
+# needs: {}  # none — static, no infrastructure
+name: report
+services:
+  web:
+    type: static
+    path: /
+```

package/src/corpus/templates/web-app/cloudgrid.yaml

@@ -0,0 +1,10 @@
+# static — deploys as an inspiration (instant, works on hosted) via gridctl_drop;
+# this yaml is only for plugging it as an OWNED static runtime (async, local
+# edition only). To publish the page, prefer gridctl_drop, not grid plug.
+#
+# needs: {}  # none — static, no infrastructure
+name: web-app
+services:
+  web:
+    type: static
+    path: /

package/src/corpus/templates/web-app/index.md

@@ -0,0 +1,30 @@
+# Template: web-app (static)
+
+A single self-contained HTML web-app. **No infrastructure** — no database, no backend,
+no `needs:`. State (if any) lives only in memory and is lost on refresh.
+
+## How it deploys
+
+To publish this page, use **`gridctl_drop`** (or `gridctl_plug` with the inline
+HTML): it deploys as an **inspiration** — instant, and works on the **hosted**
+edition (Claude Web) as well as local. The reference `cloudgrid.yaml` in this
+directory (`type: static`) is ONLY for plugging the page as an OWNED static
+runtime (async, local edition only); the fast path is `gridctl_drop`.
+
+The fillable HTML is the real template — fetch it with
+`gridctl_fetch("template", "web-app")` and fill in the user's content.
+
+## cloudgrid.yaml (reference only)
+
+```yaml
+# static — deploys as an inspiration (instant, works on hosted) via gridctl_drop;
+# this yaml is only for plugging it as an OWNED static runtime (async, local
+# edition only). To publish the page, prefer gridctl_drop, not grid plug.
+#
+# needs: {}  # none — static, no infrastructure
+name: web-app
+services:
+  web:
+    type: static
+    path: /
+```

package/src/corpus/usage.md

@@ -16,7 +16,7 @@ Which one you use depends on the client. Pick your client below.
 - **Node 18+** (for `npx`).
 - **No login needed to try it** — anonymous drop works out of the box. For owned
   drops (into your org), run `cloudgrid login` once, or use the `login` skill / the
-  `cloudgrid_login` MCP tool.
+  `gridctl_login` MCP tool.
 
 ---
 
@@ -45,7 +45,7 @@ npx skills add cloudgrid-io/skills
 ```
 claude mcp add cloudgrid -- npx -y @cloudgrid-io/mcp
 ```
-- **Find it under `/mcp`.** Exposes tools `cloudgrid_drop`, `cloudgrid_login`, …
+- **Find it under `/mcp`.** Exposes tools `gridctl_drop`, `gridctl_login`, …
 - Invoke by describing the task; the model calls the tool.
 
 > Where did my install go? `/skills` (skills), `/plugin` (plugin), `/mcp` (MCP).

package/src/corpus/workflows/app-with-data.md

@@ -1,6 +1,10 @@
 ---
 name: app-with-data
-when: The user wants an app that SAVES or PERSISTS data, shares state across users/sessions, has accounts/login, stores submissions, or needs a backend/API/database — e.g. a to-do list, a CRUD dashboard, a form that stores entries, a guestbook.
+when: to-do, task list, notes app, guestbook, CRUD app, form that SAVES/STORES submissions, anything that SAVES or PERSISTS data or shares state across users/sessions, sign-in/accounts, a backend/API/database — e.g. a to-do list, a CRUD dashboard, a form that stores entries, a guestbook. Needs a database → runtime → local edition.
+needs: database
+deploy: runtime
+editions: local
+capabilities_note: persistent — needs a database (Mongo). Runtime app, async build, local edition only. Canonical need is `database: true` (metadata); the deployed yaml uses `requires: [mongodb]` until #1527 lands.
 summary: Build a real persistent Next.js + Mongo runtime app on the grid — edition-gate first, scaffold, put the app under services/web/, wire process.env.MONGODB_URL lazily, declare requires:[mongodb] (not needs:), deploy async, poll to a live URL.
 ---
 

package/src/corpus/workflows/dashboard.md

@@ -1,6 +1,10 @@
 ---
 name: dashboard
-when: The user wants to build a dashboard showing metrics, status, or KPIs with cards and charts.
+when: dashboard, metrics, KPIs, stats page, status board, charts, analytics view — display-only (static data baked in).
+needs: none
+deploy: inspiration
+editions: all
+capabilities_note: static — no infrastructure, data is baked into the page. Publishes as an inspiration (instant, works on hosted) via gridctl_drop.
 summary: Fetch the dashboard template, fill it with the user's metrics and inline charts, deploy it, and return the live share URL.
 ---
 

package/src/corpus/workflows/landing-page.md

@@ -1,6 +1,10 @@
 ---
 name: landing-page
-when: The user wants to build a landing page, marketing page, or product page for something.
+when: landing page, marketing page, product page, hero page, coming-soon, waitlist, pricing page, portfolio, link-in-bio, event page.
+needs: none
+deploy: inspiration
+editions: all
+capabilities_note: static — no infrastructure. Publishes as an inspiration (instant, works on hosted) via gridctl_drop.
 summary: Fetch the landing-page template, fill it with the user's content, deploy it, and return the live share URL.
 ---
 

package/src/corpus/workflows/presentation.md

@@ -1,6 +1,10 @@
 ---
 name: presentation
-when: The user wants to build a presentation, slide deck, or set of slides about a topic.
+when: slides, deck, pitch, presentation, slideshow.
+needs: none
+deploy: inspiration
+editions: all
+capabilities_note: static — no infrastructure. Publishes as an inspiration (instant, works on hosted) via gridctl_drop.
 summary: Fetch the deck template, fill it with the user's content, deploy it, and return the live share URL.
 ---
 

package/src/corpus/workflows/report.md

@@ -1,6 +1,10 @@
 ---
 name: report
-when: The user wants to build a report, one-pager, brief, or write-up with sections and data.
+when: report, one-pager, summary, brief, whitepaper, case study, formatted document.
+needs: none
+deploy: inspiration
+editions: all
+capabilities_note: static — no infrastructure. Publishes as an inspiration (instant, works on hosted) via gridctl_drop.
 summary: Fetch the report template, fill it with the user's content, deploy it, and return the live share URL.
 ---
 

package/src/corpus/workflows/web-app.md

@@ -1,6 +1,10 @@
 ---
 name: web-app
-when: The user wants to build a small interactive web app, tool, calculator, or mini single-page application.
+when: calculator, converter, generator, timer, quiz, interactive tool, mini-app, single-page tool, widget — anything computed client-side with no saved data.
+needs: none
+deploy: inspiration
+editions: all
+capabilities_note: static — no infrastructure, state lives only in memory. Publishes as an inspiration (instant, works on hosted) via gridctl_drop.
 summary: Fetch the web-app template, adapt its markup and inline JS to the user's tool, deploy it, and return the live share URL.
 ---
 

package/src/tools.js

@@ -89,6 +89,7 @@ Operating rules:
 9. To modify an existing drop when you don't already have its HTML in context, first call gridctl_source to fetch the current HTML, apply your change, then call gridctl_drop/gridctl_plug with target_entity_id (the drop's entity_id) to update the SAME URL in place. Do not ask the user to paste the HTML back.
 10. Publishing a heavy or local file: in the local edition use the path parameter so it is read from disk (no inline size limit); never base64-encode HTML and never pass a file path (or an @-prefixed path) as html. If a drop looks empty, use gridctl_source to check what was actually published, then re-plug with the real HTML/path and target_entity_id.
 11. Persistence check: if the user needs to SAVE data, share state across users/sessions, log in, or store submissions, that's a runtime app-with-data (Mongo-backed), NOT a static page — static templates keep state only in memory and lose it on refresh. Use the app-with-data workflow. This requires the LOCAL edition (Claude Desktop/Code or the CLI); on the hosted edition, tell the user persistence isn't available there and offer a static version.
+12. To choose what to build: match the request against the workflow when: triggers and the capability-map (gridctl_fetch({kind:"doc", name:"capability-map"})). Pick the template whose needs: matches what the app requires (persistence → database; scheduled → cron; etc.). Static (needs: none) deploys as an inspiration (instant, any edition); anything needing needs: is a runtime (async, local edition).
 
 Deploy is edition-dependent: on the hosted MCP call the drop tool with the HTML; on local MCP / CLI write the file and run the plug tool. An HTML page deploys synchronously, so you get a URL right away.`;
 
@@ -226,30 +227,30 @@ const MIN_CLI_VERSION = "0.12.0";
 // Verb map for the drift guard: each CLI-wrapping tool's top-level verb(s).
 // The drift-guard test imports this and asserts every verb exists in `cloudgrid --help`.
 export const CLI_TOOL_VERBS = {
-  cloudgrid_init:     ["init"],
-  // cloudgrid_plug is NOT here: gridctl_plug is now a direct-API tool
+  gridctl_init:     ["init"],
+  // gridctl_plug is NOT here: gridctl_plug is now a direct-API tool
   // (POST /api/v2/plug, spec v2 §3), not a CLI wrapper.
-  cloudgrid_logs:     ["logs"],
-  cloudgrid_share:    ["visibility"],
-  cloudgrid_feedback: ["feedback"],
-  cloudgrid_whoami:   ["whoami"],
-  cloudgrid_use:      ["use"],
-  cloudgrid_logout:   ["logout"],
-  cloudgrid_status:   ["status"],
-  cloudgrid_info:     ["info"],
-  cloudgrid_get:          ["get"],
-  cloudgrid_describe_grid: ["describe"],
-  cloudgrid_pickup:        ["pickup"],
-  cloudgrid_rename:   ["rename"],
-  cloudgrid_unplug:   ["unplug"],
-  cloudgrid_delete:   ["delete"],
-  cloudgrid_rollback: ["rollback"],
-  cloudgrid_versions: ["versions"],
-  cloudgrid_env:      ["env"],
-  cloudgrid_secrets:  ["secrets"],
-  cloudgrid_scaffold: ["scaffold"],
-  cloudgrid_doctor:   ["doctor"],
-  cloudgrid_open:     ["open"],
+  gridctl_logs:     ["logs"],
+  gridctl_share:    ["visibility"],
+  gridctl_feedback: ["feedback"],
+  gridctl_whoami:   ["whoami"],
+  gridctl_use:      ["use"],
+  gridctl_logout:   ["logout"],
+  gridctl_status:   ["status"],
+  gridctl_info:     ["info"],
+  gridctl_get:          ["get"],
+  gridctl_describe_grid: ["describe"],
+  gridctl_pickup:        ["pickup"],
+  gridctl_rename:   ["rename"],
+  gridctl_unplug:   ["unplug"],
+  gridctl_delete:   ["delete"],
+  gridctl_rollback: ["rollback"],
+  gridctl_versions: ["versions"],
+  gridctl_env:      ["env"],
+  gridctl_secrets:  ["secrets"],
+  gridctl_scaffold: ["scaffold"],
+  gridctl_doctor:   ["doctor"],
+  gridctl_open:     ["open"],
 };
 
 // Simple semver comparison: true when `version` >= MIN_CLI_VERSION.
@@ -2356,34 +2357,19 @@ export async function runSource(ctx, { entity_id, url, grid, slug } = {}) {
 // Registers the tools onto `server`. ctx.edition decides whether the CLI-wrapping
 // tools are included (they need a local machine).
 export function registerTools(server, ctx) {
-  // ── Tool naming: gridctl_* with deprecated cloudgrid_* aliases ────────────
-  // Every tool is registered under its new `gridctl_*` name AND its legacy
-  // `cloudgrid_*` alias (same handler), so nothing breaks mid-migration. The
-  // alias is marked deprecated in its description; both names resolve to the
-  // same handler. Aliases are removed in a later major. `reg` wraps the
+  // ── Tool naming: gridctl_* only ───────────────────────────────────────────
+  // Every tool is registered under its `gridctl_*` name only. The legacy
+  // deprecated `cloudgrid_*` aliases were removed in 0.10.0 — they doubled the
+  // connector tool list and de-duplicated poorly in permission UIs. Clients
+  // enumerate tools dynamically, so discovery is unaffected. `reg` wraps the
   // object-config `server.registerTool`; `regTool` wraps the positional
-  // `server.tool` shorthand. Both take the new gridctl_* name and derive the
-  // alias by swapping the prefix.
-  const aliasOf = (name) => name.replace(/^gridctl_/, "cloudgrid_");
-
+  // `server.tool` shorthand.
   const reg = (name, config, handler) => {
     server.registerTool(name, config, handler);
-    const alias = aliasOf(name);
-    if (alias !== name) {
-      server.registerTool(
-        alias,
-        { ...config, description: `(deprecated: use ${name}) ${config.description}` },
-        handler,
-      );
-    }
   };
 
   const regTool = (name, description, schema, annotations, handler) => {
     server.tool(name, description, schema, annotations, handler);
-    const alias = aliasOf(name);
-    if (alias !== name) {
-      server.tool(alias, `(deprecated: use ${name}) ${description}`, schema, annotations, handler);
-    }
   };
 
   // ── Widget resources (web edition, ChatGPT Apps SDK) ──────────────────────

package/src/widgets/live-result.html

@@ -124,7 +124,7 @@ body{font-family:-apple-system,BlinkMacSystemFont,"Segoe UI",Roboto,sans-serif;b
           var statusEl = document.getElementById("vis-status");
           if (statusEl) statusEl.textContent = "Updating\u2026";
           if (!window.openai || !window.openai.callTool) return;
-          window.openai.callTool("cloudgrid_visibility", { visibility: vis }).then(function (res) {
+          window.openai.callTool("gridctl_visibility", { visibility: vis }).then(function (res) {
             var newVis = res && res.structuredContent && res.structuredContent.visibility;
             if (newVis) {
               data.current_visibility = newVis;

package/src/widgets/org-picker.html

@@ -75,7 +75,7 @@ body{font-family:-apple-system,BlinkMacSystemFont,"Segoe UI",Roboto,sans-serif;b
           if (input.fresh !== undefined) args.fresh = input.fresh;
           args.grid = slug;
           args.org = slug; // alias kept for compatibility
-          window.openai.callTool("cloudgrid_drop", args).then(function () {
+          window.openai.callTool("gridctl_drop", args).then(function () {
             // The host will render the new result with the live-result card.
           }).catch(function () {
             for (var m = 0; m < all.length; m++) all[m].classList.remove("loading");