@cloudgrid-io/mcp 0.6.1 → 0.7.0

package/README.md

@@ -54,8 +54,11 @@ It speaks MCP over stdio. Point any MCP client at the `cloudgrid-mcp` command.
 
 | Tool | Wraps | Notes |
 |---|---|---|
-| `cloudgrid_drop` | `POST /api/v2/drop/auto` | Artifact drop. Anonymous, or owned if signed in. Direct API. |
-| `cloudgrid_claim` | `POST /api/v2/anon-claim` | Claim an anonymous drop into the signed-in account. Direct API. |
+| `gridctl_plug` | `POST /api/v2/plug` | The unified create/re-plug verb: create a new entity, or update the SAME entity in place with `target_entity_id` (same URL). Source via local `path` (local edition) or inline `artifact_files` (both). |
+| `gridctl_drop` | `POST /api/v2/plug` | Artifact drop. Anonymous, or owned if signed in. Re-drops in a session update the same drop in place; anonymous drops return an `entity_id` + `owner_token` re-plug/claim handle. |
+| `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. |
@@ -70,7 +73,6 @@ also work in the web edition where no CLI exists. `cloudgrid_login` writes the s
 | Tool | Wraps | Notes |
 |---|---|---|
 | `cloudgrid_init` | `cloudgrid init` | Register an app or agent; optionally seed a web service. |
-| `cloudgrid_plug` | `cloudgrid plug` | Deploy a directory or URL. |
 | `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. |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cloudgrid-io/mcp",
