diff --git a/doc/README.md b/doc/README.md index 05116b17b..e22c49628 100644 --- a/doc/README.md +++ b/doc/README.md @@ -12,7 +12,7 @@ virtualenv venv source venv/bin/activate pip3 install mkdocs pip3 install $(mkdocs get-deps) -mkdocs server +mkdocs serve ``` When testing the API reference you need to retrieve the openapi.json file from the Hashtopolis server (e.g. via `http://localhost:8080/api/v2/openapi.json) and place it inside this folder. diff --git a/doc/TODO-notes_manual.txt b/doc/TODO-notes_manual.txt index 6ca7be8ed..ec4a95dd0 100644 --- a/doc/TODO-notes_manual.txt +++ b/doc/TODO-notes_manual.txt @@ -1,18 +1,83 @@ -# What still has to be done -- in advanced install there should be a note about files in www-data format etc -- lots of screenshots and diagrams to make the text fancier -- details about the config files, structure of repos etc. -- booting from PxE, running hashtopolis as a service ? -- Check if any difference for Agent overview in new interface -- Hashtypes --> review hashcat --exam -- make an example of supertask builder to make it clearer -- Task overview is missing !!! -- Creating an example of preprocessors in the preprocessors binary to simplify the related section in task creation -- Explaining the global interface of hashtopolis -- Check the style of the manual, page, buttons, code etc should always be within the same style -- Agent installation is not compliant with v2 -- Pictures for installation -- Sein: Review contribution guidelines -- Hashlist page, define what is cracking position -- change the port 8080 to 4200 in the installation part + add a note for the old ui -- Mac OS installation \ No newline at end of file +# Documentation rework — worklist +# (internal notes, not published; keep updated as items get done) + +## Stage 1 — Content fixes (one PR: remove mistakes/bugs visible to readers) + +Draft notes accidentally published on the docs site: +- [x] agents.md:48 remove "(To be checked with the new interface)" — removed; full verification of Agent Overview against the new UI still pending (see backlog) +- [x] tasks.md:160 "MAKE AN EXAMPLE WITH SOME FIGURES" -> worked rockyou/rules example written (figures still welcome, see backlog) +- [x] hashlist.md:41 cracking position defined (keyspace position of the successful candidate, per crackPos in code) +- [x] hashlist.md:48 Download Report -> verified: still exists but legacy UI only (src/templates/hashlists/detail.template.html); documented as such +- [x] hashlist.md:63 removed musing +- [x] hashlist.md:73-74 removed the NOTE +- [x] hashlist.md:85 removed musing -> GitHub issue candidate: type check + filter at superhashlist creation (not created yet, on purpose) +- [x] crackers_binary.md:94-97 "To be reviewed" resolved from code: Type unique + must match archive.hashtopolis.org/agent//, filename must exist in bin/, updateTrack = release channel for update checks +- [x] files.md: import-from-server functionality is NOT legacy (reintroduced in the new frontend) -> commented-out section restored as live "Import a new file" section, updated for the new UI (placeholder image dropped; screenshot still needed, see backlog) +- [x] user-settings.md:33 fixed malformed bullet +- [x] settings_and_configuration.md "(Needed, Check File)" draft note removed; commented-out old TIP block deleted + +Factual errors / inconsistencies: +- [x] index.md:22 mentions MySQL or PostgreSQL now +- [x] Port story: basic_install now points to 4200 for the web UI with a note about backend/legacy UI on 8080 +- [x] faq.md upgrade answer aligned with update.md and linked +- [x] tips.md removed (was a verbatim duplicate of the FAQ entry); nav section renamed FAQ +- [x] hashlist.md:50-54 date formats checked against HashlistUtils.php -> docs were correct (code really mixes dd.mm.yyyy and dd-mm-yyyy); left as-is. GitHub issue candidate: unify in code +- [x] copy-edit pass done on: index, basic_install, advanced_install, update, docker, tls, basic_workflow, agents, tasks, hashlist, files, crackers_binary, users, user-settings, settings_and_configuration, faq +- [x] doc/README.md "mkdocs serve" + +mkdocs.yml bugs (config, still content-correctness not style): +- [x] edit_uri -> edit/master/doc/ +- [x] fonts moved to theme.font +- [x] Redoc CDN script + redoc-dark.css removed + +## Stage 2 — Legacy page (new page collecting old-UI / pre-Docker material) + +Decision to make first: legacy page vs docs versioning (mike + version selector). +Pragmatic plan discussed: don't retrofit 0.14 docs; start versioning when v1.0.0 final +ships (deploy as 1.0 + latest). Note: current FTP deploy would need adaptation +(mike targets gh-pages) or manual versioned subdirectories + versions.json in CI. + +Create installation_guidelines/legacy.md (or user_manual/legacy.md; decide placement), +add to nav, and move/label the following: +- [ ] update.md "Migrating a non-Docker installation to Docker (pre-0.14.0)" section (already labeled legacy; can move wholesale) +- [ ] faq.md pre-Docker entries: "Why does Apache show only a directory or a 500 error?" (apache/php.ini/.htaccess) and the non-Docker half of the upgrade question +- [ ] agents.md: old-interface leftovers in Agent Overview once rewritten for the new UI +- [ ] basic_install.md agent download via agents.php?download=1 -> check whether the new UI exposes a different URL; document old one as legacy if so +- [ ] Add a short intro on the legacy page: which versions it applies to (old UI on :8080, pre-1.0 releases) +- [ ] doc/protocol.{tex,pdf} and doc/user-api/ (v1 API LaTeX+PDF from 2018/2022): decide — delete, or link from the legacy page as archived v1 protocol docs +- [ ] doc/php_style.xml is IDE config, not doc; move out of doc/ (index.md references it -> fix link) + +## Stage 3 — Style & theme modernization (separate PR after content is clean) + +mkdocs.yml / theme: +- [ ] custom brand palette (CSS variables) instead of stock blue/indigo; add favicon; dark-mode logo variant +- [ ] add auto light/dark palette entry (media: prefers-color-scheme) +- [ ] replace toc.integrate with toc.follow (right-hand TOC); reconsider header.autohide +- [ ] replace custom footer partial with native navigation.footer + extra.social icons +- [ ] short nav titles in mkdocs.yml ("Files", "FAQ", ...) instead of long H1s + +Formatting conventions (apply across all pages): +- [ ] one admonition style everywhere (github-callouts); remove !!! blocks, 
 hack in settings_and_configuration.md
