docs: update documentation

Author: mesakhcienet

examples/science/af3-slurm/README.md

@@ -412,7 +412,6 @@ terraform_backend_defaults:
 
 vars:
   # Define overall deployment variables
-  deployment_name: af3-slurm         # adjust if necessary
   project_id:  <PROJEC_ID>           # supply existing project id
   region: us-central1                # supply region with C3D-highmem and GPU capacity
   zone: us-central1-a                # supply zone with C3D-highmem and GPU capacity

examples/science/af3-slurm/examples/simple_ipynb_launcher/README.md

@@ -10,3 +10,18 @@ Please note that the launcher needs 2 specific setup steps:
 
 ## Usage Guide
 For usage of the Ipynb Launcher consult the [Step-by-Step Instructions](./Ipynb.md)
+
+## Known Limitations
+You may encounter the following problems while using the notebook.
+
+### Warning during dependency installation
+You may encounter the following warning during dependency installation:
+
+```text
+ERROR: pip's dependency resolver does not currently take into account all the packages that are installed. This behaviour is the source of the following dependency conflicts.
+google-cloud-bigtable 1.7.3 requires grpc-google-iam-v1<0.13dev,>=0.12.3, but you have grpc-google-iam-v1 0.14.2 which is incompatible
+```
+
+**Resolution**: This warning can be **safely ignored**.
+
+The version mismatch does not impact the functionality required by this project. The `google-cloud-bigtable` package is not used in any critical code path, and no issues have been observed during execution.

examples/science/af3-slurm/examples/simple_ipynb_launcher/Setup-post-cluster-deployment.md

@@ -29,7 +29,7 @@ ansible-playbook ipynb-upload-config.yml
 This step uploads the notebook (`slurm-rest-api-notebook.ipynb`) along with its required scripts and libraries to the bucket defined in the `af3ipynb_bucket` variable in `af3-slurm-deployment.yaml` file.
 
 ### 2. Grant Secret Access to the Notebook's Service Account
-**Where to run**: **On your local machine** (where the gcloud CLI is authenticated with access to your GCP project).
+**Where to run**: **On the system where you executed `gcluster`** (where the `gcloud` CLI is authenticated with access to your GCP project).
 
 This setting ensures that the notebook server can successfully retrieve the specified secret by name. For this you need to make sure that the service account running the Jupyter Notebook instance (typically the Compute Engine default service account) has permission to access the Secret Manager secret that stores your SLURM REST token.
 
@@ -47,7 +47,7 @@ You can verify this configuration in the Secret Manager section of the Google Cl
 <img src="adm/secret-manager.png" alt="secret-manager" width="1000">
 
 ### 3. Deploy the Notebook Environment
-**Where to run**: **On your local machine**, inside your cluster-toolkit directory.
+**Where to run**: **On the system where you executed `gcluster`**, under your `cluster-toolkit` directory.
 
 Deploy the Jupyter Notebook environment using the following command:
 
@@ -65,10 +65,15 @@ In the Google Cloud Console:
 
 2. Open the JupyterLab interface for the newly deployed instance
 
-3. Locate and open the `slurm-rest-api-notebook.ipynb` file. If you haven't modified the default value of `af3ipynb_bucket_local_mount` in the `af3-slurm-deployment.yaml`, the notebook should be available at `/home/jupyter/alphafold` folder.
+3. Locate and open the `slurm-rest-api-notebook.ipynb` file. If you haven't modified the default value of `af3ipynb_bucket_local_mount` in the `af3-slurm-deployment.yaml`, the notebook files will be mounted to `/home/jupyter/alphafold` on the Jupyter notebook system.
+
+    When you first connect to Jupyter Notebook, it only shows the alphafold folder — this can appear as if it's located at `/alphafold`. In reality, Jupyter starts in the `/home/jupyter` directory, and the `alphafold` folder is located inside it.
+
+    So while it looks like `/alphafold` in the interface, the actual path is `/home/jupyter/alphafold`.
 
 ### 5. Verify REST Token Access
-**Where to run**: **Inside the JupyterLab terminal** of your deployed Vertex AI Workbench instance.
+**Where to run**: **On the system where you executed `gcluster`** (where the `gcloud` CLI is authenticated with access to your GCP project, similar to step [Grant Secret Access to the Notebook's Service Account](#2-grant-secret-access-to-the-notebooks-service-account)
+).
 
 To verify that Secret Manager access is properly configured, open a terminal within JupyterLab and run the following command:
 
@@ -80,22 +85,22 @@ If the command returns the secret value successfully, it confirms that the noteb
 
 <img src="adm/rest_api.png" alt="slrum rest api" width="1000">
 
-## Teardown
-To remove the Jupyter Notebook deployment when it is no longer needed, run the following command:
-
-```bash
-./gcluster destroy af3-slurm-ipynb --auto-approve
-```
-
-> [!WARNING]
-> If you do not destroy the Jupyter Notebook deployment, it may continue to incur costs.
-> Additionally, any Cloud Storage buckets you created (via the CLI or console) will not be automatically deleted. You are responsible for cleaning them up manually to avoid unnecessary charges.
-> For deleting the buckets consult [Delete buckets](https://cloud.google.com/storage/docs/deleting-buckets).
+## Using the environment
+Go to [Ipynb.md](./Ipynb.md) for documentation on how to use the IPython environment.
 
 ## Customization
 You can adjust the notebook setup behavior using blueprint variables in the deployment YAML.
 All configurations should be validated before running jobs.
 If further modifications to SLURM REST/API Server behavior are required, you must destroy and redeploy the cluster with the updated settings.
 
-## Using the environment
-Go to [Ipynb.md](./Ipynb.md) for documentation on how to use the IPython environment.
+## Teardown
+To remove the Jupyter Notebook deployment when it is no longer needed, run the following command:
+
+    ```bash
+    ./gcluster destroy af3-slurm-ipynb --auto-approve
+    ```
+
+    > [!WARNING]
+    > If you do not destroy the Jupyter Notebook deployment, it may continue to incur costs.
+    > Additionally, any Cloud Storage buckets you created (via the CLI or console) will not be automatically deleted. You are responsible for cleaning them up manually to avoid unnecessary charges.
+    > For deleting the buckets consult [Delete buckets](https://cloud.google.com/storage/docs/deleting-buckets).

examples/science/af3-slurm/examples/simple_ipynb_launcher/Setup-pre-cluster-deployment.md

@@ -24,7 +24,7 @@ gcloud storage buckets create gs://${UNIQUE_JOB_BUCKET} \
 ```
 
 ### Configure Secret Manager
-The IPython notebook will need a secure connection with the Slurm REST API servers. We are using the Google Cloud Secret Manager to manage the necessary credentials in a secure way. Please follow the guideline [here](https://cloud.google.com/secret-manager/docs/create-secret-quickstart) to create a Secret Manager.
+The IPython notebook will need a secure connection with the Slurm REST API servers. We are using the Google Cloud Secret Manager to manage the necessary credentials in a secure way. Please follow the guideline [here](https://cloud.google.com/secret-manager/docs/create-secret-quickstart) to create a secret using Secret Manager.
 
 You do not need to manually add any data to the secret; the SLURM token will be automatically populated by the system.