@groundfloorcloud/mcp 0.1.16 → 0.2.1

package/README.md

@@ -63,6 +63,12 @@ which node
 
 The `command` must be your Node (from `which node`), not `npx` and not Cursor’s helper Node. Do not put a JWT in mcp.json.
 
+### Environment overrides
+
+Use the prefixed names: `GROUNDFLOOR_API_URL`, `GROUNDFLOOR_WORKSPACE_ID`, `GROUNDFLOOR_TOKEN` (CI only; normally the `gf login` session is used).
+
+**Deprecated:** the unprefixed `CP_API`, `WORKSPACE_ID` and `TOKEN` are still honoured as fallbacks, but they collide with unrelated variables in a shell. When one of them supplies a value the server writes a one-line notice to stderr (variable name only, never the value) and they will be removed in a later release.
+
 ## Tools
 
 | Tool | Role |
@@ -71,30 +77,38 @@ The `command` must be your Node (from `which node`), not `npx` and not Cursor’
 | `workspaces_list` | List; switch with `gf workspaces use` |
 | `coderunner_list` / `_get_status` / `_get_logs` / `_process_log` | Inspect workloads (Process Log does not need a job_id) |
 | `environments_list` | List workspace environments |
-| `coderunner_cancel_deployment` | Delete current (or given) deployment |
+| `coderunner_cancel_deployment` | **Destructive.** Deletes one deployment (`deployment_id` is required); if it is the live one, the service goes down. Always the selected workspace (no per-call `workspace_id`) |
 | `apps_list` / `apps_get` | Inspect product Apps |
