@groundfloorcloud/mcp 0.1.8 → 0.1.9

package/dist/index.js

@@ -567,7 +567,9 @@ Pick **one** type per coderunner. Changing type later means a new coderunner.
 - Same as job, plus a cron expression at deploy:
   \`gf deploy --workload-type schedule --schedule "<cron>"\`
   (or \`groundfloor.json\` \`"schedule"\`).
-- No public invoke URL. Debug with Process Log, not curl.
+- GET/list/status expose top-level \`workload_type\` and \`schedule\`.
+  \`gf coderunner status -c <slug>\` prints type, schedule, last_job.
+- No public invoke URL. Debug with \`gf coderunner logs\`, not curl.
 
 ### Service (Deployment)
 
@@ -654,6 +656,12 @@ or customer env.
 
 When the handler looks right locally, \`gf deploy\` the same tree.
 
+## Secrets on deploy
+
+Do not pass credential-shaped keys as \`--env KEY=VALUE\` (\`*_SECRET\`,
+\`*_API_KEY\`, \`DATABASE_URL\`, \u2026). Control Plane returns **422**.
+\`gf secrets set KEY\` then \`gf deploy --secret KEY\` (inject by reference).
+
 ## M2M tokens (Vault and Files)
 
 New Coderunners cannot call Vault or Files until an M2M client is attached
@@ -665,7 +673,7 @@ Writer on that workspace (full Vault skip-ACL + Files). Grant site users on
 ## Agent actions
 
 Inspect: \`workspace_context\`, \`docs_get\` id \`coderunner\` or \`coderunner-runtime\`, \`suggest_cli\`.
-Act: \`gf deploy\`, \`gf coderunner run|status\`, \`gf m2m token\`. MCP does not deploy.
+Act: \`gf deploy\`, \`gf coderunner run|status|logs\`, \`gf m2m token\`, \`gf identities ls|mint\`, \`gf api\`. MCP does not deploy.
 `.trim();
 
 // src/css-and-styling-guide.ts
@@ -711,30 +719,46 @@ Dataplane is not a database. It is how Groundfloor talks to databases.
 When the user starts any data or database work, say this first. Do not mention
 infrastructure internals (cluster operators, installers, and the like):
 
-You have ArangoDB ready to use through Dataplane. If you want another
-database, deploy it first. You can use a deployed database through Dataplane,
-or connect to it on your own.
+You have Postgres ready to use through Dataplane \u2014 a shared, platform-managed
+cluster, already there, no deploy step. If you want a different engine, or a
+database that is entirely your own (own scaling, own backups schedule), you
+can deploy one first.
 
 ## Options
 
-- ArangoDB \u2014 shared, managed, already there. Default for app data and Vault.
-  No deploy step. Query via Control Plane vault:
-  POST /v1/workspaces/{id}/vault/collections/{name}/query
-- Postgres \u2014 what you can deploy today (portal Data \u2192 Databases). After it is
-  ready, use it through Dataplane or with the connection secrets.
+- Postgres (shared) \u2014 platform-managed, already there. Default for app data
+  and Vault. No deploy step. This is NOT a workspace-owned resource: it does
+  not appear on the customer Databases page, and there is nothing to scale,
+  back up, or delete yourself \u2014 it's offered, not provisioned. Query via
+  Control Plane vault: POST /v1/workspaces/{id}/vault/collections/{name}/query
+- ArangoDB \u2014 also shared, managed, already there, no deploy step. Still fully
+  supported; just no longer the pre-selected engine for new collections.
+- A dedicated database you deploy and own (Postgres, Redis, ClickHouse,
+  Qdrant) \u2014 portal Data \u2192 Databases, or
+  POST /v1/workspaces/{id}/managed-databases. Heavier than the shared
+  default: you own its scaling, backups, and lifecycle. Use this when you
+  need a tier/engine the shared default doesn't offer (Redis, ClickHouse,
+  Qdrant) or want a database isolated to this workspace.
 - A database they already run \u2014 through Dataplane if they wire it, or direct.
 
 Do not list other engines as available to deploy. Do not call Dataplane hosts
 from apps or embed service keys.
 
