diff --git a/bycon/config.py b/bycon/config.py
index 04d491052..77c196d85 100644
--- a/bycon/config.py
+++ b/bycon/config.py
@@ -49,11 +49,17 @@
 # to be modified during execution ##############################################
 ################################################################################
 
+AUTHORIZATIONS = {
+  "anonymous": {"default": "boolean"},
+  "local": {"default": "record"}
+}
+
 BYC = {
   "DEBUG_MODE": False,
   "TEST_MODE": False,
   "ERRORS": [],
-  "WARNINGS": []
+  "WARNINGS": [],
+  "USER": "anonymous"
 }
 
 # collection object for cmd arguments and web parameters (depending on the ENV)
diff --git a/bycon/definitions/argument_definitions.yaml b/bycon/definitions/argument_definitions.yaml
index b6e424206..4e7908446 100644
--- a/bycon/definitions/argument_definitions.yaml
+++ b/bycon/definitions/argument_definitions.yaml
@@ -51,6 +51,7 @@ requested_granularity:
   cmdFlags:
     - --requestedGranularity
   description: The requested granularity of the beacon
+  default: record
 
 request_entity_path_id:
   type: string
@@ -345,8 +346,12 @@ output:
   cmdFlags:
     - --output
   description: >-
-        special output format; command line processing uses some predefined text as
-        standard, but options are e.g. json or pgxseg
+      For defining a special output format, mostly for `byconaut` services use.
+      Examples:
+
+      * `cnvstats`, for `analyses`, to present some CNV statistics
+      * `pgxseg`, using the `.pgxseg` variant file format
+      * `text`, for some services to deliver a text table instead of JSON
 
 include_handovers:
   type: boolean
diff --git a/bycon/definitions/authorizations.yaml b/bycon/definitions/authorizations.yaml
deleted file mode 100644
index 5c538c601..000000000
--- a/bycon/definitions/authorizations.yaml
+++ /dev/null
@@ -1,4 +0,0 @@
-anonymous:
-  default: boolean
-local:
-  default: record
\ No newline at end of file
diff --git a/bycon/definitions/beacon_defaults.yaml b/bycon/definitions/beacon_defaults.yaml
index 5279b7cef..336009d71 100644
--- a/bycon/definitions/beacon_defaults.yaml
+++ b/bycon/definitions/beacon_defaults.yaml
@@ -2,15 +2,10 @@ defaults:
   default_dataset_id: examplez
   request_path_root: beacon
   request_entity_path_id: info
-  assembly_id: GRCh38
   response_schema: beaconInfoResponse
   include_resultset_responses: HIT
   requested_granularity: record
   returned_granularity: record
-  user_name: anonymous
-  pagination:
-    skip: 0
-    limit: 200
   response_entity:
     entity_type: info
     response_schema: beaconInfoResponse
diff --git a/bycon/definitions/variant_request_definitions.yaml b/bycon/definitions/variant_request_definitions.yaml
index 25fdd2a25..0dd8ed450 100644
--- a/bycon/definitions/variant_request_definitions.yaml
+++ b/bycon/definitions/variant_request_definitions.yaml
@@ -1,10 +1,10 @@
 ################################################################################
 #
-# TODO: use definitions directly from model -> genomicVariations -> requestParameters
+# TODO: Beacon scouts for VQS ...
 #
 ################################################################################
 
-variant_pars:
+request_pars:
   - assembly_id
   - reference_name
   - mate_name
@@ -18,8 +18,6 @@ variant_pars:
   - gene_id
   - aminoacid_change
   - genomic_allele_short_form
-  - cyto_bands  # custom yet
-  - chro_bases  # custom yet
 
 # As long as there are no variant query schemas to define valid Beacon
 # variant parameter combinations the `request_types` here provide sets
diff --git a/bycon/lib/beacon_auth.py b/bycon/lib/beacon_auth.py
index 4247f3d73..9e7c1147f 100644
--- a/bycon/lib/beacon_auth.py
+++ b/bycon/lib/beacon_auth.py
@@ -11,38 +11,46 @@
 
 def set_user_name(byc):
     """
-    The default user is `anonymous`. If the environment is local the `local` user
-    will be assumed - but can be overwritten later, e.g. for testing purposes.
+    The default user is `anonymous`. Their access granularity is defined in 
+    `config.py` => `AUTH_DEFAULTS`.
+    If the environment is local the `local` user will be assumed - but can be
+    overwritten later, e.g. for testing purposes.
     """
     # local user has full permissions
     if "local" in ENV:
-        byc.update({"user_name": "local"})
-        return
-    un = BYC_PARS.get("user", "anonymous")
-    if un in byc.get("authorizations", {}):
-        byc.update({"user_name": un})
+        BYC.update({"USER": "local"})
+    elif (un := BYC_PARS.get("user_name", "anonymous")) in byc.get("authorizations", {}):
+        BYC.update({"USER": un})
 
 
 ################################################################################
 
 def set_returned_granularities(byc):
     rg = BYC_PARS.get("requested_granularity", "record")