-| `secrets_list` / `files_list` / `domains_list` / `dataplane_status` | Inspect (no secrets values) |
-| `docs_list` / `docs_get` | Product docs (`coderunner`, `shell`, `design-standard`, `css-and-styling`, `databases` are embedded; `access` and `m2m` are live pages) |
-| `suggest_cli` | Command to run: login, deploy, init_app, publish_app, m2m_token, … |
+| `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) |
+| `suggest_cli` | Command to run: login, deploy, create_app, init_app, publish_app, m2m_token, … |
 
 Never create `app_kind=coderunner`. Deploy with `gf deploy`.
 
-**Shell apps:** `docs_get` id `shell`. Always `gf apps init --slug <portal-slug>`,
-then `npm run release` and `gf apps publish --path release.zip`. Do not invent
+**Shell apps:** `docs_get` id `shell`. Always `gf apps create --name … --slug <portal-slug> --kind shell_federated`,
+then `gf apps init --slug <portal-slug>`, `npm install`, `npm run release` and `gf apps publish --path release.zip`. Do not invent
 `App.tsx` / `vite.config`, zip `dist/`, or upload only `remoteEntry.js`.
 Own CSS framework: `docs_get` id `css-and-styling` (`FederatedStyleRoot`).
 
+**App end users:** `docs_get` id `authentication`. They sign in only to the app via the workspace App Authentication realm; they have no Groundfloor console account or workspace membership.
+
+**Tool annotations:** every tool except `coderunner_cancel_deployment` is marked `readOnlyHint`; the cancel tool is marked `destructiveHint`.
+
 **Databases:** `docs_get` id `databases`. Dataplane is not a database. Shared
 PostgreSQL is ready through Dataplane; a dedicated PostgreSQL is what you can
 deploy today. No other engines are offered.
 
-**Coderunner how-to** is embedded: `docs_get` id `coderunner` (also
-`coderunner-overview`). That page covers:
+**Coderunner how-to** is embedded: `docs_get` id `coderunner`. The former
+`coderunner-overview` id is no longer listed by `docs_list`, but `docs_get`
+still accepts it as an alias and returns the same page. That page covers:
 
 - Types: `function`, `job`, `schedule`, `service` (**also called Deployment**)
 - App authentication is optional (end-user login); not required to create a coderunner
 - **Dockerfile is required** for `service` / Deployment
 - Runtime contract: Node `scripts.start`, listen on `PORT`/8080, bind `0.0.0.0` (`docs_get` id `coderunner-runtime`)
+- Handler signature `(context, payload)` and the HTTP return shape, plus verified limits
 - Local development against live vault/files/secrets (`gf env`; as the workload use `gf m2m token`, not `gf token`)
 
 `workspace_context` includes a `coderunner_howto` summary so agents see this

package/dist/index.js

@@ -1,8 +1,10 @@
 #!/usr/bin/env node
 
 // src/index.ts
-import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+
+// src/server.ts
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { z } from "zod";
 
 // ../cli/src/auth/oauth.ts
@@ -95,7 +97,7 @@ var EXPIRY_SKEW_MS = 3e4;
 var NotLoggedInError = class extends Error {
   constructor() {
     super(
-      "Not logged in. Set GROUNDFLOOR_TOKEN, or run `gf login` first."
+      "Not logged in. Set GROUNDFLOOR_TOKEN to a Groundfloor access token (e.g. from `gf m2m token`), or run `gf login` first."
     );
     this.name = "NotLoggedInError";
   }
@@ -129,11 +131,26 @@ function sessionFromTokens(tokens, ctx) {
 function isFresh(session) {
   return Date.now() < session.expiresAt - EXPIRY_SKEW_MS;
 }
+function isExpiredJwt(token) {
+  const exp = decodeJwt(token)?.exp;
+  return typeof exp === "number" && Date.now() >= exp * 1e3 - EXPIRY_SKEW_MS;
+}
 async function getValidAccessToken() {
   if (accessTokenProvider) {
     return accessTokenProvider();
   }
+  const envToken = process.env.GROUNDFLOOR_TOKEN?.trim();
+  let envTokenExpired = false;
+  if (envToken) {
+    if (!isExpiredJwt(envToken)) return envToken;
+    envTokenExpired = true;
+  }
   const session = await readAuth();
+  if (envTokenExpired && (!session || !session.accessToken)) {
+    throw new Error(
+      "GROUNDFLOOR_TOKEN has expired and there is no saved `gf login` session. Mint a fresh token (e.g. `gf m2m token`) or run `gf login`."
+    );
+  }
   if (!session || !session.accessToken) {
     throw new NotLoggedInError();
   }
@@ -305,17 +322,6 @@ function getProcessLogs(apiUrl, workspaceId, query = {}) {
     `/v1/workspaces/${encodeURIComponent(workspaceId)}/logs${qs ? `?${qs}` : ""}`
   );
 }
-function domainsBase(workspaceId, coderunnerId) {
-  return `/v1/workspaces/${encodeURIComponent(
-    workspaceId
-  )}/coderunners/${encodeURIComponent(coderunnerId)}/domains`;
-}
-function listDomains(apiUrl, workspaceId, coderunnerId) {
-  return cpGet(
-    apiUrl,
-    domainsBase(workspaceId, coderunnerId)
-  );
-}
 function wsPath(workspaceId, suffix) {
   return `/v1/workspaces/${encodeURIComponent(workspaceId)}${suffix}`;
 }
@@ -411,13 +417,32 @@ function trimSlash(url) {
 }
 var MISSING_TOKEN = "Not signed in. Run `gf login` (or `gf login --stage`) so MCP can use ~/.groundfloor. Do not paste JWTs into Cursor MCP config.";
 var MISSING_WORKSPACE = "No workspace selected. Run `gf workspaces` then `gf workspaces use <uuid>`, or pass workspace_id on this tool.";
+var reportedSources = /* @__PURE__ */ new Set();
+function noteDeprecatedEnv(setting, used, preferred) {
+  const key = `${setting}:${used}`;
+  if (reportedSources.has(key)) return;
+  reportedSources.add(key);
+  console.error(
+    `groundfloor MCP: ${setting} taken from deprecated env var ${used}; set ${preferred} instead (unprefixed names will be removed).`
+  );
+}
+function pick(setting, preferred, deprecated) {
+  const a = process.env[preferred];
+  if (a) return a;
+  const b = process.env[deprecated];
+  if (b) {
+    noteDeprecatedEnv(setting, deprecated, preferred);
+    return b;
+  }
+  return "";
+}
 async function resolveMcpConfig(overrides) {
   const file = await resolveConfig();
   const apiUrl = trimSlash(
-    process.env.GROUNDFLOOR_API_URL || process.env.CP_API || file.apiUrl || CELLS.production.apiUrl
+    pick("API URL", "GROUNDFLOOR_API_URL", "CP_API") || file.apiUrl || CELLS.production.apiUrl
   );
-  const workspaceId = overrides?.workspaceId || process.env.GROUNDFLOOR_WORKSPACE_ID || process.env.WORKSPACE_ID || file.workspaceId || "";
-  const envToken = (process.env.GROUNDFLOOR_TOKEN || process.env.TOKEN || "").trim();
+  const workspaceId = overrides?.workspaceId || pick("workspace id", "GROUNDFLOOR_WORKSPACE_ID", "WORKSPACE_ID") || file.workspaceId || "";
+  const envToken = pick("access token", "GROUNDFLOOR_TOKEN", "TOKEN").trim();
   if (envToken) {
     setAccessTokenProvider(async () => envToken);
   } else {
@@ -444,6 +469,88 @@ async function resolveMcpConfig(overrides) {
   return { apiUrl, workspaceId, token };
 }
 
+// src/cp-get.ts
+async function cpGetJson(apiUrl, token, path2) {
+  const res = await fetch(`${apiUrl}${path2}`, {
+    headers: { Authorization: `Bearer ${token}`, Accept: "application/json" }
+  });
+  if (!res.ok) {
+    let detail = res.statusText;
+    try {
+      const body = await res.json();
+      if (body?.detail !== void 0) {
+        detail = formatCpErrorDetail(body.detail, res.statusText);
+      }
+    } catch {
+    }
+    throw new CpError(res.status, `${res.status} ${detail}`);
+  }
+  return await res.json();
+}
+
+// src/app-authentication-guide.ts
+var APP_AUTHENTICATION_GUIDE = `
+# App authentication (end users of a customer's app)
+
+## The rule
+
+People who use an app built on Groundfloor sign in **only to that app**,
+through the workspace's **App authentication** realm. They do **not** get a
+Groundfloor console (Client Portal) account and are **not** workspace members.
+Portal team roles (Owner, Admin, Writer) are a separate system and never apply
+to app end users. Do not build, suggest or provision Portal logins for them.
+
+App authentication is **optional**. It is not needed to create Apps or deploy
+Coderunners, and it never changes how the team signs in to the Portal.
+
+## Sign-in modes (Portal: Administer \u2192 App authentication, Admin or Owner)
+
+| Mode | End users sign in with | Use when |
+|---|---|---|
+| None | Nothing | Apps are public or handle access themselves |
+| Groundfloor | A hosted sign-in page; users, roles, SSO and branding managed in the Portal | You want sign-in without running an identity provider |
+| External | Your own OpenID Connect provider (Okta, Entra ID, Auth0) | Users already have accounts there |
+
+For External, register \`https://<your-shell-site>/*\` as a redirect address with
+the provider.
+
+## Users and roles (Groundfloor mode)
+
+- **Invite user**: they set their own password (email needs Branding set up).
+- **Add user**: you set a password now; no email is sent.
+- 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**
+  (Data Vault collections, workspace-wide Files, App launch). The built-in
+  \`admin\` role is granted like any other role: new collections start with
+  an \`admin\` grant and new workspaces give it Files write, and removing a
+  grant removes admins' access. Keep \`admin\` in every Access PUT unless the
+  user means to remove it. A signed-in user with no recognised role
+  gets 403 on role-gated endpoints (Vault, feature flags).
+- SSO (OIDC or SAML) can be connected per workspace; role names in the
+  provider's tokens must match the roles granted on Site access.
+
+## Multi-tenant (customer companies inside one workspace)
+
+Turn on **Multi-tenant** in Settings to get a Tenants tab: one tenant per
+customer company, invite-only onboarding, per-tenant SSO. The user's token
+carries the tenant in the \`organization\` claim; the app must keep each tenant's
+data apart using that claim. Site access, data, files and M2M tokens stay shared
+across the workspace.
+
+## Turning it off
+
+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.
+
+## 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.
+`.trim();
+
 // src/coderunner-runtime.ts
 var CODERUNNER_RUNTIME_BODY = `
 The contract depends on the workload type.
@@ -469,9 +576,58 @@ The contract depends on the workload type.
    (\`Cannot find module './handler'\`, \`MODULE_NOT_FOUND\`) and the deployment
    ends **Failed (status 4)**. Check \`gf coderunner logs -c <id>\`.
 
-For the handler's arguments and, for functions, the HTTP event/return shape,
-see the runtime docs (https://docs.groundfloor.cloud/docs/deploy). Do not guess
-the argument order.
+### The handler signature
+
+Arguments are **\`(context, payload)\`** in that order. Export a function named
+\`handler\` (CommonJS \`module.exports = { handler }\`; an ES module
+\`export async function handler(context, payload)\` also works):
+
+\`\`\`js
+const handler = async (context, payload) => {
+  // your code
+};
+
+module.exports = { handler };
+\`\`\`
+
+- \`payload\` is the JSON input: the request body for a function, the run's input
+  for a job or schedule. Guard for a missing body (\`payload?.name\`).
+- \`context\` is reserved for runtime information. Do not rely on its contents.
+
+### Function return shape (HTTP)
+
+Whatever the handler returns becomes the response; you may return anything.
+The documented convention, used by every example, is:
+
+\`\`\`js
+const handler = async (context, payload) => {
+  if (!payload?.name) {
+    return {
+      statusCode: 400,
+      body: { error: "name is required" },
+      headers: { "content-type": "application/json" },
+    };
+  }
+  return {
+    statusCode: 200,
+    body: { greeting: \`Hello, \${payload.name}\` },
+    headers: { "content-type": "application/json" },
+  };
+};
+
+module.exports = { handler };
+\`\`\`
+
+Use \`200\`/\`201\` for success, \`400\` for bad input, \`401\`/\`403\` for auth,
+\`404\` for not found, \`500\` for unexpected errors (no internals in the body).
+Callers POST JSON to the Deployment URL with a bearer token, or use
+\`gf coderunner run -c <slug> --payload '<json>'\`.
+
+### Jobs and schedules: return value and failure
+
+A job or schedule needs no return value. If an error **escapes** the handler the
+run is marked **Failed**; if you catch it, the run succeeds and handling it is
+up to you.
 
 ## Node: service (or any Dockerfile that runs \`npm start\`)
 
@@ -480,7 +636,7 @@ A \`service\` **requires** a root Dockerfile; you own \`CMD\`. If it is
 and the process must follow the HTTP contract:
 
 \`\`\`dockerfile
-FROM node:18-alpine
+FROM node:22-alpine
 WORKDIR /app
 COPY . .
 EXPOSE 8080
@@ -505,8 +661,14 @@ Offer GET \`/\` or \`/health\` for the probe. A Dockerfile whose \`CMD\` is not
 
 ## Python
 
-Bind \`0.0.0.0\` and \`PORT\` (default 8080), for example
-\`uvicorn main:app --host 0.0.0.0 --port \${PORT:-8080}\`.
+Function, job and schedule: \`handler.py\` at the ZIP root (with
+\`requirements.txt\`) defining \`def handler(context, payload):\`, same argument
+order, same return convention (\`statusCode\`, \`body\`,
+\`headers\`; an exception escaping the handler fails a job run). \`print\` goes
+to the Process Log.
+
+A Dockerfile-based service binds \`0.0.0.0\` and \`PORT\` (default 8080), for
+example \`uvicorn main:app --host 0.0.0.0 --port \${PORT:-8080}\`.
 
 ## Jobs and schedules
 
@@ -580,8 +742,9 @@ Pick **one** type per coderunner. Changing type later means a new coderunner.
   \`/app/main.js\` that does \`require('./handler')\`; \`npm start\` is **not** run and
   \`scripts.start\` is not required. Missing \`handler.js\` \u2192 crash loop
   (\`Cannot find module './handler'\`), deployment **Failed (status 4)**.
-  \`gf deploy\` fails fast on this. Handler arguments and the HTTP event/return
-  shape: see the runtime docs (\`docs_get\` id \`coderunner-runtime\`, docs.groundfloor.cloud/docs/deploy).
+  \`gf deploy\` fails fast on this. Handler arguments are \`(context, payload)\`; the
+  signature and the HTTP return shape (\`{ statusCode, body, headers }\`) are in the
+  Runtime contract section above.
 - Node with your own Dockerfile (\`CMD ["npm","start"]\`) instead: listen on
   \`process.env.PORT || 8080\`, bind **\`0.0.0.0\`** (health GET \`/\` or \`/health\`), and
   define \`scripts.start\`.
@@ -613,7 +776,7 @@ Pick **one** type per coderunner. Changing type later means a new coderunner.
 - Node example:
 
 \`\`\`dockerfile
-FROM node:18-alpine
+FROM node:22-alpine
 WORKDIR /app
 COPY package*.json ./
 RUN npm ci --omit=dev
@@ -736,9 +899,28 @@ do the fetch yourself; keep using \`--secret\` injection for SDKs that only
 read a literal \`process.env\` value. Either way, cache the revealed value
 in your process rather than calling \`reveal\` on every request.
 
+## Limits an agent will hit
+
+Verified against the control plane source; anything not listed here is not a
+documented limit.
+
+- **M2M token endpoint**: 20 requests per minute (per client and per source).
+  Cache the token until near expiry; do not mint per request.
+- **Vault collection list/query**: \`limit\` 1-500 (default 50).
+- **Feature flag string values**: at most 10,000 characters.
+- **\`docs_get\` live pages**: truncated at 12,000 characters; use \`offset\` to
+  read the rest.
+
+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).
+
 ## Agent actions
 
-Inspect: \`workspace_context\`, \`docs_get\` id \`coderunner\` or \`coderunner-runtime\`, \`suggest_cli\`.
+
+Inspect: \`workspace_context\`, \`quota_get\`, \`docs_get\` id \`coderunner\` or \`coderunner-runtime\`, \`suggest_cli\`.
 Act: \`gf deploy\`, \`gf coderunner run|status|logs\`, \`gf m2m token\`, \`gf identities ls|mint\`, \`gf api\`. MCP does not deploy.
 `.trim();
 
