docs: enhance README with usage examples and clarify command outputs

Author: janezlapajne

README.md

@@ -65,7 +65,7 @@ python ./source/main.py --version
 
 ## 🚀 Usage
 
-```
+``` zsh
 $ siapy-cli --help
 
 Usage: siapy-cli [OPTIONS] COMMAND [ARGS]...
@@ -82,6 +82,8 @@ Commands:
   analysis        Analysis commands, e.g., train model, generate metrics, etc.
 ```
 
+During execution, all artifacts (including required data, transformed images, extracted signatures, models, etc.) are saved in the `siapy-cli/artifacts` directory.
+
 ## 📖 Cookbook
 
 This guide provides an opinionated step-by-step workflow for using the `siapy-cli` tool.
@@ -228,34 +230,69 @@ Verify proper data loading:
 siapy-cli analysis test-load-data --data-loader DataLoaderExample
 ```
 
-- This command returns the number of images, number of labels, and unique labels in the dataset.
+- This command returns an array of signatures and their corresponding labels.
+- Use `--data-loader` to specify the data loader class.
+- Ensure the number of signatures matches the number of labels.
 
 2. Train and optimize model
 
+Train a model and optimize its hyperparameters:
+
 ``` zsh
-siapy-cli analysis train-model --model SavgolPLSSVC --data-loader DataLoaderExample --parameters ParamsSavgol --parameters ParamsPLS --parameters ParamsSVC --do-optimize
+siapy-cli analysis train-model --model SavgolPLSSVC \
+                               --data-loader DataLoaderExample \
+                               --parameters ParamsSavgol \
+                               --parameters ParamsPLS \
+                               --parameters ParamsSVC \
+                               --do-optimize
 ```
 
+- The `--do-optimize` flag enables hyperparameter optimization during training.
+- You can customize and add new parameters to tune using the `--parameters` argument.
+- Use the `--model` argument to select a different model.
+- Ensure that the model and parameter configurations are compatible.
+
+Once this step is complete, proceed to the following steps (3–6) using the same flags and arguments to maintain consistency across the workflow.
+
 3. Generate metrics
 
+Create performance metrics for the trained model:
+
 ``` zsh
-siapy-cli analysis generate-metrics --model SavgolPLSSVC --data-loader DataLoaderExample --do-optimize
+siapy-cli analysis generate-metrics --model SavgolPLSSVC \
+                                    --data-loader DataLoaderExample \
+                                    --do-optimize
 ```
 
 4. Generate plots
 
+Produce visualizations for the analysis:
+
 ``` zsh
-siapy-cli analysis generate-plots --model SavgolPLSSVC --data-loader DataLoaderExample --do-optimize
+siapy-cli analysis generate-plots --model SavgolPLSSVC \
+                                  --data-loader DataLoaderExample \
+                                  --do-optimize
 ```
 
 5. Calculate relevances
 
+Analyze feature relevances:
+
 ``` zsh
-siapy-cli analysis calculate-relevances --model SavgolPLSSVC --data-loader DataLoaderExample --do-optimize
+siapy-cli analysis calculate-relevances --model SavgolPLSSVC \
+                                        --data-loader DataLoaderExample \
+                                        --do-optimize
 ```
 
 6. Display metrics
 
+Display the calculated metrics in the terminal:
+
 ``` zsh
 siapy-cli analysis display-metrics --model SavgolPLSSVC --data-loader DataLoaderExample --do-optimize
 ```
+
+> 📌 **Note:**
+>
+> - **Results Location**: All results generated by the commands are saved in the `siapy-cli/artifacts` directory.
+> - **Consistency**: Use the same flags and arguments across all steps to ensure consistency with the selected model and data loader.