-    un = byc.get("user_name", "anonymous")
     auth = byc.get("authorizations", {})
     ds_ids = byc.get("dataset_ids", [])
 
+    for ak, av in auth.items():
+        AUTHORIZATIONS.update({ak: av})
+
     g_l_s = [0]
     r_g_l = GRANULARITY_LEVELS.get(rg, 0)
 
     if not "authorized_granularities" in byc:
         byc.update({"authorized_granularities": {}})
-    for ds_id in byc["dataset_ids"]:
+
+    for ds_id in ds_ids:
         byc["authorized_granularities"].update({ds_id: rg})
-        ugs = auth.get(un, {})
+        
+        # the user is checked against predefined authorizations
+        if not (ugs := auth.get(BYC["USER"])):
+            continue
+        prdbug(f'USER {BYC["USER"]} - authorizations {ugs}')
+
+        g_l_l = ugs.get("default", "___none___")
         if ds_id in ugs:
             g_l_l = ugs[ds_id]
-        elif "default" in ugs:
-            g_l_l = ugs["default"]
+
         d_g_l = GRANULARITY_LEVELS.get(g_l_l, 0)
         if d_g_l <= r_g_l:
             byc["authorized_granularities"].update({ds_id: g_l_l})
@@ -50,8 +58,10 @@ def set_returned_granularities(byc):
 
     m_g_l = max(g_l_s)
 
+    prdbug(f'Granularity levels: {g_l_s} - max: {m_g_l} - requested: {r_g_l}')
+
     if m_g_l < r_g_l:
-        prdbug("Warning: Requested granularity exceeds user authorization - using a maximum of %s" % byc["returned_granularity"])
+        prdbug(f'Warning: Requested granularity exceeds user authorization - using a maximum of {byc["returned_granularity"]}')
         byc.update({"returned_granularity": list(GRANULARITY_LEVELS.keys())[m_g_l]})
     else:
         byc.update({"returned_granularity": list(GRANULARITY_LEVELS.keys())[r_g_l]})
diff --git a/bycon/lib/beacon_response_generation.py b/bycon/lib/beacon_response_generation.py
index 2a7e36dbe..97e7013ea 100644
--- a/bycon/lib/beacon_response_generation.py
+++ b/bycon/lib/beacon_response_generation.py
@@ -113,7 +113,7 @@ def __init__(self, byc: dict):
         self.user_name = byc.get("user_name", "anonymous")
         self.entity_defaults = self.beacon_defaults.get("entity_defaults", {"info":{}})
         self.response_schema = byc["response_schema"]
-        self.returned_granularity = BYC_PARS.get("requested_granularity", "record")
+        self.returned_granularity = byc.get("returned_granularity", "boolean")
         self.include_handovers = BYC_PARS.get("include_handovers", False)
         self.beacon_schema = byc["response_entity"].get("beacon_schema", "___none___")
         self.record_queries = {}
@@ -138,7 +138,7 @@ def resultsetResponse(self):
 
         self.data_response["response"].update({"result_sets": self.result_sets})
         self.__resultset_response_update_summaries()
-        self.__resultSetResponse_force_granularities()
+        self.__resultSetResponse_force_autorized_granularities()
 
         b_h_o = self.data_response.get("beacon_handovers", [])
         if len(b_h_o) < 1:
@@ -215,7 +215,7 @@ def __check_switch_to_error_response(self):
 
     # -------------------------------------------------------------------------#
 
-    def __resultSetResponse_force_granularities(self):
+    def __resultSetResponse_force_autorized_granularities(self):
         prdbug(f'authorized_granularities: {self.authorized_granularities}')
         for rs in self.data_response["response"]["result_sets"]:
             rs_granularity = self.authorized_granularities.get(rs["id"], "boolean")
diff --git a/bycon/lib/bycon_helpers.py b/bycon/lib/bycon_helpers.py
index 68ecac8e9..a3c5bb985 100644
--- a/bycon/lib/bycon_helpers.py
+++ b/bycon/lib/bycon_helpers.py
@@ -182,14 +182,11 @@ def mongo_test_mode_query(db_name, coll_name, test_mode_count=5):
 ################################################################################
 
 def assign_nested_value(parent, dotted_key, v, parameter_definitions={}):
-
     parameter_type = parameter_definitions.get("type", "string")
     parameter_default = parameter_definitions.get("default")
-
     if v is None:
         if parameter_default:
             v = parameter_default
-
     if v is None:
         return parent
 
