@cloudgrid-io/mcp 0.11.2 → 0.13.0

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

@@ -0,0 +1,30 @@
+# Template: api-docs (static)
+
+A single self-contained HTML API reference: a sidebar endpoint list, per-endpoint method badges (GET / POST / PUT / DELETE), a params table, and request / response examples in code blocks. **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", "api-docs")` 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: api-docs
+services:
+  web:
+    type: static
+    path: /
+```

package/src/corpus/templates/api-service/README.md

@@ -0,0 +1,87 @@
+# api-service template — REST/JSON API on Node + Mongo
+
+A minimal but real, deployable backend API. It is a plain Node `http` service
+(no web UI, no framework) that serves a small REST resource (`/items`) backed by
+the grid-shared MongoDB, so data survives refresh and is shared across sessions.
+This is the plain-service sibling of `app-with-data` — reach for it when the user
+wants a backend/API, not a full web app.
+
+## How the grid gives you a database
+
+You do **not** provision a database or set a connection string. In
+`cloudgrid.yaml` you declare `needs: { database: true }`, and the grid:
+
+- provisions shared Mongo for the service, and
+- injects the connection string as the **`DATABASE_MONGODB_URL`** environment
+  variable (plus the legacy `MONGODB_URL` alias) — at dev-time (`grid dev`) and
+  at runtime (after `grid plug`).
+
+The service reads it via `process.env.DATABASE_MONGODB_URL` (with a legacy
+`process.env.MONGODB_URL` fallback) inside `getDb` — **lazily, never at module
+top level.** A top-level read throws at node startup, before the grid injects
+the var, and crashes the service. Never hardcode a connection string; never
+commit a secret.
+
+> **Declare `needs: { database: true }` (the canonical shape).** The deployer
+> provisions Mongo and injects `DATABASE_MONGODB_URL` (plus the legacy
+> `MONGODB_URL` alias). `requires:` is the deprecated v1 alias — don't author new
+> yaml with it, and never set `needs:` and `requires:` together (the validator
+> rejects the combination).
+
+## Service layout
+
+Service code lives under **`services/api/`**, not the template root. `path:` in
+`cloudgrid.yaml` is the URL mount, not the filesystem path — the service named
+`api` means the CLI looks for `services/api/`. Files at the root fail with
+`Error: Service directory not found: …/services/api`.
+
+The server listens on `process.env.PORT || 8080` — the grid injects `PORT`; the
+`8080` default is for local runs.
+
+## Run locally
+
+```bash
+cd services/api && npm install && cd -
+grid dev          # runs the service with DATABASE_MONGODB_URL injected against dev Mongo
+```
+
+Then hit it:
+
+```bash
+curl -s localhost:8080/items
+curl -s -XPOST localhost:8080/items -H 'content-type: application/json' -d '{"text":"hello"}'
+```
+
+## Deploy
+
+```bash
+grid plug         # builds + deploys the folder (async — poll status until live)
+```
+
+A runtime deploy is asynchronous: `plug` returns `status: building`; poll status
+until the service is live, then use the returned live URL. Re-plug the same
+entity to update the same URL.
+
+## File tree
+
+```
+cloudgrid.yaml                 # name + services.api (node) + needs: { database: true }
+services/api/package.json      # type: module, main src/index.js, mongodb driver only
+services/api/src/index.js      # Node http server on PORT||8080; /items GET/POST/DELETE on Mongo
+```
+
+## Endpoints
+
+| Method | Path              | Description                          |
+|--------|-------------------|--------------------------------------|
+| GET    | `/`               | service banner + endpoint list       |
+| GET    | `/items`          | list items, newest first             |
+| POST   | `/items`          | create an item; body `{ "text": … }` |
+| DELETE | `/items?id=<id>`  | remove an item by id                 |
+
+## Adapt it
+
+- Rename the `items` collection and change the document fields to your resource.
+- Add more routes/resources as the API grows.
+- Return clear JSON errors (`{ "error": … }`) with the right status codes.
+- Add more `needs:` (e.g. `cache: true`) only if you actually use them.

package/src/corpus/templates/api-service/cloudgrid.yaml

@@ -0,0 +1,18 @@
+# Rename this service. The grid injects the DB connection string as an
+# environment variable at runtime — do NOT set it yourself, and never commit a
+# connection string or secret.
+#
+# `needs: { database: true }` is the canonical, recommended shape. The deployer
+# provisions Mongo and injects DATABASE_MONGODB_URL (plus the legacy MONGODB_URL
+# alias). `requires:` is the deprecated v1 alias — don't author new yaml with it,
+# and never set `needs:` and `requires:` together (the validator rejects it).
+#
+# This is a plain Node HTTP service (type: node), not a web UI. Service code lives
+# under services/api/ — `path:` is the URL mount, not the filesystem path.
+name: my-api
+services:
+  api:
+    type: node
+    path: /
+needs:
+  database: true

package/src/corpus/templates/api-service/index.md

@@ -0,0 +1,225 @@
+# Template: api-service (Node HTTP + Mongo REST API)
+
+A minimal but real, deployable backend API. A plain Node `http` server (no web
+UI, no framework) serving a small REST resource (`/items`) backed by the
+grid-shared MongoDB. Data survives refresh and is shared across sessions. This is
+the plain-service sibling of `app-with-data` — use it when the user wants a
+backend/API, not a full web app.
+
+**Key rules (all proven by a real end-to-end deploy):**
+
+1. **Service code MUST live under `services/<name>/`, not the repo/template
+   root.** `path:` in `cloudgrid.yaml` is the URL mount, NOT the filesystem path.
+   The service named `api` → the CLI looks for `services/api/`. Files at the root
+   fail with `Error: Service directory not found: …/services/api`.
+2. **Read the DB connection string LAZILY (inside the getter), never at module
+   top level.** The grid injects it as the `DATABASE_MONGODB_URL` environment
+   variable (plus the legacy `MONGODB_URL` alias) at dev-time and runtime; the
+   service reads `process.env.DATABASE_MONGODB_URL || process.env.MONGODB_URL`
+   inside `getClient`. A top-level `const uri = process.env.DATABASE_MONGODB_URL;
+   if (!uri) throw` crashes node startup before the grid injects the var. Never
+   hardcode a connection string; never commit a secret.
+3. **Declare the datastore with `needs: { database: true }`.** This is the
+   canonical shape — the deployer provisions Mongo and injects
+   `DATABASE_MONGODB_URL` (plus the legacy `MONGODB_URL` alias). `requires:` is
+   the deprecated v1 alias; don't author new yaml with it, and never set `needs:`
+   and `requires:` together (the validator rejects the combination).
+4. **Listen on `process.env.PORT || 8080`.** The grid injects `PORT`; the `8080`
+   default is for local runs.
+
+Write these files into the scaffolded app folder — the service code goes under
+`services/api/` — adapt the resource/fields to the user's API, then `grid dev`
+(local) / `grid plug` (deploy, async — poll to a live URL).
+
+## File tree
+
+```
+cloudgrid.yaml                 # name + services.api (node) + needs: { database: true }
+services/api/package.json      # type: module, main src/index.js, mongodb driver only
+services/api/src/index.js      # Node http server on PORT||8080; /items GET/POST/DELETE on Mongo
+```
+
+## cloudgrid.yaml
+
+```yaml
+# Rename this service. The grid injects the DB connection string as an
+# environment variable at runtime — do NOT set it yourself, and never commit a
+# connection string or secret.
+#
+# `needs: { database: true }` is the canonical, recommended shape. The deployer
+# provisions Mongo and injects DATABASE_MONGODB_URL (plus the legacy MONGODB_URL
+# alias). `requires:` is the deprecated v1 alias — don't author new yaml with it,
+# and never set `needs:` and `requires:` together (the validator rejects it).
+#
+# This is a plain Node HTTP service (type: node), not a web UI. Service code lives
+# under services/api/ — `path:` is the URL mount, not the filesystem path.
+name: my-api
+services:
+  api:
+    type: node
+    path: /
+needs:
+  database: true
+```
+
+> **Capability:** this template's need is `database: true`. The deployer
+> provisions Mongo and injects `DATABASE_MONGODB_URL` (plus the legacy
+> `MONGODB_URL` alias), so a service reading either var works. `requires:` is the
+> deprecated v1 alias — don't mix it with `needs:` (the validator rejects the
+> combination). See the capability-map for the full injection table.
+
+## services/api/package.json
+
+```json
+{
+  "name": "api",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "main": "src/index.js",
+  "scripts": {
+    "start": "node src/index.js"
+  },
+  "dependencies": {
+    "mongodb": "^6.12.0"
+  }
+}
+```
+
+## services/api/src/index.js
+
+```js
+// A minimal REST/JSON API backed by grid-shared Mongo.
+//
+// Endpoints (resource: `items`):
+//   GET    /items      -> list items (newest first)
+//   POST   /items      -> create an item; body { "text": string }
+//   DELETE /items?id=…  -> remove an item by id
+//   GET    /           -> tiny service banner + endpoint list
+//
+// The grid injects DATABASE_MONGODB_URL (plus the legacy MONGODB_URL alias) at
+// dev + runtime. The env var and Mongo client are resolved LAZILY (inside
+// getClient), never at module top level — a top-level read throws at node
+// startup, before the grid injects the var, and crashes the service. Never
+// hardcode a connection string; never commit a secret.
+import { createServer } from "node:http";
+import { MongoClient, ObjectId } from "mongodb";
+
+let clientPromise;
+
+function getClient() {
+  const uri = process.env.DATABASE_MONGODB_URL || process.env.MONGODB_URL;
+  if (!uri) {
+    throw new Error(
+      "DATABASE_MONGODB_URL is not set. The grid injects it automatically — run " +
+        "this service with `grid dev` locally, or deploy it with `grid plug`. Do " +
+        "not set it by hand.",
+    );
+  }
+  if (!clientPromise) clientPromise = new MongoClient(uri).connect();
+  return clientPromise;
+}
+
+async function items() {
+  const client = await getClient();
+  return client.db().collection("items");
+}
+
+function sendJson(res, status, body) {
+  const payload = JSON.stringify(body);
+  res.writeHead(status, {
+    "content-type": "application/json",
+    "content-length": Buffer.byteLength(payload),
+  });
+  res.end(payload);
+}
+
+function readBody(req) {
+  return new Promise((resolve) => {
+    let data = "";
+    req.on("data", (chunk) => {
+      data += chunk;
+      if (data.length > 1_000_000) req.destroy();
+    });
+    req.on("end", () => {
+      try {
+        resolve(data ? JSON.parse(data) : {});
+      } catch {
+        resolve(null);
+      }
+    });
+    req.on("error", () => resolve(null));
+  });
+}
+
+async function handle(req, res) {
+  const url = new URL(req.url, "http://localhost");
+  const { pathname } = url;
+
+  if (pathname === "/" && req.method === "GET") {
+    return sendJson(res, 200, {
+      service: "my-api",
+      endpoints: ["GET /items", "POST /items", "DELETE /items?id=<id>"],
+    });
+  }
+
+  if (pathname === "/items") {
+    const col = await items();
+
+    if (req.method === "GET") {
+      const list = await col.find({}).sort({ createdAt: -1 }).toArray();
+      return sendJson(
+        res,
+        200,
+        list.map((it) => ({ id: it._id.toString(), text: it.text, createdAt: it.createdAt })),
+      );
+    }
+
+    if (req.method === "POST") {
+      const body = await readBody(req);
+      if (body === null) return sendJson(res, 400, { error: "invalid JSON body" });
+      const text = typeof body.text === "string" ? body.text.trim() : "";
+      if (!text) return sendJson(res, 400, { error: "text is required" });
+      const doc = { text, createdAt: new Date() };
+      const { insertedId } = await col.insertOne(doc);
+      return sendJson(res, 201, { id: insertedId.toString(), ...doc });
+    }
+
+    if (req.method === "DELETE") {
+      const id = url.searchParams.get("id");
+      if (!id || !ObjectId.isValid(id)) {
+        return sendJson(res, 400, { error: "a valid id query param is required" });
+      }
+      const { deletedCount } = await col.deleteOne({ _id: new ObjectId(id) });
+      if (deletedCount === 0) return sendJson(res, 404, { error: "item not found" });
+      return sendJson(res, 200, { ok: true });
+    }
+
+    return sendJson(res, 405, { error: "method not allowed" });
+  }
+
+  return sendJson(res, 404, { error: "not found" });
+}
+
+const server = createServer((req, res) => {
+  handle(req, res).catch((err) => {
+    console.error(err);
+    if (!res.headersSent) sendJson(res, 500, { error: "internal server error" });
+  });
+});
+
+const port = process.env.PORT || 8080;
+server.listen(port, () => {
+  console.log(`api-service listening on :${port}`);
+});
+```
+
+## Adapt it
+
+- Rename the `items` collection in `services/api/src/index.js` to your resource
+  (`notes`, `orders`, `events`).
+- Change the document fields; add validation, owners, timestamps, statuses.
+- Add more routes/resources as the API grows.
+- Return clear JSON errors (`{ "error": … }`) with the right status codes.
+- Add more `needs:` (e.g. `cache: true`) only if you actually use them.
+- Run `grid dev` to test locally, `grid plug` to deploy (async — poll to live).

package/src/corpus/templates/api-service/services/api/package.json

@@ -0,0 +1,13 @@
+{
+  "name": "api",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "main": "src/index.js",
+  "scripts": {
+    "start": "node src/index.js"
+  },
+  "dependencies": {
+    "mongodb": "^6.12.0"
+  }
+}

package/src/corpus/templates/api-service/services/api/src/index.js

@@ -0,0 +1,132 @@
+// A minimal REST/JSON API backed by grid-shared Mongo.
+//
+// Endpoints (resource: `items`):
+//   GET    /items      -> list items (newest first)
+//   POST   /items      -> create an item; body { "text": string }
+//   DELETE /items?id=…  -> remove an item by id
+//   GET    /           -> tiny service banner + endpoint list
+//
+// The grid injects the connection string as the DATABASE_MONGODB_URL environment
+// variable (plus the legacy MONGODB_URL alias) at dev-time (`grid dev`) and
+// runtime (after `grid plug`). Read the canonical var first, fall back to the
+// legacy alias.
+//
+// The env var and Mongo client are resolved LAZILY (inside getDb), never at
+// module top level — a top-level read throws at node startup, before the grid
+// has injected the var, and crashes the service. Never hardcode a connection
+// string here and never commit a secret.
+import { createServer } from "node:http";
+import { MongoClient, ObjectId } from "mongodb";
+
+let clientPromise;
+
+function getClient() {
+  const uri = process.env.DATABASE_MONGODB_URL || process.env.MONGODB_URL;
+  if (!uri) {
+    throw new Error(
+      "DATABASE_MONGODB_URL is not set. The grid injects it automatically — run " +
+        "this service with `grid dev` locally, or deploy it with `grid plug` (the " +
+        "grid injects the DB connection string at runtime). Do not set it by hand.",
+    );
+  }
+  if (!clientPromise) clientPromise = new MongoClient(uri).connect();
+  return clientPromise;
+}
+
+async function items() {
+  const client = await getClient();
+  // The default DB comes from the connection-string path segment the grid injects.
+  return client.db().collection("items");
+}
+
+// ── Small JSON helpers ───────────────────────────────────────────────────────
+function sendJson(res, status, body) {
+  const payload = JSON.stringify(body);
+  res.writeHead(status, {
+    "content-type": "application/json",
+    "content-length": Buffer.byteLength(payload),
+  });
+  res.end(payload);
+}
+
+function readBody(req) {
+  return new Promise((resolve) => {
+    let data = "";
+    req.on("data", (chunk) => {
+      data += chunk;
+      if (data.length > 1_000_000) req.destroy(); // basic guard
+    });
+    req.on("end", () => {
+      try {
+        resolve(data ? JSON.parse(data) : {});
+      } catch {
+        resolve(null); // signal invalid JSON
+      }
+    });
+    req.on("error", () => resolve(null));
+  });
+}
+
+// ── Router ───────────────────────────────────────────────────────────────────
+async function handle(req, res) {
+  const url = new URL(req.url, "http://localhost");
+  const { pathname } = url;
+
+  if (pathname === "/" && req.method === "GET") {
+    return sendJson(res, 200, {
+      service: "my-api",
+      endpoints: ["GET /items", "POST /items", "DELETE /items?id=<id>"],
+    });
+  }
+
+  if (pathname === "/items") {
+    const col = await items();
+
+    if (req.method === "GET") {
+      const list = await col.find({}).sort({ createdAt: -1 }).toArray();
+      return sendJson(
+        res,
+        200,
+        list.map((it) => ({ id: it._id.toString(), text: it.text, createdAt: it.createdAt })),
+      );
+    }
+
+    if (req.method === "POST") {
+      const body = await readBody(req);
+      if (body === null) return sendJson(res, 400, { error: "invalid JSON body" });
+      const text = typeof body.text === "string" ? body.text.trim() : "";
+      if (!text) return sendJson(res, 400, { error: "text is required" });
+      const doc = { text, createdAt: new Date() };
+      const { insertedId } = await col.insertOne(doc);
+      return sendJson(res, 201, { id: insertedId.toString(), ...doc });
+    }
+
+    if (req.method === "DELETE") {
+      const id = url.searchParams.get("id");
+      if (!id || !ObjectId.isValid(id)) {
+        return sendJson(res, 400, { error: "a valid id query param is required" });
+      }
+      const { deletedCount } = await col.deleteOne({ _id: new ObjectId(id) });
+      if (deletedCount === 0) return sendJson(res, 404, { error: "item not found" });
+      return sendJson(res, 200, { ok: true });
+    }
+
+    return sendJson(res, 405, { error: "method not allowed" });
+  }
+
+  return sendJson(res, 404, { error: "not found" });
+}
+
+const server = createServer((req, res) => {
+  handle(req, res).catch((err) => {
+    // Never leak internals or a connection string in the response.
+    console.error(err);
+    if (!res.headersSent) sendJson(res, 500, { error: "internal server error" });
+  });
+});
+
+// The grid injects PORT; default to 8080 for local runs.
+const port = process.env.PORT || 8080;
+server.listen(port, () => {
+  console.log(`api-service listening on :${port}`);
+});

package/src/corpus/templates/changelog/README.md

@@ -0,0 +1,27 @@
+# changelog
+
+A single self-contained HTML changelog / release-notes page: reverse-chronological versioned entries, each with a date and tagged change items (added / fixed / changed / removed).
+
+Static inspiration — a single self-contained `index.html` (inline CSS and JS,
+no external CDNs). It deploys instantly via `gridctl_drop` and works on every
+CloudGrid edition, including hosted.
+
+## Fill it in
+
+Fetch the template with `gridctl_fetch("template", "changelog")`, then replace the
+placeholders:
+
+   - The product name and page intro.
+   - One entry per release, newest first: version, date, and a list of changes.
+   - Each change carries a tag pill — added, fixed, changed, or removed — set by its CSS class.
+
+Keep it a single self-contained HTML file. Do not add external scripts,
+stylesheets, fonts, or large embedded media.
+
+## Deploy
+
+- Hosted MCP edition: call the drop tool with the HTML.
+- Local MCP / CLI edition: write the HTML to a file and run `gridctl plug`.
+
+It deploys as an inspiration and returns a live share URL right away. Re-deploy
+with the same entity id to update the same URL.

package/src/corpus/templates/changelog/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: changelog
+services:
+  web:
+    type: static
+    path: /

package/src/corpus/templates/changelog/index.html

@@ -0,0 +1,80 @@
+<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8" />
+<meta name="viewport" content="width=device-width, initial-scale=1" />
+<title>{{PRODUCT_NAME}} changelog</title>
+<style>
+  :root {
+    --bg: #0b0f17; --panel: #121826; --fg: #e8edf5; --muted: #9aa7bd;
+    --accent: #5b8cff; --border: #223049;
+    --added: #34d399; --fixed: #5b8cff; --changed: #fbbf24; --removed: #f87171;
+  }
+  * { box-sizing: border-box; margin: 0; padding: 0; }
+  body {
+    background: var(--bg); color: var(--fg);
+    font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, Helvetica, Arial, sans-serif;
+    -webkit-font-smoothing: antialiased; line-height: 1.6;
+  }
+  .wrap { max-width: 720px; margin: 0 auto; padding: clamp(1.5rem, 5vw, 3.5rem) 1.25rem; }
+  header { margin-bottom: 3rem; }
+  header h1 { font-size: clamp(2rem, 5vw, 2.8rem); letter-spacing: -0.02em; margin-bottom: 0.5rem; }
+  header p { color: var(--muted); }
+
+  .entry { position: relative; padding-left: 1.5rem; padding-bottom: 2.5rem; border-left: 2px solid var(--border); }
+  .entry:last-child { border-left-color: transparent; padding-bottom: 0; }
+  .entry::before { content: ""; position: absolute; left: -7px; top: 4px; width: 12px; height: 12px; border-radius: 50%; background: var(--accent); border: 3px solid var(--bg); }
+  .entry .meta { display: flex; align-items: baseline; gap: 0.75rem; margin-bottom: 1rem; flex-wrap: wrap; }
+  .entry .version { font-size: 1.35rem; font-weight: 700; letter-spacing: -0.01em; }
+  .entry .date { color: var(--muted); font-size: 0.9rem; }
+  .entry ul { list-style: none; display: grid; gap: 0.6rem; }
+  .entry li { display: flex; gap: 0.65rem; align-items: baseline; color: var(--fg); }
+  .tag { flex: none; font-size: 0.7rem; font-weight: 700; text-transform: uppercase; letter-spacing: 0.04em;
+    padding: 0.15rem 0.5rem; border-radius: 6px; min-width: 62px; text-align: center; }
+  .tag.added { color: var(--added); background: rgba(52,211,153,0.12); }
+  .tag.fixed { color: var(--fixed); background: rgba(91,140,255,0.12); }
+  .tag.changed { color: var(--changed); background: rgba(251,191,36,0.12); }
+  .tag.removed { color: var(--removed); background: rgba(248,113,113,0.12); }
+  .entry li span.text { color: var(--muted); }
+  footer { color: var(--muted); font-size: 0.85rem; margin-top: 2rem; text-align: center; }
+</style>
+</head>
+<body>
+  <div class="wrap">
+    <header>
+      <h1>{{PRODUCT_NAME}} changelog</h1>
+      <p>{{CHANGELOG_INTRO}}</p>
+    </header>
+
+    <!-- ENTRIES_START -->
+    <!-- Newest release first. Each li: <span class="tag TYPE">TYPE</span>
+         where TYPE is added / fixed / changed / removed. -->
+    <div class="entry">
+      <div class="meta">
+        <span class="version">{{ENTRY_1_VERSION}}</span>
+        <span class="date">{{ENTRY_1_DATE}}</span>
+      </div>
+      <ul>
+        <li><span class="tag added">Added</span><span class="text">{{ENTRY_1_ITEM_1}}</span></li>
+        <li><span class="tag fixed">Fixed</span><span class="text">{{ENTRY_1_ITEM_2}}</span></li>
+        <li><span class="tag changed">Changed</span><span class="text">{{ENTRY_1_ITEM_3}}</span></li>
+      </ul>
+    </div>
+
+    <div class="entry">
+      <div class="meta">
+        <span class="version">{{ENTRY_2_VERSION}}</span>
+        <span class="date">{{ENTRY_2_DATE}}</span>
+      </div>
+      <ul>
+        <li><span class="tag added">Added</span><span class="text">{{ENTRY_2_ITEM_1}}</span></li>
+        <li><span class="tag removed">Removed</span><span class="text">{{ENTRY_2_ITEM_2}}</span></li>
+      </ul>
+    </div>
+    <!-- Add more .entry blocks below, newest first. -->
+    <!-- ENTRIES_END -->
+
+    <footer>{{FOOTER_TEXT}}</footer>
+  </div>
+</body>
+</html>

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

@@ -0,0 +1,30 @@
+# Template: changelog (static)
+
+A single self-contained HTML changelog / release-notes page: reverse-chronological versioned entries, each with a date and tagged change items (added / fixed / changed / removed). **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", "changelog")` 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: changelog
+services:
+  web:
+    type: static
+    path: /
+```