@@ -911,7 +1093,9 @@ One endpoint for every runtime:
 
 Weak \`ETag\` + \`Cache-Control: private, no-cache\`. Send \`If-None-Match\` \u2192 304.
 Poll no faster than every 30s (the kit uses 60s). No push channel yet.
-Flag values are not secrets \u2014 every signed-in end user can read them.
+Flag values are not secrets, but the endpoint is role-gated: only users with a
+recognised site role can read them (see Permission below); a signed-in user
+with no role gets 403.
 
 ### Shell federated app (browser)
 
@@ -1026,8 +1210,9 @@ routes (omit it or use \`false\` otherwise \u2014 never \`null\`). \`visibility:
 
 ## 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)
 - init_app \u2192 \`gf apps init --slug <portal-slug>\`
-- publish_app \u2192 init + npm install + npm run release + gf apps publish --path release.zip
+- publish_app \u2192 create + init + npm install + npm run release + gf apps publish --path release.zip
 `;
 
 // src/vault-guide.ts
@@ -1074,14 +1259,63 @@ Example:
 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).
+tables created by the first \`POST \u2026/vault/collections/{collection}\` appear when
+you pass \`include_implicit=true\` (or after a schema create).
+
+## Records: routes
+
+All under \`/v1/workspaces/{workspace_id}/vault\`:
+
+| Method and path | Purpose |
+|---|---|
+| \`POST /collections/{collection}/query\` | Filtered, paginated read |
+| \`GET /collections/{collection}/count\` | Count; optional \`filter\` query param (JSON object) |
+| \`POST /collections/{collection}\` | Create one record, body \`{"record": {...}}\`, 201, returns \`{"document": {...}}\` |
+| \`PUT /collections/{collection}/{document_id}\` | Update one record, body \`{"record": {...}}\`, returns \`{"document": {...}}\` |
+| \`DELETE /collections/{collection}/{document_id}\` | Delete one record, 204 |
+| \`GET /collections/{collection}/schema\` | Schema |
+| \`GET\`/\`PUT /collections/{collection}/acl\` | Collection ACL |
 
-## Query totals
+There is **no** \`/vault/{collection}\` route; always include \`/collections/\`.
+\`?connection=\` picks the database (default \`postgresql\`).
 
-\`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.
+## Query: request and response
+
+Request body for \`POST \u2026/collections/{collection}/query\` (all optional):
+\`filter\`, \`sort\` (e.g. \`["-created_at", "name"]\`), \`projection\`,
+\`limit\` (1-500, default 50), \`offset\` (default 0), \`connection\`.
+
+Response:
+
+\`\`\`json
+{ "items": [ {...} ], "total": 123, "has_more": true, "next_offset": 50 }
+\`\`\`
+
+- The array key is **\`items\`** (not \`records\`).
+- \`total\` is the match count from Dataplane (see below for \`$text\`) and is
+  **null** when upstream gave no count; it is never filled in from the page
+  length. Do not treat \`total === items.length\` as the full table size.
+- Page with \`next_offset\` while \`has_more\` is true; \`next_offset\` is null
+  on the last page.
+
+## Substring search (\`$text\` / \`$search\`)
+
+\`{ "filter": { "$text": "alice" } }\` is a case-insensitive substring match
+over every field value. Control Plane runs it itself by scanning the caller's
+ACL-filtered view, at most \`VAULT_TEXT_SEARCH_MAX_SCAN_ROWS\` rows per request
+(default 10 000).
+
+- Plain query: for \`$text\`, \`total\` is computed by Control Plane (not
+  Dataplane). It is exact when the collection fits under the cap; past the cap
+  it is **null** and the results cover only the scanned rows.
+- Large collections: send \`"chunked_scan": true\`, then
+  \`"scan_cursor": <scan.next_cursor>\` with the same filter/sort until
+  \`scan.complete\` is true. Each response has a \`scan\` block
+  (\`complete\`, \`next_cursor\`, \`scanned_rows\`, \`total_rows\`); the exact
+  match total is the sum of \`items\` across chunks. The cursor is not a
+  snapshot \u2014 concurrent writes can skip or repeat rows.
+- \`GET \u2026/count\` with \`$text\` uses the plain bounded scan and returns 400
+  past the cap; use the chunked query instead.
 
 ## Filters
 
@@ -1095,6 +1329,18 @@ 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.
 
+- \`PUT \u2026/acl\` is a **full replace**, saved exactly as sent. \`GET\` the
+  current grants first and send them all back with your change: every site
+  role grant, \`admin\` included, and every workload identity grant. Anything
+  you leave out is removed.
+- The built-in site role \`admin\` is granted like any other role. New
+  collections start with \`admin\` \u2192 \`delete\`; if a PUT leaves \`admin\`
+  out, admins lose access to that collection. Never drop it unless the user
+  asked for that.
+- Only builders (team members with \`ddl\`, or the Client Portal) read or
+  change ACLs. A site (app end user) token gets 403 on every ACL route,
+  even with the \`admin\` role.
+
 ## Identities vs M2M
 
 - Unattended Coderunners: attach an M2M client, \`gf deploy\`, then
@@ -1114,6 +1360,17 @@ schedules.
 
 Do not \`--env SENDGRID_SECRET=\u2026\`. That is **422**.
 \`gf secrets set SENDGRID_SECRET\` then \`gf deploy --secret SENDGRID_SECRET\`.
+
+**Caveat:** \`--secret\` injection needs the platform-wide Control Plane setting
+\`CODERUNNER_INJECT_ENV_SECRETS\`, which is **off by default** and not
+configurable per workspace. When it is off the secret is not injected. Fallback:
+give the Coderunner's M2M client the \`secrets:read\` scope (Portal
+**Administer \u2192 M2M tokens**) and read the value at runtime with
+\`GET /v1/workspaces/{workspace_id}/secrets/{key}\` using the M2M bearer token.
+It is read-only, live (no redeploy on rotation) and workspace-wide. Details in
+\`docs_get\` id \`coderunner\`. The deployed value of the setting cannot be
+checked from the repo; if \`--secret\` fails or the variable is empty, use the
+fallback rather than plaintext \`--env\`.
 `.trim();
 
 // src/version.ts
