@centrali-io/centrali-mcp 4.2.12 → 4.2.13

package/dist/tools/describe.js

@@ -633,7 +633,18 @@ function registerDescribeTools(server) {
                                     onFailure: "{ nextStepId: string } | null — step to execute on failure",
                                     retryConfig: "{ maxRetries, delayMs } | null — automatic retry on failure",
                                     timeoutMs: "number | null — step execution timeout",
+                                    encryptedParams: "Record<string, { value: string, encrypt: true }> | null — secrets (API keys, tokens) encrypted at rest, decrypted into triggerParams at execution time",
                                 },
+                                encrypted_params_notes: [
+                                    "To add a secret: { KEY: { value: 'plaintext', encrypt: true } }",
+                                    "Values are encrypted before storage — never stored in plaintext",
+                                    "API responses mask values as '********'",
+                                    "At execution time, decrypted values are merged into triggerParams — the function sees them identically to trigger params",
+                                    "To update: send { KEY: { value: 'new-plaintext', encrypt: true } }",
+                                    "To preserve existing: send { KEY: { value: '********', encrypted: true, keyVersion: N } }",
+                                    "To remove: omit the key from encryptedParams",
+                                    "Only valid on compute steps — rejected on decision and delay steps",
+                                ],
                             },
                             decision: {
                                 description: "Conditional branching based on input/output values",
@@ -705,6 +716,9 @@ function registerDescribeTools(server) {
                                         type: "compute",
                                         functionId: "func-uuid",
                                         onSuccess: { nextStepId: "check-result" },
+                                        encryptedParams: {
+                                            API_KEY: { value: "sk_live_...", encrypt: true },
+                                        },
                                     },
                                     decision_step: {
                                         id: "check-result",
@@ -754,6 +768,7 @@ function registerDescribeTools(server) {
                             "Use correlationId when triggering to trace runs across systems",
                             "Terminal steps: a compute step with no onSuccess and no subsequent step in the array will complete the run. No special 'end' step type is needed.",
                             "Decision step conditions use 'path' (not 'field') and 'op' (not 'operator'). Paths use dot notation: 'input.fieldName' or 'steps.stepId.output.fieldName'.",
+                            "Use encryptedParams on compute steps to pass secrets (API keys, tokens) — they're encrypted at rest and decrypted into triggerParams at execution time.",
                         ],
                     }, null, 2),
                 },
