zinkee 0.1.24 → 0.1.26

package/dist/index.js

@@ -275,6 +275,41 @@ var commandRegistry = {
     supportsRaw: false,
     output: writeOutput
   },
+  "displays folders list": {
+    command: "displays folders list",
+    accessLevel: "read",
+    supportsExample: true,
+    supportsRaw: false,
+    output: readOutput
+  },
+  "displays folders create": {
+    command: "displays folders create",
+    accessLevel: "write",
+    supportsExample: true,
+    supportsRaw: false,
+    output: writeOutput
+  },
+  "displays folders update": {
+    command: "displays folders update",
+    accessLevel: "write",
+    supportsExample: true,
+    supportsRaw: false,
+    output: writeOutput
+  },
+  "displays folders delete": {
+    command: "displays folders delete",
+    accessLevel: "destructive",
+    supportsExample: true,
+    supportsRaw: false,
+    output: writeOutput
+  },
+  "displays folders move": {
+    command: "displays folders move",
+    accessLevel: "write",
+    supportsExample: true,
+    supportsRaw: false,
+    output: writeOutput
+  },
   "displays layout get": {
     command: "displays layout get",
     accessLevel: "read",
@@ -2919,11 +2954,10 @@ var specificExamples = {
   ]),
   "navigation resources move": buildCommandExamples([
     {
-      description: "Move a schema into a navigation folder.",
-      command: "zinkee --json navigation resources move 2eb8bdcf-6d9c-4fbb-9018-7fa8180f4c5e --type SCHEMA --to Sales",
+      description: "Move a schema into a navigation folder. Only schemas can be moved; the navigation menu holds databases.",
+      command: "zinkee --json navigation resources move 2eb8bdcf-6d9c-4fbb-9018-7fa8180f4c5e --to Sales",
       raw: `{
   "resourceId": "2eb8bdcf-6d9c-4fbb-9018-7fa8180f4c5e",
-  "resourceType": "SCHEMA",
   "targetFolderId": "84a0fca4-37ef-4c83-a8ed-9ef67ad9324a"
 }`,
       response: `{
@@ -2932,39 +2966,11 @@ var specificExamples = {
 }`
     },
     {
-      description: "Move a workflow.",
-      command: "zinkee --json navigation resources move 3f8a2c1b-9d4e-4a5b-8c6d-7e8f90123456 --type WORKFLOW --to Operations",
-      raw: `{
-  "resourceId": "3f8a2c1b-9d4e-4a5b-8c6d-7e8f90123456",
-  "resourceType": "WORKFLOW",
-  "targetFolderId": "b8c9d0e1-f2a3-4b5c-6d7e-8f9012345678"
-}`
-    },
-    {
-      description: "Move a display.",
-      command: "zinkee --json navigation resources move 0f6f062f-1478-4df2-96a1-c495d037d260 --type DISPLAY --to Operations",
-      raw: `{
-  "resourceId": "0f6f062f-1478-4df2-96a1-c495d037d260",
-  "resourceType": "DISPLAY",
-  "targetFolderId": "b8c9d0e1-f2a3-4b5c-6d7e-8f9012345678"
-}`
-    },
-    {
-      description: "Move a resource back to the root folder (root is always UUID 00000000-0000-0000-0000-000000000000).",
-      command: "zinkee --json navigation resources move 5223cbc8-8c6c-4694-93bc-dd176364df9b --type SCHEMA --to 00000000-0000-0000-0000-000000000000",
+      description: "Move a schema back to the root folder (root is always UUID 00000000-0000-0000-0000-000000000000).",
+      command: "zinkee --json navigation resources move 5223cbc8-8c6c-4694-93bc-dd176364df9b --to 00000000-0000-0000-0000-000000000000",
       raw: `{
   "resourceId": "5223cbc8-8c6c-4694-93bc-dd176364df9b",
-  "resourceType": "SCHEMA",
   "targetFolderId": "00000000-0000-0000-0000-000000000000"
-}`
-    },
-    {
-      description: "Move a schedule resource.",
-      command: "zinkee --json navigation resources move a1b2c3d4-e5f6-7890-1234-567890abcdef --type SCHEDULE --to Operations",
-      raw: `{
-  "resourceId": "a1b2c3d4-e5f6-7890-1234-567890abcdef",
-  "resourceType": "SCHEDULE",
-  "targetFolderId": "b8c9d0e1-f2a3-4b5c-6d7e-8f9012345678"
 }`
     }
   ]),
