@centrali-io/centrali-mcp 4.4.5 → 4.4.6

package/dist/tools/describe.js

@@ -82,6 +82,9 @@ function registerDescribeTools(server) {
                                     "list_allowed_domains",
                                     "add_allowed_domain",
                                     "remove_allowed_domain",
+                                    "get_function_run",
+                                    "list_function_runs",
+                                    "get_compute_job_status",
                                 ],
                             },
                             smart_queries: {
@@ -161,8 +164,119 @@ function registerDescribeTools(server) {
                                     "accept_page_proposal",
                                 ],
                             },
+                            auth_providers: {
+                                summary: "External identity provider configuration for BYOT (Bring Your Own Token). Connect Clerk, Auth0, Okta, Keycloak, or any OIDC provider so your app's users can authenticate with their existing IdP and Centrali handles authorization via claim-based policies.",
+                                describeWith: "describe_auth_providers",
+                                tools: [
+                                    "list_auth_providers",
+                                    "get_auth_provider",
+                                    "create_auth_provider",
+                                    "update_auth_provider",
+                                    "delete_auth_provider",
+                                    "test_auth_provider",
+                                    "refresh_auth_provider_jwks",
+                                ],
+                            },
+                            service_accounts: {
+                                summary: "Machine identities for backend-to-backend API access. Create service accounts with client_credentials OAuth2 flow, manage roles and groups for fine-grained permissions, and introspect access with permission scanning.",
+                                describeWith: "describe_service_accounts",
+                                tools: [
+                                    "list_service_accounts",
+                                    "get_service_account",
+                                    "create_service_account",
+                                    "update_service_account_name",
+                                    "update_service_account_description",
+                                    "delete_service_account",
+                                    "rotate_service_account_secret",
+                                    "revoke_service_account",
+                                    "generate_dev_token",
+                                    "scan_service_account_permissions",
+                                    "simulate_service_account_permission",
+                                    "generate_remediation",
+                                    "preview_remediation",
+                                    "apply_remediation",
+                                    "list_service_account_roles",
+                                    "assign_role_to_service_account",
+                                    "remove_role_from_service_account",
+                                    "list_service_account_groups",
+                                    "add_service_account_to_group",
+                                    "remove_service_account_from_group",
+                                    "list_roles",
+                                    "get_role",
+                                    "create_role",
+                                    "update_role",
+                                    "delete_role",
+                                    "list_groups",
+                                    "get_group",
+                                    "create_group",
+                                    "update_group",
+                                    "delete_group",
+                                    "list_publishable_keys",
+                                    "get_publishable_key",
+                                    "create_publishable_key",
+                                    "update_publishable_key",
+                                    "revoke_publishable_key",
+                                    "get_current_identity",
+                                ],
+                            },
+                        },
+                        workflow: "Typical workflow: 1) Define collections → 2) Create records → 3) Write compute functions → 4) Wire orchestrations → 5) Build pages to surface data → 6) Publish pages for end users. When building an app, also: 7) Create a service account → 8) Grant least-privilege permissions via remediation → 9) Create publishable keys for the frontend.",
+                        app_credential_setup: {
+                            description: "When building an app that uses Centrali, you need credentials. The flow depends on whether the code runs server-side or client-side.",
+                            backend: {
+                                description: "Server-side apps (Next.js API routes, Node.js services) use service accounts.",
+                                flow: [
+                                    "1. create_service_account → get clientId + clientSecret",
+                                    "2. scan_service_account_permissions(filter='denied') → see what's missing",
+                                    "3. generate_remediation(sa, resource, category, actions) → get options to grant access",
+                                    "4. Pick the LEAST-PRIVILEGE option (prefer 'create_new' for exact permissions over broad role assignments)",
+                                    "5. apply_remediation → grant access",
+                                    "6. Use clientId/clientSecret in the SDK: new CentraliSDK({ clientId, clientSecret, ... })",
+                                ],
+                                principle: "ALWAYS grant least privilege. Only grant the exact resources and actions the app needs. Never assign a broad admin role when a narrow permission will do.",
+                            },
+                            frontend: {
+                                description: "Client-side apps (React, Vue, mobile) use publishable keys — safe to embed in code.",
+                                flow: [
+                                    "1. create_publishable_key with scoped access (e.g., records:list:products, records:retrieve:products)",
+                                    "2. Use the key in the SDK: new CentraliSDK({ publishableKey: 'pk_live_...', ... })",
+                                ],
+                                principle: "Publishable keys are already scoped. Only grant the specific collections and actions the UI needs. Write actions (create, execute) require explicit collection slugs — no wildcards.",
+                            },
+                        },
+                        docs: "Full documentation: https://docs.centrali.io — SDK guide, API reference, compute functions, orchestrations, and more.",
+                        feature_matrix: {
+                            description: "Not all features are available through all interfaces. Use this matrix to know which tool to use.",
+                            capabilities: {
+                                "Collections CRUD": { sdk: true, mcp: true, console: true },
+                                "Records CRUD": { sdk: true, mcp: true, console: true },
+                                "Compute functions": { sdk: true, mcp: true, console: true },
+                                "Triggers": { sdk: true, mcp: true, console: true },
+                                "Smart queries": { sdk: true, mcp: true, console: true },
+                                "Orchestrations": { sdk: true, mcp: true, console: true },
+                                "Pages": { sdk: "partial", mcp: true, console: true },
+                                "Realtime subscriptions (SSE)": { sdk: true, mcp: false, console: false, note: "SDK-only — use client.realtime.subscribe() in app code" },
+                                "Validation scans": { sdk: true, mcp: true, console: true },
+                                "Anomaly insights": { sdk: true, mcp: true, console: true },
+                                "Search": { sdk: true, mcp: true, console: true },
+                                "Function runs (execution history)": { sdk: true, mcp: true, console: true },
+                                "Service accounts & IAM": { sdk: false, mcp: true, console: true, note: "MCP tools for full SA lifecycle, roles, groups, and permission introspection" },
+                                "File uploads": { sdk: true, mcp: false, console: true, note: "SDK-only — use client.uploadFile() in app code" },
+                            },
+                        },
+                        sdk_integration: {
+                            description: "When building an app, use MCP tools to create backend resources (collections, functions, triggers, orchestrations) and the SDK in your app code to interact with them at runtime.",
+                            install: "npm install @centrali-io/centrali-sdk",
+                            nextjs_server: {
+                                description: "For Next.js API routes and server components, use service account auth.",
+                                code: "import { CentraliSDK } from '@centrali-io/centrali-sdk';\nconst centrali = new CentraliSDK({ baseUrl: 'https://centrali.io', workspaceId: 'your-workspace-slug', clientId: process.env.CENTRALI_CLIENT_ID, clientSecret: process.env.CENTRALI_CLIENT_SECRET });",
+                            },
+                            react_vite_client: {
+                                description: "For React + Vite browser apps, use a publishable key (safe to expose in client code).",
+                                code: "import { CentraliSDK } from '@centrali-io/centrali-sdk';\nconst centrali = new CentraliSDK({ baseUrl: 'https://centrali.io', workspaceId: 'your-workspace-slug', publishableKey: 'pk_live_your_key_here' });",
+                            },
+                            note: "workspaceId is the workspace slug (e.g., 'acme'), not a UUID. See https://docs.centrali.io/guides/centrali-sdk for the full guide.",
                         },