+- [ ] FAQ: replace  question headers with real ### headings (TOC, anchors, search)
+- [ ] content tabs (pymdownx.tabbed) for MySQL vs PostgreSQL blocks in basic_install/advanced_install/update (content.tabs.link is already enabled)
+- [ ] standardize screenshot widths + captions; retake outdated ones with the new UI; consistent light/dark
+- [ ] check style consistency of page/buttons/code naming (bold vs quotes vs code) — define a small convention first
+
+## Stage 4 — Landing page & diagrams
+- [ ] real landing page on index.md: hero (assets exist: hero.svg/jpg + hero.css, currently unused) + grid cards (Get started / Install / Manual / FAQ / API)
+- [ ] Mermaid architecture diagram (server/agents/db) in index.md
+- [ ] Mermaid task-lifecycle diagram (keyspace -> benchmark -> chunks) replacing part of the prose
+- [ ] "Explaining the global interface of hashtopolis" — overview page/section of the new UI layout
+
+## Backlog — content additions (from previous TODO list, still valid)
+- [ ] advanced install: note about files in www-data format
+- [ ] details about config files, structure of repos
+- [ ] booting from PXE, running hashtopolis as a service?
+- [ ] supertask builder: worked example (ties into tasks.md marker above)
+- [ ] preprocessor example to simplify the related section in task creation
+- [ ] task overview section is thin -> expand
+- [ ] agent installation: check compliance with v2 / new UI, add pictures, Windows + macOS instructions
+- [ ] hashtypes: review hashcat --exam tip (partially done in settings page)
+- [ ] more screenshots and diagrams overall
+- [ ] Sein: review contribution guidelines
+- [ ] docs CI: phpDocumentor output is generated into doc/php-documentor/ but not linked in nav -> link it or drop the build step
diff --git a/doc/assets/stylesheets/redoc-dark.css b/doc/assets/stylesheets/redoc-dark.css
deleted file mode 100644
index 6bb26d7cc..000000000
--- a/doc/assets/stylesheets/redoc-dark.css
+++ /dev/null
@@ -1,43 +0,0 @@
-/* Redoc-Darkmode nur aktiv, wenn MkDocs das 'slate'-Theme verwendet */
-body[data-md-color-scheme="slate"] .redoc-wrap {
-  background-color: #121212 !important;
-  color: #e0e0e0 !important;
-}
-
-/* Überschriften */
-body[data-md-color-scheme="slate"] .redoc-wrap h1,
-body[data-md-color-scheme="slate"] .redoc-wrap h2,
-body[data-md-color-scheme="slate"] .redoc-wrap h3 {
-  color: #ffffff !important;
-}
-
-/* Codeblöcke */
-body[data-md-color-scheme="slate"] .redoc-wrap code {
-  background-color: #1e1e1e !important;
-  color: #e0e0e0 !important;
-}
-
-/* Response-Boxen */
-body[data-md-color-scheme="slate"] .response-box,
-body[data-md-color-scheme="slate"] .response {
-  background-color: #1e1e1e !important;
-  color: #e0e0e0 !important;
-  border: 1px solid #333 !important;
-}
-
-/* (Optional) Sidebar-Hintergrund */
-body[data-md-color-scheme="slate"] .menu-content {
-  background-color: #1e1e1e !important;
-}
-
-/* (Optional) Sidebar-Textfarbe */
-body[data-md-color-scheme="slate"] .menu-content * {
-  color: #e0e0e0 !important;
-}
-
-/* (Optional) Suchfeld */
-body[data-md-color-scheme="slate"] input[type="text"] {
-  background-color: #2a2a2a !important;
-  color: #ffffff !important;
-  border: 1px solid #444 !important;
-}
diff --git a/doc/faq_tips/faq.md b/doc/faq_tips/faq.md
index 220a71d21..57708e0c3 100644
--- a/doc/faq_tips/faq.md
+++ b/doc/faq_tips/faq.md
@@ -281,17 +281,17 @@ When encountering 500 Internal Server Errors, check Apache error logs at `/var/l
 ❓ How to fix a failed first login in Docker?
 
 Check if the backend logs show `initialization successful`. 
-Docker environment variables must be set correctly (e.g. by using the example given in `env.example`.
+Docker environment variables must be set correctly (e.g. by using the example given in `env.mysql.example` or `env.postgres.example`).
 
 ---
 
 ❓ How to upgrade Hashtopolis without data loss?
 
 If you run Hashtopolis in a dockerized setup with docker-compose, all the data which should be persistent is stored in volumes or mounted into the containers.
-In this case you simply can pull the newest images with `docker compose pull` and then recreate them with `docker compose up -d`.
+Back up your database, then pull the newest images with `docker compose pull` and recreate the containers with `docker compose up -d` — pending database migrations are applied automatically on startup.
+Follow the [update guide](../installation_guidelines/update.md) for the detailed procedure, including refreshing the docker-compose file when it changed between releases.
 
-In case you run a setup directly on a server, back up the database, pull the latest version from Git. 
-When accessing Hashtopolis the first time afterwards, the required updates are executed automatically.
+Setups installed directly on a server (pre-0.14.0, without Docker) should be migrated to Docker as described in the [migration section](../installation_guidelines/update.md#migrating-a-non-docker-installation-to-docker-pre-0140) of the update guide.
 
 ---
 
diff --git a/doc/faq_tips/tips.md b/doc/faq_tips/tips.md
deleted file mode 100644
index b3122733b..000000000
--- a/doc/faq_tips/tips.md
+++ /dev/null
@@ -1,21 +0,0 @@
-# Tips
-
-Here are some cool tips for the users
-
-## Debugging MySQL queries
-
-Running into some funky issues? Want to see what hashtopolis is really submitting to the database?
-
-You can enable query logging in mysql.
-
-Login into the database:
-```
-docker exec -it  /bin/bash
-mysql -p
-# default is: hashtopolis
-SET GLOBAL general_log = 'ON';
-SET GLOBAL sql_log_off = 'ON';
-exit
-cd /var/lib/mysql
-tail -f *.log
-```
diff --git a/doc/index.md b/doc/index.md
index 288c28b3a..6a950d840 100644
--- a/doc/index.md
+++ b/doc/index.md
@@ -11,7 +11,7 @@ Hashtopolis is built to:
 - **Efficiently distribute** workloads to multiple agents, locally or over a network, taking into account heterogeneous hardware configurations.
 - **Support various cracking tools**, primarily designed for **Hashcat**, as well as custom attack strategies.
 - Allow **easy monitoring**, **task automation**, and result collection in large-scale environments.
-- **Centralized management** of files (e.g. wordlists, rules,...) as well as binaries update and distribution.
+- **Centralized management** of files (e.g. wordlists, rules,...) as well as binary updates and distribution.
 - Support **multi-user environment** with configurable permission levels.
 
 
@@ -19,7 +19,7 @@ Hashtopolis is built to:
 
 Hashtopolis operates on a **client-server architecture**:
 
-- The **server** hosts the web interface and database, serving as the central hub where users upload hashes and files, configure cracking tasks, and monitor overall progress. It distributes all necessary files, hashlists, and binaries to agents, centralizes their cracking progress, and collects the recovered passwords. The server runs on PHP and uses MySQL as its database backend.
+- The **server** hosts the web interface and database, serving as the central hub where users upload hashes and files, configure cracking tasks, and monitor overall progress. It distributes all necessary files, hashlists, and binaries to agents, centralizes their cracking progress, and collects the recovered passwords. The server runs on PHP and uses MySQL or PostgreSQL as its database backend.
 
 - The **agents** are lightweight Python clients installed on various computing resources. They communicate with the server by requesting work, execute cracking tasks using Hashcat, and report results back to the server.
 
diff --git a/doc/installation_guidelines/advanced_install.md b/doc/installation_guidelines/advanced_install.md
index 4877af602..dd462c28a 100644
--- a/doc/installation_guidelines/advanced_install.md
+++ b/doc/installation_guidelines/advanced_install.md
@@ -1,44 +1,66 @@
 # Advanced installation
 
+> [!NOTE]
+> Throughout this page, *docker-compose.yml* refers to the file created during the installation (basic or offline), which is saved under that name whether you chose the MySQL or the PostgreSQL variant. Unless stated otherwise, the modifications described on this page apply identically to both variants.
+
 ## Installation in an offline environment
-If you want to run Hashtopolis on a network without internet access, you need a separate machine with internet to either pull the images from Docker Hub or build them yourself.
+If you want to run Hashtopolis on a network without internet access, you need a separate machine with internet to either pull the images from Docker Hub or build them yourself (to build the images from source, follow the instructions in the [dedicated section](#build-hashtopolis-images-yourself)).
+
+Hashtopolis supports MySQL and PostgreSQL since v.1.0.0-rainbow5. The procedure is the same for both databases — only the database image and the docker-compose/env files differ — so simply follow the subsection matching your choice. In both cases, make sure the database image version matches the one pinned in the docker-compose file of the release you are installing.
+
+### Offline installation with MySQL
 
-Here are the commands to pull the images from Docker hub. To build the images from source, follow the instructions in the section related to building images.
+1. On the machine with internet access, pull the images from Docker Hub and save them as .tar archives:
 ```
 docker pull hashtopolis/backend:latest
 docker pull hashtopolis/frontend:latest
 docker pull mysql:9.7
-```
 
-The images can then be saved as .tar archives:
-```
 docker save hashtopolis/backend:latest --output hashtopolis-backend.tar
 docker save hashtopolis/frontend:latest --output hashtopolis-frontend.tar
 docker save mysql:9.7 --output mysql.tar
 ```
 
-Next, transfer both file to your Hashtopolis server and import them using the following commands:
+2. Download the docker-compose and env files:
+```
+wget https://raw.githubusercontent.com/hashtopolis/server/master/docker-compose.mysql.yml -O docker-compose.yml
+wget https://raw.githubusercontent.com/hashtopolis/server/master/env.mysql.example -O .env
+```
+
+3. Transfer the .tar archives, *docker-compose.yml* and *.env* to your Hashtopolis server and import the images:
 ```
 docker load --input hashtopolis-backend.tar
 docker load --input hashtopolis-frontend.tar
 docker load --input mysql.tar
 ```
 
-Hashtopolis supports MySQL and PostgreSQL since v.1.0.0-rainbow5. You can choose between both databases. Depending of your choice, download the corresponding files:.
+### Offline installation with PostgreSQL
 
-Download docker-compose.mysql.yml and env.mysql.example for MySQL   
+1. On the machine with internet access, pull the images from Docker Hub and save them as .tar archives:
 ```
-wget https://raw.githubusercontent.com/hashtopolis/server/master/docker-compose.mysql.yml -O docker-compose.yml
-wget https://raw.githubusercontent.com/hashtopolis/server/master/env.mysql.example -O .env
-```   
+docker pull hashtopolis/backend:latest
+docker pull hashtopolis/frontend:latest
+docker pull postgres:18
 
-**or**
+docker save hashtopolis/backend:latest --output hashtopolis-backend.tar
+docker save hashtopolis/frontend:latest --output hashtopolis-frontend.tar
+docker save postgres:18 --output postgres.tar
+```
 
-Download docker-compose.postgres.yml and env.postgres.example for PostgreSQL   
- ```
+2. Download the docker-compose and env files:
+```
 wget https://raw.githubusercontent.com/hashtopolis/server/master/docker-compose.postgres.yml -O docker-compose.yml
 wget https://raw.githubusercontent.com/hashtopolis/server/master/env.postgres.example -O .env
