@carthooks/arcubase-cli 0.1.9 → 0.1.12

package/src/runtime/execute.ts

@@ -1,11 +1,11 @@
 import { parseCLIArgs, hasFlag, flagValue } from './argv.js'
 import { loadRuntimeEnv, type RuntimeEnv } from './env.js'
-import { CLIError } from './errors.js'
+import { CLIError, type CLIErrorDetails } from './errors.js'
 import { buildRequestHeaders, buildURL, normalizeExternalEndpoint } from './http.js'
 import { listModules, listModuleCommands, findCommand, findCommandSuggestions, type CommandScope } from './command_registry.js'
 import { loadBodyFromFlags, loadQueryFromFlags } from './body_loader.js'
 import { getBodySchema, getCommandDocHints, getDocHints, getTypeHints, getUnsupportedBodySchemaReason } from './zod_registry.js'
-import { renderUploadHelp, uploadLocalFile } from './upload.js'
+import { resolveArcubaseSDKPath } from './paths.js'
 
 export type CommandExecutionSummary = {
   scope: CommandScope
@@ -17,16 +17,6 @@ export type CommandExecutionSummary = {
   queryFlags: readonly string[]
 }
 
-type CustomUploadSummary = {
-  kind: 'upload'
-  status: number
-  data: ReturnType<typeof summarizeUploadResult>
-}
-
-function summarizeUploadResult(value: Awaited<ReturnType<typeof uploadLocalFile>>) {
-  return value
-}
-
 export function renderRootHelp(scope: CommandScope): string {
   const binary = scope === 'admin' ? 'arcubase-admin' : 'arcubase'
   const items = listModules(scope).map((item) => `  - ${item}`)
@@ -36,20 +26,21 @@ export function renderRootHelp(scope: CommandScope): string {
     ...(scope === 'admin'
       ? ['use arcubase-admin for app, table, access-rule, and workflow management', '']
       : ['use arcubase for entry, table, row, upload, profile, and workflow actions', '']),
+    'prefer --body-json <json-string> for normal payloads, including table schema; use --body-file only when JSON is too large for one tool call',
+    '',
     'modules:',
     ...items,
-    ...(scope === 'user' ? ['','special commands:','  - upload <local-file>'] : []),
   ].join('\n')
 }
 
-export function renderModuleHelp(scope: CommandScope, moduleName: string): string {
+export function renderModuleHelp(scope: CommandScope, moduleName: string, env: EnvInput = process.env): string {
   const items = listModuleCommands(scope, moduleName)
   if (items.length === 0) {
     const suggestions = findCommandSuggestions(moduleName, '').map((item) => `${item.binary} ${item.moduleName}${item.commandName ? ` ${item.commandName}` : ''}`)
     throw new CLIError('UNKNOWN_MODULE', `unknown module: ${moduleName}`, 2, suggestions.length > 0 ? { suggestions } : undefined)
   }
   if (items.length === 1 && items[0].commandPath.length === 1) {
-    return renderCommandHelp(scope, moduleName)
+    return renderCommandHelp(scope, moduleName, undefined, env)
   }
   return [
     `${scope === 'admin' ? 'arcubase-admin' : 'arcubase'} ${moduleName} <command> [flags]`,
@@ -57,6 +48,8 @@ export function renderModuleHelp(scope: CommandScope, moduleName: string): strin
     ...(scope === 'admin'
       ? ['use arcubase-admin for app, table, access-rule, and workflow management', '']
       : ['use arcubase for entry, table, row, upload, profile, and workflow actions', '']),
+    'prefer --body-json <json-string> for normal payloads, including table schema; use --body-file only when JSON is too large for one tool call',
+    '',
     'commands:',
     ...items.filter((item) => item.commandPath.length > 1).map((item) => `  - ${item.commandPath[1]}`),
   ].join('\n')
@@ -67,30 +60,55 @@ function buildUnknownCommandDetails(scope: CommandScope, moduleName: string, com
   return suggestions.length > 0 ? { suggestions } : undefined
 }
 
-export function renderCommandHelp(scope: CommandScope, moduleName: string, commandName?: string): string {
+type EnvInput = Record<string, string | undefined>
+
+function sdkPath(file: string, env: EnvInput = process.env): string {
+  return resolveArcubaseSDKPath(file, env)
+}
+
+export function renderCommandHelp(scope: CommandScope, moduleName: string, commandName?: string, env: EnvInput = process.env): string {
   const command = findCommand(scope, moduleName, commandName)
   if (!command) {
     throw new CLIError('UNKNOWN_COMMAND', `unknown command: ${moduleName}${commandName ? ` ${commandName}` : ''}`, 2, buildUnknownCommandDetails(scope, moduleName, commandName ?? ''))
   }
   const docHints = [
-    ...getCommandDocHints(`${scope}.${command.module}.${command.functionName}`),
-    ...(command.requestType ? getDocHints(command.requestType) : []),
+    ...getCommandDocHints(`${scope}.${command.module}.${command.functionName}`, env),
+    ...(command.requestType ? getDocHints(command.requestType, env) : []),
   ].filter((item, index, list) => list.findIndex((candidate) => candidate.file === item.file) === index)
+  const typeHints = command.requestType ? getTypeHints(command.requestType, env) : []
   const pathFlags = command.pathParams.filter((item) => !getFixedValue(item)).map((item) => `--${item.flag}`)
-  const queryFlags = command.queryParams.filter((item) => !getFixedValue(item)).map((item) => `--${item.flag}`)
+  const queryFlags = visibleQueryParams(command).map((item) => `--${item.flag}`)
+  const isTableCreate = scope === 'admin' && command.commandPath[0] === 'table' && command.commandPath[1] === 'create'
+  const bodyTypeText = isTableCreate ? 'TableCreateWithSchema' : command.requestType
+  const tableCreateExampleBody = JSON.stringify(buildTableCreateExampleBody())
   return [
     `${scope === 'admin' ? 'arcubase-admin' : 'arcubase'} ${command.commandPath.join(' ')}`,
     `method: ${command.method}`,
     `endpoint: ${normalizeExternalEndpoint(command.endpoint)}`,
-    command.requestType ? `body: ${command.requestType} via --body-file or --body-json` : 'body: none',
+    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',
+    ...(isTableCreate
+      ? [
+          'body-json example:',
+          `  - ${tableCreateExampleBody}`,
+          'body rules:',
+          '  - fields must be non-empty; empty table shell creation is not allowed',
+          '  - field_id_seq must be greater than every field.id',
+          '  - use text, not string; use member, not user',
+          '  - for select/radio/checkbox/status, use options.options.items',
+          'schema refs:',
+          `  - Table schema cheatsheet: ${sdkPath('docs/runtime-reference/entity-schema.md', env)}`,
+          `  - Field type index: ${sdkPath('docs/runtime-reference/entity-schema/README.md', env)}`,
+        ]
+      : []),
     ...(scope === 'admin' && command.commandPath[0] === 'table' && command.commandPath[1] === 'update-schema'
       ? [
           'next step:',
+          '  - prefer --body-json for schema save to avoid file creation and JSON file corruption',
           '  - switch to arcubase for row operations',
-          '  - row create: arcubase row create --app-id <app_id> --table-id <table_id> --body-file insert.json',
-          '  - row query: arcubase row query --app-id <app_id> --table-id <table_id> --body-file query.json',
+          '  - row create: arcubase row create --app-id <app_id> --table-id <table_id> --body-json <json-string> | --body-file insert.json',
+          '  - row query: arcubase row query --app-id <app_id> --table-id <table_id> --body-json <json-string> | --body-file query.json',
         ]
       : []),
     ...(scope === 'admin' && command.commandPath[0] === 'access-rule' && command.commandPath[1] === 'update'
@@ -98,21 +116,37 @@ export function renderCommandHelp(scope: CommandScope, moduleName: string, comma
           'body-json examples:',
           '  - enable: {"update":["enabled"],"enabled":true}',
           '  - rename: {"update":["name"],"name":"Sales read only"}',
-          '  - update options: {"update":["options"],"options":{"user_scope":[{"type":"user","id":123}]}}',
+          '  - update policy: {"update":["options"],"options":{"policy":{"key":"custom","actions":["view","add","edit"],"all_fields_read":true,"all_fields_write":true,"fields":[{"key":":1002","read":false,"write":false,"report":false}]},"list_options":{}}}',
+        ]
+      : []),
+    ...(scope === 'admin' && command.commandPath[0] === 'access-rule' && command.commandPath[1] === 'create'
+      ? [
+          'body-json example:',
+          '  - {"name":"Sales read write","enabled":true,"type":"form","options":{"user_scope":[{"type":"user","id":2188889901}],"policy":{"key":"custom","actions":["view","add","edit"],"all_fields_read":false,"all_fields_write":false,"fields":[{"key":":1001","read":true,"write":true,"report":false},{"key":":1002","read":false,"write":false,"report":false}]},"list_options":{}}}',
+          'success requires:',
+          '  - result.enabled must be true',
+          '  - options.user_scope[].type is "user" for tenant users',
+          '  - 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":123}]}}',
+          '  - {"update":["user_scope"],"options":{"user_scope":[{"type":"user","id":2188889901}]}}',
           'success requires:',
           '  - result.enabled must be true',
-          '  - result.options.user_scope must contain the assigned user ids',
+          '  - result.options.user_scope must contain the assigned numeric TenantUser.ID values',
+          '  - PermitUserScope.id must be numeric TenantUser.ID',
+          '  - Do not copy hash arcubaseTenantUserId into PermitUserScope.id',
+          '  - If result.enabled is false, enable the rule first and retry assign-users',
         ]
       : []),
     ...(docHints.length > 0
       ? ['docs:', ...docHints.map((item) => `  - ${item.title}: ${item.file}`)]
       : []),
+    ...(typeHints.length > 0
+      ? ['types:', ...typeHints.map((item) => `  - ${item.symbol}: ${item.file}`)]
+      : []),
   ].join('\n')
 }
 
@@ -158,7 +192,7 @@ function buildScalarQuery(command: ReturnType<typeof findCommand>, flags: Record
     return undefined
   }
   const out: Record<string, any> = {}
-  for (const scalar of command.queryParams) {
+  for (const scalar of effectiveQueryParams(command)) {
     const value = getFixedValue(scalar) ?? flagValue(flags, scalar.flag)
     if (value === undefined) continue
     out[scalar.key] = coerceScalar(value, scalar.type)
@@ -166,10 +200,133 @@ function buildScalarQuery(command: ReturnType<typeof findCommand>, flags: Record
   return Object.keys(out).length > 0 ? out : undefined
 }
 
+function validateKnownFlags(command: NonNullable<ReturnType<typeof findCommand>>, flags: Record<string, string | boolean>, env: EnvInput = process.env) {
+  const allowed = new Set<string>(['help', 'body-file', 'body-json', 'query-file'])
+  for (const mapping of command.pathParams) {
+    if (!getFixedValue(mapping)) {
+      allowed.add(mapping.flag)
+    }
+  }
+  for (const query of visibleQueryParams(command)) {
+    if (!getFixedValue(query)) {
+      allowed.add(query.flag)
+    }
+  }
+  for (const flag of Object.keys(flags)) {
+    if (!allowed.has(flag)) {
+      throw new CLIError('UNKNOWN_FLAG', `unknown flag --${flag} for ${command.commandPath.join(' ')}`, 2, {
+        ...buildUnknownFlagDetails(command, flag, env),
+      })
+    }
+  }
+}
+
+function buildUnknownFlagDetails(
+  command: NonNullable<ReturnType<typeof findCommand>>,
+  flag: string,
+  env: EnvInput = process.env,
+): CLIErrorDetails {
+  const operation = command.commandPath.join(' ')
+  const details: CLIErrorDetails = {
+    operation,
+    hint: `run ${operation} --help for the supported flags`,
+  }
+  if (command.requestType) {
+    details.requestType = command.requestType
+    details.tsHints = getTypeHints(command.requestType, env)
+    details.docHints = getDocHints(command.requestType, env)
+    details.commonMistakes = [
+      `do not pass request body fields as --${flag}`,
+      'put request body fields inside --body-json <json-string>',
+    ]
+    details.suggestions = [`retry with: ${command.commandPath.join(' ')} ${command.pathParams.filter((item) => !getFixedValue(item)).map((item) => `--${item.flag} <${item.flag.replace(/-/g, '_')}>`).join(' ')} --body-json '<json>'`.replace(/\s+/g, ' ').trim()]
+  }
+  if (command.commandPath[0] === 'row' && command.commandPath[1] === 'query' && ['limit', 'offset', 'search', 'sorts', 'view-mode'].includes(flag)) {
+    details.shapeHint = { limit: 20, offset: 0, search: { text_search: 'SO-1001' } }
+    details.suggestions = ['retry with: row query --app-id <app_id> --table-id <table_id> --body-json \'{"limit":20,"offset":0}\'']
+  }
+  if (command.commandPath[0] === 'table' && command.commandPath[1] === 'dataset' && ['app-id', 'table-id'].includes(flag)) {
+    details.hint = 'table dataset uses --dataset-id and --node-id; use table get for app/table metadata'
+    details.suggestions = [
+      'retry metadata read with: table get --app-id <app_id> --table-id <table_id>',
+      'retry dataset read with: table dataset --dataset-id <dataset_id> --node-id <node_id>',
+    ]
+  }
+  return details
+}
+
+function visibleQueryParams(command: ReturnType<typeof findCommand>) {
+  if (!command) return []
+  return effectiveQueryParams(command).filter((item) => !getFixedValue(item))
+}
+
+function effectiveQueryParams(command: ReturnType<typeof findCommand>) {
+  if (!command) return []
+  return command.queryParams.filter((item) => {
+    if (rowCommandNeedsPolicy(command) && item.key === 'policy_id') {
+      return false
+    }
+    return true
+  })
+}
+
 function isRecord(value: unknown): value is Record<string, any> {
   return Boolean(value) && typeof value === 'object' && !Array.isArray(value)
 }
 
+function stringifyUpstreamBody(value: unknown): string {
+  if (typeof value === 'string') return value
+  if (value == null) return ''
+  try {
+    return JSON.stringify(value)
+  } catch {
+    return String(value)
+  }
+}
+
+function extractTraceID(value: unknown): string | undefined {
+  if (!isRecord(value)) return undefined
+  if (typeof value.trace_id === 'string') return value.trace_id
+  if (typeof value.request_id === 'string') return value.request_id
+  return undefined
+}
+
+function upstreamErrorMessage(value: unknown): string {
+  if (isRecord(value) && typeof value.message === 'string') return value.message
+  if (typeof value === 'string') return value
+  return stringifyUpstreamBody(value)
+}
+
+function throwUpstreamHTTPError(endpoint: string, method: string, response: Response, parsedResponse: unknown): never {
+  const upstreamError = isRecord(parsedResponse) && parsedResponse.error ? parsedResponse.error : undefined
+  const body = stringifyUpstreamBody(parsedResponse)
+  throw new CLIError(
+    'UPSTREAM_REQUEST_FAILED',
+    upstreamError ? upstreamErrorMessage(upstreamError) : body || `HTTP ${response.status}`,
+    1,
+    {
+      endpoint,
+      method,
+      status: response.status,
+      traceId: extractTraceID(parsedResponse),
+      responseBody: body,
+      ...(upstreamError ? { upstreamError } : {}),
+    },
+  )
+}
+
+async function fetchUpstream(url: string, init: RequestInit, endpoint: string, method: string, fetchImpl: typeof fetch): Promise<Response> {
+  try {
+    return await fetchImpl(url, init)
+  } catch (error) {
+    throw new CLIError('UPSTREAM_NETWORK_ERROR', error instanceof Error ? error.message : String(error), 1, {
+      endpoint,
+      method,
+      reason: 'network or DNS failure before Arcubase returned an HTTP response',
+    })
+  }
+}
+
 type EntityFieldInfo = {
   id: number
   type: string
@@ -197,10 +354,12 @@ async function fetchEntityFields(
   entityId: string,
   fetchImpl: typeof fetch,
 ): Promise<Map<number, EntityFieldInfo>> {
-  const response = await fetchImpl(buildURL(runtimeEnv.ARCUBASE_BASE_URL, `/api/entity/${encodeURIComponent(appId)}/${encodeURIComponent(entityId)}`), {
+  const endpoint = `/api/entity/${appId}/${entityId}`
+  const encodedEndpoint = `/api/entity/${encodeURIComponent(appId)}/${encodeURIComponent(entityId)}`
+  const response = await fetchUpstream(buildURL(runtimeEnv.ARCUBASE_BASE_URL, encodedEndpoint), {
     method: 'GET',
     headers: buildRequestHeaders(runtimeEnv),
-  })
+  }, endpoint, 'GET', fetchImpl)
   const raw = await response.text()
   let parsedResponse: unknown = raw
   try {
@@ -209,19 +368,15 @@ async function fetchEntityFields(
     parsedResponse = raw
   }
   if (!response.ok) {
-    throw new CLIError('UPSTREAM_REQUEST_FAILED', typeof parsedResponse === 'string' ? parsedResponse : JSON.stringify(parsedResponse), 1)
+    throwUpstreamHTTPError(endpoint, 'GET', response, parsedResponse)
   }
   if (isRecord(parsedResponse) && parsedResponse.error) {
     const upstreamError = parsedResponse.error
-    const upstreamMessage =
-      isRecord(upstreamError) && typeof upstreamError.message === 'string'
-        ? upstreamError.message
-        : typeof upstreamError === 'string'
-          ? upstreamError
-          : JSON.stringify(upstreamError)
+    const upstreamMessage = upstreamErrorMessage(upstreamError)
     throw new CLIError('UPSTREAM_BODY_ERROR', upstreamMessage, 1, {
-      endpoint: `/api/entity/${appId}/${entityId}`,
+      endpoint,
       method: 'GET',
+      traceId: extractTraceID(parsedResponse),
       upstreamError,
     })
   }
@@ -282,52 +437,52 @@ async function validateFileFieldPayloads(
     const fieldName = field.label ? `${field.label} (${field.type})` : `${field.type} field ${fieldId}`
     if (typeof value === 'string') {
       const guidance = looksLikeLocalFilePath(value)
-        ? `do not put a local file path directly into ${fieldName}; run "arcubase upload ${value}" first and use the returned data array as the field value`
-        : `${fieldName} must be an array returned by "arcubase upload <local-file>", not a string`
+        ? `do not put a local file path directly into ${fieldName}; use arcubase upload token flow and pass the returned upload value array`
+        : `${fieldName} must be an upload value array, not a string`
       throw new CLIError('BODY_VALIDATION_FAILED', guidance, 2, {
         operation: `${scope}.${command.module}.${command.functionName}`,
         requestType: command.requestType ?? undefined,
         issues: [{ path: fieldPath, message: guidance }],
         docHints: [
-          { title: 'Uploads', file: '/opt/arcubase-sdk/docs/runtime-reference/uploads.md' },
-          { title: 'Row CRUD', file: '/opt/arcubase-sdk/docs/runtime-reference/row-crud.md' },
+          { title: 'Uploads', file: sdkPath('docs/runtime-reference/uploads.md', runtimeEnv) },
+          { title: 'Row CRUD', file: sdkPath('docs/runtime-reference/row-crud.md', runtimeEnv) },
         ],
       })
     }
     if (isRecord(value)) {
-      const guidance = `${fieldName} must be an array. Run "arcubase upload <local-file>" and use the returned data array directly as the field value`
+      const guidance = `${fieldName} must be an upload value array. Use the upload token flow and pass the returned array directly`
       throw new CLIError('BODY_VALIDATION_FAILED', guidance, 2, {
         operation: `${scope}.${command.module}.${command.functionName}`,
         requestType: command.requestType ?? undefined,
         issues: [{ path: fieldPath, message: guidance }],
         docHints: [
-          { title: 'Uploads', file: '/opt/arcubase-sdk/docs/runtime-reference/uploads.md' },
-          { title: 'Row CRUD', file: '/opt/arcubase-sdk/docs/runtime-reference/row-crud.md' },
+          { title: 'Uploads', file: sdkPath('docs/runtime-reference/uploads.md', runtimeEnv) },
+          { title: 'Row CRUD', file: sdkPath('docs/runtime-reference/row-crud.md', runtimeEnv) },
         ],
       })
     }
     if (!Array.isArray(value)) {
-      const guidance = `${fieldName} must be an array returned by "arcubase upload <local-file>"`
+      const guidance = `${fieldName} must be an upload value array`
       throw new CLIError('BODY_VALIDATION_FAILED', guidance, 2, {
         operation: `${scope}.${command.module}.${command.functionName}`,
         requestType: command.requestType ?? undefined,
         issues: [{ path: fieldPath, message: guidance }],
         docHints: [
-          { title: 'Uploads', file: '/opt/arcubase-sdk/docs/runtime-reference/uploads.md' },
-          { title: 'Row CRUD', file: '/opt/arcubase-sdk/docs/runtime-reference/row-crud.md' },
+          { title: 'Uploads', file: sdkPath('docs/runtime-reference/uploads.md', runtimeEnv) },
+          { title: 'Row CRUD', file: sdkPath('docs/runtime-reference/row-crud.md', runtimeEnv) },
         ],
       })
     }
     for (const [index, item] of value.entries()) {
       if (!isValidUploadEntry(item)) {
-        const guidance = `${fieldName} entries must include upload_id or assets_id plus file and file_name. Use "arcubase upload <local-file>" and copy the returned array item as-is`
+        const guidance = `${fieldName} entries must include upload_id or assets_id plus file and file_name. Use the upload token flow and copy the returned array item as-is`
         throw new CLIError('BODY_VALIDATION_FAILED', guidance, 2, {
           operation: `${scope}.${command.module}.${command.functionName}`,
           requestType: command.requestType ?? undefined,
           issues: [{ path: `${fieldPath}.${index}`, message: guidance }],
           docHints: [
-            { title: 'Uploads', file: '/opt/arcubase-sdk/docs/runtime-reference/uploads.md' },
-            { title: 'Row CRUD', file: '/opt/arcubase-sdk/docs/runtime-reference/row-crud.md' },
+            { title: 'Uploads', file: sdkPath('docs/runtime-reference/uploads.md', runtimeEnv) },
+            { title: 'Row CRUD', file: sdkPath('docs/runtime-reference/row-crud.md', runtimeEnv) },
           ],
         })
       }
@@ -335,30 +490,464 @@ async function validateFileFieldPayloads(
   }
 }
 
-function throwBodyValidationFailure(message: string, requestType: string, path: string, scope: CommandScope, command: NonNullable<ReturnType<typeof findCommand>>) {
-  throw new CLIError('BODY_VALIDATION_FAILED', message, 2, {
+function buildTableCreateExampleBody() {
+  return {
+    name: '投票项目',
+    parent: 0,
+    schema_version: 0,
+    field_id_seq: 1003,
+    layout: [[1001], [1002]],
+    fields: [
+      {
+        id: 1001,
+        label: '投票名称',
+        type: 'text',
+        required: true,
+        unique: false,
+        editable: true,
+        visible: true,
+        show_label: true,
+        scannable: false,
+        default_value_mode: 0,
+        description: '',
+        value: null,
+        number_decimal: 0,
+        depends: [],
+        key: 'vote_name',
+        code_index: false,
+        options: { type: 'text', placeholder: '', lengthLimit: false, lengthMin: 0, lengthMax: 255 },
+        transfers: null,
+        children: null,
+      },
+      {
+        id: 1002,
+        label: '投票描述',
+        type: 'textarea',
+        required: false,
+        unique: false,
+        editable: true,
+        visible: true,
+        show_label: true,
+        scannable: false,
+        default_value_mode: 0,
+        description: '',
+        value: null,
+        number_decimal: 0,
+        depends: [],
+        key: 'vote_description',
+        code_index: false,
+        options: { placeholder: '', html: false, size: 'default', lengthLimit: false, lengthMin: 0, lengthMax: 2000 },
+        transfers: null,
+        children: null,
+      },
+    ],
+    options: { Buttons: [], CustomActions: [], FrontendEvents: [], TitleFormat: { Fields: [], Parts: [], Body: '' }, misc: {} },
+    workflow_enabled: false,
+  }
+}
+
+function isAssignUsersCommand(scope: CommandScope, command: NonNullable<ReturnType<typeof findCommand>>): boolean {
+  return scope === 'admin' && command.commandPath[0] === 'access-rule' && command.commandPath[1] === 'assign-users'
+}
+
+function isTableCreateCommand(scope: CommandScope, command: NonNullable<ReturnType<typeof findCommand>>): boolean {
+  return scope === 'admin' && command.commandPath[0] === 'table' && command.commandPath[1] === 'create'
+}
+
+function isTableSchemaCommand(scope: CommandScope, command: NonNullable<ReturnType<typeof findCommand>>): boolean {
+  return scope === 'admin' && command.commandPath[0] === 'table' && (command.commandPath[1] === 'create' || command.commandPath[1] === 'update-schema')
+}
+
+function isAccessRuleCommand(scope: CommandScope, command: NonNullable<ReturnType<typeof findCommand>>): boolean {
+  return scope === 'admin' && command.commandPath[0] === 'access-rule'
+}
+
+function isAccessRuleUpdateCommand(scope: CommandScope, command: NonNullable<ReturnType<typeof findCommand>>): boolean {
+  return scope === 'admin' && command.commandPath[0] === 'access-rule' && command.commandPath[1] === 'update'
+}
+
+function buildAccessRuleShapeHint(userId = 2188889901) {
+  return {
+    name: 'Sales read write',
+    enabled: true,
+    type: 'form',
+    options: {
+      user_scope: [{ type: 'user', id: userId }],
+      policy: {
+        key: 'custom',
+        actions: ['view', 'add', 'edit'],
+        all_fields_read: true,
+        all_fields_write: true,
+        fields: [{ key: ':1002', read: false, write: false, report: false }],
+      },
+      list_options: {},
+    },
+  }
+}
+
+function buildAssignUsersValidationDetails(
+  scope: CommandScope,
+  command: NonNullable<ReturnType<typeof findCommand>>,
+  requestType: string,
+  path: string,
+  message: string,
+  env: EnvInput = process.env,
+): CLIErrorDetails {
+  return {
     operation: `${scope}.${command.module}.${command.functionName}`,
     requestType,
-    issues: [
-      {
-        path,
-        message,
+    issues: [{ path, message }],
+    tsHints: [
+      { symbol: 'AppIngressUpdateReqVO', file: sdkPath('types/ingress.ts', env) },
+      { symbol: 'EntityIngressOptions', file: sdkPath('types/ingress.ts', env) },
+      { symbol: 'PermitUserScope', file: sdkPath('types/common.ts', env) },
+    ],
+    docHints: getDocHints(requestType, env),
+    shapeHint: {
+      update: ['user_scope'],
+      options: {
+        user_scope: [{ type: 'user', id: 2188889901 }],
       },
+    },
+    commonMistakes: [
+      'do not use user_scope at top level',
+      'do not use users or allowedUsers',
+      'do not use hash tenant user id as id',
+      'id must be numeric TenantUser.ID',
     ],
-    tsHints: getTypeHints(requestType),
-    docHints: getDocHints(requestType),
-  })
+  }
+}
+
+function buildBodyGuidance(requestType: string): Pick<CLIErrorDetails, 'shapeHint' | 'commonMistakes' | 'suggestions'> {
+  if (requestType === 'EntitySaveReqVO' || requestType === 'AppCreateEntityReqVO') {
+    return {
+      shapeHint: {
+        id: 2188889845,
+        app_id: 2188889844,
+        name: '订单',
+        schema_version: 0,
+        field_id_seq: 1004,
+        layout: [[1001], [1002], [1003]],
+        fields: [
+          {
+            id: 1001,
+            label: '订单号',
+            type: 'text',
+            required: true,
+            unique: false,
+            editable: true,
+            visible: true,
+            show_label: true,
+            scannable: false,
+            default_value_mode: 0,
+            description: '',
+            value: null,
+            number_decimal: 0,
+            depends: [],
+            key: 'order_no',
+            code_index: false,
+            options: { type: 'text', placeholder: '', lengthLimit: false, lengthMin: 0, lengthMax: 255 },
+            transfers: null,
+            children: null,
+          },
+          {
+            id: 1002,
+            label: '描述',
+            type: 'textarea',
+            required: false,
+            unique: false,
+            editable: true,
+            visible: true,
+            show_label: true,
+            scannable: false,
+            default_value_mode: 0,
+            description: '',
+            value: null,
+            number_decimal: 0,
+            depends: [],
+            key: 'description',
+            code_index: false,
+            options: { placeholder: '', html: false, size: 'default', lengthLimit: false, lengthMin: 0, lengthMax: 2000 },
+            transfers: null,
+            children: null,
+          },
+          {
+            id: 1003,
+            label: '状态',
+            type: 'select',
+            required: true,
+            unique: false,
+            editable: true,
+            visible: true,
+            show_label: true,
+            scannable: false,
+            default_value_mode: 1,
+            description: '',
+            value: 'draft',
+            number_decimal: 0,
+            depends: [],
+            key: 'status',
+            code_index: false,
+            options: {
+              horizontal: false,
+              numberMax: '',
+              numberMin: '',
+              numberRange: false,
+              repeatRemind: 'This value already exists and duplicate submission is not allowed',
+              options: {
+                mode: 'custom',
+                colorful: false,
+                items: [
+                  { key: 1, value: 'draft' },
+                  { key: 2, value: 'active' },
+                ],
+              },
+            },
+            transfers: null,
+            children: null,
+          },
+        ],
+        options: { Buttons: [], CustomActions: [], FrontendEvents: [], TitleFormat: { Fields: [], Parts: [], Body: '' }, misc: {} },
+        workflow_enabled: false,
+      },
+      commonMistakes: [
+        'table create must include fields and field_id_seq; do not create an empty table shell',
+        'prefer --body-json for table create/update-schema; do not create a body file unless JSON is too large for one tool call',
+        'fields must be an array of full FieldVO objects, not an object map',
+        'get table shell first: arcubase-admin table get --app-id <app_id> --table-id <table_id>',
+        'save the full returned schema after editing; do not submit only changed fields',
+        'field_id_seq must be greater than every field.id',
+        'layout must reference existing field ids',
+        'use type "text", not "string"',
+        'use type "member", not "user"',
+        'for select/radio/checkbox/status, options must contain options.items',
+        'for linkto/relation/query, options must contain relation.app_id, relation.entity_id, relation.type',
+        'do not put per-user permissions in FieldVO; use access-rule for read/write and hidden fields',
+      ],
+      suggestions: [
+        `retry with: arcubase-admin table create --app-id <app_id> --body-json '${JSON.stringify(buildTableCreateExampleBody())}'`,
+      ],
+    }
+  }
+  if (requestType === 'AppIngressCreateReqVO' || requestType === 'AppIngressUpdateReqVO') {
+    return {
+      shapeHint: buildAccessRuleShapeHint(),
+      commonMistakes: [
+        'use options.policy, not top-level permissions',
+        'use options.policy.fields, not field_visibility',
+        'actions must use Arcubase action codes: view, add, edit; do not use read, write, or insert',
+        'field permission keys must be strings prefixed with colon, for example ":1002"; do not use FieldVO.key values such as "vote_name"',
+        'for access-rule update policy changes, use {"update":["options"],"options":{"policy":...,"list_options":{}}}; do not use update:["options.policy"]',
+        'use options.user_scope with type user/department/actor and numeric id; do not use FieldVO type "member" here',
+        'use assign-users only for updating user_scope later',
+        'assign-users preserves existing policy when body.update=["user_scope"]',
+      ],
+    }
+  }
+  if (requestType === 'InsertReqVO') {
+    return {
+      shapeHint: {
+        fields: {
+          '1001': 'SO-1001',
+          '1002': 199,
+        },
+      },
+      commonMistakes: [
+        'row fields must use numeric field ids as JSON object keys',
+        'do not use field labels such as "标题" or "投票标题" as keys',
+        'run table get first when field ids are unclear',
+        'do not add access policy fields; the CLI resolves access policy internally',
+      ],
+      suggestions: [
+        'run: arcubase table get --app-id <app_id> --table-id <table_id>',
+        'retry with: arcubase row create --app-id <app_id> --table-id <table_id> --body-json \'{"fields":{"1001":"今天吃什么"}}\'',
+      ],
+    }
+  }
+  if (requestType === 'EntityQueryReqVO') {
+    return {
+      shapeHint: {
+        limit: 20,
+        offset: 0,
+        search: { text_search: 'SO-1001' },
+      },
+      commonMistakes: [
+        'limit, offset, search, sorts, and view_mode belong inside --body-json',
+        'do not pass --limit or --offset flags',
+        'do not add access policy fields; the CLI resolves access policy internally',
+      ],
+      suggestions: [
+        'retry with: arcubase row query --app-id <app_id> --table-id <table_id> --body-json \'{"limit":20,"offset":0}\'',
+      ],
+    }
+  }
+  if (requestType === 'EntityUpdateReqVO') {
+    return {
+      shapeHint: {
+        data: { '1002': 299 },
+        changed_fields: [1002],
+      },
+      commonMistakes: [
+        'use data, not fields',
+        'changed_fields is required and must match data keys',
+        'do not add access policy fields; the CLI resolves access policy internally',
+      ],
+    }
+  }
+  if (requestType === 'EntityBulkUpdateReqVO') {
+    return {
+      shapeHint: {
+        selection: {
+          type: 'ids',
+          ids: [2188890411, 2188890412],
+          length: 2,
+        },
+        fields: [
+          {
+            id: 1003,
+            action: {
+              type: 'set',
+              value: 2,
+            },
+          },
+        ],
+      },
+      commonMistakes: [
+        'bulk update fields[].action must be an object with type',
+        'use {"type":"set","value":2} to assign a scalar value',
+        'do not use value_set, setValue, or a top-level value field',
+        'use {"type":"number_add","number_add":10} only for numeric increments',
+        'selection.type=ids requires ids and length',
+      ],
+      suggestions: [
+        'retry with: arcubase row bulk-update --app-id <app_id> --table-id <table_id> --body-json \'{"selection":{"type":"ids","ids":[2188890411],"length":1},"fields":[{"id":1003,"action":{"type":"set","value":2}}]}\'',
+      ],
+    }
+  }
+  return {}
+}
+
+function buildBodyValidationDetails(
+  scope: CommandScope,
+  command: NonNullable<ReturnType<typeof findCommand>>,
+  requestType: string,
+  issues: CLIErrorDetails['issues'],
+  env: EnvInput = process.env,
+): CLIErrorDetails {
+  return {
+    operation: `${scope}.${command.module}.${command.functionName}`,
+    requestType,
+    issues,
+    tsHints: getTypeHints(requestType, env),
+    docHints: getDocHints(requestType, env),
+    ...buildBodyGuidance(requestType),
+  }
+}
+
+function throwBodyValidationFailure(message: string, requestType: string, path: string, scope: CommandScope, command: NonNullable<ReturnType<typeof findCommand>>, env: EnvInput = process.env): never {
+  if (isAssignUsersCommand(scope, command)) {
+    throw new CLIError('BODY_VALIDATION_FAILED', message, 2, buildAssignUsersValidationDetails(scope, command, requestType, path, message, env))
+  }
+  throw new CLIError('BODY_VALIDATION_FAILED', message, 2, buildBodyValidationDetails(scope, command, requestType, [{ path, message }], env))
+}
+
+function requireTableCreateSchemaBody(scope: CommandScope, command: NonNullable<ReturnType<typeof findCommand>>, body: unknown, env: EnvInput) {
+  if (!isRecord(body)) {
+    throwBodyValidationFailure(
+      'table create requires a JSON object with name, fields, field_id_seq, layout, options, and workflow_enabled',
+      'AppCreateEntityReqVO',
+      'body',
+      scope,
+      command,
+      env,
+    )
+  }
+  if (!Array.isArray(body.fields) || body.fields.length === 0) {
+    throwBodyValidationFailure(
+      'table create must include non-empty body.fields; empty table shell creation is not allowed',
+      'AppCreateEntityReqVO',
+      'body.fields',
+      scope,
+      command,
+      env,
+    )
+  }
+  if (typeof body.field_id_seq !== 'number') {
+    throwBodyValidationFailure(
+      'table create must include body.field_id_seq greater than every field.id',
+      'AppCreateEntityReqVO',
+      'body.field_id_seq',
+      scope,
+      command,
+      env,
+    )
+  }
 }
 
 function stringArray(value: unknown): string[] {
   return Array.isArray(value) ? value.filter((item): item is string => typeof item === 'string') : []
 }
 
+function validateAccessRuleUserScope(
+  scope: CommandScope,
+  command: NonNullable<ReturnType<typeof findCommand>>,
+  requestType: string,
+  userScope: unknown,
+  env: EnvInput,
+  pathPrefix = 'body.options.user_scope',
+) {
+  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,
+    )
+  }
+  const allowedTypes = new Set(['user', 'department', 'actor'])
+  for (const [index, item] of userScope.entries()) {
+    if (!isRecord(item)) {
+      throwBodyValidationFailure(
+        'access-rule user_scope item must be an object',
+        requestType,
+        `${pathPrefix}.${index}`,
+        scope,
+        command,
+        env,
+      )
+    }
+    if (typeof item.type !== 'string' || !allowedTypes.has(item.type)) {
+      throwBodyValidationFailure(
+        'access-rule user_scope[].type must be "user", "department", or "actor"; do not use FieldVO type "member" here',
+        requestType,
+        `${pathPrefix}.${index}.type`,
+        scope,
+        command,
+        env,
+      )
+    }
+    if (typeof item.id !== 'number' || !Number.isInteger(item.id) || item.id <= 0) {
+      throwBodyValidationFailure(
+        'access-rule user_scope[].id must be numeric TenantUser.ID, department ID, or actor ID',
+        requestType,
+        `${pathPrefix}.${index}.id`,
+        scope,
+        command,
+        env,
+      )
+    }
+  }
+}
+
 function requireUpdateContains(
   scope: CommandScope,
   command: NonNullable<ReturnType<typeof findCommand>>,
   body: Record<string, unknown>,
   field: string,
+  env: EnvInput,
 ) {
   if (!(field in body)) return
   const update = stringArray(body.update)
@@ -369,6 +958,7 @@ function requireUpdateContains(
       'body.update',
       scope,
       command,
+      env,
     )
   }
 }
@@ -377,22 +967,122 @@ function validateActionSpecificRawBody(
   scope: CommandScope,
   command: NonNullable<ReturnType<typeof findCommand>>,
   body: unknown,
+  env: EnvInput,
 ) {
   if (!isRecord(body) || !command.requestType) {
     return
   }
 
-  if (scope === 'admin' && command.commandPath[0] === 'access-rule' && command.commandPath[1] === 'assign-users') {
-    if ('users' in body || 'allowedUsers' in body) {
+  if (isAssignUsersCommand(scope, command)) {
+    if ('users' in body || 'allowedUsers' in body || 'user_scope' in body) {
       throwBodyValidationFailure(
-        'access-rule assign-users does not accept users or allowedUsers; use body.options.user_scope with {"update":["user_scope"],"options":{"user_scope":[{"type":"user","id":123}]}}',
+        '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,
+      )
+    }
+  }
+
+  if (isTableSchemaCommand(scope, command)) {
+    const fields = Array.isArray(body.fields) ? body.fields : []
+    const hasPermissionPatch = fields.some((field) => isRecord(field) && ('permission' in field || 'permissions' in field || 'field_visibility' in field))
+    if (hasPermissionPatch) {
+      throwBodyValidationFailure(
+        'table schema cannot configure per-user permissions. Use access-rule create/update with options.policy.fields for hidden fields',
+        command.requestType,
+        'body.fields',
+        scope,
+        command,
+        env,
       )
     }
   }
+
+  if (isAccessRuleCommand(scope, command)) {
+    const update = stringArray(body.update)
+    if (isAccessRuleUpdateCommand(scope, command) && update.some((item) => item.startsWith('options.'))) {
+      throwBodyValidationFailure(
+        'access-rule update cannot patch nested options paths. Use {"update":["options"],"options":{"policy":{"key":"custom","actions":["view","add","edit"],"all_fields_read":true,"all_fields_write":true,"fields":[{"key":":1002","read":false,"write":false,"report":false}]},"list_options":{}}}',
+        command.requestType,
+        'body.update',
+        scope,
+        command,
+        env,
+      )
+    }
+    if ('permissions' in body || 'field_visibility' in body || 'description' in body) {
+      throwBodyValidationFailure(
+        'access-rule body only supports name, enabled, type, and options; use options.policy.actions and options.policy.fields',
+        command.requestType,
+        'body',
+        scope,
+        command,
+        env,
+      )
+    }
+    const options = isRecord(body.options) ? body.options : undefined
+    if (options && ('permissions' in options || 'field_visibility' in options)) {
+      throwBodyValidationFailure(
+        'access-rule options only supports user_scope, policy, list_options, i18n_name; use options.policy.actions and options.policy.fields',
+        command.requestType,
+        'body.options',
+        scope,
+        command,
+        env,
+      )
+    }
+    const policy = options && isRecord(options.policy) ? options.policy : undefined
+    if (isAccessRuleUpdateCommand(scope, command) && update.includes('options') && options?.user_scope !== undefined && !policy) {
+      throwBodyValidationFailure(
+        'access-rule update with update:["options"] cannot change only options.user_scope because it overwrites policy. Use access-rule assign-users for user assignment, or include the full options.policy and options.list_options.',
+        command.requestType,
+        'body.options.policy',
+        scope,
+        command,
+        env,
+      )
+    }
+    validateAccessRuleUserScope(scope, command, command.requestType, options?.user_scope, env)
+    const actions = policy && Array.isArray(policy.actions) ? policy.actions : []
+    if (actions.includes('read') || actions.includes('write')) {
+      throwBodyValidationFailure(
+        'access-rule policy.actions must use Arcubase action codes: use "view" for read and "add","edit" for write; do not use "read", "write", or "insert"',
+        command.requestType,
+        'body.options.policy.actions',
+        scope,
+        command,
+        env,
+      )
+    }
+    const fields = policy && Array.isArray(policy.fields) ? policy.fields : []
+    const allowedSystemFieldKeys = new Set(['created', 'updated', 'creator'])
+    for (const [index, field] of fields.entries()) {
+      if (!isRecord(field)) continue
+      if (typeof field.key === 'number' || (typeof field.key === 'string' && /^\d+$/.test(field.key))) {
+        throwBodyValidationFailure(
+          'access-rule policy.fields[].key must be a string prefixed with colon, for example ":1002"; do not use raw numbers',
+          command.requestType,
+          `body.options.policy.fields.${index}.key`,
+          scope,
+          command,
+          env,
+        )
+      }
+      if (typeof field.key === 'string' && !field.key.startsWith(':') && !allowedSystemFieldKeys.has(field.key)) {
+        throwBodyValidationFailure(
+          'access-rule policy.fields[].key must use Arcubase permission keys such as ":1002"; do not use FieldVO.key values such as "vote_name"',
+          command.requestType,
+          `body.options.policy.fields.${index}.key`,
+          scope,
+          command,
+          env,
+        )
+      }
+    }
+  }
 }
 
 function validateActionSpecificBody(
@@ -400,28 +1090,30 @@ function validateActionSpecificBody(
   command: NonNullable<ReturnType<typeof findCommand>>,
   flags: Record<string, string | boolean>,
   body: unknown,
+  env: EnvInput,
 ) {
   if (!isRecord(body) || !command.requestType) {
     return
   }
 
   if (scope === 'admin' && command.commandPath[0] === 'access-rule' && command.commandPath[1] === 'update') {
-    requireUpdateContains(scope, command, body, 'enabled')
-    requireUpdateContains(scope, command, body, 'name')
-    requireUpdateContains(scope, command, body, 'options')
+    requireUpdateContains(scope, command, body, 'enabled', env)
+    requireUpdateContains(scope, command, body, 'name', env)
+    requireUpdateContains(scope, command, body, 'options', env)
   }
 
-  if (scope === 'admin' && command.commandPath[0] === 'access-rule' && command.commandPath[1] === 'assign-users') {
+  if (isAssignUsersCommand(scope, command)) {
     const update = stringArray(body.update)
     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 does not accept users or allowedUsers; use body.options.user_scope with {"update":["user_scope"],"options":{"user_scope":[{"type":"user","id":123}]}}',
+        '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,
       )
     }
     if (!update.includes('user_scope')) {
@@ -431,6 +1123,7 @@ function validateActionSpecificBody(
         'body.update',
         scope,
         command,
+        env,
       )
     }
     if (!userScope || userScope.length === 0) {
@@ -440,8 +1133,43 @@ function validateActionSpecificBody(
         'body.options.user_scope',
         scope,
         command,
+        env,
       )
     }
+    validateAccessRuleUserScope(scope, command, command.requestType, userScope, env)
+    const assignedUserScope = userScope
+    for (const [index, item] of assignedUserScope.entries()) {
+      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 TenantUser.ID',
+          command.requestType,
+          `body.options.user_scope.${index}.id`,
+          scope,
+          command,
+          env,
+        )
+      }
+    }
   }
 
   if (command.commandPath[0] === 'row' && command.commandPath[1] === 'selection-action') {
@@ -463,6 +1191,7 @@ function validateActionSpecificBody(
           'body.selection.type',
           scope,
           command,
+          env,
         )
       }
       return
@@ -475,6 +1204,7 @@ function validateActionSpecificBody(
         'body.selection.type',
         scope,
         command,
+        env,
       )
     }
 
@@ -485,11 +1215,370 @@ function validateActionSpecificBody(
         'body.selection.condition',
         scope,
         command,
+        env,
       )
     }
   }
 }
 
+function unwrapData(value: unknown): unknown {
+  let current = value
+  for (let i = 0; i < 3; i += 1) {
+    if (isRecord(current) && isRecord(current.data)) {
+      current = current.data
+      continue
+    }
+    break
+  }
+  return current
+}
+
+function requiredRowAction(command: NonNullable<ReturnType<typeof findCommand>>, flags: Record<string, string | boolean>): string | undefined {
+  if (command.commandPath[0] !== 'row') return undefined
+  switch (command.commandPath[1]) {
+    case 'query':
+    case 'get':
+      return 'view'
+    case 'create':
+      return 'add'
+    case 'update':
+      return 'edit'
+    case 'delete':
+      return 'delete'
+    case 'bulk-update':
+      return 'bulk_update'
+    case 'selection-action':
+      return flagValue(flags, 'action') || undefined
+    default:
+      return undefined
+  }
+}
+
+function rowCommandNeedsPolicy(command: NonNullable<ReturnType<typeof findCommand>>): boolean {
+  return command.scope === 'user' && command.commandPath[0] === 'row'
+}
+
+function extractIngressItems(appDetail: unknown): Array<{ id: string }> {
+  const appData = unwrapData(appDetail)
+  const ingress = isRecord(appData) ? appData.ingress : undefined
+  const groups = isRecord(ingress) && Array.isArray(ingress.groups) ? ingress.groups : []
+  const items: Array<{ id: string }> = []
+  for (const group of groups) {
+    const groupItems = isRecord(group) && Array.isArray(group.items) ? group.items : []
+    for (const item of groupItems) {
+      if (!isRecord(item)) continue
+      const id = typeof item.id === 'string' ? item.id : typeof item.ID === 'string' ? item.ID : ''
+      if (id) {
+        items.push({ id })
+      }
+    }
+  }
+  return items
+}
+
+type ResolvedRowPolicy = {
+  policyID: string
+  policy?: Record<string, unknown>
+}
+
+function ingressMatchesTableAndAction(ingressDetail: unknown, tableId: string, action: string | undefined): ResolvedRowPolicy | undefined {
+  const ingressData = unwrapData(ingressDetail)
+  if (!isRecord(ingressData)) return undefined
+  const id = typeof ingressData.id === 'number' || typeof ingressData.id === 'string'
+    ? ingressData.id
+    : typeof ingressData.ID === 'number' || typeof ingressData.ID === 'string'
+      ? ingressData.ID
+      : undefined
+  if (String(id ?? '') !== tableId) return undefined
+  const policyID = typeof ingressData.hash_id === 'string'
+    ? ingressData.hash_id
+    : typeof ingressData.hashId === 'string'
+      ? ingressData.hashId
+      : undefined
+  const policy = isRecord(ingressData.policy) ? ingressData.policy : undefined
+  if (!action) return { policyID: policyID || '', policy }
+  const actions = policy && Array.isArray(policy.actions) ? policy.actions.filter((item): item is string => typeof item === 'string') : []
+  if (!actions.includes(action)) return undefined
+  return { policyID: policyID || '', policy }
+}
+
+function writtenRowFieldIds(command: NonNullable<ReturnType<typeof findCommand>>, body: unknown): number[] {
+  if (!isRecord(body)) return []
+  const source = command.commandPath[1] === 'create'
+    ? body.fields
+    : command.commandPath[1] === 'update'
+      ? body.data
+      : undefined
+  if (!isRecord(source)) return []
+  return Object.keys(source)
+    .filter((key) => /^\d+$/.test(key))
+    .map((key) => Number(key))
+}
+
+function fieldWriteAllowedByPolicy(policy: Record<string, unknown> | undefined, fieldId: number): boolean {
+  if (!policy) return true
+  const fields = Array.isArray(policy.fields) ? policy.fields : []
+  const explicit = fields.find((item) => isRecord(item) && item.key === `:${fieldId}`)
+  if (isRecord(explicit) && explicit.write === false) return false
+  if (isRecord(explicit) && explicit.write === true) return true
+  if (policy.all_fields_write === false) return false
+  return true
+}
+
+function assertWritableFieldsForRowCommand(
+  command: NonNullable<ReturnType<typeof findCommand>>,
+  runtimeEnv: RuntimeEnv,
+  body: unknown,
+  policy: Record<string, unknown> | undefined,
+) {
+  if (command.commandPath[1] !== 'create' && command.commandPath[1] !== 'update') {
+    return
+  }
+  const denied = writtenRowFieldIds(command, body).filter((fieldId) => !fieldWriteAllowedByPolicy(policy, fieldId))
+  if (denied.length === 0) {
+    return
+  }
+  const payloadKey = command.commandPath[1] === 'create' ? 'fields' : 'data'
+  throw new CLIError('FIELD_PERMISSION_REQUIRED', `row ${command.commandPath[1]} includes field ids without write permission: ${denied.join(', ')}`, 2, {
+    operation: `user.${command.module}.${command.functionName}`,
+    requestType: command.requestType ?? undefined,
+    issues: denied.map((fieldId) => ({
+      path: `body.${payloadKey}.${fieldId}`,
+      message: 'field is not writable for the resolved Arcubase access rule',
+    })),
+    docHints: [
+      { title: 'Row CRUD', file: sdkPath('docs/runtime-reference/row-crud.md', runtimeEnv) },
+      { title: 'Runtime reference', file: sdkPath('docs/runtime-reference/README.md', runtimeEnv) },
+    ],
+    suggestions: [
+      'remove non-writable field ids from the row body and retry',
+      'run arcubase table get to map visible business fields to numeric field ids',
+      'ask an admin to update the access-rule if this field should be writable',
+    ],
+  })
+}
+
+async function resolvePolicyIDForRowCommand(
+  command: NonNullable<ReturnType<typeof findCommand>>,
+  runtimeEnv: RuntimeEnv,
+  flags: Record<string, string | boolean>,
+  fetchImpl: typeof fetch,
+): Promise<ResolvedRowPolicy> {
+  const appId = flagValue(flags, 'app-id')
+  const tableId = flagValue(flags, 'table-id')
+  const action = requiredRowAction(command, flags)
+  if (!appId || !tableId) {
+    throw new CLIError('POLICY_ID_RESOLUTION_FAILED', 'row command requires --app-id and --table-id to resolve Arcubase policy_id', 2, {
+      operation: `user.${command.module}.${command.functionName}`,
+      docHints: getDocHints(command.requestType ?? '', runtimeEnv),
+    })
+  }
+
+  const appDetail = await requestJSON(runtimeEnv, 'GET', `/api/apps/${encodeURIComponent(appId)}`, undefined, fetchImpl)
+  const ingressItems = extractIngressItems(appDetail.data)
+  for (const item of ingressItems) {
+    const ingressDetail = await requestJSON(runtimeEnv, 'GET', `/api/ingress/${encodeURIComponent(appId)}/${encodeURIComponent(item.id)}`, undefined, fetchImpl)
+    const match = ingressMatchesTableAndAction(ingressDetail.data, tableId, action)
+    if (match) {
+      return { ...match, policyID: match.policyID || item.id }
+    }
+  }
+
+  throw new CLIError('POLICY_ID_RESOLUTION_FAILED', `no accessible ingress policy found for app ${appId}, table ${tableId}${action ? `, action ${action}` : ''}`, 2, {
+    operation: `user.${command.module}.${command.functionName}`,
+    requestType: command.requestType ?? undefined,
+    issues: [{ path: 'policy_id', message: 'CLI could not resolve policy_id from accessible ingress' }],
+    docHints: [
+      { title: 'Row CRUD', file: sdkPath('docs/runtime-reference/row-crud.md', runtimeEnv) },
+      { title: 'Runtime reference', file: sdkPath('docs/runtime-reference/README.md', runtimeEnv) },
+    ],
+    suggestions: [
+      'run arcubase entry and confirm the app/table is visible',
+      'ask an admin to create an enabled access-rule with the required action for this table',
+    ],
+  })
+}
+
+async function injectResolvedPolicyID(
+  command: NonNullable<ReturnType<typeof findCommand>>,
+  runtimeEnv: RuntimeEnv,
+  flags: Record<string, string | boolean>,
+  query: Record<string, unknown>,
+  body: unknown,
+  fetchImpl: typeof fetch,
+): Promise<{ query: Record<string, unknown>; body: unknown }> {
+  if (!rowCommandNeedsPolicy(command)) {
+    return { query, body }
+  }
+  if (typeof query.policy_id === 'string' && query.policy_id) {
+    return { query, body }
+  }
+  if (isRecord(body) && typeof body.policy_id === 'string' && body.policy_id) {
+    return { query, body }
+  }
+
+  const resolvedPolicy = await resolvePolicyIDForRowCommand(command, runtimeEnv, flags, fetchImpl)
+  const policyID = resolvedPolicy.policyID
+  assertWritableFieldsForRowCommand(command, runtimeEnv, body, resolvedPolicy.policy)
+  if (command.commandPath[1] === 'get') {
+    return { query: { ...query, policy_id: policyID }, body }
+  }
+  if (isRecord(body)) {
+    return { query, body: { ...body, policy_id: policyID } }
+  }
+  return { query, body }
+}
+
+function assertNoUserPolicyIDInput(
+  command: NonNullable<ReturnType<typeof findCommand>>,
+  runtimeEnv: RuntimeEnv,
+  query: Record<string, unknown>,
+  body: unknown,
+) {
+  if (!rowCommandNeedsPolicy(command)) {
+    return
+  }
+  if ('policy_id' in query || (isRecord(body) && 'policy_id' in body)) {
+    throw new CLIError('INTERNAL_POLICY_ID_NOT_ALLOWED', 'policy_id is an internal Arcubase ingress parameter; use app/table/row ids only', 2, {
+      operation: `user.${command.module}.${command.functionName}`,
+      issues: [{ path: 'policy_id', message: 'do not provide policy_id in flags, query file, or body JSON' }],
+      docHints: [
+        { title: 'Row CRUD', file: sdkPath('docs/runtime-reference/row-crud.md', runtimeEnv) },
+        { title: 'Runtime reference', file: sdkPath('docs/runtime-reference/README.md', runtimeEnv) },
+      ],
+      suggestions: ['run arcubase entry to find the app/table ids, then retry without policy_id'],
+    })
+  }
+}
+
+async function requestJSON(
+  runtimeEnv: RuntimeEnv,
+  method: string,
+  endpoint: string,
+  body: unknown,
+  fetchImpl: typeof fetch,
+): Promise<{ status: number; data: any }> {
+  const response = await fetchUpstream(buildURL(runtimeEnv.ARCUBASE_BASE_URL, endpoint), {
+    method,
+    headers: {
+      ...buildRequestHeaders(runtimeEnv),
+      'Content-Type': 'application/json',
+    },
+    body: body === undefined || method === 'GET' ? undefined : JSON.stringify(body),
+  }, endpoint, method, fetchImpl)
+  const raw = await response.text()
+  let parsedResponse: any = raw
+  try {
+    parsedResponse = raw ? JSON.parse(raw) : null
+  } catch {
+    // keep raw text
+  }
+  if (!response.ok) {
+    throwUpstreamHTTPError(endpoint, method, response, parsedResponse)
+  }
+  if (parsedResponse && typeof parsedResponse === 'object' && 'error' in parsedResponse && parsedResponse.error) {
+    const upstreamError = parsedResponse.error
+    const upstreamMessage = upstreamErrorMessage(upstreamError)
+    throw new CLIError('UPSTREAM_BODY_ERROR', upstreamMessage, 1, { upstreamError })
+  }
+  return { status: response.status, data: parsedResponse }
+}
+
+function extractCreatedTableID(value: unknown): number {
+  const candidates = [
+    value,
+    isRecord(value) ? value.data : undefined,
+    isRecord(value) && isRecord(value.data) ? value.data.data : undefined,
+  ]
+  for (const candidate of candidates) {
+    if (isRecord(candidate) && typeof candidate.id === 'number') {
+      return candidate.id
+    }
+  }
+  throw new CLIError('UPSTREAM_RESPONSE_INVALID', 'table create response did not include numeric table id', 1)
+}
+
+function normalizeTableCreateSchemaBody(body: Record<string, any>, appId: string, tableId: number): Record<string, any> {
+  const { parent: _parent, ...schemaBody } = body
+  return {
+    ...schemaBody,
+    id: tableId,
+    app_id: Number.isFinite(Number(appId)) ? Number(appId) : body.app_id,
+    schema_version: typeof body.schema_version === 'number' ? body.schema_version : 0,
+    layout: Array.isArray(body.layout) ? body.layout : [],
+    options: isRecord(body.options)
+      ? body.options
+      : { Buttons: [], CustomActions: [], FrontendEvents: [], TitleFormat: { Fields: [], Parts: [], Body: '' }, misc: {} },
+    workflow_enabled: typeof body.workflow_enabled === 'boolean' ? body.workflow_enabled : false,
+  }
+}
+
+async function executeTableCreateWithSchema(
+  command: NonNullable<ReturnType<typeof findCommand>>,
+  runtimeEnv: RuntimeEnv,
+  flags: Record<string, string | boolean>,
+  body: unknown,
+  fetchImpl: typeof fetch,
+): Promise<any> {
+  const appId = flagValue(flags, 'app-id')
+  if (!appId) {
+    throw new CLIError('MISSING_PATH_FLAG', 'missing required flag --app-id', 2)
+  }
+  if (!isRecord(body)) {
+    throw new CLIError('BODY_VALIDATION_FAILED', 'table create body must be an object', 2)
+  }
+  const createBody = {
+    name: typeof body.name === 'string' ? body.name : undefined,
+    parent: typeof body.parent === 'number' ? body.parent : 0,
+  }
+  if (!createBody.name) {
+    throw new CLIError('BODY_VALIDATION_FAILED', 'table create requires body.name', 2)
+  }
+  const createResult = await requestJSON(runtimeEnv, command.method, resolveEndpoint(command, flags), createBody, fetchImpl)
+  const tableId = extractCreatedTableID(createResult.data)
+  const saveBody = normalizeTableCreateSchemaBody(body, appId, tableId)
+  const saveSchema = getBodySchema('EntitySaveReqVO')
+  if (!saveSchema) {
+    throw new CLIError('BODY_VALIDATION_FAILED', 'EntitySaveReqVO schema is not available', 2)
+  }
+  const parsedSaveBody = saveSchema.safeParse(saveBody)
+  if (!parsedSaveBody.success) {
+    const message = parsedSaveBody.error.issues.map((issue) => `${issue.path.join('.')}: ${issue.message}`).join('; ')
+    throw new CLIError(
+      'BODY_VALIDATION_FAILED',
+      message,
+      2,
+      buildBodyValidationDetails(
+        'admin',
+        command,
+        'EntitySaveReqVO',
+        parsedSaveBody.error.issues.map((issue) => ({
+          path: issue.path.length > 0 ? `body.${issue.path.join('.')}` : 'body',
+          message: issue.message,
+        })),
+        runtimeEnv,
+      ),
+    )
+  }
+  const saveResult = await requestJSON(
+    runtimeEnv,
+    'PUT',
+    `/api/apps/${encodeURIComponent(appId)}/entity/${encodeURIComponent(String(tableId))}`,
+    parsedSaveBody.data,
+    fetchImpl,
+  )
+  return {
+    kind: 'result',
+    commandPath: command.commandPath,
+    status: saveResult.status,
+    data: {
+      id: tableId,
+      created: createResult.data,
+      schema: saveResult.data,
+    },
+  }
+}
+
 export function summarizeCommand(scope: CommandScope, moduleName: string, commandName: string): CommandExecutionSummary {
   const command = findCommand(scope, moduleName, commandName)
   if (!command) {
@@ -502,37 +1591,13 @@ export function summarizeCommand(scope: CommandScope, moduleName: string, comman
     endpoint: command.endpoint,
     requestType: command.requestType,
     pathFlags: command.pathParams.filter((item) => !getFixedValue(item)).map((item) => item.flag),
-    queryFlags: command.queryParams.filter((item) => !getFixedValue(item)).map((item) => item.flag),
+    queryFlags: visibleQueryParams(command).map((item) => item.flag),
   }
 }
 
 export async function executeCLI(scope: CommandScope, argv: string[], env?: RuntimeEnv, fetchImpl: typeof fetch = fetch): Promise<any> {
   const parsed = parseCLIArgs(argv)
-  if (scope === 'user' && parsed.commandTokens[0] === 'upload') {
-    if (hasFlag(parsed.flags, 'help') || parsed.commandTokens.length === 1) {
-      return { kind: 'help', text: renderUploadHelp() }
-    }
-    const sourcePath = parsed.commandTokens[1]
-    if (!sourcePath) {
-      throw new CLIError('UPLOAD_SOURCE_REQUIRED', 'upload requires a local file path', 2)
-    }
-    const runtimeEnv = env ?? loadRuntimeEnv(scope)
-    const data = await uploadLocalFile(
-      runtimeEnv,
-      sourcePath,
-      {
-        filename: flagValue(parsed.flags, 'filename'),
-        global: hasFlag(parsed.flags, 'global'),
-      },
-      fetchImpl,
-    )
-    return {
-      kind: 'result',
-      commandPath: ['upload', sourcePath],
-      status: 200,
-      data,
-    }
-  }
+  const envInput = env ?? process.env
   if (parsed.commandTokens.length === 0) {
     return { kind: 'help', text: renderRootHelp(scope) }
   }
@@ -542,24 +1607,38 @@ export async function executeCLI(scope: CommandScope, argv: string[], env?: Runt
   }
   const singleTokenCommand = !commandName ? findCommand(scope, moduleName) : null
   if (!commandName && !singleTokenCommand) {
-    return { kind: 'help', text: renderModuleHelp(scope, moduleName) }
+    return { kind: 'help', text: renderModuleHelp(scope, moduleName, envInput) }
   }
   if (hasFlag(parsed.flags, 'help')) {
-    return { kind: 'help', text: renderCommandHelp(scope, moduleName, commandName) }
+    return { kind: 'help', text: renderCommandHelp(scope, moduleName, commandName, envInput) }
   }
 
-  const runtimeEnv = env ?? loadRuntimeEnv(scope)
-
   const command = findCommand(scope, moduleName, commandName)
   if (!command) {
     throw new CLIError('UNKNOWN_COMMAND', `unknown command: ${moduleName}${commandName ? ` ${commandName}` : ''}`, 2, buildUnknownCommandDetails(scope, moduleName, commandName ?? ''))
   }
+  validateKnownFlags(command, parsed.flags, envInput)
+
+  const runtimeEnv = env ?? loadRuntimeEnv(scope)
 
   const endpoint = resolveEndpoint(command, parsed.flags)
   const scalarQuery = buildScalarQuery(command, parsed.flags)
   const fileQuery = loadQueryFromFlags(parsed.flags)
-  const query = { ...(scalarQuery ?? {}), ...(fileQuery ?? {}) }
-  const body = loadBodyFromFlags(parsed.flags)
+  let query = { ...(fileQuery ?? {}), ...(scalarQuery ?? {}) }
+  let body: unknown
+  try {
+    body = loadBodyFromFlags(parsed.flags)
+  } catch (error) {
+    if (error instanceof CLIError && error.code === 'INVALID_BODY_JSON' && command.requestType) {
+      throw new CLIError(
+        'INVALID_BODY_JSON',
+        `body json is invalid for ${scope}.${command.commandPath.join(' ')}; fix JSON syntax, then use the canonical ${command.requestType} shape from docs/types`,
+        2,
+        buildBodyValidationDetails(scope, command, command.requestType, [{ path: 'body', message: 'invalid JSON syntax' }], runtimeEnv),
+      )
+    }
+    throw error
+  }
   let validatedBody = body
 
   if (!command.requestType && body !== undefined) {
@@ -568,31 +1647,77 @@ export async function executeCLI(scope: CommandScope, argv: string[], env?: Runt
 
   if (command.requestType) {
     if (body === undefined) {
-      throw new CLIError('MISSING_BODY_FILE', `command requires --body-file or --body-json for ${command.requestType}`, 2)
+      throw new CLIError('MISSING_BODY_FILE', `command requires --body-json or --body-file for ${command.requestType}; prefer --body-json to avoid file creation`, 2)
+    }
+    if (isTableCreateCommand(scope, command)) {
+      requireTableCreateSchemaBody(scope, command, body, runtimeEnv)
+      validateActionSpecificRawBody(scope, command, body, runtimeEnv)
+      const { parent: _parent, ...schemaBody } = isRecord(body) ? body : {}
+      const parsedBody = getBodySchema('EntitySaveReqVO')?.safeParse(schemaBody)
+      if (!parsedBody?.success) {
+        const message = parsedBody
+          ? parsedBody.error.issues.map((issue) => `${issue.path.join('.')}: ${issue.message}`).join('; ')
+          : 'EntitySaveReqVO schema is not available'
+        throw new CLIError(
+          'BODY_VALIDATION_FAILED',
+          message,
+          2,
+          buildBodyValidationDetails(
+            scope,
+            command,
+            'EntitySaveReqVO',
+            parsedBody && !parsedBody.success
+              ? parsedBody.error.issues.map((issue) => ({
+                  path: issue.path.length > 0 ? `body.${issue.path.join('.')}` : 'body',
+                  message: issue.message,
+                }))
+              : [{ path: 'body', message }],
+            runtimeEnv,
+          ),
+        )
+      }
+      return executeTableCreateWithSchema(command, runtimeEnv, parsed.flags, parsedBody.data, fetchImpl)
     }
-    validateActionSpecificRawBody(scope, command, body)
+    validateActionSpecificRawBody(scope, command, body, runtimeEnv)
     const schema = getBodySchema(command.requestType)
     if (schema) {
       const parsedBody = schema.safeParse(body)
       if (!parsedBody.success) {
+        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 TenantUser.ID' : 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 TenantUser.ID' : message,
+              runtimeEnv,
+            )
+          )
+        }
         throw new CLIError(
           'BODY_VALIDATION_FAILED',
-          parsedBody.error.issues.map((issue) => `${issue.path.join('.')}: ${issue.message}`).join('; '),
+          message,
           2,
-          {
-            operation: `${scope}.${command.module}.${command.functionName}`,
-            requestType: command.requestType,
-            issues: parsedBody.error.issues.map((issue) => ({
+          buildBodyValidationDetails(
+            scope,
+            command,
+            command.requestType,
+            parsedBody.error.issues.map((issue) => ({
               path: issue.path.length > 0 ? `body.${issue.path.join('.')}` : 'body',
               message: issue.message,
             })),
-            tsHints: getTypeHints(command.requestType),
-            docHints: getDocHints(command.requestType),
-          }
+            runtimeEnv,
+          )
         )
       }
       validatedBody = parsedBody.data
-      validateActionSpecificBody(scope, command, parsed.flags, validatedBody)
+      validateActionSpecificBody(scope, command, parsed.flags, validatedBody, runtimeEnv)
     } else {
       const unsupportedReason = getUnsupportedBodySchemaReason(command.requestType)
       if (unsupportedReason) {
@@ -600,25 +1725,30 @@ export async function executeCLI(scope: CommandScope, argv: string[], env?: Runt
           operation: `${scope}.${command.module}.${command.functionName}`,
           requestType: command.requestType,
           reason: unsupportedReason,
-          tsHints: getTypeHints(command.requestType),
-          docHints: getDocHints(command.requestType),
+          tsHints: getTypeHints(command.requestType, runtimeEnv),
+          docHints: getDocHints(command.requestType, runtimeEnv),
         })
       }
     }
   }
 
+  assertNoUserPolicyIDInput(command, runtimeEnv, query, validatedBody)
+
   if (scope === 'user' && (command.functionName === 'insertEntity' || command.functionName === 'updateEntityRow')) {
     await validateFileFieldPayloads(scope, command, runtimeEnv, parsed.flags, validatedBody, fetchImpl)
   }
+  const policyInjected = await injectResolvedPolicyID(command, runtimeEnv, parsed.flags, query, validatedBody, fetchImpl)
+  query = policyInjected.query
+  validatedBody = policyInjected.body
 
-  const response = await fetchImpl(buildURL(runtimeEnv.ARCUBASE_BASE_URL, endpoint, Object.keys(query).length > 0 ? query : undefined), {
+  const response = await fetchUpstream(buildURL(runtimeEnv.ARCUBASE_BASE_URL, endpoint, Object.keys(query).length > 0 ? query : undefined), {
     method: command.method,
     headers: {
       ...buildRequestHeaders(runtimeEnv),
       'Content-Type': 'application/json',
     },
     body: validatedBody === undefined || command.method === 'GET' ? undefined : JSON.stringify(validatedBody),
-  })
+  }, endpoint, command.method, fetchImpl)
 
   const raw = await response.text()
   let parsedResponse: any = raw
@@ -628,22 +1758,12 @@ export async function executeCLI(scope: CommandScope, argv: string[], env?: Runt
     // keep raw text
   }
   if (!response.ok) {
-    throw new CLIError('UPSTREAM_REQUEST_FAILED', typeof parsedResponse === 'string' ? parsedResponse : JSON.stringify(parsedResponse), 1)
+    throwUpstreamHTTPError(endpoint, command.method, response, parsedResponse)
   }
   if (parsedResponse && typeof parsedResponse === 'object' && 'error' in parsedResponse && parsedResponse.error) {
     const upstreamError = parsedResponse.error
-    const upstreamMessage =
-      typeof upstreamError === 'object' && upstreamError && 'message' in upstreamError && typeof upstreamError.message === 'string'
-        ? upstreamError.message
-        : typeof upstreamError === 'string'
-          ? upstreamError
-          : JSON.stringify(upstreamError)
-    const traceId =
-      typeof parsedResponse.trace_id === 'string'
-        ? parsedResponse.trace_id
-        : typeof parsedResponse.request_id === 'string'
-          ? parsedResponse.request_id
-          : undefined
+    const upstreamMessage = upstreamErrorMessage(upstreamError)
+    const traceId = extractTraceID(parsedResponse)
     const uploadBindFailure = upstreamMessage.includes('failed to bind upload to assets')
     throw new CLIError('UPSTREAM_BODY_ERROR', upstreamMessage, 1, {
       endpoint,
@@ -653,10 +1773,10 @@ export async function executeCLI(scope: CommandScope, argv: string[], env?: Runt
       ...(uploadBindFailure
         ? {
             reason: 'the row payload used a file/image upload entry, but Arcubase could not bind that upload into an asset record',
-            hint: 'verify the upload storage host is reachable from the Arcubase server, then rerun arcubase upload and retry the row insert/update',
+            hint: 'verify the upload storage host is reachable from the Arcubase server, then use the upload token flow again and retry the row insert/update',
             docHints: [
-              { title: 'Uploads', file: '/opt/arcubase-sdk/docs/runtime-reference/uploads.md' },
-              { title: 'Row CRUD', file: '/opt/arcubase-sdk/docs/runtime-reference/row-crud.md' },
+              { title: 'Uploads', file: 'docs/runtime-reference/uploads.md' },
+              { title: 'Row CRUD', file: 'docs/runtime-reference/row-crud.md' },
             ],
           }
         : {}),