aspera-cli 4.26.2 → 4.27.1

data/lib/aspera/cli/plugins/aoc.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+require 'aspera/schema/registry'
 require 'aspera/cli/plugins/oauth'
 require 'aspera/cli/plugins/node'
 require 'aspera/cli/plugins/ats'
@@ -7,12 +8,14 @@ require 'aspera/cli/transfer_agent'
 require 'aspera/cli/special_values'
 require 'aspera/cli/wizard'
 require 'aspera/agent/node'
+require 'aspera/transfer/result'
 require 'aspera/transfer/spec'
 require 'aspera/api/aoc'
 require 'aspera/api/node'
 require 'aspera/persistency_action_once'
 require 'aspera/id_generator'
 require 'aspera/assert'
+require 'aspera/graphql'
 require 'securerandom'
 require 'date'
 
@@ -56,11 +59,9 @@ module Aspera
         PACKAGE_LIST_DEFAULT_FIELDS = %w[id name created_at files_completed bytes_transferred].freeze
 
         private_constant :REDIRECT_LOCALHOST, :ADMIN_OBJECTS, :PACKAGE_RECEIVED_BASE_QUERY, :PACKAGE_LIST_DEFAULT_FIELDS
-        class << self
-          def application_name
-            'Aspera on Cloud'
-          end
+        application_name 'Aspera on Cloud'
 
+        class << self
           # @return [Hash,NilClass]
           def detect(base_url)
             # no protocol ?
@@ -99,10 +100,10 @@ module Aspera
           # or a sequential number if extension == :seq
           # @param package_info       [Hash]   Package information
           # @param destination_folder [String] Base folder
-          # @param fld.               [Array]  List of fields of package
+          # @param fld                [Array]  List of fields of package
           def unique_folder(package_info, destination_folder, fld: nil, seq: false, opt: false)
-            Aspera.assert_array_all(fld, String, type: BadArgument){'fld'}
-            Aspera.assert_values(fld.length, [1, 2]){'fld length'}
+            Aspera.assert_array_all(fld, String, type: BadArgument) { 'fld' }
+            Aspera.assert_values(fld.length, [1, 2]) { 'fld length' }
             folder = Environment.instance.sanitized_filename(package_info[fld[0]])
             if seq
               folder = next_available_folder(folder, always: !opt)
@@ -110,9 +111,73 @@ module Aspera
               # NOTE: it might already exist
               folder = "#{folder}.#{Environment.instance.sanitized_filename(fld[1])}"
             end
-            puts("sub= #{folder}")
             File.join(destination_folder, folder)
           end
+
+          # @return [String] AoC REST path for an admin resource type
+          def aoc_res_path(res)
+            cfg = ADMIN_OBJECT_CONFIG.fetch(res, {})
+            return cfg[:path] if cfg[:path]
+            "#{res}s".gsub(/ys$/, 'ies')
+          end
+
+          # @return [Hash] {path:, ops:, id_result:, require_ws_id:, list_fields:, schema:, query_component:}
+          def aoc_res_cfg(res)
+            cfg    = ADMIN_OBJECT_CONFIG.fetch(res, {})
+            path   = aoc_res_path(res)
+            ops    = cfg[:ops] || (Base::Operations::ALL + (cfg[:extra_ops] || []))
+            schema = cfg[:create_schema] == false ? nil : Schema::Registry.req_body(Schema::Registry::AOC, "#{path}.post")
+            {
+              path:            path,
+              ops:             ops,
+              id_result:       cfg[:id_result] || 'id',
+              require_ws_id:   cfg[:require_ws_id] || false,
+              list_fields:     cfg.key?(:list_fields) ? cfg[:list_fields] : %w[id name],
+              schema:          schema,
+              query_component: Schema::Registry::AOC
+            }
+          end
+
+          # DSL helper: register the 5 short_link leaf commands under the given parent path
+          # and define the corresponding action methods on `base`.
+          # @param base        [Class]         the plugin class
+          # @param parent_path [Array<Symbol>] full path ending with :short_link
+          def register_short_link_commands(base, parent_path)
+            base.commands_under(parent_path) do
+              base.command(
+                :create, description: 'Create',
+                arguments: [{name: :custom_data, type: Hash, mandatory: false, default: {}}]
+              )
+              base.command(
+                :modify, description: 'Modify',
+                arguments: [{name: :short_link_id, type: :identifier}, {name: :custom_data, type: Hash, mandatory: false, default: {}}]
+              )
+              base.command(:list, description: 'List short links')
+              base.command(
+                :show, description: 'Show a short link',
+                arguments: [{name: :short_link_id, type: :identifier}]
+              )
+              base.command(
+                :delete, description: 'Delete a short link',
+                arguments: [{name: :short_link_id, type: :identifier}]
+              )
+            end
+            base.define_action_method(parent_path + [:create]) do |custom_data: {}, **ctx|
+              sl_exec_create(custom_data, **ctx)
+            end
+            base.define_action_method(parent_path + [:list]) do |**ctx|
+              sl_exec_list(**sl_fetch_list(**ctx))
+            end
+            base.define_action_method(parent_path + [:show]) do |**ctx|
+              sl_exec_show(**sl_fetch_list(**ctx))
+            end
+            base.define_action_method(parent_path + [:delete]) do |**ctx|
+              sl_exec_delete(**sl_fetch_list(**ctx), **ctx)
+            end
+            base.define_action_method(parent_path + [:modify]) do |custom_data: {}, **ctx|
+              sl_exec_modify(custom_data, **sl_fetch_list(**ctx), **ctx)
+            end
+          end
         end
 
         # @param wizard  [Wizard] The wizard object
@@ -133,7 +198,7 @@ module Aspera
               test_args:    'organization'
             }
           end
-          options.declare(:use_generic_client, 'Wizard: AoC: use global or org specific jwt client id', allowed: Allowed::TYPES_BOOLEAN, default: Api::AoC.saas_url?(app_url))
+          options.declare(:use_generic_client, description: 'Wizard: AoC: use global or org specific jwt client id', allowed: Type::BOOLEAN, default: Api::AoC.saas_url?(app_url))
           options.parse_options!
           # make username mandatory for jwt, this triggers interactive input
           wiz_username = options.get_option(:username, mandatory: true)
@@ -201,19 +266,20 @@ module Aspera
           }
         end
 
+        option :workspace,         description: 'Name of workspace', allowed: [String, NilClass], default: Api::AoC::DEFAULT_WORKSPACE
+        option :new_user_option,   description: 'New user creation option for unknown package recipients', allowed: [Hash, NilClass]
+        option :validate_metadata, description: 'Validate shared inbox metadata', allowed: Type::BOOLEAN, default: true
+        option :package_folder,    schema: Schema::Registry::PACKAGE_FOLDER_OPTIONS
+
+        use_options Node
+
         def initialize(**_)
           super
           @cache_workspace_info = nil
           @cache_home_node_file = nil
           @cache_api_aoc = nil
           @scope = Api::AoC::Scope::USER
-          options.declare(:workspace, 'Name of workspace', allowed: [String, NilClass], default: Api::AoC::DEFAULT_WORKSPACE)
-          options.declare(:new_user_option, 'New user creation option for unknown package recipients', allowed: Hash)
-          options.declare(:validate_metadata, 'Validate shared inbox metadata', allowed: Allowed::TYPES_BOOLEAN, default: true)
-          options.declare(:package_folder, 'Handling of reception of packages in folders', allowed: Hash, default: {})
           options.parse_options!
-          # add node plugin options (for manual)
-          Node.declare_options(options)
         end
 
         # Change API scope for subsequent calls, re-instantiate API object
@@ -233,17 +299,17 @@ module Aspera
           api = Api::AoC.new(
             scope:         @scope,
             subpath:       base_path,
-            secret_finder: config,
+            secret_finder: context.secret_finder,
             **Oauth.kwargs_from_options(options)
           )
           # User set a workspace ?
           # @type [String, nil]
           workspace = options.get_option(:workspace)
-          if !workspace.nil? && (m = Manager.percent_selector(workspace))
+          if !workspace.nil? && (m = Parser.percent_selector(workspace))
             case m[:field]
             when 'name' then api.ws_ids[:name] = m[:value]
             when 'id' then api.ws_ids[:id] = m[:value]
-            else Aspera.error_unexpected_value(m[:field]){'workspace selector: only `name` or `id`'}
+            else Aspera.error_unexpected_value(m[:field]) { 'workspace selector: only `name` or `id`' }
             end
           else
             api.ws_ids[:name] = workspace
@@ -287,11 +353,11 @@ module Aspera
         end
 
         # Get resource identifier from command line, either directly specifying the `id` or from `name` (percent selector).
-        # @param resource_class_path url path for resource
-        # @return identifier
+        # @param resource_class_path [String] url path for resource
+        # @return [String] identifier
         def get_resource_id_from_args(resource_class_path)
           return options.instance_identifier do |field, value|
-            Aspera.assert_values(field, ['name'], type: BadArgument){'selector field'}
+            Aspera.assert_values(field, ['name'], type: BadArgument) { 'selector field' }
             aoc_api.lookup_with_q(resource_class_path, value: value)['id']
           end
         end
@@ -302,15 +368,17 @@ module Aspera
         end
 
         # List all entities, given additional, default and user's queries
-        # @param resource_class_path path to query on API
-        # @param fields fields to display
-        # @param base_query a query applied always
-        # @param default_query default query unless overridden by user
+        # @param resource_class_path [String]     path to query on API
+        # @param fields              [Array, nil] fields to display
+        # @param base_query          [Hash]       a query applied always
+        # @param default_query       [Hash]       default query unless overridden by user
+        # @param query_component     [String, nil] registry component key; when set, --query=help shows filter schema
         # @yieldparam query [Hash] The user's or default query for modification
-        def result_list(resource_class_path, fields: nil, base_query: {}, default_query: {})
+        def result_list(resource_class_path, fields: nil, base_query: {}, default_query: {}, query_component: nil)
           Aspera.assert_type(base_query, Hash)
           Aspera.assert_type(default_query, Hash)
-          query = query_read_delete(default: default_query)
+          qs_path = query_component ? Schema::Registry.query_params(query_component, resource_class_path) : nil
+          query = query_read_delete(default: default_query, schema: qs_path)
           # caller may add specific modifications or checks to query
           yield(query) if block_given?
           result = aoc_api.read_with_paging(resource_class_path, base_query.merge(query).compact)
@@ -321,7 +389,7 @@ module Aspera
         def resolve_dropbox_name_default_ws_id(query)
           if query.key?('dropbox_name')
             # convenience: specify name instead of id
-            raise BadArgument, 'Use field dropbox_name or dropbox_id, not both' if query.key?('dropbox_id')
+            Aspera.assert(!query.key?('dropbox_id'), type: BadArgument) { 'Use field dropbox_name or dropbox_id, not both' }
             # TODO : craft a query that looks for dropbox only in current workspace
             query['dropbox_id'] = aoc_api.lookup_with_q('dropboxes', value: query.delete('dropbox_name'))['id']
           end
@@ -330,25 +398,34 @@ module Aspera
           query['exclude_dropbox_packages'] = !query.key?('dropbox_id') unless query.key?('exclude_dropbox_packages')
         end
 
-        # List all packages according to `query` option.
-        # @param <none>
-        # @return [Hash] {items,total} with all packages according to combination of user's query and default query
+        # List all packages from the API using the current `--query` option.
+        # The special `max` key is extracted *before* the API call and returned separately,
+        # so callers that apply a post-API filter (e.g. once_only) can enforce the limit
+        # after filtering rather than before.
+        # @return [Array(Hash, Integer, nil)] [{items:,total:} paging result, max (or nil)]
         def list_all_packages_with_query
-          query = query_read_delete(default: {})
-          Aspera.assert_type(query, Hash){'query'}
-          PACKAGE_RECEIVED_BASE_QUERY.each{ |k, v| query[k] = v unless query.key?(k)}
+          query = query_read_delete(default: {}, schema: Schema::Registry.query_params(Schema::Registry::AOC, 'packages'))
+          Aspera.assert_type(query, Hash) { 'query' }
+          PACKAGE_RECEIVED_BASE_QUERY.each { |k, v| query[k] = v unless query.key?(k) }
           resolve_dropbox_name_default_ws_id(query)
-          return aoc_api.read_with_paging('packages', query.compact)
+          # Extract `max` before paging so callers can apply it after post-API filtering
+          max_items = query.delete(RestList::MAX_ITEMS)&.to_i
+          return aoc_api.read_with_paging('packages', query.compact), max_items
         end
 
         FILES_COMMANDS = (Node::COMMANDS_GEN4 + %i[transfer]).freeze
 
