@carthooks/arcubase-cli 0.1.22 → 0.1.24

package/dist/runtime/execute.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"execute.d.ts","sourceRoot":"","sources":["../../src/runtime/execute.ts"],"names":[],"mappings":"AAGA,OAAO,EAAkB,KAAK,UAAU,EAAE,MAAM,UAAU,CAAA;AAG1D,OAAO,EAAyF,KAAK,YAAY,EAAE,MAAM,uBAAuB,CAAA;AAShJ,MAAM,MAAM,uBAAuB,GAAG;IACpC,KAAK,EAAE,YAAY,CAAA;IACnB,WAAW,EAAE,SAAS,MAAM,EAAE,CAAA;IAC9B,MAAM,EAAE,MAAM,CAAA;IACd,QAAQ,EAAE,MAAM,CAAA;IAChB,WAAW,EAAE,MAAM,GAAG,IAAI,CAAA;IAC1B,SAAS,EAAE,SAAS,MAAM,EAAE,CAAA;IAC5B,UAAU,EAAE,SAAS,MAAM,EAAE,CAAA;CAC9B,CAAA;AAED,wBAAgB,cAAc,CAAC,KAAK,EAAE,YAAY,GAAG,MAAM,CAe1D;AAaD,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,EAAE,GAAG,GAAE,QAAsB,GAAG,MAAM,CAoB7G;AA8BD,KAAK,QAAQ,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAA;AAUlD,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,EAAE,WAAW,CAAC,EAAE,MAAM,EAAE,GAAG,GAAE,QAAsB,GAAG,MAAM,CA8HpI;AAurED,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,uBAAuB,CActH;AAED,wBAAsB,UAAU,CAAC,KAAK,EAAE,YAAY,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE,GAAG,CAAC,EAAE,UAAU,EAAE,SAAS,GAAE,OAAO,KAAa,GAAG,OAAO,CAAC,GAAG,CAAC,CAyOrI"}
+{"version":3,"file":"execute.d.ts","sourceRoot":"","sources":["../../src/runtime/execute.ts"],"names":[],"mappings":"AAGA,OAAO,EAAkB,KAAK,UAAU,EAAE,MAAM,UAAU,CAAA;AAG1D,OAAO,EAAyF,KAAK,YAAY,EAAE,MAAM,uBAAuB,CAAA;AAShJ,MAAM,MAAM,uBAAuB,GAAG;IACpC,KAAK,EAAE,YAAY,CAAA;IACnB,WAAW,EAAE,SAAS,MAAM,EAAE,CAAA;IAC9B,MAAM,EAAE,MAAM,CAAA;IACd,QAAQ,EAAE,MAAM,CAAA;IAChB,WAAW,EAAE,MAAM,GAAG,IAAI,CAAA;IAC1B,SAAS,EAAE,SAAS,MAAM,EAAE,CAAA;IAC5B,UAAU,EAAE,SAAS,MAAM,EAAE,CAAA;CAC9B,CAAA;AAED,wBAAgB,cAAc,CAAC,KAAK,EAAE,YAAY,GAAG,MAAM,CAe1D;AAaD,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,EAAE,GAAG,GAAE,QAAsB,GAAG,MAAM,CAoB7G;AA8BD,KAAK,QAAQ,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAA;AAUlD,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,EAAE,WAAW,CAAC,EAAE,MAAM,EAAE,GAAG,GAAE,QAAsB,GAAG,MAAM,CA8HpI;AAquED,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,uBAAuB,CActH;AAED,wBAAsB,UAAU,CAAC,KAAK,EAAE,YAAY,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE,GAAG,CAAC,EAAE,UAAU,EAAE,SAAS,GAAE,OAAO,KAAa,GAAG,OAAO,CAAC,GAAG,CAAC,CAyOrI"}

package/dist/runtime/execute.js

@@ -948,15 +948,37 @@ function buildBodyGuidance(requestType) {
                 dataSourceType: 'entity',
                 dimensions: [{ IsField: true, FieldID: 1004, Name: 'Source' }],
                 measures: [{ FieldID: 1005, Aggregate: 'sum', Name: 'Total Amount' }],
+                conditions: { mode: 'and', conditions: [{ column: ':1006', operator: '$eq', value: 'yes' }] },
             },
             commonMistakes: [
                 'widget preview-data body is the chart query itself',
                 'do not send a saved widget object with id, entity_id, or options',
                 'field dimensions with FieldID must set IsField:true',
+                'use conditions, not filters, for chart data filtering',
+                'do not retry without conditions and then hand-calculate filtered statistics',
                 'unsupported aggregates are invalid; use sum, avg, max, min, count, or distinct_count',
             ],
             suggestions: [
                 'retry with: arcubase-admin widget preview-data --app-id <app_id> --body-json \'{"dataSource":<table_id>,"dataSourceType":"entity","dimensions":[{"IsField":true,"FieldID":<field_id>,"Name":"Source"}],"measures":[{"FieldID":<number_field_id>,"Aggregate":"sum","Name":"Total Amount"}]}\'',
+                'conditional stats: arcubase-admin widget preview-data --app-id <app_id> --body-json \'{"dataSource":<table_id>,"dataSourceType":"entity","dimensions":[{"IsField":true,"FieldID":<source_field_id>,"Name":"Source"}],"conditions":{"mode":"and","conditions":[{"column":":1006","operator":"$eq","value":"yes"}]},"measures":[{"FieldID":<customer_field_id>,"Aggregate":"distinct_count","Name":"Distinct Customers"}]}\'',
+            ],
+        };
+    }
+    if (requestType === 'AppNewWidgetsReqVO') {
+        return {
+            shapeHint: {
+                type: 'list',
+                options: { ingress_id: 2188893001 },
+            },
+            commonMistakes: [
+                'dashboard widgets use options.dashboard_id',
+                'ingress widgets use options.ingress_id',
+                'do not put entity_id at body top level or under options when creating a widget',
+                'after creating an ingress widget, use widget update-ingress-options to adjust display configuration',
+            ],
+            suggestions: [
+                'dashboard chart: arcubase-admin widget create --app-id <app_id> --body-json \'{"type":"chart","options":{"dashboard_id":<dashboard_id>}}\'',
+                'ingress list: arcubase-admin widget create --app-id <app_id> --body-json \'{"type":"list","options":{"ingress_id":<ingress_id>}}\'',
             ],
         };
     }
@@ -969,15 +991,39 @@ function buildBodyGuidance(requestType) {
                         entity_id: 2188891001,
                         dimensions: [{ IsField: true, FieldID: 1004, Name: 'Source' }],
                         measures: [{ FieldID: 1005, Aggregate: 'sum', Name: 'Total Amount' }],
+                        conditions: { mode: 'and', conditions: [{ column: ':1006', operator: '$eq', value: 'yes' }] },
                         type: 'bar',
                     },
                 },
             },
             commonMistakes: [
                 'dashboard chart config belongs in body.options.charts',
+                'ingress/list display settings use widget update-ingress-options, not widget update',
+                'do not put ingress_id, list, default_cols, page_size, or entry display settings in widget update',
                 'field dimensions with FieldID must set IsField:true',
+                'use options.charts.conditions, not filters, for chart data filtering',
+                'do not retry without conditions and then hand-calculate filtered statistics',
                 'verify persistence with widget get or widget list after update',
             ],
+            suggestions: [
+                'dashboard chart: arcubase-admin widget update --app-id <app_id> --widget-id <widget_id> --body-json \'{"entity_id":<table_id>,"options":{"charts":{"entity_id":<table_id>,"dimensions":[{"IsField":true,"FieldID":<field_id>,"Name":"Source"}],"measures":[{"FieldID":<number_field_id>,"Aggregate":"sum","Name":"Total Amount"}],"type":"bar"}}}\'',
+                'ingress list display: arcubase-admin widget update-ingress-options --app-id <app_id> --widget-id <widget_id> --body-json \'{"options":{"cond_follow":true,"cond_follow_tab":true,"cond_follow_cols":[":1001",":1002"]}}\'',
+            ],
+        };
+    }
+    if (requestType === 'AppUpdateWidgetsIngressOptionsReqVO') {
+        return {
+            shapeHint: {
+                options: { cond_follow: true, cond_follow_tab: true, cond_follow_cols: [':1001', ':1002'] },
+            },
+            commonMistakes: [
+                'widget update-ingress-options is for ingress widgets, not dashboard chart widgets',
+                'put display settings under body.options',
+                'verify the ingress widget with widget get after update',
+            ],
+            suggestions: [
+                'retry with: arcubase-admin widget update-ingress-options --app-id <app_id> --widget-id <widget_id> --body-json \'{"options":{"cond_follow":true,"cond_follow_tab":true,"cond_follow_cols":[":1001",":1002"]}}\'',
+            ],
         };
     }
     return {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@carthooks/arcubase-cli",
-  "version": "0.1.22",
+  "version": "0.1.24",
   "description": "Arcubase runtime CLI for admin and user command execution",
   "type": "module",
   "main": "./dist/index.js",
@@ -9,8 +9,8 @@
     ".": "./dist/index.js"
   },
   "bin": {
-    "arcubase-admin": "./dist/bin/arcubase-admin.js",
-    "arcubase": "./dist/bin/arcubase.js"
+    "arcubase-admin": "dist/bin/arcubase-admin.js",
+    "arcubase": "dist/bin/arcubase.js"
   },
   "files": [
     "dist",

package/sdk-dist/docs/runtime-reference/dashboard.md

@@ -1,9 +1,24 @@
 # Dashboard
 
-Use `arcubase dashboard get` and `arcubase dashboard widgets` to read dashboards as a tenant user.
+Use `arcubase app get`, `arcubase dashboard get`, and `arcubase dashboard widgets` to read dashboards as a tenant user.
+
+User dashboard discovery:
+
+- `arcubase entry` lists the current user's visible apps and tables.
+- `arcubase app get --app-id <app_id>` returns app detail, including dashboards visible to the current user.
+- To find a dashboard by name, run `app get` for candidate apps from `entry`, match `Dashboard[].Name`, then use that app id and dashboard id with `dashboard get`, `dashboard widgets`, and `widget data`.
+- Do not use admin dashboard commands to prove a normal user's dashboard visibility.
 
 Use `arcubase-admin dashboard list`, `arcubase-admin dashboard create`, `arcubase-admin dashboard get-options`, `arcubase-admin dashboard update-options`, `arcubase-admin dashboard update-layout`, and `arcubase-admin dashboard rename` to manage dashboards as an admin.
 
+Dashboard visibility:
+
+- A dashboard is user-visible only when its options include a matching user scope.
+- After `dashboard create`, call `dashboard update-options` with `{"changed":["users"],"users":[{"type":"user","id":<arcubaseUserId>}]}`
+  for the current or target Arcubase user.
+- For the current BotWorks human speaker, use `currentSpeaker.arcubaseUserId`; do not call organization lookup only to resolve yourself.
+- Before claiming a normal user can see a dashboard, run user-side `arcubase app get --app-id <app_id>` and require `dashboards[]` to include that dashboard.
+
 Dashboard title updates use body `{"name":"..."}`.
 
 Dashboard layout updates use a top-level JSON array of layout positions, not an object wrapper. Example:

package/sdk-dist/docs/runtime-reference/help-examples/admin/dashboard/update-options.json

@@ -0,0 +1,23 @@
+{
+  "scope": "admin",
+  "command": ["dashboard", "update-options"],
+  "examples": [
+    {
+      "title": "make a dashboard visible to one Arcubase user",
+      "body": {
+        "changed": ["users"],
+        "users": [
+          {
+            "type": "user",
+            "id": 2188889901
+          }
+        ]
+      },
+      "notes": [
+        "dashboard visibility is controlled by DashboardUpdateOptionsReqVO.users",
+        "use the currentSpeaker.arcubaseUserId value for the current human speaker",
+        "after updating, verify from the user side with arcubase app get and require dashboards to include the dashboard"
+      ]
+    }
+  ]
+}

package/sdk-dist/docs/runtime-reference/help-examples/admin/widget/preview-data.json

@@ -37,6 +37,30 @@
         "supported Aggregate values are sum, avg, max, min, count, and distinct_count",
         "unsupported aggregate names fail local body validation before the request is sent"
       ]
+    },
+    {
+      "title": "preview filtered distinct_count grouped by source",
+      "body": {
+        "dataSource": 2188891001,
+        "dataSourceType": "entity",
+        "dimensions": [
+          {"IsField": true, "FieldID": 1004, "Name": "Source"}
+        ],
+        "conditions": {
+          "mode": "and",
+          "conditions": [
+            {"column": ":1006", "operator": "$eq", "value": "yes"}
+          ]
+        },
+        "measures": [
+          {"FieldID": 1002, "Aggregate": "distinct_count", "Name": "Distinct Customers"}
+        ]
+      },
+      "notes": [
+        "use conditions, not filters, for chart data filtering",
+        "for saved charts put the same condition set under options.charts.conditions",
+        "do not remove the condition and hand-calculate filtered statistics from row query results"
+      ]
     }
   ]
 }

