@cloudgrid-io/mcp 0.13.0 → 0.15.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cloudgrid-io/mcp",
-  "version": "0.13.0",
+  "version": "0.15.0",
   "description": "MCP server for CloudGrid. Three editions: a local stdio server (full toolset), a hosted web server (light, CLI-free toolset), and a public docs server (search_cloudgrid_documentation) over MCP Streamable HTTP.",
   "type": "module",
   "bin": {

package/src/corpus/capability-map.md

@@ -13,7 +13,7 @@ cloudgrid.yaml schema (every field, the `needs:` injection table, the
 requires-vs-needs caveat, validation rules), fetch the companion reference:
 `gridctl_fetch("doc", "cloudgrid-yaml")`.
 
-## The 19 templates
+## The 59 templates
 
 | Intent (match on `when:`) | Template | `needs:` | Deploy | Edition |
 |---|---|---|---|---|
@@ -29,13 +29,35 @@ requires-vs-needs caveat, validation rules), fetch the companion reference:
 | dashboard, metrics, KPIs, stats page, status board, charts, analytics view — display-only, static data baked in | `dashboard` | none | inspiration (instant) | all |
 | report, one-pager, summary, brief, whitepaper, case study, formatted document | `report` | none | inspiration (instant) | all |
 | slides, deck, pitch, presentation, slideshow | `presentation` (dir: `deck`) | none | inspiration (instant) | all |
+| product launch page, launch announcement, new product page, "we just launched" | `product-launch` | none | inspiration (instant) | all |
+| company website, business site, corporate site, about-us site, small-business homepage | `company-website` | none | inspiration (instant) | all |
 | to-do, task list, notes app, guestbook, CRUD app, a form that SAVES/STORES submissions, anything that PERSISTS data or shares state across users/sessions, sign-in/accounts | `app-with-data` | `database: true` | runtime (async, poll) | local |
 | CRM, contacts, leads, sales pipeline, customer manager, deal tracker | `crm` | `database: true` | runtime (async, poll) | local |
 | kanban board, task board, trello-style board, workflow columns | `kanban` | `database: true` | runtime (async, poll) | local |
 | task manager, to-do app (richer than the app-with-data starter), task list with due dates/priorities | `task-manager` | `database: true` | runtime (async, poll) | local |
 | admin dashboard, admin panel, back-office, CRUD admin, manage records | `admin-dashboard` | `database: true` | runtime (async, poll) | local |
+| invoice system, invoicing, billing invoices, send invoices, invoice tracker | `invoice` | `database: true` | runtime (async, poll) | local |
+| inventory management, stock tracker, warehouse, product stock, SKU manager | `inventory` | `database: true` | runtime (async, poll) | local |
+| job board, careers page, job listings, hiring board, open roles | `job-board` | `database: true` | runtime (async, poll) | local |
+| ticket system, support tickets, helpdesk, issue tracker, support queue | `ticket-system` | `database: true` | runtime (async, poll) | local |
 | REST API, backend for X, API endpoint(s), CRUD API, JSON API, webhook receiver — a backend/service that stores data and isn't a full web UI | `api-service` | `database: true` | runtime (async, poll) | local |
 | chatbot, AI assistant, Q&A bot, conversational app, support bot, ask-me-anything, an app that talks to an LLM / generates text with AI | `ai-app` | `ai: true, database: true` | runtime (async, poll) | local |
