@carthooks/arcubase-cli 0.1.22 → 0.1.23

package/bundle/arcubase-admin.mjs

@@ -1082,6 +1082,27 @@ var 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",
@@ -18434,6 +18455,68 @@ var 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"
+        ]
       }
     ]
   },
@@ -19775,16 +19858,38 @@ function buildBodyGuidance(requestType) {
         dataSource: 2188891001,
         dataSourceType: "entity",
         dimensions: [{ IsField: true, FieldID: 1004, Name: "Source" }],
-        measures: [{ FieldID: 1005, Aggregate: "sum", Name: "Total Amount" }]
+        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"}]}'`
+        `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>}}'`
       ]
     };
   }
@@ -19797,14 +19902,38 @@ 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"]}}'`
       ]
     };
   }

package/bundle/arcubase.mjs

@@ -1082,6 +1082,27 @@ var 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",
@@ -18434,6 +18455,68 @@ var 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"
+        ]
       }
     ]
   },
@@ -19775,16 +19858,38 @@ function buildBodyGuidance(requestType) {
         dataSource: 2188891001,
         dataSourceType: "entity",
         dimensions: [{ IsField: true, FieldID: 1004, Name: "Source" }],
-        measures: [{ FieldID: 1005, Aggregate: "sum", Name: "Total Amount" }]
+        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"}]}'`
+        `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>}}'`
       ]
     };
   }
@@ -19797,14 +19902,38 @@ 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"]}}'`
       ]
     };
   }

package/dist/generated/command_registry.generated.d.ts

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

package/dist/generated/command_registry.generated.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"command_registry.generated.d.ts","sourceRoot":"","sources":["../../src/generated/command_registry.generated.ts"],"names":[],"mappings":"AAEA,MAAM,MAAM,mBAAmB,GAAG;IAChC,KAAK,EAAE,OAAO,GAAG,MAAM,CAAA;IACvB,MAAM,EAAE,MAAM,CAAA;IACd,YAAY,EAAE,MAAM,CAAA;IACpB,WAAW,EAAE,SAAS,MAAM,EAAE,CAAA;IAC9B,MAAM,EAAE,MAAM,CAAA;IACd,QAAQ,EAAE,MAAM,CAAA;IAChB,UAAU,EAAE,SAAS;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,UAAU,CAAC,EAAE,MAAM,CAAA;KAAE,EAAE,CAAA;IAC3E,UAAU,EAAE,MAAM,CAAA;IAClB,WAAW,EAAE,MAAM,GAAG,IAAI,CAAA;IAC1B,WAAW,EAAE,SAAS;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,OAAO,CAAC;QAAC,UAAU,CAAC,EAAE,MAAM,CAAA;KAAE,EAAE,CAAA;IAC7G,YAAY,EAAE,MAAM,CAAA;CACrB,CAAA;AAED,eAAO,MAAM,aAAa;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAi5BhB,CAAA;AAEV,eAAO,MAAM,YAAY;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAszBf,CAAA"}
+{"version":3,"file":"command_registry.generated.d.ts","sourceRoot":"","sources":["../../src/generated/command_registry.generated.ts"],"names":[],"mappings":"AAEA,MAAM,MAAM,mBAAmB,GAAG;IAChC,KAAK,EAAE,OAAO,GAAG,MAAM,CAAA;IACvB,MAAM,EAAE,MAAM,CAAA;IACd,YAAY,EAAE,MAAM,CAAA;IACpB,WAAW,EAAE,SAAS,MAAM,EAAE,CAAA;IAC9B,MAAM,EAAE,MAAM,CAAA;IACd,QAAQ,EAAE,MAAM,CAAA;IAChB,UAAU,EAAE,SAAS;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,UAAU,CAAC,EAAE,MAAM,CAAA;KAAE,EAAE,CAAA;IAC3E,UAAU,EAAE,MAAM,CAAA;IAClB,WAAW,EAAE,MAAM,GAAG,IAAI,CAAA;IAC1B,WAAW,EAAE,SAAS;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,OAAO,CAAC;QAAC,UAAU,CAAC,EAAE,MAAM,CAAA;KAAE,EAAE,CAAA;IAC7G,YAAY,EAAE,MAAM,CAAA;CACrB,CAAA;AAED,eAAO,MAAM,aAAa;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAi5BhB,CAAA;AAEV,eAAO,MAAM,YAAY;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EA20Bf,CAAA"}

package/dist/generated/command_registry.generated.js

@@ -937,6 +937,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/dist/generated/help_examples.generated.d.ts

@@ -323,6 +323,45 @@ export declare const helpExamplesIndex: {
                 }];
             };
             readonly notes: readonly ["supported Aggregate values are sum, avg, max, min, count, and distinct_count", "unsupported aggregate names fail local body validation before the request is sent"];
