docs: rewrite metadata section #7185 (#7221)

docs/admin/developer/agama/faq.md

@@ -9,13 +9,13 @@ tags:
 
 ## Common errors
 
-### Unable to find a constructor with arity ... in class ...
+### Unable to find a suitable constructor with arity ... in class ...
 
-A Java invocation of the form `Call package.className#new ...` is passing a number of parameters that does not match any of the existing constructors for that class. 
+A Java invocation of the form `Call package.className#new ...` is passing an incorrect number of arguments or their data types do not match the signature of any of the constructors for that class. 
 
-### Unable to find a method called ... with arity ... in class ...
+### Unable to find a suitable method called ... with arity ... in class ...
 
-A java invocation is attempting to call a method that is not part of the given class or the number of parameters passed for the method is not correct.
+A java invocation is attempting to call a method that is not part of the given class, the number of arguments passed for the method is not correct, or the arguments could not be converted to make a successful call.
 
 ### No Finish instruction was reached
 
@@ -25,7 +25,7 @@ This occurs when no `Finish` statement has been found in the execution of a flow
 
 Agama engine saves the state of a flow every time an [RRF](../../../agama/language-reference.md#rrf) or [RFAC](../../../agama/language-reference.md#rfac) instruction is reached. The _State_ can be understood as the set of all variables defined in a flow and their associated values up to certain point. 
 
-Most of times, variables hold basic Agama [values](../../../agama/language-reference.md#data-types) like strings, booleans, numbers, lists or maps, however, more complex values may appear due to Java `Call`s. The engine does its best  to properly serialize these Java objects, nonetheless, this is not always feasible. In these cases, the flow crashes and errors will appear on screen as well as in the server logs.
+Most of times, variables hold basic Agama [values](../../../agama/language-reference.md#data-types) like strings, booleans, numbers, lists or maps, however, more complex values may appear due to Java `Call`s. The engine does its best  to properly serialize these Java objects, nonetheless, this is not always possible. In these cases, the flow crashes and errors will appear on screen as well as in the server logs.
 
 Use the information in the logs to detect the problematic Java class. This would normally allow you to identify the variable that is causing the issue. Now you have several options to proceed:
 
@@ -41,7 +41,7 @@ In general, a good practice is to avoid handling complex variables in flows. Let
 
 ### What Groovy and Java versions are supported?
 
-Groovy 4.0 and Java 11. The runtime is Amazon Corretto 17.
+Groovy 4.0 and Java 8 or higher. The runtime is Amazon Corretto 17.
 
 ### How to add third party libraries?
 
@@ -122,9 +122,9 @@ This is to avoid traversing big structures fully. You can increase the value of
 
 ### How to add two numbers or compare numeric values in Agama?
 
-Agama only provides operators for equality check in conditional statements. The structure of an authentication flow will rarely have to deal with computations/comparisons of numbers, strings, etc. In case this is needed, developers have to resort to Java.
+Agama only provides operators for equality/inequality check in conditional statements. Comparisons like "less-than", "greater-than-or-equal", etc. require Java usage, however, the structure of an authentication flow will rarely have to deal with this kind of computations.
 
-_Hint_: some methods like `addExact`, `incrementExact`, etc. in `java.lang.Math` might help.  
+_Hint_: methods like `addExact`, `incrementExact`, etc. in `java.lang.Math` may help you to do some arithmetic.  
 
 ### How to concatenate strings in Agama?
 

docs/agama/gama-format.md

@@ -39,29 +39,41 @@ Except for `code` and `web` directories, all elements in the file structure abov
 
 ### Metadata
 
-`project.json` file is expected to contain metadata about the contents of the project in JSON format. This is an example:
+`project.json` file is expected to contain metadata about the contents of the project in JSON format. 
+
+|Field|Description|data type|
+|-|-|-|
+|`projectName`|A unique name that will be associated to this project|_string_|
+|`version`|Project's version. It is recommended to use semantic versioning format|_string_|
+|`author`|A user handle that identifies the author of the project|_string_|
+|`license`|A reference to applicable license terms|_string_|
+|`description`||_string_|
+|`configs`|Object containing exemplifying [configuration properties](./language-reference.md#header-basics) for flows that may need them. The keys of this field, if any, are qualified flow names already part of the project|_json object_|
+|`noDirectLaunch`|An array holding zero or more qualified flow names. This list is used to prevent certain flows to be launched directly from a web browser. It's a security measure to avoid end-users triggering flows at will|_array_|
+
+All fields are optional and more can be added if desired.
+
+Below is an example of a `project.json` file:
 
 ```
 {
-  "projectName": "A unique name that will be associated to this project",
-  "author": "A user handle that identifies you",
-  "description": "Other relevant data can go here",
-  "type": "",
+  "projectName": "biometric-auth",
+  "version": "2.0.3",
+  "author": "avgJoe123",
+  "license": "apache-2.0",
+  "description": "Allows users to authenticate via fingerpint and/or iris recognition",
   "configs": {
-    "com.foods.sweet": {
+    "com.acme.bio.IrisScan": {
         "prop1": "secret",
-        "prop2": [1, 2, 3]
+        "prop2": { "subprop": [1, 2, 3] }
     }
   },
-  "noDirectLaunch": [ "test" ]
+  "noDirectLaunch": [ "com.acme.bio.TraitExtractor" ]
 }
 ```
 
-The `configs` section is a JSON object containing exemplifying [configuration properties](./language-reference.md#header-basics) for flows that may need them. Note `.gama` files **must not** contain **real** configuration properties because these files can be freely distributed; in practice, configurations hold sensitive data that should not be exposed. The keys of object `configs`, if any, are qualified flow names already part of the project.  
-
-The `noDirectLaunch` section is an array holding zero or more qualified flow names. Use this list to prevent certain flows to be launched directly from a web browser. This is a security measure to avoid end-users triggering flows at will.
-
-Other fields can be added in `project.json`.
+!!! Important
+    Use the `configs` section wisely: `.gama` files **must not** contain **real** configuration properties because these files may be freely distributed; in practice, configurations hold sensitive data that should not be exposed
 
 ## Sample project