@cloudgrid-io/mcp 0.20.48 → 0.20.50

package/README.md

@@ -6,17 +6,17 @@ It ships in two editions from one codebase:
 
 - **Local (stdio)** — runs on your machine, full toolset including the CLI-wrapping
   tools. This README covers it. For Claude Code, Cursor, Claude Desktop.
-- **Web (hosted HTTP)** — a light, CLI-free toolset (drop, claim, login,
-  visibility) for web clients like claude.ai. See [REMOTE.md](REMOTE.md).
+- **Web (hosted HTTP)** — a lighter toolset (14 shared direct-API tools, no CLI
+  wrappers) for web clients like claude.ai. See [REMOTE.md](REMOTE.md).
 
 The local edition wraps the `grid` CLI for authenticated operations (the CLI
 handles auth, org context, and error formatting) and calls the API directly for the
-drop, claim, and login tools.
+plug, login, and visibility tools.
 
 ## CLI compatibility
 
 The MCP uses an installed CLI only when it meets the platform floor
-(`MIN_CLI_VERSION`, currently 0.15.2 - kept in lockstep with the API's live
+(`MIN_CLI_VERSION`, currently 0.15.14 — kept in lockstep with the API's live
 `cli_compat` floor, which rejects older CLIs with HTTP 426). Below the floor it
 skips the local/global CLI and lazily fetches `@cloudgrid-io/cli@latest` via
 npx instead. A CI drift guard (`npm run test:drift-guard`) asserts every
@@ -50,13 +50,27 @@ npx -y @cloudgrid-io/mcp
 Or from a clone:
 
 ```
-cd mcp-server
+cd mcp
 npm install
 npm start
 ```
 
 It speaks MCP over stdio. Point any MCP client at the `cloudgrid-mcp` command.
 
+### One CloudGrid server per client
+
+Run EITHER this local (stdio) server — standalone or via the Claude Code
+plugin, which bundles it — OR a hosted connector (`mcp.cloudgrid.io` /
+`mcp-connected.cloudgrid.io`) in a given client. Never both: each `grid_*`
+tool appears twice, the two servers hold separate sign-in state (the local
+edition shares the CLI's `~/.cloudgrid/credentials`; the connector holds an
+OAuth session), and they can disagree about whether you are signed in — the
+model may then act on whichever answered last. How to tell: duplicate
+`grid_*` entries in the client's tool list, or two CloudGrid servers in its
+MCP/connector settings. Which to keep: the local edition wherever you build
+runtime apps from folders (it has `path` + the CLI); the connector in
+chat-only clients where you publish single pages.
+
 ### QA session log (optional)
 
 Set `CLOUDGRID_QA_SLACK_WEBHOOK` to an **internal / private** Slack incoming-webhook
@@ -67,24 +81,29 @@ MUST be internal. Unset → the feature is fully dark (nothing captured, nothing
 posted). `CLOUDGRID_QA_IDLE_MS` overrides the abandoned-idle window (default
 900000 = 15 min).
 
+<!-- gen:tools -->
 ## Tools
 
+36 tools registered (14 shared across both editions, 22 local-only). No deprecated aliases. MIN_CLI_VERSION: 0.15.14.
+
 ### Direct-API tools (both editions)
 
-| Tool | Wraps | Notes |
+| Tool | Wraps | Summary |
 |---|---|---|
-| `grid_deploy` | `POST /api/v2/plug` | THE deploy/publish verb (CloudGrid calls it "plug"): create a new entity, or update the SAME entity in place with `target_entity_id` (same URL). Source via inline `html` (single page), local `path` (local edition), or inline `artifact_files` (both). Anonymous drops return an `entity_id` + `owner_token` re-plug/claim handle. |
-| `grid_claim_anonymous_deploy` | `POST /api/v2/entities/:id/pickup` | Claim an anonymous drop into the signed-in account (the claim token IS the drop's owner token). |
-| `grid_copy_app` | `POST /api/v2/runtimes/:id/fork` | Start a new entity from an existing runtime (lineage recorded). Needs sign-in. |
-| `grid_download_source` | `GET /api/v2/runtimes/:id/source` | Signed 15-minute source-bundle URLs. Needs sign-in. |
-| `grid_get_app_source` | `GET /api/v2/.../source` | Fetch a deployed entity's source (resolves entity_id from a URL). Read-only. |
-| `grid_login` | `GET /auth/login` | Start a CLI-free sign-in; returns a URL to open. |
-| `grid_login_status` | `GET /auth/status` | Finish the sign-in; saves the token to the shared CLI credentials. |
-| `grid_visibility` | `PATCH /api/v2/inspirations/<id>` | Change who can see a drop (private, space, authenticated, org, link). Needs sign-in. |
-| `grid_list_grids` | `GET /api/v2/orgs` | List the caller's grids. Read-only. |
-| `grid_start` | corpus | Orientation: the playbook + workflow index + live context. Call FIRST. Read-only. |
-| `grid_get_template` | corpus | Fetch a workflow / template / example / doc from the bundled corpus. Read-only. (`grid_fetch` is a kept deprecated alias.) |
-| `grid_note` / `grid_report` / `grid_feedback` | API | Session notes, consent-gated error reports, feedback feed. |
+| `grid_pickup` | API | Pick up an app: make your OWN COPY of any app you can see (like a git fork) into a grid you can build in. |
+| `grid_pull` | API | Pull an app to continue/edit it IN PLACE — like `git clone` of the SAME entity: your next grid_plug (with its target_... |
+| `grid_create_grid` | API | Create a new grid (workspace) for the signed-in user — they become its admin. |
+| `grid_note` | API | Optionally leave a one-paragraph summary of what you built this session and why. |
+| `grid_plug` | API | Plug an app, website, game, or single HTML page into CloudGrid — the live runtime that runs it and provides its infra... |
+| `grid_get_app_source` | API | Retrieve the CURRENT deployed HTML of an inspiration/drop inline as text, so you can edit it and re-plug the SAME URL... |
+| `grid_login` | API | Start a CLI-free CloudGrid sign-in. |
+| `grid_login_status` | API | Finish a sign-in started by grid_login. |
+| `grid_visibility` | API | Change who can see a CloudGrid inspiration OR runtime app/agent. |
+| `grid_check_deploy` | API | Check whether an async runtime-app build has finished and the app is live. |
+| `grid_list_grids` | API | List the signed-in user's grids, each with slug, name, role, and provisioning status. |
+| `grid_start` | API | Orient before building with CloudGrid — the live runtime environment where the user's apps run WITH the infrastructur... |
+| `grid_get_template` | corpus | Load a specific CloudGrid workflow, template, example, rule, or doc by name — deterministic retrieval from the bundle... |
+| `grid_report` | API | Report a genuine CloudGrid failure to the CloudGrid team — ONLY with the user's explicit consent. |
 
 The direct-API tools call the platform without the CLI, so they also work in
 the web edition. `grid_login` writes the same `~/.cloudgrid/credentials` the
@@ -92,40 +111,38 @@ CLI uses, so the two share one identity.
 
 ### CLI-wrapping tools (local edition only)
 
-| Tool | Wraps | Notes |
+| Tool | Wraps | Summary |
 |---|---|---|
-| `grid_create_project` | `grid new` | Scaffold an app or agent project; optionally seed a web service. |
-| `grid_view_logs` | `grid logs` | Snapshot of recent logs. Does not stream. Read-only. (`grid_logs` is a kept deprecated alias.) |
-| `grid_share` | `grid visibility set` | Set visibility, default link. |
-| `grid_whoami` | `grid whoami` | Show the signed-in user and active grid. Read-only. |
+| `grid_create_project` | `grid new` | Scaffold a new CloudGrid app or agent folder (cloudgrid.yaml + a web service), optionally pre-declaring resources. |
+| `grid_view_logs` | `grid logs` | Tail recent logs for an entity. |
+| `grid_share` | `grid visibility set` | Set an entity's visibility and print its URL. |
+| `grid_feedback` | `grid feedback list` | List recent feedback events for the active grid. |
+| `grid_whoami` | `grid whoami` | Show the signed-in user and active grid. |
 | `grid_switch_grid` | `grid use` | Switch the active grid. |
-| `grid_logout` | `grid logout` | Sign out and clear local credentials. Destructive. |
-| `grid_status` | `grid status` | Grid dashboard or entity detail. Read-only. |
-| `grid_info` | `grid info` | Entity metadata. Read-only. |
-| `grid_get` | `grid get grids\|entities\|spaces` | List grids, entities, or spaces. Read-only. |
-| `grid_describe_grid` | `grid describe grid <slug>` | Grid detail. Read-only. |
-| `grid_edit_existing_app` | `grid pickup <name>` | Download an entity's source and bind the folder. |
-| `grid_rename` | `grid rename` | Rename an entity's display name. |
-| `grid_take_offline` | `grid unplug` | Take an entity off the grid. Destructive; requires confirm. |
-| `grid_delete` | `grid delete entity` | Archive an inspiration. Destructive; requires confirm. |
-| `grid_rollback_deploy` | `grid rollback` | Rollback to a previous version. |
-| `grid_list_versions` | `grid versions` | List published versions. Read-only. |
-| `grid_set_env` | `grid env` | Get, set, or list environment variables. |
-| `grid_set_secret` | `grid secrets` | Set or list secret names. Never returns secret values. |
-| `grid_scaffold` | `grid scaffold` | Generate starter files. |
-| `grid_diagnose` | `grid doctor` | Run local diagnostics. Read-only. |
-| `grid_get_url` | `grid open --print` | Return the public URL. Does not open a browser. Read-only. |
+| `grid_logout` | `grid logout` | Sign out and clear local credentials. |
+| `grid_status` | `grid status` | Org dashboard, entity detail, or deploy snapshot. |
+| `grid_info` | `grid info` | Show metadata for a CloudGrid entity. |
+| `grid_get` | `grid get <grids|entities|spaces> --json` | List CloudGrid grids, entities, or spaces. |
+| `grid_describe_grid` | `grid describe grid <slug> --json` | Show a grid's detail: role, members, spaces, tier, wildcard-TLS state. |
+| `grid_edit_existing_app` | `grid pull` | Continue/edit an EXISTING entity locally: download its source + cloudgrid.yaml and link the folder so your next `grid... |
+| `grid_rename` | `grid rename` | Rename a CloudGrid entity's display name (slug stays the same). |
+| `grid_take_offline` | `grid unplug` | Take an entity off the grid. |
+| `grid_delete` | `grid delete entity` | Archive a CloudGrid inspiration. |
+| `grid_rollback_deploy` | `grid rollback` | Rollback an entity to a previous version. |
+| `grid_list_versions` | `grid versions` | List published versions for an entity. |
+| `grid_set_env` | `grid env` | Manage environment variables for an entity. |
+| `grid_set_secret` | `grid secrets` | Set or list secret names for an entity. |
+| `grid_scaffold` | `grid scaffold` | Scaffold service folders declared in cloudgrid.yaml (idempotent). |
+| `grid_diagnose` | `grid doctor` | Run CloudGrid diagnostics on the local environment. |
+| `grid_get_url` | `grid open --print` | Return the public URL for an entity. |
+
+<!-- /gen:tools -->
 
 `grid_share` and `grid_visibility` overlap on purpose: `grid_share`
 wraps the CLI and defaults to `link`; `grid_visibility` is direct API, takes an
-explicit scope, and defaults its target to the session's last drop -- it is the one
+explicit scope, and defaults its target to the session's last drop — it is the one
 the web edition gets.
 
-37 tool names are advertised in total: 35 canonical + 2 kept deprecated
-aliases (`grid_fetch`, `grid_logs`). The 0.20.8 alias diet dropped the other 16
-legacy aliases. Per-tool internals (signature, sketch, behavior):
-[docs/TOOL-INTERNALS.md](docs/TOOL-INTERNALS.md).
-
 All tools carry MCP annotations (`readOnlyHint`, `destructiveHint`,
 `openWorldHint`) for clients that support them.
 
@@ -135,7 +152,7 @@ A smoke test spawns the server with a real MCP client, lists the tools, and call
 the read-only `grid_feedback` tool end to end:
 
 ```
-cd mcp-server
+cd mcp
 npm install
 npm run smoke
 ```
@@ -146,5 +163,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.
-- `grid_logs` never uses `--follow`; a streaming call would never return.
+- `grid_view_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.20.48",
+  "version": "0.20.50",
   "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/auth.js

@@ -25,6 +25,13 @@ const PUBLIC_API_BASE = (
   process.env.CLOUDGRID_PUBLIC_API_URL || "https://api.cloudgrid.io"
 ).replace(/\/+$/, "");
 
+// The public URL of the connected (OAuth) MCP host, used in error guidance that
+// suggests the hosted connector as an alternative. Derived from MCP_PUBLIC_URL
+// (set on the deployment) with a fallback.
+const CONNECTED_MCP_HOST =
+  process.env.MCP_PUBLIC_URL?.replace(/\/+$/, "") ||
+  "https://mcp-connected.cloudgrid.io";
+
 export function cloudgridHome() {
   return process.env.CLOUDGRID_HOME || join(homedir(), ".cloudgrid");
 }
@@ -52,7 +59,7 @@ const CERT_ERROR_GUIDANCE =
   "- Install the root CA into your OS trust store (macOS Keychain, Windows " +
   "Certificate Manager, or /usr/local/share/ca-certificates on Linux), or\n" +
   "- Set NODE_EXTRA_CA_CERTS=/path/to/root-ca.pem before launching the MCP, or\n" +
-  "- Use the hosted MCP connector: https://mcp-connected.cloudgrid.io/mcp";
+  `- Use the hosted MCP connector: ${CONNECTED_MCP_HOST}/mcp`;
 
 function throwCertError() {
   const err = new Error(CERT_ERROR_GUIDANCE);
@@ -82,7 +89,7 @@ export async function pollStatusOnce(code) {
     throw new Error(
       `Can't reach api.cloudgrid.io (${cause}). ` +
         `If you are behind a proxy, set HTTPS_PROXY; or use the hosted connector ` +
-        `https://mcp-connected.cloudgrid.io/mcp.`,
+        `${CONNECTED_MCP_HOST}/mcp.`,
     );
   }
   if (res.status === 404) {

package/src/corpus/cli-reference.md

@@ -90,7 +90,7 @@ grid grid
 | `logs [name]` | Stream entity logs |
 | `open [name]` | Open the entity URL in the browser |
 | `info [name]` / `builds [name]` | Entity metadata; recent deploys |
-| `visibility set <slug> <mode>` | private \| authenticated \| org \| link |
+| `visibility set <slug> <mode>` | private \| grid \| link — or the axes: `--inside <private\|spaces\|grid> --outside <none\|link\|public>` (+ `--require-signin`, `--space <slug>`) |
 | `rollback` / `versions` | Roll back to a prior deploy; list/tag minted versions |
 | `env` / `secrets` | Manage runtime env vars and secrets (secret values are never printed) |
 | `grid` / `list` | List what's on your hub / org |

package/src/corpus/install.md

@@ -136,8 +136,13 @@ npx -y @cloudgrid-io/mcp
 ```
 
 It wraps the same `grid` CLI and uses the same credentials, so no extra login
-is needed. Remote-capable clients can point at `https://mcp.cloudgrid.io/mcp`
-instead. See [USAGE.md](USAGE.md) for per-client snippets.
+is needed. Remote-capable clients can point at one of two hosted endpoints:
+
+- `https://mcp.cloudgrid.io/mcp` — anonymous-first; no account needed to try it.
+- `https://mcp-connected.cloudgrid.io/mcp` — connected; native OAuth sign-in
+  when you add it (for claude.ai org connectors and clients that support OAuth).
+
+See [USAGE.md](USAGE.md) for per-client snippets.
 
 ### Claude Desktop — one-click install
 

package/src/corpus/playbook.md

@@ -7,7 +7,7 @@ Operating rules:
 3b. No grid yet (first-time signed-in user): grid_plug returns needs_grid_create when the account has no grid, and a plug can fail with 403 NO_ACTIVE_ORG. Do NOT send the user to the console — suggest a short slug (3-40 lowercase letters/digits/hyphens, starting with a letter), confirm it with the user (it is permanent and appears in URLs), call grid_create_grid, then re-call grid_plug with grid: <slug>.
 3c. A failed runtime build never loses the work: the source was uploaded before the build ran and lives on the entity. Read the build log (grid_check_deploy) and fix; if it cannot be fixed from this session (hosted, no filesystem), hand the user their files — grid_get_app_source returns a source zip link (source_download_url), and `npx -y @cloudgrid-io/cli@latest pull <grid>/<slug>` downloads the project AND links the folder so the next plug updates the SAME entity locally. Offer one of these instead of abandoning the build or starting over.
 4. Load specifics on demand. Use grid_get_template({kind, name}) to pull the exact workflow, template, or example you need (kind ∈ workflow|template|example|rule|troubleshooting|doc).
-5. Always return the live share URL at the end — that is the deliverable. On a NEW plug, then ASK the user who should be able to open it — private (only you), a space, your grid, anyone with the link, or anyone signed in — and set their choice with grid_visibility. Never pick the visibility silently. On a re-plug/edit of an existing entity, leave its current visibility as-is unless the user asks to change it.
+5. Always return the live share URL at the end — that is the deliverable. On a NEW plug, then ASK the user who should be able to open it — private (only you), your grid, or anyone with the link (optionally sign-in required, or search-indexed for public findability; selected spaces via inside: spaces) — and set their choice with grid_visibility. Never pick the visibility silently. On a re-plug/edit of an existing entity, leave its current visibility as-is unless the user asks to change it. Note the model: visibility is two axes — inside the grid (private | spaces | grid) and outside it (none | link | public); the old 'authenticated' mode is retired (it equals a sign-in-required link) and 'org' is gone (use grid).
 6. Brainstorm first (lightly) for a real app, then minimize questions. For a substantial runtime app, take ONE lightweight beat before generating/plugging: confirm the goal + 3-5 core features in a sentence, check for a matching template/recipe (capability-map), and infer the data/runtime needs and STATE them ("I'll add a database so entries are saved"). Keep it to a line or two; never ask a non-technical user infra questions they can't answer. A simple single page skips this and builds immediately. Otherwise use sensible defaults and build; don't front-load setup questions.
 7. If a signed-in publish fails with a server error, do not fall back to anonymous publishing (it burns the anonymous quota and downgrades ownership); surface the error, use the CLI fallback if offered, or ask the user.
 8. When signed in and the user has more than one grid, do not assume a target. For a NEW app, establish the grid UP FRONT — grid_start returns the grids; if there is more than one, ask "which grid should this go on?" before you start building, and carry that slug into grid_plug. As a backstop, grid_plug hard-gates this: an authed create with >1 grid and no chosen grid returns needs_grid (the picker) instead of plugging; a create with no auth and no anon returns needs_auth (sign-in vs anonymous) instead of silently publishing anonymously. Relay either ask to the user; never pick silently.

package/src/corpus/skill-share.md

@@ -40,11 +40,17 @@ The command prints the outlet URL. Hand that URL to the user.
 
 `grid visibility set <slug> <mode>` accepts:
 
-- `link` — anyone with the URL can open it. Use this for sharing.
+- `link` — anyone with the URL can open it. Use this for sharing. Add
+  `--require-signin` for signed-in accounts only, `--indexed` to be findable by
+  search engines.
 - `private` — only the owner.
-- `authenticated` — any logged-in user.
-- `org` — members of the org.
-- `space` — members of the entity's space.
+- `grid` — everyone in the grid.
+
+Finer control uses the two axes instead of a mode:
+`grid visibility set <slug> --inside <private|spaces|grid> --outside <none|link|public> [--space <slug>...] [--require-signin]`
+(`--outside public` = anyone, search-indexed. `authenticated` is retired — it
+equals `--inside private --outside link --require-signin`; `org` is gone — use
+`grid`.)
 
 Default to `link` when the user says "share" or "make it public". Confirm before
 using a wider mode than they asked for.

package/src/tools/constants.js

@@ -29,12 +29,20 @@ export const ANON_HTML_MAX_BYTES = 2_000_000;
 export const AUTHED_HTML_MAX_BYTES = 25_000_000;
 export const CONSOLE_URL = "https://console.cloudgrid.io/";
 
+// Display labels for visibility values (two-axis model). The OPTIONS list is what
+// the post-plug ask offers; the LABELS map also keeps legacy keys (org,
+// authenticated, space) so an entity's CURRENT stored value still renders — do
+// not offer those as choices.
+export const VISIBILITY_OPTIONS = ["private", "grid", "link"];
 export const VISIBILITY_LABELS = {
   private: "Only you",
-  org: "Your grid",
-  authenticated: "Anyone signed in",
-  space: "A space",
+  grid: "Everyone in your grid",
   link: "Anyone with the link",
+  // display-only (legacy stored values / axis renderings):
+  org: "Everyone in your grid",
+  authenticated: "Anyone with the link, sign-in required",
+  space: "Selected spaces",
+  public: "Anyone, findable by search",
 };
 
 // ── Widget resources (ChatGPT Apps SDK, web edition only) ────────────────────

package/src/tools/deploy.js

@@ -13,6 +13,7 @@ import {
   AUTHED_HTML_MAX_BYTES,
   CONSOLE_URL,
   VISIBILITY_LABELS,
+  VISIBILITY_OPTIONS,
   APPS_WIDGETS_ENABLED,
   GRID_PICKER_URI,
   PLUG_UPLOAD_TIMEOUT_MS,
@@ -316,8 +317,8 @@ const GUEST_ORG_SLUG = "guest";
 // `<slug>--<grid>.cloudgrid.io`), so it must never be the primary source:
 //   - inspiration (HTML drops): path-based at the org apex
 //       https://<grid>.cloudgrid.io/<slug>
-//   - runtime (app/agent):      flat-arch double-dash host
-//       https://<slug>--<grid>.cloudgrid.io
+//   - runtime (app/agent):      subdomain
+//       https://<slug>.<grid>.cloudgrid.io
 // Anonymous drops are grid-less in the response (`grid: null`); they live under
 // the Guest Org, so the apex slug is the constant `guest`.
 function composePlugUrl(data) {
@@ -326,11 +327,7 @@ function composePlugUrl(data) {
   const grid = data?.grid || GUEST_ORG_SLUG;
   const kind = data?.detection?.kind;
   if (kind === "app" || kind === "agent") {
-    // Flat-arch host: runtime entities serve at `<slug>--<grid>.cloudgrid.io`
-    // (double-dash), NOT the legacy nested `<slug>.<grid>` form — the latter
-    // 404s on every current grid. Still fallback-only; the server's `data.url`
-    // remains the primary source (resolvePlugUrl).
-    return `https://${slug}--${grid}.cloudgrid.io`;
+    return `https://${slug}.${grid}.cloudgrid.io`;
   }
   // inspiration (and any unknown/static kind) — path-based at the org apex.
   return `https://${grid}.cloudgrid.io/${slug}`;
@@ -1243,6 +1240,15 @@ export async function runPlug(ctx, input, deps = {}) {
         "may accompany a .zip `path` — it becomes the index.html over the archive's assets.",
     );
   }
+  // M3: a create/re-plug with NO source at all is a caller mistake — fail it
+  // here with the source list instead of letting it wander into an obscure
+  // downstream error.
+  if (!hasHtml && !hasArtifacts && !hasPath) {
+    throw new Error(
+      "No source to plug. Pass exactly one of: `html` (a single inline HTML document), " +
+        "`artifact_files` (multiple inline files), or `path` (a local file/folder/zip, local edition only).",
+    );
+  }
   if (ctx.edition === "web" && hasPath) {
     throw new Error(
       "The hosted server cannot read local files — pass the source inline via `html` or `artifact_files`.",
@@ -1750,14 +1756,14 @@ export async function runPlug(ctx, input, deps = {}) {
     const current = typeof data.visibility === "string" ? data.visibility : null;
     structured.console_url = CONSOLE_URL;
     if (current) structured.current_visibility = current;
-    structured.visibility_options = Object.entries(VISIBILITY_LABELS).map(([v, l]) => ({ value: v, label: l }));
+    structured.visibility_options = VISIBILITY_OPTIONS.map((v) => ({ value: v, label: VISIBILITY_LABELS[v] }));
     lines.push(`Manage all your apps in your grid: ${CONSOLE_URL}`);
     lines.push(
       `Now ASK the user who should be able to open this${current ? ` (currently ${VISIBILITY_LABELS[current] ?? current})` : ""}, then set their choice with grid_visibility — do not decide it for them. Options: ${
-        Object.entries(VISIBILITY_LABELS)
-          .map(([v, l]) => `${v} (${l})`)
+        VISIBILITY_OPTIONS
+          .map((v) => `${v} (${VISIBILITY_LABELS[v]})`)
           .join("; ")
-      }.`,
+      }. Finer control: a sign-in-required link (require_signin), search-indexed (indexed), or selected spaces (inside: spaces).`,
     );
   }
   return { text: lines.join("\n"), structured };
@@ -1848,7 +1854,7 @@ export async function runPickup(ctx, { id, into_org_slug, name, source_version_i
 // direct API — works on the hosted edition where the CLI-wrapping share tool is
 // unavailable. Kind-aware routing (see below). Defaults to the drop made in this
 // session, so "make it private" needs no ids.
-export async function runVisibility(ctx, { target, visibility, kind, org }) {
+export async function runVisibility(ctx, { target, visibility, inside, outside, require_signin, spaces, indexed, kind, org }) {
   const token = await ctx.getToken();
   if (!token) {
     throw new Error("Changing visibility needs an owner. Run grid_login first.");
@@ -1865,32 +1871,78 @@ export async function runVisibility(ctx, { target, visibility, kind, org }) {
     headers["X-CloudGrid-Org"] = orgSlug;
   }
 
-  // Two visibility surfaces with two vocabularies:
-  //   - inspirations: PATCH /api/v2/inspirations/:id       { private|space|authenticated|org|link }
-  //   - runtimes:     PATCH /api/v2/entities/:id/visibility { private|authenticated|grid|link }
-  // Whole-grid visibility is the legacy `org` on inspirations and the canonical
-  // `grid` on runtimes. Normalize the caller's value to `grid`, then map per
-  // route. `space` exists only on inspirations.
-  const vis = visibility === "org" ? "grid" : visibility;
-  const runtimeValue = vis; // private | authenticated | grid | link
-  const inspirationValue = vis === "grid" ? "org" : vis; // private | space | authenticated | org | link
+  // ── Two-axis visibility model ──────────────────────────────────────
+  // A scope is two independent axes:
+  //   inside  (share_scope):     private | spaces | grid   — who in the grid sees it
+  //   outside (external_access): none | link | public      — reach beyond the grid
+  //   require_signin: link only — the link needs a signed-in CloudGrid account
+  // Legacy positional modes (private|grid|link) still ride the { visibility }
+  // body; `authenticated` is RETIRED as a first-class mode and maps to the axis
+  // body it equals (private + link + require_signin); `org` is rejected;
+  // `public` as a mode is an alias of `link` (the axis value `public` is the
+  // indexed one); `space` maps to inside: spaces and needs the `spaces` list.
+  const normSpaces = [...new Set((spaces || []).map((s) => String(s).trim().toLowerCase()).filter(Boolean))];
+  const useAxes = inside !== undefined || outside !== undefined;
+  let body;
+  let requested; // for the result text when the response is sparse
+  if (useAxes) {
+    if (visibility) throw new Error("Pass either `visibility` or the `inside`/`outside` axes, not both.");
+    if (!inside || !outside) {
+      throw new Error("Both axes are required: inside (private|spaces|grid) and outside (none|link|public).");
+    }
+    if (inside === "spaces" && normSpaces.length === 0) {
+      throw new Error("inside: spaces needs at least one space slug in `spaces`.");
+    }
+    if (inside !== "spaces" && normSpaces.length > 0) {
+      throw new Error("`spaces` only applies with inside: spaces.");
+    }
+    if (require_signin === true && outside !== "link") {
+      throw new Error("require_signin only applies when outside is link.");
+    }
+    body = {
+      share_scope: inside,
+      external_access: outside,
+      ...(require_signin === true ? { require_signin: true } : {}),
+      ...(inside === "spaces" ? { visibility_spaces: normSpaces } : {}),
+    };
+    requested = `inside: ${inside}${inside === "spaces" ? ` (${normSpaces.join(", ")})` : ""}, outside: ${outside}${require_signin === true ? " (sign-in required)" : ""}`;
+  } else {
+    let mode = String(visibility || "").trim().toLowerCase();
+    if (!mode) throw new Error("Pass a visibility mode (private | grid | link), or the inside/outside axes.");
+    if (mode === "org") {
+      throw new Error("'org' visibility is deprecated. Use 'grid' (everyone in the grid).");
+    }
+    if (mode === "public") mode = "link"; // alias; `indexed: true` governs search-indexing
+    if (mode === "authenticated") {
+      // Retired as a first-class mode — the axis body it equals.
+      body = { share_scope: "private", external_access: "link", require_signin: true };
+      requested = "link with sign-in required (the retired 'authenticated')";
+    } else if (mode === "space") {
+      if (normSpaces.length === 0) {
+        throw new Error("'space' visibility needs the `spaces` list (which space slugs can see it) — or use inside: spaces with outside: none.");
+      }
+      body = { share_scope: "spaces", external_access: "none", visibility_spaces: normSpaces };
+      requested = `selected spaces (${normSpaces.join(", ")})`;
+    } else if (mode === "private" || mode === "grid" || mode === "link") {
+      body = { visibility: mode };
+      if (mode === "grid" && normSpaces.length > 0) body.visibility_spaces = normSpaces;
+      if (mode === "link") body.link_indexed = indexed === true;
+      requested = mode + (mode === "link" && indexed === true ? " (search-indexed)" : "");
+    } else {
+      throw new Error(`Unknown visibility '${visibility}'. Use private | grid | link (public = link alias), or the inside/outside axes.`);
+    }
+  }
 
   const k = kind || ctx.state.lastDrop?.kind || null;
   const isRuntimeKind = k === "app" || k === "agent";
 
-  if (vis === "space" && isRuntimeKind) {
-    throw new Error(
-      "'space' visibility isn't available for runtime apps/agents. Use grid, authenticated, private, or link.",
-    );
-  }
-
-  const patch = async (pathName, value) => {
+  const patch = async (pathName) => {
     let res;
     try {
       res = await fetch(`${API_BASE}${pathName}`, {
         method: "PATCH",
         headers,
-        body: JSON.stringify({ visibility: value }),
+        body: JSON.stringify(body),
       });
     } catch (err) {
       throw new Error(`Could not reach CloudGrid at ${API_BASE}: ${err.message}`);
@@ -1901,33 +1953,53 @@ export async function runVisibility(ctx, { target, visibility, kind, org }) {
     return { res, data, raw };
   };
 
+  // BOTH realms now take the same realm-scoped visibility PATCH with the
+  // same body vocabulary: /api/v2/entities/:id/visibility (runtimes) and
+  // /api/v2/inspirations/:id/visibility (inspirations).
   const runtimePath = `/api/v2/entities/${encodeURIComponent(id)}/visibility`;
-  const inspirationPath = `/api/v2/inspirations/${encodeURIComponent(id)}`;
+  const inspirationPath = `/api/v2/inspirations/${encodeURIComponent(id)}/visibility`;
 
-  // Route order. `space` is inspiration-only; a known runtime kind goes straight
-  // to the entities route; a known inspiration goes straight to the inspiration
-  // route; an unknown kind tries the runtime route first and falls back to the
-  // inspiration route on a not-found (mirrors runPickup).
+  // Route order: a known runtime kind goes straight to the entities route; a
+  // known inspiration to the inspiration route; unknown tries runtime first and
+  // falls back on a not-found (mirrors runPickup).
   let order;
-  if (vis === "space") order = ["inspiration"];
-  else if (isRuntimeKind) order = ["runtime"];
+  if (isRuntimeKind) order = ["runtime"];
   else if (k === "inspiration") order = ["inspiration"];
   else order = ["runtime", "inspiration"];
 
   let last;
   for (let i = 0; i < order.length; i++) {
     const route = order[i];
-    last = route === "runtime"
-      ? await patch(runtimePath, runtimeValue)
-      : await patch(inspirationPath, inspirationValue);
+    last = await patch(route === "runtime" ? runtimePath : inspirationPath);
     if (last.res.ok) {
-      const lines = [`Visibility is now ${vis}.`];
-      if (last.data?.url) lines.push(last.data.url);
+      const d = last.data || {};
+      // Prefer the server's stored axes (stored axes are authoritative on
+      // the wire); fall back to what we asked for.
+      const lines = [];
+      if (d.share_scope || d.external_access) {
+        const insideLine =
+          d.share_scope === "private" ? "only the owner" :
+          d.share_scope === "spaces" ? `selected spaces${Array.isArray(d.visibility_spaces) && d.visibility_spaces.length ? ` (${d.visibility_spaces.join(", ")})` : ""}` :
+          d.share_scope === "grid" ? "everyone in the grid" : d.share_scope;
+        const outsideLine =
+          d.external_access === "none" ? "no one outside the grid" :
+          d.external_access === "link" ? `anyone with the link${d.require_signin ? " (signed-in accounts only)" : ""}${d.link_indexed ? ", search-indexed" : ""}` :
+          d.external_access === "public" ? "anyone, findable by search engines" : d.external_access;
+        lines.push(`Visibility set — inside the grid: ${insideLine}; outside: ${outsideLine}.`);
+      } else {
+        lines.push(`Visibility is now ${d.visibility || requested}.`);
+      }
+      if (d.url) lines.push(d.url);
       return {
         text: lines.join("\n"),
         structured: {
-          visibility: vis,
-          ...(last.data?.url ? { url: last.data.url } : {}),
+          visibility: d.visibility || (useAxes ? undefined : String(visibility || "").trim().toLowerCase() || undefined),
+          ...(d.share_scope ? { share_scope: d.share_scope } : {}),
+          ...(d.external_access ? { external_access: d.external_access } : {}),
+          ...(d.require_signin !== undefined ? { require_signin: d.require_signin === true } : {}),
+          ...(Array.isArray(d.visibility_spaces) ? { visibility_spaces: d.visibility_spaces } : {}),
+          ...(d.link_indexed !== undefined ? { link_indexed: d.link_indexed === true } : {}),
+          ...(d.url ? { url: d.url } : {}),
         },
       };
     }

package/src/tools/register.js

@@ -398,7 +398,10 @@ export function registerTools(server, ctx) {
         })).optional().describe("Alias of grids (legacy picker alias)."),
         via: z.string().optional().describe("Recovery marker: 'cli-fallback' when a signed-in create was published through the bundled CloudGrid CLI."),
       },
-      annotations: { readOnlyHint: false, destructiveHint: false, openWorldHint: true },
+      // destructiveHint (M3): a re-plug with target_entity_id REPLACES what is
+      // live at a public URL in place. Versions + grid rollback exist, but the
+      // honest MCP annotation for overwrite-live-state is destructive.
+      annotations: { readOnlyHint: false, destructiveHint: true, openWorldHint: true },
       ...(ctx.edition === "web" && APPS_WIDGETS_ENABLED ? {
         _meta: {
           ui: { resourceUri: LIVE_RESULT_URI, csp: WIDGET_CSP },
@@ -659,15 +662,25 @@ export function registerTools(server, ctx) {
   reg(
     "grid_visibility",
     {
-      description: "Change who can see a CloudGrid inspiration OR runtime app/agent: private, authenticated, grid (everyone in the grid), or link (anyone with the URL). `space` is inspiration-only. Use when the user wants to make something private, restrict who sees it, or open it up — including right after a drop, with no target id needed. Kind-aware: routes runtime apps/agents to the entities visibility surface and inspirations to the inspiration surface automatically. Defaults to the drop made in this session. Requires sign-in. Calls the API directly.",
+      description: "Change who can see a CloudGrid inspiration OR runtime app/agent. Simple modes: private (only the user), grid (everyone in their grid), link (anyone with the URL — add indexed: true to be findable by search engines). Finer control via the TWO AXES instead: inside (who in the grid: private | spaces | grid) and outside (reach beyond it: none | link | public), with require_signin for a members-only link and `spaces` for selected spaces. 'authenticated' is retired (it maps to a sign-in-required link); 'org' is gone — use grid. Use when the user wants to make something private, restrict who sees it, or open it up — including right after a drop, with no target id needed. Kind-aware routing across both surfaces. Defaults to the drop made in this session. Requires sign-in. Calls the API directly.",
       inputSchema: {
-        visibility: z.enum(["private", "space", "authenticated", "grid", "org", "link"]).describe("The new scope. Use `grid` for whole-grid visibility (`org` is the deprecated alias). `space` is inspiration-only."),
+        visibility: z.enum(["private", "grid", "link", "public", "authenticated", "space"]).optional().describe("Simple mode: private | grid | link ('public' is an alias of link — pass indexed: true for search-findable; 'authenticated' is the retired alias for a sign-in-required link; 'space' needs the `spaces` list). Pass either this OR the inside/outside axes."),
+        inside: z.enum(["private", "spaces", "grid"]).optional().describe("Axis 1 — who in the grid can see it: private (only the user), spaces (selected spaces — pass `spaces`), or grid (everyone in the grid). Use together with `outside`, instead of `visibility`."),
+        outside: z.enum(["none", "link", "public"]).optional().describe("Axis 2 — reach beyond the grid: none, link (anyone with the link; add require_signin: true for signed-in accounts only), or public (anyone, and findable by search engines)."),
+        require_signin: z.boolean().optional().describe("With outside: link (or visibility: link) — the link requires a signed-in CloudGrid account."),
+        spaces: z.array(z.string()).optional().describe("Space slugs, for inside: spaces (or the legacy space/grid modes)."),
+        indexed: z.boolean().optional().describe("With visibility: link — make the page search-engine indexable."),
         target: z.string().optional().describe("Entity id. Defaults to this session's last drop."),
         kind: z.enum(["inspiration", "app", "agent"]).optional().describe("Entity kind. Omit to auto-detect from this session's last drop (falls back to trying the runtime surface, then the inspiration surface)."),
         org: z.string().optional().describe("Grid of the entity. Defaults to the active grid."),
       },
       outputSchema: {
-        visibility: z.string().describe("The visibility that was set."),
+        visibility: z.string().optional().describe("The legacy mode that was set, when a simple mode was used."),
+        share_scope: z.string().optional().describe("Stored axis: who in the grid (private | spaces | grid)."),
+        external_access: z.string().optional().describe("Stored axis: reach beyond the grid (none | link | public)."),
+        require_signin: z.boolean().optional().describe("Whether the link requires sign-in."),
+        visibility_spaces: z.array(z.string()).optional().describe("The space slugs, when share_scope is spaces."),
+        link_indexed: z.boolean().optional().describe("Whether the link is search-indexed."),
         url: z.string().optional().describe("URL of the entity, if returned."),
       },
       annotations: { readOnlyHint: false, destructiveHint: false, openWorldHint: true },