+## Creating a collection / table
+
+Pass the engine explicitly \u2014 do not rely on Dataplane's default connector
+resolution. POST /v1/workspaces/{id}/vault/collections with
+\`"schema": {"engine": "postgresql", ...}\` for the shared default, or
+\`"engine": "arangodb"\` to use ArangoDB instead.
+
 ## Paths
 
 - Browse / edit rows \u2192 Data Vault (portal or vault APIs)
-- Deploy Postgres \u2192 Customer Portal Databases page, or
-  POST /v1/workspaces/{id}/managed-databases with engine postgres
+- Deploy your own database \u2192 Customer Portal Databases page, or
+  POST /v1/workspaces/{id}/managed-databases with engine postgres|redis|clickhouse|qdrant
 - Shell 403 / empty vault \u2192 collection Access for the site role
 
-docs_get id databases. Human docs: /docs/customer-portal/databases
+docs_get id databases. Human docs: /docs/customer-portal/databases and /docs/customer-portal/data-vault
 `;
 
 // src/design-standard-guide.ts
@@ -818,9 +842,11 @@ remoteEntry.js. Header logos: manifest \`theme.logoUrl\` (absolute https).
 UI look: \`docs_get\` id \`design-standard\`. CSS: Tailwind by default;
 own framework uses FederatedStyleRoot (Shadow DOM) \u2014 \`docs_get\` id
 \`css-and-styling\`. Data: Dataplane is not a database. Say first: you have
-ArangoDB ready through Dataplane; deploy Postgres if you want another
-database; use it through Dataplane or on your own (\`docs_get\` id
-\`databases\`). Local UI without live vault: \`npm run dev:fixtures\`.
+Postgres (shared, platform-managed, no deploy step) ready through Dataplane
+by default; ArangoDB is also ready the same way. Deploy your own dedicated
+database only if you need a different engine or workspace-owned isolation
+(\`docs_get\` id \`databases\`). Local UI without live vault:
+\`npm run dev:fixtures\`.
 
 ## suggest_cli
 
@@ -828,6 +854,86 @@ database; use it through Dataplane or on your own (\`docs_get\` id
 - publish_app \u2192 init + npm install + npm run release + gf apps publish --path release.zip
 `;
 