-        # Execute a node gen4 command starting at given node and file IDs
-        # @param command_repo [Symbol] Command to execute
-        # @param node_id [String] Node identifier
-        # @param file_id [String] Root file id for the operation (can be AK root, or other, e.g. package, or link). If `nil` use AK root file id.
-        # @param scope [String] node scope (Node::SCOPE_<USER|ADMIN>), or nil (requires secret)
-        def execute_nodegen4_command(command_repo, node_id, file_id: nil, scope: nil)
+        # Execute a node gen4 command starting at given node and file IDs.
+        # Arguments already resolved by the DSL (e.g. path:) are forwarded via +resolved_args+
+        # and injected into the dispatch context so node.rb does not re-consume them from the CLI.
+        # @param command_repo       [Symbol] Command to execute (from Node::COMMANDS_GEN4 or :transfer)
+        # @param node_id            [String] Node identifier
+        # @param file_id            [String, nil] Root file id; if nil, the AK root file id is used
+        # @param scope              [String, nil] node scope (Node::Scope::USER/ADMIN), or nil (requires secret)
+        # @param transfer_direction [Symbol, nil] :push or :pull (only for command_repo == :transfer)
+        # @param transfer_source    [String, nil] source folder  (only for command_repo == :transfer)
+        # @param resolved_args      [Hash] already-resolved CLI arguments (e.g. path:) forwarded to dispatch
+        def execute_nodegen4_command(command_repo, node_id, file_id: nil, scope: nil, transfer_direction: nil, transfer_source: nil, **resolved_args)
           top_node_api = aoc_api.node_api_from(
             node_id:        node_id,
             scope:          scope,
@@ -358,13 +435,16 @@ module Aspera
           node_plugin = Node.new(context: context, api: top_node_api)
           case command_repo
           when *Node::COMMANDS_GEN4
-            return node_plugin.execute_command_gen4(command_repo, file_id)
+            # For permission: the handler consumes the path first then re-dispatches to sub-commands.
+            # Calling dispatch_from_registry with skip_setup would bypass path consumption and fail.
+            return node_plugin.send(:"action_access_keys_do_#{command_repo}", do_root_file_id: file_id, **resolved_args) if command_repo.eql?(:permission)
+            return node_plugin.dispatch_from_registry([:access_keys, :do, command_repo], {do_root_file_id: file_id, **resolved_args}, skip_setup: true)
           when :transfer
             # client side is agent
             # server side is transfer server
             # in same workspace
-            push_pull = options.get_next_argument('direction', accept_list: %i[push pull])
-            source_folder = options.get_next_argument('folder or source files', validation: String)
+            push_pull = transfer_direction
+            source_folder = transfer_source
             case push_pull
             when :push
               client_direction = Transfer::Spec::DIRECTION_SEND
@@ -396,592 +476,94 @@ module Aspera
               client_direction,
               add_ts
             )))
-          else Aspera.error_unexpected_value(command_repo){'command'}
+          else Aspera.error_unexpected_value(command_repo) { 'command' }
           end
           Aspera.error_unreachable_line
         end
 
         # Execute an action on admin resources
         # @param resource_type [Symbol] One of ADMIN_OBJECTS
-        def execute_resource_action(resource_type)
-          # Set to `true` is resource creation requires a workspace id
-          require_workspace_id = false
-          # Default fields to display
-          list_default_fields = %w[id name]
-          # Default query for `list` action
-          list_default_query = {}
-          # In result of create, what is the field that contains the id of the created resource
-          id_result = 'id'
-          supported_operations = Operations::ALL
-          # API path
-          resource_class_path = "#{resource_type}s"
-          resource_class_path = resource_class_path.gsub(/ys$/, 'ies')
-          # path in openapi where post is located to get creation schema
-          create_schema_path = resource_class_path
-          case resource_type
-          when :client
-            supported_operations += %i[set_pub_key]
-            # schema_create_modify = Schema::Registry.req_body(Schema::Registry::AOC, "#{resource_class_path}.post")
-          when :client_access_key
-            resource_class_path = "admin/#{resource_type}s"
-          when :client_registration_token
-            resource_class_path = "admin/#{resource_type}s"
-            list_default_fields = %w[id value data.client_subject_scopes data.name created_at]
-            id_result = 'token'
-          when :contact
-            list_default_fields = %w[source_type source_id name email]
-            # list_default_query = {'include_only_user_personal_contacts' => true} if @scope == Api::AoC::Scope::USER
-          when :configuration_policy, :network_policy
-            list_default_fields = nil
-          when :dropbox
-            require_workspace_id = true
-            resource_class_path = "#{resource_type}es"
-            create_schema_path = resource_class_path
-          when :group, :saml_configuration
-            create_schema_path = nil
-          when :group_membership
-            list_default_fields = %w[id group_id member_type member_id]
-            create_schema_path = nil
-          when :kms_profile
-            resource_class_path = "integrations/#{resource_type}s"
-            create_schema_path = nil
-          when :node
-            list_default_fields = %w[id name host access_key]
-            supported_operations += %i[do bearer_token]
-          when :operation
-            list_default_fields = %w[id type status created_at updated_at workspace_id user_id workspace_membership_id group_membership_id]
-            supported_operations = %i[list show modify]
-          when :organization, :self
-            supported_operations = Operations::SINGLETON
-            resource_instance_path = resource_class_path = resource_type
-          when :short_link
-            list_default_fields = %w[id short_url data.url_token_data.purpose password_enabled password_protected updated_by_user_id updated_at]
-          when :user
-            list_default_fields = %w[id name email]
-            supported_operations += %i[preferences notifications]
-          when :workspace
-            supported_operations += %i[shared_folder dropbox]
-          when :workspace_membership
-            list_default_fields = %w[id workspace_id member_type member_id]
-          end
-          # Default location of creation payload in schema
-          schema_create_modify = Schema::Registry.req_body(Schema::Registry::AOC, "#{create_schema_path}.post") if create_schema_path && supported_operations.include?(:create)
-          command = options.get_next_command(supported_operations)
-          # Require identifier for non global commands
-          if (supported_operations != Operations::SINGLETON) && !Operations::GLOBAL.include?(command)
-            res_id = get_resource_id_from_args(resource_class_path)
-            resource_instance_path = "#{resource_class_path}/#{res_id}"
-          end
-          case command
-          when :create
-            # TODO: report inconsistency: creation url is !=, and does not return id.
-            resource_class_path = 'admin/client_registration/token' if resource_class_path.eql?('admin/client_registration_tokens')
-            workspace_id = aoc_api.workspace_info[:id] if require_workspace_id
-            return do_bulk_operation(command: command, descr: 'creation data', id_result: id_result, schema: schema_create_modify) do |params|
-              params['workspace_id'] = workspace_id if require_workspace_id && workspace_id && !params.key?('workspace_id')
-              aoc_api.create(resource_class_path, params)
-            end
-          when :list
-            return result_list(resource_class_path, fields: list_default_fields, default_query: list_default_query)
-          when :show
-            object = aoc_api.read(resource_instance_path, query_read_delete)
-            return Result::SingleObject.new(object, fields: Formatter.all_but('certificate'))
-          when :modify
-            changes = options.get_next_argument('properties', validation: Hash, schema: schema_create_modify)
-            return do_bulk_operation(command: command, values: res_id) do |one_id|
-              aoc_api.update("#{resource_class_path}/#{one_id}", changes)
-              {'id' => one_id}
-            end
-          when :delete
-            return do_bulk_operation(command: command, values: res_id) do |one_id|
-              aoc_api.delete("#{resource_class_path}/#{one_id}")
-              {'id' => one_id}
-            end
-          when :set_pub_key
-            # special : reads private and generate public
-            the_private_key = options.get_next_argument('private_key PEM value', validation: String)
-            the_public_key = OpenSSL::PKey::RSA.new(the_private_key).public_key.to_s
-            aoc_api.update(resource_instance_path, {jwt_grant_enabled: true, public_key: the_public_key})
-            return Result::Success.new
-          when :do
-            command_repo = options.get_next_command(FILES_COMMANDS)
-            return execute_nodegen4_command(command_repo, res_id, scope: Api::Node::Scope::ADMIN)
-          when :bearer_token
-            node_api = aoc_api.node_api_from(
-              node_id: res_id,
-              scope:   options.get_next_argument('scope', default: Api::Node::Scope::ADMIN)
-            )
-            return Result::Text.new(node_api.oauth.authorization)
-          when :dropbox
-            command_shared = options.get_next_command(%i[list])
-            case command_shared
-            when :list
-              query = options.get_option(:query) || {}
-              res_data = aoc_api.read('dropboxes', query.merge({'workspace_id'=>res_id}))
-              return Result::ObjectList.new(res_data, fields: %w[id name description])
-            end
-          when :shared_folder
-            query = options.get_option(:query) || Api::AoC.workspace_access(res_id).merge({'admin' => true})
-            shared_folders = aoc_api.read_with_paging("#{resource_instance_path}/permissions", query)[:items]
-            # inside a workspace
-            command_shared = options.get_next_command(%i[list node member])
-            case command_shared
-            when :list
-              return Result::ObjectList.new(shared_folders, fields: %w[id node_name node_id file_id file.path tags.aspera.files.workspace.share_as])
-            when :node
-              shared_folder_id = options.instance_identifier(description: 'Shared folder ID')
-              shared_folder = shared_folders.find{ |i| i['id'].eql?(shared_folder_id)}
-              Aspera.assert(shared_folder, 'shared folder not found')
-              command_repo = options.get_next_command(FILES_COMMANDS)
-              return execute_nodegen4_command(command_repo, shared_folder['node_id'], file_id: shared_folder['file_id'], scope: Api::Node::Scope::ADMIN)
-            when :member
-              shared_folder_id = options.instance_identifier(description: 'Shared folder ID')
-              shared_folder = shared_folders.find{ |i| i['id'].eql?(shared_folder_id)}
-              Aspera.assert(shared_folder, 'shared folder not found')
-              command_shared_member = options.get_next_command(%i[list])
-              case command_shared_member
-              when :list
-                node_api = aoc_api.node_api_from(
-                  node_id: shared_folder['node_id'],
-                  workspace_id: res_id,
-                  workspace_name: nil,
-                  scope: Api::Node::Scope::USER
-                )
-                result = node_api.read(
-                  'permissions',
-                  {'file_id' => shared_folder['file_id'], 'tag' => "aspera.files.workspace.id=#{res_id}"}
-                )
-                result.each do |item|
-                  item['member'] = begin
-                    if Api::AoC.workspace_access?(item)
-                      {'name'=>'[Internal permission]'}
-                    else
-                      aoc_api.read("admin/#{item['access_type']}s/#{item['access_id']}") rescue {'name': 'not found'}
-                    end
-                  rescue => e
-                    {'name'=>e.to_s}
-                  end
-                end
-                # TODO : read users and group name and add, if query "include_members"
-                return Result::ObjectList.new(result, fields: %w[access_type access_id access_level last_updated_at member.name member.email member.system_group_type member.system_group])
-              end
-            end
-          when :preferences, :notifications
-            user_preferences_res = "#{resource_instance_path}/#{command.eql?(:preferences) ? 'user_interaction_preferences' : 'notification_preferences'}"
-            case options.get_next_command(%i[show modify])
-            when :show
-              return Result::SingleObject.new(aoc_api.read(user_preferences_res))
-            when :modify
-              aoc_api.update(user_preferences_res, options.get_next_argument('properties', validation: Hash))
-              return Result::Status.new('modified')
-            end
-          else Aspera.error_unexpected_value(command)
-          end
-        end
-
-        def execute_application_action
-          apps_info = aoc_api.read('admin/apps')
-          # List of allowed symbols for app type
-          all_app_syms = apps_info.map{ |i| i['app_type'].to_sym}
-          command_apps = options.get_next_command(%i[types settings instance membership])
-          case command_apps
-          when :types
-            return Result::ObjectList.new(apps_info)
-          when :settings
-            app_type = options.get_next_command(all_app_syms)
-            cmd_path = "/apps/#{app_type}/settings"
-            command_app_settings = options.get_next_command(Operations::SINGLETON)
-            case command_app_settings
-            when :show
-              return Result::SingleObject.new(aoc_api.read(cmd_path))
-            when :modify
-              aoc_api.update(cmd_path, options.get_next_argument('properties', validation: Hash))
-              return Result::Status.new('modified')
-            end
-          when :instance
-            list_default_query = {workspace_id: aoc_api.workspace_info[:id]}
-            list_default_fields = %w[id app_type available workspace_id]
-            command_app_instances = options.get_next_command(%i[list] + Operations::SINGLETON)
-            resource_path = 'admin/apps_new'
-            if Operations::SINGLETON.include?(command_app_instances)
-              app_type = options.get_next_command(all_app_syms)
-              resource_path = "#{resource_path}/#{app_type}/#{options.instance_identifier(description: "#{app_type} identifier")}"
-            end
-            case command_app_instances
-            when :list
-              return result_list(resource_path, fields: list_default_fields, default_query: list_default_query)
-            when :show
-              return Result::SingleObject.new(aoc_api.read(resource_path, query_read_delete))
-            when :modify
-              aoc_api.update(resource_path, options.get_next_argument('properties', validation: Hash))
-              return Result::Status.new('modified')
-            end
-          when :membership
-            resource_path = 'apps/app_memberships'
-            command_app_member = options.get_next_command(%i[create list show delete])
-            resource_path = "#{resource_path}/#{options.instance_identifier(description: 'membership id')}" unless Operations::GLOBAL.include?(command_app_member)
-            case command_app_member
-            when :list
-              return result_list(resource_path)
-            when :delete
-              aoc_api.delete(resource_path)
-              return Result::Status.new('deleted')
-            when :show
-              return Result::SingleObject.new(aoc_api.read(resource_path, query_read_delete))
-            when :create
-              data = options.get_next_argument('membership properties', validation: Hash)
-              app_type = data.delete('app_type')
-              Aspera.assert_type(app_type, String){'app_type'}
-              Aspera.assert_values(app_type.to_sym, all_app_syms){'app_type'}
-              return Result::SingleObject.new(aoc_api.create("apps/#{app_type}/app_memberships", data))
-            end
-          end
-        end
+        # Per-resource configuration for admin CRUD resources.
+        # Keys: path, list_fields, id_result, require_ws_id, create_schema, extra_ops, singleton, op_setup
+        # op_setup: Hash of op => setup method name, used for ops that require consuming an instance identifier.
+        #   For Operations::INSTANCE ops (show/modify/delete), use the auto-generated :setup_admin_<res>_instance.
+        #   For extra_ops that are instance ops, specify explicitly (or rely on the auto-generated one).
+        ADMIN_OBJECT_CONFIG = {
+          client:                    {extra_ops: %i[set_pub_key], extra_op_args: {set_pub_key: [{name: :private_key_pem, type: String}]}},
+          client_access_key:         {path: 'admin/client_access_keys'},
+          client_registration_token: {path: 'admin/client_registration_tokens', list_fields: %w[id value data.client_subject_scopes data.name created_at], id_result: 'token'},
+          configuration_policy:      {list_fields: nil},
+          contact:                   {list_fields: %w[source_type source_id name email]},
+          dropbox:                   {path: 'dropboxes', require_ws_id: true},
+          dropbox_membership:        {},
+          group:                     {create_schema: false},
+          group_membership:          {list_fields: %w[id group_id member_type member_id], create_schema: false},
+          kms_profile:               {path: 'integrations/kms_profiles', create_schema: false},
+          network_policy:            {list_fields: nil},
+          node:                      {list_fields: %w[id name host access_key], extra_ops: %i[do bearer_token], extra_op_args: {bearer_token: [{name: :scope, mandatory: false, default: nil}]}},
+          operation:                 {list_fields: %w[id type status created_at updated_at workspace_id user_id workspace_membership_id group_membership_id], ops: %i[list show modify]},
+          organization:              {singleton: true},
+          package:                   {},
+          saml_configuration:        {create_schema: false},
+          self:                      {singleton: true},
+          short_link:                {list_fields: %w[id short_url data.url_token_data.purpose password_enabled password_protected updated_by_user_id updated_at]},
+          user:                      {list_fields: %w[id name email], extra_ops: %i[preferences notifications], op_setup: {preferences: :setup_admin_user_instance, notifications: :setup_admin_user_instance}},
+          workspace:                 {extra_ops: %i[shared_folder dropbox], op_setup: {shared_folder: :setup_admin_workspace_shared_folder, dropbox: :setup_admin_workspace_dropbox}},
+          workspace_membership:      {list_fields: %w[id workspace_id member_type member_id]}
+        }.freeze
+        private_constant :ADMIN_OBJECT_CONFIG
 