+| blog, CMS, content site with posts, publishing platform, articles | `blog-cms` | `database: true` | runtime (async, poll) | local |
+| product catalog, product listings, catalog site, browse products (no checkout) | `product-catalog` | `database: true` | runtime (async, poll) | local |
+| analytics dashboard, usage analytics, metrics from stored events | `analytics-dashboard` | `database: true` | runtime (async, poll) | local |
+| monitoring dashboard, service health board, uptime/incident monitor (data-backed) | `monitoring-dashboard` | `database: true` | runtime (async, poll) | local |
+| financial dashboard, finance metrics, P&L, cashflow board | `financial-dashboard` | `database: true` | runtime (async, poll) | local |
+| expense tracker, spending log, budget tracker, expense report | `expense-tracker` | `database: true` | runtime (async, poll) | local |
+| time tracking, timesheet, hours logger, billable hours | `time-tracking` | `database: true` | runtime (async, poll) | local |
+| event board, events listing, community events, meetup board | `event-board` | `database: true` | runtime (async, poll) | local |
+| directory, business directory, member directory, listings directory | `directory` | `database: true` | runtime (async, poll) | local |
+| quiz, quiz platform, trivia, assessment, questionnaire | `quiz-platform` | `database: true` | runtime (async, poll) | local |
+| API dashboard, API usage dashboard, API requests monitor | `api-dashboard` | `database: true` | runtime (async, poll) | local |
+| feature request board, feedback board, roadmap voting, idea board | `feature-request-board` | `database: true` | runtime (async, poll) | local |
+| revenue dashboard, sales dashboard, MRR/revenue view | `revenue-dashboard` | `database: true` | runtime (async, poll) | local |
+| property listings, real estate site, rentals/homes listings | `property-listings` | `database: true` | runtime (async, poll) | local |
+| project management, projects and tasks tracker, team project board | `project-management` | `database: true` | runtime (async, poll) | local |
+| search over my documents / PDFs / notes / knowledge base, semantic search, document search, find across my files, searchable archive | `semantic-search` | `database: true` (NO `vector` #1545; NO cron #1585) | runtime (async, poll) | local |
 
 **Rule of thumb:** if the app must SAVE/remember data, share state across
 users/sessions, log in, or store submissions → it is persistent → runtime, local
@@ -43,13 +65,26 @@ edition. Pick by shape: a full web UI → `app-with-data`; a plain backend/JSON
 (no UI) → `api-service`; an app that talks to an LLM → `ai-app` (adds `ai:`).
 Otherwise a static template deploys instantly anywhere.
 
-**The DB-CRUD family.** `crm`, `kanban`, `task-manager`, and `admin-dashboard`
-all share the exact `app-with-data` shape (nextjs + `needs: { database: true }`,
-app under `services/web/`, lazy Mongo getter, force-dynamic App-Router routes) —
-they differ only by domain schema + UI. Match the request to the closest one by
-its `when:`; if it is a bare to-do or generic "save this data" with no specific
+**The DB-CRUD family.** `crm`, `kanban`, `task-manager`, `admin-dashboard`,
+`invoice`, `inventory`, `job-board`, and `ticket-system` all share the exact
+`app-with-data` shape (nextjs + `needs: { database: true }`, app under
+`services/web/`, lazy Mongo getter, force-dynamic App-Router routes) — they
+differ only by domain schema + UI. Match the request to the closest one by its
+`when:`; if it is a bare to-do or generic "save this data" with no specific
 domain, use `app-with-data` (the minimal reference). Deploy path is identical for
-all five.
+all of them.
+
+**Document search (`semantic-search`).** For "search over my own documents / PDFs
+/ notes / knowledge base" with keyword **and** meaning, `semantic-search` ships
+real runnable code in a different shape from the Next.js family: a React (Vite)
+**static** frontend at `/` plus a **Python FastAPI** backend at `/backend`, on the
+same grid-shared Mongo (`needs: { database: true }`). Hybrid search = Mongo
+`$text` + in-app NumPy cosine over embedding arrays + metadata filters. It stores
+embeddings in the Mongo `chunks` collection (NO `needs: vector` — pgvector is
+blocked on **#1545**) and refreshes via a manager endpoint (NO active cron — a
+Python `type: cron` is blocked on **#1585**). Read its `AGENTS.md` for the source
+adapter (dropbox/local/url) + embeddings wiring and the health-without-secrets /
+startup-index patterns.
 
 ## Held / pending platform (not yet buildable)
 
@@ -61,6 +96,45 @@ know they are coming but must NOT author them yet:
 | scheduled task, cron job, "run every day/hour", periodic worker | a `type: cron` service (`schedule`, `timezone`) | **HELD** — platform issue #1543 (cron entities crash the online-check). Do not build. |
 | RAG chatbot, "answer over my own docs", semantic search, retrieval-augmented Q&A | `ai-app` + `needs: { vector: pgvector }` | **HELD** — platform issue #1545 (pgvector crashes the deploy). Ship the plain `ai-app` (no vector) for now. |
 
+## Blueprints (structure + cloudgrid.yaml; adapt the app — some pending platform support)
+
+A **blueprint** is a heavier archetype that ships **structure + a correct
+`cloudgrid.yaml` + an `AGENTS.md`** rather than fill-in-the-blanks app code
+(`kind: blueprint` in the workflow frontmatter). Fetch the workflow, fetch the
+template, **read its `AGENTS.md`** for the file tree / collections / CloudGrid
+wiring (DB injection, `vault:` secrets for auth + Stripe, deploy), then BUILD the
+app under `services/web/` following it. All are persistent Next.js + Mongo →
+runtime, async build, **local edition only**. Auth/payment secrets map through a
+`vault:` block → env vars (never `requires:`).
+
+| Intent (match on `when:`) | Template | `needs:` | Deploy | Edition |
+|---|---|---|---|---|
+| online store, e-commerce store, shop with checkout, sell products online | `online-store` | `database: true` (+ Stripe via `vault:`) | runtime (async, poll) | local |
+| marketplace, multi-vendor platform, two-sided marketplace | `marketplace` | `database: true` (+ Stripe/auth via `vault:`) | runtime (async, poll) | local |
+| HR portal, employee portal, HR management, leave/PTO system | `hr-portal` | `database: true` (+ auth via `vault:`) | runtime (async, poll) | local |
+| ERP, enterprise resource planning, integrated multi-module business system | `erp` | `database: true` (+ auth/Stripe via `vault:`) | runtime (async, poll) | local |
+| forum, discussion board, community forum, threaded discussions | `forum` | `database: true` (+ auth via `vault:`) | runtime (async, poll) | local |
+| membership site, paid community, subscriber content, gated content | `membership-site` | `database: true` (+ Stripe/auth via `vault:`) | runtime (async, poll) | local |
+| course platform, sell online courses, Teachable-style | `course-platform` | `database: true` (+ Stripe/auth via `vault:`) | runtime (async, poll) | local |
+| LMS, learning management system, training platform | `lms` | `database: true` (+ auth via `vault:`) | runtime (async, poll) | local |
+| subscription management, manage subscriptions, self-serve plans/billing | `subscription-management` | `database: true` (+ Stripe via `vault:`) | runtime (async, poll) | local |
+| billing dashboard, invoicing and payments dashboard, SaaS billing | `billing-dashboard` | `database: true` (+ Stripe via `vault:`) | runtime (async, poll) | local |
+| internal tools portal, admin tools hub, back-office portal | `internal-tools-portal` | `database: true` (+ auth via `vault:`) | runtime (async, poll) | local |
+| approval workflow, request approvals, multi-step approval system | `approval-workflow` | `database: true` (+ auth via `vault:`) | runtime (async, poll) | local |
+| booking system, reservations, appointment booking, scheduling | `booking-system` | `database: true` (+ Stripe/auth via `vault:`); reminder **cron pending #1543** | runtime (async, poll) | local |
+| calendar scheduler, team calendar, scheduling app, meeting scheduler | `calendar-scheduler` | `database: true` (+ optional auth/Stripe via `vault:`); reminder **cron pending #1543** | runtime (async, poll) | local |
+| appointment booking, clinic/salon booking, appointment scheduler | `appointment-booking` | `database: true` (+ auth/Stripe via `vault:`); reminder **cron pending #1543** | runtime (async, poll) | local |
+| restaurant website with reservations, table booking, restaurant site | `restaurant-reservations` | `database: true` (+ Stripe/email via `vault:`); reminder **cron pending #1543** | runtime (async, poll) | local |
+| travel booking portal, trip booking, flights/hotels booking, travel reservations | `travel-booking` | `database: true` (+ Stripe/auth via `vault:`); reminder **cron pending #1543** | runtime (async, poll) | local |
+| RAG, ask my docs, knowledge base chatbot, retrieval-augmented search over documents | `ai-knowledge-base` | `ai: true, database: true`; ideal `vector: pgvector` **pending #1545** (store embeddings in Mongo + cosine-rank until it lands) | runtime (async, poll) | local |
+
+The booking family (`booking-system`, `calendar-scheduler`, `appointment-booking`,
+`restaurant-reservations`, `travel-booking`) is fully buildable today **minus**
+the reminder cron — a `type: cron` service is HELD on platform issue **#1543**, so
+ship without it. `ai-knowledge-base` builds today on the AI Gateway + Mongo; its
+ideal `needs: { vector: pgvector }` embedding store is HELD on **#1545**, so store
+chunks in Mongo and cosine-rank in-app until it lands.
+
 ## The full `needs:` vocabulary (the whole menu)
 
 `needs:` is a MAP declaring infrastructure capabilities. Values are `true` or an

package/src/corpus/templates/_cloudgrid.yaml.reference

@@ -0,0 +1,228 @@
+# ============================================================================
+# cloudgrid.yaml — Complete Example
+# ============================================================================
+#
+# This file shows EVERY field the platform supports, with comments explaining
+# each one. It is a reference — no real project would use all of these at once.
+#
+# STANDARD: every CloudGrid template ships its cloudgrid.yaml in THIS full form.
+# Uncomment ONLY the fields the archetype needs (always: name + services; plus
+# needs: for runtime apps). Leave everything else commented. Comments are
+# ignored by the parser, so the file deploys to exactly the active fields.
+#
+# Only two fields are required: name and services. Everything else is optional.
+# Full docs: docs/cloudgrid-yaml-reference.md
+# ============================================================================
+
+
+# ─── IDENTITY ───────────────────────────────────────────────────────────────
+
+# Entity slug (REQUIRED). 2-42 chars, lowercase alphanumeric + hyphens.
+# Must start and end with a letter or digit.
+# Becomes part of your public URL: <name>-<4hex>.<org>.cloudgrid.io
+name: my-app
+
+# One-line summary. Max 280 chars. If omitted, Grid Brain auto-generates one.
+# description: Order processing API for the e-commerce platform
+
+# Single emoji or short text shown as the entity icon. Max 64 chars.
+# icon: "📦"
+
+# Entity type: 'app' (default) or 'agent'. An agent is an app with an agent: block.
+# kind: app
+
+
+# ─── NETWORKING ─────────────────────────────────────────────────────────────
+
+# Whether this entity serves public HTTP traffic.
+# true = public URL + Ingress (default). false = internal only.
+# expose: true
+
+# Additional domain names this entity serves on (the platform URL is always active).
+# custom_domains:
+#   - orders.example.com
+#   - shop.example.com
+
+
+# ─── HEALTH PROBE (entity-level override) ──────────────────────────────────
+
+# Override the default health check for the entire entity.
+# probe:
+#   path: /healthz               # HTTP path to probe (default: /).
+#   expected: "<500"             # '<500' (default), '200', '2xx'.
+
+
+# ─── DEPLOY NOTIFICATIONS ──────────────────────────────────────────────────
+
+# Slack notification to the org's default channel on deploy failure.
+# true = notify (default), false = silent.
+# notify: true
+
+
+# ─── SCALING ────────────────────────────────────────────────────────────────
+
+# Replica scaling intent.
+#   'auto'  — platform decides from the grid tier (default).
+#   'alert' — single-replica, emit a SPOF warning at plug time.
+#   1-10    — explicit replica count, clamped to the grid max.
+# scale: auto
+
+
+# ─── INFRASTRUCTURE NEEDS ──────────────────────────────────────────────────
+#
+# Declare infrastructure; the platform provisions it and injects connection
+# details as env vars. Nine needs: database, cache, kv, queue, pubsub, vector,
+# object_storage, disk, ai. Simplest form is `true`.
+#
+# needs:
+#   # database — MongoDB. Injects DATABASE_MONGODB_URL (+ legacy MONGODB_URL).
+#   #   true | pool | dedicated | { tier: external, secret: MY_DB }
+#   database: true
+#   # cache — Redis, LRU eviction (derived data). Injects CACHE_REDIS_URL (+ REDIS_URL).
+#   #   true | redis | { engine: external, secret: MY_REDIS_URL }
+#   cache: true
+#   # kv — Redis, no eviction (durable: flags, idempotency). Injects KV_REDIS_URL.
+#   kv: true
+#   # queue — Redis job-queue substrate (BullMQ). Injects QUEUE_REDIS_URL.
+#   queue: true
+#   # pubsub — Redis broadcast pub/sub. Injects PUBSUB_REDIS_URL.
+#   pubsub: true
+#   # vector — pgvector on Postgres. Injects VECTOR_PGVECTOR_URL (+ PGVECTOR_URL).
+#   #   true | pgvector | { engine: pgvector, dim: 1536 }
+#   vector: pgvector
+#   # object_storage — GCS bucket. Injects OBJECT_STORAGE_GCS_BUCKET, _GCS_REGION.
+#   #   true | { size: 10Gi }
+#   object_storage: true
+#   # disk — persistent FS mount (PVC). Injects DISK_PATH. Pins to 1 replica.
+#   #   true | { size: 1Gi, mount: /var/data }  (forbidden: /proc /sys /dev)
+#   disk: true
+#   # ai — AI Gateway via @cloudgrid-io/ai. Injects AI_GATEWAY_URL. true | false.
+#   ai: true
+
+
+# ─── INTER-ENTITY COMMUNICATION ────────────────────────────────────────────
+
+# Entities this app calls (outbound). Service-account token injected per pair.
+# calls:
+#   - org:atomic/billing-api
+
+# Inbound caller policy — who can call YOUR entity.
+# callers:
+#   policy: auto                 # 'auto' | 'manual' (default).
+#   scope: org                   # 'org' (default) | 'space' | 'explicit'.
+#   fallback: deny               # 'deny' (default) | 'warn'.
+#   # allowed_apps:              # required only when scope: explicit
+#   #   - org:atomic/frontend
+
+
+# ─── VAULT ──────────────────────────────────────────────────────────────────
+
+# Map org vault items to env vars. Keys UPPER_SNAKE_CASE; values = vault item keys.
+# vault:
+#   STRIPE_KEY: stripe-live-key
+#   SENDGRID_API_KEY: sendgrid-key
+
+
+# ─── CONNECTORS AND HOOKS ──────────────────────────────────────────────────
+
+# connectors:
+#   - id: team-slack
+#     target: org                # 'system' | 'org'.
+#     channel: "#deploys"
+# hooks:
+#   - on: deploy.failed          # release.published | deploy.failed | feedback.received | entity.created
+#     via: team-slack
+#     template: "Deploy failed for {entity_name}: {error}"
+#     channel: "#alerts"
+# triggers:
+#   - from: team-slack
+#     event: message
+#     channel: "#support"
+#     route: /webhooks/slack
+
+
+# ─── LOCAL DEVELOPMENT ──────────────────────────────────────────────────────
+
+# Config for `grid dev`. Redact fields in dev data snapshots.
+# dev:
+#   snapshot:
+#     mask:
+#       - users.email
+#       - users.phone
+
+
+# ─── AGENT METADATA ────────────────────────────────────────────────────────
+
+# An agent is an app with kind: agent (above) and an agent: block.
+# agent:
+#   purpose: Sync customer data from external CRM every night
+#   schedule: "0 2 * * *"
+#   trigger: webhook
+
+
+# ─── PRIVATE RESOURCE AUTO-DEPENDENCIES ────────────────────────────────────
+
+# When true (default), private resources are auto-injected as depends_on.
+# auto_depends_on_private_requires: true
+
+
+# ─── SERVICES (REQUIRED) ───────────────────────────────────────────────────
+#
+# At least one service is required. Key = service name (slug rules).
+# Types: node, nextjs, python, static, cron.
+#
+services:
+  web:
+    # type (REQUIRED): node | nextjs | python | static | cron
+    type: static
+    # HTTP route: '/' | '/api' | false (internal) | omitted (=false + warning).
+    # Only one service per entity can claim '/'.
+    path: /
+    # Container port (default 8080; read process.env.PORT). Not for cron.
+    # port: 3000
+    # nextjs only: base_image: distroless (default) | alpine
+    # base_image: distroless
+    # node only: lang: javascript (default) | typescript
+    # lang: typescript
+    # Custom source location (default services/<name>/). '.' = project root.
+    # source:
+    #   path: src/worker
+    # Health probe: false/omitted (TCP) | true (/health) | "/path" | {path,expected}
+    # health:
+    #   path: /api/health
+    #   expected: "200"
+    # Static runtime env vars (strings). Reserved: PORT, APP_NAME, SERVICE_NAME,
+    # NODE_ENV, MONGODB_URL, REDIS_URL, AI_GATEWAY_URL, N8N_WEBHOOK_URL, CLOUDGRID_*.
+    # env:
+    #   LOG_LEVEL: info
+    # Sibling services/private resources that must be Ready first (no cron, no cycles).
+    # depends_on:
+    #   - worker
+    # Per-service needs override (merges with app-level needs).
+    # needs:
+    #   queue: true
+    # Static-only build step:
+    # build:
+    #   command: npm run build
+    #   output: dist
+    #   env:
+    #     VITE_API_URL: https://api.example.com
+    # node_version: "22"          # static build step: '18'|'20'|'22'|'24' (quoted)
+    # Cron-only: schedule (REQUIRED), timezone (UTC|EST|PST), run (job | https URL)
+    # schedule: "0 9 * * 1"
+    # timezone: UTC
+    # run: job
+    # Verbose per-service persistence (prefer needs.disk):
+    # persist:
+    #   - name: scratch
+    #     path: /tmp/scratch
+    #     size: 500Mi
+
+
+# ============================================================================
+# NOTES
+# - NOT here: org:/entity_id: (→ .cloudgrid/link.json), secrets (→ grid secrets set),
+#   Dockerfile (platform generates from services.*.type).
+# - Deploy: grid plug   |   Local with grid resources: grid dev
+# - Full reference: docs/cloudgrid-yaml-reference.md  |  CLI: docs/cli-reference.md
+# ============================================================================

package/src/corpus/templates/admin-dashboard/cloudgrid.yaml

@@ -1,15 +1,233 @@
-# Rename this app. 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).
+# ============================================================================
+# cloudgrid.yaml — Complete Example
+# ============================================================================
+#
+# This file shows EVERY field the platform supports, with comments explaining
+# each one. It is a reference — no real project would use all of these at once.
+#
+# STANDARD: every CloudGrid template ships its cloudgrid.yaml in THIS full form.
+# Uncomment ONLY the fields the archetype needs (always: name + services; plus
+# needs: for runtime apps). Leave everything else commented. Comments are
+# ignored by the parser, so the file deploys to exactly the active fields.
+#
+# Only two fields are required: name and services. Everything else is optional.
+# Full docs: docs/cloudgrid-yaml-reference.md
+# ============================================================================
+
+
+# ─── IDENTITY ───────────────────────────────────────────────────────────────
+
+# Entity slug (REQUIRED). 2-42 chars, lowercase alphanumeric + hyphens.
+# Must start and end with a letter or digit.
+# Becomes part of your public URL: <name>-<4hex>.<org>.cloudgrid.io
 name: my-admin
+
+# One-line summary. Max 280 chars. If omitted, Grid Brain auto-generates one.
+# description: Order processing API for the e-commerce platform
+
+# Single emoji or short text shown as the entity icon. Max 64 chars.
+# icon: "📦"
+
+# Entity type: 'app' (default) or 'agent'. An agent is an app with an agent: block.
+# kind: app
+
+
+# ─── NETWORKING ─────────────────────────────────────────────────────────────
+
+# Whether this entity serves public HTTP traffic.
+# true = public URL + Ingress (default). false = internal only.
+# expose: true
+
+# Additional domain names this entity serves on (the platform URL is always active).
+# custom_domains:
+#   - orders.example.com
+#   - shop.example.com
+
+
+# ─── HEALTH PROBE (entity-level override) ──────────────────────────────────
+
+# Override the default health check for the entire entity.
+# probe:
+#   path: /healthz               # HTTP path to probe (default: /).
+#   expected: "<500"             # '<500' (default), '200', '2xx'.
+
+
+# ─── DEPLOY NOTIFICATIONS ──────────────────────────────────────────────────
+
+# Slack notification to the org's default channel on deploy failure.
+# true = notify (default), false = silent.
+# notify: true
+
+
+# ─── SCALING ────────────────────────────────────────────────────────────────
+
+# Replica scaling intent.
+#   'auto'  — platform decides from the grid tier (default).
+#   'alert' — single-replica, emit a SPOF warning at plug time.
+#   1-10    — explicit replica count, clamped to the grid max.
+# scale: auto
+
+
+# ─── INFRASTRUCTURE NEEDS ──────────────────────────────────────────────────
+#
+# Declare infrastructure; the platform provisions it and injects connection
+# details as env vars. Nine needs: database, cache, kv, queue, pubsub, vector,
+# object_storage, disk, ai. Simplest form is `true`.
+#
+# needs:
+#   # database — MongoDB. Injects DATABASE_MONGODB_URL (+ legacy MONGODB_URL).
+#   #   true | pool | dedicated | { tier: external, secret: MY_DB }
+#   database: true
+#   # cache — Redis, LRU eviction (derived data). Injects CACHE_REDIS_URL (+ REDIS_URL).
+#   #   true | redis | { engine: external, secret: MY_REDIS_URL }
+#   cache: true
+#   # kv — Redis, no eviction (durable: flags, idempotency). Injects KV_REDIS_URL.
+#   kv: true
+#   # queue — Redis job-queue substrate (BullMQ). Injects QUEUE_REDIS_URL.
+#   queue: true
+#   # pubsub — Redis broadcast pub/sub. Injects PUBSUB_REDIS_URL.
+#   pubsub: true
+#   # vector — pgvector on Postgres. Injects VECTOR_PGVECTOR_URL (+ PGVECTOR_URL).
+#   #   true | pgvector | { engine: pgvector, dim: 1536 }
+#   vector: pgvector
+#   # object_storage — GCS bucket. Injects OBJECT_STORAGE_GCS_BUCKET, _GCS_REGION.
+#   #   true | { size: 10Gi }
+#   object_storage: true
+#   # disk — persistent FS mount (PVC). Injects DISK_PATH. Pins to 1 replica.
+#   #   true | { size: 1Gi, mount: /var/data }  (forbidden: /proc /sys /dev)
+#   disk: true
+#   # ai — AI Gateway via @cloudgrid-io/ai. Injects AI_GATEWAY_URL. true | false.
+#   ai: true
+
+
+# ─── INTER-ENTITY COMMUNICATION ────────────────────────────────────────────
+
+# Entities this app calls (outbound). Service-account token injected per pair.
+# calls:
+#   - org:atomic/billing-api
+
+# Inbound caller policy — who can call YOUR entity.
+# callers:
+#   policy: auto                 # 'auto' | 'manual' (default).
+#   scope: org                   # 'org' (default) | 'space' | 'explicit'.
+#   fallback: deny               # 'deny' (default) | 'warn'.
+#   # allowed_apps:              # required only when scope: explicit
+#   #   - org:atomic/frontend
+
+
+# ─── VAULT ──────────────────────────────────────────────────────────────────
+
+# Map org vault items to env vars. Keys UPPER_SNAKE_CASE; values = vault item keys.
+# vault:
+#   STRIPE_KEY: stripe-live-key
+#   SENDGRID_API_KEY: sendgrid-key
+
+
+# ─── CONNECTORS AND HOOKS ──────────────────────────────────────────────────
+
+# connectors:
+#   - id: team-slack
+#     target: org                # 'system' | 'org'.
+#     channel: "#deploys"
+# hooks:
+#   - on: deploy.failed          # release.published | deploy.failed | feedback.received | entity.created
+#     via: team-slack
+#     template: "Deploy failed for {entity_name}: {error}"
+#     channel: "#alerts"
+# triggers:
+#   - from: team-slack
+#     event: message
+#     channel: "#support"
+#     route: /webhooks/slack
+
+
+# ─── LOCAL DEVELOPMENT ──────────────────────────────────────────────────────
+
+# Config for `grid dev`. Redact fields in dev data snapshots.
+# dev:
+#   snapshot:
+#     mask:
+#       - users.email
+#       - users.phone
+
+
+# ─── AGENT METADATA ────────────────────────────────────────────────────────
+
+# An agent is an app with kind: agent (above) and an agent: block.
+# agent:
+#   purpose: Sync customer data from external CRM every night
+#   schedule: "0 2 * * *"
+#   trigger: webhook
+
+
+# ─── PRIVATE RESOURCE AUTO-DEPENDENCIES ────────────────────────────────────
+
+# When true (default), private resources are auto-injected as depends_on.
+# auto_depends_on_private_requires: true
+
+
+# ─── SERVICES (REQUIRED) ───────────────────────────────────────────────────
+#
+# At least one service is required. Key = service name (slug rules).
+# Types: node, nextjs, python, static, cron.
+#
 services:
   web:
+    # type (REQUIRED): node | nextjs | python | static | cron
     type: nextjs
+    # HTTP route: '/' | '/api' | false (internal) | omitted (=false + warning).
+    # Only one service per entity can claim '/'.
     path: /
+    # Container port (default 8080; read process.env.PORT). Not for cron.
+    # port: 3000
+    # nextjs only: base_image: distroless (default) | alpine
+    # base_image: distroless
+    # node only: lang: javascript (default) | typescript
+    # lang: typescript
+    # Custom source location (default services/<name>/). '.' = project root.
+    # source:
+    #   path: src/worker
+    # Health probe: false/omitted (TCP) | true (/health) | "/path" | {path,expected}
+    # health:
+    #   path: /api/health
+    #   expected: "200"
+    # Static runtime env vars (strings). Reserved: PORT, APP_NAME, SERVICE_NAME,
+    # NODE_ENV, MONGODB_URL, REDIS_URL, AI_GATEWAY_URL, N8N_WEBHOOK_URL, CLOUDGRID_*.
+    # env:
+    #   LOG_LEVEL: info
+    # Sibling services/private resources that must be Ready first (no cron, no cycles).
+    # depends_on:
+    #   - worker
+    # Per-service needs override (merges with app-level needs).
+    # needs:
+    #   queue: true
+    # Static-only build step:
+    # build:
+    #   command: npm run build
+    #   output: dist
+    #   env:
+    #     VITE_API_URL: https://api.example.com
+    # node_version: "22"          # static build step: '18'|'20'|'22'|'24' (quoted)
+    # Cron-only: schedule (REQUIRED), timezone (UTC|EST|PST), run (job | https URL)
+    # schedule: "0 9 * * 1"
+    # timezone: UTC
+    # run: job
+    # Verbose per-service persistence (prefer needs.disk):
+    # persist:
+    #   - name: scratch
+    #     path: /tmp/scratch
+    #     size: 500Mi
+
+
+
 needs:
   database: true
+
+
+# ============================================================================
+# NOTES
+# - NOT here: org:/entity_id: (→ .cloudgrid/link.json), secrets (→ grid secrets set),
+#   Dockerfile (platform generates from services.*.type).
+# - Deploy: grid plug   |   Local with grid resources: grid dev
+# - Full reference: docs/cloudgrid-yaml-reference.md  |  CLI: docs/cli-reference.md
+# ============================================================================

package/src/corpus/templates/admin-dashboard/index.md

@@ -39,6 +39,9 @@ services/web/app/api/orders/route.js    # GET / POST / DELETE on the orders coll
 ## cloudgrid.yaml
 
 ```yaml
+# On disk this file is the full-annotated reference (templates/_cloudgrid.yaml.reference) with EVERY
+# field present as a comment; only the fields below are uncommented, so it
+# deploys to exactly these active fields.
 name: my-admin
 services:
   web: