@cloudgrid-io/mcp 0.13.0 → 0.15.0

package/src/corpus/workflows/subscription-management.md

@@ -0,0 +1,141 @@
+---
+name: subscription-management
+when: "subscription management, manage subscriptions, self-serve plans/billing"
+needs: database
+deploy: runtime
+editions: local
+kind: blueprint
+capabilities_note: "persistent — needs a database (Mongo) plus Stripe subscription secrets. Runtime app, async build, local edition only. Declare needs { database: true } (deployer injects DATABASE_MONGODB_URL / legacy MONGODB_URL) and a vault block mapping STRIPE_KEY / STRIPE_WEBHOOK_SECRET to env vars. This is a BLUEPRINT — read AGENTS.md for the structure, then build."
+summary: "Build a self-serve subscription-management app on the grid — a Next.js app where a signed-in customer views their current plan, changes/upgrades/downgrades or cancels it, and manages billing via the Stripe Billing Portal, with a Stripe webhook syncing local state and grid-shared Mongo (customers + subscriptions collections). This is a BLUEPRINT: fetch the template, read AGENTS.md for the file tree + CloudGrid wiring (needs database true, vault for Stripe secrets), build the app under services/web/, deploy async, poll to a live URL."
+---
+
+# Workflow: subscription-management
+
+The user wants self-serve subscription management: a signed-in customer sees
+their current plan, upgrades/downgrades or cancels it, and manages billing (card,
+invoices, receipts) — with the app's state staying in sync with Stripe. That is a
+**persistent runtime app** — a Next.js app backed by the grid's shared Mongo,
+with Stripe subscription updates, the Stripe Billing Portal, and a webhook that
+keeps local subscription state authoritative.
+
+This is the **manage-what-you-already-have** surface. If the user actually wants
+the sign-up + paywall + gated-content acquisition flow, that is the
+`membership-site` workflow instead — the two share the same Stripe + Mongo wiring.
+
+This is a **blueprint**, not a fill-in template. There is no finished app to
+copy — there is a `cloudgrid.yaml` and a structure guide (`AGENTS.md`). Read the
+guide, then build the app following it. Be honest that a runtime deploy is async
+(not instant like a static drop) and that it needs the local edition.
+
+## 1. Edition check FIRST (hard gate)
+
+A subscription-management app is a built + deployed container. It requires the
+**local edition** (Claude Desktop / Claude Code) or the CLI.
+
+- **Hosted edition (Claude Web / hosted MCP):** you CANNOT build a runtime app —
+  hosted is inline-only and can only publish static pages. Tell the user
+  plainly, offer a **static pricing/plans page** instead, and STOP the runtime
+  path here.
+- **Local edition:** continue.
+
+## 2. Auth + grid
+
+1. Ensure signed in: `gridctl_login_status`; if not, `gridctl_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. Read the blueprint
+
+Fetch the template and read its structure guide — this is the core of the
+workflow:
+
+- `gridctl_fetch("template", "subscription-management")` — the `cloudgrid.yaml` +
+  **`AGENTS.md`**. AGENTS.md has the file tree, the Mongo collections
+  (`customers`, `subscriptions`), the CloudGrid injection table, and the Stripe
+  change-plan / cancel / billing-portal / webhook wiring. **Read it fully before
+  building.**
+- `gridctl_fetch("template", "app-with-data")` — the proven Next.js + Mongo
+  shape this blueprint extends (lazy db client in `lib/db.js`, App-Router
+  GET/POST route). Imitate its wiring.
+
+## 4. Scaffold
+
+`gridctl_init` an app `<name>`. `init` creates the entity + `.cloudgrid/link.json`
+and writes a `cloudgrid.yaml` with an EMPTY `services: {}`. `plug` needs a linked
+directory, so run `init` FIRST. Then write the app under **`services/web/`** and
+set `cloudgrid.yaml` to the active shape below.
+
+## 5. Build the app following AGENTS.md
+
+Build the file tree from AGENTS.md under `services/web/`: the lazy Mongo client,
+the lazy Stripe client, the plan catalog (`lib/plans.js`), the auth middleware,
+the subscription (change-plan) + cancel + billing-portal + webhook API routes,
+and the `/account` dashboard. Adapt the plans and document fields to the user.
+Key non-negotiables:
+
+- **App code under `services/web/`** — `path:` is the URL mount, NOT the
+  filesystem path. Root files fail with `Service directory not found`.
+- **Read the DB LAZILY** from `process.env.DATABASE_MONGODB_URL` (legacy
+  `process.env.MONGODB_URL` fallback) inside the getter — never at module top
+  level, or `next build` fails.
+- **Read secrets LAZILY** too — `process.env.STRIPE_KEY`,
+  `STRIPE_WEBHOOK_SECRET` — inside getters, never top-level.
+- **The webhook is the source of truth.** The change-plan and cancel APIs call
+  Stripe; do NOT write plan/status to Mongo there — let `/api/webhook` reconcile
+  the `subscriptions` collection so Stripe and Mongo never diverge. Read
+  plan/status server-side from Mongo; validate requested plans against
+  `lib/plans.js` (never accept an arbitrary price id from the client).
+- **Tie every action to the signed-in user** — resolve `userRef` server-side and
+  only ever act on that user's `stripeCustomerId`.
+
+`cloudgrid.yaml` active shape:
+
+```yaml
+name: my-subscription-management
+services:
+  web:
+    type: nextjs
+    path: /
+needs:
+  database: true
+vault:
+  STRIPE_KEY: stripe-live-key
+  STRIPE_WEBHOOK_SECRET: stripe-webhook-secret
+```
+
+**Declare the datastore with `needs: { database: true }`** — the canonical
+shape. `requires:` is the deprecated v1 alias; don't author new yaml with it, and
+never set `needs:` and `requires:` together (the validator rejects it).
+
+## 6. Config / secrets
+
+- Stripe secrets → `gridctl_secrets` (set the vault items `stripe-live-key` and
+  `stripe-webhook-secret` that the `vault:` block maps from). The deployer
+  injects each as its env var at runtime and under `grid dev`. Add
+  `auth-provider-key` too if you use an auth SDK.
+- Non-secret config (Stripe publishable key `NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY`,
+  price ids, auth publishable key) → `gridctl_env` / `services.web.env`.
+- Do **NOT** set the DB connection vars yourself (`DATABASE_MONGODB_URL` / legacy
+  `MONGODB_URL`) — the grid injects them.
+
+## 7. (Optional) Run locally
+
+Mention that the user can `grid dev` to run locally against the injected Mongo
+and vault secrets before deploying. Don't require it.
+
+## 8. Deploy (async)
+
+Deploy the folder with `gridctl_plug`. A **runtime deploy is ASYNC**: the first
+response is `status: "building"`, NOT a live URL yet.
+- Poll `gridctl_status` (or the returned poll_url) until the entity is live.
+- Surface a liveness signal while it builds — never a bare silent wait.
+- Once live, register the `/api/webhook` URL as the Stripe webhook endpoint,
+  copy the signing secret into the `stripe-webhook-secret` vault item, configure
+  the Billing Portal in the Stripe dashboard, and re-plug. Return the deployed
+  app URL (NOT the build/log link).
+
+## 9. Return the live URL + iterate
+
+Give the user the live app URL — that is the deliverable. To iterate, re-plug the
+SAME entity so it updates the same URL. Keep it honest: async build, local-edition
+only, DB injected by the grid, secrets injected from the vault.

package/src/corpus/workflows/ticket-system.md

@@ -0,0 +1,101 @@
+---
+name: ticket-system
+when: ticket system, support tickets, helpdesk, issue tracker, support queue — a persistent app that stores tickets (subject, requester, status, priority, body) with status changes. 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 persistent Next.js + Mongo support ticket queue on the grid — a `tickets` collection (subject, requester, status open/pending/closed, priority, body) with add / status-change / delete. 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: ticket-system
+
+The user wants a tickets app that **remembers** its
+records — they survive refresh and are shared across sessions. That is a
+**runtime app** backed by the grid's shared Mongo, not a static page. It is the
+same proven shape as `app-with-data`, with a `tickets` domain
+(subject, requester, status of open/pending/closed, priority, body) and a table view with add, per-row status changes, and delete.
+
+Follow this recipe. Be honest that a runtime deploy is async (not instant like a
+static drop) and that it needs the local edition.
+
+## 1. Edition check FIRST (hard gate)
+
+A persistent app is a built + deployed container. It requires the **local
+edition** (Claude Desktop / Claude Code) or the CLI.
+
+- **Hosted edition (Claude Web / hosted MCP):** you CANNOT build a runtime app —
+  hosted is inline-only and can only publish static pages. Tell the user
+  plainly, offer a **static version** instead, and STOP the runtime path here.
+- **Local edition:** continue.
+
+## 2. Auth + grid
+
+1. Ensure signed in: `gridctl_login_status`; if not, `gridctl_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
+
+`gridctl_init` an app `<name>`. `init` creates the entity + `.cloudgrid/link.json`
+and writes a `cloudgrid.yaml` with an EMPTY `services: {}`. `plug` needs a linked
+directory, so run `init` FIRST. Then (a) write the app under **`services/web/`**,
+and (b) fill `cloudgrid.yaml` to the shape below (`services.web` + `needs:
+{ database: true }`).
+
+## 4. Add the datastore + wire Mongo
+
+1. Set `cloudgrid.yaml`. **App code MUST live under `services/<name>/`** —
+   `path:` is the URL mount, NOT the filesystem path.
+   ```yaml
+   name: my-tickets
+   services:
+     web:
+       type: nextjs
+       path: /
+   needs:
+     database: true
+   ```
+   **Declare the datastore with `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 it). The template ships this file in the **full-annotated
+   reference form** — every field present as a comment, only `name`,
+   `services.web`, and `needs.database` uncommented — so it deploys to exactly
+   those active fields.
+2. Fetch the template for the Mongo wiring + CRUD shape:
+   `gridctl_fetch("template", "ticket-system")`. It is a minimal, real Next.js +
+   `mongodb`-driver app under `services/web/`: a lazy client in
+   `services/web/lib/db.js`, an App-Router GET/POST/PATCH (status)/DELETE route on a `tickets` collection, a
+   server-component page, and a client component.
+3. Adapt it (rename the collection, change fields, adjust the UI). **Read the DB
+   from `process.env.DATABASE_MONGODB_URL`** (legacy `process.env.MONGODB_URL`
+   fallback) — the grid injects it at dev-time and runtime.
+   - **Put the DB connection behind a lazy getter — never read the connection
+     string at module top level, or `next build` fails.**
+
+## 5. (Optional) Run locally
+
+Mention that the user can `grid dev` to run locally against the injected Mongo
+before deploying. Don't require it.
+
+## 6. Config
+
+- API keys / secrets → `gridctl_secrets`. Non-secret config → `gridctl_env`.
+- Do **NOT** set the DB connection vars yourself (`DATABASE_MONGODB_URL` or the
+  legacy `MONGODB_URL`) — the grid injects them.
+
+## 7. Deploy (async)
+
+Deploy the folder with `gridctl_plug`. A **runtime deploy is ASYNC**: the first
+response is `status: "building"`, NOT a live URL yet.
+- Poll `gridctl_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 app URL (NOT the build/log link).
+
+## 8. Return the live URL + iterate
+
+Give the user the live app URL — that is the deliverable. To iterate, re-plug the
+SAME entity so it updates the same URL. Keep it honest: async build, local-edition
+only, credentials injected by the grid.