-        ADMIN_ACTIONS = %i[bearer_token application ats usage_reports analytics subscription auth_providers].concat(ADMIN_OBJECTS).freeze
+        # Instance delegators so instance methods can call aoc_res_path/aoc_res_cfg without self.class.
+        def aoc_res_path(res) = self.class.aoc_res_path(res)
+        def aoc_res_cfg(res)  = self.class.aoc_res_cfg(res)
 
-        def execute_admin_action
-          # change scope to admin
-          change_api_scope(Api::AoC::Scope::ADMIN)
-          command_admin = options.get_next_command(ADMIN_ACTIONS)
-          case command_admin
-          when :bearer_token
-            return Result::Text.new(aoc_api.oauth.authorization)
-          when *ADMIN_OBJECTS
-            return execute_resource_action(command_admin)
-          when :application
-            return execute_application_action
-          when :auth_providers
-            command_auth_prov = options.get_next_command(%i[list update])
-            case command_auth_prov
-            when :list
-              return result_list('admin/auth_providers')
-            when :update
-              Aspera.error_not_implemented
-            end
-          when :subscription
-            org = aoc_api.read('organization')
-            bss_graphql = api_from_options('bss/platform/graphql')
-            command_subscription = options.get_next_command(%i[account usage])
-            case command_subscription
-            when :account
-              # cspell:disable
-              graphql_query = <<-GRAPHQL
-              query ($organization_id: ID!) {
-                aoc (organization_id: $organization_id) {
-                  bssSubscription {
-                    aocVersion
-                    endDate
-                    startDate
-                    termMonths
-                    plan
-                    trial
-                    termType
-                    aocOrganizations {
-                      id
-                    }
-                    additionalStorageVolumeGb
-                    additionalEgressVolumeGb
-                    term {
-                      startDate
-                      endDate
-                      transferVolumeGb
-                      egressVolumeGb
-                      storageVolumeGb
-                      transferVolumeOffsetGb
-                    }
-                    paygoRate {
-                      transferRate
-                      storageRate
-                      currency
-                    }
-                    aocPlanData {
-                      tier
-                      trial
-                      workspaces { max }
-                      users {
-                        planAmount
-                        max
-                      }
-                      samlIntegration
-                      activity
-                      sharedInboxes
-                      uniqueUrls
-                      support
-                      watermarking
-                      byok
-                      automation { planAmount, max }
-                    }
-                  }
-                }
-              }
-              GRAPHQL
-              # cspell:enable
-              result = bss_graphql.create(nil, {query: graphql_query, variables: {organization_id: org['id']}})['data']
-              return Result::SingleObject.new(result['aoc']['bssSubscription'])
-            when :usage
-              # cspell:disable
-              graphql_query = <<-GRAPHQL
-              query ($organization_id: ID!, $startDate: Date!, $endDate: Date!, $aggregate: TransferUsageAggregateOption!) {
-                aoc (organization_id: $organization_id) {
-                  bssSubscription {
-                    aocOrganizations { id }
-                    additionalStorageVolumeGb
-                    additionalEgressVolumeGb
-                    aocPlanData {
-                      tier
-                      trial
-                    }
-                    term {
-                      transferVolumeGb
-                      egressVolumeGb
-                      storageVolumeGb
-                      startDate
-                      endDate
-                      transferVolumeOffsetGb
-                    }
-                    termMonths
-                    transferUsages (startDate: $startDate, endDate: $endDate, aggregate: $aggregate) { mbTotal }
-                    egressUsages (startDate: $startDate, endDate: $endDate, aggregate: $aggregate) { usageMb }
-                  }
-                  subscriptionEntitlements {
-                    id
-                    transferUsages (startDate: $startDate, endDate: $endDate, aggregate: $aggregate) { mbTotal }
-                    egressUsages (startDate: $startDate, endDate: $endDate, aggregate: $aggregate) { usageMb }
-                  }
-                }
-              }
-              GRAPHQL
-              aggregate = options.get_next_argument('aggregation', accept_list: %i[ALL MONTHLY], default: :ALL)
-              today = Date.today
-              start_date = options.get_next_argument('start date', mandatory: false, default: today.prev_year.strftime('%Y-%m-%d'))
-              end_date = options.get_next_argument('end date', mandatory: false, default: today.strftime('%Y-%m-%d'))
-              # cspell:enable
-              result = bss_graphql.create(
-                nil,
-                {
-                  query:     graphql_query,
-                  variables: {
-                    organization_id: org['id'],
-                    aggregate:       aggregate,
-                    startDate:       start_date,
-                    endDate:         end_date
-                  }
-                }
-              )['data']
-              return Result::SingleObject.new(result['aoc'])
-            end
-          when :ats
-            ats_api = Rest.new(**aoc_api.params.deep_merge({
-              base_url: "#{aoc_api.base_url}/admin/ats/pub/v1",
-              auth:     {params: {scope: Api::AoC::Scope::ADMIN_USER}}
-            }))
-            return Ats.new(context: context, api: ats_api).execute_action
-          when :analytics
-            analytics_api = Rest.new(**aoc_api.params.deep_merge({
-              base_url: "#{aoc_api.base_url.gsub('/api/v1', '')}/analytics/v2",
-              auth:     {params: {scope: Api::AoC::Scope::ADMIN_USER}}
-            }))
-            command_analytics = options.get_next_command(%i[application_events transfers files])
-            case command_analytics
-            when :application_events
-              event_type = command_analytics.to_s
-              events = analytics_api.read("organizations/#{aoc_api.current_user_info['organization_id']}/#{event_type}")[event_type]
-              return Result::ObjectList.new(events)
-            when :transfers
-              event_type = command_analytics.to_s
-              event_resource_type = options.get_next_argument('resource', accept_list: %i[organizations users nodes])
-              event_resource_id = options.get_next_argument("#{event_resource_type} identifier", mandatory: false) ||
-                case event_resource_type
-                when :organizations then aoc_api.current_user_info['organization_id']
-                when :users then aoc_api.current_user_info['id']
-                when :nodes then aoc_api.current_user_info['read_only_home_node_id']
-                else Aspera.error_unreachable_line
-                end
-              filter = query_read_delete(default: {})
-              filter['limit'] ||= 100
-              if options.get_option(:once_only, mandatory: true)
-                saved_date = []
-                start_date_persistency = PersistencyActionOnce.new(
-                  manager: persistency,
-                  data: saved_date,
-                  id: IdGenerator.from_list(
-                    'aoc_ana_date',
-                    options.get_option(:url, mandatory: true),
-                    aoc_api.workspace_info[:name],
-                    event_resource_type.to_s,
-                    event_resource_id
-                  )
-                )
-                start_date_time = saved_date.first
-                stop_date_time = Time.now.utc.strftime('%FT%T.%LZ')
-                saved_date[0] = stop_date_time
-                filter['start_time'] = start_date_time unless start_date_time.nil?
-                filter['stop_time'] = stop_date_time
-              end
-              events = analytics_api.read("#{event_resource_type}/#{event_resource_id}/#{event_type}", filter)[event_type]
-              start_date_persistency&.save
-              if !options.get_option(:notify_to).nil?
-                events.each do |tr_event|
-                  config.send_email_template(values: {ev: tr_event})
-                end
-              end
-              return Result::ObjectList.new(events)
-            when :files
-              event_type = command_analytics.to_s
-              event_resource_type = options.get_next_argument('resource', accept_list: %i[organizations users nodes])
-              event_resource_id = options.instance_identifier(description: "#{event_resource_type} identifier")
-              event_resource_id =
-                case event_resource_type
-                when :organizations then aoc_api.current_user_info['organization_id']
-                when :users then aoc_api.current_user_info['id']
-                when :nodes then aoc_api.current_user_info['read_only_home_node_id']
-                else Aspera.error_unreachable_line
-                end if event_resource_id.empty?
-              event_uuid = options.instance_identifier(description: 'event uuid')
-              filter = query_read_delete(default: {})
-              filter['limit'] ||= 100
-              events = analytics_api.read("#{event_resource_type}/#{event_resource_id}/transfers/#{event_uuid}/#{event_type}", filter)[event_type]
-              return Result::ObjectList.new(events)
-            end
-          when :usage_reports
-            return result_list('usage_reports', base_query: workspace_id_hash)
-          end
-        end
-
-        # Create a short link for the given entity: Shared folder or Shared Inbox
-        # Short link entity: `short_links` have:
-        # - a numerical id, e.g. `764412`
-        # - a resource type, e.g. `UrlToken`
-        # - a resource id, e.g. `scQ7uXPbvQ`
-        # - a short URL path, e.g. `dxyRpT9`
-        # @param shared_data [Hash] Information for shared data: dropbox_id+name or file_id+node_id
-        # @param shared_data [Hash] Shared data for the short link
-        # @yieldparam operation [Symbol] Operation type (:create, :update, :delete)
-        # @yieldparam resource_id [String] Resource ID for permission management
-        # @yieldparam access_levels [Object] Access levels for permissions
-        def short_link_command(**shared_data, &perm_block)
-          link_type = options.get_next_argument('link access (public or private)', accept_list: %i[public private])
+        # Known fixed set of AoC application types (verified against API: activity, automation, files, packages)
+        APP_TYPES = %i[activity automation files packages].freeze
+
+        ADMIN_ACTIONS = (%i[bearer_token application ats usage_reports analytics subscription auth_providers] + ADMIN_OBJECTS).freeze
+
+        # Build analytics REST API (shared by action_admin_analytics_*)
+        def build_analytics_api
+          Rest.new(**aoc_api.params.deep_merge({
+            base_url: "#{aoc_api.base_url.gsub('/api/v1', '')}/analytics/v2",
+            auth:     {params: {scope: Api::AoC::Scope::ADMIN_USER}}
+          }))
+        end
+
+        # Compute short-link purposes from shared_data keys and link_type.
+        # @param shared_data [Hash] :dropbox_id+:name or :file_id+:node_id
+        # @param link_type [Symbol] :public or :private
+        # @return [Array(String,String)] [token_purpose, short_link_purpose]
+        def short_link_purposes(shared_data, link_type)
           if shared_data.keys.sort == %i[dropbox_id name]
-            # Packages app, Shared inbox
             token_purpose = 'send_package_to_dropbox'
             short_link_purpose = link_type.eql?(:public) ? 'send_package_to_dropbox' : 'shared_folder_auth_link'
           elsif shared_data.keys.sort == %i[file_id node_id]
-            # Files app, Shared folder
             token_purpose = 'view_shared_file'
             short_link_purpose = link_type.eql?(:public) ? 'token_auth_redirection' : 'shared_folder_auth_link'
           else
             Aspera.error_unexpected_value(shared_data.keys)
           end