@@ -3375,7 +3381,7 @@ var specificExamples = {
   "displays widgets create": buildCommandExamples([
     {
       description: "Create a TABLE widget (CLI normalises --type table to TABLE_OR_SUBTABLE).",
-      command: `zinkee --json displays widgets create 0f6f062f-1478-4df2-96a1-c495d037d260 --type table --name Customers --origin-resource 2eb8bdcf-6d9c-4fbb-9018-7fa8180f4c5e --layout '{"x":0,"y":0,"w":12,"h":8}' --field id --field contact-name --field status --sort '{"fieldId":"id","direction":"DESC"}'`,
+      command: `zinkee --json displays widgets create 0f6f062f-1478-4df2-96a1-c495d037d260 --type table --name Customers --origin-resource 2eb8bdcf-6d9c-4fbb-9018-7fa8180f4c5e --layout '{"x":0,"y":0,"w":12,"h":8}' --field contact-name --field status --field amount --sort '{"fieldId":"contact-name","direction":"ASC"}'`,
       raw: `{
   "type": "TABLE_OR_SUBTABLE",
   "source": {
@@ -3390,11 +3396,11 @@ var specificExamples = {
   },
   "query": {
     "sorts": [
-      { "fieldId": "id", "direction": "DESC" }
+      { "fieldId": "contact-name", "direction": "ASC" }
     ]
   },
   "view": {
-    "fields": ["id", "contact-name", "status"]
+    "fields": ["contact-name", "status", "amount"]
   }
 }`,
       response: `{
@@ -3474,7 +3480,7 @@ var specificExamples = {
     },
     {
       description: "Create a bars CHART widget with a monthly time-serie x-axis and two y-axis series.",
-      command: `zinkee --json displays widgets create 0f6f062f-1478-4df2-96a1-c495d037d260 --type CHART --name "Revenue by month" --origin-resource 2eb8bdcf-6d9c-4fbb-9018-7fa8180f4c5e --layout '{"x":0,"y":0,"w":8,"h":6}' --chart-type bars --x-axis-field due-date --x-axis-date-format MONTH_YEAR --x-axis-time-series --y-axis-serie '{"typeCalc":"SUM","fieldCalc":"amount","color":"#4B9CD3","axisType":"PRIMARY"}' --y-axis-serie '{"typeCalc":"COUNT","fieldCalc":"id","color":"#E57373","axisType":"SECONDARY"}' --legend '{"position":"bottom"}'`,
+      command: `zinkee --json displays widgets create 0f6f062f-1478-4df2-96a1-c495d037d260 --type CHART --name "Revenue by month" --origin-resource 2eb8bdcf-6d9c-4fbb-9018-7fa8180f4c5e --layout '{"x":0,"y":0,"w":8,"h":6}' --chart-type bars --x-axis-field due-date --x-axis-date-format MONTH_YEAR --x-axis-time-series --y-axis-serie '{"typeCalc":"SUM","fieldCalc":"amount","color":"#4B9CD3","axisType":"PRIMARY"}' --y-axis-serie '{"typeCalc":"COUNT","fieldCalc":"contact-name","color":"#E57373","axisType":"SECONDARY"}' --legend '{"position":"bottom"}'`,
       raw: `{
   "type": "CHART",
   "source": {
@@ -3499,7 +3505,7 @@ var specificExamples = {
       },
       {
         "typeCalc": "COUNT",
-        "fieldCalc": "id",
+        "fieldCalc": "contact-name",
         "color": "#E57373",
         "axisType": "SECONDARY"
       }
@@ -3569,8 +3575,8 @@ var specificExamples = {
 }`
     },
     {
-      description: "Create a TIMELINE widget.",
-      command: `zinkee --json displays widgets create 0f6f062f-1478-4df2-96a1-c495d037d260 --type TIMELINE --name "Customer schedule" --origin-resource 2eb8bdcf-6d9c-4fbb-9018-7fa8180f4c5e --layout '{"x":0,"y":0,"w":12,"h":6}' --field contact-name --field due-date`,
+      description: "Create a TIMELINE widget via flags. The typed view state lives in view.viewAdditionalProperties.viewState; field references there must be UUIDs (slugs are only resolved in --field). cardConfig uses category1/category2/category4 (no category3). Use --view-state for UI scalars (granularity, sidebarWidth, show* ...).",
+      command: `zinkee --json displays widgets create 0f6f062f-1478-4df2-96a1-c495d037d260 --type TIMELINE --name "Customer schedule" --origin-resource 2eb8bdcf-6d9c-4fbb-9018-7fa8180f4c5e --layout '{"x":0,"y":0,"w":12,"h":6}' --field c60b8526-5835-4c9f-aecd-9a16c7704a34 --field a8f1d7e3-2b5c-4d9e-8a1b-3c4d5e6f7890 --field c52efe3f-2825-4c60-a7e3-34dd4c1ce043 --field d4e5f6a7-b8c9-0d1e-2f3a-4b5c6d7e8f90 --start-date-field d4e5f6a7-b8c9-0d1e-2f3a-4b5c6d7e8f90 --end-date-field e5f6a7b8-c9d0-1e2f-3a4b-5c6d7e8f9012 --label-field c60b8526-5835-4c9f-aecd-9a16c7704a34 --group-field a8f1d7e3-2b5c-4d9e-8a1b-3c4d5e6f7890 --subgroup-field c60b8526-5835-4c9f-aecd-9a16c7704a34 --progress-field c52efe3f-2825-4c60-a7e3-34dd4c1ce043 --card-title-field c60b8526-5835-4c9f-aecd-9a16c7704a34 --card-category1-field a8f1d7e3-2b5c-4d9e-8a1b-3c4d5e6f7890 --card-category2-field d4e5f6a7-b8c9-0d1e-2f3a-4b5c6d7e8f90 --card-category4-field c52efe3f-2825-4c60-a7e3-34dd4c1ce043 --card-description-field c60b8526-5835-4c9f-aecd-9a16c7704a34 --view-state '{"granularity":"month","sidebarWidth":300,"showUngroupedEvents":true,"showUnsubgroupedEvents":true}'`,
       raw: `{
   "type": "TIMELINE",
   "source": {
@@ -3582,13 +3588,41 @@ var specificExamples = {
   },
   "presentation": { "name": "Customer schedule" },
   "view": {
-    "fields": ["contact-name", "due-date"]
+    "fields": [
+      "c60b8526-5835-4c9f-aecd-9a16c7704a34",
+      "a8f1d7e3-2b5c-4d9e-8a1b-3c4d5e6f7890",
+      "c52efe3f-2825-4c60-a7e3-34dd4c1ce043",
+      "d4e5f6a7-b8c9-0d1e-2f3a-4b5c6d7e8f90"
+    ],
+    "viewAdditionalProperties": {
+      "viewState": {
+        "granularity": "month",
+        "sidebarWidth": 300,
+        "showUngroupedEvents": true,
+        "showUnsubgroupedEvents": true,
+        "fieldMapping": {
+          "startDateField": "d4e5f6a7-b8c9-0d1e-2f3a-4b5c6d7e8f90",
+          "endDateField": "e5f6a7b8-c9d0-1e2f-3a4b-5c6d7e8f9012",
+          "labelField": "c60b8526-5835-4c9f-aecd-9a16c7704a34",
+          "groupField": "a8f1d7e3-2b5c-4d9e-8a1b-3c4d5e6f7890",
+          "subgroupField": "c60b8526-5835-4c9f-aecd-9a16c7704a34",
+          "progressField": "c52efe3f-2825-4c60-a7e3-34dd4c1ce043",
+          "cardConfig": {
+            "titleField": "c60b8526-5835-4c9f-aecd-9a16c7704a34",
+            "category1Field": "a8f1d7e3-2b5c-4d9e-8a1b-3c4d5e6f7890",
+            "category2Field": "d4e5f6a7-b8c9-0d1e-2f3a-4b5c6d7e8f90",
+            "category4Field": "c52efe3f-2825-4c60-a7e3-34dd4c1ce043",
+            "descriptionField": "c60b8526-5835-4c9f-aecd-9a16c7704a34"
+          }
+        }
+      }
+    }
   }
 }`
     },
     {
-      description: "Create a KANBAN widget with a status filter and groupsExpanded config (rich query/view requires --raw).",
-      command: `zinkee --json displays widgets create 0f6f062f-1478-4df2-96a1-c495d037d260 --raw '{"type":"KANBAN","source":{"originResourceId":"2eb8bdcf-6d9c-4fbb-9018-7fa8180f4c5e","isOriginSubSchema":false},"placement":{"layout":{"x":0,"y":0,"w":12,"h":8}},"presentation":{"name":"Status board"},"query":{"filters":[{"origin":{"schemaId":"contacts","fieldId":"status"},"comparisonOperator":"ANY_OF","values":["1","2","3"]}]},"view":{"fields":["contact-name","status","amount"],"groupsExpanded":{"1":true,"2":true,"3":false}}}'`,
+      description: "Create a KANBAN widget via flags. The typed view state lives in view.viewAdditionalProperties.viewState; field references there must be UUIDs (slugs are only resolved in --field). cardConfig uses category1/category2/category3 (no category4). --aggregation-method/--aggregation-field set the card aggregation; use --view-state for UI scalars.",
+      command: `zinkee --json displays widgets create 0f6f062f-1478-4df2-96a1-c495d037d260 --type KANBAN --name "Status board" --origin-resource 2eb8bdcf-6d9c-4fbb-9018-7fa8180f4c5e --layout '{"x":0,"y":0,"w":12,"h":8}' --field c60b8526-5835-4c9f-aecd-9a16c7704a34 --field a8f1d7e3-2b5c-4d9e-8a1b-3c4d5e6f7890 --field c52efe3f-2825-4c60-a7e3-34dd4c1ce043 --field d4e5f6a7-b8c9-0d1e-2f3a-4b5c6d7e8f90 --column-field a8f1d7e3-2b5c-4d9e-8a1b-3c4d5e6f7890 --swimlane-field c60b8526-5835-4c9f-aecd-9a16c7704a34 --card-title-field c60b8526-5835-4c9f-aecd-9a16c7704a34 --card-category1-field a8f1d7e3-2b5c-4d9e-8a1b-3c4d5e6f7890 --card-category2-field d4e5f6a7-b8c9-0d1e-2f3a-4b5c6d7e8f90 --card-category3-field c52efe3f-2825-4c60-a7e3-34dd4c1ce043 --card-description-field c60b8526-5835-4c9f-aecd-9a16c7704a34 --aggregation-method sum --aggregation-field c52efe3f-2825-4c60-a7e3-34dd4c1ce043 --view-state '{"hideEmptyColumns":false,"showNoValueColumn":true,"showNoValueSwimlane":true}'`,
       raw: `{
   "type": "KANBAN",
   "source": {
@@ -3599,27 +3633,41 @@ var specificExamples = {
     "layout": { "x": 0, "y": 0, "w": 12, "h": 8 }
   },
   "presentation": { "name": "Status board" },
-  "query": {
-    "filters": [
-      {
-        "origin": {
-          "schemaId": "contacts",
-          "fieldId": "status"
-        },
-        "comparisonOperator": "ANY_OF",
-        "values": ["1", "2", "3"]
-      }
-    ]
-  },
   "view": {
-    "fields": ["contact-name", "status", "amount"],
-    "groupsExpanded": { "1": true, "2": true, "3": false }
+    "fields": [
+      "c60b8526-5835-4c9f-aecd-9a16c7704a34",
+      "a8f1d7e3-2b5c-4d9e-8a1b-3c4d5e6f7890",
+      "c52efe3f-2825-4c60-a7e3-34dd4c1ce043",
+      "d4e5f6a7-b8c9-0d1e-2f3a-4b5c6d7e8f90"
+    ],
+    "viewAdditionalProperties": {
+      "viewState": {
+        "hideEmptyColumns": false,
+        "showNoValueColumn": true,
+        "showNoValueSwimlane": true,
+        "fieldMapping": {
+          "columnField": "a8f1d7e3-2b5c-4d9e-8a1b-3c4d5e6f7890",
+          "swimlaneField": "c60b8526-5835-4c9f-aecd-9a16c7704a34",
+          "cardConfig": {
+            "titleField": "c60b8526-5835-4c9f-aecd-9a16c7704a34",
+            "category1Field": "a8f1d7e3-2b5c-4d9e-8a1b-3c4d5e6f7890",
+            "category2Field": "d4e5f6a7-b8c9-0d1e-2f3a-4b5c6d7e8f90",
+            "category3Field": "c52efe3f-2825-4c60-a7e3-34dd4c1ce043",
+            "descriptionField": "c60b8526-5835-4c9f-aecd-9a16c7704a34"
+          },
+          "aggregationConfig": {
+            "method": "sum",
+            "fieldId": "c52efe3f-2825-4c60-a7e3-34dd4c1ce043"
+          }
+        }
+      }
+    }
   }
 }`
     },
     {
-      description: "Create a HIERARCHY widget rooted on a parent field.",
-      command: `zinkee --json displays widgets create 0f6f062f-1478-4df2-96a1-c495d037d260 --raw '{"type":"HIERARCHY","source":{"originResourceId":"2eb8bdcf-6d9c-4fbb-9018-7fa8180f4c5e","isOriginSubSchema":false},"placement":{"layout":{"x":0,"y":0,"w":12,"h":6}},"presentation":{"name":"Org tree"},"view":{"fields":["contact-name","status"],"hierarchyConfig":{"parentFieldId":"contact-name"}}}'`,
+      description: "Create a HIERARCHY widget via flags. Declare columns once (--hierarchy-label, repeatable --hierarchy-info <id:name>, --hierarchy-number <id:name:aggregation>), map the root level (the view's own table) with --hierarchy-root-* and add each child level as a JSON object with --hierarchy-child. label is required per level; info/number mappings are optional. Column ids (e.g. col_1779975207355_zfndknslw) are unique opaque identifiers you choose \u2014 not the column name \u2014 and are reused as columnId in every mapping. All field references must be UUIDs.",
+      command: `zinkee --json displays widgets create 0f6f062f-1478-4df2-96a1-c495d037d260 --type HIERARCHY --name "Org tree" --origin-resource 2eb8bdcf-6d9c-4fbb-9018-7fa8180f4c5e --layout '{"x":0,"y":0,"w":12,"h":6}' --field c60b8526-5835-4c9f-aecd-9a16c7704a34 --field a8f1d7e3-2b5c-4d9e-8a1b-3c4d5e6f7890 --field c52efe3f-2825-4c60-a7e3-34dd4c1ce043 --hierarchy-label "Name" --hierarchy-info "col_1779975207355_zfndknslw:Status" --hierarchy-info "col_1779975243018_qm4t7xb2pa:Description" --hierarchy-number "col_1779975261490_h8kd3nv9ws:Total amount:SUM" --hierarchy-root-name "Customers" --hierarchy-root-label-field c60b8526-5835-4c9f-aecd-9a16c7704a34 --hierarchy-root-info "col_1779975207355_zfndknslw:a8f1d7e3-2b5c-4d9e-8a1b-3c4d5e6f7890" --hierarchy-root-number "col_1779975261490_h8kd3nv9ws:c52efe3f-2825-4c60-a7e3-34dd4c1ce043" --hierarchy-child '{"name":"Projects","schemaId":"3ec9cdef-7e0a-4cdd-8019-8fb9281f5d6f","childFieldId":"80deefae-af3d-4000-b322-bfe1594f8073","labelFieldId":"50dbef0b-7e0a-4fdd-8019-8fb9281f5d70","infoMappings":[{"columnId":"col_1779975243018_qm4t7xb2pa","fieldId":"60dcef0c-8f1b-4eee-9120-9fc0392f6e71"}],"numberMappings":[{"columnId":"col_1779975261490_h8kd3nv9ws","fieldId":"70ddef0d-9f2c-4fff-a221-afd0493f7f72"}]}'`,
       raw: `{
   "type": "HIERARCHY",
   "source": {
@@ -3631,9 +3679,46 @@ var specificExamples = {
   },
   "presentation": { "name": "Org tree" },
   "view": {
-    "fields": ["contact-name", "status"],
+    "fields": [
+      "c60b8526-5835-4c9f-aecd-9a16c7704a34",
+      "a8f1d7e3-2b5c-4d9e-8a1b-3c4d5e6f7890",
+      "c52efe3f-2825-4c60-a7e3-34dd4c1ce043"
+    ],
     "hierarchyConfig": {
-      "parentFieldId": "contact-name"
+      "columns": {
+        "label": "Name",
+        "infos": [
+          { "id": "col_1779975207355_zfndknslw", "name": "Status" },
+          { "id": "col_1779975243018_qm4t7xb2pa", "name": "Description" }
+        ],
+        "numbers": [
+          { "id": "col_1779975261490_h8kd3nv9ws", "name": "Total amount", "aggregation": "SUM" }
+        ]
+      },
+      "rootLevel": {
+        "name": "Customers",
+        "labelFieldId": "c60b8526-5835-4c9f-aecd-9a16c7704a34",
+        "infoMappings": [
+          { "columnId": "col_1779975207355_zfndknslw", "fieldId": "a8f1d7e3-2b5c-4d9e-8a1b-3c4d5e6f7890" }
+        ],
+        "numberMappings": [
+          { "columnId": "col_1779975261490_h8kd3nv9ws", "fieldId": "c52efe3f-2825-4c60-a7e3-34dd4c1ce043" }
+        ]
+      },
+      "childLevels": [
+        {
+          "name": "Projects",
+          "schemaId": "3ec9cdef-7e0a-4cdd-8019-8fb9281f5d6f",
+          "childFieldId": "80deefae-af3d-4000-b322-bfe1594f8073",
+          "labelFieldId": "50dbef0b-7e0a-4fdd-8019-8fb9281f5d70",
+          "infoMappings": [
+            { "columnId": "col_1779975243018_qm4t7xb2pa", "fieldId": "60dcef0c-8f1b-4eee-9120-9fc0392f6e71" }
+          ],
+          "numberMappings": [
+            { "columnId": "col_1779975261490_h8kd3nv9ws", "fieldId": "70ddef0d-9f2c-4fff-a221-afd0493f7f72" }
+          ]
+        }
+      ]
     }
   }
 }`
@@ -3642,13 +3727,13 @@ var specificExamples = {
   "displays widgets update": buildCommandExamples([
     {
       description: "Move placement, update view columns, rename the widget and lock it.",
-      command: `zinkee --json displays widgets update 0f6f062f-1478-4df2-96a1-c495d037d260 11111111-1111-4111-a111-111111111111 --layout '{"x":1,"y":2,"w":8,"h":4}' --field id --field contact-name --field status --name "Revenue Updated" --widget-read-only`,
+      command: `zinkee --json displays widgets update 0f6f062f-1478-4df2-96a1-c495d037d260 11111111-1111-4111-a111-111111111111 --layout '{"x":1,"y":2,"w":8,"h":4}' --field contact-name --field status --field amount --name "Revenue Updated" --widget-read-only`,
       raw: `{
   "placement": {
     "layout": { "x": 1, "y": 2, "w": 8, "h": 4 }
   },
   "view": {
-    "fields": ["id", "contact-name", "status"]
+    "fields": ["contact-name", "status", "amount"]
   },
   "presentation": { "name": "Revenue Updated" },
   "behavior": { "readOnly": true }
@@ -4453,7 +4538,7 @@ var specificExamples = {
     "resources": [
       {
         "id": "2eb8bdcf-6d9c-4fbb-9018-7fa8180f4c5e",
-        "name": "Contacts",
+        "name": "Customer records",
         "type": "SCHEMA",
         "isInSpace": false,
         "additionalProperties": {}
@@ -4477,19 +4562,10 @@ var specificExamples = {
     "resources": [
       {
         "id": "3f8a2c1b-9d4e-4a5b-8c6d-7e8f90123456",
-        "name": "Quote approval",
-        "type": "WORKFLOW",
+        "name": "Shipments",
+        "type": "SCHEMA",
         "isInSpace": false,
         "additionalProperties": {}
-      },
-      {
-        "id": "0f6f062f-1478-4df2-96a1-c495d037d260",
-        "name": "Executive Revenue",
-        "type": "DISPLAY",
-        "isInSpace": true,
-        "additionalProperties": {
-          "pinned": true
-        }
       }
     ],
     "additionalProperties": {
@@ -4536,8 +4612,13 @@ var specificExamples = {
     "name": "Shared Dashboards",
     "order": 1,
     "isRoot": false,
-    "resourceCount": 1,
+    "resourceCount": 2,
     "resources": [
+      {
+        "id": "2eb8bdcf-6d9c-4fbb-9018-7fa8180f4c5e",
+        "name": "Customer records",
+        "type": "SCHEMA"
+      },
       {
         "id": "0f6f062f-1478-4df2-96a1-c495d037d260",
         "name": "Executive Revenue",
@@ -4709,7 +4790,7 @@ var specificExamples = {
         "hideDeleteButton": false
       },
       "view": {
-        "fields": ["id", "contact-name", "status", "amount"],
+        "fields": ["contact-name", "status", "amount"],
         "columnSize": { "contact-name": 240 }
       }
     }
@@ -4756,6 +4837,83 @@ var specificExamples = {
       command: "zinkee --json displays delete 0f6f062f-1478-4df2-96a1-c495d037d260"
     }
   ]),
+  "displays folders list": buildCommandExamples([
+    {
+      description: "List flat display folders (non-root folders plus the root bucket).",
+      command: "zinkee --json displays folders list",
+      response: `[
+  {
+    "id": "e7a1c3d2-5f4b-4a6c-9d8e-1f2a3b4c5d6e",
+    "name": "Executive Dashboards",
+    "isRoot": false,
+    "displayCount": 2
+  },
+  {
+    "id": "8b22282b-3db3-4dd7-87f7-b29365dcf3f6",
+    "name": null,
+    "isRoot": true,
+    "displayCount": 4
+  }
+]`
+    }
+  ]),
+  "displays folders create": buildCommandExamples([
+    {
+      description: "Create one flat display folder.",
+      command: 'zinkee --json displays folders create --name "Executive Dashboards"',
+      raw: `{
+  "name": "Executive Dashboards"
+}`,
+      response: `{
+  "id": "e7a1c3d2-5f4b-4a6c-9d8e-1f2a3b4c5d6e",
+  "name": "Executive Dashboards",
+  "isRoot": false,
+  "displayCount": 0
+}`
+    }
+  ]),
+  "displays folders update": buildCommandExamples([
+    {
+      description: "Rename a display folder. The folder argument accepts a UUID or an exact name.",
+      command: 'zinkee --json displays folders update "Executive Dashboards" --name "Executive Dashboards (2026)"',
+      raw: `{
+  "name": "Executive Dashboards (2026)"
+}`,
+      response: `{
+  "id": "e7a1c3d2-5f4b-4a6c-9d8e-1f2a3b4c5d6e",
+  "name": "Executive Dashboards (2026)",
+  "isRoot": false,
+  "displayCount": 2
+}`
+    }
+  ]),
+  "displays folders delete": buildCommandExamples([
+    {
+      description: "Delete a non-root display folder. Its displays move back to the root folder.",
+      command: 'zinkee --json displays folders delete "Executive Dashboards"',
+      response: `{
+  "id": "e7a1c3d2-5f4b-4a6c-9d8e-1f2a3b4c5d6e",
+  "name": "Executive Dashboards",
+  "isRoot": false,
+  "displayCount": 2
+}`
+    }
+  ]),
+  "displays folders move": buildCommandExamples([
+    {
+      description: "Move one display into a target folder by exact folder name.",
+      command: 'zinkee --json displays folders move 0f6f062f-1478-4df2-96a1-c495d037d260 --to "Executive Dashboards"',
+      raw: `{
+  "displayId": "0f6f062f-1478-4df2-96a1-c495d037d260",
+  "targetFolderId": "e7a1c3d2-5f4b-4a6c-9d8e-1f2a3b4c5d6e"
+}`,
+      response: `{
+  "id": "e7a1c3d2-5f4b-4a6c-9d8e-1f2a3b4c5d6e",
+  "name": "Executive Dashboards",
+  "isRoot": false
+}`
+    }
+  ]),
   "displays layout get": buildCommandExamples([
     {
       description: "Get the layout block of a display (template + tabs/freeformLayouts/slots).",
@@ -4849,7 +5007,7 @@ var specificExamples = {
     "hideDeleteButton": false
   },
   "view": {
-    "fields": ["id", "contact-name", "status", "amount"],
+    "fields": ["contact-name", "status", "amount"],
     "columnSize": { "contact-name": 240 }
   }
 }`
@@ -5769,7 +5927,8 @@ var specificExamples = {
       description: "Move one automation into a target folder by exact folder name.",
       command: 'zinkee --json automations folders move automation-1 --to "Codex Frontend Demo"',
       raw: `{
-  "automationId": "automation-1"
+  "automationId": "automation-1",
+  "targetFolderId": "cdfc14e3-3169-4ffb-8d9b-b11858a9240f"
 }`,
       response: `{
   "id": "cdfc14e3-3169-4ffb-8d9b-b11858a9240f",
@@ -6415,7 +6574,7 @@ var AutomationsApi = class {
   }
   moveAutomation(input) {
     return this.client.requestJson(
-      `/api/v2/automation-folders/${segment(input.targetFolderId)}/automations:move`,
+      "/api/v2/automation-folders/automations:move",
       jsonOptions(input, "POST")
     );
   }
@@ -7560,8 +7719,8 @@ function registerAutomationsCommands(program, options = {}) {
   const filePath = options.configPath ?? defaultConfigPath;
   const stdout = getCommandIo2(options.stdout);
   const automations = program.command("automations").description("Manage automations, triggers, actions, and connections");
-  const folders = automations.command("folders").description("Manage automation folders");
-  folders.command("list").description("List automation folders").action(async function action() {
+  const folders = automations.command("folders").description("Manage automation folders (flat: a folder only has a name, no order or properties)");
+  folders.command("list").description("List automation folders (non-root folders plus the root bucket, whose name is null)").action(async function action() {
     const { api, json } = createAutomationsApi(this, filePath);
     const data = await api.listFolders();
     if (json) {
@@ -7611,7 +7770,11 @@ function registerAutomationsCommands(program, options = {}) {
     }
     writeLine2(stdout, `Deleted automation folder "${folder.value}".`);
   });
-  folders.command("move").description("Move an automation into a folder").argument("<automation>", "automation UUID", parseUuidOrSlugSelector).requiredOption("--to <folder>", "target folder UUID or exact name", parseUuidOrSlugSelector).action(async function action(automation, commandOptions) {
+  folders.command("move").description("Move an automation into a folder").argument("<automation>", "automation UUID", parseUuidOrSlugSelector).requiredOption(
+    "--to <folder>",
+    "target folder UUID or exact name (use the root folder to move it out of any folder)",
+    parseUuidOrSlugSelector
+  ).action(async function action(automation, commandOptions) {
     const { api, json, readOnly } = createAutomationsApi(this, filePath);
     ensureWritable("automations folders move", readOnly, "write");
     if (!commandOptions.to) {
@@ -8296,6 +8459,33 @@ var DisplaysApi = class {
       { method: "DELETE" }
     );
   }
+  listFolders() {
+    return this.client.getJson("/api/v2/display-folders");
+  }
+  createFolder(body) {
+    return this.client.requestJson(
+      "/api/v2/display-folders",
+      jsonOptions3(body, "POST")
+    );
+  }
+  updateFolder(folder, body) {
+    return this.client.requestJson(
+      `/api/v2/display-folders/${selectorValue3(folder)}`,
+      jsonOptions3(body, "PATCH")
+    );
+  }
+  deleteFolder(folder) {
+    return this.client.requestJson(
+      `/api/v2/display-folders/${selectorValue3(folder)}`,
+      { method: "DELETE" }
+    );
+  }
+  moveDisplay(input) {
+    return this.client.requestJson(
+      "/api/v2/display-folders/displays:move",
+      jsonOptions3(input, "POST")
+    );
+  }
 };
 
 // src/parsers/expressions.ts
@@ -8508,6 +8698,150 @@ function readNamedJsonOption(raw, rawFile, inlineFlag = "--option", fileFlag = "
 function isEmptyObject3(value) {
   return Object.keys(value).length === 0;
 }
+function isPlainObject(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function deepMerge(target, source) {
+  const out = { ...target };
+  for (const [key, value] of Object.entries(source)) {
+    const existing = out[key];
+    out[key] = isPlainObject(existing) && isPlainObject(value) ? deepMerge(existing, value) : value;
+  }
+  return out;
+}
+function assignDefined(target, key, value) {
+  if (value !== void 0) target[key] = value;
+}
+function readNamedJsonObject(raw, rawFile, inlineFlag, fileFlag) {
+  const parsed = readNamedJsonOption(raw, rawFile, inlineFlag, fileFlag);
+  if (parsed === void 0) return void 0;
+  if (!isPlainObject(parsed)) {
+    throw new CliError("invalid_cli_usage", `${inlineFlag} payload must be a JSON object.`);
+  }
+  return parsed;
+}
+var HIERARCHY_AGGREGATIONS = /* @__PURE__ */ new Set([
+  "SUM",
+  "AVERAGE",
+  "MINIMUM",
+  "MAXIMUM",
+  "COUNT",
+  "COUNT_DISTINCT"
+]);
+function parseHierarchyInfo(value) {
+  const idx = value.indexOf(":");
+  if (idx <= 0 || idx === value.length - 1) {
+    throw new CliError("invalid_cli_usage", `--hierarchy-info "${value}" must use the format <id:name>.`);
+  }
+  return { id: value.slice(0, idx).trim(), name: value.slice(idx + 1).trim() };
+}
+function parseHierarchyNumber(value) {
+  const parts = value.split(":");
+  if (parts.length < 3) {
+    throw new CliError(
+      "invalid_cli_usage",
+      `--hierarchy-number "${value}" must use the format <id:name:aggregation>.`
+    );
+  }
+  const id = parts[0]?.trim() ?? "";
+  const aggregation = (parts[parts.length - 1]?.trim() ?? "").toUpperCase();
+  const name = parts.slice(1, -1).join(":").trim();
+  if (!id || !name) {
+    throw new CliError(
+      "invalid_cli_usage",
+      `--hierarchy-number "${value}" must use the format <id:name:aggregation>.`
+    );
+  }
+  if (!HIERARCHY_AGGREGATIONS.has(aggregation)) {
+    throw new CliError(
+      "invalid_cli_usage",
+      `--hierarchy-number aggregation "${aggregation}" must be one of SUM, AVERAGE, MINIMUM, MAXIMUM, COUNT, COUNT_DISTINCT.`
+    );
+  }
+  return { id, name, aggregation };
+}
+function parseHierarchyMapping(value, flag) {
+  const idx = value.indexOf(":");
+  if (idx <= 0 || idx === value.length - 1) {
+    throw new CliError("invalid_cli_usage", `${flag} "${value}" must use the format <columnId:fieldId>.`);
+  }
+  return { columnId: value.slice(0, idx).trim(), fieldId: value.slice(idx + 1).trim() };
+}
+function buildWidgetFieldMapping(options) {
+  const mapping = {};
+  assignDefined(mapping, "columnField", options.columnField);
+  assignDefined(mapping, "swimlaneField", options.swimlaneField);
+  assignDefined(mapping, "startDateField", options.startDateField);
+  assignDefined(mapping, "endDateField", options.endDateField);
+  assignDefined(mapping, "labelField", options.labelField);
+  assignDefined(mapping, "groupField", options.groupField);
+  assignDefined(mapping, "subgroupField", options.subgroupField);
+  assignDefined(mapping, "progressField", options.progressField);
+  const cardConfig = {};
+  assignDefined(cardConfig, "titleField", options.cardTitleField);
+  assignDefined(cardConfig, "category1Field", options.cardCategory1Field);
+  assignDefined(cardConfig, "category2Field", options.cardCategory2Field);
+  assignDefined(cardConfig, "category3Field", options.cardCategory3Field);
+  assignDefined(cardConfig, "category4Field", options.cardCategory4Field);
+  assignDefined(cardConfig, "descriptionField", options.cardDescriptionField);
+  if (Object.keys(cardConfig).length > 0) mapping.cardConfig = cardConfig;
+  const aggregationConfig = {};
+  assignDefined(aggregationConfig, "method", options.aggregationMethod);
+  assignDefined(aggregationConfig, "fieldId", options.aggregationField);
+  if (Object.keys(aggregationConfig).length > 0) mapping.aggregationConfig = aggregationConfig;
+  return Object.keys(mapping).length > 0 ? mapping : void 0;
+}
+function buildHierarchyConfig(options) {
+  const base = readNamedJsonObject(
+    options.hierarchyConfig,
+    options.hierarchyConfigFile,
+    "--hierarchy-config",
+    "--hierarchy-config-file"
+  );
+  const patch = {};
+  const columns = {};
+  assignDefined(columns, "label", options.hierarchyLabel);
+  if (options.hierarchyInfo && options.hierarchyInfo.length > 0) {
+    columns.infos = options.hierarchyInfo.map(parseHierarchyInfo);
+  }
+  if (options.hierarchyNumber && options.hierarchyNumber.length > 0) {
+    columns.numbers = options.hierarchyNumber.map(parseHierarchyNumber);
+  }
+  if (Object.keys(columns).length > 0) patch.columns = columns;
+  const rootLevel = {};
+  assignDefined(rootLevel, "name", options.hierarchyRootName);
+  assignDefined(rootLevel, "labelFieldId", options.hierarchyRootLabelField);
+  if (options.hierarchyRootInfo && options.hierarchyRootInfo.length > 0) {
+    rootLevel.infoMappings = options.hierarchyRootInfo.map(
+      (entry) => parseHierarchyMapping(entry, "--hierarchy-root-info")
+    );
+  }
+  if (options.hierarchyRootNumber && options.hierarchyRootNumber.length > 0) {
+    rootLevel.numberMappings = options.hierarchyRootNumber.map(
+      (entry) => parseHierarchyMapping(entry, "--hierarchy-root-number")
+    );
+  }
+  if (Object.keys(rootLevel).length > 0) patch.rootLevel = rootLevel;
+  if (options.hierarchyChild && options.hierarchyChild.length > 0) {
+    patch.childLevels = options.hierarchyChild.map((entry, index) => {
+      let parsed;
+      try {
+        parsed = JSON.parse(entry);
+      } catch {
+        throw new CliError("invalid_cli_usage", `--hierarchy-child payload #${index + 1} is invalid JSON.`);
+      }
+      if (!isPlainObject(parsed)) {
+        throw new CliError(
+          "invalid_cli_usage",
+          `--hierarchy-child payload #${index + 1} must be a JSON object.`
+        );
+      }
+      return parsed;
+    });
+  }
+  if (base === void 0 && Object.keys(patch).length === 0) return void 0;
+  return deepMerge(base ?? {}, patch);
+}
 function displayRows(displays) {
   return displays.map((display) => ({
     id: display.id,
@@ -8523,6 +8857,31 @@ function getDisplaySubresource(value) {
   }
   return value.filter((entry) => Boolean(entry) && typeof entry === "object");
 }
+function displayFolderRows(folders) {
+  return folders.map((folder) => ({
+    id: folder.id ?? "",
+    name: folder.name ?? "",
+    isRoot: folder.isRoot ?? "",
+    displayCount: folder.displayCount ?? ""
+  }));
+}
+async function resolveDisplayFolderId(api, selector) {
+  if (selector.kind === "uuid") {
+    return selector.value;
+  }
+  const folders = await api.listFolders();
+  const matches = folders.filter((folder) => folder.name === selector.value);
+  if (matches.length === 1 && typeof matches[0]?.id === "string" && matches[0].id.length > 0) {
+    return matches[0].id;
+  }
+  if (matches.length > 1) {
+    throw new CliError(
+      "invalid_cli_usage",
+      `Folder "${selector.value}" is ambiguous. Found ${matches.length} matches.`
+    );
+  }
+  throw new CliError("invalid_cli_usage", `Folder "${selector.value}" was not found.`);
+}
 function buildVariableBody(options) {
   const body = {
     ...readRawObject2(options.raw, options.rawFile)
@@ -8589,11 +8948,31 @@ function buildWidgetBody(options) {
       layout
     };
   }
+  const viewPatch = {};
   if (options.field && options.field.length > 0) {
-    body.view = {
-      ...typeof body.view === "object" && body.view ? body.view : {},
-      fields: options.field
-    };
+    viewPatch.fields = options.field;
+  }
+  const fieldMapping = buildWidgetFieldMapping(options);
+  const viewStateBase = readNamedJsonObject(
+    options.viewState,
+    options.viewStateFile,
+    "--view-state",
+    "--view-state-file"
+  );
+  let viewState = viewStateBase ? { ...viewStateBase } : void 0;
+  if (fieldMapping) {
+    viewState = deepMerge(viewState ?? {}, { fieldMapping });
+  }
+  if (viewState !== void 0) {
+    viewPatch.viewAdditionalProperties = { viewState };
+  }
+  const hierarchyConfig = buildHierarchyConfig(options);
+  if (hierarchyConfig !== void 0) {
+    viewPatch.hierarchyConfig = hierarchyConfig;
+  }
+  if (Object.keys(viewPatch).length > 0) {
+    const existingView = typeof body.view === "object" && body.view ? body.view : {};
+    body.view = deepMerge(existingView, viewPatch);
   }
   const queryMerge = {};
   if (options.sort && options.sort.length > 0) queryMerge.sorts = options.sort;
@@ -8728,6 +9107,72 @@ function registerDisplaysCommands(program, options = {}) {
     }
     writeLine4(stdout, `Deleted display "${display.value}".`);
   });
+  const folders = displays.command("folders").description("Manage display folders (flat: a folder only has a name, no order or properties)");
+  folders.command("list").description("List display folders (non-root folders plus the root bucket, whose name is null)").action(async function action() {
+    const { api, json } = createDisplaysApi(this, filePath);
+    const data = await api.listFolders();
+    if (json) {
+      emitJson4(stdout, "displays folders list", data);
+      return;
+    }
+    printTable(displayFolderRows(data), ["id", "name", "isRoot", "displayCount"], stdout);
+  });
+  folders.command("create").description("Create a display folder").requiredOption("--name <name>", "folder name").action(async function action(commandOptions) {
+    const { api, json, readOnly } = createDisplaysApi(this, filePath);
+    ensureWritable3("displays folders create", readOnly, "write");
+    if (commandOptions.name === void 0) {
+      throw new CliError("invalid_cli_usage", 'Provide folder name via "--name".');
+    }
+    const data = await api.createFolder({ name: commandOptions.name });
+    if (json) {
+      emitJson4(stdout, "displays folders create", data);
+      return;
+    }
+    writeLine4(stdout, `Created display folder "${String(data.name ?? commandOptions.name)}".`);
+  });
+  folders.command("update").description("Rename a display folder").argument("<folder>", "folder UUID or exact name", parseUuidOrSlugSelector3).requiredOption("--name <name>", "folder name").action(async function action(folder, commandOptions) {
+    const { api, json, readOnly } = createDisplaysApi(this, filePath);
+    ensureWritable3("displays folders update", readOnly, "write");
+    if (commandOptions.name === void 0) {
+      throw new CliError("invalid_cli_usage", 'Provide folder name via "--name".');
+    }
+    const folderId = await resolveDisplayFolderId(api, folder);
+    const data = await api.updateFolder({ kind: "uuid", value: folderId }, { name: commandOptions.name });
+    if (json) {
+      emitJson4(stdout, "displays folders update", data);
+      return;
+    }
+    writeLine4(stdout, `Updated display folder "${String(data.name ?? folder.value)}".`);
+  });
+  folders.command("delete").description("Delete a display folder (its displays move back to the root folder)").argument("<folder>", "folder UUID or exact name", parseUuidOrSlugSelector3).action(async function action(folder) {
+    const { api, json, readOnly } = createDisplaysApi(this, filePath);
+    ensureWritable3("displays folders delete", readOnly, "destructive");
+    const folderId = await resolveDisplayFolderId(api, folder);
+    const data = await api.deleteFolder({ kind: "uuid", value: folderId });
+    if (json) {
+      emitJson4(stdout, "displays folders delete", data);
+      return;
+    }
+    writeLine4(stdout, `Deleted display folder "${folder.value}".`);
+  });
+  folders.command("move").description("Move a display into a folder").argument("<display>", "display UUID", parseUuidOrSlugSelector3).requiredOption(
+    "--to <folder>",
+    "target folder UUID or exact name (use the root folder to move it out of any folder)",
+    parseUuidOrSlugSelector3
+  ).action(async function action(display, commandOptions) {
+    const { api, json, readOnly } = createDisplaysApi(this, filePath);
+    ensureWritable3("displays folders move", readOnly, "write");
+    if (!commandOptions.to) {
+      throw new CliError("invalid_cli_usage", 'Provide target folder via "--to".');
+    }
+    const targetFolderId = await resolveDisplayFolderId(api, commandOptions.to);
+    const data = await api.moveDisplay({ displayId: display.value, targetFolderId });
+    if (json) {
+      emitJson4(stdout, "displays folders move", data);
+      return;
+    }
+    writeLine4(stdout, `Moved display "${display.value}" to folder "${targetFolderId}".`);
+  });
   const layout = displays.command("layout").description("Manage display layout");
   layout.command("get").description("Get display layout").argument("<display>", "display uuid or slug", parseUuidOrSlugSelector3).action(async function action(display) {
     const { api, json } = createDisplaysApi(this, filePath);
@@ -8866,7 +9311,7 @@ function registerDisplaysCommands(program, options = {}) {
     }
     printTable([data], void 0, stdout);
   });
-  widgets.command("create").description("Create widget").argument("<display>", "display uuid or slug", parseUuidOrSlugSelector3).requiredOption("--type <type>", "widget type").option("--name <name>").option("--description <text>").option("--icon <icon>").option("--color <color>").option("--origin-resource <uuid>").option("--origin-subschema").option("--tab <tabId>").option("--slot <slotId>").option("--layout <json>").option("--layout-file <path>").option("--field <field>", "repeatable field", (v, p = []) => [...p, v], []).option("--sort <sort>", "repeatable sort", (v, p = []) => [...p, v], []).option("--filter <expr>", "repeatable filter", collectFilters, []).option("--widget-read-only").option("--hide-add-button").option("--hide-delete-button").option("--hide-sort-button").option("--hide-filter-button").option("--hide-see-button").option("--calc <type>").option("--calc-field <uuid>").option("--kpi-config <json>").option("--chart-type <type>", "chart type (lines, bars, stackedBars, combined)").option("--x-axis-field <uuid>").option("--x-axis-date-format <granularity>", "time granularity (DATE, MONTH_YEAR, QUARTER_YEAR, YEAR)").option("--x-axis-time-series").option("--y-axis-serie <json>", "repeatable y axis serie", (v, p = []) => [...p, v], []).option("--legend <json>").option("--raw <json>").option("--raw-file <path>").action(async function action(display, commandOptions) {
+  widgets.command("create").description("Create widget").argument("<display>", "display uuid or slug", parseUuidOrSlugSelector3).requiredOption("--type <type>", "widget type").option("--name <name>").option("--description <text>").option("--icon <icon>").option("--color <color>").option("--origin-resource <uuid>").option("--origin-subschema").option("--tab <tabId>").option("--slot <slotId>").option("--layout <json>").option("--layout-file <path>").option("--field <field>", "repeatable field", (v, p = []) => [...p, v], []).option("--sort <sort>", "repeatable sort", (v, p = []) => [...p, v], []).option("--filter <expr>", "repeatable filter", collectFilters, []).option("--widget-read-only").option("--hide-add-button").option("--hide-delete-button").option("--hide-sort-button").option("--hide-filter-button").option("--hide-see-button").option("--calc <type>").option("--calc-field <uuid>").option("--kpi-config <json>").option("--chart-type <type>", "chart type (lines, bars, stackedBars, combined)").option("--x-axis-field <uuid>").option("--x-axis-date-format <granularity>", "time granularity (DATE, MONTH_YEAR, QUARTER_YEAR, YEAR)").option("--x-axis-time-series").option("--y-axis-serie <json>", "repeatable y axis serie", (v, p = []) => [...p, v], []).option("--legend <json>").option("--column-field <uuid>", "KANBAN column field (UUID, not slug)").option("--swimlane-field <uuid>", "KANBAN swimlane field (UUID, not slug)").option("--start-date-field <uuid>", "TIMELINE start date field (UUID, not slug)").option("--end-date-field <uuid>", "TIMELINE end date field (UUID, not slug)").option("--label-field <uuid>", "TIMELINE label field (UUID, not slug)").option("--group-field <uuid>", "TIMELINE group field (UUID, not slug)").option("--subgroup-field <uuid>", "TIMELINE subgroup field (UUID, not slug)").option("--progress-field <uuid>", "TIMELINE progress field (UUID, not slug)").option("--card-title-field <uuid>", "KANBAN/TIMELINE card title field (UUID, not slug)").option("--card-category1-field <uuid>", "KANBAN/TIMELINE card category 1 field (UUID, not slug)").option("--card-category2-field <uuid>", "KANBAN/TIMELINE card category 2 field (UUID, not slug)").option("--card-category3-field <uuid>", "KANBAN card category 3 field (UUID, not slug)").option("--card-category4-field <uuid>", "TIMELINE card category 4 field (UUID, not slug)").option("--card-description-field <uuid>", "KANBAN/TIMELINE card description field (UUID, not slug)").option("--aggregation-method <method>", "KANBAN card aggregation method (e.g. sum)").option("--aggregation-field <uuid>", "KANBAN card aggregation field (UUID, not slug)").option("--view-state <json>", "KANBAN/TIMELINE viewState UI scalars (columnOrder, granularity, sidebarWidth, show* ...)").option("--view-state-file <path>", "read --view-state JSON from a file").option("--hierarchy-label <name>", "HIERARCHY label column name").option("--hierarchy-info <id:name>", "HIERARCHY info column; id is a unique opaque column id you choose (e.g. col_1779975207355_zfndknslw), not the name, and is reused as columnId in mappings (repeatable)", (v, p = []) => [...p, v], []).option("--hierarchy-number <id:name:aggregation>", "HIERARCHY number column; id is a unique opaque column id (e.g. col_1779975207355_zfndknslw), not the name; aggregation SUM|AVERAGE|MINIMUM|MAXIMUM|COUNT|COUNT_DISTINCT (repeatable)", (v, p = []) => [...p, v], []).option("--hierarchy-root-name <name>", "HIERARCHY root level name").option("--hierarchy-root-label-field <uuid>", "HIERARCHY root level label field (UUID, not slug)").option("--hierarchy-root-info <columnId:fieldId>", "HIERARCHY root info mapping; columnId must match a --hierarchy-info id (repeatable)", (v, p = []) => [...p, v], []).option("--hierarchy-root-number <columnId:fieldId>", "HIERARCHY root number mapping; columnId must match a --hierarchy-number id (repeatable)", (v, p = []) => [...p, v], []).option("--hierarchy-child <json>", "HIERARCHY child level JSON {name,schemaId,childFieldId,labelFieldId,infoMappings,numberMappings} (repeatable)", (v, p = []) => [...p, v], []).option("--hierarchy-config <json>", "HIERARCHY full hierarchyConfig JSON (escape hatch)").option("--hierarchy-config-file <path>", "read --hierarchy-config JSON from a file").option("--raw <json>").option("--raw-file <path>").action(async function action(display, commandOptions) {
     const { api, json, readOnly } = createDisplaysApi(this, filePath);
     ensureWritable3("displays widgets create", readOnly, "write");
     const data = await api.createWidget(display, buildWidgetBody(commandOptions));
@@ -8876,7 +9321,7 @@ function registerDisplaysCommands(program, options = {}) {
     }
     writeLine4(stdout, `Created widget on display "${display.value}".`);
   });
-  widgets.command("update").description("Update widget").argument("<display>", "display uuid or slug", parseUuidOrSlugSelector3).argument("<widget>", "widget id").option("--type <type>").option("--name <name>").option("--description <text>").option("--icon <icon>").option("--color <color>").option("--origin-resource <uuid>").option("--origin-subschema").option("--tab <tabId>").option("--slot <slotId>").option("--layout <json>").option("--layout-file <path>").option("--field <field>", "repeatable field", (v, p = []) => [...p, v], []).option("--sort <sort>", "repeatable sort", (v, p = []) => [...p, v], []).option("--filter <expr>", "repeatable filter", collectFilters, []).option("--widget-read-only").option("--hide-add-button").option("--hide-delete-button").option("--hide-sort-button").option("--hide-filter-button").option("--hide-see-button").option("--calc <type>").option("--calc-field <uuid>").option("--kpi-config <json>").option("--chart-type <type>", "chart type (lines, bars, stackedBars, combined)").option("--x-axis-field <uuid>").option("--x-axis-date-format <granularity>", "time granularity (DATE, MONTH_YEAR, QUARTER_YEAR, YEAR)").option("--x-axis-time-series").option("--y-axis-serie <json>", "repeatable y axis serie", (v, p = []) => [...p, v], []).option("--legend <json>").option("--raw <json>").option("--raw-file <path>").action(async function action(display, widgetId, commandOptions) {
+  widgets.command("update").description("Update widget").argument("<display>", "display uuid or slug", parseUuidOrSlugSelector3).argument("<widget>", "widget id").option("--type <type>").option("--name <name>").option("--description <text>").option("--icon <icon>").option("--color <color>").option("--origin-resource <uuid>").option("--origin-subschema").option("--tab <tabId>").option("--slot <slotId>").option("--layout <json>").option("--layout-file <path>").option("--field <field>", "repeatable field", (v, p = []) => [...p, v], []).option("--sort <sort>", "repeatable sort", (v, p = []) => [...p, v], []).option("--filter <expr>", "repeatable filter", collectFilters, []).option("--widget-read-only").option("--hide-add-button").option("--hide-delete-button").option("--hide-sort-button").option("--hide-filter-button").option("--hide-see-button").option("--calc <type>").option("--calc-field <uuid>").option("--kpi-config <json>").option("--chart-type <type>", "chart type (lines, bars, stackedBars, combined)").option("--x-axis-field <uuid>").option("--x-axis-date-format <granularity>", "time granularity (DATE, MONTH_YEAR, QUARTER_YEAR, YEAR)").option("--x-axis-time-series").option("--y-axis-serie <json>", "repeatable y axis serie", (v, p = []) => [...p, v], []).option("--legend <json>").option("--column-field <uuid>", "KANBAN column field (UUID, not slug)").option("--swimlane-field <uuid>", "KANBAN swimlane field (UUID, not slug)").option("--start-date-field <uuid>", "TIMELINE start date field (UUID, not slug)").option("--end-date-field <uuid>", "TIMELINE end date field (UUID, not slug)").option("--label-field <uuid>", "TIMELINE label field (UUID, not slug)").option("--group-field <uuid>", "TIMELINE group field (UUID, not slug)").option("--subgroup-field <uuid>", "TIMELINE subgroup field (UUID, not slug)").option("--progress-field <uuid>", "TIMELINE progress field (UUID, not slug)").option("--card-title-field <uuid>", "KANBAN/TIMELINE card title field (UUID, not slug)").option("--card-category1-field <uuid>", "KANBAN/TIMELINE card category 1 field (UUID, not slug)").option("--card-category2-field <uuid>", "KANBAN/TIMELINE card category 2 field (UUID, not slug)").option("--card-category3-field <uuid>", "KANBAN card category 3 field (UUID, not slug)").option("--card-category4-field <uuid>", "TIMELINE card category 4 field (UUID, not slug)").option("--card-description-field <uuid>", "KANBAN/TIMELINE card description field (UUID, not slug)").option("--aggregation-method <method>", "KANBAN card aggregation method (e.g. sum)").option("--aggregation-field <uuid>", "KANBAN card aggregation field (UUID, not slug)").option("--view-state <json>", "KANBAN/TIMELINE viewState UI scalars (columnOrder, granularity, sidebarWidth, show* ...)").option("--view-state-file <path>", "read --view-state JSON from a file").option("--hierarchy-label <name>", "HIERARCHY label column name").option("--hierarchy-info <id:name>", "HIERARCHY info column; id is a unique opaque column id you choose (e.g. col_1779975207355_zfndknslw), not the name, and is reused as columnId in mappings (repeatable)", (v, p = []) => [...p, v], []).option("--hierarchy-number <id:name:aggregation>", "HIERARCHY number column; id is a unique opaque column id (e.g. col_1779975207355_zfndknslw), not the name; aggregation SUM|AVERAGE|MINIMUM|MAXIMUM|COUNT|COUNT_DISTINCT (repeatable)", (v, p = []) => [...p, v], []).option("--hierarchy-root-name <name>", "HIERARCHY root level name").option("--hierarchy-root-label-field <uuid>", "HIERARCHY root level label field (UUID, not slug)").option("--hierarchy-root-info <columnId:fieldId>", "HIERARCHY root info mapping; columnId must match a --hierarchy-info id (repeatable)", (v, p = []) => [...p, v], []).option("--hierarchy-root-number <columnId:fieldId>", "HIERARCHY root number mapping; columnId must match a --hierarchy-number id (repeatable)", (v, p = []) => [...p, v], []).option("--hierarchy-child <json>", "HIERARCHY child level JSON {name,schemaId,childFieldId,labelFieldId,infoMappings,numberMappings} (repeatable)", (v, p = []) => [...p, v], []).option("--hierarchy-config <json>", "HIERARCHY full hierarchyConfig JSON (escape hatch)").option("--hierarchy-config-file <path>", "read --hierarchy-config JSON from a file").option("--raw <json>").option("--raw-file <path>").action(async function action(display, widgetId, commandOptions) {
     const { api, json, readOnly } = createDisplaysApi(this, filePath);
     ensureWritable3("displays widgets update", readOnly, "write");
     const data = await api.updateWidget(display, widgetId, buildWidgetBody(commandOptions));
@@ -9901,7 +10346,7 @@ function registerNavigationCommands(program, options = {}) {
     }
     printTable(folderRows2([resolved]), ["id", "order", "name", "resourceCount"], stdout);
   });
-  folders.command("create").description("Create a navigation folder").requiredOption("--name <name>", "folder name").option("--order <n>", "folder order").option("--props <json>", "folder additionalProperties JSON").option("--props-file <path>", "folder additionalProperties JSON file").action(async function action(commandOptions) {
+  folders.command("create").description("Create a navigation folder").requiredOption("--name <name>", "folder name").option("--order <n>", "display order (lower values appear first)").option("--props <json>", 'additionalProperties JSON: free-form client metadata, e.g. {"color":"blue","icon":"chart-line"}').option("--props-file <path>", "path to a file with the additionalProperties JSON").action(async function action(commandOptions) {
     const { api, json, readOnly } = createNavigationApi(this, filePath);
     ensureWritable6("navigation folders create", readOnly, "write");
     const data = await api.createFolder(buildFolderBody(commandOptions));
@@ -9911,7 +10356,7 @@ function registerNavigationCommands(program, options = {}) {
     }
     writeLine8(stdout, `Created navigation folder "${String(data.name ?? commandOptions.name)}".`);
   });
-  folders.command("update").description("Update a navigation folder").argument("<folder>", "folder UUID or exact name", parseUuidOrSlugSelector7).option("--name <name>", "folder name").option("--order <n>", "folder order").option("--props <json>", "folder additionalProperties JSON").option("--props-file <path>", "folder additionalProperties JSON file").action(async function action(folder, commandOptions) {
+  folders.command("update").description("Update a navigation folder").argument("<folder>", "folder UUID or exact name", parseUuidOrSlugSelector7).option("--name <name>", "folder name").option("--order <n>", "display order (lower values appear first)").option("--props <json>", 'additionalProperties JSON: free-form client metadata, e.g. {"color":"blue","icon":"chart-line"}').option("--props-file <path>", "path to a file with the additionalProperties JSON").action(async function action(folder, commandOptions) {
     const { api, json, readOnly } = createNavigationApi(this, filePath);
     ensureWritable6("navigation folders update", readOnly, "write");
     const allFolders = await api.listFolders();
@@ -9939,14 +10384,15 @@ function registerNavigationCommands(program, options = {}) {
     }
     writeLine8(stdout, `Deleted navigation folder "${resolved.name ?? resolved.id}".`);
   });
-  navigation.command("resources").description("Manage navigation resources").command("move").description("Move a resource into a folder").argument("<resource>", "resource UUID").requiredOption("--type <type>", "resource type").requiredOption("--to <folder>", "target folder UUID or exact name").action(async function action(resourceId, commandOptions) {
+  navigation.command("resources").description("Manage navigation resources").command("move").description(
+    "Move a schema into a navigation folder. Only schemas can be moved (the navigation menu holds databases); schedules and sub-schemas follow their parent schema. Use the root folder UUID 00000000-0000-0000-0000-000000000000 to move it back to the workspace root."
+  ).argument("<resource>", "schema UUID").requiredOption("--to <folder>", "target folder UUID or exact name").action(async function action(resourceId, commandOptions) {
     const { api, json, readOnly } = createNavigationApi(this, filePath);
     ensureWritable6("navigation resources move", readOnly, "write");
     const allFolders = await api.listFolders();
     const resolved = resolveFolder2(allFolders, parseUuidOrSlugSelector7(commandOptions.to));
     const data = await api.moveResource({
       resourceId,
-      resourceType: commandOptions.type.toUpperCase(),
       targetFolderId: resolved.id
     });
     if (json) {
@@ -11479,7 +11925,7 @@ function registerTeamspaceCommands(program, options = {}) {
   const stdout = getCommandIo12(options.stdout);
   const teamspace = program.command("teamspace").description("Manage teamspace folders and resources");
   const folders = teamspace.command("folders").description("Manage teamspace folders");
-  folders.command("list").description("List teamspace folders").option("--include-resources", "include nested resources").action(async function action(commandOptions) {
+  folders.command("list").description("List teamspace folders").option("--include-resources", "include the published resources inside each folder").action(async function action(commandOptions) {
     const { api, json } = createTeamspaceApi(this, filePath);
     const data = await api.listFolders(Boolean(commandOptions.includeResources));
     if (json) {
@@ -11488,7 +11934,7 @@ function registerTeamspaceCommands(program, options = {}) {
     }
     emitTable5(stdout, data);
   });
-  folders.command("get").description("Get a teamspace folder by exact name or UUID").argument("<folder>", "folder UUID or exact name", parseUuidOrSlugSelector10).option("--include-resources", "include nested resources").action(async function action(folder, commandOptions) {
+  folders.command("get").description("Get a teamspace folder by exact name or UUID").argument("<folder>", "folder UUID or exact name", parseUuidOrSlugSelector10).option("--include-resources", "include the published resources inside each folder").action(async function action(folder, commandOptions) {
     const { api, json } = createTeamspaceApi(this, filePath);
     const resolvedFolder = await resolveFolderSelector2(api, folder);
     const allFolders = await api.listFolders(Boolean(commandOptions.includeResources));
@@ -11499,7 +11945,7 @@ function registerTeamspaceCommands(program, options = {}) {
     }
     emitTable5(stdout, data);
   });
-  folders.command("create").description("Create a teamspace folder").requiredOption("--name <name>", "folder name").option("--order <n>", "folder order", parseNonNegativeInteger3).option("--props <json>", "folder properties payload").option("--props-file <path>", "path to a folder properties JSON payload").action(async function action(commandOptions) {
+  folders.command("create").description("Create a teamspace folder").requiredOption("--name <name>", "folder name").option("--order <n>", "display order (lower values appear first)", parseNonNegativeInteger3).option("--props <json>", 'additionalProperties JSON: free-form client metadata, e.g. {"icon":"folder-users","color":"gold"}').option("--props-file <path>", "path to a file with the additionalProperties JSON").action(async function action(commandOptions) {
     const { api, json, readOnly } = createTeamspaceApi(this, filePath);
     ensureWritable9("teamspace folders create", readOnly, "write");
     const data = await api.createFolder(buildFolderCreateInput(commandOptions));
@@ -11509,7 +11955,7 @@ function registerTeamspaceCommands(program, options = {}) {
     }
     writeLine12(stdout, `Created folder "${getFolderIdentifier(data)}".`);
   });
-  folders.command("update").description("Update a teamspace folder").argument("<folder>", "folder UUID or exact name", parseUuidOrSlugSelector10).option("--name <name>", "folder name").option("--order <n>", "folder order", parseNonNegativeInteger3).option("--props <json>", "folder properties payload").option("--props-file <path>", "path to a folder properties JSON payload").action(async function action(folder, commandOptions) {
+  folders.command("update").description("Update a teamspace folder").argument("<folder>", "folder UUID or exact name", parseUuidOrSlugSelector10).option("--name <name>", "folder name").option("--order <n>", "display order (lower values appear first)", parseNonNegativeInteger3).option("--props <json>", 'additionalProperties JSON: free-form client metadata, e.g. {"icon":"folder-users","color":"gold"}').option("--props-file <path>", "path to a file with the additionalProperties JSON").action(async function action(folder, commandOptions) {
     const { api, json, readOnly } = createTeamspaceApi(this, filePath);
     ensureWritable9("teamspace folders update", readOnly, "write");
     const resolvedFolder = await resolveFolderSelector2(api, folder);
@@ -11532,7 +11978,13 @@ function registerTeamspaceCommands(program, options = {}) {
     writeLine12(stdout, `Deleted folder "${resolvedFolder.value}".`);
   });
   const resources = teamspace.command("resources").description("Manage teamspace resources");
-  resources.command("publish").description("Publish a resource to a teamspace folder").argument("<resource>", "resource UUID or exact name", parseUuidOrSlugSelector10).requiredOption("--to <folder>", "target folder", parseUuidOrSlugSelector10).action(async function action(resource, commandOptions) {
+  resources.command("publish").description(
+    "Publish a resource to a teamspace folder. Publishing an already-published resource moves it to the new folder."
+  ).argument("<resource>", "schema UUID, schema slug, or display UUID", parseUuidOrSlugSelector10).requiredOption(
+    "--to <folder>",
+    "target folder UUID or exact name (root folder UUID is 00000000-0000-0000-0000-000000000000)",
+    parseUuidOrSlugSelector10
+  ).action(async function action(resource, commandOptions) {
     const { api, json, readOnly } = createTeamspaceApi(this, filePath);
     ensureWritable9("teamspace resources publish", readOnly, "write");
     const folder = await resolveFolderSelector2(api, commandOptions.to);
@@ -11546,7 +11998,7 @@ function registerTeamspaceCommands(program, options = {}) {
     }
     writeLine12(stdout, `Published resource "${resource.value}" to folder "${folder.value}".`);
   });
-  resources.command("unpublish").description("Unpublish a resource from teamspace").argument("<resource>", "resource UUID or exact name", parseUuidOrSlugSelector10).action(async function action(resource) {
+  resources.command("unpublish").description("Unpublish a resource from teamspace (removes it from its shared folder)").argument("<resource>", "schema UUID, schema slug, or display UUID", parseUuidOrSlugSelector10).action(async function action(resource) {
     const { api, json, readOnly } = createTeamspaceApi(this, filePath);
     ensureWritable9("teamspace resources unpublish", readOnly, "write");
     const data = await api.unpublishResource(resource.value);