@groundfloorcloud/mcp 0.2.2 → 0.2.4

package/README.md

@@ -81,8 +81,8 @@ Use the prefixed names: `GROUNDFLOOR_API_URL`, `GROUNDFLOOR_WORKSPACE_ID`, `GROU
 | `apps_list` / `apps_get` | Inspect product Apps |
 | `secrets_list` / `files_list` / `dataplane_status` | Inspect (no secrets values) |
 | `domains_list` | Custom domains of an App's Coderunner (`app_id` or `coderunner_id`). Domains exist on Apps, not standalone Coderunners |
-| `quota_get` / `billing_summary` | Plan quota and billing for the workspace's **account** (account id is not the workspace id; billing needs Owner or Billing admin) |
-| `docs_list` / `docs_get` | Product docs (`coderunner`, `coderunner-runtime`, `shell`, `design-standard`, `css-and-styling`, `databases`, `vault`, `feature-flags`, `authentication` are embedded; `access` and `m2m` are live pages, with an `offset` parameter to read past the 12,000-character page limit) |
+| `quota_get` / `billing_summary` | Plan quota and billing for the workspace's **account** (account id is not the workspace id; billing needs organization Owner, Admin or Billing admin) |
+| `docs_list` / `docs_get` | Product docs (`coderunner`, `coderunner-runtime`, `shell`, `design-standard`, `css-and-styling`, `databases`, `vault`, `feature-flags`, `authentication`, `service-access` are embedded; `access` and `m2m` are live pages, with an `offset` parameter to read past the 12,000-character page limit) |
 | `suggest_cli` | Command to run: login, deploy, create_app, init_app, publish_app, m2m_token, … |
 
 Never create `app_kind=coderunner`. Deploy with `gf deploy`.

package/dist/index.js

@@ -516,9 +516,20 @@ the provider.
 
 ## Users and roles (Groundfloor mode)
 
-- **Invite user**: they set their own password from an emailed invitation.
-- **Add user**: you set a password now; they get an email with their sign-in
-  address and role (never the password).
+- **Invite user**: they set their own password from an emailed invitation
+  (the link works for 72 hours).
+- **Add user**: they can sign in straight away. Prefer **Generate a temporary
+  password** (API: \`POST /v1/workspaces/{id}/users/add\` with
+  \`generate_password: true\`): it is returned once in \`temporary_password\`
+  with \`sign_in_url\`, never stored or emailed, and must be changed at first
+  sign-in. They also get an email with their sign-in address and role (never
+  the password).
+- Invite and add take an optional \`app_id\` so the email's sign-in link opens
+  that app.
+- Inviting or adding someone who can already sign in (a password, another
+  credential or single sign-on) returns 409 and sends nothing. Use
+  \`POST \u2026/users/{user_id}/reset-password\` for them instead.
+- App users never appear on the portal **Team** page.
 - Each user has a role: built-in \`viewer\`, \`user\`, \`admin\`, or a custom role
   created on the **Roles** tab. Roles here are unrelated to Portal team roles.
 - The role decides what the user reaches once granted on **Site access**
@@ -549,6 +560,47 @@ the provider.
   stored custom server settings and password. Only send \`mail\` when the user
   means to change email settings.
 
+## When an invite email isn't sent
+
+Never report an invite as delivered without checking. Invite, add, resend and
+reset responses, and every user in \`GET /v1/workspaces/{id}/users\`, carry:
+
+- \`email_sent\`: \`true\` sent, \`false\` not sent, \`null\` unknown.
+- \`email_skipped_reason\`: \`smtp_not_configured\` (no email server set up for
+  the workspace's sign-in email), \`send_failed\` (the server refused or
+  failed), \`delivery_unconfirmed\` (timed out; it may still arrive),
+  \`not_requested\` (sent with \`send_email: false\`), or \`null\`.
+  \`keycloak_smtp_missing\` is retired and no longer returned.
+- \`email_attempted_at\` (\`null\` = invited before delivery was recorded),
+  \`invite_pending\`, \`password_change_required\`,
+  \`temporary_password_set_at\`, \`invite_link_expires_at\`.
+
+If \`email_sent\` is not \`true\` for a pending user, tell the user plainly
+and offer the fallbacks. In the Portal they are on the user's row under
+**App authentication \u2192 Users**; all need workspace \`administer\` (M2M and
+app-user tokens get 403):
+
+1. **Resend** (\`POST \u2026/users/{user_id}/resend-invite\`, pending users only):
+   at most once per 60 s and 5 times per 24 h; re-inviting a pending user
+   counts against the same limit (429 with \`Retry-After\`). If the reason is
+   \`send_failed\` or \`smtp_not_configured\`, fix email first (Branding \u2192
+   Email sending, Send test email) or resending will fail the same way.
+2. **Temp password** (\`POST \u2026/users/{user_id}/temporary-password\`, pending
+   or still on an unused temporary password): returns \`temporary_password\`
+   and \`sign_in_url\` once; no email is sent; same user id and roles; must be
+   changed at first sign-in. 504 = it may or may not be set, retry.
+3. **Copy link** (\`POST \u2026/users/{user_id}/invite-link\`, pending and enabled
+   users only): returns a one-time \`url\` (the portal's \`/join\` page) and
+   \`expires_at\` (24 h), once. The user opens it and chooses their own
+   password. Each call cancels the previous link; \`DELETE\` cancels it;
+   at most 10 per user per hour. Anyone holding the link can set the
+   password.
+
+Temporary passwords and invite links are credentials. Show them only to the
+person who asked for them, tell them to share privately, and never write them
+to files, commits, logs or chat with anyone else. Once a user has set their
+own password, none of these apply (409): use reset-password.
+
 ## Multi-tenant (customer companies inside one workspace)
 
 Turn on **Multi-tenant** in Settings to get a Tenants tab: one tenant per
@@ -563,11 +615,24 @@ Switching to None or External keeps users, roles and settings (switch back and
 they return). To remove them, turn sign-in off first, then **Delete Groundfloor
 login**. Access grants and M2M tokens are kept.
 
+## What app users' tokens can call
+
+App users' tokens work only on: app list and by-slug, Data Vault collection
+list/schema and record query/count/create/update/delete (per collection
+grants), Files list/upload/download/delete (per Files grants) and
+\`GET \u2026/flags/runtime\`. Everything else returns 403 "This API is not
+available to app end users", whatever their role, \`admin\` included. A user
+with no role at all gets 403 too.
+
 ## In a Shell app
 
 The signed-in user's JWT comes from \`window.__GF_GET_ACCESS_TOKEN__()\`. See
-\`docs_get\` id \`shell\`. Unattended workloads use M2M instead (\`docs_get\` id
-\`m2m\`), not an end-user login.
+\`docs_get\` id \`shell\`. Roles are in the token's \`realm_access.roles\`
+(Groundfloor mode). A Shell app's backend Service is public and must verify
+that token itself (issuer and client ID from \`/v1/public/workspaces/by-host\`,
+JWKS, RS256): \`docs_get\` id \`service-access\`.
+Unattended workloads use M2M instead (\`docs_get\` id \`m2m\`), not an
+end-user login.
 `.trim();
 
 // src/coderunner-runtime.ts
