@cloudgrid-io/mcp 0.10.0 → 0.11.2

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

@@ -1,7 +1,11 @@
 ---
 name: app-with-data
-when: The user wants an app that SAVES or PERSISTS data, shares state across users/sessions, has accounts/login, stores submissions, or needs a backend/API/database — e.g. a to-do list, a CRUD dashboard, a form that stores entries, a guestbook.
-summary: Build a real persistent Next.js + Mongo runtime app on the grid — edition-gate first, scaffold, put the app under services/web/, wire process.env.MONGODB_URL lazily, declare requires:[mongodb] (not needs:), deploy async, poll to a live URL.
+when: to-do, task list, notes app, guestbook, CRUD app, form that SAVES/STORES submissions, anything that SAVES or PERSISTS data or shares state across users/sessions, sign-in/accounts, a backend/API/database — e.g. a to-do list, a CRUD dashboard, a form that stores entries, a guestbook. Needs a database → runtime → local edition.
+needs: database
+deploy: runtime
+editions: local
+capabilities_note: persistent — needs a database (Mongo). Runtime app, async build, local edition only. Declare the canonical `needs: { database: true }`; the deployer injects DATABASE_MONGODB_URL (+legacy MONGODB_URL).
+summary: Build a real persistent Next.js + Mongo runtime app on the grid — edition-gate first, scaffold, put the app under services/web/, wire process.env.DATABASE_MONGODB_URL (legacy MONGODB_URL fallback) lazily, declare needs:{database:true} (not requires:), deploy async, poll to a live URL.
 ---
 
 # Workflow: app-with-data
@@ -44,7 +48,7 @@ the entity + `.cloudgrid/link.json` and writes a `cloudgrid.yaml` with an EMPTY
 `services: {}`. `plug` needs a linked directory, so run `init` FIRST.
 
 You then do two things: (a) write the app under **`services/web/`**, and (b) fill
-in `cloudgrid.yaml` to the shape below (`services.web` + `requires: [mongodb]`).
+in `cloudgrid.yaml` to the shape below (`services.web` + `needs: { database: true }`).
 
 ## 4. Add the datastore + wire Mongo
 
@@ -59,27 +63,28 @@ in `cloudgrid.yaml` to the shape below (`services.web` + `requires: [mongodb]`).
      web:
        type: nextjs
        path: /
-   requires:
-     - mongodb        # alias: db
-     # - redis: private   # OPTIONAL — add only if the app needs Redis
+   needs:
+     database: true
+     # cache: true      # OPTIONAL — add only if the app needs Redis
    ```
-   **Declare the datastore with `requires: [mongodb]` (NOT `needs:`)** — see the
-   yaml comment in the template. The CLI warns `requires:` is deprecated, but the
-   deployer only injects `MONGODB_URL` from `requires:`; `needs:` builds fine but
-   injects NO DB connection (every request 500s). Keep `requires:` until the
-   deployer honors `needs:`.
+   **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) at dev-time and
+   runtime. `requires:` is the deprecated v1 alias; don't author new yaml with it,
+   and never set `needs:` and `requires:` together (the validator rejects it).
 2. Fetch the template for the Mongo wiring + CRUD shape:
    `gridctl_fetch("template", "app-with-data")`. It is a minimal, real
    Next.js + `mongodb`-driver to-do app under `services/web/`: a lazy client in
    `services/web/lib/db.js`, an App-Router GET/POST/DELETE route on a `todos`
    collection, and a page.
 3. Adapt it to the user's app (rename the collection, change the fields, adjust
-   the UI). **Read the database from `process.env.MONGODB_URL`** — the grid
-   injects that env var at dev-time and runtime. Never hardcode a connection
-   string; never commit a secret.
-   - **Put the DB connection behind a lazy getter — never read
-     `process.env.MONGODB_URL` at module top level, or `next build` fails** (the
-     module is imported for route analysis before the grid injects the var).
+   the UI). **Read the database from `process.env.DATABASE_MONGODB_URL`** (falling
+   back to the legacy `process.env.MONGODB_URL`) — the grid injects those env vars
+   at dev-time and runtime. Never hardcode a connection string; never commit a
+   secret.
+   - **Put the DB connection behind a lazy getter — never read the connection
+     string at module top level, or `next build` fails** (the module is imported
+     for route analysis before the grid injects the var).
    - (Optional) fetch `gridctl_fetch("example", "app-with-data")` for a slightly
      richer filled reference to imitate.
 
@@ -92,7 +97,9 @@ and sanity-check before deploying. Don't require it.
 
 - API keys / secrets → `gridctl_secrets`.
 - Non-secret config → `gridctl_env`.
-- Do **NOT** set `MONGODB_URL` or `REDIS_URL` yourself — the grid injects them.
+- Do **NOT** set the DB/cache connection vars yourself (`DATABASE_MONGODB_URL`,
+  `CACHE_REDIS_URL`, or their legacy `MONGODB_URL` / `REDIS_URL` aliases) — the
+  grid injects them.
 
 ## 7. Deploy (async)
 

package/src/corpus/workflows/dashboard.md

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

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

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

package/src/corpus/workflows/presentation.md

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

package/src/corpus/workflows/report.md

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

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

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

package/src/tools.js

@@ -89,6 +89,8 @@ Operating rules:
 9. To modify an existing drop when you don't already have its HTML in context, first call gridctl_source to fetch the current HTML, apply your change, then call gridctl_drop/gridctl_plug with target_entity_id (the drop's entity_id) to update the SAME URL in place. Do not ask the user to paste the HTML back.
 10. Publishing a heavy or local file: in the local edition use the path parameter so it is read from disk (no inline size limit); never base64-encode HTML and never pass a file path (or an @-prefixed path) as html. If a drop looks empty, use gridctl_source to check what was actually published, then re-plug with the real HTML/path and target_entity_id.
 11. Persistence check: if the user needs to SAVE data, share state across users/sessions, log in, or store submissions, that's a runtime app-with-data (Mongo-backed), NOT a static page — static templates keep state only in memory and lose it on refresh. Use the app-with-data workflow. This requires the LOCAL edition (Claude Desktop/Code or the CLI); on the hosted edition, tell the user persistence isn't available there and offer a static version.
+12. To choose what to build: match the request against the workflow when: triggers and the capability-map (gridctl_fetch({kind:"doc", name:"capability-map"})). Pick the template whose needs: matches what the app requires (persistence → database; scheduled → cron; etc.). Static (needs: none) deploys as an inspiration (instant, any edition); anything needing needs: is a runtime (async, local edition).
+13. Before writing a cloudgrid.yaml, fetch the reference: gridctl_fetch({kind:"doc", name:"cloudgrid-yaml"}) — it has the full schema, the needs: vocabulary, and the requires-vs-needs caveat (the deployer does not inject from needs: yet, so a database/cache today uses requires: [mongodb] / requires: [redis]).
 
 Deploy is edition-dependent: on the hosted MCP call the drop tool with the HTML; on local MCP / CLI write the file and run the plug tool. An HTML page deploys synchronously, so you get a URL right away.`;