@centrali-io/centrali-mcp 4.2.11 → 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",
@@ -752,6 +766,9 @@ function registerDescribeTools(server) {
                             "Use get_orchestration_run with includeSteps=true to see step-by-step execution details",
                             "Orchestrations must be 'active' to be triggered — draft orchestrations cannot run",
                             "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),
                 },
@@ -869,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",
@@ -880,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: {
@@ -1002,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?')",
@@ -1047,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 },
+                                            ],
                                         },
                                     ],
                                 },
@@ -1151,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",
@@ -1194,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",
@@ -1229,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",
@@ -1252,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.",
@@ -1350,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.11",
+  "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",
@@ -845,6 +859,9 @@ export function registerDescribeTools(server: McpServer) {
                 "Use get_orchestration_run with includeSteps=true to see step-by-step execution details",
                 "Orchestrations must be 'active' to be triggered — draft orchestrations cannot run",
                 "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,
@@ -1004,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",
@@ -1017,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: {
@@ -1175,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:
@@ -1231,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 },
+                        ],
                       },
                     ],
                   },
@@ -1345,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 }",
                   },
@@ -1393,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)",
@@ -1447,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:
@@ -1606,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 {