@@ -807,6 +872,11 @@ CMD ["npm", "start"]
 
 - Services follow the \`npm start\` / \`PORT\` contract: Node needs \`scripts.start\` if CMD is \`npm start\`.
 - Prefer curling the Deployment URL (\`/health\`) over \`\u2026/run\`.
+- **The Deployment URL (and any App domain on it) is public.** Groundfloor
+  checks no identity. A Service that is a Shell app's backend must verify the
+  user's token itself, and allow the Shell origin for CORS. Off-the-shelf
+  images (port 80 defaults, MySQL, local uploads, sessions): \`docs_get\` id
+  \`service-access\`.
 
 ## Latest deploy rules (all types)
 
@@ -817,6 +887,11 @@ CMD ["npm", "start"]
   \`externalEndpoint\` and status 4 means the container never became ready.
   \`gf deploy\` prints the last Process Log lines, ids, and a Portal link on
   failure. Fetch more with \`gf coderunner logs -c <id|slug>\`.
+- \`coderunner_get_status\` (\`GET \u2026/coderunners/{id}/status\`) returns
+  \`deployment_status\` (same 1\u20137 codes) and \`deployment_status_message\` for
+  the current deployment. While it is 4 (Failed), an App address or custom
+  domain routed to it answers 503, and the Portal app page shows "Deployment
+  failed".
 - Strip \`.env*\`, \`.git\`, \`node_modules\` from ZIPs. Put secrets in
   \`gf secrets\` / deploy \`-e\`, never in the archive.
 - Zip **contents** at root, not a wrapping folder.
@@ -899,10 +974,14 @@ An M2M client can also read secret **values** directly at runtime instead
 of (or alongside) \`--secret\` deploy-time injection: grant it the
 **\`secrets:read\`** scope (same Portal **Administer \u2192 M2M tokens** screen,
 per-client toggle), then call
-\`GET {CONTROLPLANE_URL}/v1/workspaces/{workspace_id}/secrets/{key}\` with
-\`Authorization: Bearer\` from \`gf m2m token\` locally, or the deployed
+\`GET {CONTROLPLANE_URL}/v1/workspaces/{workspace_id}/secrets/{key}?environment_id=$GROUNDFLOOR_ENVIRONMENT_ID\`
+with \`Authorization: Bearer\` from \`gf m2m token\` locally, or the deployed
 workload's injected \`GROUNDFLOOR_M2M_CLIENT_ID\`/\`GROUNDFLOOR_M2M_CLIENT_SECRET\`
-exchanged the same way. This path is:
+exchanged the same way. **Always pass \`environment_id\`**
+(\`GROUNDFLOOR_ENVIRONMENT_ID\` is injected on deploy for a Coderunner bound to
+an environment) to choose which environment's value is read: omitted or
+empty, it resolves to the workspace's \`dev\` environment (or its only active
+one), so a prod workload silently reads dev secrets. This path is:
 
 - **Read-only** \u2014 \`secrets:read\` never grants \`upsert\`/\`delete\`, regardless
   of the client's writer relation on Vault/Files.
@@ -911,7 +990,9 @@ exchanged the same way. This path is:
 - **Workspace-wide, not per-key or per-environment** \u2014 granting the scope
   exposes every secret in the workspace across all environments to that
   client's code, same class of trade as the existing Vault/Files writer
-  grant. Not a fit for isolating one secret to one Coderunner.
+  grant. \`environment_id\` only selects which environment's value is
+  returned; it is not an access boundary. Not a fit for isolating one secret
+  (or one environment) to one Coderunner.
 
 Prefer it over \`--secret\` injection when you want live rotation and can
 do the fetch yourself; keep using \`--secret\` injection for SDKs that only
@@ -933,8 +1014,9 @@ documented limit.
 Plan quota and usage are account-scoped, not workspace-scoped. The **account
 id is not the workspace id**: read \`account_id\` from \`workspaces_list\`. If a
 deploy is refused or you need to know what is in use, call \`quota_get\`.
-\`billing_summary\` shows spend, and only Owners and Billing admins can read it
-(others get 403).
+\`billing_summary\` shows spend, and only organization Owners, Admins and
+Billing admins can read it (others get 403). A Billing admin has no workspace
+access at all.
 
 ## Agent actions
 
@@ -994,16 +1076,26 @@ deploy a dedicated PostgreSQL first.
 ## Options
 
 - PostgreSQL (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
+  and Vault. No deploy step. The portal Databases page lists it first as
+  "Shared PostgreSQL" (Default, connected as \`postgresql\`), but it is NOT a
+  workspace-owned resource: no credentials, and 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
 - Dedicated PostgreSQL you deploy and own \u2014 portal Data \u2192 Databases, or
   POST /v1/workspaces/{id}/managed-databases with engine postgres. Heavier
   than the shared default: you own its scaling, backups, and lifecycle. Use it
   when you want a database isolated to this workspace.
 - A database they already run \u2014 through Dataplane if they wire it, or direct.
 
+A dedicated PostgreSQL is usable through Vault only once Dataplane has it:
+\`GET /v1/workspaces/{id}/managed-databases\` returns \`dataplane_status\`
+(\`connected\` | \`not_connected\` | null while not up) and
+\`dataplane_connection_name\` (pass it as Vault \`connection\`). If it is
+\`not_connected\`, retry with
+\`POST \u2026/managed-databases/{managed_database_id}/dataplane/register\` (write; the
+portal's Retry button), or tell the user to. New dedicated databases get a
+daily backup schedule (30-day retention) where the cell has backup storage.
+
 PostgreSQL is the only engine offered today, shared or dedicated. Do not offer
 other engines (ArangoDB, MongoDB, Redis, ClickHouse, Qdrant, \u2026) as available,
 even if you see them mentioned elsewhere. Do not call Dataplane hosts from apps
@@ -1119,9 +1211,10 @@ with no role gets 403.
 ### Shell federated app (browser)
 
 - **Token**: the Shell end-user JWT, \`await window.__GF_GET_ACCESS_TOKEN__()\`.
-- **Permission**: workspace \`read\`. Site users get it from a recognised site
-  role (member/admin); self-registered users with no role get 403 (same rule
-  as Vault). No per-flag Access grant exists or is needed.
+- **Permission**: any role from the workspace's App authentication (built-in
+  or custom); a signed-in user with no role gets 403 (same rule as Vault).
+  App users are not workspace members. No per-flag Access grant exists or is
+  needed.
 - **Environment**: \`window.__GF_ENVIRONMENT_ID__\` \u2014 the environment the app is
   bound to, published by the Shell before your remote mounts. Unset in local
   Dev Shell \u2192 server default (dev); \`VITE_GF_ENVIRONMENT_ID\` pins one.
@@ -1180,6 +1273,113 @@ active environments \xB7 400 bad or reserved key \xB7 422 value/value_type misma
 423 workspace frozen (writes).
 `.trim();
 