+        }, {
+            readonly title: "preview filtered distinct_count grouped by source";
+            readonly body: {
+                readonly dataSource: 2188891001;
+                readonly dataSourceType: "entity";
+                readonly dimensions: readonly [{
+                    readonly IsField: true;
+                    readonly FieldID: 1004;
+                    readonly Name: "Source";
+                }];
+                readonly conditions: {
+                    readonly mode: "and";
+                    readonly conditions: readonly [{
+                        readonly column: ":1006";
+                        readonly operator: "$eq";
+                        readonly value: "yes";
+                    }];
+                };
+                readonly measures: readonly [{
+                    readonly FieldID: 1002;
+                    readonly Aggregate: "distinct_count";
+                    readonly Name: "Distinct Customers";
+                }];
+            };
+            readonly notes: readonly ["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"];
+        }];
+    };
+    readonly "admin.widget.update-ingress-options": {
+        readonly command: readonly ["widget", "update-ingress-options"];
+        readonly examples: readonly [{
+            readonly title: "adjust an ingress list widget display configuration";
+            readonly body: {
+                readonly options: {
+                    readonly cond_follow: true;
+                    readonly cond_follow_tab: true;
+                    readonly cond_follow_cols: readonly [":1001", ":1002"];
+                };
+            };
+            readonly notes: readonly ["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"];
         }];
     };
     readonly "user.row.bulk-update": {

package/dist/generated/help_examples.generated.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"help_examples.generated.d.ts","sourceRoot":"","sources":["../../src/generated/help_examples.generated.ts"],"names":[],"mappings":"AAEA,MAAM,MAAM,oBAAoB,GAAG;IACjC,KAAK,EAAE,MAAM,CAAA;IACb,IAAI,CAAC,EAAE,OAAO,CAAA;IACd,KAAK,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;CAC1B,CAAA;AAED,eAAO,MAAM,iBAAiB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA6iBgF,CAAA"}
+{"version":3,"file":"help_examples.generated.d.ts","sourceRoot":"","sources":["../../src/generated/help_examples.generated.ts"],"names":[],"mappings":"AAEA,MAAM,MAAM,oBAAoB,GAAG;IACjC,KAAK,EAAE,MAAM,CAAA;IACb,IAAI,CAAC,EAAE,OAAO,CAAA;IACd,KAAK,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;CAC1B,CAAA;AAED,eAAO,MAAM,iBAAiB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA2mBgF,CAAA"}

package/dist/generated/help_examples.generated.js

@@ -458,6 +458,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/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.23",
   "description": "Arcubase runtime CLI for admin and user command execution",
   "type": "module",
   "main": "./dist/index.js",

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

@@ -1,6 +1,13 @@
 # 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.
 

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

@@ -465,6 +465,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

@@ -465,6 +465,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', () => {

package/src/tests/execute_validation.test.ts

