@carthooks/arcubase-cli 0.1.18 → 0.1.20

package/dist/runtime/execute.js

@@ -10,6 +10,7 @@ import { getBodySchema, getCommandDocHints, getDocHints, getTypeHints, getUnsupp
 import { resolveArcubaseSDKPath } from './paths.js';
 import { compileCSVImportMapping, compileExcelImportMapping } from './entity_import_mapping.js';
 import { uploadLocalFileWithToken } from './local_upload.js';
+import { renderCommandHelpExamples } from './help_examples.js';
 export function renderRootHelp(scope) {
     const binary = scope === 'admin' ? 'arcubase-admin' : 'arcubase';
     const items = listModules(scope).map((item) => `  - ${item}`);
@@ -50,9 +51,29 @@ function buildUnknownCommandDetails(scope, moduleName, commandName) {
     const suggestions = findCommandSuggestions(moduleName, commandName).map((item) => `${item.binary} ${item.moduleName}${item.commandName ? ` ${item.commandName}` : ''}`);
     return suggestions.length > 0 ? { suggestions } : undefined;
 }
+function throwHelpExamplesRequiresCommand(scope, moduleName) {
+    const binary = binaryForScope(scope);
+    const suggestions = scope === 'admin'
+        ? [
+            `${binary} access-rule create --help-examples`,
+            `${binary} access-rule assign-users --help-examples`,
+        ]
+        : [
+            `${binary} row bulk-update --help-examples`,
+            `${binary} row selection-action --help-examples`,
+        ];
+    throw new CLIError('HELP_EXAMPLES_REQUIRES_COMMAND', '--help-examples must follow a final command', 2, {
+        operation: moduleName ? `${binary} ${moduleName} --help-examples` : `${binary} --help-examples`,
+        hint: `retry with a final command, for example: ${suggestions[0]}`,
+        suggestions,
+    });
+}
 function sdkPath(file, env = process.env) {
     return resolveArcubaseSDKPath(file, env);
 }
+function binaryForScope(scope) {
+    return scope === 'admin' ? 'arcubase-admin' : 'arcubase';
+}
 export function renderCommandHelp(scope, moduleName, commandName, env = process.env) {
     const command = findCommand(scope, moduleName, commandName);
     if (!command) {
@@ -75,6 +96,7 @@ export function renderCommandHelp(scope, moduleName, commandName, env = process.
         command.requestType ? `body: ${bodyTypeText} via --body-json <json-string> | --body-file <file>.json` : 'body: none',
         queryFlags.length ? `query flags: ${queryFlags.join(', ')}, --query-file` : 'query flags: --query-file',
         pathFlags.length ? `path flags: ${pathFlags.join(', ')}` : 'path flags: none',
+        `copyable examples: ${scope === 'admin' ? 'arcubase-admin' : 'arcubase'} ${command.commandPath.join(' ')} --help-examples`,
         ...(isTableCreate
             ? [
                 'body-json example:',
@@ -113,19 +135,19 @@ export function renderCommandHelp(scope, moduleName, commandName, env = process.
                 `  - hide field: ${JSON.stringify(buildHiddenFieldAccessRuleBody())}`,
                 'success requires:',
                 '  - result.enabled must be true',
-                '  - options.user_scope[].type is "user" for tenant users',
+                '  - options.user_scope[].type is "user", "department", or "actor"',
                 '  - hidden fields use colon field keys such as ":1002"',
             ]
             : []),
         ...(scope === 'admin' && command.commandPath[0] === 'access-rule' && command.commandPath[1] === 'assign-users'
             ? [
                 'body-json example:',
-                '  - {"update":["user_scope"],"options":{"user_scope":[{"type":"user","id":2188889901}]}}',
+                '  - {"update":["user_scope"],"options":{"user_scope":[{"type":"user","id":2188889901},{"type":"department","id":2188881201},{"type":"actor","id":2188883301}]}}',
                 'success requires:',
                 '  - result.enabled must be true',
-                '  - result.options.user_scope must contain the assigned numeric arcubaseUserId values',
-                '  - PermitUserScope.id must be the numeric arcubaseUserId',
-                '  - Do not copy a non-numeric arcubaseUserId into PermitUserScope.id',
+                '  - result.options.user_scope must contain every assigned user, department, or actor scope',
+                '  - PermitUserScope.id must be the numeric arcubaseUserId, department ID, or actor ID',
+                '  - Do not copy a non-numeric BotWorks userId into PermitUserScope.id',
                 '  - If result.enabled is false, enable the rule first and retry assign-users',
             ]
             : []),
@@ -229,7 +251,7 @@ function buildScalarQuery(command, flags) {
     return Object.keys(out).length > 0 ? out : undefined;
 }
 function validateKnownFlags(command, flags, env = process.env) {
-    const allowed = new Set(['help', 'body-file', 'body-json', 'query-file']);
+    const allowed = new Set(['help', 'help-examples', 'body-file', 'body-json', 'query-file']);
     for (const mapping of command.pathParams) {
         if (!getFixedValue(mapping)) {
             allowed.add(mapping.flag);
@@ -628,14 +650,18 @@ function buildAssignUsersValidationDetails(scope, command, requestType, path, me
         shapeHint: {
             update: ['user_scope'],
             options: {
-                user_scope: [{ type: 'user', id: 2188889901 }],
+                user_scope: [
+                    { type: 'user', id: 2188889901 },
+                    { type: 'department', id: 2188881201 },
+                    { type: 'actor', id: 2188883301 },
+                ],
             },
         },
         commonMistakes: [
             'do not use user_scope at top level',
             'do not use users or allowedUsers',
-            'do not use non-numeric arcubaseUserId as id',
-            'id must be the numeric arcubaseUserId',
+            'do not use non-numeric BotWorks userId as id',
+            'id must be the numeric arcubaseUserId, department ID, or actor ID',
         ],
     };
 }
@@ -895,7 +921,7 @@ function validateAccessRuleUserScope(scope, command, requestType, userScope, env
     if (userScope === undefined)
         return;
     if (!Array.isArray(userScope)) {
-        throwBodyValidationFailure('access-rule user_scope must be an array of {"type":"user","id":2188889901}', requestType, pathPrefix, scope, command, env);
+        throwBodyValidationFailure('access-rule user_scope must be an array of {"type":"user","id":2188889901}, {"type":"department","id":2188881201}, or {"type":"actor","id":2188883301}', requestType, pathPrefix, scope, command, env);
     }
     const allowedTypes = new Set(['user', 'department', 'actor']);
     for (const [index, item] of userScope.entries()) {
@@ -910,6 +936,32 @@ function validateAccessRuleUserScope(scope, command, requestType, userScope, env
         }
     }
 }
+function normalizeNumericAccessRuleUserScopeIDs(scope, command, body) {
+    if (!isAccessRuleCommand(scope, command) || !isRecord(body) || !isRecord(body.options) || !Array.isArray(body.options.user_scope)) {
+        return body;
+    }
+    let changed = false;
+    const userScope = body.options.user_scope.map((item) => {
+        if (!isRecord(item) || typeof item.id !== 'string' || !/^\d+$/.test(item.id)) {
+            return item;
+        }
+        const id = Number(item.id);
+        if (!Number.isFinite(id) || !Number.isInteger(id)) {
+            return item;
+        }
+        changed = true;
+        return { ...item, id };
+    });
+    if (!changed)
+        return body;
+    return {
+        ...body,
+        options: {
+            ...body.options,
+            user_scope: userScope,
+        },
+    };
+}
 function requireUpdateContains(scope, command, body, field, env) {
     if (!(field in body))
         return;
@@ -924,7 +976,7 @@ function validateActionSpecificRawBody(scope, command, body, env) {
     }
     if (isAssignUsersCommand(scope, command)) {
         if ('users' in body || 'allowedUsers' in body || 'user_scope' in body) {
-            throwBodyValidationFailure('access-rule assign-users only accepts body.options.user_scope with {"update":["user_scope"],"options":{"user_scope":[{"type":"user","id":2188889901}]}}', command.requestType, 'body.options.user_scope', scope, command, env);
+            throwBodyValidationFailure('access-rule assign-users only accepts body.options.user_scope with {"update":["user_scope"],"options":{"user_scope":[{"type":"user","id":2188889901},{"type":"department","id":2188881201},{"type":"actor","id":2188883301}]}}', command.requestType, 'body.options.user_scope', scope, command, env);
         }
     }
     if (isTableSchemaCommand(scope, command)) {
@@ -983,7 +1035,7 @@ function validateActionSpecificBody(scope, command, flags, body, env) {
         const options = isRecord(body.options) ? body.options : undefined;
         const userScope = options && Array.isArray(options.user_scope) ? options.user_scope : undefined;
         if ('users' in body || 'allowedUsers' in body) {
-            throwBodyValidationFailure('access-rule assign-users only accepts body.options.user_scope with {"update":["user_scope"],"options":{"user_scope":[{"type":"user","id":2188889901}]}}', command.requestType, 'body.options.user_scope', scope, command, env);
+            throwBodyValidationFailure('access-rule assign-users only accepts body.options.user_scope with {"update":["user_scope"],"options":{"user_scope":[{"type":"user","id":2188889901},{"type":"department","id":2188881201},{"type":"actor","id":2188883301}]}}', command.requestType, 'body.options.user_scope', scope, command, env);
         }
         if (!update.includes('user_scope')) {
             throwBodyValidationFailure('access-rule assign-users requires body.update to include "user_scope"', command.requestType, 'body.update', scope, command, env);
@@ -997,11 +1049,8 @@ function validateActionSpecificBody(scope, command, flags, body, env) {
             if (!isRecord(item)) {
                 throwBodyValidationFailure('access-rule assign-users requires each body.options.user_scope item to be an object', command.requestType, `body.options.user_scope.${index}`, scope, command, env);
             }
-            if (item.type !== 'user') {
-                throwBodyValidationFailure('access-rule assign-users requires body.options.user_scope[].type to be "user"', command.requestType, `body.options.user_scope.${index}.type`, scope, command, env);
-            }
             if (typeof item.id !== 'number' || !Number.isInteger(item.id) || item.id <= 0) {
-                throwBodyValidationFailure('access-rule assign-users requires body.options.user_scope[].id to be numeric arcubaseUserId', command.requestType, `body.options.user_scope.${index}.id`, scope, command, env);
+                throwBodyValidationFailure('access-rule assign-users requires body.options.user_scope[].id to be numeric arcubaseUserId, department ID, or actor ID', command.requestType, `body.options.user_scope.${index}.id`, scope, command, env);
             }
         }
     }
@@ -1638,16 +1687,32 @@ export async function executeCLI(scope, argv, env, fetchImpl = fetch) {
     const parsed = parseCLIArgs(argv);
     const envInput = env ?? process.env;
     if (parsed.commandTokens.length === 0) {
+        if (hasFlag(parsed.flags, 'help-examples')) {
+            throwHelpExamplesRequiresCommand(scope);
+        }
         return { kind: 'help', text: renderRootHelp(scope) };
     }
     const [moduleName, commandName] = parsed.commandTokens;
     if (!moduleName) {
+        if (hasFlag(parsed.flags, 'help-examples')) {
+            throwHelpExamplesRequiresCommand(scope);
+        }
         return { kind: 'help', text: renderRootHelp(scope) };
     }
     const singleTokenCommand = !commandName ? findCommand(scope, moduleName) : null;
     if (!commandName && !singleTokenCommand) {
+        if (hasFlag(parsed.flags, 'help-examples')) {
+            throwHelpExamplesRequiresCommand(scope, moduleName);
+        }
         return { kind: 'help', text: renderModuleHelp(scope, moduleName, envInput) };
     }
+    if (hasFlag(parsed.flags, 'help-examples')) {
+        const command = commandName ? findCommand(scope, moduleName, commandName) : singleTokenCommand;
+        if (!command) {
+            throw new CLIError('UNKNOWN_COMMAND', `unknown command: ${moduleName}${commandName ? ` ${commandName}` : ''}`, 2, buildUnknownCommandDetails(scope, moduleName, commandName ?? ''));
+        }
+        return { kind: 'help', text: renderCommandHelpExamples(scope, command) };
+    }
     if (hasFlag(parsed.flags, 'help')) {
         return { kind: 'help', text: renderCommandHelp(scope, moduleName, commandName, envInput) };
     }
@@ -1688,6 +1753,7 @@ export async function executeCLI(scope, argv, env, fetchImpl = fetch) {
         if (body === undefined) {
             throw new CLIError('MISSING_BODY_FILE', `command requires --body-json or --body-file for ${command.requestType}; prefer --body-json to avoid file creation`, 2);
         }
+        body = normalizeNumericAccessRuleUserScopeIDs(scope, command, body);
         if (isTableCreateCommand(scope, command)) {
             requireTableCreateSchemaBody(scope, command, body, runtimeEnv);
             validateActionSpecificRawBody(scope, command, body, runtimeEnv);
@@ -1714,7 +1780,8 @@ export async function executeCLI(scope, argv, env, fetchImpl = fetch) {
                 const message = parsedBody.error.issues.map((issue) => `${issue.path.join('.')}: ${issue.message}`).join('; ');
                 if (isAssignUsersCommand(scope, command)) {
                     const hasUserScopeIDIssue = parsedBody.error.issues.some((issue) => issue.path.join('.') === 'options.user_scope.0.id' || issue.path.join('.').startsWith('options.user_scope.'));
-                    throw new CLIError('BODY_VALIDATION_FAILED', hasUserScopeIDIssue ? 'access-rule assign-users requires body.options.user_scope[].id to be numeric arcubaseUserId' : message, 2, buildAssignUsersValidationDetails(scope, command, command.requestType, hasUserScopeIDIssue ? 'body.options.user_scope' : 'body', hasUserScopeIDIssue ? 'access-rule assign-users requires body.options.user_scope[].id to be numeric arcubaseUserId' : message, runtimeEnv));
+                    const userScopeIDMessage = 'access-rule assign-users requires body.options.user_scope[].id to be numeric arcubaseUserId, department ID, or actor ID';
+                    throw new CLIError('BODY_VALIDATION_FAILED', hasUserScopeIDIssue ? userScopeIDMessage : message, 2, buildAssignUsersValidationDetails(scope, command, command.requestType, hasUserScopeIDIssue ? 'body.options.user_scope' : 'body', hasUserScopeIDIssue ? userScopeIDMessage : message, runtimeEnv));
                 }
                 throw new CLIError('BODY_VALIDATION_FAILED', message, 2, buildBodyValidationDetails(scope, command, command.requestType, parsedBody.error.issues.map((issue) => ({
                     path: issue.path.length > 0 ? `body.${issue.path.join('.')}` : 'body',

package/dist/runtime/help_examples.d.ts

@@ -0,0 +1,10 @@
+import type { CommandDef, CommandScope } from './command_registry.js';
+type HelpExample = {
+    title: string;
+    body?: unknown;
+    notes?: readonly string[];
+};
+export declare function getCommandHelpExamples(scope: CommandScope, command: CommandDef): readonly HelpExample[];
+export declare function renderCommandHelpExamples(scope: CommandScope, command: CommandDef): string;
+export {};
+//# sourceMappingURL=help_examples.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"help_examples.d.ts","sourceRoot":"","sources":["../../src/runtime/help_examples.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,uBAAuB,CAAA;AAErE,KAAK,WAAW,GAAG;IACjB,KAAK,EAAE,MAAM,CAAA;IACb,IAAI,CAAC,EAAE,OAAO,CAAA;IACd,KAAK,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;CAC1B,CAAA;AAyBD,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,YAAY,EAAE,OAAO,EAAE,UAAU,GAAG,SAAS,WAAW,EAAE,CAEvG;AAED,wBAAgB,yBAAyB,CAAC,KAAK,EAAE,YAAY,EAAE,OAAO,EAAE,UAAU,GAAG,MAAM,CAwB1F"}

package/dist/runtime/help_examples.js

@@ -0,0 +1,48 @@
+import { helpExamplesIndex } from '../generated/help_examples.generated.js';
+function binaryForScope(scope) {
+    return scope === 'admin' ? 'arcubase-admin' : 'arcubase';
+}
+function getFixedValue(value) {
+    if (!('fixedValue' in value)) {
+        return undefined;
+    }
+    const fixedValue = value.fixedValue;
+    return typeof fixedValue === 'string' ? fixedValue : undefined;
+}
+function pathFlagPlaceholders(command) {
+    const parts = command.pathParams
+        .filter((item) => !getFixedValue(item))
+        .map((item) => `--${item.flag} <${item.flag.replace(/-/g, '_')}>`);
+    return parts.length > 0 ? `${parts.join(' ')} ` : '';
+}
+function helpExampleKey(scope, command) {
+    return `${scope}.${command.commandPath.join('.')}`;
+}
+export function getCommandHelpExamples(scope, command) {
+    return helpExamplesIndex[helpExampleKey(scope, command)]?.examples ?? [];
+}
+export function renderCommandHelpExamples(scope, command) {
+    const binary = binaryForScope(scope);
+    const examples = getCommandHelpExamples(scope, command);
+    const header = `${binary} ${command.commandPath.join(' ')} --help-examples`;
+    if (examples.length === 0) {
+        return [
+            header,
+            '',
+            'No dedicated examples for this final command yet.',
+            `Use ${binary} ${command.commandPath.join(' ')} --help for flags, docs, and type paths.`,
+        ].join('\n');
+    }
+    return [
+        header,
+        '',
+        ...examples.flatMap((example) => [
+            `${example.title}:`,
+            ...(example.body === undefined
+                ? []
+                : [`  ${binary} ${command.commandPath.join(' ')} ${pathFlagPlaceholders(command)}--body-json '${JSON.stringify(example.body)}'`.replace(/\s+/g, ' ').trim()]),
+            ...(example.notes ?? []).map((note) => `  - ${note}`),
+            '',
+        ]),
+    ].join('\n').trimEnd();
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@carthooks/arcubase-cli",
-  "version": "0.1.18",
+  "version": "0.1.20",
   "description": "Arcubase runtime CLI for admin and user command execution",
   "type": "module",
   "main": "./dist/index.js",
@@ -22,9 +22,10 @@
     "codegen:commands": "node scripts/generate-command-registry.mjs",
     "codegen:zod": "node scripts/generate-zod-registry.mjs",
     "codegen:type-index": "node scripts/generate-type-index.mjs",
-    "bundle": "npm run codegen:commands && npm run codegen:zod && npm run codegen:type-index && tsc && node scripts/bundle-cli.mjs",
+    "codegen:help-examples": "node scripts/generate-help-examples.mjs",
+    "bundle": "npm run codegen:commands && npm run codegen:zod && npm run codegen:type-index && npm run codegen:help-examples && tsc && node scripts/bundle-cli.mjs",
     "build": "npm run bundle && npm run docs:llms",
-    "test": "npm run codegen:commands && npm run codegen:zod && npm run codegen:type-index && tsx --test src/tests/*.test.ts",
+    "test": "npm run codegen:commands && npm run codegen:zod && npm run codegen:type-index && npm run codegen:help-examples && tsx --test src/tests/*.test.ts",
     "watch": "tsc --watch",
     "type-check": "tsc --noEmit",
     "docs:llms": "node -e \"\""

package/sdk-dist/docs/runtime-reference/access-rule.md

@@ -4,9 +4,9 @@ Use `arcubase-admin access-rule` for app/table access.
 
 ## One Path
 
-1. Get the numeric `arcubaseUserId`.
+1. Get the numeric `arcubaseUserId`, department ID, or actor ID.
 2. Create an enabled rule with `options.policy`.
-3. Assign users with `options.user_scope`.
+3. Assign user scope with `options.user_scope`.
 4. Verify with `access-rule get`.
 
 ## User Mapping
@@ -17,8 +17,8 @@ arcubase-admin get-digiemployee-users
 
 Use the numeric `arcubaseUserId`.
 
-Do not use non-numeric Arcubase user ids in `user_scope[].id`.
-Use `user_scope[].type:"user"` for a tenant user. Do not use FieldVO field type `member` in access rules.
+Do not use non-numeric BotWorks user ids in `user_scope[].id`.
+Use `user_scope[].type:"user"` for a tenant user, `type:"department"` for a department, and `type:"actor"` for a role/actor. Do not use FieldVO field type `member` in access rules.
 
 ## Body Input
 
@@ -90,7 +90,7 @@ Rules:
 - field key is not the FieldVO `key`; do not use values like `vote_description`
 - preserve `list_options:{}` unless the existing rule has a known replacement
 
-## Assign Users Only
+## Assign User Scope Only
 
 Use this only when the rule already has the correct `policy`.
 
@@ -99,16 +99,18 @@ arcubase-admin access-rule assign-users \
   --app-id 2188893436 \
   --table-id 2188893443 \
   --rule-id 2188893557 \
-  --body-json '{"update":["user_scope"],"options":{"user_scope":[{"type":"user","id":2188889901}]}}'
+  --body-json '{"update":["user_scope"],"options":{"user_scope":[{"type":"user","id":2188889901},{"type":"department","id":2188881201},{"type":"actor","id":2188883301}]}}'
 ```
 
 Rules:
 
-- `assign-users` preserves the existing policy.
+- `assign-users` preserves the existing policy and only replaces `options.user_scope`.
 - body must use `update:["user_scope"]`.
 - body must use `options.user_scope`.
-- `user_scope[].type` is `user` for Arcubase organization users.
-- `user_scope[].id` is the numeric `arcubaseUserId`.
+- `user_scope[].type` must be `user`, `department`, or `actor`.
+- `user_scope[].id` must be the numeric `arcubaseUserId`, department ID, or actor ID.
+- Multiple scope items are OR: any matching user, department membership, or actor membership can use the ingress.
+- Department scope includes child departments because Arcubase matches the user's department path.
 
 ## Verify
 
@@ -122,7 +124,7 @@ arcubase-admin access-rule get \
 Success:
 
 - `enabled=true`
-- `options.user_scope` contains the numeric user id
+- `options.user_scope` contains every expected `type/id` scope item
 - `options.policy.actions` contains `view`, `add`, `edit`
 - `options.policy.fields` contains hidden fields as `{"key":":1002","read":false,"write":false,"report":false}`
 - visible fields are explicitly present with `read/write=true` when `all_fields_read/write=false`

package/sdk-dist/docs/runtime-reference/help-examples/admin/access-rule/assign-users.json

@@ -0,0 +1,23 @@
+{
+  "scope": "admin",
+  "command": ["access-rule", "assign-users"],
+  "examples": [
+    {
+      "title": "replace user_scope with user, department, and actor scopes",
+      "body": {
+        "update": ["user_scope"],
+        "options": {
+          "user_scope": [
+            {"type": "user", "id": 2188889901},
+            {"type": "department", "id": 2188881201},
+            {"type": "actor", "id": 2188883301}
+          ]
+        }
+      },
+      "notes": [
+        "id must be numeric arcubaseUserId, department ID, or actor ID",
+        "assign-users updates user_scope only and preserves the existing policy"
+      ]
+    }
+  ]
+}

package/sdk-dist/docs/runtime-reference/help-examples/admin/access-rule/create.json

@@ -0,0 +1,95 @@
+{
+  "scope": "admin",
+  "command": ["access-rule", "create"],
+  "examples": [
+    {
+      "title": "full access for a specific arcubaseUserId",
+      "body": {
+        "name": "Admin full access",
+        "enabled": true,
+        "type": "form",
+        "options": {
+          "user_scope": [{"type": "user", "id": 2188889977}],
+          "policy": {
+            "key": "custom",
+            "actions": ["view", "add", "edit", "delete"],
+            "all_fields_read": true,
+            "all_fields_write": true
+          },
+          "list_options": {}
+        }
+      }
+    },
+    {
+      "title": "department can view/add/edit only rows created by themselves",
+      "body": {
+        "name": "Sales own rows",
+        "enabled": true,
+        "type": "form",
+        "options": {
+          "user_scope": [{"type": "department", "id": 2188881201}],
+          "policy": {
+            "key": "custom",
+            "actions": ["view", "add", "edit"],
+            "all_fields_read": true,
+            "all_fields_write": true,
+            "condition": {
+              "mode": "and",
+              "conditions": [
+                {"column": "creator", "operator": "$eq", "value": "[[current_user]]", "value_from": 0, "value_relation": ""}
+              ]
+            }
+          },
+          "list_options": {}
+        }
+      },
+      "notes": [
+        "department scope includes child departments",
+        "row-owner isolation uses [[current_user]] on creator"
+      ]
+    },
+    {
+      "title": "role actor can view rows matching a complex AND/OR condition",
+      "body": {
+        "name": "Sales manager review queue",
+        "enabled": true,
+        "type": "form",
+        "options": {
+          "user_scope": [{"type": "actor", "id": 2188883301}],
+          "policy": {
+            "key": "custom",
+            "actions": ["view", "edit"],
+            "all_fields_read": true,
+            "all_fields_write": true,
+            "condition": {
+              "mode": "and",
+              "conditions": [
+                {"column": ":1004", "operator": "$eq", "value": "pending", "value_from": 0, "value_relation": ""},
+                {
+                  "column": "",
+                  "operator": "",
+                  "value": null,
+                  "value_from": 0,
+                  "value_relation": "",
+                  "subset": {
+                    "mode": "or",
+                    "conditions": [
+                      {"column": "creator", "operator": "$eq", "value": "[[current_user]]", "value_from": 0, "value_relation": ""},
+                      {"column": ":1005", "operator": "$eq", "value": "high", "value_from": 0, "value_relation": ""}
+                    ]
+                  }
+                }
+              ]
+            }
+          },
+          "list_options": {}
+        }
+      },
+      "notes": [
+        "actor means Arcubase role id",
+        "condition mode \"and\" and \"or\" are canonical; legacy \"all\" also reads as AND",
+        "nested OR uses subset and leaves the wrapper column/operator empty"
+      ]
+    }
+  ]
+}

package/sdk-dist/docs/runtime-reference/help-examples/user/row/bulk-update.json

@@ -0,0 +1,23 @@
+{
+  "scope": "user",
+  "command": ["row", "bulk-update"],
+  "examples": [
+    {
+      "title": "bulk update explicit row ids",
+      "body": {
+        "selection": {"type": "ids", "ids": [2188890411, 2188890412], "length": 2},
+        "fields": [{"id": 1003, "action": {"type": "set", "value": 2}}]
+      }
+    },
+    {
+      "title": "bulk update rows selected by a search condition",
+      "body": {
+        "selection": {"type": "condition", "condition": {"selectAll": true, "q": "SO-1001"}, "length": 0},
+        "fields": [{"id": 1003, "action": {"type": "set", "value": 2}}]
+      },
+      "notes": [
+        "condition selection uses row-query style keys such as q, tab, and filter_:1002"
+      ]
+    }
+  ]
+}

package/sdk-dist/docs/runtime-reference/help-examples/user/row/selection-action.json

@@ -0,0 +1,25 @@
+{
+  "scope": "user",
+  "command": ["row", "selection-action"],
+  "examples": [
+    {
+      "title": "run a custom action against explicit row ids",
+      "body": {
+        "selection": {"type": "ids", "ids": [2188890411], "length": 1}
+      },
+      "notes": [
+        "pass the backend action code with --action",
+        "for query action, use ids or all selection instead of condition selection"
+      ]
+    },
+    {
+      "title": "run a custom action against a filtered selection",
+      "body": {
+        "selection": {"type": "condition", "condition": {"selectAll": true, "q": "SO-1001"}, "length": 0}
+      },
+      "notes": [
+        "condition selection uses row-query style keys such as q, tab, and filter_:1002"
+      ]
+    }
+  ]
+}