docs: improve

Signed-off-by: Bartosz Czyż <czyzbartosz3@gmail.com>

Author: czyz-bartosz

here-naksha-cli/README.md

@@ -0,0 +1,50 @@
+# Naksha CLI - Command Line Interface for Naksha
+
+## How to Build and Run
+
+Use the provided script `./naksha-cli` to build and run the CLI.
+
+> [!NOTE]
+> The build process runs only once by default.  
+> To force a rebuild, pass the `--Sbuild` flag:
+> ```bash
+> ./naksha-cli --Sbuild
+> ```
+
+## Available Storages
+
+The fat JAR includes the following built-in storage implementations:
+
+- `com.here.naksha.cli.storages.GeneratingStorage`
+- `naksha.psql.PsqlStorage`
+
+### Adding Custom Storage
+
+You can add your own storage implementation by:
+
+1. Creating a class that implements the required storage interface `naksha.model.IStorage`.
+2. Ensuring the class is **packaged inside the fat JAR** so it's available at runtime (i.e., included in the JAR's
+   classpath).
+3. Editing the [Gradle build file](./build.gradle.kts) to include your custom storage class in the final JAR.
+
+> [!NOTE]
+> Your custom storage class **must be included in the classpath of the fat JAR** in order to be discovered and loaded
+> correctly at runtime.
+
+## Populated PostgreSQL
+
+This module contains a prepared Dockerfile that utilizes the Naksha CLI to create a Docker image with a PostgreSQL
+database populated with random features. For more details, see the [docker](./docker/README.md).
+
+## Releasing
+
+To release a new version, use the command below. The JAR file will be prepared automatically.  
+The JAR can be found in the [build/libs](./build/libs) directory.
+
+```bash
+gradle releaseAndShadow -Prelease.forceVersion=0.1.1
+```
+
+## Read More
+
+For more information, see the [docs](./docs).

here-naksha-cli/docker/README.md

@@ -11,7 +11,7 @@
 ## Build image
 
 - Move to `here-naksha-cli/docker` dir.
-- To edit generation's parameters edit files in `naksha-cli-files` dir. Look at `here-naksha-cli/docs/GeneratingStorageConfig.md` to learn more.
+- To edit generation's parameters edit files in `naksha-cli-files` dir. Look at [GeneratingStorageConfig.md](../docs/GeneratingStorageConfig.md) to learn more.
 > [!NOTE]
 > There are defaults targetMapId="genmap" and targetCollectionId="gencol".
 > You can change target's mapId and collectionId using build-args:

here-naksha-cli/docs/GeneratingStorageConfig.md

@@ -7,10 +7,15 @@ We define the configuration in a JSON file. The schema looks like this:
   "id": "generating_storage",
   "className": "com.here.naksha.cli.storages.GeneratingStorage",
   "properties": {
-    "count": 1000, // Required: Number of features to generate
-    "idsPrefix": "genTest", // Optional: Prefix for generated feature IDs. Defaults to "gen" if not provided
-    "featureTemplateFile": "sample_topology_feature.json", // Optional: Path to the feature template file used as a base for generated features.
+    // Required: Number of features to generate
+    "count": 1000,
+    // Optional: Prefix for generated feature IDs. Defaults to "gen" if not provided
+    "idsPrefix": "genTest",
+    // Optional: Path to the feature template file used as a base for generated features.
+    // It can be an absolute path or relative to the working directory
+    "featureTemplateFile": "sample_topology_feature.json",
     // Either "tileIdsCsvFile" or "tileIds" must be provided to specify the tiles where features will be generated
+    // Absolute path or relative to the working directory
     "tileIdsCsvFile": "tile_ids.csv",
     "tileIds": ["122013000000", "122013000001"]
   }

here-naksha-cli/docs/HOW_TO.md

@@ -2,9 +2,62 @@
 
 ## Copy command
 
+### Database population
+
+1. Prepare the source Storage Configuration
+
+   To generate features use Generating Storage. Look at [GeneratingStorageConfig.md](./GeneratingStorageConfig.md) to learn more about configuration.
+
+   Create `gen.json` file. The example content of the file:
+   ```json
+      {
+        "id": "test_generating_storage",
+        "className": "com.here.naksha.cli.storages.GeneratingStorage",
+        "properties": {
+          "featureTemplateFile": "./sample_topology_feature.json",
+          "count": 40000,
+          "tileIdsCsvFile": "./tile_ids.csv",
+          "idsPrefix": "gen"
+        }
+      }
+   ```
+
+2. Prepare the target Storage Configuration
+
+   Create `psql.json` file. The example content of the file:
+    ```json
+    {
+      "id": "storage",
+      "type": "Storage",
+      "create": true,
+      "upgrade": true,
+      "className": "naksha.psql.PsqlStorage",
+      "master": {
+        "host": "0.0.0.0",
+        "database": "postgres",
+        "port": "5432",
+        "user": "postgres",
+        "password": "password",
+        "readOnly": false
+      }
+    }
+    ```
+
+3. Run the Copy Command
+    ```bash
+       ./naksha-cli copy \
+         --srcStorageConfig gen.json \
+         --targetStorageConfig psql.json \
+         --targetMapId "targetmapid" \
+         --targetCollectionId "targetcolid" \
+         --autoCreateTarget
+    ```
+
+### The same PsqlStorage as target and source
+
 1. Prepare the Storage Configuration
 
-   In my case:
+   Create `test_config.json` file. The example content of the file:
     ```json
     {
       "id": "storage",
@@ -17,11 +70,12 @@
         "database": "postgres",
         "port": "5432",
         "user": "postgres",
-        "password": "pass",
+        "password": "password",
         "readOnly": false
       }
     }
     ```
+   
 2. Run the Copy Command
     ```bash
     ./naksha-cli copy \