- ```
+```
+
+3. Transfer the .tar archives, *docker-compose.yml* and *.env* to your Hashtopolis server and import the images:
+```
+docker load --input hashtopolis-backend.tar
+docker load --input hashtopolis-frontend.tar
+docker load --input postgres.tar
+```
+
+### Finalize the installation
 
 Continue with the normal docker installation described in the [basic installation section](basic_install.md#setup-hashtopolis-server).
 
@@ -70,10 +92,10 @@ In your docker-compose.yml-file you have to add an additional container:
       - 8081:80
 
 ```
-Adapt the configuration as needed. In this example you have to put your binary-ZIP-files in the `./data`-folder, where your docker-compose.yml is located and the webserver listens on port 8081.
+Adapt the configuration as needed. In this example you have to put your binary-ZIP-files in the `./data`-folder, where your docker-compose.yml is located, and the webserver listens on port 8081. Port 8081 is used on purpose: port 8080 is already taken by the Hashtopolis backend, so this dedicated file-download server must use a different one.
 
-!!! note "Note:" 
-    If your environment is offline, keep in mind that you need to export and import the nginx image first following a similar process than for the hashtopolis images as described [previously](./advanced_install.md#installation-in-an-offline-environment). 
+> [!NOTE]
+> If your environment is offline, keep in mind that you need to export and import the nginx image first, following a similar process to the one described for the Hashtopolis images [previously](./advanced_install.md#installation-in-an-offline-environment). 
 
 ### nginx.conf
 
@@ -237,12 +259,12 @@ Finally, copy the data back into the appropriate folders after recreating the co
 
 ## Backup and Restore
 
-What the best way to backup and restore your hashtopolis instance depends heavily on the way the instance is set up and what configurations are made.
+The best way to back up and restore your Hashtopolis instance depends heavily on the way the instance is set up and what configurations are made.
 Therefore, there is no guide available for backing up / restoring which works for everyone, but some considerations which need to be taken into account:
 
 - Depending on the amount of data (files, database size, etc.) in the hashtopolis instance, a complete backup can become quite large. If it is needed to just be able to restore information about executed tasks, progress etc. (e.g. in case of a fatal failure of the system) it is enough to just back up the database, but of course this would not allow a easy restore to a previous state.
 - If you plan to do a backup in a way to be able to completely restore it to the previous state (files, logs, database, users, etc.), you need to be careful to include all required items into your backup and when restoring make sure that nothing gets left out during that process, otherwise you may end up with a semi-broken or non-functional hashtopolis instance.
-- In case you have set up your hashtopolis instance only using volumes (one for the database, one for all the hashtopolis data), backup up the complete content of these volumes is enough to have all data backed up.
+- In case you have set up your hashtopolis instance only using volumes (one for the database, one for all the hashtopolis data), backing up the complete content of these volumes is enough to have all data backed up.
 - Restoring only parts (some tasks, only users, other database parts) from a backup is very tricky and should only be done by experts and very easily goes wrong when primary keys are not sequential and not updated for auto increment in the database.
 
 ## Set up a fresh and clean instance
@@ -254,7 +276,7 @@ When there is the need for a complete reset/clean setup (e.g. for testing), you
 
 These steps assume that you have set up your hashtopolis instance using a `docker-compose.yml` file (either MySQL or PostgreSQL).
 
-First stop all running all containers and clean them up:
+First stop all running containers and clean them up:
 
 ```
 cd 
diff --git a/doc/installation_guidelines/basic_install.md b/doc/installation_guidelines/basic_install.md
index 8fcc307b4..a3b14805b 100644
--- a/doc/installation_guidelines/basic_install.md
+++ b/doc/installation_guidelines/basic_install.md
@@ -61,7 +61,10 @@ nano .env
 docker compose up --detach
 ```   
 
-5. Access the Hashtopolis UI through: ```http://127.0.0.1:8080``` using the credentials set in the *.env* file, default are user=admin and password=hashtopolis.
+5. Access the Hashtopolis web UI through: ```http://127.0.0.1:4200``` using the credentials set in the *.env* file, defaults are user=admin and password=hashtopolis.
+
+> [!NOTE]
+> The web UI is served by the frontend container on port 4200. The backend container listens on port 8080: it serves the API used by the agents as well as the legacy web interface.
 
 
 ## Agent installation
@@ -76,7 +79,7 @@ To install the agent, ensure that the following prerequisites are met:
 python3 --version
 ```
 
-2. Python Packages: The Hashtopolis agents depends on the following Python packages:
+2. Python Packages: The Hashtopolis agent depends on the following Python packages:
 
    - requests
    - psutil
@@ -95,8 +98,8 @@ pip install requests psutil
 
 ### Download the Hashtopolis agent
 
-1. Connect to the Hashtopolis server: ```http://:8080``` and log in. Navigate to the page *Agents > Show Agents* and click on the button *'+ New Agent'*. 
-2. On that page you can click on "..." and choose to download the agent binary or copy the URL of the agent binary and download the agent using wget/curl:
+1. Connect to the Hashtopolis web UI: ```http://:4200``` and log in. Navigate to the page *Agents > Show Agents* and click on the button *'+ New Agent'*. 
+2. On that page you can click on "..." and choose to download the agent binary or copy the URL of the agent binary and download the agent using wget/curl (note that the agent binary is served by the backend on port 8080):
 
 ```
 curl -o hashtopolis.zip "http://:8080/agents.php?download=1"
diff --git a/doc/installation_guidelines/docker.md b/doc/installation_guidelines/docker.md
index 79f1f0c2b..e819dc6c9 100644
--- a/doc/installation_guidelines/docker.md
+++ b/doc/installation_guidelines/docker.md
@@ -35,7 +35,7 @@ docker compose down
 ```
 docker compose ps
 ```
- Here you see the different containers (frontend, backend and db), that are need to run Hashtopolis. In addition you see, when the containers were created and since when they are running.
+ Here you see the different containers (frontend, backend and db) that are needed to run Hashtopolis. In addition you see when the containers were created and since when they are running.
 
 ## Access the database:
 
diff --git a/doc/installation_guidelines/tls.md b/doc/installation_guidelines/tls.md
index 14158a0d8..eb3886526 100644
--- a/doc/installation_guidelines/tls.md
+++ b/doc/installation_guidelines/tls.md
@@ -22,13 +22,13 @@ openssl req -x509 -newkey rsa:2048 -keyout nginx.key -out nginx.crt -days 365 -n
 
 ## Setting up docker-compose and env.example
 
-Refer to the [Basic installation](../installation_guidelines/basic_install.md) page on how to download those settings file. 
+Refer to the [Basic installation](../installation_guidelines/basic_install.md) page on how to download those settings files. 
 
 1. Edit docker-compose.yaml
 
 Add the following new container to the `service:` section in the docker-compose.yaml.
 
-```json
+```yaml
   nginx:
     container_name: nginx
     image: nginx:latest
diff --git a/doc/user_manual/agents.md b/doc/user_manual/agents.md
index 1df4fdef5..9e51c1d8b 100644
--- a/doc/user_manual/agents.md
+++ b/doc/user_manual/agents.md
@@ -45,8 +45,6 @@ The visuals use the following color code:
 ---
 
 ## Agent Overview 
-***(To be checked with the new interface)***
-
 
 Clicking on an agent in the list opens the **Agent Overview** page, which provides detailed information and management options for that agent as described below:
 
diff --git a/doc/user_manual/basic_workflow.md b/doc/user_manual/basic_workflow.md
index a2c22dc5c..ba714fbbd 100644
--- a/doc/user_manual/basic_workflow.md
+++ b/doc/user_manual/basic_workflow.md
@@ -3,7 +3,7 @@
 Before using Hashtopolis, it's important to understand key terms commonly used in the manual and the application:
 
 - **Agent**: A Hashtopolis client instance that performs password cracking using its available/associated hardware resources (e.g., GPUs and CPUs).
-- **Hashlist**: A collection of hashes stored in the database. Hashlists are most commonly in TEXT, yet other formats like HCCAPX, or BINARY are also supported.
+- **Hashlist**: A collection of hashes stored in the database. Hashlists are most commonly in TEXT, yet other formats like HCCAPX or BINARY are also supported.
 - **Task**: A specific password cracking job, defined by a command line specifying all the parameters, files to use, hashlist to target and binary to use.
 - **Supertask**: A container grouping multiple subtasks together for easier management and monitoring. It is not a standalone cracking task.
 - **Subtask**: A smaller task within a supertask, which behaves like a normal task but whose priority matters only inside the supertask.
@@ -105,10 +105,10 @@ Once the task is active, you can track its status and results:
 
 ## Do’s and Don’ts
 
-- **Do** test your command line locally with Hashcat if your task is failing for unknown reason.
+- **Do** test your command line locally with Hashcat if your task is failing for an unknown reason.
 - **Don’t** use multiple wordlists with attack mode 0, Hashtopolis currently supports only a single wordlist per task.
 - **Don’t** use the `--increment` flag in your command line, as it is not supported.
 - **Be cautious** with the `--slow-candidates` option, it may cause performance issues or unexpected behavior.
-- **Don’t** create extremely large tasks as **small task**. This goes against Hashtopolis’s parallel processing design..
+- **Don’t** create extremely large tasks as **small tasks**. This goes against Hashtopolis’s parallel processing design.
 - **Do** monitor your agents’ performance to adjust chunk sizes or task priorities as needed.
 
diff --git a/doc/user_manual/crackers_binary.md b/doc/user_manual/crackers_binary.md
index 110256bd5..f2c3ce7de 100644
--- a/doc/user_manual/crackers_binary.md
+++ b/doc/user_manual/crackers_binary.md
@@ -1,28 +1,28 @@
 # Binaries
 
-Hashtopolis is also responsible of the update and distribution of several binaries, starting from the cracker, e.g. Hashcat, or also the binaries for the agent. This part of the manual is dedicated to the management of those binaries from the corresponding menu.
+Hashtopolis is also responsible for the update and distribution of several binaries, starting with the cracker, e.g. Hashcat, but also the binaries for the agent. This part of the manual is dedicated to the management of those binaries from the corresponding menu.
 
 ## Crackers
 
-When Hashtopolis was first developed it was solely designed to manage hashcat tasks with multiple agents. As part of the evolution of the project, support for other tool than hashcat was integrated in hashtopolis. In addition to the support of different tools, hashtopolis can also manage different versions of the same tool. 
+When Hashtopolis was first developed it was solely designed to manage hashcat tasks with multiple agents. As part of the evolution of the project, support for other tools than hashcat was integrated into Hashtopolis. In addition to the support of different tools, Hashtopolis can also manage different versions of the same tool. 
 
 

     ![screenshot_cracker_page](../assets/images/cracker_page.png){ width="600" }
 

 
-This page displays some basic information about all the crackers configured in hashtopolis. Apart from the ID of the cracker and its name, the version(s) available is also displayed. Hashtopolis is configured with a default hashcat cracker to be downloaded by the agents whenever they need it. 
+This page displays some basic information about all the crackers configured in Hashtopolis. Apart from the ID of the cracker and its name, the available version(s) are also displayed. Hashtopolis is configured with a default hashcat cracker to be downloaded by the agents whenever they need it. 
 
 ### Creating a New Cracker
 
 As mentioned above, Hashtopolis supports other crackers than Hashcat. To deploy a new cracker, two steps are required, first the creation of the type of cracker and then adding a version for it. 
 
-By clicking on the ``*New Cracker*'' button, a new page opens in which you can set the name for the new cracker.  A cracker must have the following features in order to split the work into chunks:
+By clicking on the *New Cracker* button, a new page opens in which you can set the name for the new cracker.  A cracker must have the following features in order to split the work into chunks:
 
 - **--keyspace**: calculate the size of the task to be distributed.
 - **--skip**: define the starting point from where the hashcat instance should start working on the keyspace.
 - **--limit**: define how many entries from the keyspace should be evaluated by the hashcat instance.
 
-In other words, the keyspace is the total amount of work related to a task. The combination of skip and limit will define a portion of the keyspace, also called chunk, on wich an agent will be working. That is the main features required to distribute a task among the several agents.
+In other words, the keyspace is the total amount of work related to a task. The combination of skip and limit will define a portion of the keyspace, also called chunk, on which an agent will be working. These are the main features required to distribute a task among several agents.
 
 
@@ -42,7 +42,7 @@ Whether it is the first version for a new cracker or to update an existing crack
 
 The three following information are required to deploy a new version.
 
-- **Binary Base Name**: this is how the cracker should be called from the command line by the agent. In our example, the hashcat cracker is called with ```hashcat'''. 
+- **Binary Base Name**: this is how the cracker should be called from the command line by the agent. In our example, the hashcat cracker is called with ```hashcat```. 
 - **Binary Version**: the version number of the cracker should be inserted here. The backend will order them in decreasing order. The latest version will be selected by default for this cracker.
 - **Download URL**: this specifies from where the agent should download the binary package. In the case of our example, it is directly downloaded from the hashcat webpage. 
 
@@ -52,32 +52,32 @@ The three following information are required to deploy a new version.
 
 ## Preprocessors
 
-The purpose of a pre-processor in the context of hashcat is to generate passwords candidates that are then fed through the standard input to a hashcat process. The preprocessor page displayed below list all the preprocessors configured in hashtopolis. 
+The purpose of a preprocessor in the context of hashcat is to generate password candidates that are then fed through the standard input to a hashcat process. The preprocessor page displayed below lists all the preprocessors configured in Hashtopolis. 
 
 

     ![screenshot_cracker_page](../assets/images/preprocessor_page.png){ width="600" }
 

 
-By default hashtopolis is installed with a single preprocessor, namely [*Prince*](https://github.com/hashcat/princeprocessor). Additional preprocessors can be added by clicking the *New Preprocessor" button. The creation page below is diplayed.
+By default Hashtopolis is installed with a single preprocessor, namely [*Prince*](https://github.com/hashcat/princeprocessor). Additional preprocessors can be added by clicking the *New Preprocessor* button. The creation page below is displayed.
 
 

     ![screenshot_cracker_page](../assets/images/new_preprocessor_page.png){ width="600" }
 

 
-It is rather similar to the creation of a new version of a [cracker](./crackers_binary.md#adding-a-new-version). The main difference is that the user can associate the required keyspace, skip, and limit options to different flags of the preprocessor. Note that those three remain mandatory to be used within hashtopolis, however, this allows more flexibility as the preprocessor may have named those options differently. If additional paramaters are required at execution time, they should be included in the [preprocessor's command](./tasks.md#advanced-parameters) during the task creation.
+It is rather similar to the creation of a new version of a [cracker](./crackers_binary.md#adding-a-new-version). The main difference is that the user can associate the required keyspace, skip, and limit options to different flags of the preprocessor. Note that those three remain mandatory to be used within Hashtopolis, however this allows more flexibility as the preprocessor may have named those options differently. If additional parameters are required at execution time, they should be included in the [preprocessor's command](./tasks.md#advanced-parameters) during the task creation.
 
 
 ## Agent Binaries
 
 There are several situations where deploying a new Hashtopolis agent binary is necessary. Most commonly, this happens when official updates introduce bug fixes, performance improvements, or support for new features. However, you may also need to build or modify an agent binary yourself—for example, if you've developed a custom cracker that requires integration via a new Python handler, or if you need a version of the agent compiled specifically for another platform such as Windows. In all cases, updating the agent typically involves replacing the existing binary and ensuring any dependencies are still met.
 
-The agent binaries page displayed the information shown below about the current agent binaries configured in hashtopolis.
+The agent binaries page displays the information shown below about the current agent binaries configured in Hashtopolis.
 
 

     ![screenshot_cracker_page](../assets/images/agent_binaries_page.png){ width="600" }
 

 
-To create a new agent, simply press the button *New Binary* in the agent binary page. The following page is then displayed.
+To register a new agent binary, simply press the button *New Binary* in the agent binaries page. The following page is then displayed.
 
 

     ![screenshot_cracker_page](../assets/images/new_agent_page.png){ width="400" }
@@ -85,13 +85,11 @@ To create a new agent, simply press the button *New Binary* in the agent binary
 
 The following fields need to be filled at creation time.
 
-- **Type**: This field is used to provide information about the agent binaries such as for example the programming language in which it is written.
-- **Operating Systems**: specifies the list of OSs supported by the agent.
-- **Filename**: specifies the filename of the agent binaries.
-- **Version**: specifies the version of the agent binaries
-- **Update Track**: this can be either stable or release. It specifies the status of the current agent.
+- **Type**: Identifier of the agent binary, e.g. the language it is written in (the default Python agent uses *python*). It must be unique among the agent binaries. For official agents, it must match the name used on the Hashtopolis archive (see the note on updates below).
+- **Operating Systems**: Informational free text listing the OSs supported by the agent, e.g. *Windows, Linux, OS X*.
+- **Filename**: The filename of the agent binary as stored in the *bin/* folder of the server. The file must exist there: when adding a custom agent binary, you need to place the file in that folder yourself (e.g. by copying it into the backend container).
+- **Version**: The version number of the agent binary. It is compared against the archive to detect available updates.
+- **Update Track**: The release channel used when checking for updates, either *stable* or *release*.
 
-**To be reviewed**
-- Are the two first fields free text zones or they are checked and linked to something?
-- What it the update track field needed for... for information purpose ?
-- WHere does one store the agent... I guess it should be in the folder binaries of hashtopolis, but so it means it has to be uploaded manually and therefore we should have an explanation about this or to have an upload / url functionality.
\ No newline at end of file
+> [!NOTE]
+> For official agents, the server checks ```https://archive.hashtopolis.org/agent///``` for a newer version than the one configured. When an update is available, it can be downloaded from the archive directly from this page; the server verifies the SHA256 checksum and replaces the file in the *bin/* folder automatically.
\ No newline at end of file
diff --git a/doc/user_manual/files.md b/doc/user_manual/files.md
index 433d6f160..919038e5a 100644
--- a/doc/user_manual/files.md
+++ b/doc/user_manual/files.md
@@ -18,14 +18,14 @@ When creating a password recovery task in Hashtopolis, you may need to upload ad
 
 ## Manage Files
 
-Each type of file has a dedicated page containing similar information. The figure below shows what the rule page looks like. It contains information such as the name of the file, its size, the number of line in it as well as the access group. The key next to the name indicates that the file is secret and can only be accessed by [trusted agents](./agents.md#agent-overview).
+Each type of file has a dedicated page containing similar information. The figure below shows what the rule page looks like. It contains information such as the name of the file, its size, the number of lines in it as well as the access group. The key next to the name indicates that the file is secret and can only be accessed by [trusted agents](./agents.md#agent-overview).
 
 

     ![screenshot_rule_page](../assets/images/rules_files.png)
 

 
 
-From this page, files can be edited by clicking on their name or on the related action. Files can also be deleted from there. The picture below shows the page opened when editing a rule file. Other type of files are very similar to this one. 
+From this page, files can be edited by clicking on their name or on the related action. Files can also be deleted from there. The picture below shows the page opened when editing a rule file. Other types of files are very similar to this one. 
 
 Navigating to the Files page of the Hashtopolis User Interface, you can manage the files uploaded to the server.
 
@@ -35,9 +35,9 @@ Navigating to the Files page of the Hashtopolis User Interface, you can manage t
 
 1. **Select Category**.
 2. **Secret**: Files that are marked as secret will only be sent to trusted agents.
-Line count: Reprocess the file and update the line count with the number of lines contained in the file.
-3. **Edit**: Edit the parameters of the file (name, file type and associated group).
-4. **Delete**: Removes the file from Hashtopolis.
+3. **Line count**: Reprocess the file and update the line count with the number of lines contained in the file.
+4. **Edit**: Edit the parameters of the file (name, file type and associated group).
+5. **Delete**: Removes the file from Hashtopolis.
 
 > [!NOTE]
 > Files can only be deleted if they are not referenced in any task, whether they are active, finished or even archived. 
@@ -47,7 +47,7 @@ Line count: Reprocess the file and update the line count with the number of line
 For each category, new files can be added to the server by pressing "New Wordlist/Rules/File" button. Files are uploaded using one of the following methods:
 
 - **Upload from your computer** – Directly upload files stored on your local machine.
-
+- **Import from the import directory** – Use files that have been preloaded into the server's import directory. This is especially useful for very large files.
 - **Download from a URL** – Provide a URL to fetch files from an external source.
 Detailed instructions for each upload method are provided in the following subsections.
 
@@ -57,28 +57,24 @@ Detailed instructions for each upload method are provided in the following subse
     ![screenshot_new_file](../assets/images/upload_rule.png){ width="400" }
 

 
-1. **Add file**: Click this button to enable file upload. After clicking, a new field labeled Choose file will appear. Each time you click on Add File, an additional Choose file field will be added, allowing you to upload multiple files simultaneously..
+1. **Add file**: Click this button to enable file upload. After clicking, a new field labeled Choose file will appear. Each time you click on Add File, an additional Choose file field will be added, allowing you to upload multiple files simultaneously.
 2. **Associated Access Group**: Define the access group that will have permissions to access the file(s) you are uploading. 
 3. **Choose file**: Click this button to open your computer’s file explorer. Select the file you wish to upload.
-4. **Upload files**: Once you have selected all the files you wanted to upload, click the Upload files button.
+4. **Upload files**: Once you have selected all the files you want to upload, click the Upload files button.
 
-
+2. **Import the file**: Select the import method on the *New Wordlist/Rules/File* page. The files present in the import directory are listed:
+    - Define the **Associated Access Group** that will have permissions to access the file(s).
+    - **Select the files to import** by ticking the box in front of them, or use *Select All*.
+    - Click **Import files**.
 
 ### Download new file from URL
 
diff --git a/doc/user_manual/hashlist.md b/doc/user_manual/hashlist.md
index 7c43d35a7..0aab451ad 100644
--- a/doc/user_manual/hashlist.md
+++ b/doc/user_manual/hashlist.md
@@ -25,12 +25,12 @@ Fill out the fields as follows:
     - **Paste**: Copy and paste the hashes directly into the "Input" field.
     - **Upload**: Select a file containing the hashes from your computer.
     - **URL Download**: Provide a URL to download the hashlist.
-    - **Import**: This option can be used as a workaround in case of upload errors with the first version of the user interface. To import a file, first copy it to the import folder as described in the section Import a new file.
+    - **Import**: Use a file that has been preloaded into the server's import directory. This is especially useful for large hashlists that fail to upload through the browser. To import a file, first copy it to the import folder as described in the [Import a new file](./files.md#import-a-new-file) section.
 7. **Access Group**: Modify the access group associated with the hashlist if needed.
 8. **Create Hashlist**: Click "Create Hashlist" to finalize the process. This will open a new page displaying the details of your newly created hashlist.
 
 ## Hashlists View
-Ordered by ID by default. It reports the hashlists created. A checkmark is shown beside the hashlist name once all associated passwords have been successfully recovered. It shows the number of recovered passwords as well as the total number of hashes. It allows to import *pre-cracked hashes* or export the recovered passwords (*see below for more details*). The hashlists can also be archived or deleted.
+This page lists the created hashlists, ordered by ID by default. A checkmark is shown beside the hashlist name once all associated passwords have been successfully recovered. It shows the number of recovered passwords as well as the total number of hashes. It allows importing *pre-cracked hashes* or exporting the recovered passwords (*see below for more details*). The hashlists can also be archived or deleted.
 
 ## Hashlists Details
 If you click on a Hashlist, either in the hashlists view, in the Tasks overview or inside a task, it brings you to the corresponding Hashlist details page. 
@@ -38,29 +38,29 @@ If you click on a Hashlist, either in the hashlists view, in the Tasks overview
 Apart from the parameters specific to this hashlist (i.e. ID, Access Group, Hashlist name, ...), the page displays some information about the total number of hashes, the number of cracked ones and the number of remaining ones to be recovered. Clicking on one of these three values will open a new window displaying information about the Hashes of the Hashlist as detailed below.
 
 ### Hashes of Hashlist X 
-This page list all the hashes from the related hashlist. Filters can be applied to show either the cracked, the uncracked or all the hashes. According to the display filter selected, the Hashes only, the plaintext only or both are displayed. Additionally, the cracking position (**to be defined**) can be displayed next to the cracked ones. Only 1000 hashes can be displayed at a time within a page but the user can navigate through the pages. The number of hashes per page can be configured in *Config > UI* settings.
+This page lists all the hashes from the related hashlist. Filters can be applied to show either the cracked, the uncracked or all the hashes. According to the display filter selected, the hashes only, the plaintext only or both are displayed. Additionally, the cracking position can be displayed next to the cracked ones, this is the position within the attack's keyspace at which the successful password candidate was found, as reported by the cracker. Only 1000 hashes can be displayed at a time within a page but the user can navigate through the pages. The number of hashes per page can be configured in *Config > UI* settings.
 
 A HEX converter is present at the bottom of the page to convert any HEX values. This can be useful when the reported password is stored in a HEX format.
 
 ### Actions on the hashlist
-Several actions are offered to the user which are detailed below. Note that some of the options are logically not available if no password have been recovered for the specific hashlist. 
+Several actions are offered to the user which are detailed below. Note that some of the options are logically not available if no passwords have been recovered for the specific hashlist. 
 
-- **Download Report**: **will we still have this function**
+- **Download Report**: Generates a report about the hashlist based on the report templates available on the server. This action is currently only available in the old user interface.
 
-- **Generate Wordlist**: This action generates a file listing all the recovered passwords from this hashlist. The file is automatically stored in the *wordlist* section of the *Files* section. The generated file can be easily retrieved as it got assigned to the latest file ID. The filename is *Wordlist_[Hashlist_ID]_[dd.mm.yyyy]_[hh.mm.ss].txt*. 
+- **Generate Wordlist**: This action generates a file listing all the recovered passwords from this hashlist. The file is automatically stored in the *wordlist* section of the *Files* section. The generated file can be easily retrieved as it is assigned the latest file ID. The filename is *Wordlist_[Hashlist_ID]_[dd.mm.yyyy]_[hh.mm.ss].txt*. 
 
-- **Export Hashes for pre-crack**: This action generates a file listing all the recovered passwords from this hashlist associated with the corresponding hash value in the format *[hash]:[plaintext]*. The file is automatically stored in the *wordlist* section of the *Files* section. The generated file can be easily retrieved as it got assigned to the latest file ID. The filename is *Pre-cracked_[Hashlist_ID]_[dd-mm-yyyy]_[hh-mm-ss].txt*. 
+- **Export Hashes for pre-crack**: This action generates a file listing all the recovered passwords from this hashlist associated with the corresponding hash value in the format *[hash]:[plaintext]*. The file is automatically stored in the *wordlist* section of the *Files* section. The generated file can be easily retrieved as it is assigned the latest file ID. The filename is *Pre-cracked_[Hashlist_ID]_[dd-mm-yyyy]_[hh-mm-ss].txt*. 
 
-- **Export Left Hashes**: This action generates a file listing all the hashes for which no password have been recovered at the moment of the file creation. The file is automatically stored in the *wordlist* section of the *Files* section. The generated file can be easily retrieved as it got assigned to the latest file ID. The filename is *Leftlist_[Hashlist_ID]_[dd-mm-yyyy]_[hh-mm-ss].txt*. 
+- **Export Left Hashes**: This action generates a file listing all the hashes for which no password has been recovered at the moment of the file creation. The file is automatically stored in the *wordlist* section of the *Files* section. The generated file can be easily retrieved as it is assigned the latest file ID. The filename is *Leftlist_[Hashlist_ID]_[dd-mm-yyyy]_[hh-mm-ss].txt*. 
 
-- **Import pre-cracked Hashes**: This action opens a new page in which the user can upload pre-cracked hashes for the related hashlist. A pre-crack is supposed to be a hash contained in the hashlist associated with a plaintext in the format *[hash]\(:[salt]\):[plaintext]*. Such data can be imported in different ways: *"Paste, Upload, Import, URL download"* such as the option to import the hashes during a hashlist creation. In case of salted password, the field separator must be indicated, ':' being the default one. When validating by pressing the *Pre-crack hashes* button, the back-end will check if the imported data contains hash values from the targeted hashlist and integrate the plaintext value accordingly. If the option *Overwrite already cracked hashes* is selected, existing recovered passwords will be overwritten by the new imported ones in case of conflict. The front-end is then reporting to the user how many hashes have been considered as well as how many entries have been updated.  
+- **Import pre-cracked Hashes**: This action opens a new page in which the user can upload pre-cracked hashes for the related hashlist. A pre-crack is supposed to be a hash contained in the hashlist associated with a plaintext in the format *[hash]\(:[salt]\):[plaintext]*. Such data can be imported in different ways — *"Paste, Upload, Import, URL download"* — similar to the options available during a hashlist creation. In case of salted passwords, the field separator must be indicated, ':' being the default one. When validating by pressing the *Pre-crack hashes* button, the back-end will check if the imported data contains hash values from the targeted hashlist and integrate the plaintext values accordingly. If the option *Overwrite already cracked hashes* is selected, existing recovered passwords will be overwritten by the newly imported ones in case of conflict. The front-end then reports to the user how many hashes have been considered as well as how many entries have been updated.  
 
-Pre-cracked management is useful to share results between different instances of hashtopolis. This is especially relevant for salted hashlists as each new recovered plaintext is improving the efficiency of the attack is there is no more hashes associated with the same salt value. 
+Pre-crack management is useful to share results between different instances of Hashtopolis. This is especially relevant for salted hashlists: each newly recovered plaintext improves the efficiency of the attack, as salts with no remaining uncracked hashes no longer need to be processed. 
 
 ### Tasks overview and creation
 At the bottom of the page there are three subsections related to task for this hashlist.
 
-- **Tasks cracking this hashlists**: This section lists all the tasks that are related to this hashlist. Note that supertasks will not appear here (**is this something we would like in the future... let see how it will be handled within project**). The details displayed are defined in the *Show Tasks* section as they are the same. Note that not all the infos present in the *Show Tasks* page are displayed here. 
+- **Tasks cracking this hashlist**: This section lists all the tasks that are related to this hashlist. Note that supertasks will not appear here. The details displayed are defined in the *Show Tasks* section as they are the same, although not all the information present in the *Show Tasks* page is displayed here. 
 
 - **Create pre-configured tasks**: this section lists all the existing pre-configured tasks. The user can select a set of pre-configured tasks and create the corresponding task for the current hashlist. See the section on *pre-configured tasks* for more detail on this.
 
@@ -70,9 +70,6 @@ At the bottom of the page there are three subsections related to task for this h
 
 ## Super Hashlists
 
-> [!NOTE]
-> Should we include pictures in this section that is quite obvious
-
 A Super Hashlist is a virtual hashlist that combines multiple classic hashlists without duplicating data at the database level. It allows you to run a single cracking task on multiple hashlists at once. Since the hashes are only linked, not merged, storage is optimized, and updates to individual hashlists are immediately reflected. This is especially useful when working with related datasets that require the same attack strategies, saving time and resources while keeping everything well-organized.
 
 ### New SuperHashlist
@@ -82,13 +79,13 @@ The page displays all the existing hashlists in the database. To create a new su
 - scroll down to the bottom of the page, and enter a name for the superhashlist in the corresponding field;
 - Click on the *create* button.
 
-You can select all the hashlists at once by clicking on the button *select all*. However, keep in mind that a superhashlist should only contains hash of the same type to work. **We should probably introduce a check at the creation of the super list, and also allow to search or filters to only display those of a specific type to select all in a controlled manner** 
+You can select all the hashlists at once by clicking on the button *select all*. However, keep in mind that a superhashlist should only contain hashes of the same type to work correctly. 
 
 ### Overview
 
-Once you have created a superhashlist or if you open the *SuperHashlist* menu, the overview page of Superhashlist is open. Such page displays all the information about the superhashlists created so far. It is very similar to the hashlist overview page, the only difference being that you cannot archive a superhashlist.
+Once you have created a superhashlist or if you open the *SuperHashlist* menu, the superhashlist overview page opens. This page displays all the information about the superhashlists created so far. It is very similar to the hashlist overview page, the only difference being that you cannot archive a superhashlist.
 
-If you click on a superhashlist, the superhashlist detail page will be open. Again this page is very similar to the hashlist page. The only difference is that it contains the following details about the hashlist(s) contained in the superhashlist:
+If you click on a superhashlist, the superhashlist detail page opens. Again this page is very similar to the hashlist page. The only difference is that it contains the following details about the hashlist(s) contained in the superhashlist:
 - ID of each hashlist
 - Name of each hashlist
 - Cracked percentage of each hashlist
@@ -120,4 +117,4 @@ This page displays all the cracked passwords that have been recovered and that a
 - **Type**: Hashmode related to the hash
 - **Salt**: Salt associated to the hash if relevant.
 
-1.000 entries are displayed per page and there is a search functionalities that is applied on all the field of the table.
\ No newline at end of file
+1,000 entries are displayed per page and a search functionality is available, applied to all the fields of the table.
\ No newline at end of file
diff --git a/doc/user_manual/settings_and_configuration.md b/doc/user_manual/settings_and_configuration.md
index 93ce7f4a2..678bf9a59 100644
--- a/doc/user_manual/settings_and_configuration.md
+++ b/doc/user_manual/settings_and_configuration.md
@@ -51,7 +51,7 @@
 
 - **Forbidden Characters in Attack Command Input**:  List of characters not allowed in the attack command line to prevent injection or command errors.
 
-- **Automatic Assignment of Tasks with Priority 0 (Needed, Check File)**:  Controls whether tasks with priority 0 are automatically assigned to agents or require manual action.
+- **Automatic Assignment of Tasks with Priority 0**:  Controls whether tasks with priority 0 are automatically assigned to agents or require manual action.
 
 - **Display Cracks per Minute for Active Tasks**:  Enables showing real-time statistics of password cracks per minute for currently running tasks.
 
@@ -138,38 +138,6 @@ Click on *+ New Hashtype* to add a new hashtype. Fill the corresponding fields d
 - **Salted**: Salted indicates whether the hash algorithm uses a separate salt value (e.g., vBulletin). It does not apply to algorithms where the salt is embedded within the hash itself (e.g., bcrypt). This setting allows Hashtopolis to automatically check the Salted box when importing a hashlist that uses such an algorithm.
 - **Slow Hash**: Check this box if the hashmode is a computationally intensive (slow) hash function. 
 
-
-
 !!! tip "Tip: Using hashcat to inspect hashmodes"
 
     Considering that the hashmode is configured in your hashcat binary, you can obtain all this information directly from hashcat:
diff --git a/doc/user_manual/tasks.md b/doc/user_manual/tasks.md
index 057a6153d..a2faddffe 100644
--- a/doc/user_manual/tasks.md
+++ b/doc/user_manual/tasks.md
@@ -10,7 +10,7 @@ To create a new task, click on the button "+ New Task" on the *Tasks > Show Task
 
 1. **Name**: Provide a name for the task you want to create. This name will be shown during [task monitoring](./tasks.md#task-overview) and should be descriptive enough for easy identification.
 
-2. **Hashlist**: Select the hashlist you want this task to target. Tasks are ordered by their IDs. [SuperHashlists](./hashlist.md#super-hashlists) are at the bottom of the list ordered by their respective IDs.
+2. **Hashlist**: Select the hashlist you want this task to target. Hashlists are ordered by their IDs. [SuperHashlists](./hashlist.md#super-hashlists) are at the bottom of the list ordered by their respective IDs.
 
 3. **Command Line**: Provide the attack command to be executed by the agent. The placeholder #HL# represents the hashlist and is automatically replaced with the correct path during execution. Do not remove or replace it manually. For example, to perform a 6-digit mask attack, use: ```#HL# -a3 ?d?d?d?d?d?d```. For a dictionary attack with rules, select the necessary files from the right-side panel. Selecting a rule file automatically includes it and the '-r' flag in the command line.
 
@@ -38,7 +38,7 @@ These additional task configuration options allow greater control over execution
 
 13. **Binary type to run the task**: Specify the binary type and version to use for this task. Defaults to the latest available in the [Binaries](./crackers_binary.md#crackers) section. 
 
-14. **Set as preprocessor task**: Such option allows the usage of a preprocessor. By default hashtopolis is installed with a single preprocessor, namely [*Prince*](https://github.com/hashcat/princeprocessor). Additional preprocessors can be defined in the [*preprocessors*](./crackers_binary.md#preprocessors) page. The command that should be used for this preprocessor must be defined in the free text zone below. A task define with a preprocessor will result in the execution of the preprocessor redirecting the output as stdin for the command line defined above in the same task. This allows the usage of "external" candidate generator such as Prince.  
+14. **Set as preprocessor task**: This option allows the usage of a preprocessor. By default Hashtopolis is installed with a single preprocessor, namely [*Prince*](https://github.com/hashcat/princeprocessor). Additional preprocessors can be defined in the [*preprocessors*](./crackers_binary.md#preprocessors) page. The command that should be used for this preprocessor must be defined in the free text zone below. A task defined with a preprocessor will result in the execution of the preprocessor, redirecting its output as stdin for the command line defined above in the same task. This allows the usage of "external" candidate generators such as Prince.  
 
 15. **Skip a given keyspace at the beginning of the task**: Assign an integer value X. Skips the first X candidates in the keyspace, equivalent to adding *-s X* in the Hashcat command. Useful for resuming from a previous partial run.
 
@@ -111,14 +111,14 @@ The **SuperTask menu** shows a list of all supertasks and their associated preco
 
 ### SuperTask in the *ShowTasks* Menu
 
-Supertask are not displayed as regular tasks in the *Show Task* menu as displayed in the picture below. 
+Supertasks are not displayed as regular tasks in the *Show Tasks* menu, as shown in the picture below. 
 
 
 

     ![screenshot_showtask_supertask](../assets/images/supertasks_showtasks.png)
 

 
-The same information than those of a task are displayed. The *copy to Pretask* and *copy to task* options are not available. There is instead an information button which open a pop-up window displaying the list of subtasks of the supertask. This window is identical to the ShowTasks page apart that only the subtasks of the supertask are displayed in it as shown in the figure below. 
+The same information as for a regular task is displayed. The *Copy to Pretask* and *Copy to Task* options are not available. There is instead an information button which opens a pop-up window displaying the list of subtasks of the supertask. This window is identical to the *Show Tasks* page except that only the subtasks of the supertask are displayed in it, as shown in the figure below. 
 
 

     ![screenshot_import_file](../assets/images/supertasks_subtasks.png)
@@ -130,34 +130,47 @@ The **SuperTask Builder** menu offers functionalities to create SuperTasks and t
 
 ### Masks
 
-This functionality allows the user to create a supertask from a mask file or a set of masks. It is a good alternative to replace the --increment option of hashcat that cannot be use in hashtopolis.
+This functionality allows the user to create a supertask from a mask file or a set of masks. It is a good alternative to the --increment option of hashcat that cannot be used in Hashtopolis.
 
 - **Name**: Defines the name that will be given at the created SuperTask
-- **Are small tasks**: If this parameter is set to yes, a single agent can be assigned to the tasks that will be created when the resulting supertask is apply to a hashlist. This is relevant for small tasks or to assign the full keyspace in a single chunk to an agent. Note that this is **NOT** equivalent to define the *Maximum number of agents* to 1. Indeed, in this latter case, the task will still be divided in chunks according to the *chunk size* parameter. The parameter is set to No by default.
-- **Max Agents**: Specify the maximum agents that can be assigned to the tasks that will be created when the resulting supertask is apply to a hashlist. If this amount is reached, future available agents will be assigned to the next task available with a lower priority even if the all the chunks of the task have been distributed. The default value of 0 means that there is no maximum and therefore, all available agents are assigned to this tasks until all the chunks have been distributed. This functionality is helpful to only use a portion of the cluster for a specific task, and therefore allowing to split the workers on different tasks.
+- **Are small tasks**: If this parameter is set to yes, a single agent can be assigned to the tasks that will be created when the resulting supertask is applied to a hashlist. This is relevant for small tasks or to assign the full keyspace in a single chunk to an agent. Note that this is **NOT** equivalent to define the *Maximum number of agents* to 1. Indeed, in this latter case, the task will still be divided in chunks according to the *chunk size* parameter. The parameter is set to No by default.
+- **Max Agents**: Specify the maximum number of agents that can be assigned to the tasks that will be created when the resulting supertask is applied to a hashlist. If this amount is reached, further available agents will be assigned to the next available task with a lower priority, even if not all the chunks of the task have been distributed. The default value of 0 means that there is no maximum and therefore all available agents are assigned to these tasks until all the chunks have been distributed. This functionality is helpful to only use a portion of the cluster for a specific task, allowing to split the workers on different tasks.
 - **Are CPU tasks**: If this parameter is set to yes, only the agents that are declared as CPU only can be assigned to this task. More details can be found in the [agent section](./agents.md) of this manual. The parameter is set to No by default. 
 - **Use Optimized flag (-O)**: If this parameter is set to Yes, the optimized flag -O will be added to the command line of all the sub-tasks of this supertask. The -O flag in Hashcat enables the use of optimized kernels for better performance. This improves cracking speed yet it has an impact on some aspects such as limiting the maximum length of the candidates to be tested, e.g. from 256 to 55 in the case of MD5 or from 256 to 27 for NTLM. 
 - **Benchmark Type**: Select which benchmarking type should be used for the subtasks of the supertask. It is recommended to use the default *Speed Test* for mask attack. Only in few cases, such as tasks with big salted lists, the *Runtime* may be used.
 - **Cracker Binary which is used to run this task**: This parameter specifies the binary type to use for this specific task. 
 - **Insert Masks**: The mask lines that will generate the subtask should be written here. The expected format is the one of a *.hcmask" file for hashcat. In a nutshell, there should be one mask per line following the format **[?1,][?2,][?3,][?4,]mask**, where [?x] specifies the optional charset that can be used in the mask. More details can be found [here](https://hashcat.net/wiki/doku.php?id=mask_attack).
 
-A subtask will be created for each line of the the *Insert masks* text zone and they will be grouped in a supertask. The subtasks are pre-configured task from the database point of view, however they are not displayed in the *Preconfigured Tasks* page. The subtasks that will be generated in this supertasks will be ordered accordingly to their order in the *Insert masks* text zone giving the highest priority to the first line.
+A subtask will be created for each line of the *Insert masks* text zone and they will be grouped in a supertask. The subtasks are pre-configured tasks from the database point of view, however they are not displayed in the *Preconfigured Tasks* page. The subtasks generated in this supertask will be ordered according to their order in the *Insert masks* text zone, giving the highest priority to the first line.
 
 > [!NOTE]
 > Note that the options above will be applied to all the pre-configured tasks that will be created during the generation of the supertasks from this build.
 
 ### Wordlist/Rule bulk
 
-The wordlist/Rule bulk functionality allows to create a set of subtasks for an iteration of several files selected by the user. It allows for example to create an attack strategy of a succession of wordlists to be applied one after the other or to use different rule files with a single wordlist. 
+The Wordlist/Rule bulk functionality allows creating a set of subtasks iterating over several files selected by the user. It allows for example to create an attack strategy consisting of a succession of wordlists to be applied one after the other, or to use different rule files with a single wordlist. 
 
-Most of the options are identical to those of the Mask supertask creation. The main difference is that the *Insert Masks* is obviously not present and is replaced by the *Base Command* option. In this text zone the user is expected to type the command line that should be iterated. Similarly to the *New Task* page, *#HL#* is filled in by default in the command line. It is a placeholder for the hashlist and will be replaced automatically at execution time by the agent with the correct path to the hashlist file. The user then need to select the Rules and Wordlist to use in the supertask. When selecting a file as a base - wether a Rule file, a wordlist or other - the file is immediately added at the command line like in a regular task creation. 
+Most of the options are identical to those of the Masks supertask creation. The main difference is that *Insert Masks* is obviously not present and is replaced by the *Base Command* option. In this text zone the user is expected to type the command line that should be iterated. Similarly to the *New Task* page, *#HL#* is filled in by default in the command line. It is a placeholder for the hashlist and will be replaced automatically at execution time by the agent with the correct path to the hashlist file. The user then needs to select the Rules and Wordlists to use in the supertask. When selecting a file as a base — whether a rule file, a wordlist or other — the file is immediately added to the command line like in a regular task creation. 
 
-Multiple files are expected to be selected as "Iterate". They should be of the same type (rules/wordlists/other), yet this functionality allows to select different type of files. The placeholder **FILE** should be manually placed by the user. During creation of the supertask, one subtask is created for each file selected as iterate replacing the FILE placeholder by one of the "Iterate File". 
+Multiple files are expected to be selected as "Iterate". They should usually be of the same type (rules/wordlists/other), yet this functionality allows selecting different types of files. The placeholder **FILE** should be manually placed by the user. During creation of the supertask, one subtask is created for each file selected as iterate, replacing the FILE placeholder by one of the "Iterate" files. 
 
-Similarly to a regular task, any hashcat parameter can be added to the command line. For example, if the user wants that the Optimized Kernel option (-O) is used, it should be added. That is the reason why this option is not offered to the user among the options contrary to the *Build Masks*.
+Similarly to a regular task, any hashcat parameter can be added to the command line. For example, if the user wants the Optimized Kernel option (-O) to be used, it should be added manually. That is the reason why this option is not offered among the options, contrary to the *Masks* builder.
 
+**Example**: Suppose you want to run the wordlist *rockyou.txt* against the hashlist with three different rule files: *best64.rule*, *dive.rule* and *leetspeak.rule*.
 
-**MAKE AN EXAMPLE WITH SOME FIGURES**
+1. Select *rockyou.txt* as base file — it is automatically appended to the command line.
+2. Write the base command including the **-r FILE** placeholder:
+```
+#HL# -O rockyou.txt -r FILE
+```
+3. Select the three rule files as "Iterate".
+
+When creating the supertask, one subtask is generated per iterated file:
+```
+#HL# -O rockyou.txt -r best64.rule
+#HL# -O rockyou.txt -r dive.rule
+#HL# -O rockyou.txt -r leetspeak.rule
+```
 
 > [!CAUTION]
-> If the iteration is done over rule files, the flag **-r** will not be added when FILE is replaced by the rule file. It should therefore be added in the command line as displayed in the example above. 
+> If the iteration is done over rule files, the flag **-r** will not be added automatically when FILE is replaced by the rule file. It must therefore be included in the base command, as displayed in the example above. 
diff --git a/doc/user_manual/user-settings.md b/doc/user_manual/user-settings.md
index 473bc6abf..c3ca1bdef 100644
--- a/doc/user_manual/user-settings.md
+++ b/doc/user_manual/user-settings.md
@@ -30,9 +30,9 @@ A notification can be triggered for the following triggers (if you are allowed t
 - **newHashlist**: When a new hashlist was created
 - **deleteHashlist**: When a hashlist was deleted
 - **hashlistAllCracked**: When all hashes in a hashlist got cracked
-- **hashlistCrackedHash. When any hash got cracked - 
+- **hashlistCrackedHash**: When any hash got cracked
 > [!CAUTION]
-> You could receive a lot of notifications if you try to crack a large hashlist.
+> The *hashlistCrackedHash* trigger fires for every single crack — you could receive a lot of notifications when cracking a large hashlist.
 - **userCreated**: When a new user was created
 - **userDeleted**: When a user was deleted
 - **userLoginFailed**: When a user login failed
diff --git a/doc/user_manual/users.md b/doc/user_manual/users.md
index a980810d4..b1ba2fadd 100644
--- a/doc/user_manual/users.md
+++ b/doc/user_manual/users.md
@@ -19,13 +19,13 @@ Click on the **+ New User** button to create a new user which will open the user
 
 ### Edit user to set a password
 
-If an email server has not been properly set, it is necessary for the admin to set a password for the newly created user to give her the possibility to login. To do this, click on **edit-user** in the action field for this user as depicted on the picture below. A freely chosen password can then be set. The newly created user can now log in with a user name and password. The rights that the user has are defined in the corresponding permission group and determine which areas will be visible and editable for the new user (see the [Access management](users.md#access-management) section).
+If an email server has not been properly set up, it is necessary for the admin to set a password for the newly created user so that they can log in. To do this, click on **edit-user** in the action field for this user as depicted on the picture below. A freely chosen password can then be set. The newly created user can now log in with a user name and password. The rights that the user has are defined in the corresponding permission group and determine which areas will be visible and editable for the new user (see the [Access management](users.md#access-management) section).
 
 

     ![screenshot_new_user](../assets/images/edit_user.png){ width="600" }
 

 
-In addition, users can be deactivated. A deactivated user can no longer log in. He will receive the error message **Check Credentials**. Deactivated users can be reactivated at any time by an admin.
+In addition, users can be deactivated. A deactivated user can no longer log in. They will receive the error message **Check Credentials**. Deactivated users can be reactivated at any time by an admin.
 
 
 
@@ -38,12 +38,12 @@ The very first step is to create the global permission group. This can be easily
 
 In the second step, the authorizations of the created permission group must be defined. To do this, simply click on **Edit Permission Group** in the overview area. We can now define which rights the global permission group should have for the individual access areas. We differentiate here between the **Create**, **Read**, **Update** and **Delete** events. Depending on the access area, there are dependencies, for example it is partly predefined that the authorization **Create Agent** must also receive the authorization **Reg Voucher**, as the two processes are technically linked. Nevertheless, authorizations can be defined in fine granularity.
 
-We now drag the link to the user administration. Each user must be a member of a permission group, which is selected when the user is created. This ensures that the user has defined authorizations at all times and can only see the areas that are intended. It is important to note that a user can only be a member of a single permission group. The permission group can be changed via the settings under **Edit User**. The individual members of a permission group can be viewed under **Edit Permission Group**. This logic also means that a permission group can only be deleted when no more users belong to it, so that it has been ensured that the users have been transferred to another permission group.
+This connects to the user administration: each user must be a member of a permission group, which is selected when the user is created. This ensures that the user has defined authorizations at all times and can only see the areas that are intended. It is important to note that a user can only be a member of a single permission group. The permission group can be changed via the settings under **Edit User**. The individual members of a permission group can be viewed under **Edit Permission Group**. This logic also means that a permission group can only be deleted when no more users belong to it, so that it has been ensured that the users have been transferred to another permission group.
 
 ### Access Groups
 In the global permissions, we have defined what rights users are generally allowed to have. For example, creating an agent or registering a voucher. The access groups now define the specific objects on which these rights can be executed. Let's do an example of this:
 
-When creating a hash list, I have to define which access group this hash list is assigned to. As a user with the global permission **Create Task,** I can now only see the hash list when creating the task if I am also a member of the corresponding access group. The Access Group can therefore regulate who can see, use and work with which files.
+When creating a hashlist, I have to define which access group this hashlist is assigned to. As a user with the global permission **Create Task**, I can now only see the hashlist when creating the task if I am also a member of the corresponding access group. The Access Group can therefore regulate who can see, use and work with which files.
 The same applies to the agents. I can therefore use the access groups to control who gets which access to my computing resources.
 
 In contrast to the permission groups, a user can be a member of none, one or more access groups in order to keep the options offered by Hashtopolis as flexible as possible.
diff --git a/mkdocs.yml b/mkdocs.yml
index 40b76faae..b827c5c3b 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -21,9 +21,8 @@ nav:
       - user_manual/settings_and_configuration.md
       - user_manual/users.md
       - user_manual/user-settings.md
-  - FAQ and Tips:
+  - FAQ:
       - faq_tips/faq.md
-      - faq_tips/tips.md
   - changelog.md
   - API Reference:
       - APIv2: api.md
@@ -32,6 +31,9 @@ theme:
   name: material
   custom_dir: doc/overrides
   logo: assets/images/logo.png
+  font:
+    text: Roboto
+    code: Fira Code
   palette:
     - scheme: default
       primary: blue
@@ -57,7 +59,7 @@ theme:
     - navigation.footer
     - content.tabs.link
 
-edit_uri: blob/docs/doc/
+edit_uri: edit/master/doc/
 
 markdown_extensions:
   - github-callouts
@@ -68,13 +70,6 @@ markdown_extensions:
 
 extra_css:
   - assets/stylesheets/hero.css
-  - assets/stylesheets/redoc-dark.css
-  
-
-extra:
-  font:
-    text: Roboto
-    code: Fira Code
 
 plugins:
   - swagger-ui-tag
@@ -83,6 +78,3 @@ plugins:
       minify_html: true
   - git-revision-date-localized:
       fallback_to_build_date: true
-
-extra_javascript:
-  - https://cdn.redoc.ly/redoc/latest/bundles/redoc.standalone.js