package/sdk-dist/docs/runtime-reference/help-examples/admin/widget/update-ingress-options.json

@@ -0,0 +1,21 @@
+{
+  "scope": "admin",
+  "command": ["widget", "update-ingress-options"],
+  "examples": [
+    {
+      "title": "adjust an ingress list widget display configuration",
+      "body": {
+        "options": {
+          "cond_follow": true,
+          "cond_follow_tab": true,
+          "cond_follow_cols": [":1001", ":1002"]
+        }
+      },
+      "notes": [
+        "use this only for widgets created with options.ingress_id",
+        "do not use dashboard update-layout for ingress widgets",
+        "verify with widget get after updating ingress options"
+      ]
+    }
+  ]
+}

package/sdk-dist/docs/runtime-reference/widgets.md

@@ -8,6 +8,14 @@ Use `arcubase widget data --app-id <app_id> --body-json '<FetchWidgetsDataReqVO>
 
 Create dashboard widgets with `{"type":"chart","options":{"dashboard_id":<dashboard_id>}}`. Do not set `options.type` by hand; the backend derives dashboard versus ingress widget type from `dashboard_id` or `ingress_id`.
 
+Create ingress list widgets with `{"type":"list","options":{"ingress_id":<ingress_id>}}`, where `ingress_id` is the entry/access-rule id. Do not put `entity_id` at the top level or under `options` when creating a widget. After creation, adjust entry list display settings with `widget update-ingress-options`, then verify with `widget get`. Ingress widgets have `dashboard_id:0` and must not be placed with `dashboard update-layout`.
+
+If ingress/list display settings such as `ingress_id`, `list`, `default_cols`, or `page_size` are rejected by `widget update`, switch to `widget update-ingress-options`; do not retry `widget update` with empty options.
+
+```json
+{"options":{"cond_follow":true,"cond_follow_tab":true,"cond_follow_cols":[":1001",":1002"]}}
+```
+
 Most widget commands use `--widget-id`; `widget preview-data` is the exception. Preview data does not read a saved widget by id and does not accept `--widget-id`, `widget_id`, or `id`. Its body is the chart query itself:
 
 ```json
@@ -20,6 +28,22 @@ Fastfail rule: `widget preview-data` accepts only the chart query body. If valid
 
 After `widget update`, verify persistence with `widget get` or `widget list`. The saved widget must contain non-null `options.charts`; an update response alone is not enough evidence that the chart configuration was persisted.
 
+## Chart conditions
+
+Use `conditions`, not `filters`, to filter dashboard chart statistics. The condition set shape is:
+
+```json
+{"mode":"and","conditions":[{"column":":1006","operator":"$eq","value":"yes"}]}
+```
+
+For saved widgets, place this under `options.charts.conditions`. For `widget preview-data`, place it at top level beside `dataSource`, `dimensions`, and `measures`.
+
+```json
+{"dataSource":2188891001,"dataSourceType":"entity","dimensions":[{"IsField":true,"FieldID":1004,"Name":"Source"}],"conditions":{"mode":"and","conditions":[{"column":":1006","operator":"$eq","value":"yes"}]},"measures":[{"FieldID":1002,"Aggregate":"distinct_count","Name":"Distinct Customers"}]}
+```
+
+Fastfail rule: if a chart statistic requires filtering and validation rejects a guessed key such as `filters`, retry with `conditions`. Do not remove the filter and then hand-calculate filtered statistics from row data.
+
 ## Chart measures
 
 Dashboard chart widgets use `ChartOption.measures[]` to define statistics. Supported `Aggregate` values are:

package/sdk-dist/generated/command_registry.generated.ts

@@ -953,6 +953,27 @@ export const userCommands = [
     ],
     "responseType": "GlobalActionEntryRespVO"
   },