-          command = options.get_next_command(%i[create delete list show] + (link_type.eql?(:public) ? %i[modify] : []))
-          case command
-          when :create
-            # Add workspace id
-            workspace_id_hash(shared_data)
-            create_payload = {
-              purpose:            short_link_purpose,
-              user_selected_name: nil
-            }
-            case link_type
-            when :private
-              create_payload[:data] = shared_data
-            when :public
-              create_payload[:expires_at]       = nil
-              create_payload[:password_enabled] = false
-              shared_data[:name] = ''
-              create_payload[:data] = {
-                aoc:            true,
-                url_token_data: {
-                  data:    shared_data,
-                  purpose: token_purpose
-                }
-              }
-            end
-            custom_data = value_create_modify(command: command, default: {})
-            access_levels = custom_data.delete('access_levels')
-            if (pass = custom_data.delete('password'))
-              create_payload[:data][:url_token_data][:password] = pass
-              create_payload[:password_enabled] = true
-            end
-            create_payload.deep_merge!(custom_data)
-            result_create_short_link = aoc_api.create('short_links', create_payload)
-            # Creation: perm_block: permission on node
-            yield(:create, result_create_short_link['resource_id'], access_levels) if block_given? && link_type.eql?(:public)
-            return Result::SingleObject.new(result_create_short_link)
-          when :delete, :list, :show, :modify
-            workspace_id_hash(shared_data)
-            query = if link_type.eql?(:private)
-              shared_data
-            else
-              {
-                url_token_data: {
-                  data:    shared_data,
-                  purpose: token_purpose
-                }
-              }
-            end
-            list_params = {
-              json_query:  query.to_json,
-              purpose:     short_link_purpose,
-              edit_access: true,
-              # embed: 'updated_by_user',
-              sort:        '-created_at'
-            }
-            short_list = aoc_api.read_with_paging('short_links', list_params.merge(query_read_delete(default: {})).compact)
-            case command
-            when :delete
-              one_id = options.instance_identifier(description: 'short link id')
-              if link_type.eql?(:public)
-                found = short_list[:items].find{ |item| item['id'].eql?(one_id)}
-                raise BadIdentifier.new('Short link', one_id) if found.nil?
-                yield(:delete, found['resource_id'], nil)
-              end
-              aoc_api.delete("short_links/#{one_id}", {
-                edit_access: true,
-                json_query:  shared_data.to_json
-              })
-              return Result::Status.new('deleted')
-            when :list
-              return Result::ObjectList.new(short_list[:items], fields: Formatter.all_but('data'), total: short_list[:total])
-            when :show
-              one_id = options.instance_identifier(description: 'short link id')
-              found = short_list[:items].find{ |item| item['id'].eql?(one_id)}
-              raise BadIdentifier.new('Short link', one_id) if found.nil?
-              return Result::SingleObject.new(found, fields: Formatter.all_but('data'))
-            when :modify
-              one_id = options.instance_identifier(description: 'short link id')
-              node_file = shared_data.slice(:node_id, :file_id)
-              modify_payload = {
-                edit_access: true,
-                json_query:  node_file
-              }
-              custom_data = value_create_modify(command: command)
-              if (pass = custom_data.delete('password'))
-                modify_payload[:password_enabled] = true
-                modify_payload[:data] = {
-                  url_token_data: {
-                    password: pass,
-                    data:     node_file
-                  }
-                }
-              else
-                modify_payload[:password_enabled] = false
-              end
-              if custom_data.delete('access_levels')
-                # Modification: perm_block: permission on node
-                found = short_list[:items].find{ |item| item['id'].eql?(one_id)}
-                raise BadIdentifier.new('Short link', one_id) if found.nil?
-                yield(:update, found['resource_id'], access_levels)
-              end
-              modify_payload.deep_merge!(custom_data)
-              aoc_api.update("short_links/#{one_id}", modify_payload)
-              return Result::Status.new('modified')
-            end
-          else Aspera.error_unexpected_value(command)
+          [token_purpose, short_link_purpose]
+        end
+
+        # Build the list_params hash used by delete/list/show/modify short link operations.
+        # @return [Hash]
+        def short_link_list_params(shared_data:, link_type:, token_purpose:, short_link_purpose:, **)
+          query = if link_type.eql?(:private)
+            shared_data
+          else
+            {url_token_data: {data: shared_data, purpose: token_purpose}}
           end
+          {
+            json_query:  query.to_json,
+            purpose:     short_link_purpose,
+            edit_access: true,
+            sort:        '-created_at'
+          }
         end
 
-        # @return persistency object if option `once_only` is used.
+        # @return [PersistencyActionOnce, nil] persistency object if option `once_only` is used.
         def package_persistency
           return unless options.get_option(:once_only, mandatory: true)
           # TODO: add query info to id
@@ -999,294 +581,1009 @@ module Aspera
 
         def reject_packages_from_persistency(all_packages, skip_ids_persistency)
           return if skip_ids_persistency.nil?
-          skip_package = skip_ids_persistency.data.to_h{ |i| [i, true]}
-          all_packages.reject!{ |pkg| skip_package[pkg['id']]}
+          skip_package = skip_ids_persistency.data.to_h { |i| [i, true] }
+          all_packages.reject! { |pkg| skip_package[pkg['id']] }
         end
 
-        # must be public
-        ACTIONS = %i[reminder servers bearer_token organization tier_restrictions user packages files admin automation gateway].freeze
+        # --- DSL command declarations ---
 
-        def execute_action
-          command = options.get_next_command(ACTIONS)
-          if %i[files packages].include?(command)
-            formatter.display_status("Workspace: #{aoc_api.workspace_info[:name].to_s.red}#{' (default)' if aoc_api.default_workspace?}")
-            if !aoc_api.private_link.nil?
-              folder_name = aoc_api.node_api_from(node_id: aoc_api.home[:node_id]).read("files/#{aoc_api.home[:file_id]}")['name']
-              formatter.display_status("Private Folder: #{folder_name}")
-            end
-          end
-          case command
-          when :reminder
-            # send an email reminder with list of orgs
-            user_email = options.get_option(:username, mandatory: true)
+        # Root-level commands
+        command :reminder, description: 'Send reminder email with list of orgs'
+        command(
+          :servers, description: 'List AoC servers (no auth)',
+          action: lambda do
             no_auth_api = Api::AoC.new(url: options.get_option(:url), auth: :none)
-            no_auth_api.create('organization_reminders', {email: user_email})
-            return Result::Status.new("List of organizations user is member of, has been sent by e-mail to #{user_email}")
-          when :servers
-            no_auth_api = Api::AoC.new(url: options.get_option(:url), auth: :none)
-            return Result::ObjectList.new(no_auth_api.read('servers'))
-          when :bearer_token
-            return Result::Text.new(aoc_api.oauth.authorization)
-          when :organization
-            return Result::SingleObject.new(aoc_api.read('organization'))
-          when :tier_restrictions
-            return Result::SingleObject.new(aoc_api.read('tier_restrictions'))
-          when :user
-            user_cmd = options.get_next_command(%i[workspaces profile preferences notifications contacts settings])
-            case user_cmd
-            when :contacts
-              return execute_resource_action(:contact)
-            when :settings
-              return entity_execute(api: aoc_api, entity: 'client_settings')
-            when :workspaces
-              case options.get_next_command(%i[list current])
-              when :list
-                return result_list('workspaces', fields: %w[id name])
-              when :current
-                return Result::SingleObject.new(aoc_api.workspace_info)
-              end
-            when :profile
-              case options.get_next_command(%i[show modify])
-              when :show
-                return Result::SingleObject.new(aoc_api.current_user_info(exception: true))
-              when :modify
-                aoc_api.update("users/#{aoc_api.current_user_info(exception: true)['id']}", options.get_next_argument('properties', validation: Hash))
-                return Result::Status.new('modified')
-              end
-            when :preferences, :notifications
-              user_preferences_res = "users/#{aoc_api.current_user_info(exception: true)['id']}/#{user_cmd.eql?(:preferences) ? 'user_interaction_preferences' : 'notification_preferences'}"
-              case options.get_next_command(%i[show modify])
-              when :show
-                return Result::SingleObject.new(aoc_api.read(user_preferences_res))
-              when :modify
-                aoc_api.update(user_preferences_res, options.get_next_argument('properties', validation: Hash))
-                return Result::Status.new('modified')
-              end
+            Result::ObjectList.new(no_auth_api.read('servers'))
+          end
+        )
+        command :bearer_token,      description: 'Display bearer token',
+          action: -> { Result::Text.new(aoc_api.oauth.authorization) }
+        command :organization,      description: 'Show organization info',
+          action: -> { Result::SingleObject.new(aoc_api.read('organization')) }
+        command :tier_restrictions, description: 'Show tier restrictions',
+          action: -> { Result::SingleObject.new(aoc_api.read('tier_restrictions')) }
+        command :user,              description: 'User commands'
+        command :packages,          description: 'Package commands', setup: :setup_workspace_display
+        command :files,             description: 'Files commands (workspace-aware)', setup: :setup_workspace_display
+        command :admin, description: 'Administration commands', setup: :setup_admin_scope
+        commands_under :admin do
+          command :bearer_token,   description: 'Show admin bearer token',
+            action: -> { Result::Text.new(aoc_api.oauth.authorization) }
+          command :application,    description: 'Manage applications'
+          command :ats, description: 'Manage ATS (Aspera Transfer Service)',
+            delegate_instance: :build_ats_plugin, delegates_to: []
+          command :usage_reports,  description: 'List usage reports',
+            action: -> { result_list('usage_reports', base_query: workspace_id_hash) }
+          command :auth_providers, description: 'Manage auth providers'
+          command :subscription,   description: 'Show subscription info'
+          command :analytics,      description: 'Query analytics'
+          ADMIN_OBJECTS.each do |res|
+            cfg            = ADMIN_OBJECT_CONFIG.fetch(res, {})
+            op_setup       = cfg[:op_setup] || {}
+            extra_op_args  = cfg[:extra_op_args] || {}
+            is_singleton   = cfg[:singleton]
+            id_arg_spec    = is_singleton ? [] : [{name: :"#{res}_id", type: :identifier, lookup: :"lookup_aoc_#{res}_id"}]
+            ops            = if cfg[:ops]
+              cfg[:ops]
+            elsif is_singleton
+              %i[show]
+            else
+              Operations::ALL + (cfg[:extra_ops] || [])
             end