+// src/vault-guide.ts
+var VAULT_GUIDE = `
+# Data Vault collections
+
+Vault is workspace data behind Control Plane
+\`/v1/workspaces/{workspace_id}/vault/\u2026\`. Browser apps send the Shell JWT.
+Coderunners use \`gf m2m token\` (preferred) or a workload-identity Vault JWT.
+
+## Create a collection (JSON Schema)
+
+POST \`/v1/workspaces/{id}/vault/collections\` with a **JSON Schema** object
+(\`type: object\`, \`properties\`, optional \`required\`). A missing schema is a
+**400** with a field error \u2014 not a 500.
+
+Pass \`engine\` explicitly \u2014 don't rely on Dataplane's default connector.
+\`"postgresql"\` is the platform default (shared, no deploy step);
+\`"arangodb"\` is also available the same way.
+
+Example:
+
+\`\`\`json
+{
+  "name": "properties",
+  "engine": "postgresql",
+  "schema": {
+    "type": "object",
+    "properties": {
+      "name": { "type": "string" },
+      "metadata": { "type": "object" }
+    },
+    "required": ["name"]
+  }
+}
+\`\`\`
+
+Or use \`gf api -X POST /v1/workspaces/{workspace_id}/vault/collections --body '{...}'\`.
+
+\`GET \u2026/vault/collections\` lists schema-registered collections. Implicit
+tables created by the first \`POST \u2026/vault/{collection}\` appear when you pass
+\`include_implicit=true\` (or after a schema create).
+
+## Query totals
+
+\`POST \u2026/vault/{collection}/query\` \`total\` is the **unpaged** match count.
+\`limit\` only sizes \`records\`. Do not treat \`total === records.length\` as
+the full table size.
+
+## Filters
+
+Top-level fields work in \`filter\`. Nested paths such as \`metadata.sector\`
+are either supported by the connector or rejected with **400 unsupported
+path** \u2014 never a silent empty page.
+
+## ACLs
+
+Grant site roles on **Administer \u2192 Access**. Workload identities get
+collection grants via \`PUT \u2026/vault/collections/{name}/acl\`. M2M is Team
+Writer (workspace-wide), not an Access subject.
+
+## Identities vs M2M
+
+- Unattended Coderunners: attach an M2M client, \`gf deploy\`, then
+  \`gf m2m token\`.
+- Workload identity mint: \`gf identities mint --identity <id>\`. The **first**
+  mint returns \`refresh_secret\` once. Later mints omit it unless
+  \`--rotate-refresh\`. Prefer M2M for new workloads.
+
+## Scheduled jobs
+
+\`gf deploy --workload-type schedule --schedule "<cron>"\`.
+\`gf coderunner status -c <slug>\` shows **type**, **schedule**, and **last_job**.
+\`gf coderunner logs -c <slug>\` shows stdout. There is no public URL for
+schedules.
+
+## Secrets on deploy
+
+Do not \`--env SENDGRID_SECRET=\u2026\`. That is **422**.
+\`gf secrets set SENDGRID_SECRET\` then \`gf deploy --secret SENDGRID_SECRET\`.
+`.trim();
+
 // src/docs.ts
 var DOCS_ORIGIN = "https://docs.groundfloor.cloud";
 var DOC_CATALOG = [
@@ -913,8 +1019,22 @@ var DOC_CATALOG = [
     id: "databases",
     title: "Databases",
     path: "/docs/customer-portal/databases",
-    summary: "Dataplane is not a database. ArangoDB is ready through Dataplane. Postgres you deploy first, then use through Dataplane or on your own.",
+    summary: "Dataplane is not a database. Postgres (shared, platform-managed) is the default, ready through Dataplane with no deploy step. ArangoDB is also ready the same way. A dedicated database you deploy and own is a separate, heavier path.",
     embedded: DATABASES_GUIDE
+  },
+  {
+    id: "vault",
+    title: "Data Vault",
+    path: "/docs/api/vault",
+    summary: "Create collections with JSON Schema, query totals vs limit, ACLs, implicit tables, nested filters, identities vs M2M.",
+    embedded: VAULT_GUIDE
+  },
+  {
+    id: "scheduled-jobs",
+    title: "Scheduled jobs",
+    path: "/docs/customer-portal/scheduled-jobs",
+    summary: "workload_type=schedule plus cron. gf coderunner status shows type/schedule/last_job. Use Process Log, not a public URL.",
+    embedded: CODERUNNER_GUIDE
   }
 ];
 function docUrl(entry) {
@@ -1179,9 +1299,10 @@ server.tool(
         databases_howto: {
           docs_get: "databases",
           dataplane: "Dataplane is not a database. It is how Groundfloor talks to databases.",
-          say_first: "You have ArangoDB ready to use through Dataplane. If you want another database, deploy it first. You can use a deployed database through Dataplane, or connect to it on your own.",
-          arango: "Shared, managed, already there. Default for app data and Vault. No deploy step.",
-          deploy: "Postgres is what you can deploy today."
+          say_first: "You have Postgres ready to use through Dataplane \u2014 shared, platform-managed, already there, no deploy step. ArangoDB is also available the same way. If you want your own dedicated database instead, deploy it first.",
+          shared_postgres: 'Default for app data and Vault. Platform-managed, not workspace-owned \u2014 nothing to scale/backup/delete yourself. Pass engine "postgresql" explicitly when creating a collection.',
+          arango: "Also shared, managed, already there, no deploy step. Still fully supported; just no longer pre-selected.",
+          deploy: "A dedicated Postgres/Redis/ClickHouse/Qdrant you own is what you can deploy today (portal Data \u2192 Databases)."
         },
         actions: {
           deploy: suggestCli("deploy"),
@@ -1459,7 +1580,7 @@ server.tool(
 );
 server.tool(
   "dataplane_status",
-  "Dataplane setup status (Dataplane is how Groundfloor talks to databases, not a database itself). ArangoDB is ready through it. Provision with `gf dataplane provision`.",
+  "Dataplane setup status (Dataplane is how Groundfloor talks to databases, not a database itself). Postgres (shared, platform-managed) is ready through it by default; ArangoDB is also ready. Provision with `gf dataplane provision`.",
   { workspace_id: wsId },
   async ({ workspace_id }) => {
     try {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@groundfloorcloud/mcp",
-  "version": "0.1.8",
+  "version": "0.1.9",
   "description": "Groundfloor MCP — inspect workspace state and docs; take actions with the gf CLI.",
   "type": "module",
   "bin": {