@cloudgrid-io/mcp 0.19.2 → 0.20.2

package/src/corpus/skill-share.md

@@ -4,7 +4,7 @@ name: share
 description: |
   Make a CloudGrid entity shareable and print its URL. Use when the user wants to
   share a link, make something public, send an app to someone, or get a shareable
-  URL. Wraps cloudgrid visibility.
+  URL. Wraps grid visibility.
 argument-hint: "[name]"
 allowed-tools: Bash
 ---
@@ -12,12 +12,12 @@ allowed-tools: Bash
 # CloudGrid Share
 
 Set an entity's visibility so others can reach it, then print the URL. Wraps
-`cloudgrid visibility set`.
+`grid visibility set`.
 
 ## Step 0 — Bootstrap
 
-1. If `cloudgrid` is not on `$PATH`: `npm install -g @cloudgrid-io/cli`
-2. If `cloudgrid whoami` fails: ask the user to run `cloudgrid login`. Wait for
+1. If `grid` is not on `$PATH`: `npm install -g @cloudgrid-io/cli`
+2. If `grid whoami` fails: ask the user to run `grid login`. Wait for
    confirmation.
 
 ## UX rules
@@ -31,14 +31,14 @@ Set an entity's visibility so others can reach it, then print the URL. Wraps
 To make an entity reachable by anyone with the link:
 
 ```
-cloudgrid visibility set my-thing link
+grid visibility set my-thing link
 ```
 
 The command prints the outlet URL. Hand that URL to the user.
 
 ## Visibility modes
 
-`cloudgrid visibility set <slug> <mode>` accepts:
+`grid visibility set <slug> <mode>` accepts:
 
 - `link` — anyone with the URL can open it. Use this for sharing.
 - `private` — only the owner.

package/src/corpus/skills-readme.md

@@ -2,7 +2,7 @@
 
 Multi-agent skills for CloudGrid. Install them in Claude Code, Codex, or Cursor,
 and your agent can build, ship, and run things on CloudGrid through the
-`cloudgrid` CLI.
+`grid` CLI.
 
 ## Why CloudGrid
 
@@ -22,7 +22,7 @@ behalf: scaffold, deploy, tail logs, share, read feedback. Everything here is fr
 2. Log in:
 
    ```
-   cloudgrid login
+   grid login
    ```
 
 3. Add the agent-core. In Claude Code (recommended):

package/src/corpus/templates/docs-app/astro.config.mjs

@@ -0,0 +1,42 @@
+// @ts-check
+import { defineConfig } from 'astro/config';
+import starlight from '@astrojs/starlight';
+import starlightLlmsTxt from 'starlight-llms-txt';
+
+// A docs-app is served at the entity ROOT (e.g. https://my-docs--<grid>.cloudgrid.io/),
+// so there is NO `base`. (A base is only needed when a docs site is mounted under
+// a sub-path like /docs — that is a special case, not the default.)
+// https://astro.build/config
+export default defineConfig({
+	site: 'https://example.com',
+	integrations: [
+		starlight({
+			// Emit agent-readable docs on every build: /llms.txt (index) and
+			// /llms-full.txt (full content). Keeps in sync with the content.
+			plugins: [
+				starlightLlmsTxt({
+					projectName: 'My Project',
+					description: 'One-line summary of what this project is — shown to agents at /llms.txt.',
+				}),
+			],
+			title: 'My Project Docs',
+			description: 'Documentation for My Project.',
+			social: [
+				{ icon: 'github', label: 'GitHub', href: 'https://github.com/your-org/your-repo' },
+			],
+			sidebar: [
+				{
+					label: 'Start here',
+					items: [
+						{ label: 'Introduction', slug: 'index' },
+						{ label: 'Getting started', slug: 'guides/getting-started' },
+					],
+				},
+				{
+					label: 'Reference',
+					items: [{ label: 'Overview', slug: 'reference/overview' }],
+				},
+			],
+		}),
+	],
+});

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

@@ -0,0 +1,24 @@
+# docs-app — a multi-page documentation SITE (Astro Starlight): sidebar,
+# client-side search, and agent-readable llms.txt / llms-full.txt.
+#
+# It is a static site WITH a build step, served at the entity ROOT. Multi-file +
+# build → deploy is async (like a runtime app) and needs the LOCAL edition
+# (Claude Desktop/Code or the CLI); the hosted MCP cannot build it. Deploy with
+# `grid plug` on the linked folder. `llms.txt` and `llms-full.txt` are generated
+# automatically at the site root.
+#
+# For a quick single-page doc with no build, use the `docs-site` archetype instead.
+name: docs-app
+services:
+  site:
+    type: static
+    path: /
+    node_version: "22"
+    # source.path: . tells the platform the project is at the folder ROOT (not
+    # under services/site/). Required for a single root-level build like this;
+    # without it the build looks for services/<name>/ and fails.
+    source:
+      path: .
+    build:
+      command: "npm run build"
+      output: "dist"

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