@@ -871,7 +886,6 @@ function registerDescribeTools(server) {
                                 description: "Single-record view — shows all fields of one record with optional related data and actions.",
                                 typical_sections: ["hero", "content", "supporting"],
                                 typical_blocks: [
-                                    "detail-fields",
                                     "field-display",
                                     "related-list",
                                     "activity-feed",
@@ -882,18 +896,8 @@ function registerDescribeTools(server) {
                             form: {
                                 description: "Data entry form — lets users create or update records with validation and submission actions.",
                                 typical_sections: ["content", "actions"],
-                                typical_blocks: [
-                                    "form",
-                                    "field-group",
-                                    "text-input",
-                                    "number-input",
-                                    "select",
-                                    "checkbox",
-                                    "date-picker",
-                                    "textarea",
-                                    "file-upload",
-                                ],
-                                validation_requirement: "Form pages must have at least one field block (text-input, number-input, select, checkbox, date-picker, textarea, file-upload, field, field-group, or field-display) to pass publishing validation.",
+                                typical_blocks: ["field-group", "markdown", "static-html"],
+                                IMPORTANT: "Use 'field-group' blockType with a 'fields' array. Do NOT use individual field block types (text-input, select, etc.) — the runtime only renders fields from field-group's fields array.",
                                 use_when: "You need users to input or edit data",
                             },
                             dashboard: {
@@ -1004,29 +1008,22 @@ function registerDescribeTools(server) {
                             filterableColumns: "string[] | null — which columns users can filter on (for data-table blocks)",
                         },
                         data_source_shape: {
-                            type: "'structure' | 'query'",
-                            ref: "string — the collection ID (UUID) for 'structure' type, or smart query ID for 'query' type",
-                            mode: "'list' | 'single' | 'aggregate' — how to fetch data. 'list' returns multiple records, 'single' returns one, 'aggregate' returns computed values.",
+                            type: "'structure' — the data source type",
+                            ref: "string — the collection ID (UUID)",
+                            recordSlug: "string | undefined — the collection's record slug for direct resolution (avoids an extra lookup). Recommended.",
                             config: {
-                                fields: "string[] | null — specific fields to fetch (null = all fields)",
-                                fieldOrder: "string[] | null — display order for fields",
-                                filters: "object | null — same filter syntax as query_records (data.field[operator]: value)",
+                                description: "Optional query configuration",
+                                filter: "object | null — same filter syntax as query_records",
                                 sort: "SortConfig[] | null — array of { field, direction: 'asc' | 'desc' }",
-                                limit: "number | null — max records to fetch",
                                 page: "number | null — for pagination",
                                 pageSize: "number | null — records per page",
                             },
                             aggregation: {
-                                description: "Only used when mode is 'aggregate'. Defines computations over the data.",
+                                description: "For metric/chart blocks. Defines computations over the data.",
                                 operations: "Record<string, { count?: '*', sum?: 'fieldName', avg?: 'fieldName', min?: 'fieldName', max?: 'fieldName' }>",
                                 groupBy: "string[] | null — fields to group by",
                             },
-                        },
-                        presentation_shape: {
-                            density: "'compact' | 'comfortable' | 'spacious' — controls spacing/padding",
-                            columns: "string[] — which columns to show (for table blocks)",
-                            chartType: "'bar' | 'line' | 'pie' — for chart blocks",
-                            emphasisRules: "EmphasisRule[] — conditional formatting rules: { field, operator, threshold, severity }",
+                            mode: "'list' | 'single' | 'aggregate' — optional. Set to 'aggregate' for metric-card and chart blocks that use aggregation. For list and detail pages, mode is inferred from context.",
                         },
                         narrative_shape: {
                             primaryQuestion: "string — the business question this block answers (e.g., 'How are sales trending?')",
@@ -1049,20 +1046,14 @@ function registerDescribeTools(server) {
                                             dataSource: {
                                                 type: "structure",
                                                 ref: "<collection-uuid>",
-                                                mode: "list",
-                                                config: {
-                                                    fields: [
-                                                        "name",
-                                                        "email",
-                                                        "status",
-                                                        "createdAt",
-                                                    ],
-                                                    sort: [{ field: "createdAt", direction: "desc" }],
-                                                    pageSize: 25,
-                                                },
+                                                recordSlug: "customers",
                                             },
-                                            presentation: { density: "comfortable" },
-                                            filterableColumns: ["status", "name"],
+                                            columns: [
+                                                { key: "name", label: "Name", filterable: true, sortable: true },
+                                                { key: "email", label: "Email", sortable: true },
+                                                { key: "status", label: "Status", filterable: true, sortable: true },
+                                                { key: "createdAt", label: "Created", sortable: true },
+                                            ],
                                         },
                                     ],
                                 },
@@ -1153,42 +1144,56 @@ function registerDescribeTools(server) {
                     text: JSON.stringify({
                         domain: "Page Block Types",
                         description: "Blocks are the UI components inside page sections. Each blockType has its own configuration requirements.",
+                        IMPORTANT_config_convention: "Block-type-specific config uses named properties on the block object (e.g., block.kanbanConfig, block.chartConfig), NOT a generic 'config' key. This is critical — using 'config' instead of the named property will silently fail.",
                         block_types: {
                             "data-table": {
-                                description: "Tabular data display with columns, sorting, filtering, and pagination. The primary block for list pages.",
-                                dataSource: "Required — type: 'structure', mode: 'list'",
-                                config: {
-                                    columns: "{ field: string, label: string, sortable?: boolean }[] — column definitions",
-                                    defaultSort: "{ field: string, direction: 'asc' | 'desc' } — initial sort",
-                                    pageSize: "number — rows per page (default: 25)",
-                                    rowClickAction: "BlockAction | null — action when a row is clicked (typically navigate-to-page)",
+                                description: "Tabular data display with columns, sorting, filtering, and pagination. The primary block for list and dashboard pages.",
+                                dataSource: "Required — type: 'structure'. Add recordSlug for direct resolution.",
+                                columns: "{ key: string, label: string, filterable?: boolean, sortable?: boolean }[] — column definitions on the block object. Used by both the publish validator and the runtime renderer.",
+                                example: {
+                                    id: "<uuid>",
+                                    blockType: "data-table",
+                                    dataSource: { type: "structure", ref: "<collection-uuid>", recordSlug: "my-records" },
+                                    columns: [
+                                        { key: "name", label: "Name", filterable: true, sortable: true },
+                                        { key: "status", label: "Status", filterable: true, sortable: true },
+                                        { key: "createdAt", label: "Created", sortable: true },
+                                    ],
                                 },
-                                presentation: "density, columns, emphasisRules",
-                                filterableColumns: "string[] — columns users can filter on",
                             },
                             "metric-card": {
                                 description: "Single KPI metric display — shows a number with label, optional trend, and thresholds.",
-                                dataSource: "Required — type: 'structure', mode: 'aggregate' with a single aggregation",
-                                config: {
-                                    aggregation: "'count' | 'sum' | 'average' | 'min' | 'max'",
-                                    valueField: "string — field to aggregate (not needed for 'count')",
-                                    label: "string — display label for the metric",
-                                    format: "'number' | 'currency' | 'percentage' — value formatting",
-                                    trend: "{ enabled: boolean, comparison: 'previous-period' }",
-                                    thresholds: "{ green?: [min, max], amber?: [min, max], red?: [min, max] } — color-code the value",
+                                dataSource: "Required — type: 'structure', mode: 'aggregate' with aggregation.operations in the dataSource",
+                                label: "string — display label for the metric, placed directly on the block object",
+                                metricConfig: {
+                                    format: "'number' | 'currency' | 'percentage' — value formatting (optional)",
+                                    thresholds: "{ green?: [min, max], amber?: [min, max], red?: [min, max] } — color-code the value (optional)",
+                                },
+                                example: {
+                                    id: "<uuid>",
+                                    blockType: "metric-card",
+                                    label: "Pending Requests",
+                                    dataSource: {
+                                        ref: "<collection-uuid>",
+                                        type: "structure",
+                                        mode: "aggregate",
+                                        recordSlug: "governance_requests",
+                                        config: { filters: { "data.status": "pending_approval" } },
+                                        aggregation: { operations: { count: { count: "*" } } },
+                                    },
                                 },
                             },
                             "stat-group": {
                                 description: "Group of 2-5 related metrics displayed side by side. More compact than individual metric-cards.",
                                 dataSource: "Not set at block level — each item has its own dataSource",
-                                config: {
+                                statGroupConfig: {
                                     items: "StatGroupItem[] — array of { id, label, dataSource, aggregation, valueField, format, trend }",
                                 },
                             },
                             chart: {
                                 description: "Data visualization — bar, line, or pie chart.",
-                                dataSource: "Required — type: 'structure', mode: 'aggregate' with groupBy",
-                                config: {
+                                dataSource: "Required — type: 'structure' with aggregation and groupBy in the dataSource",
+                                chartConfig: {
                                     chartType: "'bar' | 'line' | 'pie'",
                                     categoryField: "string — field for x-axis / categories",
                                     valueField: "string — field for y-axis / values",
@@ -1196,31 +1201,36 @@ function registerDescribeTools(server) {
                                     colors: "string[] | null — custom color palette",
                                     showLegend: "boolean (default: true)",
                                 },
-                                presentation: "chartType",
                             },
-                            form: {
-                                description: "Data entry form with typed fields, validation, and submission. Used for creating or editing records.",
-                                dataSource: "Optional — if set with mode: 'single', pre-populates form for editing",
-                                config: {
-                                    fields: "FormFieldDef[] — array of field definitions (see below)",
-                                },
-                                form_field_shape: {
+                            "field-group": {
+                                description: "Group of editable form fields. THE block type for form pages. Contains a 'fields' array directly on the block (not under config).",
+                                dataSource: "Optional — set with recordSlug to scope. For edit forms, include recordSlug to pre-populate.",
+                                fields: "FormFieldDef[] — array of field definitions directly on the block object",
+                                field_shape: {
                                     key: "string — maps to the record's data field name",
                                     label: "string — display label",
                                     type: "'text' | 'number' | 'email' | 'date' | 'boolean' | 'select' | 'textarea'",
                                     required: "boolean (default: false)",
                                     placeholder: "string | null",
-                                    optionSource: "For 'select' type: { type: 'static' | 'dynamic', staticOptions?: [{label, value}], dynamicRef?: 'collection-id', labelField?, valueField? }",
+                                    options: "For 'select' type: { label: string, value: string }[] — inline static options",
+                                    optionSource: "For 'select' type (alternative): { type: 'static' | 'dynamic', staticOptions?: [{label, value}], dynamicRef?: 'collection-uuid', labelField?, valueField? }",
                                 },
+                                allowed_actions: ["create-record", "update-record", "invoke-trigger"],
+                                default_activation: "form-submit",
+                                param_source: "form",
                             },
-                            "detail-fields": {
-                                description: "Read-only display of a single record's fields. Used for detail pages.",
-                                dataSource: "Required — type: 'structure', mode: 'single'",
+                            "field-display": {
+                                description: "Read-only display of record fields with labels. THE block type for detail pages. Contains a 'fields' array directly on the block.",
+                                dataSource: "Required — type: 'structure'",
+                                fields: "{ key: string, label: string }[] — fields to display from the record",
+                                allowed_actions: ["invoke-trigger", "navigate-to-page"],
+                                default_activation: "button",
+                                param_source: "record",
                             },
                             "activity-feed": {
                                 description: "Chronological list of recent items/events, showing title, description, and timestamp.",
-                                dataSource: "Required — type: 'structure', mode: 'list'",
-                                config: {
+                                dataSource: "Required — type: 'structure'",
+                                feedConfig: {
                                     titleField: "string — field to use as item title",
                                     descriptionField: "string | null — field for item description",
                                     timestampField: "string — field for item timestamp",
@@ -1231,20 +1241,19 @@ function registerDescribeTools(server) {
                             "progress-indicator": {
                                 description: "Visual progress display — bar, ring, or badge. Shows completion toward a target.",
                                 dataSource: "Optional — can use static value or aggregate from data",
-                                config: {
+                                progressConfig: {
                                     mode: "'bar' | 'ring' | 'badge'",
                                     label: "string",
                                     value: "number | null — static value (if no dataSource)",
                                     valueField: "string | null — field to aggregate (if using dataSource)",
-                                    aggregation: "'count' | 'sum' | 'average' | 'percentage'",
                                     target: "number — the 100% target value",
                                     thresholds: "{ green?: [min, max], amber?: [min, max], red?: [min, max] }",
                                 },
                             },
                             kanban: {
                                 description: "Kanban board — drag-and-drop cards grouped by a status/category field.",
-                                dataSource: "Required — type: 'structure', mode: 'list'",
-                                config: {
+                                dataSource: "Required — type: 'structure'",
+                                kanbanConfig: {
                                     groupByField: "string — field to group cards by (e.g., 'status')",
                                     columnOrder: "string[] | null — explicit column order (e.g., ['todo', 'in-progress', 'done'])",
                                     cardTitleField: "string — field for card title",
@@ -1254,89 +1263,39 @@ function registerDescribeTools(server) {
                             },
                             calendar: {
                                 description: "Calendar view — displays records as events on a month/week/day calendar.",
-                                dataSource: "Required — type: 'structure', mode: 'list'",
-                                config: {
+                                dataSource: "Required — type: 'structure'",
+                                calendarConfig: {
                                     dateField: "string — field for event start date",
                                     endDateField: "string | null — field for event end date (for multi-day events)",
                                     titleField: "string — field for event title",
                                     colorField: "string | null — field to determine event color",
                                     defaultView: "'month' | 'week' | 'day' (default: 'month')",
-                                    eventClickAction: "BlockAction | null — action when an event is clicked",
                                 },
                             },
                             "filter-bar": {
                                 description: "Global filter bar for dashboards — provides date range pickers and dropdown filters that control other blocks on the page.",
                                 dataSource: "Not required",
-                                config: {
+                                filterBarConfig: {
                                     dateField: "string | null — field to filter by date range",
                                     datePresets: "('today' | '7d' | '30d' | '90d' | 'custom')[] — available date range presets",
                                     dropdownFilters: "{ field: string, label: string }[] — dropdown filter options",
                                 },
                             },
                             "related-list": {
-                                description: "Displays related records from another collection. Similar to data-table but used in detail pages to show linked data (e.g., orders belonging to a customer).",
-                                dataSource: "Required — type: 'structure', mode: 'list' (with filters to scope to the parent record)",
+                                description: "Displays related records from another collection. Similar to data-table but used in detail pages to show linked data.",
+                                dataSource: "Required — type: 'structure'",
+                                columns: "{ key: string, label: string }[] — column definitions on the block object",
                                 allowed_actions: ["navigate-to-page", "invoke-trigger"],
                                 default_activation: "row-click",
                                 param_source: "row",
                             },
-                            "field-display": {
-                                description: "Read-only display of a single field value with label. Used in detail pages to show individual fields with formatting.",
-                                dataSource: "Required — type: 'structure', mode: 'single'",
-                                allowed_actions: ["invoke-trigger", "navigate-to-page"],
-                                default_activation: "button",
-                                param_source: "record",
-                            },
-                            "field-group": {
-                                description: "Group of editable form fields. Used in form pages for structured data entry with multiple fields in a logical group.",
-                                dataSource: "Optional — if set with mode: 'single', pre-populates for editing",
-                                allowed_actions: [
-                                    "create-record",
-                                    "update-record",
-                                    "invoke-trigger",
-                                ],
-                                default_activation: "form-submit",
-                                param_source: "form",
-                            },
-                            "text-input": {
-                                description: "Single-line text input field for form pages.",
-                                dataSource: "Not required (value comes from user input)",
-                                category: "field-block",
-                            },
-                            "number-input": {
-                                description: "Numeric input field for form pages. Supports min/max constraints.",
-                                dataSource: "Not required",
-                                category: "field-block",
-                            },
-                            select: {
-                                description: "Dropdown select input for form pages. Options can be static or dynamically loaded from a collection.",
-                                dataSource: "Not required (static options) or optional (dynamic options from collection)",
-                                category: "field-block",
-                            },
-                            checkbox: {
-                                description: "Boolean checkbox input for form pages.",
-                                dataSource: "Not required",
-                                category: "field-block",
-                            },
-                            "date-picker": {
-                                description: "Date/datetime picker input for form pages.",
-                                dataSource: "Not required",
-                                category: "field-block",
-                            },
-                            textarea: {
-                                description: "Multi-line text input for form pages. Use for long text, descriptions, notes.",
-                                dataSource: "Not required",
-                                category: "field-block",
-                            },
-                            "file-upload": {
-                                description: "File upload input for form pages. Stores files in blob storage.",
-                                dataSource: "Not required",
-                                category: "field-block",
+                            form: {
+                                description: "DEPRECATED — use 'field-group' blockType instead. The runtime does not handle 'form' as a blockType.",
+                                IMPORTANT: "Do NOT use this. Use field-group with a fields array.",
                             },
-                            field: {
-                                description: "Generic field block — base type for custom field rendering in form pages.",
-                                dataSource: "Not required",
-                                category: "field-block",
+                            "detail-fields": {
+                                description: "DEPRECATED — use 'field-display' blockType instead. The runtime does not handle 'detail-fields'.",
+                                IMPORTANT: "Do NOT use this. Use field-display with a fields array.",
                             },
                             markdown: {
                                 description: "Static markdown content block. Renders markdown text on the page. Must have non-empty content to pass publishing validation.",
@@ -1352,8 +1311,8 @@ function registerDescribeTools(server) {
                             },
                         },
                         block_categories: {
-                            "data-block": "Blocks that display data from collections (data-table, chart, metric-card, stat-group, detail-fields, related-list, field-display, activity-feed, kanban, calendar, progress-indicator)",
-                            "field-block": "Input blocks for form pages (text-input, number-input, select, checkbox, date-picker, textarea, file-upload, field, field-group). Form pages must have at least one field block.",
+                            "data-block": "Blocks that display data from collections (data-table, chart, metric-card, stat-group, field-display, related-list, activity-feed, kanban, calendar, progress-indicator)",
+                            "form-block": "Use 'field-group' blockType with a 'fields' array for form pages. Do NOT use individual field block types (text-input, select, etc.) — the runtime renders field types from the field-group's fields array.",
                             "content-block": "Static content blocks (markdown, static-html). Must have non-empty 'content' property.",
                             "layout-block": "Blocks that control page-level behavior (filter-bar)",
                         },

package/dist/tools/orchestrations.js

@@ -188,7 +188,7 @@ function registerOrchestrationTools(server, sdk) {
             .describe("Trigger configuration object. Must include 'type' (on-demand, event-driven, scheduled, webhook)"),
         steps: zod_1.z
             .array(zod_1.z.record(zod_1.z.string(), zod_1.z.any()))
-            .describe("Array of step definitions. Step types: 'compute' (functionId + onSuccess/onFailure), 'decision' (cases with conditions using path/op/value + defaultNextStepId), 'delay' (delayMs + nextStepId). Call describe_orchestrations for full schema."),
+            .describe("Array of step definitions. Step types: 'compute' (functionId + onSuccess/onFailure + optional encryptedParams), 'decision' (cases with conditions using path/op/value + defaultNextStepId), 'delay' (delayMs + nextStepId). Compute steps support encryptedParams: { KEY: { value: 'plaintext', encrypt: true } } for secrets like API keys — values are encrypted at rest and decrypted at execution time into triggerParams. Call describe_orchestrations for full schema."),
     }, (_a) => __awaiter(this, [_a], void 0, function* ({ slug, name, description, trigger, steps }) {
         try {
             const input = { slug, name, trigger, steps };
@@ -226,7 +226,7 @@ function registerOrchestrationTools(server, sdk) {
         steps: zod_1.z
             .array(zod_1.z.record(zod_1.z.string(), zod_1.z.any()))
             .optional()
-            .describe("Updated step definitions"),
+            .describe("Updated step definitions. Compute steps support encryptedParams: { KEY: { value: 'plaintext', encrypt: true } } for secrets. Existing encrypted params with { encrypted: true } are preserved as-is; omitted params are removed."),
     }, (_a) => __awaiter(this, [_a], void 0, function* ({ orchestrationId, name, description, status, trigger, steps }) {
         try {
             const input = {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@centrali-io/centrali-mcp",
-  "version": "4.2.12",
+  "version": "4.2.13",
   "description": "Centrali MCP Server - AI assistant integration for Centrali workspaces",
   "main": "dist/index.js",
   "type": "commonjs",

package/src/tools/describe.ts

@@ -726,7 +726,18 @@ export function registerDescribeTools(server: McpServer) {
                     onFailure: "{ nextStepId: string } | null — step to execute on failure",
                     retryConfig: "{ maxRetries, delayMs } | null — automatic retry on failure",
                     timeoutMs: "number | null — step execution timeout",
+                    encryptedParams: "Record<string, { value: string, encrypt: true }> | null — secrets (API keys, tokens) encrypted at rest, decrypted into triggerParams at execution time",
                   },
+                  encrypted_params_notes: [
+                    "To add a secret: { KEY: { value: 'plaintext', encrypt: true } }",
+                    "Values are encrypted before storage — never stored in plaintext",
+                    "API responses mask values as '********'",
+                    "At execution time, decrypted values are merged into triggerParams — the function sees them identically to trigger params",
+                    "To update: send { KEY: { value: 'new-plaintext', encrypt: true } }",
+                    "To preserve existing: send { KEY: { value: '********', encrypted: true, keyVersion: N } }",
+                    "To remove: omit the key from encryptedParams",
+                    "Only valid on compute steps — rejected on decision and delay steps",
+                  ],
                 },
                 decision: {
                   description: "Conditional branching based on input/output values",
@@ -798,6 +809,9 @@ export function registerDescribeTools(server: McpServer) {
                       type: "compute",
                       functionId: "func-uuid",
                       onSuccess: { nextStepId: "check-result" },
+                      encryptedParams: {
+                        API_KEY: { value: "sk_live_...", encrypt: true },
+                      },
                     },
                     decision_step: {
                       id: "check-result",
@@ -847,6 +861,7 @@ export function registerDescribeTools(server: McpServer) {
                 "Use correlationId when triggering to trace runs across systems",
                 "Terminal steps: a compute step with no onSuccess and no subsequent step in the array will complete the run. No special 'end' step type is needed.",
                 "Decision step conditions use 'path' (not 'field') and 'op' (not 'operator'). Paths use dot notation: 'input.fieldName' or 'steps.stepId.output.fieldName'.",
+                "Use encryptedParams on compute steps to pass secrets (API keys, tokens) — they're encrypted at rest and decrypted into triggerParams at execution time.",
               ],
             },
             null,
@@ -1006,7 +1021,6 @@ export function registerDescribeTools(server: McpServer) {
                     "Single-record view — shows all fields of one record with optional related data and actions.",
                   typical_sections: ["hero", "content", "supporting"],
                   typical_blocks: [
-                    "detail-fields",
                     "field-display",
                     "related-list",
                     "activity-feed",
@@ -1019,19 +1033,8 @@ export function registerDescribeTools(server: McpServer) {
                   description:
                     "Data entry form — lets users create or update records with validation and submission actions.",
                   typical_sections: ["content", "actions"],
-                  typical_blocks: [
-                    "form",
-                    "field-group",
-                    "text-input",
-                    "number-input",
-                    "select",
-                    "checkbox",
-                    "date-picker",
-                    "textarea",
-                    "file-upload",
-                  ],
-                  validation_requirement:
-                    "Form pages must have at least one field block (text-input, number-input, select, checkbox, date-picker, textarea, file-upload, field, field-group, or field-display) to pass publishing validation.",
+                  typical_blocks: ["field-group", "markdown", "static-html"],
+                  IMPORTANT: "Use 'field-group' blockType with a 'fields' array. Do NOT use individual field block types (text-input, select, etc.) — the runtime only renders fields from field-group's fields array.",
                   use_when: "You need users to input or edit data",
                 },
                 dashboard: {
@@ -1177,36 +1180,24 @@ export function registerDescribeTools(server: McpServer) {
                   "string[] | null — which columns users can filter on (for data-table blocks)",
               },
               data_source_shape: {
-                type: "'structure' | 'query'",
-                ref: "string — the collection ID (UUID) for 'structure' type, or smart query ID for 'query' type",
-                mode: "'list' | 'single' | 'aggregate' — how to fetch data. 'list' returns multiple records, 'single' returns one, 'aggregate' returns computed values.",
+                type: "'structure' — the data source type",
+                ref: "string — the collection ID (UUID)",
+                recordSlug: "string | undefined — the collection's record slug for direct resolution (avoids an extra lookup). Recommended.",
                 config: {
-                  fields:
-                    "string[] | null — specific fields to fetch (null = all fields)",
-                  fieldOrder:
-                    "string[] | null — display order for fields",
-                  filters:
-                    "object | null — same filter syntax as query_records (data.field[operator]: value)",
+                  description: "Optional query configuration",
+                  filter: "object | null — same filter syntax as query_records",
                   sort: "SortConfig[] | null — array of { field, direction: 'asc' | 'desc' }",
-                  limit: "number | null — max records to fetch",
                   page: "number | null — for pagination",
                   pageSize: "number | null — records per page",
                 },
                 aggregation: {
                   description:
-                    "Only used when mode is 'aggregate'. Defines computations over the data.",
+                    "For metric/chart blocks. Defines computations over the data.",
                   operations:
                     "Record<string, { count?: '*', sum?: 'fieldName', avg?: 'fieldName', min?: 'fieldName', max?: 'fieldName' }>",
                   groupBy: "string[] | null — fields to group by",
                 },
-              },
-              presentation_shape: {
-                density:
-                  "'compact' | 'comfortable' | 'spacious' — controls spacing/padding",
-                columns: "string[] — which columns to show (for table blocks)",
-                chartType: "'bar' | 'line' | 'pie' — for chart blocks",
-                emphasisRules:
-                  "EmphasisRule[] — conditional formatting rules: { field, operator, threshold, severity }",
+                mode: "'list' | 'single' | 'aggregate' — optional. Set to 'aggregate' for metric-card and chart blocks that use aggregation. For list and detail pages, mode is inferred from context.",
               },
               narrative_shape: {
                 primaryQuestion:
@@ -1233,20 +1224,14 @@ export function registerDescribeTools(server: McpServer) {
                         dataSource: {
                           type: "structure",
                           ref: "<collection-uuid>",
-                          mode: "list",
-                          config: {
-                            fields: [
-                              "name",
-                              "email",
-                              "status",
-                              "createdAt",
-                            ],
-                            sort: [{ field: "createdAt", direction: "desc" }],
-                            pageSize: 25,
-                          },
+                          recordSlug: "customers",
                         },
-                        presentation: { density: "comfortable" },
-                        filterableColumns: ["status", "name"],
+                        columns: [
+                          { key: "name", label: "Name", filterable: true, sortable: true },
+                          { key: "email", label: "Email", sortable: true },
+                          { key: "status", label: "Status", filterable: true, sortable: true },
+                          { key: "createdAt", label: "Created", sortable: true },
+                        ],
                       },
                     ],
                   },
@@ -1347,46 +1332,53 @@ export function registerDescribeTools(server: McpServer) {
               domain: "Page Block Types",
               description:
                 "Blocks are the UI components inside page sections. Each blockType has its own configuration requirements.",
+              IMPORTANT_config_convention: "Block-type-specific config uses named properties on the block object (e.g., block.kanbanConfig, block.chartConfig), NOT a generic 'config' key. This is critical — using 'config' instead of the named property will silently fail.",
               block_types: {
                 "data-table": {
                   description:
-                    "Tabular data display with columns, sorting, filtering, and pagination. The primary block for list pages.",
-                  dataSource: "Required — type: 'structure', mode: 'list'",
-                  config: {
-                    columns:
-                      "{ field: string, label: string, sortable?: boolean }[] — column definitions",
-                    defaultSort:
-                      "{ field: string, direction: 'asc' | 'desc' } — initial sort",
-                    pageSize: "number — rows per page (default: 25)",
-                    rowClickAction:
-                      "BlockAction | null — action when a row is clicked (typically navigate-to-page)",
+                    "Tabular data display with columns, sorting, filtering, and pagination. The primary block for list and dashboard pages.",
+                  dataSource: "Required — type: 'structure'. Add recordSlug for direct resolution.",
+                  columns: "{ key: string, label: string, filterable?: boolean, sortable?: boolean }[] — column definitions on the block object. Used by both the publish validator and the runtime renderer.",
+                  example: {
+                    id: "<uuid>",
+                    blockType: "data-table",
+                    dataSource: { type: "structure", ref: "<collection-uuid>", recordSlug: "my-records" },
+                    columns: [
+                      { key: "name", label: "Name", filterable: true, sortable: true },
+                      { key: "status", label: "Status", filterable: true, sortable: true },
+                      { key: "createdAt", label: "Created", sortable: true },
+                    ],
                   },
-                  presentation: "density, columns, emphasisRules",
-                  filterableColumns: "string[] — columns users can filter on",
                 },
                 "metric-card": {
                   description:
                     "Single KPI metric display — shows a number with label, optional trend, and thresholds.",
                   dataSource:
-                    "Required — type: 'structure', mode: 'aggregate' with a single aggregation",
-                  config: {
-                    aggregation:
-                      "'count' | 'sum' | 'average' | 'min' | 'max'",
-                    valueField:
-                      "string — field to aggregate (not needed for 'count')",
-                    label: "string — display label for the metric",
-                    format:
-                      "'number' | 'currency' | 'percentage' — value formatting",
-                    trend: "{ enabled: boolean, comparison: 'previous-period' }",
-                    thresholds:
-                      "{ green?: [min, max], amber?: [min, max], red?: [min, max] } — color-code the value",
+                    "Required — type: 'structure', mode: 'aggregate' with aggregation.operations in the dataSource",
+                  label: "string — display label for the metric, placed directly on the block object",
+                  metricConfig: {
+                    format: "'number' | 'currency' | 'percentage' — value formatting (optional)",
+                    thresholds: "{ green?: [min, max], amber?: [min, max], red?: [min, max] } — color-code the value (optional)",
+                  },
+                  example: {
+                    id: "<uuid>",
+                    blockType: "metric-card",
+                    label: "Pending Requests",
+                    dataSource: {
+                      ref: "<collection-uuid>",
+                      type: "structure",
+                      mode: "aggregate",
+                      recordSlug: "governance_requests",
+                      config: { filters: { "data.status": "pending_approval" } },
+                      aggregation: { operations: { count: { count: "*" } } },
+                    },
                   },
                 },
                 "stat-group": {
                   description:
                     "Group of 2-5 related metrics displayed side by side. More compact than individual metric-cards.",
                   dataSource: "Not set at block level — each item has its own dataSource",
-                  config: {
+                  statGroupConfig: {
                     items:
                       "StatGroupItem[] — array of { id, label, dataSource, aggregation, valueField, format, trend }",
                   },
@@ -1395,52 +1387,51 @@ export function registerDescribeTools(server: McpServer) {
                   description:
                     "Data visualization — bar, line, or pie chart.",
                   dataSource:
-                    "Required — type: 'structure', mode: 'aggregate' with groupBy",
-                  config: {
+                    "Required — type: 'structure' with aggregation and groupBy in the dataSource",
+                  chartConfig: {
                     chartType: "'bar' | 'line' | 'pie'",
                     categoryField: "string — field for x-axis / categories",
                     valueField: "string — field for y-axis / values",
-                    groupByField:
-                      "string | null — optional field for series grouping",
+                    groupByField: "string | null — optional field for series grouping",
                     colors: "string[] | null — custom color palette",
                     showLegend: "boolean (default: true)",
                   },
-                  presentation: "chartType",
                 },
-                form: {
+                "field-group": {
                   description:
-                    "Data entry form with typed fields, validation, and submission. Used for creating or editing records.",
+                    "Group of editable form fields. THE block type for form pages. Contains a 'fields' array directly on the block (not under config).",
                   dataSource:
-                    "Optional — if set with mode: 'single', pre-populates form for editing",
-                  config: {
-                    fields:
-                      "FormFieldDef[] — array of field definitions (see below)",
-                  },
-                  form_field_shape: {
+                    "Optional — set with recordSlug to scope. For edit forms, include recordSlug to pre-populate.",
+                  fields: "FormFieldDef[] — array of field definitions directly on the block object",
+                  field_shape: {
                     key: "string — maps to the record's data field name",
                     label: "string — display label",
                     type: "'text' | 'number' | 'email' | 'date' | 'boolean' | 'select' | 'textarea'",
                     required: "boolean (default: false)",
                     placeholder: "string | null",
-                    optionSource:
-                      "For 'select' type: { type: 'static' | 'dynamic', staticOptions?: [{label, value}], dynamicRef?: 'collection-id', labelField?, valueField? }",
+                    options: "For 'select' type: { label: string, value: string }[] — inline static options",
+                    optionSource: "For 'select' type (alternative): { type: 'static' | 'dynamic', staticOptions?: [{label, value}], dynamicRef?: 'collection-uuid', labelField?, valueField? }",
                   },
+                  allowed_actions: ["create-record", "update-record", "invoke-trigger"],
+                  default_activation: "form-submit",
+                  param_source: "form",
                 },
-                "detail-fields": {
+                "field-display": {
                   description:
-                    "Read-only display of a single record's fields. Used for detail pages.",
-                  dataSource:
-                    "Required — type: 'structure', mode: 'single'",
+                    "Read-only display of record fields with labels. THE block type for detail pages. Contains a 'fields' array directly on the block.",
+                  dataSource: "Required — type: 'structure'",
+                  fields: "{ key: string, label: string }[] — fields to display from the record",
+                  allowed_actions: ["invoke-trigger", "navigate-to-page"],
+                  default_activation: "button",
+                  param_source: "record",
                 },
                 "activity-feed": {
                   description:
                     "Chronological list of recent items/events, showing title, description, and timestamp.",
-                  dataSource:
-                    "Required — type: 'structure', mode: 'list'",
-                  config: {
+                  dataSource: "Required — type: 'structure'",
+                  feedConfig: {
                     titleField: "string — field to use as item title",
-                    descriptionField:
-                      "string | null — field for item description",
+                    descriptionField: "string | null — field for item description",
                     timestampField: "string — field for item timestamp",
                     iconField: "string | null — field for item icon",
                     maxItems: "number (default: 10)",
@@ -1449,147 +1440,66 @@ export function registerDescribeTools(server: McpServer) {
                 "progress-indicator": {
                   description:
                     "Visual progress display — bar, ring, or badge. Shows completion toward a target.",
-                  dataSource:
-                    "Optional — can use static value or aggregate from data",
-                  config: {
+                  dataSource: "Optional — can use static value or aggregate from data",
+                  progressConfig: {
                     mode: "'bar' | 'ring' | 'badge'",
                     label: "string",
                     value: "number | null — static value (if no dataSource)",
-                    valueField:
-                      "string | null — field to aggregate (if using dataSource)",
-                    aggregation:
-                      "'count' | 'sum' | 'average' | 'percentage'",
+                    valueField: "string | null — field to aggregate (if using dataSource)",
                     target: "number — the 100% target value",
-                    thresholds:
-                      "{ green?: [min, max], amber?: [min, max], red?: [min, max] }",
+                    thresholds: "{ green?: [min, max], amber?: [min, max], red?: [min, max] }",
                   },
                 },
                 kanban: {
                   description:
                     "Kanban board — drag-and-drop cards grouped by a status/category field.",
-                  dataSource:
-                    "Required — type: 'structure', mode: 'list'",
-                  config: {
-                    groupByField:
-                      "string — field to group cards by (e.g., 'status')",
-                    columnOrder:
-                      "string[] | null — explicit column order (e.g., ['todo', 'in-progress', 'done'])",
+                  dataSource: "Required — type: 'structure'",
+                  kanbanConfig: {
+                    groupByField: "string — field to group cards by (e.g., 'status')",
+                    columnOrder: "string[] | null — explicit column order (e.g., ['todo', 'in-progress', 'done'])",
                     cardTitleField: "string — field for card title",
-                    cardSubtitleField:
-                      "string | null — field for card subtitle",
-                    cardBadgeField:
-                      "string | null — field for a badge/tag on the card",
+                    cardSubtitleField: "string | null — field for card subtitle",
+                    cardBadgeField: "string | null — field for a badge/tag on the card",
                   },
                 },
                 calendar: {
                   description:
                     "Calendar view — displays records as events on a month/week/day calendar.",
-                  dataSource:
-                    "Required — type: 'structure', mode: 'list'",
-                  config: {
+                  dataSource: "Required — type: 'structure'",
+                  calendarConfig: {
                     dateField: "string — field for event start date",
-                    endDateField:
-                      "string | null — field for event end date (for multi-day events)",
+                    endDateField: "string | null — field for event end date (for multi-day events)",
                     titleField: "string — field for event title",
-                    colorField:
-                      "string | null — field to determine event color",
-                    defaultView:
-                      "'month' | 'week' | 'day' (default: 'month')",
-                    eventClickAction:
-                      "BlockAction | null — action when an event is clicked",
+                    colorField: "string | null — field to determine event color",
+                    defaultView: "'month' | 'week' | 'day' (default: 'month')",
                   },
                 },
                 "filter-bar": {
                   description:
                     "Global filter bar for dashboards — provides date range pickers and dropdown filters that control other blocks on the page.",
                   dataSource: "Not required",
-                  config: {
-                    dateField:
-                      "string | null — field to filter by date range",
-                    datePresets:
-                      "('today' | '7d' | '30d' | '90d' | 'custom')[] — available date range presets",
-                    dropdownFilters:
-                      "{ field: string, label: string }[] — dropdown filter options",
+                  filterBarConfig: {
+                    dateField: "string | null — field to filter by date range",
+                    datePresets: "('today' | '7d' | '30d' | '90d' | 'custom')[] — available date range presets",
+                    dropdownFilters: "{ field: string, label: string }[] — dropdown filter options",
                   },
                 },
                 "related-list": {
                   description:
-                    "Displays related records from another collection. Similar to data-table but used in detail pages to show linked data (e.g., orders belonging to a customer).",
-                  dataSource:
-                    "Required — type: 'structure', mode: 'list' (with filters to scope to the parent record)",
+                    "Displays related records from another collection. Similar to data-table but used in detail pages to show linked data.",
+                  dataSource: "Required — type: 'structure'",
+                  columns: "{ key: string, label: string }[] — column definitions on the block object",
                   allowed_actions: ["navigate-to-page", "invoke-trigger"],
                   default_activation: "row-click",
                   param_source: "row",
                 },
-                "field-display": {
-                  description:
-                    "Read-only display of a single field value with label. Used in detail pages to show individual fields with formatting.",
-                  dataSource:
-                    "Required — type: 'structure', mode: 'single'",
-                  allowed_actions: ["invoke-trigger", "navigate-to-page"],
-                  default_activation: "button",
-                  param_source: "record",
-                },
-                "field-group": {
-                  description:
-                    "Group of editable form fields. Used in form pages for structured data entry with multiple fields in a logical group.",
-                  dataSource:
-                    "Optional — if set with mode: 'single', pre-populates for editing",
-                  allowed_actions: [
-                    "create-record",
-                    "update-record",
-                    "invoke-trigger",
-                  ],
-                  default_activation: "form-submit",
-                  param_source: "form",
-                },
-                "text-input": {
-                  description:
-                    "Single-line text input field for form pages.",
-                  dataSource: "Not required (value comes from user input)",
-                  category: "field-block",
-                },
-                "number-input": {
-                  description:
-                    "Numeric input field for form pages. Supports min/max constraints.",
-                  dataSource: "Not required",
-                  category: "field-block",
-                },
-                select: {
-                  description:
-                    "Dropdown select input for form pages. Options can be static or dynamically loaded from a collection.",
-                  dataSource: "Not required (static options) or optional (dynamic options from collection)",
-                  category: "field-block",
-                },
-                checkbox: {
-                  description:
-                    "Boolean checkbox input for form pages.",
-                  dataSource: "Not required",
-                  category: "field-block",
-                },
-                "date-picker": {
-                  description:
-                    "Date/datetime picker input for form pages.",
-                  dataSource: "Not required",
-                  category: "field-block",
-                },
-                textarea: {
-                  description:
-                    "Multi-line text input for form pages. Use for long text, descriptions, notes.",
-                  dataSource: "Not required",
-                  category: "field-block",
-                },
-                "file-upload": {
-                  description:
-                    "File upload input for form pages. Stores files in blob storage.",
-                  dataSource: "Not required",
-                  category: "field-block",
+                form: {
+                  description: "DEPRECATED — use 'field-group' blockType instead. The runtime does not handle 'form' as a blockType.",
+                  IMPORTANT: "Do NOT use this. Use field-group with a fields array.",
                 },
-                field: {
-                  description:
-                    "Generic field block — base type for custom field rendering in form pages.",
-                  dataSource: "Not required",
-                  category: "field-block",
+                "detail-fields": {
+                  description: "DEPRECATED — use 'field-display' blockType instead. The runtime does not handle 'detail-fields'.",
+                  IMPORTANT: "Do NOT use this. Use field-display with a fields array.",
                 },
                 markdown: {
                   description:
@@ -1608,9 +1518,9 @@ export function registerDescribeTools(server: McpServer) {
               },
               block_categories: {
                 "data-block":
-                  "Blocks that display data from collections (data-table, chart, metric-card, stat-group, detail-fields, related-list, field-display, activity-feed, kanban, calendar, progress-indicator)",
-                "field-block":
-                  "Input blocks for form pages (text-input, number-input, select, checkbox, date-picker, textarea, file-upload, field, field-group). Form pages must have at least one field block.",
+                  "Blocks that display data from collections (data-table, chart, metric-card, stat-group, field-display, related-list, activity-feed, kanban, calendar, progress-indicator)",
+                "form-block":
+                  "Use 'field-group' blockType with a 'fields' array for form pages. Do NOT use individual field block types (text-input, select, etc.) — the runtime renders field types from the field-group's fields array.",
                 "content-block":
                   "Static content blocks (markdown, static-html). Must have non-empty 'content' property.",
                 "layout-block":

package/src/tools/orchestrations.ts

@@ -219,7 +219,7 @@ export function registerOrchestrationTools(server: McpServer, sdk: CentraliSDK)
         .describe("Trigger configuration object. Must include 'type' (on-demand, event-driven, scheduled, webhook)"),
       steps: z
         .array(z.record(z.string(), z.any()))
-        .describe("Array of step definitions. Step types: 'compute' (functionId + onSuccess/onFailure), 'decision' (cases with conditions using path/op/value + defaultNextStepId), 'delay' (delayMs + nextStepId). Call describe_orchestrations for full schema."),
+        .describe("Array of step definitions. Step types: 'compute' (functionId + onSuccess/onFailure + optional encryptedParams), 'decision' (cases with conditions using path/op/value + defaultNextStepId), 'delay' (delayMs + nextStepId). Compute steps support encryptedParams: { KEY: { value: 'plaintext', encrypt: true } } for secrets like API keys — values are encrypted at rest and decrypted at execution time into triggerParams. Call describe_orchestrations for full schema."),
     },
     async ({ slug, name, description, trigger, steps }) => {
       try {
@@ -262,7 +262,7 @@ export function registerOrchestrationTools(server: McpServer, sdk: CentraliSDK)
       steps: z
         .array(z.record(z.string(), z.any()))
         .optional()
-        .describe("Updated step definitions"),
+        .describe("Updated step definitions. Compute steps support encryptedParams: { KEY: { value: 'plaintext', encrypt: true } } for secrets. Existing encrypted params with { encrypted: true } are preserved as-is; omitted params are removed."),
     },
     async ({ orchestrationId, name, description, status, trigger, steps }) => {
       try {