-                        workflow: "Typical workflow: 1) Define collections → 2) Create records → 3) Write compute functions → 4) Wire orchestrations → 5) Build pages to surface data → 6) Publish pages for end users.",
                     }, null, 2),
                 },
             ],
@@ -505,26 +619,93 @@ function registerDescribeTools(server) {
                             wildcards: "Use '*.example.com' to allow all subdomains of example.com",
                             note: "Functions can only make HTTP requests to domains on this list. Add domains before creating functions that call external APIs.",
                         },
+                        compute_input_contract: {
+                            description: "Every compute function has three globals: api, triggerParams, executionParams. What they contain depends on how the function was invoked.",
+                            signature: "async function run() { /* use api, triggerParams, executionParams */ return result; }",
+                            important: "Do NOT use module.exports. Always use 'async function run() { ... }'.",
+                            per_trigger_type: {
+                                "http-trigger": {
+                                    triggerParams: "Static params from trigger.triggerMetadata.params (set at trigger creation time)",
+                                    executionParams: "{ payload } — parsed request body from the incoming HTTP POST",
+                                },
+                                "endpoint": {
+                                    triggerParams: "Static params from trigger.triggerMetadata.params",
+                                    executionParams: "{ payload, method, headers, query } — full HTTP request context",
+                                },
+                                "scheduled": {
+                                    triggerParams: "Static params from trigger.triggerMetadata.params (max 64KB)",
+                                    executionParams: "{} — empty (no request context for scheduled runs)",
+                                },
+                                "on-demand": {
+                                    triggerParams: "Static params from trigger.triggerMetadata.params",
+                                    executionParams: "{ payload } — the payload passed to invoke_trigger",
+                                },
+                                "pages-action": {
+                                    triggerParams: "{ input, token } — from page action invocation",
+                                    executionParams: "{} — empty",
+                                },
+                                "orchestration-step": {
+                                    triggerParams: "Merged: orchestration input + previous step outputs + decrypted encrypted params",
+                                    executionParams: "Not used — all input arrives via triggerParams for orchestration steps",
+                                },
+                            },
+                        },
                         sandbox_api: {
-                            description: "Functions receive an `api` object with built-in utilities. Key crypto methods:",
+                            description: "Functions receive an `api` object with built-in utilities.",
+                            records: "api.queryRecords, api.fetchRecord, api.createRecord, api.updateRecord, api.deleteRecord, api.bulkCreateRecords, api.bulkUpdateRecords, api.bulkDeleteRecords",
+                            http: "api.httpRequest, api.httpFetch — outbound calls to allowed domains only",
+                            files: "api.storeFile, api.storeAsCSV, api.storeAsJSON",
                             crypto: {
                                 "api.crypto.sha256(data)": "SHA256 hash → base64 string",
                                 "api.crypto.hmacSha256(key, data, options?)": "HMAC-SHA256 → base64 string. options: { keyEncoding: 'utf8' | 'base64' }",
                                 "api.crypto.rsaSign(privateKeyPem, data, algorithm?)": "RSA signature → base64url string. algorithm: 'RS256' (default), 'RS384', 'RS512'",
                                 "api.crypto.signJwt(privateKeyPem, payload, options?)": "Build + sign a JWT → 'header.payload.signature'. options: { algorithm, expiresIn (seconds), issuer }",
                             },
-                            note: "Private keys should be stored as encrypted trigger params. signJwt automatically sets iat and supports RS256/RS384/RS512.",
+                            utilities: "api.uuid, api.formatDate, api.chunk, api.merge, api.math, api.evaluate, api.renderTemplate, api.log, api.logError, api.toCSV, api.toJSON",
+                        },
+                        secrets: {
+                            description: "Compute functions have NO built-in environment variables or secrets field.",
+                            recommended: "Wrap the function in an orchestration and use encrypted params on the compute step. Encrypted params are stored with AES-256-GCM at rest, decrypted at execution time, and arrive in triggerParams.",
+                            alternative: "Pass secrets in the trigger invocation payload via executionParams. This works but means the calling app is the courier for the secret.",
+                            encrypted_params_flow: "Create orchestration → add compute step with encryptedParams: { API_KEY: { value: 'secret', encrypt: true } } → at execution, API_KEY arrives decrypted in triggerParams.API_KEY",
+                        },
+                        async_execution: {
+                            description: "Trigger invocation is ASYNCHRONOUS. invoke_trigger returns a job ID, not the execution result. There are two ways to get the result.",
+                            path_1_realtime: {
+                                description: "SDK realtime subscription (recommended for apps). Subscribe to run status events via SSE — no polling needed. The SDK handles reconnection automatically.",
+                                when_to_use: "In your app code (Next.js, React, Node.js server). Best for dashboards and UIs that need to show run progress in real-time.",
+                                how: "Use client.realtime.subscribe() in your app to listen for function run completion events keyed by the jobId.",
+                                note: "Realtime is SDK-only — not available through MCP.",
+                            },
+                            path_2_polling: {
+                                description: "Poll with get_compute_job_status(jobId) (recommended for MCP and scripts).",
+                                when_to_use: "In MCP tool calls, CLI scripts, or any context where you can't hold a realtime connection.",
+                                flow: "1) Call invoke_trigger → get jobId. 2) Call get_compute_job_status(jobId) to check state. 3) Repeat until state is 'completed' or 'failed'.",
+                            },
+                            job_statuses: "queued → running → completed | failed",
+                            tools: {
+                                get_compute_job_status: "Poll by job ID — returns state, returnValue (on success), failedReason (on failure). This is the direct way to check a specific invocation.",
+                                get_function_run: "Get a function run by its run UUID — returns detailed status, output (runData), errors, timing, memory/CPU usage",
+                                list_function_runs: "List runs by triggerId or functionId — useful for browsing execution history",
+                            },
+                            tip: "For orchestration workflows, use get_orchestration_run(includeSteps=true) instead — it shows step-by-step execution with inputs/outputs.",
+                        },
+                        success_vs_failure: {
+                            description: "Compute functions can fail in two ways. The distinction matters for debugging.",
+                            throw: "Throwing an error → run status = 'failure', errorMessage populated. Use for unexpected errors.",
+                            return_error: "Returning { ok: false, ... } → run status = 'completed', but the business action failed. Use for expected failures (e.g., provider returned 403).",
+                            recommendation: "For provider-backed calls (Resend, Stripe, etc.), check the response status and return { ok: false, status, body } so the caller can diagnose. Only throw for truly unexpected errors.",
                         },
                         tips: [
                             "Use list_functions to see all available functions",
                             "Use list_triggers to see how functions are wired to execution events",
                             "Only on-demand triggers can be invoked via invoke_trigger — other types fire automatically",
-                            "Functions receive the trigger payload in their execution context",
-                            "Use pause_trigger/resume_trigger to temporarily disable triggers without deleting them",
                             "Use test_function to validate code before creating or updating a function",
                             "Use create_function + create_trigger together to set up a complete compute pipeline",
+                            "Use get_function_run or list_function_runs to check execution results after invoking a trigger",
                             "Use api.crypto.signJwt() for GitHub App, Google Cloud, or Azure AD authentication flows",
                             "Before creating functions that call external APIs, add the target domains with add_allowed_domain",
+                            "For secrets (API keys, credentials), use orchestration encrypted params — see the 'secrets' section above",
                         ],
                     }, null, 2),
                 },