-          when :packages
-            package_command = options.get_next_command(%i[shared_inboxes send receive list show delete modify].concat(Node::NODE4_READ_ACTIONS), aliases: {recv: :receive})
-            case package_command
-            when :shared_inboxes
-              case options.get_next_command(%i[list show short_link])
-              when :list
-                default_query = {'embed[]' => 'dropbox', 'aggregate_permissions_by_dropbox' => true, 'sort' => 'dropbox_name'}
-                workspace_id_hash(default_query, string: true)
-                return result_list('dropbox_memberships', fields: %w[dropbox_id dropbox.name], default_query: default_query)
-              when :show
-                return Result::SingleObject.new(aoc_api.read(get_resource_path_from_args('dropboxes')))
-              when :short_link
-                # TODO: check name
-                return short_link_command(dropbox_id: get_resource_id_from_args('dropboxes'), name: '')
-              end
-            when :send
-              package_data = value_create_modify(command: package_command, schema: Schema::Registry.req_body(Schema::Registry::AOC, 'packages.post'))
-              new_user_option = options.get_option(:new_user_option)
-              option_validate = options.get_option(:validate_metadata)
-              # Works for both normal user auth and link auth.
-              workspace_id_hash(package_data, string: true) unless package_data.key?('workspace_id')
-              if !aoc_api.public_link.nil?
-                aoc_api.assert_public_link_types(%w[send_package_to_user send_package_to_dropbox])
-                box_type = aoc_api.public_link['purpose'].split('_').last
-                package_data['recipients'] = [{'id' => aoc_api.public_link['data']["#{box_type}_id"], 'type' => box_type}]
-                # enforce workspace id from link (should be already ok, but in case user wanted to override)
-                package_data['workspace_id'] = aoc_api.public_link['data']['workspace_id']
-              end
-              package_data['encryption_at_rest'] = true if transfer.user_transfer_spec['content_protection'].eql?('encrypt')
-              # transfer may raise an error
-              created_package = aoc_api.create_package_simple(package_data, option_validate, new_user_option)
-              Runner.result_transfer(transfer.start(created_package[:spec], rest_token: created_package[:node]))
-              # return all info on package (especially package id)
-              return Result::SingleObject.new(created_package[:info])
-            when :receive
-              ids_to_download = nil
-              if !aoc_api.public_link.nil?
-                aoc_api.assert_public_link_types(['view_received_package'])
-                # Set the package id from link
-                ids_to_download = aoc_api.public_link['data']['package_id']
-              end
-              # Get from command line unless it was a public link
-              ids_to_download ||= options.instance_identifier
-              skip_ids_persistency = package_persistency
-              case ids_to_download
-              when SpecialValues::INIT
-                all_packages = list_all_packages_with_query[:items]
-                Aspera.assert(skip_ids_persistency, 'INIT requires option once_only')
-                skip_ids_persistency.data.clear.concat(all_packages.map{ |e| e['id']})
-                skip_ids_persistency.save
-                return Result::Status.new("Initialized skip for #{skip_ids_persistency.data.count} package(s)")
-              when SpecialValues::ALL
-                all_packages = list_all_packages_with_query[:items]
-                # remove from list the ones already downloaded
-                reject_packages_from_persistency(all_packages, skip_ids_persistency)
-                ids_to_download = all_packages.map{ |e| e['id']}
-                formatter.display_status("Found #{ids_to_download.length} package(s).")
-              else
-                # single id to array
-                ids_to_download = [ids_to_download] unless ids_to_download.is_a?(Array)
-              end
-              # download all files, or specified list only
-              ts_paths = transfer.ts_source_paths(default: ['.'])
-              per_package_def = options.get_option(:package_folder).symbolize_keys
-              save_metadata = per_package_def.delete(:inf)
-              # get value outside of loop
-              destination_folder = transfer.destination_folder(Transfer::Spec::DIRECTION_RECEIVE)
-              result_transfer = []
-              ids_to_download.each do |package_id|
-                package_info = aoc_api.read("packages/#{package_id}")
-                package_node_api = aoc_api.node_api_from(
-                  node_id: package_info['node_id'],
-                  package_info: package_info,
-                  **workspace_id_hash(name: true)
-                )
-                transfer_spec = package_node_api.transfer_spec_gen4(
-                  package_info['contents_file_id'],
-                  Transfer::Spec::DIRECTION_RECEIVE,
-                  {'paths'=> ts_paths}
-                )
-                transfer.user_transfer_spec['destination_root'] = self.class.unique_folder(package_info, destination_folder, **per_package_def) unless per_package_def.empty?
-                dest_folder = transfer.user_transfer_spec['destination_root'] || destination_folder
-                formatter.display_status(%Q{Downloading package: [#{package_info['id']}] "#{package_info['name']}" to [#{dest_folder}]})
-                statuses = transfer.start(
-                  transfer_spec,
-                  rest_token: package_node_api
-                )
-                File.write(File.join(dest_folder, "#{package_id}.info.json"), package_info.to_json) if save_metadata
-                result_transfer.push({'package' => package_id, Runner::STATUS_FIELD => statuses})
-                # update skip list only if all transfer sessions completed
-                if skip_ids_persistency && TransferAgent.session_status(statuses).eql?(:success)
-                  skip_ids_persistency.data.push(package_id)
-                  skip_ids_persistency.save
+            command res, description: "Manage #{res.to_s.tr('_', ' ')}"
+            commands_under res do
+              ops.each do |op|
+                extra_setup = op_setup[op]
+                base_attrs = extra_setup ? {setup: extra_setup} : {}
+                extra_arg_list =
+                  if !is_singleton && op.eql?(:create)
+                    c = aoc_res_cfg(res)
+                    [{name: :data, type: Hash, bulk: true, schema: c[:schema]}]
+                  elsif !is_singleton && op.eql?(:modify)
+                    c = aoc_res_cfg(res)
+                    [{name: :data, type: Hash, schema: c[:schema]}]
+                  elsif extra_op_args.key?(op)
+                    extra_op_args[op]
+                  else
+                    []
+                  end
+                # For non-global ops, prepend the identifier spec
+                arg_list = (Operations::GLOBAL.include?(op) ? [] : id_arg_spec) + extra_arg_list
+                merged = arg_list.empty? ? base_attrs : base_attrs.merge(arguments: arg_list)
+                # Attach query_schema (full path) to :list CommandSpec so --help shows the tip
+                if op.eql?(:list)
+                  c = aoc_res_cfg(res)
+                  merged = merged.merge(query_schema: Schema::Registry.query_params(c[:query_component], c[:path]))
                 end
+                command op, description: op.to_s.tr('_', ' ').capitalize, **merged
               end
-              return Runner.result_transfer_multiple(result_transfer)
-            when :show
-              package_id = options.instance_identifier
-              package_info = aoc_api.read("packages/#{package_id}")
-              return Result::SingleObject.new(package_info)
-            when :list
-              result = list_all_packages_with_query
-              skip_ids_persistency = package_persistency
-              reject_packages_from_persistency(result[:items], skip_ids_persistency)
-              display_fields = PACKAGE_LIST_DEFAULT_FIELDS
-              display_fields += ['workspace_id'] if aoc_api.workspace_info[:id].nil?
-              return Result::ObjectList.new(result[:items], fields: display_fields, total: result[:total])
-            when :delete
-              return do_bulk_operation(command: package_command, values: options.instance_identifier) do |package_id|
-                Aspera.assert_type(package_id, String, Integer){'identifier'}
-                aoc_api.delete("packages/#{package_id}")
+            end
+          end
+        end
+        # admin > workspace > shared_folder sub-tree
+        commands_under %i[admin workspace shared_folder] do
+          command :list,   description: 'List shared folders'
+          command :node,   description: 'Execute node command on shared folder',
+            arguments: [{name: :sf_id, type: :identifier}],
+            setup: :setup_admin_workspace_shared_folder_node
+          command :member, description: 'Show folder members',
+            arguments: [{name: :sf_id, type: :identifier}],
+            setup: :setup_admin_workspace_shared_folder_member
+        end
+        # admin > workspace > shared_folder > node sub-tree (Gen4 commands)
+        commands_under %i[admin workspace shared_folder node] do
+          command :transfer,   description: 'Transfer files (node-to-node)'
+          command :permission, description: 'Manage permissions'
+          command :sync,       description: 'Synchronize folders'
+          Node::COMMANDS_GEN4_SPEC.each do |cmd, spec|
+            command cmd, **spec
+          end
+        end
+        commands_under %i[admin workspace shared_folder member] do
+          command :list, description: 'List members of a shared folder'
+        end
+        # admin > workspace > dropbox sub-tree
+        commands_under %i[admin workspace dropbox] do
+          command :list, description: 'List dropboxes in workspace'
+        end
+        # admin > node > do sub-tree (Gen4 commands)
+        commands_under %i[admin node do] do
+          command :transfer,   description: 'Transfer files (node-to-node)'
+          command :permission, description: 'Manage permissions'
+          command :sync,       description: 'Synchronize folders'
+          Node::COMMANDS_GEN4_SPEC.each do |cmd, spec|
+            command cmd, **spec
+          end
+        end
+        # admin > user > preferences|notifications sub-trees
+        %i[preferences notifications].each do |pref|
+          commands_under([:admin, :user, pref]) do
+            command :show,   description: "Show #{pref}"
+            command :modify, description: "Modify #{pref}",
+              arguments: [{name: :properties, type: Hash}]
+          end
+        end
+        commands_under %i[admin auth_providers] do
+          command :list, description: 'List auth providers',
+            action: -> { result_list('admin/auth_providers') }
+          command :update, description: 'Update auth provider', action: -> { Aspera.error_not_implemented }
+        end
+        commands_under %i[admin subscription] do
+          command :account, description: 'Show subscription account'
+          command :usage,   description: 'Show subscription usage',
+            arguments: [
+              {name: :aggregate,   mandatory: false, default: :ALL, allowed: %i[ALL MONTHLY]},
+              {name: :start_date,  mandatory: false, default: nil},
+              {name: :end_date,    mandatory: false, default: nil}
+            ]
+        end
+        commands_under %i[admin analytics] do
+          command :application_events, description: 'List application events'
+          command :transfers,          description: 'List transfer events',
+            arguments: [
+              {name: :event_resource_type, mandatory: true,  allowed: %i[organizations users nodes]},
+              {name: :event_resource_id,   mandatory: false, default: nil}
+            ]
+          command :files,              description: 'List file events',
+            arguments: [
+              {name: :event_resource_type, mandatory: true, allowed: %i[organizations users nodes]},
+              {name: :event_resource_id,   mandatory: true},
+              {name: :event_uuid,          mandatory: true}
+            ]
+        end
+        # application sub-commands
+        commands_under %i[admin application] do
+          command :types,      description: 'List application types',
+            action: -> { Result::ObjectList.new(aoc_api.read('admin/apps')) }
+          command :settings,   description: 'Manage per-app-type settings'
+          command :instance,   description: 'Manage app instances'
+          command :membership, description: 'Manage app memberships'
+        end
+        APP_SETTINGS_PATH = %i[admin application settings].freeze
+        APP_INSTANCE_PATH = %i[admin application instance].freeze
+        private_constant :APP_SETTINGS_PATH, :APP_INSTANCE_PATH
+        commands_under APP_SETTINGS_PATH do
+          APP_TYPES.each do |app_type|
+            command app_type, description: "Settings for #{app_type} app"
+            commands_under app_type do
+              command :show, description: "Show #{app_type} settings",
+                action: -> { Result::SingleObject.new(aoc_api.read("/apps/#{app_type}/settings")) }
+              command(
+                :modify, description: "Modify #{app_type} settings",
+                arguments: [{name: :properties, type: Hash}],
+                action: lambda do |properties:, **|
+                  aoc_api.update("/apps/#{app_type}/settings", properties)
+                  Result::Status.new('modified')
+                end
+              )
+            end
+          end
+        end
+        commands_under APP_INSTANCE_PATH do
+          command(:list, description: 'List app instances', action: lambda do
+            result_list(
+              'admin/apps_new',
+              fields:        %w[id app_type available workspace_id],
+              default_query: {workspace_id: aoc_api.workspace_info[:id]}
+            )
+          end)
+          APP_TYPES.each do |app_type|
+            command app_type, description: "Show or modify a #{app_type} instance"
+            commands_under app_type do
+              command :show,   description: "Show a #{app_type} instance",
+                arguments: [{name: :"#{app_type}_id", type: :identifier}]
+              command :modify, description: "Modify a #{app_type} instance",
+                arguments: [{name: :"#{app_type}_id", type: :identifier}, {name: :properties, type: Hash}]
+            end
+          end
+        end
+        commands_under %i[admin application membership] do
+          command :list, description: 'List app memberships', action: -> { result_list('apps/app_memberships') }
+          command :show,   description: 'Show an app membership', arguments: [{name: :membership_id, type: :identifier}]
+          command :delete, description: 'Delete an app membership', arguments: [{name: :membership_id, type: :identifier}]
+          command :create, description: 'Create an app membership', arguments: [{name: :membership, type: Hash}]
+        end
+        command :automation,        description: 'Automation commands (BETA)', setup: :setup_automation_api
+        command :gateway,           description: 'Start AoC Faspex4 gateway',
+          arguments: [{name: :parameters, type: Hash, mandatory: false, default: {}}]
+
+        # user sub-commands
+        commands_under :user do
+          commands_under :workspaces, description: "User's workspaces" do
+            command :list,    description: 'List workspaces', action: -> { result_list('workspaces', fields: %w[id name]) }
+            command :current, description: 'Show current workspace', action: -> { Result::SingleObject.new(aoc_api.workspace_info) }
+          end
+          # command :profile, description: 'User profile commands'
+          commands_under :profile, description: "Manager user's profile" do
+            command :show, description: 'Show user profile', action: -> { Result::SingleObject.new(aoc_api.current_user_info(exception: true)) }
+            command(
+              :modify, description: 'Modify user profile',
+              arguments: [{name: :properties, type: Hash}],
+              action: lambda do |properties:, **|
+                aoc_api.update("users/#{aoc_api.current_user_info(exception: true)['id']}", properties)
+                Result::Status.new('modified')
               end
-            when :modify
-              package_id = options.instance_identifier
-              package_data = value_create_modify(command: package_command)
-              aoc_api.update("packages/#{package_id}", package_data)
-              return Result::Status.new('modified')
-            when *Node::NODE4_READ_ACTIONS
-              package_id = options.instance_identifier
-              package_info = aoc_api.read("packages/#{package_id}")
-              return execute_nodegen4_command(package_command, package_info['node_id'], file_id: package_info['contents_file_id'], scope: Api::Node::Scope::USER)
+            )
+          end
+          command :preferences,   description: 'User interaction preferences'
+          command :notifications, description: 'Notification preferences'
+          command :contacts,      description: 'Manage contacts'
+          # user > contacts sub-commands (same CRUD as admin > contact)
+          commands_under %i[contacts] do
+            Operations::ALL.each { |op| command op, description: op.to_s.capitalize }
+          end
+          command :settings, description: 'Manage client settings'
+          commands_under %i[settings] do
+            crud_commands api: :aoc_api, entity: 'client_settings', name: 'client setting'
+          end
+        end
+
+        commands_under %i[user preferences] do
+          command(
+            :show, description: 'Show user preferences',
+            action: lambda do
+              user_id = aoc_api.current_user_info(exception: true)['id']
+              Result::SingleObject.new(aoc_api.read("users/#{user_id}/user_interaction_preferences"))
+            end
+          )
+          command(
+            :modify, description: 'Modify user preferences',
+            arguments: [{name: :properties, type: Hash}],
+            action: lambda do |properties:, **|
+              user_id = aoc_api.current_user_info(exception: true)['id']
+              aoc_api.update("users/#{user_id}/user_interaction_preferences", properties)
+              Result::Status.new('modified')
+            end
+          )
+        end
+
+        commands_under %i[user notifications] do
+          command(
+            :show, description: 'Show notification preferences',
+            action: lambda do
+              user_id = aoc_api.current_user_info(exception: true)['id']
+              Result::SingleObject.new(aoc_api.read("users/#{user_id}/notification_preferences"))
             end
-          when :files
-            command_repo = options.get_next_command([:short_link].concat(FILES_COMMANDS))
-            case command_repo
-            when *FILES_COMMANDS
-              return execute_nodegen4_command(command_repo, aoc_api.home[:node_id], file_id: aoc_api.home[:file_id], scope: Api::Node::Scope::USER)
-            when :short_link
-              folder_dest = options.get_next_argument('path', validation: String)
-              home_node_api = aoc_api.node_api_from(
-                node_id: aoc_api.home[:node_id],
-                **workspace_id_hash(name: true)
+          )
+          command(
+            :modify, description: 'Modify notification preferences',
+            arguments: [{name: :properties, type: Hash}],
+            action: lambda do |properties:, **|
+              user_id = aoc_api.current_user_info(exception: true)['id']
+              aoc_api.update("users/#{user_id}/notification_preferences", properties)
+              Result::Status.new('modified')
+            end
+          )
+        end
+
+        # packages sub-commands — instance commands consume package_id
+        commands_under :packages do
+          command :shared_inboxes, description: 'Shared inbox commands'
+          command :send, description: 'Send a package', transfer_paths: :send,
+            arguments: [{name: :data, type: Hash, schema: Schema::Registry.req_body(Schema::Registry::AOC, 'packages.post')}]
+          command :receive, description: 'Receive packages', aliases: [:recv], transfer_paths: :receive,
+            arguments: [{name: :package_id, type: :identifier}]
+          command :list, description: 'List packages'
+          command :show, description: 'Show a package',
+            arguments: [{name: :package_id, type: :identifier}]
+          command :delete, description: 'Delete packages',
+            arguments: [{name: :package_id, type: :identifier}]
+          command :modify, description: 'Modify a package',
+            arguments: [{name: :package_id, type: :identifier}, {name: :data, type: Hash}]
+          # Node Gen4 read-only actions on packages
+          command :bearer_token_node, description: 'Show bearer token for package node',
+            arguments: [{name: :package_id, type: :identifier}]
+          command :node_info,         description: 'Show node info for package',
+            arguments: [{name: :package_id, type: :identifier}]
+          command :ls,                description: 'List package contents', aliases: [:browse],
+            arguments: [{name: :package_id, type: :identifier}]
+          command :find,              description: 'Find files in package',
+            arguments: [{name: :package_id, type: :identifier}]
+        end
+
+        commands_under %i[packages shared_inboxes] do
+          command :list,       description: 'List shared inboxes',
+            action: (lambda do
+              result_list(
+                'dropbox_memberships',
+                fields: %w[dropbox_id dropbox.name],
+                default_query: workspace_id_hash({'embed[]' => 'dropbox', 'aggregate_permissions_by_dropbox' => true, 'sort' => 'dropbox_name'}, string: true)
               )
-              shared_apifid = home_node_api.resolve_api_fid(aoc_api.home[:file_id], folder_dest)
-              return short_link_command(
-                node_id:        shared_apifid.node_api.app_info.node_info['id'],
-                file_id:        shared_apifid.file_id
-              ) do |op, id, access_levels|
-                case op
-                when :create
-                  # `id` is the resource id
-                  perm_data = {
-                    'file_id'       => shared_apifid.file_id,
-                    'access_id'     => id,
-                    'access_type'   => 'user',
-                    'access_levels' => Api::AoC.expand_access_levels(access_levels),
-                    'tags'          => {
-                      'url_token'        => true,
-                      'folder_name'      => File.basename(folder_dest),
-                      'created_by_name'  => aoc_api.current_user_info['name'],
-                      'created_by_email' => aoc_api.current_user_info['email'],
-                      'access_key'       => shared_apifid.node_api.app_info.node_info['access_key'],
-                      'node'             => shared_apifid.node_api.app_info.node_info['name'],
-                      **workspace_id_hash(string: true, name: true)
-                    }
-                  }
-                  created_data = shared_apifid.node_api.create('permissions', perm_data)
-                  aoc_api.permissions_send_event(event_data: created_data, app_info: shared_apifid.node_api.app_info)
-                when :update
-                  # `id` is the permission_id
-                  found = shared_apifid.node_api.read('permissions', {file_id: shared_apifid.file_id, inherited: false, access_type: 'user', access_id: id}).find{ |i| i['access_id'].eql?(id)}
-                  raise Error, "Short link not found: #{id}" if found.nil?
-                  shared_apifid.node_api.update("permissions/#{found['id']}", {access_levels: Api::AoC.expand_access_levels(access_levels)})
-                when :delete
-                  # `id` is the resource id, i.e. `access_id`
-                  found = shared_apifid.node_api.read('permissions', {file_id: shared_apifid.file_id, inherited: false, access_type: 'user', access_id: id}).first
-                  raise Error, "Short link not found: #{id}" if found.nil?
-                  shared_apifid.node_api.delete("permissions/#{found['id']}")
-                else Aspera.error_unexpected_value(op)
-                end
+            end)
+          command :show,       description: 'Show a shared inbox',
+            arguments: [{name: :dropbox_id, type: :identifier, lookup: :lookup_aoc_dropbox_id}],
+            action: ->(dropbox_id:, **) { Result::SingleObject.new(aoc_api.read("dropboxes/#{dropbox_id}")) }
+          command :short_link, description: 'Manage shared inbox short links',
+            arguments: [{name: :link_type, allowed: %i[public private]}],
+            setup: :setup_packages_short_link
+        end
+        # packages > shared_inboxes > short_link sub-commands
+        register_short_link_commands(self, %i[packages shared_inboxes short_link])
+
+        # files sub-commands: AoC-specific commands + all Gen4 commands from COMMANDS_GEN4_SPEC
+        commands_under :files do
+          command :short_link, description: 'Manage file short link',
+            arguments: [{name: :folder_dest, type: String}, {name: :link_type, allowed: %i[public private]}],
+            setup: :setup_files_short_link
+          command :transfer, description: 'Transfer files (node-to-node)',
+            arguments: [{name: :direction, allowed: %i[push pull]}, {name: :source_folder, type: String}]
+          command :permission, description: 'Manage permissions'
+          command :sync,       description: 'Synchronize folders'
+          Node::COMMANDS_GEN4_SPEC.each do |cmd, spec|
+            command cmd, **spec
+          end
+        end
+        # files > short_link sub-commands
+        register_short_link_commands(self, %i[files short_link])
+
+        # automation sub-commands
+        commands_under :automation  do
+          commands_under :instances do
+            crud_commands api: :aoc_api, entity: 'workflow_instances', name: 'workflow instance'
+          end
+
+          commands_under :workflows do
+            crud_commands api: :@automation_api, entity: 'workflows'
+            command :launch, description: 'Launch a workflow',
+              arguments: [{name: :wf_id, type: :identifier}],
+              action: ->(wf_id:, **) { Result::SingleObject.new(@automation_api.create("workflows/#{wf_id}/launch", {})) }
+            commands_under :action, description: 'Add action to workflow (TODO)' do
+              %i[list create show].each do |cmd|
+                command cmd,
+                  description: "#{cmd.capitalize} action (TODO)",
+                  arguments:   [{name: :wf_id, type: :identifier}]
               end
             end
-          when :automation
-            change_api_scope(Api::AoC::Scope::ADMIN_USER)
-            Log.log.warn('BETA: work under progress')
-            # automation api is not in the same place
-            automation_api = Rest.new(**aoc_api.params, base_url: aoc_api.base_url.gsub('/api/', '/automation/'))
-            command_automation = options.get_next_command(%i[workflows instances])
-            case command_automation
-            when :instances
-              return entity_execute(api: aoc_api, entity: 'workflow_instances')
-            when :workflows
-              wf_command = options.get_next_command(%i[action launch].concat(Operations::ALL))
-              case wf_command
-              when *Operations::ALL
-                return entity_execute(
-                  api: automation_api,
-                  entity: 'workflows',
-                  command: wf_command
-                )
-              when :launch
-                wf_id = options.instance_identifier
-                data = automation_api.create("workflows/#{wf_id}/launch", {})
-                return Result::SingleObject.new(data)
-              when :action
-                # TODO: not complete
-                wf_id = options.instance_identifier
-                wf_action_cmd = options.get_next_command(%i[list create show])
-                Log.log.warn{"Not implemented: #{wf_action_cmd}"}
-                step = automation_api.create('steps', {'workflow_id' => wf_id})
-                automation_api.update("workflows/#{wf_id}", {'step_order' => [step['id']]})
-                action = automation_api.create('actions', {'step_id' => step['id'], 'type' => 'manual'})
-                automation_api.update("steps/#{step['id']}", {'action_order' => [action['id']]})
-                wf = automation_api.read("workflows/#{wf_id}")
-                return Result::SingleObject.new(wf)
+          end
+        end
+
+        # --- setup methods ---
+
+        # Display workspace info before dispatching files/packages sub-commands.
+        # Returns {} so it does not inject anything into ctx.
+        def setup_workspace_display(**)
+          formatter.display_status("Workspace: #{aoc_api.workspace_info[:name].to_s.red}#{' (default)' if aoc_api.default_workspace?}")
+          if !aoc_api.private_link.nil?
+            folder_name = aoc_api.node_api_from(node_id: aoc_api.home[:node_id]).read("files/#{aoc_api.home[:file_id]}")['name']
+            formatter.display_status("Private Folder: #{folder_name}")
+          end
+          {}
+        end
+
+        # Build automation API and store in @automation_api ivar.
+        def setup_automation_api(**)
+          change_api_scope(Api::AoC::Scope::ADMIN_USER)
+          Log.log.warn('BETA: work under progress')
+          @automation_api = Rest.new(**aoc_api.params, base_url: aoc_api.base_url.gsub('/api/', '/automation/'))
+          {}
+        end
+
+        # --- handler methods ---
+
+        def action_reminder
+          user_email = options.get_option(:username, mandatory: true)
+          no_auth_api = Api::AoC.new(url: options.get_option(:url), auth: :none)
+          no_auth_api.create('organization_reminders', {email: user_email})
+          return Result::Status.new("List of organizations user is member of, has been sent by e-mail to #{user_email}")
+        end
+
+        # packages > send
+        def action_packages_send(data:, **)
+          package_data = data
+          new_user_option = options.get_option(:new_user_option)
+          option_validate = options.get_option(:validate_metadata)
+          workspace_id_hash(package_data, string: true) unless package_data.key?('workspace_id')
+          if !aoc_api.public_link.nil?
+            aoc_api.assert_public_link_types(%w[send_package_to_user send_package_to_dropbox])
+            box_type = aoc_api.public_link['purpose'].split('_').last
+            package_data['recipients'] = [{'id' => aoc_api.public_link['data']["#{box_type}_id"], 'type' => box_type}]
+            package_data['workspace_id'] = aoc_api.public_link['data']['workspace_id']
+          end
+          package_data['encryption_at_rest'] = true if transfer.user_transfer_spec['content_protection'].eql?('encrypt')
+          created_package = aoc_api.create_package_simple(package_data, option_validate, new_user_option)
+          Runner.result_transfer(transfer.start(created_package[:spec], rest_token: created_package[:node]))
+          return Result::SingleObject.new(created_package[:info])
+        end
+
+        # packages > receive — package_id: from arguments:(:identifier) (or overridden by public_link)
+        def action_packages_receive(package_id:, **)
+          ids_to_download = if aoc_api.public_link.nil?
+            package_id
+          else
+            aoc_api.assert_public_link_types(['view_received_package'])
+            aoc_api.public_link['data']['package_id']
+          end
+          skip_ids_persistency = package_persistency
+          case ids_to_download
+          when SpecialValues::INIT
+            all_packages, = list_all_packages_with_query
+            Aspera.assert(skip_ids_persistency, 'INIT requires option once_only')
+            skip_ids_persistency.data.clear.concat(all_packages[:items].map { |e| e['id'] })
+            skip_ids_persistency.save
+            return Result::Status.new("Initialized skip for #{skip_ids_persistency.data.count} package(s)")
+          when SpecialValues::ALL
+            all_packages, max_items = list_all_packages_with_query
+            reject_packages_from_persistency(all_packages[:items], skip_ids_persistency)
+            all_packages[:items] = all_packages[:items][0, max_items] if max_items
+            ids_to_download = all_packages[:items].map { |e| e['id'] }
+            formatter.display_status("Found #{ids_to_download.length} package(s).")
+          else
+            ids_to_download = [ids_to_download] unless ids_to_download.is_a?(Array)
+          end
+          ts_paths = transfer.ts_source_paths(default: ['.'])
+          per_package_def = options.get_option(:package_folder).symbolize_keys
+          save_metadata = per_package_def.delete(:inf)
+          destination_folder = transfer.destination_folder(Transfer::Spec::DIRECTION_RECEIVE)
+          result_transfer = []
+          ids_to_download.each do |package_id|
+            package_info = aoc_api.read("packages/#{package_id}")
+            package_node_api = aoc_api.node_api_from(
+              node_id: package_info['node_id'],
+              package_info: package_info,
+              **workspace_id_hash(name: true)
+            )
+            transfer_spec = package_node_api.transfer_spec_gen4(
+              package_info['contents_file_id'],
+              Transfer::Spec::DIRECTION_RECEIVE,
+              {'paths'=> ts_paths}
+            )
+            transfer.user_transfer_spec['destination_root'] = self.class.unique_folder(package_info, destination_folder, **per_package_def) unless per_package_def.empty?
+            dest_folder = transfer.user_transfer_spec['destination_root'] || destination_folder
+            formatter.display_status(%Q{Downloading package: [#{package_info['id']}] "#{package_info['name']}" to [#{dest_folder}]})
+            statuses = transfer.start(transfer_spec, rest_token: package_node_api)
+            File.write(File.join(dest_folder, "#{package_id}.info.json"), package_info.to_json) if save_metadata
+            result_transfer.push({'package' => package_id, Runner::STATUS_FIELD => statuses})
+            if skip_ids_persistency && statuses.is_a?(Transfer::Result::Success)
+              skip_ids_persistency.data.push(package_id)
+              skip_ids_persistency.save
+            end
+          end
+          return Runner.result_transfer_multiple(result_transfer)
+        end
+
+        # packages > list
+        def action_packages_list
+          result, max_items = list_all_packages_with_query
+          skip_ids_persistency = package_persistency
+          reject_packages_from_persistency(result[:items], skip_ids_persistency)
+          result[:items] = result[:items][0, max_items] if max_items
+          display_fields = PACKAGE_LIST_DEFAULT_FIELDS
+          display_fields += ['workspace_id'] if aoc_api.workspace_info[:id].nil?
+          Result::ObjectList.new(result[:items], fields: display_fields, total: result[:total])
+        end
+
+        # packages > show
+        def action_packages_show(package_id:, **)
+          Result::SingleObject.new(aoc_api.read("packages/#{package_id}"))
+        end
+
+        # packages > delete
+        def action_packages_delete(package_id:, **)
+          bulk_result(package_id, command: :delete) do |one_id|
+            Aspera.assert_type(one_id, String, Integer) { 'identifier' }
+            aoc_api.delete("packages/#{one_id}")
+          end
+        end
+
+        # packages > modify
+        def action_packages_modify(data:, package_id:, **)
+          aoc_api.update("packages/#{package_id}", data)
+          Result::Status.new('modified')
+        end
+
+        # packages > bearer_token_node / node_info / ls / find
+        # (NODE4_READ_ACTIONS dispatched by full path: action_packages_bearer_token_node, etc.)
+        Node::NODE4_READ_ACTIONS.each do |action|
+          define_action_method([:packages, action]) do |package_id:, **|
+            package_info = aoc_api.read("packages/#{package_id}")
+            execute_nodegen4_command(action, package_info['node_id'], file_id: package_info['contents_file_id'], scope: Api::Node::Scope::USER)
+          end
+        end
+
+        # setup: files > short_link
+        # Resolves the target folder, consumes link_type argument, computes purposes.
+        # @return [Hash] ctx keys: sl_shared_data, sl_link_type, sl_token_purpose, sl_short_link_purpose, sl_perm_block, sl_shared_apifid, sl_folder_dest
+        def setup_files_short_link(folder_dest:, link_type:, **)
+          home_node_api = aoc_api.node_api_from(
+            node_id: aoc_api.home[:node_id],
+            **workspace_id_hash(name: true)
+          )
+          shared_apifid = home_node_api.resolve_api_fid(aoc_api.home[:file_id], folder_dest)
+          shared_data = {
+            node_id: shared_apifid.node_api.app_info.node_info['id'],
+            file_id: shared_apifid.file_id
+          }
+          token_purpose, short_link_purpose = short_link_purposes(shared_data, link_type)
+          perm_block = lambda do |op, id, access_levels|
+            case op
+            when :create
+              perm_data = {
+                'file_id'       => shared_apifid.file_id,
+                'access_id'     => id,
+                'access_type'   => 'user',
+                'access_levels' => Api::AoC.expand_access_levels(access_levels),
+                'tags'          => {
+                  'url_token'        => true,
+                  'folder_name'      => File.basename(folder_dest),
+                  'created_by_name'  => aoc_api.current_user_info['name'],
+                  'created_by_email' => aoc_api.current_user_info['email'],
+                  'access_key'       => shared_apifid.node_api.app_info.node_info['access_key'],
+                  'node'             => shared_apifid.node_api.app_info.node_info['name'],
+                  **workspace_id_hash(string: true, name: true)
+                }
+              }
+              created_data = shared_apifid.node_api.create('permissions', perm_data)
+              aoc_api.permissions_send_event(event_data: created_data, app_info: shared_apifid.node_api.app_info)
+            when :update
+              found = shared_apifid.node_api.read('permissions', {file_id: shared_apifid.file_id, inherited: false, access_type: 'user', access_id: id}).find { |i| i['access_id'].eql?(id) }
+              Aspera.assert(!found.nil?, type: Error) { "Short link not found: #{id}" }
+              shared_apifid.node_api.update("permissions/#{found['id']}", {access_levels: Api::AoC.expand_access_levels(access_levels)})
+            when :delete
+              found = shared_apifid.node_api.read('permissions', {file_id: shared_apifid.file_id, inherited: false, access_type: 'user', access_id: id}).first
+              Aspera.assert(!found.nil?, type: Error) { "Short link not found: #{id}" }
+              shared_apifid.node_api.delete("permissions/#{found['id']}")
+            else Aspera.error_unexpected_value(op)
+            end
+          end
+          {
+            sl_shared_data:        shared_data,
+            sl_link_type:          link_type,
+            sl_token_purpose:      token_purpose,
+            sl_short_link_purpose: short_link_purpose,
+            sl_perm_block:         perm_block
+          }
+        end
+
+        # setup: packages > shared_inboxes > short_link
+        # Reads dropbox_id, consumes link_type argument, computes purposes.
+        # @return [Hash] ctx keys: sl_shared_data, sl_link_type, sl_token_purpose, sl_short_link_purpose
+        def setup_packages_short_link(link_type:, **)
+          dropbox_id = get_resource_id_from_args('dropboxes')
+          shared_data = {dropbox_id: dropbox_id, name: ''}
+          token_purpose, short_link_purpose = short_link_purposes(shared_data, link_type)
+          {
+            sl_shared_data:        shared_data,
+            sl_link_type:          link_type,
+            sl_token_purpose:      token_purpose,
+            sl_short_link_purpose: short_link_purpose,
+            sl_perm_block:         nil
+          }
+        end
+
+        # Shared implementation for short_link > create
+        def sl_exec_create(custom_data = {}, sl_shared_data:, sl_link_type:, sl_token_purpose:, sl_short_link_purpose:, sl_perm_block:, **)
+          shared_data = sl_shared_data.dup
+          workspace_id_hash(shared_data)
+          create_payload = {purpose: sl_short_link_purpose, user_selected_name: nil}
+          case sl_link_type
+          when :private
+            create_payload[:data] = shared_data
+          when :public
+            create_payload[:expires_at]       = nil
+            create_payload[:password_enabled] = false
+            shared_data[:name] = ''
+            create_payload[:data] = {
+              aoc:            true,
+              url_token_data: {data: shared_data, purpose: sl_token_purpose}
+            }
+          end
+          custom_data = {}
+          access_levels = custom_data.delete('access_levels')
+          if (pass = custom_data.delete('password'))
+            create_payload[:data][:url_token_data][:password] = pass
+            create_payload[:password_enabled] = true
+          end
+          create_payload.deep_merge!(custom_data)
+          result_create_short_link = aoc_api.create('short_links', create_payload)
+          sl_perm_block&.call(:create, result_create_short_link['resource_id'], access_levels) if sl_link_type.eql?(:public)
+          Result::SingleObject.new(result_create_short_link)
+        end
+
+        # Shared implementation for short_link > delete|list|show|modify: fetch the short_list
+        def sl_fetch_list(sl_shared_data:, sl_link_type:, sl_token_purpose:, sl_short_link_purpose:, **)
+          shared_data = sl_shared_data.dup
+          workspace_id_hash(shared_data)
+          list_params = short_link_list_params(
+            shared_data: shared_data, link_type: sl_link_type,
+            token_purpose: sl_token_purpose, short_link_purpose: sl_short_link_purpose
+          )
+          {
+            sl_short_list:     aoc_api.read_with_paging('short_links', list_params.merge(query_read_delete(default: {})).compact),
+            sl_shared_data_ws: shared_data
+          }
+        end
+
+        # Shared implementation for short_link > delete
+        def sl_exec_delete(sl_shared_data_ws:, sl_short_list:, sl_link_type:, sl_perm_block:, short_link_id: nil, **)
+          one_id = short_link_id
+          if sl_link_type.eql?(:public)
+            found = sl_short_list[:items].find { |item| item['id'].eql?(one_id) }
+            raise BadIdentifier.new('Short link', one_id) if found.nil?
+            sl_perm_block&.call(:delete, found['resource_id'], nil)
+          end
+          aoc_api.delete("short_links/#{one_id}", {edit_access: true, json_query: sl_shared_data_ws.to_json})
+          Result::Status.new('deleted')
+        end
+
+        # Shared implementation for short_link > list
+        def sl_exec_list(sl_short_list:, **)
+          Result::ObjectList.new(sl_short_list[:items], fields: Formatter.all_but('data'), total: sl_short_list[:total])
+        end
+
+        # Shared implementation for short_link > show
+        def sl_exec_show(sl_short_list:, short_link_id: nil, **)
+          one_id = short_link_id
+          found = sl_short_list[:items].find { |item| item['id'].eql?(one_id) }
+          raise BadIdentifier.new('Short link', one_id) if found.nil?
+          Result::SingleObject.new(found, fields: Formatter.all_but('data'))
+        end
+
+        # Shared implementation for short_link > modify
+        def sl_exec_modify(custom_data = {}, sl_shared_data:, sl_short_list:, sl_link_type:, sl_perm_block:, short_link_id: nil, **)
+          Aspera.assert_values(sl_link_type, [:public], type: Cli::BadArgument) { 'link_type' }
+          one_id = short_link_id
+          node_file = sl_shared_data.slice(:node_id, :file_id)
+          modify_payload = {edit_access: true, json_query: node_file}
+          custom_data = {}
+          if (pass = custom_data.delete('password'))
+            modify_payload[:password_enabled] = true
+            modify_payload[:data] = {url_token_data: {password: pass, data: node_file}}
+          else
+            modify_payload[:password_enabled] = false
+          end
+          if custom_data.delete('access_levels')
+            found = sl_short_list[:items].find { |item| item['id'].eql?(one_id) }
+            raise BadIdentifier.new('Short link', one_id) if found.nil?
+            sl_perm_block&.call(:update, found['resource_id'], nil)
+          end
+          modify_payload.deep_merge!(custom_data)
+          aoc_api.update("short_links/#{one_id}", modify_payload)
+          Result::Status.new('modified')
+        end
+
+        # files > transfer
+        def action_files_transfer(direction:, source_folder:, **)
+          execute_nodegen4_command(
+            :transfer, aoc_api.home[:node_id],
+            file_id:            aoc_api.home[:file_id],
+            scope:              Api::Node::Scope::USER,
+            transfer_direction: direction,
+            transfer_source:    source_folder
+          )
+        end
+
+        # files > FILES_COMMANDS (all Gen4 node commands except :transfer, handled above)
+        FILES_COMMANDS.reject { |a| a.eql?(:transfer) }.each do |action|
+          define_action_method([:files, action]) do |**ctx|
+            execute_nodegen4_command(action, aoc_api.home[:node_id], file_id: aoc_api.home[:file_id], scope: Api::Node::Scope::USER, **ctx)
+          end
+        end
+
+        # admin > application > instance > <type> > show|modify
+        APP_TYPES.each do |app_type|
+          define_action_method([:admin, :application, :instance, app_type, :show]) do |**kwargs|
+            app_id = kwargs[:"#{app_type}_id"]
+            Result::SingleObject.new(aoc_api.read("admin/apps_new/#{app_type}/#{app_id}", query_read_delete))
+          end
+
+          define_action_method([:admin, :application, :instance, app_type, :modify]) do |properties:, **kwargs|
+            app_id = kwargs[:"#{app_type}_id"]
+            aoc_api.update("admin/apps_new/#{app_type}/#{app_id}", properties)
+            Result::Status.new('modified')
+          end
+        end
+
+        def action_admin_application_membership_create(membership:, **)
+          data = membership.dup
+          app_type = data.delete('app_type')
+          Aspera.assert_type(app_type, String) { 'app_type' }
+          Aspera.assert_values(app_type.to_sym, APP_TYPES) { 'app_type' }
+          Result::SingleObject.new(aoc_api.create("apps/#{app_type}/app_memberships", data))
+        end
+
+        # admin > application > membership > show|delete
+        def action_admin_application_membership_show(membership_id:, **)
+          Result::SingleObject.new(aoc_api.read("apps/app_memberships/#{membership_id}", query_read_delete))
+        end
+
+        def action_admin_application_membership_delete(membership_id:, **)
+          aoc_api.delete("apps/app_memberships/#{membership_id}")
+          Result::Status.new('deleted')
+        end
+
+        # admin - setup: change API scope to admin once
+        def setup_admin_scope(**)
+          change_api_scope(Api::AoC::Scope::ADMIN)
+          {}
+        end
+
+        # admin > subscription > account
+        def action_admin_subscription_account
+          org = aoc_api.read('organization')
+          result = GraphQL.execute(api_from_options('bss/platform/graphql'), 'bss_subscription_account', {organization_id: org['id']})
+          Result::SingleObject.new(result['aoc']['bssSubscription'])
+        end
+
+        # admin > subscription > usage
+        def action_admin_subscription_usage(aggregate:, start_date:, end_date:, **)
+          today      = Date.today
+          aggregate  = :ALL if aggregate.nil?
+          start_date = today.prev_year.strftime('%Y-%m-%d') if start_date.nil?
+          end_date   = today.strftime('%Y-%m-%d') if end_date.nil?
+          org    = aoc_api.read('organization')
+          result = GraphQL.execute(
+            api_from_options('bss/platform/graphql'), 'bss_subscription_usage',
+            {organization_id: org['id'], aggregate: aggregate, startDate: start_date, endDate: end_date}
+          )
+          Result::SingleObject.new(result['aoc'])
+        end
+
+        # admin > analytics > application_events
+        def action_admin_analytics_application_events
+          events = build_analytics_api.read("organizations/#{aoc_api.current_user_info['organization_id']}/application_events")['application_events']
+          Result::ObjectList.new(events)
+        end
+
+        # admin > analytics > transfers
+        def action_admin_analytics_transfers(event_resource_type:, event_resource_id:, **)
+          event_resource_id ||=
+            case event_resource_type
+            when :organizations then aoc_api.current_user_info['organization_id']
+            when :users         then aoc_api.current_user_info['id']
+            when :nodes         then aoc_api.current_user_info['read_only_home_node_id']
+            else Aspera.error_unreachable_line
+            end
+          filter = query_read_delete(default: {})
+          filter['limit'] ||= 100
+          if options.get_option(:once_only, mandatory: true)
+            saved_date = []
+            start_date_persistency = PersistencyActionOnce.new(
+              manager: persistency,
+              data:    saved_date,
+              id:      IdGenerator.from_list('aoc_ana_date', options.get_option(:url, mandatory: true), aoc_api.workspace_info[:name], event_resource_type.to_s, event_resource_id)
+            )
+            start_date_time = saved_date.first
+            stop_date_time  = Time.now.utc.strftime('%FT%T.%LZ')
+            saved_date[0]   = stop_date_time
+            filter['start_time'] = start_date_time unless start_date_time.nil?
+            filter['stop_time']  = stop_date_time
+          end
+          events = build_analytics_api.read("#{event_resource_type}/#{event_resource_id}/transfers", filter)['transfers']
+          start_date_persistency&.save
+          events.each { |tr_event| context.mailer.send_email_template(values: {ev: tr_event}) } if !options.get_option(:notify_to).nil?
+          Result::ObjectList.new(events)
+        end
+
+        # admin > analytics > files
+        def action_admin_analytics_files(event_resource_type:, event_resource_id:, event_uuid:, **)
+          event_resource_id =
+            case event_resource_type
+            when :organizations then aoc_api.current_user_info['organization_id']
+            when :users         then aoc_api.current_user_info['id']
+            when :nodes         then aoc_api.current_user_info['read_only_home_node_id']
+            else Aspera.error_unreachable_line
+            end if event_resource_id.to_s.empty?
+          filter = query_read_delete(default: {})
+          filter['limit'] ||= 100
+          events = build_analytics_api.read("#{event_resource_type}/#{event_resource_id}/transfers/#{event_uuid}/files", filter)['files']
+          Result::ObjectList.new(events)
+        end
+
+        # Lookup methods for arguments:(:identifier) + lookup: on admin resources.
+        # One method per non-singleton resource; each delegates to get_resource_id_from_args.
+        ADMIN_OBJECTS.reject { |r| ADMIN_OBJECT_CONFIG.dig(r, :singleton) }.each do |res|
+          define_method(:"lookup_aoc_#{res}_id") do |_field, value, **|
+            aoc_api.lookup_with_q(aoc_res_path(res), value: value)['id']
+          end
+        end
+
+        # admin > <res> > list
+        ADMIN_OBJECTS.each do |res|
+          define_action_method([:admin, res, :list]) do
+            c = aoc_res_cfg(res)
+            result_list(c[:path], fields: c[:list_fields], query_component: c[:query_component])
+          end
+        end
+
+        # admin > <res> > show
+        ADMIN_OBJECTS.reject { |r| ADMIN_OBJECT_CONFIG.dig(r, :singleton) }.each do |res|
+          define_action_method([:admin, res, :show]) do |**kwargs|
+            res_id = kwargs[:"#{res}_id"]
+            c = aoc_res_cfg(res)
+            Result::SingleObject.new(aoc_api.read("#{c[:path]}/#{res_id}", query_read_delete), fields: Formatter.all_but('certificate'))
+          end
+        end
+
+        # admin > organization|self > show (singleton)
+        %i[organization self].each do |res|
+          define_action_method([:admin, res, :show]) do
+            Result::SingleObject.new(aoc_api.read(res.to_s, query_read_delete), fields: Formatter.all_but('certificate'))
+          end
+        end
+
+        # admin > <res> > create
+        ADMIN_OBJECTS.reject { |r| ADMIN_OBJECT_CONFIG.dig(r, :singleton) }.each do |res|
+          define_action_method([:admin, res, :create]) do |data:, **|
+            c = aoc_res_cfg(res)
+            path = c[:path]
+            # Special case: client_registration_token has a different creation URL
+            path = 'admin/client_registration/token' if path.eql?('admin/client_registration_tokens')
+            workspace_id = aoc_api.workspace_info[:id] if c[:require_ws_id]
+            bulk_result(data, command: :create, id_result: c[:id_result]) do |params|
+              params['workspace_id'] = workspace_id if c[:require_ws_id] && workspace_id && !params.key?('workspace_id')
+              aoc_api.create(path, params)
+            end
+          end
+        end
+
+        # admin > <res> > modify
+        ADMIN_OBJECTS.reject { |r| ADMIN_OBJECT_CONFIG.dig(r, :singleton) || ADMIN_OBJECT_CONFIG.dig(r, :ops)&.then { |o| !o.include?(:modify) } }.each do |res|
+          define_action_method([:admin, res, :modify]) do |data:, **kwargs|
+            res_id = kwargs[:"#{res}_id"]
+            c = aoc_res_cfg(res)
+            aoc_api.update("#{c[:path]}/#{res_id}", data)
+            Result::Status.new('modified')
+          end
+        end
+
+        # admin > <res> > delete
+        ADMIN_OBJECTS.reject do |r|
+          cfg = ADMIN_OBJECT_CONFIG.fetch(r, {})
+          cfg[:singleton] || (cfg[:ops] && !cfg[:ops].include?(:delete))
+        end.each do |res|
+          define_action_method([:admin, res, :delete]) do |**kwargs|
+            res_id = kwargs[:"#{res}_id"]
+            c = aoc_res_cfg(res)
+            bulk_result(res_id, command: :delete) do |one_id|
+              aoc_api.delete("#{c[:path]}/#{one_id}")
+              {'id' => one_id}
+            end
+          end
+        end
+
+        # user > contacts > list|show|create|modify|delete (same API path as admin > contact)
+        Operations::ALL.each do |op|
+          define_action_method([:user, :contacts, op]) do |**ctx|
+            send(CommandSpec.action_method([:admin, :contact, op]), **ctx)
+          end
+        end
+
+        # admin > client > set_pub_key
+        def action_admin_client_set_pub_key(private_key_pem:, client_id:, **)
+          c = aoc_res_cfg(:client)
+          the_public_key = OpenSSL::PKey::RSA.new(private_key_pem).public_key.to_s
+          aoc_api.update("#{c[:path]}/#{client_id}", {jwt_grant_enabled: true, public_key: the_public_key})
+          Result::Success.new
+        end
+
+        # admin > ats — build and return an Ats plugin instance wired to the AoC ATS API.
+        # Used as delegate_instance: target so --help traverses the Ats registry.
+        # @return [Ats] configured Ats plugin instance
+        def build_ats_plugin
+          ats_api = Rest.new(**aoc_api.params.deep_merge({
+            base_url: "#{aoc_api.base_url}/admin/ats/pub/v1",
+            auth:     {params: {scope: Api::AoC::Scope::ADMIN_USER}}
+          }))
+          Ats.new(context: context, api: ats_api)
+        end
+
+        # admin > node > do | bearer_token — setup reuses the generic instance setup
+        # (setup_admin_node_instance is auto-generated above, providing res_id:)
+
+        # admin > node > do > <FILES_COMMAND>
+        FILES_COMMANDS.each do |cmd|
+          define_action_method([:admin, :node, :do, cmd]) do |node_id:, **ctx|
+            execute_nodegen4_command(cmd, node_id, scope: Api::Node::Scope::ADMIN, **ctx)
+          end
+        end
+
+        # admin > node > bearer_token
+        def action_admin_node_bearer_token(scope:, node_id:, **)
+          scope ||= Api::Node::Scope::ADMIN
+          node_api = aoc_api.node_api_from(node_id: node_id, scope: scope)
+          Result::Text.new(node_api.oauth.authorization)
+        end
+
+        # admin > workspace > dropbox — res_id: already in ctx via arguments:(:identifier)
+        def setup_admin_workspace_dropbox(workspace_id:, **)
+          {ws_res_id: workspace_id}
+        end
+
+        # admin > workspace > dropbox > list
+        def action_admin_workspace_dropbox_list(ws_res_id:, **)
+          query = options.get_option(:query) || {}
+          Result::ObjectList.new(aoc_api.read('dropboxes', query.merge({'workspace_id' => ws_res_id})), fields: %w[id name description])
+        end
+
+        # admin > workspace > shared_folder — res_id: already in ctx via arguments:(:identifier)
+        def setup_admin_workspace_shared_folder(workspace_id:, **)
+          resource_instance_path = "#{aoc_res_path(:workspace)}/#{workspace_id}"
+          query = options.get_option(:query) || Api::AoC.workspace_access(workspace_id).merge({'admin' => true})
+          shared_folders = aoc_api.read_with_paging("#{resource_instance_path}/permissions", query)[:items]
+          {ws_res_id: workspace_id, shared_folders: shared_folders}
+        end
+
+        # admin > workspace > shared_folder > list
+        def action_admin_workspace_shared_folder_list(shared_folders:, **)
+          Result::ObjectList.new(shared_folders, fields: %w[id node_name node_id file_id file.path tags.aspera.files.workspace.share_as])
+        end
+
+        # admin > workspace > shared_folder > node|member — sf_id: already in ctx via arguments:(:identifier)
+        def resolve_sf_item(shared_folders:, sf_id:, **)
+          sf_item = shared_folders.find { |i| i['id'].eql?(sf_id) }
+          Aspera.assert(sf_item, 'shared folder not found')
+          {sf_item: sf_item}
+        end
+
+        alias_method :setup_admin_workspace_shared_folder_node,   :resolve_sf_item
+        alias_method :setup_admin_workspace_shared_folder_member, :resolve_sf_item
+
+        # admin > workspace > shared_folder > node > <FILES_COMMAND>
+        FILES_COMMANDS.each do |cmd|
+          define_action_method([:admin, :workspace, :shared_folder, :node, cmd]) do |sf_item:, **ctx|
+            execute_nodegen4_command(cmd, sf_item['node_id'], file_id: sf_item['file_id'], scope: Api::Node::Scope::ADMIN, **ctx)
+          end
+        end
+
+        # admin > workspace > shared_folder > member > list
+        def action_admin_workspace_shared_folder_member_list(ws_res_id:, sf_item:, **)
+          node_api = aoc_api.node_api_from(
+            node_id:        sf_item['node_id'],
+            workspace_id:   ws_res_id,
+            workspace_name: nil,
+            scope:          Api::Node::Scope::USER
+          )
+          result = node_api.read('permissions', {'file_id' => sf_item['file_id'], 'tag' => "aspera.files.workspace.id=#{ws_res_id}"})
+          result.each do |item|
+            item['member'] = begin
+              if Api::AoC.workspace_access?(item)
+                {'name' => '[Internal permission]'}
+              else
+                aoc_api.read("admin/#{item['access_type']}s/#{item['access_id']}") rescue {'name' => 'not found'}
               end
+            rescue => e
+              {'name' => e.to_s}
             end
-          when :admin
-            return execute_admin_action
-          when :gateway
-            require 'aspera/faspex_gw'
-            parameters = value_create_modify(command: command, default: {}).symbolize_keys
-            uri = URI.parse(parameters.delete(:url){WebServerSimple::DEFAULT_URL})
-            server = WebServerSimple.new(uri, **parameters.slice(*WebServerSimple::PARAMS))
-            Aspera.assert(parameters.except(*WebServerSimple::PARAMS).empty?){"unexpected parameters: #{parameters.except(*WebServerSimple::PARAMS).keys}"}
-            server.mount(uri.path, Faspex4GWServlet, aoc_api, aoc_api.workspace_info[:id])
-            server.start
-            return Result::Status.new('Gateway terminated')
-          else Aspera.error_unreachable_line
           end
-          Aspera.error_unreachable_line
+          # TODO : read users and group name and add, if query "include_members"
+          Result::ObjectList.new(result, fields: %w[access_type access_id access_level last_updated_at member.name member.email member.system_group_type member.system_group])
+        end
+
+        # admin > user > preferences|notifications > show|modify
+        # (setup_admin_user_instance is auto-generated, providing res_id:)
+        %i[preferences notifications].each do |pref|
+          pref_path = pref.eql?(:preferences) ? 'user_interaction_preferences' : 'notification_preferences'
+          define_action_method([:admin, :user, pref, :show]) do |user_id:, **|
+            Result::SingleObject.new(aoc_api.read("#{aoc_res_path(:user)}/#{user_id}/#{pref_path}"))
+          end
+          define_action_method([:admin, :user, pref, :modify]) do |properties:, user_id:, **|
+            aoc_api.update("#{aoc_res_path(:user)}/#{user_id}/#{pref_path}", properties)
+            Result::Status.new('modified')
+          end
         end
 
-        private :execute_admin_action
+        # automation > workflows > action > * (TODO: not fully implemented)
+        %i[list create show].each do |cmd|
+          define_action_method([:automation, :workflows, :action, cmd]) do |wf_id:, **|
+            Log.log.warn { "Not implemented: #{cmd}" }
+            step = @automation_api.create('steps', {'workflow_id' => wf_id})
+            @automation_api.update("workflows/#{wf_id}", {'step_order' => [step['id']]})
+            action = @automation_api.create('actions', {'step_id' => step['id'], 'type' => 'manual'})
+            @automation_api.update("steps/#{step['id']}", {'action_order' => [action['id']]})
+            Result::SingleObject.new(@automation_api.read("workflows/#{wf_id}"))
+          end
+        end
+
+        def action_gateway(parameters: {}, **)
+          require 'aspera/faspex_gw'
+          parameters = parameters.symbolize_keys
+          uri = URI.parse(parameters.delete(:url) { WebServerSimple::DEFAULT_URL })
+          server = WebServerSimple.new(uri, **parameters.slice(*WebServerSimple::PARAMS))
+          Aspera.assert(parameters.except(*WebServerSimple::PARAMS).empty?) { "unexpected parameters: #{parameters.except(*WebServerSimple::PARAMS).keys}" }
+          server.mount(uri.path, Faspex4GWServlet, aoc_api, aoc_api.workspace_info[:id])
+          server.start
+          return Result::Status.new('Gateway terminated')
+        end
       end
     end
   end