@@ -1149,7 +1406,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-02"
+    lastUpdated: "2026-10-08"
   },
   {
     id: "coderunner-runtime",
@@ -1157,27 +1414,21 @@ var DOC_CATALOG = [
     path: "/docs/deploy",
     summary: "What the platform expects your code to do: Node handler.js for function/job/schedule, npm start + PORT/8080 + bind 0.0.0.0 for service/Dockerfile, Python bind.",
     embedded: CODERUNNER_RUNTIME_CONTRACT,
-    lastUpdated: "2026-10-02"
-  },
-  {
-    id: "coderunner-overview",
-    title: "Coderunner overview",
-    path: "/docs/deploy",
-    summary: "Architecture and lifecycle. Prefer docs_get id coderunner for type usage, Dockerfile, and create prerequisites.",
-    embedded: CODERUNNER_GUIDE,
-    lastUpdated: "2026-10-02"
+    lastUpdated: "2026-10-08"
   },
   {
     id: "authentication",
     title: "Workspace Authentication",
     path: "/docs/access/app-authentication",
-    summary: "Workspace site auth (Groundfloor or external) is optional end-user login. Leaving Groundfloor keeps the realm (disabled) until Delete Groundfloor login. Separate from portal Team. Not required to create Apps or Coderunners."
+    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. Optional; not required to create Apps or Coderunners. Separate from portal Team.",
+    embedded: APP_AUTHENTICATION_GUIDE,
+    lastUpdated: "2026-10-12"
   },
   {
     id: "access",
     title: "Access",
     path: "/docs/access/site-access",
-    summary: "Grant site roles Data Vault collections, workspace-wide Files, and Apps launch. Admin is implicit. M2M is not an Access subject. Team membership is unchanged."
+    summary: "Grant site roles Data Vault collections, workspace-wide Files, and Apps launch. The built-in admin role is granted like any other role; every Access PUT is a full replace, so include admin and the existing grants or they are removed. Only builders manage Access; app end users get 403. M2M is not an Access subject. Team membership is unchanged."
   },
   {
     id: "m2m",
@@ -1197,7 +1448,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-09-26"
+    lastUpdated: "2026-10-08"
   },
   {
     id: "design-standard",
@@ -1227,9 +1478,9 @@ var DOC_CATALOG = [
     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.",
+    summary: "Create collections with JSON Schema, record routes (/vault/collections/{collection}/\u2026), query request/response (items, total, has_more, next_offset, limit 1-500), $text substring search (bounded scan, chunked_scan/scan_cursor), ACLs, implicit tables, nested filters, identities vs M2M, secrets fallback.",
     embedded: VAULT_GUIDE,
-    lastUpdated: "2026-09-26"
+    lastUpdated: "2026-10-12"
   },
   {
     id: "feature-flags",
@@ -1237,7 +1488,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-09-26"
+    lastUpdated: "2026-10-08"
   },
   {
     id: "flags-api",
@@ -1245,7 +1496,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-09-26"
+    lastUpdated: "2026-10-08"
   },
   {
     id: "scheduled-jobs",
@@ -1253,12 +1504,19 @@ 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-02"
+    lastUpdated: "2026-10-08"
   }
 ];
 function docUrl(entry) {
   return `${DOCS_ORIGIN}${entry.path}`;
 }
+var DOC_ALIASES = {
+  "coderunner-overview": "coderunner"
+};
+function getDocById(id) {
+  const key = DOC_ALIASES[id] ?? id;
+  return DOC_CATALOG.find((d) => d.id === key);
+}
 function findDoc(query) {
   const q = query.trim().toLowerCase();
   if (!q) return DOC_CATALOG;
@@ -1272,7 +1530,7 @@ function htmlToText(html) {
   return article.replace(/<script\b[\s\S]*?<\/script>/gi, " ").replace(/<style\b[\s\S]*?<\/style>/gi, " ").replace(/<nav\b[\s\S]*?<\/nav>/gi, " ").replace(/<footer\b[\s\S]*?<\/footer>/gi, " ").replace(/<[^>]+>/g, " ").replace(/&nbsp;/g, " ").replace(/&amp;/g, "&").replace(/&lt;/g, "<").replace(/&gt;/g, ">").replace(/&#39;/g, "'").replace(/&quot;/g, '"').replace(/\s+/g, " ").trim();
 }
 var MAX_CHARS = 12e3;
-async function fetchDocPage(entry) {
+async function fetchDocPage(entry, offset = 0) {
   const url = docUrl(entry);
   if (entry.embedded?.trim()) {
     return {
@@ -1293,15 +1551,18 @@ async function fetchDocPage(entry) {
     throw new Error(`Docs fetch failed: ${res.status} ${url}`);
   }
   const html = await res.text();
-  let body = htmlToText(html);
-  const truncated = body.length > MAX_CHARS;
-  if (truncated) body = `${body.slice(0, MAX_CHARS)}
-\u2026`;
+  const full = htmlToText(html);
+  const start = Math.max(0, Math.min(offset, full.length));
+  const end = start + MAX_CHARS;
+  const truncated = full.length > end;
+  const body = full.slice(start, end) + (truncated ? "\n\u2026" : "");
   return {
     url,
     title: entry.title,
     text: body,
     truncated,
+    totalChars: full.length,
+    nextOffset: truncated ? end : null,
     source: "docs.groundfloor.cloud",
     lastUpdated: null,
     mcpVersion: GF_MCP_VERSION
@@ -1309,6 +1570,10 @@ async function fetchDocPage(entry) {
 }
 
 // src/playbook.ts
+function createAppCommand(slug, name) {
+  const displayName = name?.trim() || "<App Name>";
+  return `gf apps create --name ${JSON.stringify(displayName)} --slug ${slug || "<portal-slug>"} --kind shell_federated`;
+}
 function suggestCli(intent, args) {
   const ws = args?.workspace ? ` -w ${args.workspace}` : "";
   const name = args?.name ?? args?.coderunner;
@@ -1349,6 +1614,14 @@ function suggestCli(intent, args) {
         why: "Process Log (stdout/stderr). gf deploy prints the last lines on failure; this command fetches more. runner_id accepts a coderunner id.",
         docs: "https://docs.groundfloor.cloud/docs/deploy"
       };
+    case "create_app": {
+      const slug = args?.slug?.trim();
+      return {
+        command: createAppCommand(slug, args?.name),
+        why: 'Register the App in the workspace. gf apps publish resolves the App by slug and fails with "App not found" if this was never run. A 409 means the slug already exists: skip to init/publish. This is a Shell federated App, not a Coderunner (never --kind coderunner).',
+        docs: "https://docs.groundfloor.cloud/docs/apps/shell/getting-started"
+      };
+    }
     case "init_app": {
       const slug = args?.slug?.trim();
       return {
@@ -1357,12 +1630,15 @@ function suggestCli(intent, args) {
         docs: "https://docs.groundfloor.cloud/docs/apps/shell"
       };
     }
-    case "publish_app":
+    case "publish_app": {
+      const slug = args?.slug?.trim();
+      const dir = slug || "<slug>";
       return {
-        command: args?.slug ? `gf apps init --slug ${args.slug} && cd ${args.slug} && npm install && npm run release && gf apps publish --path release.zip` : "gf apps init --slug <portal-slug> && cd <slug> && npm install && npm run release && gf apps publish --path release.zip",
-        why: "Ship a Shell federated App. Always init the kit first. npm run release (not zip dist/, not a lone remoteEntry.js). Do not gf deploy. Do not invent App.tsx.",
+        command: `${createAppCommand(slug, args?.name)} && gf apps init --slug ${slug || "<portal-slug>"} && cd ${dir} && npm install && npm run release && gf apps publish --path release.zip`,
+        why: "Ship a Shell federated App. Register it (gf apps create), then init the kit. Skip create if the App already exists (create returns 409). npm run release (not zip dist/, not a lone remoteEntry.js). Do not gf deploy. Do not invent App.tsx.",
         docs: "https://docs.groundfloor.cloud/docs/apps/shell"
       };
+    }
     case "environments":
       return {
         command: `gf environments ls${ws}`,
@@ -1371,8 +1647,8 @@ function suggestCli(intent, args) {
       };
     case "cancel_deployment":
       return {
-        command: name ? `gf coderunner cancel-deployment -c ${name}${ws}` : `gf coderunner cancel-deployment -c <id-or-slug>${ws}`,
-        why: "Delete the current deployment (or --deployment-id). Use this for a deploy stuck in deploying.",
+        command: name ? `gf coderunner cancel-deployment -c ${name} --yes${ws}` : `gf coderunner cancel-deployment -c <id-or-slug> --yes${ws}`,
+        why: "Delete the current deployment (or --deployment-id). Use this for a deploy stuck in deploying. --yes cancels without a confirmation prompt (required without a TTY).",
         docs: "https://docs.groundfloor.cloud/docs/deploy"
       };
     case "secrets":
@@ -1403,7 +1679,7 @@ function suggestCli(intent, args) {
     default:
       return {
         command: "gf --help",
-        why: `Unknown intent "${intent}". Use login | switch_workspace | deploy | run | status | logs | environments | cancel_deployment | init_app | publish_app | secrets | flags | dataplane | vault_token.`,
+        why: `Unknown intent "${intent}". Use login | switch_workspace | deploy | run | status | logs | environments | cancel_deployment | create_app | init_app | publish_app | secrets | flags | dataplane | vault_token.`,
         docs: "https://docs.groundfloor.cloud/docs/developer-tools/cli"
       };
   }
@@ -1434,7 +1710,9 @@ function errText(err) {
   return { content: [{ type: "text", text: message }], isError: true };
 }
 
-// src/index.ts
+// src/server.ts
+var READ_ONLY = { readOnlyHint: true };
+var DESTRUCTIVE = { readOnlyHint: false, destructiveHint: true };
 var wsId = z.string().optional().describe("Override the gf default workspace for this call only");
 async function cfg(workspaceId, requireWorkspace = true) {
   return resolveMcpConfig({ workspaceId, requireWorkspace });
@@ -1453,6 +1731,7 @@ server.tool(
   "whoami",
   "Show the gf CLI session (identity, cell, selected workspace). Run `gf login` if this fails.",
   {},
+  READ_ONLY,
   async () => {
     try {
       const c = await cfg(void 0, false);
@@ -1476,6 +1755,7 @@ server.tool(
   "workspace_context",
   "Live context for the selected workspace: session, coderunners, apps, environments (with the default one), feature flags, dataplane (access layer, not a database), databases_howto, suggested gf commands. Use docs_get id coderunner before deploying; id databases for data work; id feature-flags for toggles/config; id css-and-styling for own CSS framework.",
   { workspace_id: wsId },
+  READ_ONLY,
   async ({ workspace_id }) => {
     try {
       const c = await cfg(workspace_id);
@@ -1535,12 +1815,16 @@ server.tool(
           node: "function/job/schedule without a Dockerfile run a generated /app/main.js that requires ./handler: ship a root handler.js exporting handler (scripts.start not needed). service/Dockerfile running npm start: scripts.start, listen PORT||8080, bind 0.0.0.0. gf deploy fails fast on either missing.",
           local_live_data: 'eval "$(gf env)". For files/secrets as a builder use Bearer $(gf token). For Vault/Files as the deployed workload, attach an M2M client and use Bearer $(gf m2m token). Never DATAPLANE_SERVICE_API_KEY. Do not zip .env files.'
         },
+        app_end_users: {
+          docs_get: "authentication",
+          rule: "End users of a customer's app sign in only to that app, through the workspace's App Authentication realm (Administer \u2192 App authentication). They have no Groundfloor console account and no workspace membership; their site role (viewer/user/admin or custom) decides what they reach via Site access. Do not build or suggest Portal logins for them."
+        },
         shell_app_howto: {
           docs_get: "shell",
-          rule: "Never invent a Vite + Module Federation app. gf apps init --slug <portal-slug>, npm install, npm run release, gf apps publish --path release.zip. Do not zip dist/ or upload only remoteEntry.js.",
+          rule: "Never invent a Vite + Module Federation app. gf apps create --name <name> --slug <portal-slug> --kind shell_federated (registers the App; publish fails with App not found without it), gf apps init --slug <portal-slug>, npm install, npm run release, gf apps publish --path release.zip. Do not zip dist/ or upload only remoteEntry.js.",
           css: "Tailwind is the default (docs_get id css-and-styling). Own framework: FederatedStyleRoot + ?inline CSS in Shadow DOM. Do not load a second CSS framework onto the Shell page.",
           design: "docs_get id design-standard",
-          suggest_cli: "init_app | publish_app"
+          suggest_cli: "create_app | init_app | publish_app"
         },
         databases_howto: {
           docs_get: "databases",
@@ -1559,6 +1843,7 @@ server.tool(
           flags: suggestCli("flags"),
           cancel_deployment: suggestCli("cancel_deployment"),
           vault_token: suggestCli("m2m_token"),
+          create_app: suggestCli("create_app"),
           init_app: suggestCli("init_app"),
           publish_app: suggestCli("publish_app")
         },
@@ -1578,6 +1863,7 @@ server.tool(
   "workspaces_list",
   "List workspaces visible to the current user. To change the default, tell the user to run `gf workspaces use <uuid>` (CLI owns that).",
   {},
+  READ_ONLY,
   async () => {
     try {
       const c = await cfg(void 0, false);
@@ -1599,6 +1885,7 @@ server.tool(
   "coderunner_list",
   "List Coderunners in the workspace (read-only).",
   { workspace_id: wsId },
+  READ_ONLY,
   async ({ workspace_id }) => {
     try {
       const c = await cfg(workspace_id);
@@ -1616,6 +1903,7 @@ server.tool(
     workspace_id: wsId,
     coderunner_id: z.string().min(1).describe("Coderunner id or slug")
   },
+  READ_ONLY,
   async (args) => {
     try {
       const c = await cfg(args.workspace_id);
@@ -1645,6 +1933,7 @@ server.tool(
     search: z.string().optional(),
     deployment_id: z.string().optional()
   },
+  READ_ONLY,
   async (args) => {
     try {
       const c = await cfg(args.workspace_id);
@@ -1671,6 +1960,7 @@ server.tool(
   "environments_list",
   "List environments in the workspace (id, name, status).",
   { workspace_id: wsId },
+  READ_ONLY,
   async ({ workspace_id }) => {
     try {
       const c = await cfg(workspace_id);
@@ -1686,30 +1976,23 @@ server.tool(
 );
 server.tool(
   "coderunner_cancel_deployment",
-  "Delete a coderunner deployment (current deployment if deployment_id is omitted). Same as `gf coderunner cancel-deployment`.",
+  "DESTRUCTIVE. Deletes one deployment of a Coderunner; if it is the live deployment the service goes down. deployment_id is required (find it with coderunner_get_status). Acts only on the configured workspace (gf workspaces use). Same as `gf coderunner cancel-deployment --deployment-id`. Confirm with the user before calling.",
   {
-    workspace_id: wsId,
     coderunner_id: z.string().min(1).describe("Coderunner id or slug"),
-    deployment_id: z.string().optional().describe("Deployment id; defaults to the current deployment")
+    deployment_id: z.string().trim().min(1).describe(
+      "Id of the deployment to delete (coderunner_get_status \u2192 deployment.id). Required: there is no default."
+    )
   },
+  DESTRUCTIVE,
   async (args) => {
     try {
-      const c = await cfg(args.workspace_id);
+      const c = await cfg();
       const id = await resolveCoderunnerId(
         c.apiUrl,
         c.workspaceId,
         args.coderunner_id
       );
-      let deploymentId = args.deployment_id?.trim();
-      if (!deploymentId) {
-        const current = await getDeployment(c.apiUrl, c.workspaceId, id);
-        deploymentId = current?.id?.trim();
-      }
-      if (!deploymentId) {
-        throw new Error(
-          `No current deployment for coderunner ${id}. Pass deployment_id.`
-        );
-      }
+      const deploymentId = args.deployment_id;
       await deleteCoderunnerDeployment(
         c.apiUrl,
         c.workspaceId,
@@ -1717,6 +2000,7 @@ server.tool(
         deploymentId
       );
       return text({
+        workspace_id: c.workspaceId,
         coderunner_id: id,
         deployment_id: deploymentId,
         deleted: true,
@@ -1735,6 +2019,7 @@ server.tool(
     coderunner_id: z.string().min(1),
     job_id: z.string().min(1)
   },
+  READ_ONLY,
   async (args) => {
     try {
       const c = await cfg(args.workspace_id);
@@ -1753,6 +2038,7 @@ server.tool(
   "apps_list",
   "List product Apps (Shell / standalone). Workloads are Coderunners, not Apps.",
   { workspace_id: wsId },
+  READ_ONLY,
   async ({ workspace_id }) => {
     try {
       const c = await cfg(workspace_id);
@@ -1766,6 +2052,7 @@ server.tool(
   "apps_get",
   "Get one product App by id or slug.",
   { workspace_id: wsId, app_id: z.string().min(1) },
+  READ_ONLY,
   async (args) => {
     try {
       const c = await cfg(args.workspace_id);
@@ -1783,6 +2070,7 @@ server.tool(
   "secrets_list",
   "List secret keys (values are not shown). To set/delete, use `gf secrets`.",
   { workspace_id: wsId, environment_id: z.string().optional() },
+  READ_ONLY,
   async (args) => {
     try {
       const c = await cfg(args.workspace_id);
@@ -1798,6 +2086,7 @@ server.tool(
   "flags_list",
   "List feature flags and values in one environment (omit environment_id \u2192 workspace default, dev; response echoes the resolved id). To set/delete/promote, use `gf flags`. docs_get id feature-flags for runtime use.",
   { workspace_id: wsId, environment_id: z.string().optional() },
+  READ_ONLY,
   async (args) => {
     try {
       const c = await cfg(args.workspace_id);
@@ -1813,6 +2102,7 @@ server.tool(
   "files_list",
   "List workspace files (read-only). Upload/download with `gf files`.",
   { workspace_id: wsId },
+  READ_ONLY,
   async ({ workspace_id }) => {
     try {
       const c = await cfg(workspace_id);
@@ -1824,17 +2114,45 @@ server.tool(
 );
 server.tool(
   "domains_list",
-  "List custom domains for a Coderunner service. Add/verify with `gf domains`.",
-  { workspace_id: wsId, coderunner_id: z.string().min(1) },
+  'List custom domains of a standalone App (the service-backed kind). Pass app_id (id or slug) or coderunner_id (the App\'s primary Coderunner). Standalone Coderunners have no domains of their own: the Coderunner domain routes always return 400 "Custom domains are available on Apps" and that server message is surfaced if hit. Shell apps have none. Add/verify with `gf domains` only for an App-backed service.',
+  {
+    workspace_id: wsId,
+    app_id: z.string().min(1).optional().describe("App id or slug"),
+    coderunner_id: z.string().min(1).optional().describe("Coderunner id or slug; resolves to the App whose primary Coderunner it is")
+  },
+  READ_ONLY,
   async (args) => {
     try {
+      if (!args.app_id && !args.coderunner_id) {
+        throw new Error("Pass app_id (id or slug) or coderunner_id.");
+      }
       const c = await cfg(args.workspace_id);
-      const id = await resolveCoderunnerId(
+      const listed = await listApps(c.apiUrl, c.workspaceId);
+      let match;
+      if (args.app_id) {
+        match = listed.apps.find(
+          (app) => app.id === args.app_id || app.slug === args.app_id
+        );
+        if (!match) throw new Error(`App not found: ${args.app_id}`);
+      } else {
+        const crId = await resolveCoderunnerId(
+          c.apiUrl,
+          c.workspaceId,
+          args.coderunner_id
+        );
+        match = listed.apps.find((app) => app.primary_coderunner_id === crId);
+        if (!match) {
+          throw new Error(
+            `Coderunner ${crId} is not the primary Coderunner of any App, and standalone Coderunners cannot have custom domains. Package it as an App first (gf apps create --kind standalone --primary-coderunner <id>).`
+          );
+        }
+      }
+      const domains = await cpGetJson(
         c.apiUrl,
-        c.workspaceId,
-        args.coderunner_id
+        c.token,
+        `/v1/workspaces/${encodeURIComponent(c.workspaceId)}/apps/${encodeURIComponent(match.id)}/coderunner/domains`
       );
-      return text(await listDomains(c.apiUrl, c.workspaceId, id));
+      return text({ app_id: match.id, app_slug: match.slug, ...domains });
     } catch (e) {
       return errText(e);
     }
@@ -1842,8 +2160,9 @@ server.tool(
 );
 server.tool(
   "dataplane_status",
-  "Dataplane setup status (Dataplane is how Groundfloor talks to databases, not a database itself). PostgreSQL (shared, platform-managed) is ready through it by default. Provision with `gf dataplane provision`.",
+  "Dataplane setup status for the workspace, as reported by Control Plane. Provision with `gf dataplane provision`. See docs_get id databases for what Dataplane is.",
   { workspace_id: wsId },
+  READ_ONLY,
   async ({ workspace_id }) => {
     try {
       const c = await cfg(workspace_id);
@@ -1853,10 +2172,73 @@ server.tool(
     }
   }
 );
+var accountId = z.string().optional().describe(
+  "Organization/account id (NOT the workspace id). Defaults to the account that owns the selected workspace."
+);
+async function resolveAccountId(c, explicit) {
+  if (explicit?.trim()) return explicit.trim();
+  const workspaces = await listWorkspaces(c.apiUrl);
+  const ws = workspaces.find((w) => w.id === c.workspaceId);
+  const id = ws?.account_id || ws?.organization_id;
+  if (!id) {
+    throw new Error(
+      "Could not determine the account for the selected workspace. Pass account_id (organization id)."
+    );
+  }
+  return id;
+}
+server.tool(
+  "quota_get",
+  "Plan tier and usage against plan limits (workspaces, file storage, activity-log events, \u2026) for the organization that owns the workspace. Account-scoped, not workspace-scoped; readable by organization members. Use when a create/deploy is refused for plan reasons.",
+  { workspace_id: wsId, account_id: accountId },
+  READ_ONLY,
+  async (args) => {
+    try {
+      const c = await cfg(args.workspace_id);
+      const id = await resolveAccountId(c, args.account_id);
+      return text(
+        await cpGetJson(
+          c.apiUrl,
+          c.token,
+          `/v1/accounts/${encodeURIComponent(id)}/quota`
+        )
+      );
+    } catch (e) {
+      return errText(e);
+    }
+  }
+);
+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.",
+  {
+    workspace_id: wsId,
+    account_id: accountId,
+    since_seconds: z.number().int().min(3600).max(400 * 86400).optional().describe("Lookback window in seconds (server default 30 days; min 1 hour, max ~13 months)")
+  },
+  READ_ONLY,
+  async (args) => {
+    try {
+      const c = await cfg(args.workspace_id);
+      const id = await resolveAccountId(c, args.account_id);
+      const qs = args.since_seconds ? `?since_seconds=${args.since_seconds}` : "";
+      return text(
+        await cpGetJson(
+          c.apiUrl,
+          c.token,
+          `/v1/accounts/${encodeURIComponent(id)}/billing/summary${qs}`
+        )
+      );
+    } catch (e) {
+      return errText(e);
+    }
+  }
+);
 server.tool(
   "docs_list",
   "Catalog of Groundfloor product docs (docs.groundfloor.cloud) the MCP can fetch.",
   { query: z.string().optional() },
+  READ_ONLY,
   async ({ query }) => {
     const hits = findDoc(query ?? "");
     return text({
@@ -1874,15 +2256,19 @@ server.tool(
 );
 server.tool(
   "docs_get",
-  "How-to for Coderunner, Shell, design-standard, css-and-styling, databases, access, m2m. 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.",
+  "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"
+    ),
+    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."
     )
   },
-  async ({ id }) => {
+  READ_ONLY,
+  async ({ id, offset }) => {
     try {
-      const entry = DOC_CATALOG.find((d) => d.id === id);
+      const entry = getDocById(id);
       if (!entry) {
         return errText(
           new Error(
@@ -1890,7 +2276,7 @@ server.tool(
           )
         );
       }
-      return text(await fetchDocPage(entry));
+      return text(await fetchDocPage(entry, offset ?? 0));
     } catch (e) {
       return errText(e);
     }
@@ -1898,7 +2284,7 @@ server.tool(
 );
 server.tool(
   "suggest_cli",
-  "Return the gf command to run. For a Shell App use intent init_app or publish_app (never scaffold App.tsx; never gf deploy). MCP does not execute mutations.",
+  "Return the gf command to run. For a Shell App use intent create_app, init_app or publish_app (publish_app is the full create + init + release + publish chain; never scaffold App.tsx; never gf deploy). MCP does not execute mutations.",
   {
     intent: z.enum([
       "login",
@@ -1909,6 +2295,7 @@ server.tool(
       "logs",
       "environments",
       "cancel_deployment",
+      "create_app",
       "init_app",
       "publish_app",
       "secrets",
@@ -1918,10 +2305,11 @@ server.tool(
       "m2m_token"
     ]),
     workspace: z.string().optional(),
-    name: z.string().optional().describe("Coderunner name/id for deploy/run/status/logs/cancel_deployment/vault_token"),
-    slug: z.string().optional().describe("Portal app slug for init_app / publish_app"),
+    name: z.string().optional().describe("Coderunner name/id for deploy/run/status/logs/cancel_deployment/vault_token; App display name for create_app / publish_app"),
+    slug: z.string().optional().describe("Portal app slug for create_app / init_app / publish_app"),
     cell: z.enum(["production", "stage", "dev"]).optional()
   },
+  READ_ONLY,
   async (args) => {
     return text(
       suggestCli(args.intent, {
@@ -1934,6 +2322,8 @@ server.tool(
     );
   }
 );
+
+// src/index.ts
 async function main() {
   const transport = new StdioServerTransport();
   await server.connect(transport);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@groundfloorcloud/mcp",
-  "version": "0.1.16",
+  "version": "0.2.1",
   "description": "Groundfloor MCP — inspect workspace state and docs; take actions with the gf CLI.",
   "type": "module",
   "bin": {
@@ -27,14 +27,14 @@
   "scripts": {
     "build": "tsup",
     "dev": "tsup --watch",
-    "typecheck": "tsup --silent",
+    "typecheck": "tsc --noEmit",
     "start": "node dist/index.js",
     "clean": "rm -rf dist *.tsbuildinfo .turbo",
     "prepublishOnly": "npm run build"
   },
   "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.12.1",
-    "zod": "^3.24.2"
+    "@modelcontextprotocol/sdk": "^1.23.0",
+    "zod": "^4.4.3"
   },
   "devDependencies": {
     "@types/node": "^20",