+  {
+    "scope": "user",
+    "module": "app",
+    "functionName": "getAppDetail",
+    "commandPath": [
+      "app",
+      "get"
+    ],
+    "method": "GET",
+    "endpoint": "/api/apps/:id",
+    "pathParams": [
+      {
+        "param": "id",
+        "flag": "app-id"
+      }
+    ],
+    "controller": "UserAction.AppDetail",
+    "requestType": null,
+    "queryParams": [],
+    "responseType": "AppDetailRespVO"
+  },
   {
     "scope": "user",
     "module": "dashboard",

package/sdk-dist/generated/help_examples.generated.ts

@@ -370,6 +370,33 @@ export const helpExamplesIndex = {
       }
     ]
   },
+  "admin.dashboard.update-options": {
+    "command": [
+      "dashboard",
+      "update-options"
+    ],
+    "examples": [
+      {
+        "title": "make a dashboard visible to one Arcubase user",
+        "body": {
+          "changed": [
+            "users"
+          ],
+          "users": [
+            {
+              "type": "user",
+              "id": 2188889901
+            }
+          ]
+        },
+        "notes": [
+          "dashboard visibility is controlled by DashboardUpdateOptionsReqVO.users",
+          "use the currentSpeaker.arcubaseUserId value for the current human speaker",
+          "after updating, verify from the user side with arcubase app get and require dashboards to include the dashboard"
+        ]
+      }
+    ]
+  },
   "admin.widget.create": {
     "command": [
       "widget",
@@ -465,6 +492,68 @@ export const helpExamplesIndex = {
           "supported Aggregate values are sum, avg, max, min, count, and distinct_count",
           "unsupported aggregate names fail local body validation before the request is sent"
         ]
+      },
+      {
+        "title": "preview filtered distinct_count grouped by source",
+        "body": {
+          "dataSource": 2188891001,
+          "dataSourceType": "entity",
+          "dimensions": [
+            {
+              "IsField": true,
+              "FieldID": 1004,
+              "Name": "Source"
+            }
+          ],
+          "conditions": {
+            "mode": "and",
+            "conditions": [
+              {
+                "column": ":1006",
+                "operator": "$eq",
+                "value": "yes"
+              }
+            ]
+          },
+          "measures": [
+            {
+              "FieldID": 1002,
+              "Aggregate": "distinct_count",
+              "Name": "Distinct Customers"
+            }
+          ]
+        },
+        "notes": [
+          "use conditions, not filters, for chart data filtering",
+          "for saved charts put the same condition set under options.charts.conditions",
+          "do not remove the condition and hand-calculate filtered statistics from row query results"
+        ]
+      }
+    ]
+  },
+  "admin.widget.update-ingress-options": {
+    "command": [
+      "widget",
+      "update-ingress-options"
+    ],
+    "examples": [
+      {
+        "title": "adjust an ingress list widget display configuration",
+        "body": {
+          "options": {
+            "cond_follow": true,
+            "cond_follow_tab": true,
+            "cond_follow_cols": [
+              ":1001",
+              ":1002"
+            ]
+          }
+        },
+        "notes": [
+          "use this only for widgets created with options.ingress_id",
+          "do not use dashboard update-layout for ingress widgets",
+          "verify with widget get after updating ingress options"
+        ]
       }
     ]
   },

package/src/generated/command_registry.generated.ts

@@ -953,6 +953,27 @@ export const userCommands = [
     ],
     "responseType": "GlobalActionEntryRespVO"
   },
+  {
+    "scope": "user",
+    "module": "app",
+    "functionName": "getAppDetail",
+    "commandPath": [
+      "app",
+      "get"
+    ],
+    "method": "GET",
+    "endpoint": "/api/apps/:id",
+    "pathParams": [
+      {
+        "param": "id",
+        "flag": "app-id"
+      }
+    ],
+    "controller": "UserAction.AppDetail",
+    "requestType": null,
+    "queryParams": [],
+    "responseType": "AppDetailRespVO"
+  },
   {
     "scope": "user",
     "module": "dashboard",

package/src/generated/help_examples.generated.ts

@@ -370,6 +370,33 @@ export const helpExamplesIndex = {
       }
     ]
   },