package/src/corpus/workflows/time-tracking.md

@@ -0,0 +1,104 @@
+---
+name: time-tracking
+when: time tracking, timesheet, hours logger, billable hours — a persistent app that logs time entries (task, project, minutes, date) and totals hours per project. 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 persistent Next.js + Mongo time tracker on the grid — an `entries` collection (task, project, minutes:number, date) with add / list / delete and totals per project. 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: time-tracking
+
+The user wants a time tracker / timesheet / billable-hours logger that
+**remembers** its entries — hours that survive refresh and are shared across
+sessions. That is a **runtime app** backed by the grid's shared Mongo, not a
+static page. It is the same proven shape as `app-with-data`, with an `entries`
+domain (task, project, minutes, date), an add form, a list of entries, and a
+per-project totals table.
+
+Follow this recipe. Be honest that a runtime deploy is async (not instant like a
+static drop) and that it needs the local edition.
+
+## 1. Edition check FIRST (hard gate)
+
+A persistent app is a built + deployed container. It requires the **local
+edition** (Claude Desktop / Claude Code) or the CLI.
+
+- **Hosted edition (Claude Web / hosted MCP):** you CANNOT build a runtime app —
+  hosted is inline-only and can only publish static pages. Tell the user
+  plainly, offer a **static version** instead, and STOP the runtime path here.
+- **Local edition:** continue.
+
+## 2. Auth + grid
+
+1. Ensure signed in: `gridctl_login_status`; if not, `gridctl_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
+
+`gridctl_init` an app `<name>`. `init` creates the entity + `.cloudgrid/link.json`
+and writes a `cloudgrid.yaml` with an EMPTY `services: {}`. `plug` needs a linked
+directory, so run `init` FIRST. Then (a) write the app under **`services/web/`**,
+and (b) fill `cloudgrid.yaml` to the shape below (`services.web` + `needs:
+{ database: true }`).
+
+## 4. Add the datastore + wire Mongo
+
+1. Set `cloudgrid.yaml`. **App code MUST live under `services/<name>/`** —
+   `path:` is the URL mount, NOT the filesystem path.
+   ```yaml
+   name: my-tracker
+   services:
+     web:
+       type: nextjs
+       path: /
+   needs:
+     database: true
+   ```
+   **Declare the datastore with `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 it).
+2. Fetch the template for the Mongo wiring + CRUD shape:
+   `gridctl_fetch("template", "time-tracking")`. It is a minimal, real Next.js +
+   `mongodb`-driver time tracker under `services/web/`: a lazy client in
+   `services/web/lib/db.js`, an App-Router GET/POST/DELETE route on an `entries`
+   collection, a server-component page, and a client form that also renders
+   per-project totals.
+3. Adapt it (rename the collection, change fields, adjust the UI). The domain is
+   `entries {task, project, minutes:number, date}`: add an entry, list entries,
+   total minutes per project. **Read the DB from
+   `process.env.DATABASE_MONGODB_URL`** (legacy `process.env.MONGODB_URL`
+   fallback) — the grid injects it at dev-time and runtime.
+   - **Put the DB connection behind a lazy getter — never read the connection
+     string at module top level, or `next build` fails.**
+   - The route handler is `export const dynamic = "force-dynamic"` so time
+     entries are always read/written live.
+
+## 5. (Optional) Run locally
+
+Mention that the user can `grid dev` to run locally against the injected Mongo
+before deploying. Don't require it.
+
+## 6. Config
+
+- API keys / secrets → `gridctl_secrets`. Non-secret config → `gridctl_env`.
+- Do **NOT** set the DB connection vars yourself (`DATABASE_MONGODB_URL` or the
+  legacy `MONGODB_URL`) — the grid injects them.
+
+## 7. Deploy (async)
+
+Deploy the folder with `gridctl_plug`. A **runtime deploy is ASYNC**: the first
+response is `status: "building"`, NOT a live URL yet.
+- Poll `gridctl_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 app URL (NOT the build/log link).
+
+## 8. Return the live URL + iterate
+
+Give the user the live app URL — that is the deliverable. To iterate, re-plug the
+SAME entity so it updates the same URL. Keep it honest: async build, local-edition
+only, credentials injected by the grid.

package/src/corpus/workflows/travel-booking.md

@@ -0,0 +1,115 @@
+---
+name: travel-booking
+when: travel booking portal, trip booking, flights/hotels booking, book a flight, book a hotel, travel reservations — a persistent app where users search and book flights/hotels and manage trips that survive refresh and are shared across sessions. Needs a database → runtime → local edition.
+needs: database
+deploy: runtime
+editions: local
+kind: blueprint
+capabilities_note: "persistent — needs a database (Mongo). Runtime app, async build, local edition only. BLUEPRINT — ships structure + cloudgrid.yaml, not app code; read AGENTS.md and build. Declare the canonical `needs: { database: true }`; the deployer injects DATABASE_MONGODB_URL (+legacy MONGODB_URL). Payment/auth secrets via the `vault:` block → env vars. Trip-reminder cron is NOT yet deployable (platform issue #1543)."
+summary: "Build a persistent Next.js + Mongo travel booking portal on the grid — `flights`, `hotels`, `bookings`, `trips` collections with search + availability logic, Stripe checkout, an auth provider, and a (pending) trip-reminder cron. This is a BLUEPRINT: fetch it, read AGENTS.md for the file tree + data model + CloudGrid wiring, then build the app under services/web/. Edition-gate first, scaffold, declare needs:{database:true} (not requires:), map secrets via vault:, deploy async, poll to a live URL."
+---
+
+# Workflow: travel-booking
+
+The user wants a travel booking portal — search and book flights and hotels, pay,
+and manage trips — that **remembers** its bookings across refresh and sessions.
+That is a **runtime app** backed by the grid's shared Mongo, not a static page.
+The proven runtime shape is the same as `app-with-data` (Next.js + lazy Mongo
+client under `services/web/`), with a travel domain (`flights`, `hotels`,
+`bookings`, `trips` with overbooking protection), Stripe checkout for paid
+bookings, an auth provider for accounts, and a scheduled trip-reminder job.
+
+**This is a BLUEPRINT.** It does NOT ship prewritten app code — it ships the
+annotated `cloudgrid.yaml` and an `AGENTS.md` structure guide (file tree, Mongo
+data model, and CloudGrid wiring). Fetch it, **read `AGENTS.md`**, then build the
+app under `services/web/` following it.
+
+Follow this recipe. Be honest that a runtime deploy is async (not instant like a
+static drop), that it needs the local edition, and that the trip-reminder **cron
+service is not yet deployable** (platform issue #1543).
+
+## 1. Edition check FIRST (hard gate)
+
+A persistent app is a built + deployed container. It requires the **local
+edition** (Claude Desktop / Claude Code) or the CLI.
+
+- **Hosted edition (Claude Web / hosted MCP):** you CANNOT build a runtime app —
+  hosted is inline-only and can only publish static pages. Tell the user plainly,
+  offer a **static preview** instead, and STOP the runtime path here.
+- **Local edition:** continue.
+
+## 2. Auth + grid
+
+1. Ensure signed in: `gridctl_login_status`; if not, `gridctl_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. Read the blueprint, then scaffold
+
+1. Fetch the blueprint: `gridctl_fetch("template", "travel-booking")`. **Read its
+   `AGENTS.md`** — it is the structure guide (file tree under `services/web/`, the
+   `flights` / `hotels` / `bookings` / `trips` collections + the overbooking
+   guard, how CloudGrid injects the DB and vault secrets, how to wire Stripe +
+   auth, and the trip-reminder-cron design).
+2. `gridctl_init` an app `<name>`. `init` creates the entity + `.cloudgrid/link.json`
+   and writes a `cloudgrid.yaml` with an EMPTY `services: {}`. `plug` needs a
+   linked directory, so run `init` FIRST.
+
+## 4. Build the app + set cloudgrid.yaml
+
+1. Build the files under **`services/web/`** per the AGENTS.md file tree. **App
+   code MUST live under `services/<name>/`** — `path:` is the URL mount, NOT the
+   filesystem path.
+2. Set `cloudgrid.yaml` to the blueprint shape:
+   ```yaml
+   name: my-travel-booking
+   vault:
+     STRIPE_KEY: stripe-live-key
+     STRIPE_WEBHOOK_SECRET: stripe-webhook-secret
+     AUTH_PROVIDER_KEY: auth-provider-key
+   services:
+     web:
+       type: nextjs
+       path: /
+   needs:
+     database: true
+   ```
+   **Declare the datastore with `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 it).
+3. **Read every injected var lazily** (inside a getter), never at module top level
+   — `process.env.DATABASE_MONGODB_URL || process.env.MONGODB_URL`, and the vault
+   secrets (`STRIPE_KEY`, etc.) the same way. A top-level read fails `next build`.
+4. **Keep the trip-reminder cron COMMENTED.** cron deploy is PENDING platform
+   issue #1543 — `plug` rejects a `type: cron` service. Ship `web` alone; use the
+   stopgap in AGENTS.md §7 for reminders until #1543 lands.
+
+## 5. Config (secrets)
+
+- Payment/auth secrets → add the vault items with `gridctl_secrets` (e.g.
+  `stripe-live-key`, `stripe-webhook-secret`, `auth-provider-key`) BEFORE plug so
+  the `vault:` mappings resolve. Non-secret config → `gridctl_env`.
+- Do **NOT** set the DB connection vars yourself (`DATABASE_MONGODB_URL` / legacy
+  `MONGODB_URL`) — the grid injects them.
+
+## 6. (Optional) Run locally
+
+Mention that the user can `grid dev` to run locally against the injected Mongo +
+vault env vars before deploying. Good for testing search/availability logic. Don't
+require it.
+
+## 7. Deploy (async)
+
+Deploy the folder with `gridctl_plug`. A **runtime deploy is ASYNC**: the first
+response is `status: "building"`, NOT a live URL yet.
+- Poll `gridctl_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 app URL (NOT the build/log link).
+
+## 8. Return the live URL + iterate
+
+Give the user the live app URL — that is the deliverable. To iterate, re-plug the
+SAME entity so it updates the same URL. Keep it honest: async build, local-edition
+only, credentials injected by the grid, and the trip-reminder cron pending #1543.