+// src/service-access-guide.ts
+var SERVICE_ACCESS_GUIDE = `
+# Who can reach a Service (and checking Shell tokens in a backend)
+
+## The rule
+
+Every Coderunner Service is public. Its Deployment URL, and an App's domain
+routed to it, accept requests from anyone. Groundfloor routes the request but
+signs nobody in and checks no token. The Service decides who gets in.
+
+| Service is\u2026 | Example | Do |
+|---|---|---|
+| Open to everyone | website, docs, public API, webhook receiver | Nothing (default) |
+| An app with its own logins | WordPress, Ghost, Metabase | Nothing from Groundfloor; its own login applies. Admin pages (\`/wp-admin\`) are public too |
+| Backend for a Shell app | API the Shell app calls with \`__GF_GET_ACCESS_TOKEN__()\` | Verify the user's token on **every** request |
+
+Never tell a user that Shell sign-in, App authentication or Site access
+protects a Service. Anyone can call the Service directly.
+
+## Verifying a Shell user's token in a backend
+
+1. **Issuer and client ID**: \`GET {CONTROLPLANE_URL}/v1/public/workspaces/by-host?host=<shell-site-host>\`
+   (unauthenticated) \u2192 \`{ workspace_id, mode, oidc: { issuer, client_id } | null, site_host }\`.
+   Check \`workspace_id\` is the user's workspace. \`oidc\` is null in mode
+   \`none\`. Groundfloor mode: per-workspace issuer, \`client_id\` \`shell\`.
+   External mode: the provider's issuer and the client ID the customer
+   entered. Look it up **once at setup**, never at runtime from the request's
+   \`Host\` header (caller-controlled). Do not hard-code the issuer host (it
+   differs per cell); copy the issuer **exactly, including any trailing \`/\`**
+   (do not strip it before comparing \`iss\`) into non-secret env such as
+   \`AUTH_ISSUER\` / \`AUTH_CLIENT_ID\` (Dockerfile \`ENV\`, since deploy-time
+   env is not kept between deploys).
+2. **Checks** (401 if any fails): RS256 signature against
+   \`{issuer}/protocol/openid-connect/certs\` (External: the provider's
+   \`jwks_uri\`), key chosen by the token's \`kid\` (the JWKS has several
+   keys); \`iss\` equals the issuer exactly; \`exp\` present and in the future;
+   the token was issued to the client ID:
+   - Groundfloor mode: \`azp\` == client ID. Do not require an app-specific
+     \`aud\` (none exists yet; tokens often carry \`aud: "account"\`, so with
+     PyJWT set \`verify_aud: False\` and check the client yourself).
+   - External mode: the client ID must appear in \`azp\` (or the provider's
+     equivalent, e.g. \`cid\`, \`appid\`) **or** in \`aud\`. Never accept a
+     token naming it in neither. If the provider allows open sign-up, "any
+     signed-in user" means anyone: require a role.
+   403 when the token is valid but the role (or tenant) is wrong.
+3. **Claims**: roles in \`realm_access.roles\` (built-in \`viewer\`/\`user\`/
+   \`admin\` plus custom roles; ignore \`offline_access\`, \`uma_authorization\`,
+   \`default-roles-*\`). Treat a missing or malformed \`realm_access\`/\`roles\`
+   (not an object / not a list) as no roles \u2192 403, never a 500, and match
+   whole role strings only. External mode: roles come from the customer's
+   provider, in its own claim. For the user ID claim, follow the docs page
+   /docs/apps/shell/sign-in#know-who-the-user-is.
+   **Multi-tenant**: roles apply across every company (an \`admin\` in one
+   company is admin everywhere), so filter every read and write by the
+   \`organization\` claim too. It can hold more than one company: check the
+   record's company is in it. Its exact form is unconfirmed; accept a list of
+   names or an object keyed by name, anything else = no companies.
+4. **Libraries**: Python PyJWT \`PyJWKClient(JWKS_URL, timeout=5)\` (it
+   refetches the JWKS on every unknown \`kid\`, so keep the timeout short) +
+   \`jwt.decode(token, key.key, algorithms=["RS256"], issuer=ISSUER,
+   options={"require": ["exp", "iss"], "verify_aud": False})\`, then
+   \`azp == CLIENT_ID\` (External: or \`cid\`/\`appid\`/\`aud\`), as a FastAPI
+   dependency plus a \`require_role()\` dependency for 403. Node: \`jose\`
+   \`createRemoteJWKSet\` + \`jwtVerify(token, JWKS, { issuer, algorithms:
+   ["RS256"], requiredClaims: ["exp"] })\`, then the same client check; fail at
+   startup if \`AUTH_ISSUER\` or \`AUTH_CLIENT_ID\` is unset (an undefined
+   issuer disables jose's \`iss\` check). Full examples on the docs page.
+5. **CORS**: the Shell site and the Service are different origins, so the
+   browser preflights calls carrying \`Authorization\`. Allow the Shell site
+   origin (and its custom domain), methods, and the \`Authorization\` and
+   \`Content-Type\` headers (FastAPI \`CORSMiddleware\`; Express
+   \`cors({ origin: ["https://<shell-site>"], allowedHeaders: ["Authorization", "Content-Type"] })\`,
+   never bare \`cors()\`, which allows every origin), so preflight is answered
+   before the token check. Never \`*\` with credentials; the bearer header
+   needs no credentials mode.
+
+## Every app on the Shell site can use the user's token
+
+Every app on a Shell site, including apps the customer didn't write, can get
+the signed-in user's token and call the customer's backends as that user, and
+a token from one app is accepted by every other app's backend in the
+workspace. Tell users to install only apps they trust and to check roles for
+anything sensitive. Per-app tokens, sign-in settings injected into the
+Service, and a verify helper are planned (no date). Do not promise per-app
+isolation.
+
+## Running off-the-shelf images as a Service
+
+- Listen on 8080 (or \`PORT\`) on 0.0.0.0; many images default to 80, so
+  reconfigure in the Dockerfile.
+- Managed databases are PostgreSQL only; MySQL/MariaDB/MongoDB apps
+  (WordPress) need an external database.
+- **Finish the installer immediately**: apps with a first-visit installer
+  (WordPress) can be claimed by anyone who opens the URL until it's completed.
+  Tell the user to complete it as soon as the first deploy finishes.
+- Read secrets in an entrypoint script: pass the M2M credentials to curl on
+  stdin (not argv), fail closed if the value is empty, \`unset\` the M2M
+  credentials and token before \`exec\`ing the app.
+- Local disk is lost on restart, redeploy and scale-to-zero, and is per
+  instance. Use the app's S3/object-storage plugin against external storage;
+  Groundfloor Files is an API for code the customer writes, not an S3 endpoint.
+- More than one instance breaks in-memory/on-disk sessions; keep one instance
+  or store sessions in the database. Set min instances \u2265 1 so the first visit
+  doesn't wait.
+- Only the app's own login applies; Groundfloor sign-in can't front it today.
+`.trim();
+
 // src/shell-guide.ts
 var SHELL_APP_GUIDE = `
 # Shell federated apps
@@ -1227,6 +1427,12 @@ outside Shell) so the breadcrumb does not show the raw id. Give that route
 routes (omit it or use \`false\` otherwise \u2014 never \`null\`). \`visibility:
 "public"\` makes a route reachable without login.
 
+Backends: secrets and server-side work go in a Coderunner Service the app
+calls with \`Authorization: Bearer \${await window.__GF_GET_ACCESS_TOKEN__()}\`.
+Shell sign-in does **not** protect that Service: its URL is public, so it must
+verify the token on every request and allow the Shell origin for CORS
+(\`docs_get\` id \`service-access\`).
+
 ## suggest_cli
 
 - create_app \u2192 \`gf apps create --name "<App Name>" --slug <portal-slug> --kind shell_federated\` (register the App first; publish fails with App not found otherwise)
@@ -1425,7 +1631,7 @@ var DOC_CATALOG = [
     path: "/docs/deploy",
     summary: "Workload types (function, job, schedule, service/Deployment), runtime contract (handler.js for function/job/schedule; npm start, PORT 8080 for service), Dockerfile for services, Coderunner identities for Vault, App authentication optional, local live data, gf deploy.",
     embedded: CODERUNNER_GUIDE,
-    lastUpdated: "2026-10-08"
+    lastUpdated: "2026-10-14"
   },
   {
     id: "coderunner-runtime",
@@ -1435,13 +1641,21 @@ var DOC_CATALOG = [
     embedded: CODERUNNER_RUNTIME_CONTRACT,
     lastUpdated: "2026-10-08"
   },
+  {
+    id: "service-access",
+    title: "Who can reach your Service",
+    path: "/docs/deploy/securing-a-service",
+    summary: "Every Service (Deployment URL or App domain) is public; Groundfloor signs nobody in and checks no token. Open sites and apps with their own logins need nothing (finish installers like WordPress immediately); a Shell app's backend must verify the user's JWT on every request: issuer and client_id copied once from GET /v1/public/workspaces/by-host (never from the request Host header), RS256 via the issuer's JWKS by kid, exact iss, exp, azp == client_id in Groundfloor mode (External: azp/cid/appid or aud), no app aud yet; roles in realm_access.roles (malformed = no roles = 403); with Multi-tenant also filter by organization. CORS for the Shell origin. Every app on the Shell site can use the user's token against any of the workspace's backends until per-app tokens ship. Off-the-shelf images: port 8080, PostgreSQL only, ephemeral disk, sessions, min instances.",
+    embedded: SERVICE_ACCESS_GUIDE,
+    lastUpdated: "2026-10-14"
+  },
   {
     id: "authentication",
     title: "Workspace Authentication",
     path: "/docs/access/app-authentication",
-    summary: "App end users sign in only to the app via the workspace App Authentication realm; no Groundfloor console account or workspace membership. Modes none / Groundfloor / external, users and roles, SSO, multi-tenant, sign-in email (Groundfloor email by default, or your own server). Optional; not required to create Apps or Coderunners. Separate from portal Team.",
+    summary: "App end users sign in only to the app via the workspace App Authentication realm; no Groundfloor console account or workspace membership. Modes none / Groundfloor / external, users and roles, SSO, multi-tenant, sign-in email (Groundfloor email by default, or your own server). Invite delivery (email_sent, email_skipped_reason) and what to do when an invite isn't sent: resend, generated temporary password, one-time invite link; 409 for people who can already sign in. App users' tokens work only on the end-user routes. Optional; not required to create Apps or Coderunners. Separate from portal Team.",
     embedded: APP_AUTHENTICATION_GUIDE,
-    lastUpdated: "2026-10-13"
+    lastUpdated: "2026-10-14"
   },
   {
     id: "access",
@@ -1467,7 +1681,7 @@ var DOC_CATALOG = [
     path: "/docs/apps/shell",
     summary: "Product Apps vs Coderunner. Always gf apps init --slug <portal-slug>, then npm run release and gf apps publish --path release.zip. Never zip dist/ or upload only remoteEntry.js.",
     embedded: SHELL_APP_GUIDE,
-    lastUpdated: "2026-10-08"
+    lastUpdated: "2026-10-14"
   },
   {
     id: "design-standard",
@@ -1489,9 +1703,9 @@ var DOC_CATALOG = [
     id: "databases",
     title: "Databases",
     path: "/docs/data/databases",
-    summary: "Dataplane is not a database. PostgreSQL (shared, platform-managed) is ready through Dataplane with no deploy step. A dedicated PostgreSQL you deploy and own is a separate, heavier path. PostgreSQL is the only engine offered.",
+    summary: "Dataplane is not a database. PostgreSQL (shared, platform-managed) is ready through Dataplane with no deploy step. A dedicated PostgreSQL you deploy and own is a separate, heavier path; check its dataplane_status before using it in Vault. PostgreSQL is the only engine offered.",
     embedded: DATABASES_GUIDE,
-    lastUpdated: "2026-09-26"
+    lastUpdated: "2026-10-14"
   },
   {
     id: "vault",
@@ -1507,7 +1721,7 @@ var DOC_CATALOG = [
     path: "/docs/configure/feature-flags",
     summary: "Built-in per-environment feature flags (toggles / config values) \u2014 use these, not a Vault collection. gf flags ls|set|compare|promote. Apps read GET \u2026/flags/runtime: Shell apps with the end-user JWT + window.__GF_ENVIRONMENT_ID__ (starter-kit useFlag), Coderunners with gf m2m token + GROUNDFLOOR_ENVIRONMENT_ID. Default environment is dev.",
     embedded: FLAGS_GUIDE,
-    lastUpdated: "2026-10-08"
+    lastUpdated: "2026-10-14"
   },
   {
     id: "flags-api",
@@ -1515,7 +1729,7 @@ var DOC_CATALOG = [
     path: "/docs/api/flags",
     summary: "REST reference for flags: list/get/put/delete per environment_id (omitted \u2192 workspace default, dev), compare, promote, runtime read. Key format, value_type validation, auth per method (M2M read-only), error codes.",
     embedded: FLAGS_GUIDE,
-    lastUpdated: "2026-10-08"
+    lastUpdated: "2026-10-14"
   },
   {
     id: "scheduled-jobs",
@@ -1523,7 +1737,7 @@ var DOC_CATALOG = [
     path: "/docs/deploy/schedules",
     summary: "workload_type=schedule plus cron. gf coderunner status shows type/schedule/last_job. Use Process Log, not a public URL.",
     embedded: CODERUNNER_GUIDE,
-    lastUpdated: "2026-10-08"
+    lastUpdated: "2026-10-14"
   }
 ];
 function docUrl(entry) {
@@ -1818,7 +2032,7 @@ server.tool(
           default_environment_id: flags?.environment_id ?? null,
           default_environment_flags: flags ? flags.flags.map((f) => ({ key: f.key, value_type: f.value_type, value: f.value })) : null,
           manage: "gf flags ls|get|set|rm|compare|promote -e <env id or name>. Omitting -e uses the default environment (dev).",
-          shell_app: "Starter-kit src/lib/flags.ts: useFlag('key', fallback). Calls GET /v1/workspaces/{id}/flags/runtime?environment_id=window.__GF_ENVIRONMENT_ID__ with the Shell end-user JWT (needs a site role \u2192 workspace read).",
+          shell_app: "Starter-kit src/lib/flags.ts: useFlag('key', fallback). Calls GET /v1/workspaces/{id}/flags/runtime?environment_id=window.__GF_ENVIRONMENT_ID__ with the Shell end-user JWT (needs any App authentication role; app users are not workspace members).",
           coderunner: "GET \u2026/flags/runtime?environment_id=$GROUNDFLOOR_ENVIRONMENT_ID with an M2M token (gf m2m token). M2M is read-only on flags; workload-identity tokens are rejected."
         },
         coderunner_howto: {
@@ -2229,7 +2443,7 @@ server.tool(
 );
 server.tool(
   "billing_summary",
-  "Compute-unit usage and billing estimate for the organization that owns the workspace (account-scoped, not workspace-scoped). Only Owners and Billing admins may read it; others get 403. The response notes whether it is an estimate.",
+  "Compute-unit usage and billing estimate for the organization that owns the workspace (account-scoped, not workspace-scoped). Only organization Owners, Admins and Billing admins may read it; others get 403. The response notes whether it is an estimate.",
   {
     workspace_id: wsId,
     account_id: accountId,
@@ -2278,7 +2492,7 @@ server.tool(
   "How-to for Coderunner, Shell, design-standard, css-and-styling, databases, access, m2m, authentication (app end users). Pass id from docs_list. Prefer id coderunner or coderunner-runtime before deploying. For site grants use id access. For Coderunner Vault/Files use id m2m.",
   {
     id: z.string().min(1).describe(
-      "Catalog id, e.g. coderunner | coderunner-runtime | shell | design-standard | css-and-styling | databases | agents | developers | authentication | access | m2m"
+      "Catalog id, e.g. coderunner | coderunner-runtime | service-access | shell | design-standard | css-and-styling | databases | agents | developers | authentication | access | m2m"
     ),
     offset: z.number().int().min(0).optional().describe(
       "Live (non-embedded) pages only: character offset to resume from. Pass nextOffset from the previous result when truncated is true."

package/package.json

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