@@ -0,0 +1,40 @@
+# docs-app template
+
+A multi-page documentation **site** for CloudGrid, built with
+[Astro Starlight](https://starlight.astro.build): sidebar navigation,
+client-side full-text search, and agent-readable `llms.txt` / `llms-full.txt`
+generated on every build.
+
+Use this when the docs are more than one page and you will keep editing them.
+For a quick single-page doc baked into one HTML file (instant, works on the
+hosted MCP), use the `docs-site` archetype instead.
+
+## Layout
+
+```
+package.json          Astro + Starlight + starlight-llms-txt
+astro.config.mjs      site config, sidebar, the llms.txt plugin
+tsconfig.json
+cloudgrid.yaml        static + build block, served at the entity root
+src/content.config.ts
+src/content/docs/
+  index.mdx           the home page
+  guides/getting-started.md
+  reference/overview.md
+```
+
+## Build + deploy
+
+This is a **built** static site, so it needs the local edition (Claude
+Desktop/Code) or the CLI — the hosted MCP cannot build it.
+
+```sh
+npm install
+npm run build      # produces dist/ (and dist/llms.txt, dist/llms-full.txt)
+grid plug          # deploys the folder; live in ~30s at the entity root
+```
+
+`cloudgrid.yaml` declares a single `static` service with a `build:` block
+(`npm run build` → `dist`). The deploy is async — poll to the live URL, then
+return it. Add pages under `src/content/docs/` and list them in the
+`sidebar` in `astro.config.mjs`.

package/src/corpus/templates/docs-app/package.json

@@ -0,0 +1,19 @@
+{
+  "name": "docs-app",
+  "type": "module",
+  "version": "0.1.0",
+  "description": "A multi-page documentation site on CloudGrid (Astro Starlight + agent-readable llms.txt).",
+  "scripts": {
+    "dev": "astro dev",
+    "build": "astro build",
+    "preview": "astro preview"
+  },
+  "dependencies": {
+    "@astrojs/starlight": "^0.41.3",
+    "astro": "^7.0.2",
+    "sharp": "^0.34.5"
+  },
+  "devDependencies": {
+    "starlight-llms-txt": "^0.11.0"
+  }
+}

package/src/corpus/templates/docs-app/src/content/docs/guides/getting-started.md

@@ -0,0 +1,18 @@
+---
+title: Getting started
+description: Install and run My Project.
+---
+
+Replace this guide with real getting-started steps for your project.
+
+## Install
+
+```sh
+# however your users install it
+npm install my-project
+```
+
+## First run
+
+Explain the smallest useful thing a reader can do, then link them to the
+[reference](/reference/overview/) for the details.

package/src/corpus/templates/docs-app/src/content/docs/index.mdx

@@ -0,0 +1,22 @@
+---
+title: My Project
+description: Documentation for My Project. Replace this with a one-line summary.
+---
+
+import { Card, CardGrid, LinkCard } from '@astrojs/starlight/components';
+
+Welcome to the documentation for **My Project**. Replace this page with your own
+introduction: what the project is, who it is for, and where to start.
+
+<CardGrid>
+	<LinkCard title="Getting started" href="/guides/getting-started/" description="Install and run My Project in a few minutes." />
+	<LinkCard title="Reference" href="/reference/overview/" description="Full reference for the API and configuration." />
+</CardGrid>
+
+## What is here
+
+- **Guides** — task-oriented walkthroughs.
+- **Reference** — the complete, look-it-up documentation.
+
+The sidebar and search box are generated automatically. Add pages under
+`src/content/docs/` and list them in `astro.config.mjs`.

package/src/corpus/templates/docs-app/src/content/docs/reference/overview.md

@@ -0,0 +1,13 @@
+---
+title: Reference overview
+description: The complete reference for My Project.
+---
+
+Replace this with your reference material — API, configuration, CLI flags, and so
+on. Reference pages are for looking things up, not for reading top to bottom.
+
+## Configuration
+
+| Option | Default | What it does |
+| --- | --- | --- |
+| `example` | `false` | Replace with a real option. |

package/src/corpus/templates/docs-app/src/content.config.ts

@@ -0,0 +1,7 @@
+import { defineCollection } from 'astro:content';
+import { docsLoader } from '@astrojs/starlight/loaders';
+import { docsSchema } from '@astrojs/starlight/schema';
+
+export const collections = {
+	docs: defineCollection({ loader: docsLoader(), schema: docsSchema() }),
+};

package/src/corpus/templates/docs-app/tsconfig.json

@@ -0,0 +1,5 @@
+{
+  "extends": "astro/tsconfigs/strict",
+  "include": [".astro/types.d.ts", "**/*"],
+  "exclude": ["dist"]
+}

package/src/corpus/troubleshooting/deploy-errors.md

@@ -10,7 +10,7 @@ Match the symptom to the row, apply the fix, and stop. Do not retry permutations
 
 | Symptom | Cause | Fix |
 | --- | --- | --- |
-| `SCOPE_INVALID` on deploy | Known platform issue, not your request | Deploy from a terminal with `grid plug <path>` or `cloudgrid plug <path>`. Do not retry flag or path permutations. If no terminal is available, tell the user it is a known issue that needs the CLI. |
+| `SCOPE_INVALID` on deploy | Known platform issue, not your request | Deploy from a terminal with `grid plug <path>`. Do not retry flag or path permutations. If no terminal is available, tell the user it is a known issue that needs the CLI. |
 | `429` anonymous cap reached | Anonymous deploy quota is exhausted | Stop. Do not log in to work around it and do not retry today. Tell the user the cap is reached; they can try later or sign in for a higher limit as a deliberate choice. |
 | `409 EDIT_REJECTED` on re-plug | The target entity is archived or expired | Do not silently create a new entity — that mints a new URL and orphans the shared one. Ask the user before creating a fresh entity. |
 | `401` on an anonymous edit | Missing or stale `owner_token` | Re-plug with the `owner_token` from the last deploy of that entity. Each anonymous edit returns a fresh token — store the new one and use it next time. |

package/src/corpus/usage.md

@@ -15,7 +15,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
+  drops (into your org), run `grid login` once, or use the `login` skill / the
   `grid_login` MCP tool.
 
 ---

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

@@ -115,7 +115,7 @@ response is `status: "building"` with a `poll_url` / entity, NOT a live URL yet.
 
 Give the user the live app URL — that is the deliverable. To iterate, re-plug
 the SAME entity (`target_entity_id`) so it updates the same URL. Runtime re-plug
-uses the CLI path (`cloudgrid plug` in the linked folder), per the plug
+uses the CLI path (`grid plug` in the linked folder), per the plug
 description.
 
 Keep it honest: async build, local-edition only, credentials injected by the

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

@@ -0,0 +1,120 @@
+---
+name: docs-app
+when: multi-page documentation SITE, developer docs portal, knowledge base, help center you'll keep editing — docs with a sidebar, full-text search, and agent-readable llms.txt, built with Astro/Starlight. SEPARATE content files, not one page. For a quick single-page doc baked into one HTML file (instant, works on the hosted MCP), use docs-site instead. For an interactive REST API endpoint reference, use api-docs.
+needs: none
+deploy: static build
+editions: local
+capabilities_note: a built, multi-page static documentation site (Astro Starlight) — sidebar nav, client-side search, and llms.txt / llms-full.txt generated on every build. No infrastructure (no needs:). Because it BUILDS from multiple files, it deploys async and needs the local edition; the hosted MCP cannot build it. Served at the entity root via grid_plug.
+summary: Scaffold an Astro Starlight docs site from the docs-app template, fill in the content, build it, deploy the folder with grid_plug (async → poll to a live URL), then ask the user what visibility they want. llms.txt / llms-full.txt are generated automatically.
+---
+
+# Workflow: docs-app
+
+The user wants a **real, multi-page documentation site** they will keep editing —
+a docs portal / knowledge base with a sidebar, search, and agent-readable
+`llms.txt`. That is a **built static site** (Astro Starlight), not a single page.
+
+Choose the right archetype first:
+- **Quick, single-page doc**, or you're on the **hosted MCP** (Claude Web) → use
+  `docs-site` (one self-contained HTML file, instant inspiration, any edition).
+- **Interactive REST API endpoint reference** → use `api-docs`.
+- **Multi-page site you'll maintain (sidebar + search + llms.txt)** → `docs-app`,
+  this workflow.
+
+Be honest that a `docs-app` deploy is a build (async, not instant like a single
+HTML drop) and that it needs the local edition.
+
+## 1. Edition check FIRST (hard gate)
+
+A docs-app is built (`npm run build`) from multiple files, so it requires the
+**local edition** (Claude Desktop / Claude Code) or the CLI — the grid folder-plugs
+and builds your project.
+
+- **Hosted edition (Claude Web / hosted MCP):** you CANNOT build a multi-file
+  site. Tell the user plainly: "A multi-page docs site needs the local edition
+  (Claude Desktop/Code) or the CloudGrid CLI; the hosted edition can only publish
+  a single page — I can make you a one-page `docs-site` instead." Offer the
+  `docs-site` fallback; do not try to build here.
+- **Local edition:** continue.
+
+## 2. Auth + grid
+
+1. Ensure signed in: `grid_login_status`; if not, `grid_login`.
+2. A grid is required. Respect the grid picker: if the user has more than one
+   grid, ask which to use; do not assume a target.
+
+## 3. Scaffold
+
+`grid_init` an app `<name>`. `init` creates the entity + `.cloudgrid/link.json`
+and writes a `cloudgrid.yaml`. Then fetch the template:
+`grid_fetch("template", "docs-app")` — a minimal Astro Starlight project:
+
+```
+package.json          Astro + Starlight + starlight-llms-txt
+astro.config.mjs      site config, sidebar, the llms.txt plugin
+tsconfig.json
+cloudgrid.yaml        static + build block, served at the entity root
+src/content.config.ts
+src/content/docs/index.mdx + guides/ + reference/
+```
+
+Write those files into the linked folder (keep the project at the folder root —
+this is a static build, so unlike a `node`/`nextjs` service the project is NOT
+nested under `services/<name>/`).
+
+## 4. Fill in the content
+
+- Set `title`, `description`, and the `starlightLlmsTxt({ projectName, description })`
+  values in `astro.config.mjs` to the user's project.
+- Write the actual pages under `src/content/docs/` (Markdown/MDX, one file per
+  page) and list them in the `sidebar` array in `astro.config.mjs`.
+- Keep internal links root-relative (`/guides/getting-started/`). The site is
+  served at the entity **root**, so do NOT set a `base`.
+- Do not add external CDN scripts, fonts, or stylesheets.
+
+## 5. cloudgrid.yaml
+
+The template already declares the right shape — a single `static` service with a
+build step, served at the root:
+
+```yaml
+name: my-docs
+services:
+  site:
+    type: static
+    path: /
+    node_version: "22"
+    source:
+      path: .          # project is at the folder root, not under services/site/
+    build:
+      command: "npm run build"
+      output: "dist"
+```
+
+`source.path: .` is REQUIRED for this root-level build — without it the platform
+looks for `services/site/` and fails with "Service directory not found". No
+`needs:` — a docs site has no infrastructure. Never author an active `needs:` and
+`requires:` together (the validator rejects the combo).
+
+## 6. Build + deploy (async)
+
+Deploy the folder with `grid_plug`. The platform (Cloud Build) runs `npm run
+build` for you and serves the `dist/` output — you do NOT need to build first. A build deploy is **ASYNC**: the first response is
+`status: "building"` with a `poll_url` / entity, NOT a live URL yet.
+- Poll `grid_status` (or the returned poll_url) until the entity is live.
+- Surface a liveness signal while it builds — never a bare silent wait.
+- Only once it is live, return the deployed URL.
+
+## 7. Return the live URL, point at llms.txt, and ASK visibility
+
+- Give the user the live docs URL — that is the deliverable.
+- Point out the agent-readable docs: `<url>/llms.txt` (index) and
+  `<url>/llms-full.txt` (full content), generated automatically.
+- This is a NEW deploy, so ASK the user who should be able to open it (private /
+  a space / your grid / anyone with the link / anyone signed in) and set their
+  choice with `grid_visibility`. Do not pick the visibility for them.
+
+To iterate, edit the content and re-plug the SAME entity (`target_entity_id`) so
+it updates the same URL.
+
+Keep it honest: multi-file build, async deploy, local-edition only.

package/src/corpus/workflows/docs-site.md

@@ -1,6 +1,6 @@
 ---
 name: docs-site
-when: documentation site, docs, developer docs, guide, manual, knowledge base, help center (static, content baked in). For an interactive API endpoint reference, use api-docs instead.
+when: single-page docs, a quick guide/manual/README-as-a-page, small knowledge base (static, content baked into ONE HTML file). For a MULTI-PAGE site you'll keep editing (sidebar + full-text search + llms.txt, built with Starlight), use docs-app instead. For an interactive API endpoint reference, use api-docs instead.
 needs: none
 deploy: inspiration
 editions: all

package/src/index.js

@@ -15,6 +15,9 @@ import {
   writeCredentials,
   credentialsPath,
 } from "./auth.js";
+import { randomUUID } from "node:crypto";
+import { createSessionLogger } from "./session-logger.js";
+import { createSink } from "./log-sink.js";
 
 const { version } = JSON.parse(readFileSync(new URL("../package.json", import.meta.url)));
 
@@ -28,6 +31,18 @@ const ctx = {
   savedLocationNote: () => `Credentials saved to ${credentialsPath()}.`,
 };
 
+// QA session log (dark by default: no CLOUDGRID_QA_SLACK_WEBHOOK → null → no-op).
+// The stdio process IS the session. user_request is forwarded by Claude Code via
+// CLOUDGRID_USER_REQUEST when present.
+ctx.sessionId = `cli-${randomUUID()}`;
+ctx.logger = createSessionLogger({
+  transport: "stdio",
+  sessionId: ctx.sessionId,
+  sink: createSink(process.env),
+  ctx,
+  userRequest: process.env.CLOUDGRID_USER_REQUEST || null,
+});
+
 const server = new McpServer({ name: "cloudgrid-mcp", version });
 registerTools(server, ctx);
 
@@ -45,3 +60,17 @@ server.server.oninitialized = () => {
 
 const transport = new StdioServerTransport();
 await server.connect(transport);
+
+// Flush the QA log once on shutdown if nothing triggered a flush during the
+// session (abandoned / build-only session). Best-effort — a hard kill may cut
+// delivery short; that is acceptable for QA. Guarded so it never crashes exit.
+let shuttingDown = false;
+async function flushAndExit(code) {
+  if (shuttingDown) return;
+  shuttingDown = true;
+  try { await ctx.logger?.flush("abandoned"); } catch { /* never */ }
+  process.exit(code);
+}
+process.on("SIGINT", () => flushAndExit(0));
+process.on("SIGTERM", () => flushAndExit(0));
+process.on("beforeExit", () => { ctx.logger?.flush("abandoned").catch(() => {}); });

package/src/log-sink.js

@@ -0,0 +1,45 @@
+// src/log-sink.js
+// Pluggable delivery for the QA session log. Default sink posts to a Slack
+// incoming webhook. Dark by default: createSink returns null when the webhook
+// env var is unset, so the logger factory returns null and capture is a no-op.
+//
+// NOTE: Slack incoming webhooks cannot upload file attachments — only a JSON
+// message body. We post the summary + the full log inside a fenced code block.
+// True file attachment (files.upload) needs a bot token and is deferred.
+const SLACK_TEXT_LIMIT = 38000; // headroom under Slack's ~40k message cap
+
+export class SlackWebhookSink {
+  constructor(url, { fetchImpl } = {}) {
+    this.url = url;
+    this.fetchImpl = fetchImpl || globalThis.fetch;
+  }
+  async send({ filename, summary, text }) {
+    try {
+      const body = String(text || "");
+      const clipped = body.length > SLACK_TEXT_LIMIT
+        ? body.slice(0, SLACK_TEXT_LIMIT) + "\n…(truncated)"
+        : body;
+      const message = `*${filename}* — ${summary}\n\`\`\`\n${clipped}\n\`\`\``;
+      // Bound the POST so a hung webhook host can't stall flushAndExit on
+      // SIGINT/SIGTERM. Abort after 5s; clear the timer once the fetch settles.
+      const ac = new AbortController();
+      const timer = setTimeout(() => ac.abort(), 5000);
+      try {
+        await this.fetchImpl(this.url, {
+          method: "POST",
+          headers: { "content-type": "application/json" },
+          body: JSON.stringify({ text: message }),
+          signal: ac.signal,
+        });
+      } finally {
+        clearTimeout(timer);
+      }
+    } catch { /* delivery is best-effort; never throws */ }
+  }
+}
+
+export function createSink(env = process.env) {
+  const url = env.CLOUDGRID_QA_SLACK_WEBHOOK;
+  if (!url) return null;
+  return new SlackWebhookSink(url);
+}