@@ -1095,6 +1095,16 @@ test('entry fixed app tables query cannot be disabled by query file', async () =
 })
 
 test('dashboard and widget commands map to approved endpoints', async () => {
+  const userAppGet = await executeCLI(
+    'user',
+    ['app', 'get', '--app-id', 'app_1'],
+    env as any,
+    async (url, init) => new Response(JSON.stringify({ url, method: init?.method }), { status: 200 }),
+  )
+  assert.equal(userAppGet.kind, 'result')
+  assert.equal(userAppGet.data.url, 'https://arcubase.example.com/api/apps/app_1')
+  assert.equal(userAppGet.data.method, 'GET')
+
   const adminWidgetList = await executeCLI(
     'admin',
     ['widget', 'list', '--app-id', 'app_1', '--type', 'dashboard', '--dashboard-id', '100'],
@@ -1131,6 +1141,61 @@ test('dashboard and widget commands map to approved endpoints', async () => {
   assert.deepEqual(userWidgetData.data.body, { dashboard_id: 100, type: 1 })
 })
 
+test('widget create ingress mistakes suggest ingress widget shape before request', async () => {
+  let called = false
+  await assert.rejects(async () => {
+    await executeCLI(
+      'admin',
+      ['widget', 'create', '--app-id', 'app_1', '--body-json', '{"type":"list","options":{"entity_id":2188891001}}'],
+      env as any,
+      async () => {
+        called = true
+        return new Response('{}', { status: 200 })
+      },
+    )
+  }, (error: unknown) => {
+    assert.ok(error instanceof CLIError)
+    assert.equal(error.code, 'BODY_VALIDATION_FAILED')
+    assert.equal(error.details?.requestType, 'AppNewWidgetsReqVO')
+    assert.ok((error.details?.commonMistakes ?? []).includes('ingress widgets use options.ingress_id'))
+    assert.ok((error.details?.commonMistakes ?? []).includes('after creating an ingress widget, use widget update-ingress-options to adjust display configuration'))
+    return true
+  })
+  assert.equal(called, false)
+})
+
+test('widget update ingress list options points to update-ingress-options before request', async () => {
+  let called = false
+  await assert.rejects(async () => {
+    await executeCLI(
+      'admin',
+      [
+        'widget',
+        'update',
+        '--app-id',
+        'app_1',
+        '--widget-id',
+        'widget_1',
+        '--body-json',
+        '{"ingress_id":2188893001,"options":{"list":{"default_cols":[1001,1002],"page_size":10}}}',
+      ],
+      env as any,
+      async () => {
+        called = true
+        return new Response('{}', { status: 200 })
+      },
+    )
+  }, (error: unknown) => {
+    assert.ok(error instanceof CLIError)
+    assert.equal(error.code, 'BODY_VALIDATION_FAILED')
+    assert.equal(error.details?.requestType, 'AppUpdateWidgetsReqVO')
+    assert.ok((error.details?.commonMistakes ?? []).includes('ingress/list display settings use widget update-ingress-options, not widget update'))
+    assert.ok((error.details?.suggestions ?? []).some((item) => item.includes('widget update-ingress-options')))
+    return true
+  })
+  assert.equal(called, false)
+})
+
 test('widget preview-data rejects unsupported aggregate before request', async () => {
   let called = false
   await assert.rejects(async () => {
@@ -1191,6 +1256,38 @@ test('widget preview-data rejects field dimensions without IsField true before r
   assert.equal(called, false)
 })
 
+test('widget preview-data filter mistakes suggest chart conditions before request', async () => {
+  let called = false
+  await assert.rejects(async () => {
+    await executeCLI(
+      'admin',
+      [
+        'widget',
+        'preview-data',
+        '--app-id',
+        'app_1',
+        '--body-json',
+        '{"dataSource":2188891001,"dataSourceType":"entity","dimensions":[{"IsField":true,"FieldID":1004,"Name":"Source"}],"filters":[{"FieldID":1006,"Operator":"$eq","Value":"yes"}],"measures":[{"Name":"Distinct Customers","FieldID":1002,"Aggregate":"distinct_count"}]}',
+      ],
+      env as any,
+      async () => {
+        called = true
+        return new Response('{}', { status: 200 })
+      },
+    )
+  }, (error: unknown) => {
+    assert.ok(error instanceof CLIError)
+    assert.equal(error.code, 'BODY_VALIDATION_FAILED')
+    assert.equal(error.details?.requestType, 'AppPreviewWidgetsDataReqVO')
+    assert.ok((error.details?.issues ?? []).some((item) => item.path === 'body'))
+    assert.ok((error.details?.commonMistakes ?? []).includes('use conditions, not filters, for chart data filtering'))
+    assert.ok((error.details?.commonMistakes ?? []).includes('do not retry without conditions and then hand-calculate filtered statistics'))
+    assert.ok((error.details?.suggestions ?? []).some((item) => item.includes('"conditions":{"mode":"and","conditions":[{"column":":1006","operator":"$eq","value":"yes"}]}')))
+    return true
+  })
+  assert.equal(called, false)
+})
+
 test('widget update rejects chart field dimensions without IsField true before request', async () => {
   let called = false
   await assert.rejects(async () => {

package/src/tests/help.test.ts

@@ -136,6 +136,12 @@ test('dashboard and widget help exposes agent-readable body docs and flags', asy
   assert.match(userWidgetData.text, /body: FetchWidgetsDataReqVO via --body-json/)
   assert.match(userWidgetData.text, /^types:$/m)
   assert.match(userWidgetData.text, /^docs:$/m)
+
+  const userAppGet = await executeCLI('user', ['app', 'get', '--help'], env as any, async () => new Response('{}'))
+  assert.equal(userAppGet.kind, 'help')
+  assert.match(userAppGet.text, /arcubase app get/)
+  assert.match(userAppGet.text, /endpoint: \/apps\/:id/)
+  assert.match(userAppGet.text, /path flags: --app-id/)
 })
 
 test('admin access-rule help gives update whitelist and assign-users body-json examples', async () => {
@@ -221,6 +227,8 @@ test('admin widget preview-data help-examples show chart query body without widg
   assert.match(out.text, /"dataSource":2188891001/)
   assert.match(out.text, /"dataSourceType":"entity"/)
   assert.match(out.text, /"Aggregate":"sum"/)
+  assert.match(out.text, /"conditions":\{"mode":"and","conditions":\[\{"column":":1006","operator":"\$eq","value":"yes"\}\]\}/)
+  assert.match(out.text, /use conditions, not filters/)
   assert.match(out.text, /preview-data does not accept --widget-id/)
   assert.match(out.text, /do not send widget_id or id/)
   assert.doesNotMatch(out.text, /--widget-id <widget_id>/)
@@ -236,6 +244,14 @@ test('admin widget create help-examples avoid manual options type', async () =>
   assert.doesNotMatch(out.text, /"options":\{"dashboard_id":2188892001,"type":/)
 })
 
+test('admin widget update-ingress-options help-examples show ingress display body', async () => {
+  const out = await executeCLI('admin', ['widget', 'update-ingress-options', '--help-examples'], env as any, async () => new Response('{}'))
+  assert.equal(out.kind, 'help')
+  assert.match(out.text, /arcubase-admin widget update-ingress-options --help-examples/)
+  assert.match(out.text, /"cond_follow":true/)
+  assert.match(out.text, /verify with widget get/)
+})
+
 test('user row bulk-update help-examples show ids and condition selection bodies', async () => {
   const out = await executeCLI('user', ['row', 'bulk-update', '--help-examples'], env as any, async () => new Response('{}'))
   assert.equal(out.kind, 'help')