diff --git a/bycon/lib/parse_variant_request.py b/bycon/lib/parse_variant_request.py
index ca5b830db..8d0b30192 100644
--- a/bycon/lib/parse_variant_request.py
+++ b/bycon/lib/parse_variant_request.py
@@ -14,7 +14,7 @@ def parse_variants(byc):
 ################################################################################
 
 def __parse_variant_parameters(byc):
-    v_p_s = byc["variant_request_definitions"].get("variant_pars", [])
+    v_p_s = byc["variant_request_definitions"].get("request_pars", [])
     a_defs = byc.get("argument_definitions", {})
     v_t_defs = byc["variant_type_definitions"]
 
diff --git a/bycon/lib/response_remapping.py b/bycon/lib/response_remapping.py
index f14684e40..eac73c9aa 100644
--- a/bycon/lib/response_remapping.py
+++ b/bycon/lib/response_remapping.py
@@ -91,10 +91,8 @@ def remap_variants(r_s_res, byc):
 def remap_analyses(r_s_res, byc):
     if not "analysis" in byc["response_entity_id"]:
         return r_s_res
-
     pop_keys = ["info", "provenance", "cnv_statusmaps", "cnv_chro_stats", "cnv_stats"]
-
-    if "cnvstats" in byc.get("output", "___none___").lower():
+    if "cnvstats" in BYC_PARS.get("output", "___none___").lower():
         pop_keys = ["info", "provenance", "cnv_statusmaps"]
 
     for cs_i, cs_r in enumerate(r_s_res):
@@ -102,7 +100,6 @@ def remap_analyses(r_s_res, byc):
         r_s_res[cs_i].update({"pipeline_name": "progenetix", "analysis_date": "1967-11-11"})
         for k in pop_keys:
             r_s_res[cs_i].pop(k, None)
-
     return r_s_res
 
 
diff --git a/bycon/lib/variant_mapping.py b/bycon/lib/variant_mapping.py
index 2065df08a..4cec88bb9 100644
--- a/bycon/lib/variant_mapping.py
+++ b/bycon/lib/variant_mapping.py
@@ -13,12 +13,12 @@
 ################################################################################
 
 class ByconVariant:
-
+    
     def __init__(self, byc, variant={}):
         """
         # Class `ByconVariant`
 
-        The class provides methods for the conversion ofgenomic variant objects
+        The class provides methods for the conversion of genomic variant objects
         with slight variations in their input parameters to a "canonical" intermediary
         `byc_variant` type, and from there then map per function to other formats
         (such as the Progenetix database format, VCF or VRS).
@@ -27,8 +27,6 @@ def __init__(self, byc, variant={}):
         Progenetix platform and does not cover some use cases outside of Progenetix
         and Beacon "common use" scenarios (as of Beacon v2 / 2023).
         """
-
-        self.byc = byc
         self.byc_variant = {}
         self.pgx_variant = {}
         self.vrs_variant = {}
@@ -36,12 +34,14 @@ def __init__(self, byc, variant={}):
         self.pgxseg_variant = {}
 
         self.ChroNames = ChroNames()
-
         self.variant_types = byc.get("variant_type_definitions", {})
+
+        # datatable mappings contain the "name to place in object" definitions
+        # these are in essence identical to the `db_key` mappings in
+        # `argument_definitions` but logically different (query vs. defiition; `default`...)
         d_m = byc["datatable_mappings"].get("definitions", {})
         d_m_v = d_m.get("genomicVariant", {})
         self.variant_mappings = d_m_v.get("parameters", {})
-
         self.vrs_allele = object_instance_from_schema_name(byc, "VRSallele", "")
         self.vrs_cnv = object_instance_from_schema_name(byc, "VRScopyNumberChange", "")
 
@@ -155,6 +155,7 @@ def vrsVariant(self, variant={}):
         self.vrs_variant.update(vrs_v)
         return self.vrs_variant
 
+
     # -------------------------------------------------------------------------#
 
     def __vrs_allele(self):