@@ -1675,4 +1856,317 @@ function registerDescribeTools(server) {
             ],
         });
     }));
+    // ── Auth Providers (BYOT) ──────────────────────────────────────────
+    server.tool("describe_auth_providers", "Get the full reference for configuring external auth providers (BYOT — Bring Your Own Token). Explains how to connect Clerk, Auth0, Okta, or any OIDC provider so your app's users authenticate with their existing IdP while Centrali handles authorization.", {}, () => __awaiter(this, void 0, void 0, function* () {
+        return ({
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify({
+                        domain: "External Auth Providers (BYOT)",
+                        description: "BYOT (Bring Your Own Token) lets your app keep using Clerk, Auth0, Okta, or any OIDC provider for authentication while Centrali handles fine-grained authorization. No user duplication, no token exchange — just pass the JWT.",
+                        how_it_works: {
+                            step1: "User authenticates via your IdP (Clerk, Auth0, Okta, etc.) → receives a JWT",
+                            step2: "Your app passes the JWT to Centrali in the Authorization header",
+                            step3: "Centrali validates the JWT signature via the provider's JWKS (auto-discovered and cached)",
+                            step4: "Centrali extracts claims using your configured claim mappings (e.g., org_role → ext_role)",
+                            step5: "Authorization policies evaluate using extracted claims (ext_* attributes)",
+                            step6: "Centrali returns Allow or Deny",
+                        },
+                        blog_guide: "https://centrali.io/blog/byot-bring-your-own-token-external-idp",
+                        docs: "https://docs.centrali.io/guides/external-auth",
+                        provider_types: {
+                            clerk: "Clerk — auto-discovers JWKS from issuer URL (https://clerk.your-domain.com)",
+                            auth0: "Auth0 — auto-discovers JWKS from issuer URL (https://your-tenant.auth0.com/)",
+                            okta: "Okta — auto-discovers JWKS from issuer URL (https://your-org.okta.com)",
+                            keycloak: "Keycloak — auto-discovers JWKS from issuer URL",
+                            oidc: "Any OIDC-compliant provider — auto-discovers JWKS from issuer's .well-known/openid-configuration",
+                            custom: "Custom JWT issuer — requires manual jwksUrl",
+                        },
+                        provider_shape: {
+                            id: "UUID — auto-generated",
+                            name: "string — display name",
+                            slug: "string — URL-safe unique identifier",
+                            providerType: "'oidc' | 'clerk' | 'auth0' | 'keycloak' | 'okta' | 'custom'",
+                            issuer: "string (URL) — JWT issuer. Must match the 'iss' claim in tokens. Unique per workspace.",
+                            jwksUrl: "string (URL) | null — override JWKS URL (usually auto-discovered from issuer)",
+                            allowedAudiences: "string[] — if set, tokens must include a matching 'aud' claim",
+                            clockSkewSeconds: "number — tolerance for token expiration (default: 60, max: 300)",
+                            allowedAlgorithms: "string[] — accepted signing algorithms (default: ['RS256'])",
+                            claimMappings: "ClaimMapping[] — defines how JWT claims map to policy attributes",
+                            allowedOrigins: "string[] — CORS origins for browser requests",
+                            isActive: "boolean — inactive providers reject all tokens",
+                        },
+                        claim_mappings: {
+                            description: "Claim mappings extract values from JWT tokens and make them available as ext_<attribute> in authorization policies.",
+                            shape: {
+                                attribute: "string — becomes ext_<attribute> in policies. Example: 'role' → ext_role. Must start with a letter, alphanumeric + underscores only. Do NOT include the ext_ prefix — it's added automatically.",
+                                jwtPath: "string — dot-notation path into the JWT payload. Examples: 'org_role', 'metadata.plan', 'organization.role'",
+                                required: "boolean (default: false) — if true, token validation fails when this claim is missing",
+                                defaultValue: "string | number | boolean | string[] — fallback when claim is absent",
+                                transform: "'lowercase' | 'uppercase' | 'string' | 'boolean' | 'array' — applied to extracted value",
+                            },
+                            examples: [
+                                { attribute: "role", jwtPath: "org_role", description: "Maps JWT org_role claim → ext_role in policies" },
+                                { attribute: "plan", jwtPath: "metadata.plan", description: "Maps nested metadata.plan → ext_plan" },
+                                { attribute: "department", jwtPath: "user.public_metadata.department", defaultValue: "general", description: "Deep path with fallback" },
+                            ],
+                        },
+                        clerk_setup: {
+                            description: "Step-by-step guide for Clerk integration.",
+                            steps: [
+                                "1. In Clerk Dashboard → Configure → JWT Templates, create a template named 'centrali' with the claims you need",
+                                "2. Example JWT template: { \"org_id\": \"{{org.id}}\", \"org_role\": \"{{org.role}}\", \"metadata\": { \"plan\": \"{{user.public_metadata.plan}}\" } }",
+                                "3. Create the auth provider in Centrali: create_auth_provider with providerType='clerk', issuer='https://clerk.your-domain.com'",
+                                "4. Add claim mappings: [{ attribute: 'role', jwtPath: 'org_role' }, { attribute: 'plan', jwtPath: 'metadata.plan' }]",
+                                "5. In your Next.js app, get the token: const token = await getToken({ template: 'centrali' })",
+                                "6. Pass the token to Centrali SDK: centrali.checkAuthorization({ token, resource: 'orders', action: 'approve' })",
+                            ],
+                            nextjs_example: "import { auth } from '@clerk/nextjs/server';\nimport { CentraliSDK } from '@centrali-io/centrali-sdk';\n\nconst centrali = new CentraliSDK({ baseUrl: 'https://centrali.io', workspaceId: 'your-workspace-slug', });\n\nexport async function POST(request: Request) {\n  const { getToken } = await auth();\n  const token = await getToken({ template: 'centrali' });\n  const result = await centrali.checkAuthorization({ token, resource: 'premium-features', action: 'access' });\n  if (!result.data.allowed) return Response.json({ error: 'Upgrade to premium' }, { status: 403 });\n  return Response.json({ data: '...' });\n}",
+                        },
+                        policy_attributes: {
+                            description: "Attributes available in authorization policies when using external tokens.",
+                            attributes: {
+                                "ext_*": "Claims extracted via claim mappings (e.g., ext_role, ext_plan)",
+                                "is_external_principal": "Always true for external tokens",
+                                "external_issuer": "The JWT issuer URL",
+                                "external_subject": "The JWT subject (sub) claim",
+                                "request_metadata.*": "Context values passed via the context parameter in checkAuthorization()",
+                            },
+                        },
+                        policy_example: {
+                            description: "Example policy that allows premium users to access a feature.",
+                            policy: {
+                                name: "premium_access",
+                                specification: {
+                                    rules: [
+                                        {
+                                            rule_id: "premium-allow",
+                                            effect: "Allow",
+                                            conditions: [
+                                                { function: "string_equal", attribute: "ext_plan", value: "premium" },
+                                            ],
+                                        },
+                                    ],
+                                    default: { effect: "Deny" },
+                                },
+                            },
+                        },
+                        tools: {
+                            list_auth_providers: "List all configured providers",
+                            get_auth_provider: "Get provider details including claim mappings",
+                            create_auth_provider: "Create a new provider (Clerk, Auth0, Okta, OIDC, etc.)",
+                            update_auth_provider: "Update provider config (mappings, audiences, active status)",
+                            delete_auth_provider: "Delete a provider (tokens will be rejected)",
+                            test_auth_provider: "Test claim extraction with a sample JWT — validates your mappings without affecting production",
+                            refresh_auth_provider_jwks: "Force refresh JWKS cache after key rotation",
+                        },
+                        tips: [
+                            "Call create_auth_provider first, then test_auth_provider with a real JWT to validate claim mappings before deploying",
+                            "Claim attributes are automatically prefixed with ext_ — if you map attribute 'role', it becomes ext_role in policies",
+                            "JWKS is auto-discovered from the issuer URL for standard providers — you rarely need to set jwksUrl manually",
+                            "Use test_auth_provider to debug claim extraction without affecting production traffic",
+                            "Use allowedAudiences to restrict which apps can use this provider (matches the JWT 'aud' claim)",
+                            "Set isActive to false to temporarily disable a provider without deleting it",
+                            "For Clerk: create a JWT template in the Clerk Dashboard and retrieve tokens with getToken({ template: 'centrali' })",
+                        ],
+                    }, null, 2),
+                },
+            ],
+        });
+    }));
+    // ── Service Accounts & IAM ──────────────────────────────────────
+    server.tool("describe_service_accounts", "Get the full reference for managing service accounts, roles, groups, and permissions. Explains the complete IAM setup flow from creating a service account to granting fine-grained access.", {}, () => __awaiter(this, void 0, void 0, function* () {
+        return ({
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify({
+                        domain: "Service Accounts & IAM",
+                        description: "Service accounts are machine identities for backend-to-backend API access. They authenticate via OAuth2 client_credentials flow and receive permissions through roles and groups.",
+                        setup_flow: {
+                            description: "End-to-end flow for setting up a service account for a new app with least-privilege permissions.",
+                            steps: [
+                                "1. Create a service account: create_service_account — returns clientId + clientSecret (secret shown ONCE)",
+                                "2. Identify what the app needs: which collections it reads/writes, which triggers it invokes, which files it accesses",
+                                "3. Grant exactly those permissions: generate_remediation → pick the LEAST-PRIVILEGE option (prefer 'create_new' for exact access) → apply_remediation",
+                                "4. Verify: scan_service_account_permissions(filter='denied') — the only denied items should be things the app doesn't need",
+                                "5. Use the credentials: new CentraliSDK({ clientId, clientSecret, ... }) in your app",
+                            ],
+                            least_privilege_principle: "ALWAYS grant the minimum permissions needed. When generate_remediation returns multiple options, prefer 'create_new' (creates a minimal policy for exactly the requested access) over 'role_assignment' (which may grant broader access than needed). Only use role_assignment if the existing role exactly matches what you need.",
+                        },
+                        authentication: {
+                            production: {
+                                description: "OAuth2 client_credentials flow — standard, secure, auto-refreshing.",
+                                flow: "POST /iam/oauth2/token with grant_type=client_credentials, client_id, client_secret → receives JWT access token",
+                                sdk_example: "const centrali = new CentraliSDK({ baseUrl: 'https://centrali.io', workspaceId: 'acme', clientId: 'ci_...', clientSecret: 'sk_...' }); // SDK handles token refresh automatically",
+                            },
+                            development: {
+                                description: "Dev tokens — short-lived tokens for testing without the OAuth2 flow.",
+                                tool: "generate_dev_token(serviceAccountId, ttlSeconds)",
+                                note: "Dev tokens have limited TTL. For production, always use client_credentials flow.",
+                            },
+                        },
+                        service_account_shape: {
+                            id: "number — auto-generated numeric ID",
+                            clientId: "string — format: ci_<hex> — used as the client_id in OAuth2",
+                            clientSecret: "string — format: sk_<hex> — ONLY returned on creation and rotation",
+                            name: "string — display name",
+                            description: "string | null — optional description",
+                            workspaceSlug: "string — workspace this SA belongs to",
+                            revoked: "boolean — if true, all tokens are invalid and no new tokens can be issued",
+                            createdBy: "string — user ID who created this SA",
+                            createdAt: "string — ISO 8601 timestamp",
+                        },
+                        permission_model: {
+                            description: "Permissions flow: Service Account → Roles → Permissions. Groups are optional bundles of SAs.",
+                            role: {
+                                description: "A named bundle of permissions. Roles are assigned directly to SAs or inherited through groups.",
+                                shape: {
+                                    id: "UUID",
+                                    name: "string (e.g., 'Data Reader', 'Compute Admin')",
+                                    description: "string | null",
+                                    permissions: "string[] — permission UUIDs",
+                                },
+                            },
+                            group: {
+                                description: "A named bundle of service accounts. Roles assigned to a group are inherited by all SAs in it.",
+                                shape: {
+                                    id: "UUID",
+                                    name: "string (e.g., 'Backend Services')",
+                                    description: "string | null",
+                                },
+                            },
+                            permission_actions: [
+                                "create — create new resources",
+                                "retrieve — read a single resource by ID",
+                                "list — list/query resources",
+                                "update — modify existing resources",
+                                "delete — remove resources",
+                                "execute — run compute functions, invoke triggers",
+                                "manage — administrative actions (e.g., generate dev tokens)",
+                            ],
+                            common_resources: [
+                                "workspace::records",
+                                "workspace::structures",
+                                "workspace::compute-functions",
+                                "workspace::function-triggers",
+                                "workspace::orchestrations",
+                                "workspace::smart-queries",
+                                "workspace::pages",
+                                "workspace::service-accounts",
+                                "workspace::roles",
+                                "workspace::groups",
+                                "workspace::files",
+                                "workspace::search",
+                            ],
+                        },
+                        introspection: {
+                            scan: "scan_service_account_permissions — full access matrix showing every resource/action with Allow/Deny and reasons",
+                            simulate: "simulate_service_account_permission — test a specific resource+action, get evaluation trace and suggestions for granting access",
+                            tip: "Use scan with filter='denied' to find exactly what permissions a SA is missing, then use the remediation flow to grant them.",
+                        },
+                        remediation_flow: {
+                            description: "The recommended way to grant permissions. Instead of manually creating roles and policies, use the remediation wizard — it finds the best option automatically.",
+                            steps: [
+                                "1. Identify the gap: scan_service_account_permissions(filter='denied') or simulate_service_account_permission",
+                                "2. Generate options: generate_remediation(serviceAccountId, resource, resourceCategory, actions) — returns multiple options ranked by effort (low/medium/high) with a recommended pick",
+                                "3. Preview changes: preview_remediation(same args + chosen option) — shows exactly what would be created/modified without making changes",
+                                "4. Apply: apply_remediation(same args + chosen option) — creates roles/policies/assignments and verifies access was granted",
+                            ],
+                            option_types: {
+                                role_assignment: "Assign an existing role that already covers the needed permissions (effort: low)",
+                                group_assignment: "Add the SA to a group that has the right role (effort: low)",
+                                create_new: "Create a minimal new policy + permission + role for exactly the requested access (effort: medium-high)",
+                            },
+                            tip: "Always prefer the 'recommended' option. If multiple options exist, role_assignment is usually lowest effort. The response includes sideEffects showing what additional access the SA would gain.",
+                        },
+                        secret_management: {
+                            creation: "clientSecret shown ONCE at creation — store securely immediately",
+                            rotation: "rotate_service_account_secret — old secret immediately invalidated, new one returned (shown once)",
+                            revocation: "revoke_service_account — permanent, cannot be undone, all tokens invalidated",
+                        },
+                        tools: {
+                            lifecycle: {
+                                list_service_accounts: "List all SAs in the workspace",
+                                get_service_account: "Get SA details (no secret)",
+                                create_service_account: "Create SA — returns clientId + clientSecret",
+                                update_service_account_name: "Update SA display name",
+                                update_service_account_description: "Update SA description",
+                                delete_service_account: "Permanently delete SA",
+                                rotate_service_account_secret: "Generate new secret, invalidate old one",
+                                revoke_service_account: "Permanently disable SA",
+                                generate_dev_token: "Short-lived token for testing",
+                            },
+                            permissions: {
+                                scan_service_account_permissions: "Full access matrix audit",
+                                simulate_service_account_permission: "Test specific resource+action check",
+                                generate_remediation: "Generate options to grant missing access (role assignment, group assignment, or new policy)",
+                                preview_remediation: "Preview what changes an option would make (dry run)",
+                                apply_remediation: "Apply a remediation option to actually grant access (creates roles/policies as needed)",
+                            },
+                            roles: {
+                                list_roles: "List all roles",
+                                get_role: "Get role details with permissions",
+                                create_role: "Create role with permissions",
+                                update_role: "Update role name/description/permissions",
+                                delete_role: "Delete role",
+                                list_service_account_roles: "List roles assigned to a SA",
+                                assign_role_to_service_account: "Assign role to SA",
+                                remove_role_from_service_account: "Remove role from SA",
+                            },
+                            groups: {
+                                list_groups: "List all groups",
+                                get_group: "Get group details",
+                                create_group: "Create group",
+                                update_group: "Update group name/description",
+                                delete_group: "Delete group",
+                                list_service_account_groups: "List groups a SA belongs to",
+                                add_service_account_to_group: "Add SA to group",
+                                remove_service_account_from_group: "Remove SA from group",
+                            },
+                        },
+                        publishable_keys: {
+                            description: "Frontend-safe API keys for browser/client-side apps. Scoped to specific collections, actions, and triggers.",
+                            key_format: "pk_live_<hex> — safe to embed in client-side code, scoped and rate-limited",
+                            scope_format: {
+                                description: "Scopes control what the key can access. Format: resource:action:target",
+                                examples: [
+                                    "records:list:products — list products collection",
+                                    "records:retrieve:* — read any collection (wildcard OK for reads)",
+                                    "records:create:orders — create orders (write actions require explicit slug)",
+                                    "triggers:execute:send-email — invoke a specific HTTP trigger",
+                                    "files:retrieve — read files (two-part scope, no target)",
+                                    "collections:list — list collection schemas",
+                                ],
+                                rules: [
+                                    "Write actions (create, execute) require explicit collection/trigger slugs — no wildcards",
+                                    "Read actions (retrieve, list) allow wildcard targets (*)",
+                                    "Any records scope auto-grants collections:retrieve for that collection (schema access)",
+                                ],
+                            },
+                            tools: {
+                                list_publishable_keys: "List all publishable keys",
+                                get_publishable_key: "Get key details with scopes",
+                                create_publishable_key: "Create a new scoped key",
+                                update_publishable_key: "Update label or scopes",
+                                revoke_publishable_key: "Revoke a key (immediate, irreversible)",
+                            },
+                        },
+                        tips: [
+                            "LEAST PRIVILEGE: When granting permissions, only grant what the app actually needs. Use generate_remediation → prefer 'create_new' for exact access rather than broad role assignments.",
+                            "Use scan_service_account_permissions with filter='denied' to find missing permissions, then use the remediation flow to grant them",
+                            "Use simulate_service_account_permission to test before deploying — it shows the evaluation trace so you can debug policy decisions",
+                            "For frontend apps, use publishable keys (create_publishable_key) with scoped access — never expose service account credentials in client code",
+                            "For backend apps, use service accounts — they authenticate via OAuth2 client_credentials",
+                            "Group SAs by function (e.g., 'Backend Services', 'Analytics Pipeline') and assign roles to groups for easier management",
+                            "Always rotate secrets via rotate_service_account_secret rather than creating a new SA — preserves role/group assignments",
+                            "For development, use generate_dev_token instead of hardcoding client credentials in test scripts",
+                            "The clientSecret is only shown once — at creation and rotation. If lost, rotate to get a new one.",
+                        ],
+                    }, null, 2),
+                },
+            ],
+        });
+    }));
 }