+  "admin.dashboard.update-options": {
+    "command": [
+      "dashboard",
+      "update-options"
+    ],
+    "examples": [
+      {
+        "title": "make a dashboard visible to one Arcubase user",
+        "body": {
+          "changed": [
+            "users"
+          ],
+          "users": [
+            {
+              "type": "user",
+              "id": 2188889901
+            }
+          ]
+        },
+        "notes": [
+          "dashboard visibility is controlled by DashboardUpdateOptionsReqVO.users",
+          "use the currentSpeaker.arcubaseUserId value for the current human speaker",
+          "after updating, verify from the user side with arcubase app get and require dashboards to include the dashboard"
+        ]
+      }
+    ]
+  },
   "admin.widget.create": {
     "command": [
       "widget",
@@ -465,6 +492,68 @@ export const helpExamplesIndex = {
           "supported Aggregate values are sum, avg, max, min, count, and distinct_count",
           "unsupported aggregate names fail local body validation before the request is sent"
         ]
+      },
+      {
+        "title": "preview filtered distinct_count grouped by source",
+        "body": {
+          "dataSource": 2188891001,
+          "dataSourceType": "entity",
+          "dimensions": [
+            {
+              "IsField": true,
+              "FieldID": 1004,
+              "Name": "Source"
+            }
+          ],
+          "conditions": {
+            "mode": "and",
+            "conditions": [
+              {
+                "column": ":1006",
+                "operator": "$eq",
+                "value": "yes"
+              }
+            ]
+          },
+          "measures": [
+            {
+              "FieldID": 1002,
+              "Aggregate": "distinct_count",
+              "Name": "Distinct Customers"
+            }
+          ]
+        },
+        "notes": [
+          "use conditions, not filters, for chart data filtering",
+          "for saved charts put the same condition set under options.charts.conditions",
+          "do not remove the condition and hand-calculate filtered statistics from row query results"
+        ]
+      }
+    ]
+  },
+  "admin.widget.update-ingress-options": {
+    "command": [
+      "widget",
+      "update-ingress-options"
+    ],
+    "examples": [
+      {
+        "title": "adjust an ingress list widget display configuration",
+        "body": {
+          "options": {
+            "cond_follow": true,
+            "cond_follow_tab": true,
+            "cond_follow_cols": [
+              ":1001",
+              ":1002"
+            ]
+          }
+        },
+        "notes": [
+          "use this only for widgets created with options.ingress_id",
+          "do not use dashboard update-layout for ingress widgets",
+          "verify with widget get after updating ingress options"
+        ]
       }
     ]
   },

package/src/runtime/execute.ts

@@ -1032,15 +1032,37 @@ function buildBodyGuidance(requestType: string): Pick<CLIErrorDetails, 'retryToo
         dataSourceType: 'entity',
         dimensions: [{ IsField: true, FieldID: 1004, Name: 'Source' }],
         measures: [{ FieldID: 1005, Aggregate: 'sum', Name: 'Total Amount' }],
+        conditions: { mode: 'and', conditions: [{ column: ':1006', operator: '$eq', value: 'yes' }] },
       },
       commonMistakes: [
         'widget preview-data body is the chart query itself',
         'do not send a saved widget object with id, entity_id, or options',
         'field dimensions with FieldID must set IsField:true',
+        'use conditions, not filters, for chart data filtering',
+        'do not retry without conditions and then hand-calculate filtered statistics',
         'unsupported aggregates are invalid; use sum, avg, max, min, count, or distinct_count',
       ],
       suggestions: [
         'retry with: arcubase-admin widget preview-data --app-id <app_id> --body-json \'{"dataSource":<table_id>,"dataSourceType":"entity","dimensions":[{"IsField":true,"FieldID":<field_id>,"Name":"Source"}],"measures":[{"FieldID":<number_field_id>,"Aggregate":"sum","Name":"Total Amount"}]}\'',
+        'conditional stats: arcubase-admin widget preview-data --app-id <app_id> --body-json \'{"dataSource":<table_id>,"dataSourceType":"entity","dimensions":[{"IsField":true,"FieldID":<source_field_id>,"Name":"Source"}],"conditions":{"mode":"and","conditions":[{"column":":1006","operator":"$eq","value":"yes"}]},"measures":[{"FieldID":<customer_field_id>,"Aggregate":"distinct_count","Name":"Distinct Customers"}]}\'',
+      ],
+    }
+  }
+  if (requestType === 'AppNewWidgetsReqVO') {
+    return {
+      shapeHint: {
+        type: 'list',
+        options: { ingress_id: 2188893001 },
+      },
+      commonMistakes: [
+        'dashboard widgets use options.dashboard_id',
+        'ingress widgets use options.ingress_id',
+        'do not put entity_id at body top level or under options when creating a widget',
+        'after creating an ingress widget, use widget update-ingress-options to adjust display configuration',
+      ],
+      suggestions: [
+        'dashboard chart: arcubase-admin widget create --app-id <app_id> --body-json \'{"type":"chart","options":{"dashboard_id":<dashboard_id>}}\'',
+        'ingress list: arcubase-admin widget create --app-id <app_id> --body-json \'{"type":"list","options":{"ingress_id":<ingress_id>}}\'',
       ],
     }
   }