-  "version": "0.6.1",
+  "version": "0.7.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": {
@@ -16,6 +16,7 @@
     "start": "node src/index.js",
     "start:web": "node src/web.js",
     "smoke": "node test/smoke.mjs",
+    "test:plug-wire": "node test/plug-wire.test.mjs",
     "test:drift-guard": "node test/drift-guard.mjs",
     "smoke:drop": "node test/smoke-drop.mjs",
     "smoke:login": "node test/smoke-login.mjs",

package/src/corpus/cookbook.md

@@ -71,10 +71,28 @@ curl -sS -X POST https://api.cloudgrid.io/api/v2/plug \
   -F "artifact=@./index.html;type=text/html"
 ```
 
-The response includes `slug` (the live link is `https://guest.cloudgrid.io/<slug>`)
-and `claim_url` (sign in within 7 days 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 only; a full app needs the signed-in `plug` flow above.
+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
+only; a full app needs the signed-in `plug` flow above.
+
+## Update your drop in place
+
+Re-plugging with `target_entity_id` updates the SAME entity — same slug, same URL,
+new content. Iterate on one link instead of minting a new one per revision:
+
+```
+curl -sS -X POST https://api.cloudgrid.io/api/v2/plug \
+  -F "target_entity_id=$ENTITY_ID" \
+  -F "owner_token=$OWNER_TOKEN" \
+  -F "artifact=@./index.html;type=text/html"
+```
+
+Signed in, drop the `owner_token` field and send your auth headers instead. Each
+anonymous edit returns a refreshed `owner_token` (store the new one) and resets
+the drop's expiry. Editing an archived or expired drop returns 409
+`EDIT_REJECTED`; omit `target_entity_id` when you actually want a fresh link.
 
 ## Shorter chains
 

package/src/corpus/install.md

@@ -34,9 +34,13 @@ npx skills add cloudgrid-io/skills
 
 ```
 /plugin marketplace add cloudgrid-io/skills
+/plugin install cloudgrid@cloudgrid-skills
 ```
 
-The marketplace manifest lives in `.claude-plugin/`.
+The marketplace manifest lives in `.claude-plugin/` (marketplace name:
+`cloudgrid-skills`, plugin name: `cloudgrid`). Installing the plugin bundles the
+skills, the SessionStart orientation hook, and the CloudGrid MCP server — the MCP
+auto-starts when the plugin is enabled, so no separate `claude mcp add` is needed.
 
 ### Codex
 

package/src/corpus/skill-claim.md

@@ -14,7 +14,7 @@ allowed-tools: Bash
 
 Turn an anonymous drop into an owned one. After an anonymous drop, the user has a
 `claim_url` (or token) plus the drop's `entity_id`. Once they sign in, claiming
-transfers ownership to them and extends the expiry from 7 days to 30. Claiming
+transfers ownership to them and resets the expiry window. Claiming
 re-homes the drop into the user's grid, so its public URL changes from
 `guest.cloudgrid.io/<slug>` to `<grid>.cloudgrid.io/<slug>` — share the new link.
 
@@ -26,11 +26,17 @@ skill (or `cloudgrid login` with the CLI) first.
 ## What you need
 
 Two things: the **entity id** of the anonymous drop (the `entity_id` field the drop
-returned), and the **claim token** — the `token` query parameter inside the
-`claim_url` the drop returned, e.g. `https://console.cloudgrid.io/claim?token=<TOKEN>`.
+returned), and the **claim token**. The claim token is the drop's `owner_token` —
+the same JWT used for anonymous re-plugs. It also appears as the `token` query
+parameter inside the `claim_url` the drop returned, e.g.
+`https://console.cloudgrid.io/claim?token=<TOKEN>`.
 A browser that still holds the `cg_anon_session` cookie from the drop can claim
 without a token instead.
 
+Note: every anonymous re-plug (edit) of the drop refreshes the `owner_token` and
+resets the drop's expiry. Always claim with the token from the LATEST drop or
+edit response — an older token may have been superseded.
+
 ## How to run it
 
 Claiming is now a "pickup" of the entity into your grid. The entity id goes in the

package/src/corpus/skill-drop.md

@@ -4,8 +4,9 @@ name: drop
 description: |
   Share an artifact and get a public URL. Use when the user wants to share,
   publish, send, or deploy an HTML page or file, or wants a link for a friend.
-  Works with no login (anonymous, 7-day, claimable later) or signed in (published
-  into the user's org, owned, 30-day). Inspirations only.
+  Works with no login (anonymous, claimable later) or signed in (published
+  into the user's org, owned). Re-plugging updates the same URL in place.
+  Inspirations only.
 argument-hint: "[file]"
 allowed-tools: Bash
 ---
@@ -50,18 +51,19 @@ curl -sS -X POST https://api.cloudgrid.io/api/v2/plug \
 
 The response is JSON (HTTP 201 for an anonymous drop). Read these fields:
 
-- `slug` — the entity's public slug. An anonymous inspiration's live link is
-  `https://guest.cloudgrid.io/<slug>`. The response has no ready-made `url`;
-  compose it from the slug. (Apps/agents would be `https://<slug>.<grid>.cloudgrid.io`,
-  but anonymous drops are always inspirations.)
-- `claim_url` — the link to sign in and keep it past the 7-day expiry.
+- `url` — the live link, composed by the server. Use it verbatim; never compose a
+  URL from the slug yourself.
+- `entity_id` — the durable handle for updating this drop later (see re-plug below).
+- `owner_token` — a JWT proving you made this drop. It lets you re-plug the drop
+  anonymously and doubles as the claim token. Its lifetime matches the drop's
+  expiry (default 7 days). Persist it together with `entity_id` and `url`.
+- `claim_url` — the link to sign in and keep the drop past its expiry.
 - `claim_message` — a ready-to-show nudge to sign in and claim.
 
 ## If the user is signed in
 
 A signed-in user can publish into their own org instead of anonymously — the drop
-is owned, lasts 30 days, and needs no claim. Add their token and org to the same
-request:
+is owned and needs no claim. Add their token and org to the same request:
 
 ```
 JWT=$(jq -r .jwt ~/.cloudgrid/credentials 2>/dev/null)
@@ -71,30 +73,63 @@ curl -sS -X POST https://api.cloudgrid.io/api/v2/plug \
   -F "artifact=@/path/to/index.html;type=text/html"
 ```
 
-A signed-in drop returns HTTP 202 with `slug` + `grid` and no `claim_url` (it is
-already owned). Its live link is `https://<grid>.cloudgrid.io/<slug>` for an
-inspiration. The org is taken from the `X-CloudGrid-Org` header — there is no
+A signed-in drop returns HTTP 202 with `entity_id`, `url`, `slug` + `grid` and no
+`claim_url` (it is already owned). Use the returned `url` as the live link — do
+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.
 
-## One drop = one entity (no in-place re-drop)
+## Re-plug: update the same URL in place
 
-The unified `/api/v2/plug` endpoint is create-only for this flow: every drop mints
-a NEW entity with a NEW URL. There is no `previous_id` / in-place-update path and no
-`202 unchanged` no-op — those belonged to the retired `/drop/auto` endpoint. To
-publish an update, drop again; you get a fresh link. (To update an existing app in
-place, sign in and use `cloudgrid:plug`, which targets the entity by name.)
+`/api/v2/plug` is a unified create-or-update endpoint. The switch is the
+`target_entity_id` form field:
 
-The MCP `cloudgrid_drop` tool accepts a `fresh` flag for backward compatibility,
-but it is now a no-op — each drop is already a fresh create.
+- **Absent** → create: a new entity, a new URL.
+- **Present** → re-plug: the SAME entity is updated — same slug, same URL, new
+  content. This is how you iterate on one shareable link.
+
+Signed in, re-plug with the entity id and your normal auth headers:
+
+```
+curl -sS -X POST https://api.cloudgrid.io/api/v2/plug \
+  -H "Authorization: Bearer $JWT" -H "X-CloudGrid-Org: $ORG" \
+  -F "target_entity_id=$ENTITY_ID" \
+  -F "artifact=@/path/to/index.html;type=text/html"
+```
+
+Anonymously, prove ownership with the `owner_token` the drop returned:
+
+```
+curl -sS -X POST https://api.cloudgrid.io/api/v2/plug \
+  -F "target_entity_id=$ENTITY_ID" \
+  -F "owner_token=$OWNER_TOKEN" \
+  -F "artifact=@/path/to/index.html;type=text/html"
+```
+
+Rules that matter:
+
+- `entity_id` + `url` (+ `owner_token` when anonymous) are the durable re-plug
+  handle. Persist them after every drop.
+- Every anonymous edit REFRESHES the `owner_token` — store the one from the
+  latest response; the old one is superseded. Each edit also resets the drop's
+  expiry window.
+- Editing an archived or expired drop returns **409 `EDIT_REJECTED`** — it never
+  silently creates a new entity. Drop again (without `target_entity_id`) if the
+  user wants a new link.
+- 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
+  `fresh` flag does the same: it forces a new entity instead of updating).
 
 ## After the drop
 
-Print the composed `url` (e.g. `https://guest.cloudgrid.io/<slug>`) on its own line,
-by itself, so it can be copied in one go. Then add one line of context: an anonymous
-drop lasts 7 days and can be claimed to keep it; a signed-in drop is already owned.
-Do not bury the URL in prose.
+Print the `url` from the response on its own line, by itself, so it can be copied
+in one go. Then add one line of context: an anonymous drop expires (default 7 days,
+reset on every edit) and can be claimed to keep it; a signed-in drop is already
+owned. Do not bury the URL in prose. Keep `entity_id` (and `owner_token` if
+anonymous) so a follow-up "change X" can re-plug the same URL.
 
 ## Limits and errors
 

package/src/corpus/skills-readme.md

@@ -25,16 +25,21 @@ behalf: scaffold, deploy, tail logs, share, read feedback. Everything here is fr
    cloudgrid login
    ```
 
-3. Add the skills. In Claude Code (recommended):
+3. Add the agent-core. In Claude Code (recommended):
 
    ```
    /plugin marketplace add cloudgrid-io/skills
-   /plugin install cloudgrid
+   /plugin install cloudgrid@cloudgrid-skills
    ```
 
-   They show under `/plugin` and `/skills` as `cloudgrid:drop`, `cloudgrid:login`,
-   … — or just say what you want ("drop this HTML to CloudGrid") and the right one
-   triggers.
+   One install wires up everything: the skills, the SessionStart orientation
+   hook, and the CloudGrid MCP server (`gridctl_start`, `gridctl_fetch`, and the
+   CLI-wrapping tools). The MCP auto-starts when the plugin is enabled — no
+   separate `claude mcp add` needed.
+
+   The skills show under `/plugin` and `/skills` as `cloudgrid:drop`,
+   `cloudgrid:login`, … — or just say what you want ("drop this HTML to
+   CloudGrid") and the right one triggers.
 
    Or install with the `gh skill` extension:
 
@@ -82,9 +87,11 @@ walks through it end to end.
 
 ## MCP server
 
-The MCP server is published separately as
+The Claude Code plugin above already bundles the MCP server — installing
+`cloudgrid@cloudgrid-skills` starts it automatically. For every other client, the
+MCP server is published separately as
 [`@cloudgrid-io/mcp`](https://github.com/cloudgrid-io/mcp). It exposes the same
-nine actions as MCP tools, for agents that speak the Model Context Protocol.
+actions as MCP tools, for agents that speak the Model Context Protocol.
 Install it with `npx -y @cloudgrid-io/mcp`, or point a remote-capable client at
 `https://mcp.cloudgrid.io/mcp`. See [USAGE.md](USAGE.md) for per-client setup.
 

package/src/corpus/usage.md

@@ -128,7 +128,7 @@ You can install both; they do not conflict.
 
 | Action | What it does |
 |---|---|
-| drop | Share an artifact, get a public URL. No login needed (anonymous, 7-day) or owned if signed in (30-day). |
+| drop | Share an artifact, get a public URL. No login needed (anonymous, claimable) or owned if signed in. Re-drop with the entity id to update the same URL. |
 | login | Sign in to CloudGrid, with or without the CLI. |
 | claim | Claim an anonymous drop into your account; the URL stays the same. |
 | init | Scaffold a new app or agent. |

package/src/corpus/workflows/dashboard.md

@@ -27,5 +27,7 @@ this recipe. Do not ask setup questions first; use sensible defaults and build.
    A dashboard is an inspiration and deploys synchronously, so you get a URL
    right away.
 5. **Return the live share URL.** Give the user the URL that serves the dashboard.
+   For revisions, re-deploy with the entity id from the first deploy — it updates
+   the same share URL, so the user iterates on one link.
 
 Keep the whole flow tight: fetch, fill, deploy, share.

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

@@ -25,5 +25,7 @@ this recipe. Do not ask setup questions first; use sensible defaults and build.
    A landing page is an inspiration and deploys synchronously, so you get a URL
    right away.
 5. **Return the live share URL.** Give the user the URL that serves the page.
+   For revisions, re-deploy with the entity id from the first deploy — it updates
+   the same share URL, so the user iterates on one link.
 
 Keep the whole flow tight: fetch, fill, deploy, share.

package/src/corpus/workflows/presentation.md

@@ -24,5 +24,7 @@ this recipe. Do not ask setup questions first; use sensible defaults and build.
    An HTML deck is an inspiration and deploys synchronously, so you get a URL
    right away.
 5. **Return the live share URL.** Give the user the URL that serves the deck.
+   For revisions, re-deploy with the entity id from the first deploy — it updates
+   the same share URL, so the user iterates on one link.
 
 Keep the whole flow tight: fetch, fill, deploy, share.

package/src/corpus/workflows/report.md

@@ -27,5 +27,7 @@ this recipe. Do not ask setup questions first; use sensible defaults and build.
    A report is an inspiration and deploys synchronously, so you get a URL right
    away.
 5. **Return the live share URL.** Give the user the URL that serves the report.
+   For revisions, re-deploy with the entity id from the first deploy — it updates
+   the same share URL, so the user iterates on one link.
 
 Keep the whole flow tight: fetch, fill, deploy, share.

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

@@ -27,5 +27,7 @@ build.
    A web app is an inspiration and deploys synchronously, so you get a URL
    right away.
 5. **Return the live share URL.** Give the user the URL that serves the app.
+   For revisions, re-deploy with the entity id from the first deploy — it updates
+   the same share URL, so the user iterates on one link.
 
 Keep the whole flow tight: fetch, adapt, deploy, share.