diff --git a/docs/generated/argument_definitions.md b/docs/generated/argument_definitions.md
new file mode 100644
index 000000000..fc8582d81
--- /dev/null
+++ b/docs/generated/argument_definitions.md
@@ -0,0 +1,494 @@
+# `bycon` Arguments and Parameters
+The following is a list of arguments and parameters used in the `bycon` package as well as the `byconaut` tools.
+## Definitions
+### `user_name` 
+**type:** string    
+**pattern:** `^\w+$`    
+**cmdFlags:** `--userName`    
+**description:**
+faking a user name    
+
+### `test_mode` 
+**type:** string    
+**cmdFlags:** `-t,--testMode`    
+**description:**
+test setting, i.e. returning some random documents    
+**default:** `False`    
+
+### `skip` 
+**type:** integer    
+**cmdFlags:** `--skip`    
+**description:**
+pages to be skipped    
+**default:** `0`    
+
+### `limit` 
+**type:** integer    
+**cmdFlags:** `-l,--limit`    
+**description:**
+limit number of documents; a value of 0 sets to unlimited    
+**default:** `200`    
+
+### `requested_granularity` 
+**type:** string    
+**pattern:** `^\w+$`    
+**description:**
+The requested granularity of the beacon    
+**cmdFlags:** `--requestedGranularity`    
+**default:** `record`    
+
+### `request_entity_path_id` 
+**type:** string    
+**cmdFlags:** `--requestEntityPathId`    
+**description:**
+required data entry point, equal to the first REST path element in Beacon    
+
+### `requested_schema` 
+**type:** string    
+**cmdFlags:** `--requestedSchema`    
+**description:**
+requested schema, e.g. biosample    
+
+### `include_resultset_responses` 
+**type:** string    
+**cmdFlags:** `--includeResultsetResponses`    
+**description:**
+requested schema, e.g. biosample    
+
+### `dataset_ids` 
+**type:** array    
+**items:** string    
+**cmdFlags:** `-d,--datasetIds`    
+**description:**
+dataset ids    
+
+### `filters` 
+**type:** array    
+**items:** string    
+**cmdFlags:** `--filters`    
+**description:**
+prefixed filter values, comma concatenated    
+
+### `filter_precision` 
+**type:** string    
+**cmdFlags:** `--filterPrecision`    
+**description:**
+`either` start or `exact` (`exact being internal default`) for matching filter values    
+**default:** `exact`    
+
+### `filter_logic` 
+**type:** string    
+**cmdFlags:** `--filterLogic`    
+**description:**
+either OR or AND (translated to the MongoDB $and etc.)    
+**default:** `AND`    
+
+### `include_descendant_terms` 
+**type:** boolean    
+**cmdFlags:** `--includeDescendantTerms`    
+**description:**
+global treatment of descendant terms    
+**default:** `True`    
+
+### `assembly_id` 
+**type:** string    
+**pattern:** `^\w+?[\w\-\.]*?\w*?$`    
+**db_key:** assembly_id    
+**cmdFlags:** `--assemblyId`    
+**description:**
+assembly id    
+**default:** `GRCh38`    
+
+### `reference_name` 
+**type:** string    
+**db_key:** location.sequence_id    
+**pattern:** `^\w+.*?\w?$`    
+**cmdFlags:** `--referenceName`    
+**description:**
+chromosome    
+
+### `mate_name` 
+**type:** string    
+**db_key:** location.sequence_id    
+**pattern:** `^\w+.*?\w?$`    
+**cmdFlags:** `--mateName`    
+**description:**
+chromosome    
+
+### `reference_bases` 
+**type:** string    
+**db_key:** reference_sequence    
+**pattern:** `^[ACGTN]+$`    
+**cmdFlags:** `--referenceBases`    
+**description:**
+reference bases    
+
+### `alternate_bases` 
+**type:** string    
+**db_key:** sequence    
+**pattern:** `^[ACGTN]+$`    
+**cmdFlags:** `--alternateBases`    
+**description:**
+alternate bases    
+
+### `variant_type` 
+**type:** string    
+**db_key:** variant_state.id    
+**pattern:** `^\w+[\w \-\:]\w+?$`    
+**cmdFlags:** `--variantType`    
+**description:**
+variant type, e.g. DUP    
+
+### `start` 
+**type:** array    
+**db_key:** location.start    
+**items:**  
+    - `type`: `integer`      
+    - `pattern`: `^\d+?$`    
+**cmdFlags:** `--start`    
+**description:**
+genomic start position    
+
+### `end` 
+**type:** array    
+**db_key:** location.end    
+**items:**  
+    - `type`: `integer`      
+    - `pattern`: `^\d+?$`    
+**cmdFlags:** `--end`    
+**description:**
+genomic end position    
+
+### `variant_min_length` 
+**type:** integer    
+**db_key:** info.var_length    
+**pattern:** `^\d+?$`    
+**cmdFlags:** `--variantMinLength`    
+**description:**
+variantMinLength: The minimal variant length in bases for e.g. CNV queries.    
+
+### `variant_max_length` 
+**type:** integer    
+**db_key:** info.var_length    
+**pattern:** `^\d+?$`    
+**cmdFlags:** `--variantMaxLength`    
+**description:**
+variantMaxLength: The maximum variant length in bases for e.g. CNV queries.    
+
+### `gene_id` 
+**type:** string    
+**db_key:** None    
+**pattern:** `^\w+?(\w+?(\-\w+?)?)?$`    
+**cmdFlags:** `--geneId`    
+**description:**
+gene id    
+
+### `aminoacid_change` 
+**type:** string    
+**db_key:** molecular_attributes.aminoacid_changes    
+**pattern:** `^\w+?$`    
+**examples:** `V600E,M734V,G244A`    
+**cmdFlags:** `--aminoacidChange`    
+**description:**
+Aminoacid alteration in 1 letter format    
+
+### `genomic_allele_short_form` 
+**type:** string    
+**db_key:** identifiers.genomicHGVS_id    
+**pattern:** `^\w+.*\w$`    
+**examples:** `NC_000017.11:g.7674232C>G`    
+**cmdFlags:** `--genomicAlleleShortForm`    
+**description:**
+Genomic HGVSId descriptor    
+
+### `variant_internal_id` 
+**type:** string    
+**db_key:** variant_internal_id    
+**pattern:** `^\w[\w\:\-\,]+?\w$`    
+**examples:** `11:52900000-134452384:EFO_0030067`    
+**cmdFlags:** `--variantInternalId`    
+**description:**
+An id value used for all variant instances of the same composition; a kind of `digest`    
+
+### `accessid` 
+**type:** string    
+**db_key:** id    
+**pattern:** `^\w[\w\-]+?\w$`    
+**examples:** `b59857bc-0c4a-4ac8-804b-6596c6566494`    
+**cmdFlags:** `--accessid`    
+**description:**
+An accessid for retrieving handovers etc.    
+
+### `file_id` 
+**type:** string    
+**pattern:** `^\w[\w\-]+?\w$`    
+**examples:** `90e19951-1443-4fa8-8e0b-6b5d8c5e45cc`    
+**cmdFlags:** `--fileId`    
+**description:**
+A file id e.g. as generated by the uploader service    
+
+### `id` 
+**type:** string    
+**db_key:** id    
+**pattern:** `^\w[\w\:\-\,]+?\w$`    
+**examples:** `pgxvar-5bab576a727983b2e00b8d32,pgxind-kftx25eh`    
+**cmdFlags:** `--id`    
+**description:**
+An id; this parameter only makes sense for specific REST entry types    
+
+### `ids` 
+**type:** array    
+**items:** string    
+**cmdFlags:** `--ids`    
+**description:**
+One or more ids; this parameter only makes sense for specific REST entry types    
+
+### `biosample_ids` 
+**type:** array    
+**items:** string    
+**cmdFlags:** `--biosampleIds`    
+**description:**
+biosample ids    
+
+### `analysis_ids` 
+**type:** array    
+**items:** string    
+**cmdFlags:** `--analysisIds`    
+**description:**
+callset / analysis ids    
+
+### `callset_ids` 
+**type:** array    
+**items:** string    
+**cmdFlags:** `--callsetIds`    
+**description:**
+callset / analysis ids    
+
+### `individual_ids` 
+**type:** array    
+**items:** string    
+**cmdFlags:** `--individualIds`    
+**description:**
+subject ids    
+
+### `variant_ids` 
+**type:** array    
+**items:** string    
+**cmdFlags:** `--variantIds`    
+**description:**
+variant ids    
+
+### `debug_mode` 
+**type:** boolean    
+**cmdFlags:** `--debugMode`    
+**description:**
+debug setting    
+
+### `show_help` 
+**type:** boolean    
+**cmdFlags:** `--showHelp`    
+**description:**
+specific help display    
+
+### `test_mode_count` 
+**type:** integer    
+**cmdFlags:** `--testModeCount`    
+**description:**
+setting the number of documents reurned in test mode    
+**default:** `5`    
+
+### `output` 
+**type:** string    
+**cmdFlags:** `--output`    
+**description:**
+For defining a special output format, mostly for `byconaut` services use. Examples:
+    
+* `cnvstats`, for `analyses`, to present some CNV statistics     
+* `pgxseg`, using the `.pgxseg` variant file format     
+* `text`, for some services to deliver a text table instead of JSON    
+
+### `include_handovers` 
+**type:** boolean    
+**default:** `True`    
+**cmdFlags:** `--includeHandovers`    
+**description:**
+only used for web requests & testing    
+
+### `only_handovers` 
+**type:** boolean    
+**default:** `False`    
+**cmdFlags:** `--onlyHandovers`    
+**description:**
+only used for web requests & testing    
+
+### `method` 
+**type:** string    
+**cmdFlags:** `--method`    
+**description:**
+special method    
+**default:** `None`    
+
+### `group_by` 
+**type:** string    
+**cmdFlags:** `-g,--groupBy`    
+**description:**
+group parameter e.g. for subset splitting    
+**default:** `text`    
+
+### `parse` 
+**type:** string    
+**cmdFlags:** `-p,--parse`    
+**description:**
+input value to be parsed    
+
+### `mode` 
+**type:** string    
+**cmdFlags:** `-m,--mode`    
+**description:**
+mode, e.g. file type    
+
+### `key` 
+**type:** string    
+**cmdFlags:** `-k,--key`    
+**description:**
+some key or word    
+
+### `update` 
+**type:** string    
+**cmdFlags:** `-u,--update`    
+**description:**
+update existing records    
+**default:** `False`    
+
+### `inputfile` 
+**type:** string    
+**cmdFlags:** `-i,--inputfile`    
+**description:**
+a custom file to specify input data, usually tab-delimited with special header    
+
+### `outputdir` 
+**type:** string    
+**cmdFlags:** `--outputdir`    
+**description:**
+output directory where supported (cmd line)    
+
+### `outputfile` 
+**type:** string    
+**cmdFlags:** `-o,--outputfile`    
+**description:**
+output file where supported (cmd line)    
+
+### `randno` 
+**type:** integer    
+**cmdFlags:** `-r,--randno`    
+**description:**
+random number to limit processing, where supported    
+**default:** `0`    
+
+### `min_number` 
+**type:** integer    
+**cmdFlags:** `--minNumber`    
+**description:**
+minimal number, e.g. for collations, where supported    
+**default:** `0`    
+
+### `source` 
+**type:** string    
+**cmdFlags:** `-s,--source`    
+**description:**
+some source label, e.g. `analyses`    
+
+### `query` 
+**type:** string    
+**cmdFlags:** `-q,--query`    
+**description:**
+complete query string, e.g. `{"biosamples":{"external_references.id":"geo:GSE7428"}}`    
+
+### `delivery_keys` 
+**type:** array    
+**items:** string    
+**cmdFlags:** `--deliveryKeys`    
+**description:**
+delivery keys    
+
+### `collation_types` 
+**type:** array    
+**items:** string    
+**cmdFlags:** `--collationTypes`    
+**description:**
+selected collation types, e.g. "EFO"    
+
+### `with_samples` 
+**type:** integer    
+**cmdFlags:** `--withSamples`    
+**description:**
+only for the collations; number of code_matches...    
+
+### `selected_beacons` 
+**type:** array    
+**items:** string    
+
+### `genome_binning` 
+**type:** string    
+**default:** `1Mb`    
+**cmdFlags:** `--genomeBinning`    
+**description:**
+one of the predefined genome binning keys - default 1Mb    
+
+### `cyto_bands` 
+**type:** string    
+**db_key:** None    
+**pattern:** `^(?:chro?)?([12]?[\dXY])([pq](?:(?:ter)|(?:cen)|(?:[1-4](?:\d(?:\.\d\d*?)?)?)?))?\-?([pq](?:(?:cen)|(?:ter)|(?:[1-4](?:\d(?:\.\d\d*?)?)?)?))?$`    
+**cmdFlags:** `--cytoBands`    
+**description:**
+cytobands, e.g. 8q21q24.1    
+
+### `chro_bases` 
+**type:** string    
+**db_key:** None    
+**pattern:** `^(chro?)?([12]?[\dXY])\:(\d+?)(\-(\d+?))?$`    
+**cmdFlags:** `--chroBases`    
+**description:**
+only for the cytoband converter ... e.g. 8:0-120000000    
+
+### `city` 
+**type:** string    
+**cmdFlags:** `-c,--city`    
+**description:**
+only for the geolocations...    
+
+### `geo_latitude` 
+**type:** number    
+**cmdFlags:** `--geoLatitude`    
+**description:**
+only for the geolocations...    
+
+### `geo_longitude` 
+**type:** number    
+**cmdFlags:** `--geoLongitude`    
+**description:**
+only for the geolocations...    
+
+### `geo_distance` 
+**type:** integer    
+**cmdFlags:** `--geoDistance`    
+**description:**
+only for the geolocations...    
+
+### `marker_type` 
+**type:** string    
+**cmdFlags:** `--markerType`    
+**description:**
+marker type, only for the geolocations...    
+
+### `plot_pars` 
+**type:** string    
+**cmdFlags:** `--plotPars`    
+**description:**
+plot parameters in form `par=value` concatenated by `::`    
+
+### `plot_type` 
+**type:** string    
+**cmdFlags:** `--plotType`    
+**description:**
+plot type (histoplot, samplesplot, arrayplot - more?)    
diff --git a/docs/generated/plot_defaults.md b/docs/generated/plot_defaults.md
new file mode 100644
index 000000000..c6aae7184
--- /dev/null
+++ b/docs/generated/plot_defaults.md
@@ -0,0 +1,338 @@
+# Plot Parameters and Information
+## Plot Types
+### `histoplot` 
+**description:**
+The default option, used to plot histograms of the CNV frequencies per data collection ("collation") or aggregated sample data.    
+**data_key:** interval_frequencies_bundles    
+**data_type:** collations    
+
+### `histoheatplot` 
+**description:**
+A "heatmap" style version of the histogram plot, where a single gain/loss frequency result is transformed into a small heat color strip.    
+**data_key:** interval_frequencies_bundles    
+**data_type:** collations    
+
+### `histosparkplot` 
+**description:**
+A version of the histogram with predefined parameters for representing a small and unlabeled plot, e.g. for use in hover previews. As in the normal histogram parameters can be overridden.    
+**data_key:** interval_frequencies_bundles    
+**data_type:** collations    
+**mods:**  
+    - `plot_chro_height`: `0`      
+    - `plot_title_font_size`: `0`      
+    - `plot_area_height`: `18`      
+    - `plot_margins`: `0`      
+    - `plot_axislab_y_width`: `0`      
+    - `plot_grid_stroke`: `0`      
+    - `plot_footer_font_size`: `0`      
+    - `plot_width`: `480`      
+    - `plot_area_opacity`: `0`      
+    - `plot_dendrogram_width`: `0`      
+    - `plot_labelcol_width`: `0`      
+    - `plot_axis_y_max`: `80`    
+**modded:** histoplot    
+
+### `samplesplot` 
+**description:**
+A plot of the called CNV segments per sample, with the samples ordered by their clustering (_i.e._ similarity of binned CNV data).    
+**data_key:** callsets_variants_bundles    
+**data_type:** samples    
+
+## Plot Parameters
+### `plot_id` 
+**default:** `genomeplot`    
+
+### `plot_title` 
+**description:**
+title above the plot    
+
+### `plot_group_by` 
+**description:**
+group samples in histograms by a filter type (NCIT, PMID...)    
+**default:** ``    
+
+### `plot_filter_empty_samples` 
+**description:**
+By setting to `true` samples w/o data can be removed e.g. from sample plots    
+**type:** boolean    
+**default:** `False`    
+
+### `force_empty_plot` 
+**description:**
+By setting to `true` a plot strip will be forced even if there are no CNV samples    
+**type:** boolean    
+**default:** `False`    
+
+### `plot_cluster_results` 
+**description:**
+By setting to `false` clustering can be suppressed    
+**type:** boolean    
+**default:** `True`    
+
+### `plot_samples_cluster_type` 
+**description:**
+Selection of which measurees are used to generate the clustering matrix
+    
+* `intcoverage` uses the ~2x3k (gain, loss) 1MB intervals     
+* `chrostats` only uses the CNV coverage per chromosomal arm (separately
+  for gains and losses)    
+**default:** `intcoverage`    
+**oneOf:** `chrostats,intcoverage`    
+
+### `plot_cluster_metric` 
+**default:** `ward`    
+**oneOf:** `average,centroid,complete,median,single,ward,weighted`    
+
+### `plot_dup_color` 
+**default:** `#FFC633`    
+
+### `plot_amp_color` 
+**default:** `#FF6600`    
+
+### `plot_del_color` 
+**default:** `#33A0FF`    
+
+### `plot_homodel_color` 
+**default:** `#0033CC`    
+
+### `plot_loh_color` 
+**default:** `#0066FF`    
+
+### `plot_snv_color` 
+**default:** `#FF3300`    
+
+### `plot_chros` 
+**type:** array    
+**items:** string    
+**default:** `1,2,3,4,5,6,7,8,9,10,11,12,13,14,15,16,17,18,19,20,21,22`    
+
+### `plot_width` 
+**description:**
+    
+* width of the plot image, in px     
+* the plot area width is determined through
+    - `plot_width - 2    
+*plot_margins - plot_labelcol_width - plot_axislab_y_width - plot_dendrogram_width`    
+**type:** integer    
+**default:** `1024`    
+
+### `plot_area_height` 
+**description:**
+height of the plot area (applies only to histogram plots)    
+**type:** integer    
+**default:** `100`    
+
+### `plot_axis_y_max` 
+**description:**
+    
+* frequency value the maximum of the Y-axis corresponds to     
+* use this to e.g. spread values if a max. of less than 100 is expected    
+**type:** integer    
+**default:** `100`    
+
+### `plot_samplestrip_height` 
+**description:**
+height of a single sample strip    
+**type:** integer    
+**default:** `12`    
+
+### `plot_margins` 
+**description:**
+outer plot margins, in px    
+**type:** integer    
+**default:** `25`    
+
+### `plot_labelcol_width` 
+**description:**
+    
+* width of the space for left text labels (e.g. sample ids, collation
+  labels)
+    
+* defaults to 0 when only one item    
+**type:** integer    
+**default:** `220`    
+
+### `plot_axislab_y_width` 
+**description:**
+width of the space for histogram percentage markers    
+**type:** integer    
+**default:** `30`    
+
+### `plot_dendrogram_width` 
+**description:**
+    
+* width of the cluster tree     
+* defaults to 0 when no clustering is being performed    
+**type:** integer    
+**default:** `50`    
+
+### `plot_dendrogram_color` 
+**description:**
+color of the cluster tree stroke    
+**default:** `#333333`    
+
+### `plot_dendrogram_stroke` 
+**description:**
+thickness of the cluster tree stroke    
+**type:** number    
+**default:** `0.5`    
+
+### `plot_chro_height` 
+**description:**
+height (well, width...) of the chromosomes in the ideogram strip    
+**type:** integer    
+**default:** `14`    
+
+### `plot_region_gap_width` 
+**type:** integer    
+**default:** `3`    
+
+### `plot_canvas_color` 
+**description:**
+color of the document background    
+**default:** `#ffffff`    
+
+### `plot_area_color` 
+**description:**
+color of the plot area background    
+**default:** `#eef6ff`    
+
+### `plot_area_opacity` 
+**description:**
+opacity of the plot background    
+**type:** number    
+**default:** `0.8`    
+
+### `plot_heat_intensity` 
+**description:**
+factor for frequency heatmap value brightness    
+**type:** number    
+**default:** `1`    
+
+### `plot_grid_stroke` 
+**type:** integer    
+**default:** `1`    
+
+### `plot_grid_color` 
+**description:**
+color of grid lines    
+**default:** `#c0e3ee`    
+
+### `plot_grid_opacity` 
+**type:** float    
+**default:** `0.8`    
+
+### `plot_font_color` 
+**default:** `#000000`    
+
+### `plot_font_size` 
+**description:**
+font size, in px    
+**type:** integer    
+**default:** `10`    
+
+### `plot_title_font_size` 
+**description:**
+title font size, in px    
+**type:** integer    
+**default:** `16`    
+
+### `plot_labelcol_font_size` 
+**description:**
+label font size (left column), in px    
+**type:** integer    
+**default:** `12`    
+
+### `plot_label_y_font_size` 
+**description:**
+font size for Y-axis labels (percents ...)    
+**type:** integer    
+**default:** `8`    
+
+### `plot_label_y_font_color` 
+**description:**
+font color for Y-axis labels (percents ...)    
+**default:** `#666666`    
+
+### `plot_label_y_values` 
+**type:** array    
+**items:** integer    
+**default:** `25,50,75`    
+
+### `plot_label_y_unit` 
+**type:** string    
+**default:** `%`    
+
+### `plot_probe_y_factor` 
+**description:**
+relative y-scaling of the probes in array-/probeplots    
+**type:** integer    
+**default:** `1`    
+
+### `plot_probe_label_y_values` 
+**type:** array    
+**items:** number    
+**default:** `1,2,3,4,5,6,7,8,9`    
+
+### `plot_probedot_size` 
+**type:** integer    
+**default:** `1`    
+
+### `plot_probedot_opacity` 
+**type:** integer    
+**default:** `222`    
+
+### `plot_region_labels` 
+**description:**
+    
+* placeholder for markers / labels in the     
+* format is `8:120000000-124000000:Region+of+Interest`     
+* comma-concatenation for multiple values     
+* label is optional    
+**type:** array    
+
+### `plot_regionlabel_color` 
+**default:** `#ddceff`    
+
+### `plot_gene_symbols` 
+**description:**
+    
+* label a gene's position by its symbol (CDKN2A, MYC, ERBB2...)     
+* comma-concatenation for multiple values    
+**type:** array    
+
+### `plot_cytoregion_labels` 
+**description:**
+    
+* label a cytoband's position (8q24, 1p12p11, 17q...)     
+* comma-concatenation for multiple values    
+**type:** array    
+
+### `plot_cytoregion_color` 
+**default:** `#ffe3ee`    
+
+### `plot_marker_font_color` 
+**description:**
+font color for gene and region markers    
+**default:** `#dd3333`    
+
+### `plot_marker_font_size` 
+**type:** integer    
+**default:** `10`    
+
+### `plot_marker_label_padding` 
+**description:**
+text padding of markers versus background/box    
+**type:** integer    
+**default:** `4`    
+
+### `plot_marker_lane_padding` 
+**type:** integer    
+**default:** `2`    
+
+### `plot_footer_font_size` 
+**type:** integer    
+**default:** `10`    
+
+### `plot_footer_font_color` 
+**default:** `#999999`    
diff --git a/mkdocs.yaml b/mkdocs.yaml
index 24c58cdaa..572d5efe7 100644
--- a/mkdocs.yaml
+++ b/mkdocs.yaml
@@ -11,6 +11,7 @@ nav:
   - Installation: installation
   - Recent Changes: changes
   - Upcoming & To Do: future
+  - Parameters: generated/argument_definitions
   - API Tests: tests
   - Code notes: code-notes
   - Progenetix Site: http://progenetix.org