@@ -1053,15 +1075,39 @@ function buildBodyGuidance(requestType: string): Pick<CLIErrorDetails, 'retryToo
             entity_id: 2188891001,
             dimensions: [{ IsField: true, FieldID: 1004, Name: 'Source' }],
             measures: [{ FieldID: 1005, Aggregate: 'sum', Name: 'Total Amount' }],
+            conditions: { mode: 'and', conditions: [{ column: ':1006', operator: '$eq', value: 'yes' }] },
             type: 'bar',
           },
         },
       },
       commonMistakes: [
         'dashboard chart config belongs in body.options.charts',
+        'ingress/list display settings use widget update-ingress-options, not widget update',
+        'do not put ingress_id, list, default_cols, page_size, or entry display settings in widget update',
         'field dimensions with FieldID must set IsField:true',
+        'use options.charts.conditions, not filters, for chart data filtering',
+        'do not retry without conditions and then hand-calculate filtered statistics',
         'verify persistence with widget get or widget list after update',
       ],
+      suggestions: [
+        'dashboard chart: arcubase-admin widget update --app-id <app_id> --widget-id <widget_id> --body-json \'{"entity_id":<table_id>,"options":{"charts":{"entity_id":<table_id>,"dimensions":[{"IsField":true,"FieldID":<field_id>,"Name":"Source"}],"measures":[{"FieldID":<number_field_id>,"Aggregate":"sum","Name":"Total Amount"}],"type":"bar"}}}\'',
+        'ingress list display: arcubase-admin widget update-ingress-options --app-id <app_id> --widget-id <widget_id> --body-json \'{"options":{"cond_follow":true,"cond_follow_tab":true,"cond_follow_cols":[":1001",":1002"]}}\'',
+      ],
+    }
+  }
+  if (requestType === 'AppUpdateWidgetsIngressOptionsReqVO') {
+    return {
+      shapeHint: {
+        options: { cond_follow: true, cond_follow_tab: true, cond_follow_cols: [':1001', ':1002'] },
+      },
+      commonMistakes: [
+        'widget update-ingress-options is for ingress widgets, not dashboard chart widgets',
+        'put display settings under body.options',
+        'verify the ingress widget with widget get after update',
+      ],
+      suggestions: [
+        'retry with: arcubase-admin widget update-ingress-options --app-id <app_id> --widget-id <widget_id> --body-json \'{"options":{"cond_follow":true,"cond_follow_tab":true,"cond_follow_cols":[":1001",":1002"]}}\'',
+      ],
     }
   }
   return {}

package/src/tests/command_registry.test.ts

@@ -54,6 +54,7 @@ test('admin surface is restricted to reset white list', () => {
 test('user surface is restricted to reset white list', () => {
   const actual = commandPaths(userCommands)
   const expected = [
+    'app get',
     'dashboard get',
     'dashboard widgets',
     'entry',
@@ -93,7 +94,7 @@ test('generated modules use CLI namespaces only', () => {
   const adminModules = [...new Set(adminCommands.map((item) => item.module))].sort()
   const userModules = [...new Set(userCommands.map((item) => item.module))].sort()
   assert.deepEqual(adminModules, ['access-rule', 'app', 'dashboard', 'table', 'widget', 'workflow'])
-  assert.deepEqual(userModules, ['dashboard', 'entry', 'profile', 'row', 'table', 'upload', 'widget', 'workflow'])
+  assert.deepEqual(userModules, ['app', 'dashboard', 'entry', 'profile', 'row', 'table', 'upload', 'widget', 'workflow'])
 })
 
 test('black list commands are removed from registry', () => {