package/src/tools.js

@@ -867,6 +867,30 @@ function composePlugUrl(data) {
   return `https://${grid}.cloudgrid.io/${slug}`;
 }
 
+// Parse the top-level `name:` from a cloudgrid.yaml manifest (issue #48). The
+// manifest is the source of truth for the entity name on a create, but the
+// inline-create wire never forwarded it, so an `artifact_files` create landed as
+// an auto `drop-XXXX` slug. Deliberately a tiny top-level-scalar scan (no YAML
+// dep, matching the rest of this module): the FIRST unindented `name:` key wins,
+// nested `services:`/`needs:` `name:` keys (indented) are ignored, and quotes +
+// inline `# comments` are stripped. Returns null when absent/unparseable.
+export function parseManifestName(yaml) {
+  if (typeof yaml !== "string" || yaml.length === 0) return null;
+  for (const rawLine of yaml.split(/\r?\n/)) {
+    // Top-level keys only — a leading space/tab means it is nested under a map.
+    if (/^\s/.test(rawLine)) continue;
+    const m = /^name:\s*(.+?)\s*$/.exec(rawLine);
+    if (!m) continue;
+    let val = m[1];
+    // Strip an inline comment on an unquoted scalar.
+    if (!/^["']/.test(val)) val = val.replace(/\s+#.*$/, "").trim();
+    // Strip surrounding quotes.
+    val = val.replace(/^(["'])(.*)\1$/, "$2").trim();
+    return val.length > 0 ? val : null;
+  }
+  return null;
+}
+
 // The public URL of a `/plug` response: the server-composed `url` verbatim
 // (canonical, flat-arch-aware — the unified plug spec), falling back to client-side composition
 // ONLY when the server left it empty (its composition is best-effort).
@@ -1958,6 +1982,24 @@ export async function runPlug(ctx, input, deps = {}) {
   }
   if (useAnonWire && ctx.state.anonCookie) headers["Cookie"] = ctx.state.anonCookie;
 
+  // ── CREATE manifest injection (issue #48) ───────────────────────────────────
+  // On a folder-walk create, a `cloudgrid.yaml` on disk is walked into the tree
+  // and — because directory reads surface it before the nested `services/…`
+  // files — rides the multipart body as the FIRST `artifact` part, with the
+  // walk's uniform `application/octet-stream` content-type. The runtime build
+  // orchestrator relies on the manifest leading the bundle (it drives the
+  // service graph + the entity name). The inline `artifact_files` create used to
+  // APPEND the `cloudgrid_yaml` manifest LAST and as `text/plain`, so a
+  // multi-service runtime rolled out with no service graph (0 replicas /
+  // rollout_failed) and an auto `drop-XXXX` name. Fold the manifest into the
+  // artifact list as the first entry (deduping any `cloudgrid.yaml` the caller
+  // already inlined) so both create paths emit a byte-equivalent bundle.
+  if (!isEdit && cloudgrid_yaml) {
+    const manifest = { path: "cloudgrid.yaml", buffer: Buffer.from(cloudgrid_yaml, "utf8") };
+    const rest = artifacts.filter((a) => a.path !== "cloudgrid.yaml");
+    artifacts = [manifest, ...rest];
+  }
+
   // ── Wire assembly ───────────────────────────────────────────────────────────
   const form = new FormData();
   for (const a of artifacts) {
@@ -1976,15 +2018,17 @@ export async function runPlug(ctx, input, deps = {}) {
         "cloudgrid.yaml",
       );
     }
-  } else if (cloudgrid_yaml) {
-    // On CREATE the manifest rides as a regular artifact file (the create wire
-    // filters a part FIELD-named `cloudgrid.yaml`, but a file named
-    // cloudgrid.yaml lands in the detected source tree).
-    form.append(
-      "artifact",
-      new Blob([cloudgrid_yaml], { type: "text/plain" }),
-      "cloudgrid.yaml",
-    );
+  }
+  // Honor the manifest name (issue #48): send `name:` parsed from `cloudgrid_yaml`
+  // as an explicit name/slug hint so the created entity uses it instead of an
+  // auto `drop-XXXX` slug. Harmless if the server owns slug generation; on a
+  // re-plug the entity's name is authoritative, so only send on create.
+  if (!isEdit) {
+    const manifestName = parseManifestName(cloudgrid_yaml);
+    if (manifestName) {
+      form.append("name", manifestName);
+      form.append("slug", manifestName);
+    }
   }
   if (hints?.kind) {
     // `kind_hint` is what the create orchestrator reads; `hints_kind` is the
@@ -2086,10 +2130,27 @@ export async function runPlug(ctx, input, deps = {}) {
     ...(freshOwnerToken ? { owner_token: freshOwnerToken } : {}),
   };
 
+  // Accurate status (issue #48): a runtime create/edit is an ASYNC build — the
+  // server replies `status: "building"` (+ a poll_url) while the rollout is still
+  // in flight. Do NOT claim "Live"/"Updated in place" for a build that has not
+  // finished; that reported success for apps that then rolled-out-failed. Only
+  // the terminal states get the live wording; anything still building points at
+  // the poll_url and gridctl_status.
+  const isBuilding = data.status === "building" || Boolean(data.poll_url);
   const lines = [];
-  lines.push(isEdit ? `Updated in place: ${url}` : `Live: ${url}`);
-  if (data.status === "building" && data.poll_url) {
-    lines.push(`Build dispatched — poll ${data.poll_url} (trace ${data.trace_id ?? "n/a"}).`);
+  if (isBuilding) {
+    lines.push(
+      isEdit
+        ? `Building (async): ${url} — the update is deploying, not live yet.`
+        : `Building (async): ${url} — the deploy is in progress, not live yet.`,
+    );
+    lines.push(
+      data.poll_url
+        ? `Poll ${data.poll_url} or run gridctl_status until it is ready (trace ${data.trace_id ?? "n/a"}). Do not report it as live until then.`
+        : "Run gridctl_status until it is ready. Do not report it as live until then.",
+    );
+  } else {
+    lines.push(isEdit ? `Updated in place: ${url}` : `Live: ${url}`);
   }
   if (data.entity_id) {
     lines.push(