diff --git a/README.md b/README.md
index 78dbe33..03a27eb 100644
--- a/README.md
+++ b/README.md
@@ -27,6 +27,36 @@ make fclean   # remove .o files and the binary
 
 ## Project Architecture
 
+```mermaid
+flowchart TD
+    START([42sh binary]) --> INIT["init_main(env)\nbuild env_t list · parse PATH · load .c_zsh_history · load .czshrc"]
+    INIT --> SIGS["setup_shell_signals()\nSIGINT / SIGTSTP / SIGQUIT → SIG_IGN · shell becomes pgid leader"]
+    SIGS --> REPL
+
+    subgraph REPL ["REPL loop  —  src/core/main.c"]
+        PROMPT["display_prompt()\nfolder · user · git branch · time/date with ANSI colors"] --> INPUT["get_command()\nraw-termios char-by-char loop  or  getline (non-TTY)"]
+        INPUT --> HIST["manage_history()\nappend to ~/.c_zsh_history"]
+        HIST --> EXEC["execute_command()\nsplit on ';' (quote-aware)"]
+    end
+
+    EXEC --> D{segment type?}
+    D -->|"&& / ||"| OP["execute_operator()\nshort-circuit evaluation of chained commands"]
+    D -->|"|"| PIPE["execute_pipeline()\nfork · pipe FDs · wait all PIDs"]
+    D -->|plain| SINGLE["execute_single_command()\nparse_command_context  →  $VAR expand  →  quote convert"]
+
+    OP --> SINGLE
+    PIPE --> SINGLE
+
+    SINGLE --> E{builtin?}
+    E -->|yes| BUILTIN["execute_builtin()\nenv · setenv · unsetenv · cd · which · where\nprintenv · repeat · foreach · history · source"]
+    E -->|no| EXT["exec_any()\nloop_bin (PATH search) → run_fork (fork + execve + waitpid)"]
+
+    BUILTIN --> REPL
+    EXT --> REPL
+
+    style REPL fill:#e3f2fd,stroke:#1565c0,color:#000
+```
+
 ```
 42sh/
 ├── Makefile
diff --git a/docs/ARCHITECTURE_DIAGRAM.mmd b/docs/ARCHITECTURE_DIAGRAM.mmd
index 43c8d53..aa7a009 100644
--- a/docs/ARCHITECTURE_DIAGRAM.mmd
+++ b/docs/ARCHITECTURE_DIAGRAM.mmd
@@ -18,7 +18,7 @@ flowchart TD
     subgraph REPL ["LOOP 1 — REPL  ·  while buffer ≠ 'exit'  ·  src/core/main.c"]
         direction TB
 
-        PROMPT_DRAW["write_print()\nstyled prompt: dir · git branch · user"]
+        PROMPT_DRAW["write_print() → display_prompt()\nfolder · user · git branch · time/date (ANSI colors)"]
         PROMPT_DRAW --> TTY_CHECK
 
         %% ─────────────────────────────────────────────────────────────
@@ -60,7 +60,7 @@ flowchart TD
 
         LINE_READY --> SERIALIZE["serialize()\ntrim leading/trailing whitespace"]
         GETLINE --> SERIALIZE
-        SERIALIZE --> ADD_HIST["add_to_history(buffer)\nappend to ~/.c_zsh_history"]
+        SERIALIZE --> ADD_HIST["manage_history(history, buffer)\nappend to ~/.c_zsh_history"]
         ADD_HIST --> EXEC_CMD["execute_command(buffer)"]
 
         %% ─────────────────────────────────────────────────────────────
diff --git a/src/builtins/config/source.c b/src/builtins/config/source.c
index ea6ccee..f80b579 100644
--- a/src/builtins/config/source.c
+++ b/src/builtins/config/source.c
@@ -2,9 +2,9 @@
 ** EPITECH PROJECT, 2026
 ** 42sh
 ** File description:
-** source / . builtin: opens the file with openator(), splits it
-** into lines with str_to_array_of_word_array(), then executes
-** each line via exec_any() in the current shell context.
+** source / . builtin: reloads the shell config by calling update_rc()
+** with ctx->argv[1] as the target file path, immediately applying
+** RC settings to the running shell; command execution from file pending.
 ** Authors: @Celz-Pch @Lukas-sgx @ErwanTheKing @sacha-lma @Jessymgadd
 */
 
diff --git a/src/builtins/history/history.c b/src/builtins/history/history.c
index c777606..b75283c 100644
--- a/src/builtins/history/history.c
+++ b/src/builtins/history/history.c
@@ -2,9 +2,9 @@
 ** EPITECH PROJECT, 2026
 ** 42sh
 ** File description:
-** history builtin: iterates the history_cmd_t doubly-linked list
-** from oldest to newest and prints each entry as:
-**   ID  HH:MM  command
+** history builtin: opens .c_zsh_history and dispatches to write_history
+** (last N entries, oldest-first) or write_reverse_history (-r flag,
+** newest-first up to N); N defaults to the full file when omitted.
 ** Authors: @Celz-Pch @Lukas-sgx @ErwanTheKing @sacha-lma @Jessymgadd
 */
 
diff --git a/src/builtins/repeat/repeat.c b/src/builtins/repeat/repeat.c
index 55364e5..4b7db97 100644
--- a/src/builtins/repeat/repeat.c
+++ b/src/builtins/repeat/repeat.c
@@ -2,9 +2,9 @@
 ** EPITECH PROJECT, 2026
 ** 42sh
 ** File description:
-** repeat builtin: builtin_repeat validates the count argument
-** with my_char_isnum; repeat() runs exec_any() in a for loop
-** 0..N-1 and returns the exit code of the last iteration.
+** repeat builtin: parses the count with atoi(), sets up a shifted
+** command_ctx_t pointing to the command after N, then runs exec_any()
+** in a loop 0..N-1 and returns the exit code of the last iteration.
 ** Authors: @Celz-Pch @Lukas-sgx @ErwanTheKing @sacha-lma @Jessymgadd
 */
 
diff --git a/src/config/manage_prompt.c b/src/config/manage_prompt.c
index 6fcd9d7..e0d5280 100644
--- a/src/config/manage_prompt.c
+++ b/src/config/manage_prompt.c
@@ -2,9 +2,9 @@
 ** EPITECH PROJECT, 2026
 ** 42sh
 ** File description:
-** Prompt configuration parser: get_color/get_b_color convert
-** color name strings to ANSI codes; manage_format, manage_time,
-** manage_date, manage_branche, manage_folder, manage_user fill
+** Prompt config parser: get_color/get_b_color map color name strings
+** to ANSI codes; manage_prompt dispatches [prompt] key=value pairs
+** to manage_user, manage_folder, manage_branche, manage_date, manage_time.
 ** Authors: @Celz-Pch @Lukas-sgx @ErwanTheKing @sacha-lma @Jessymgadd
 */
 
diff --git a/src/utils/display/display_time.c b/src/utils/display/display_time.c
index 0e1efd8..caa0ece 100644
--- a/src/utils/display/display_time.c
+++ b/src/utils/display/display_time.c
@@ -2,9 +2,9 @@
 ** EPITECH PROJECT, 2026
 ** 42sh
 ** File description:
-** Time display: display_time prints current HH:MM right-aligned
-** using terminal column count from ioctl(TIOCGWINSZ).
-** check_null_win falls back to 80 columns when ioctl fails.
+** Time/date display: computes right-padding via ioctl(TIOCGWINSZ) and
+** calculate_limit, then prints HH:MM:SS via displauy_time() and the date
+** in LONG/EU/US/ISO format via display_date(), both with ANSI color support.
 ** Authors: @Celz-Pch @Lukas-sgx @ErwanTheKing @sacha-lma @Jessymgadd
 */
 
diff --git a/src/utils/display/get_folder.c b/src/utils/display/get_folder.c
index 77745ae..69296b5 100644
--- a/src/utils/display/get_folder.c
+++ b/src/utils/display/get_folder.c
@@ -2,9 +2,9 @@
 ** EPITECH PROJECT, 2026
 ** 42sh
 ** File description:
-** Working directory for the prompt: get_folder calls getcwd()
-** then shortens the path to its last two components
-** (e.g. 'project/src') for a compact prompt appearance.
+** Working directory for the prompt: get_folder calls getcwd(),
+** splits on '/' and returns a heap-allocated copy of the last
+** path component for compact display in the shell prompt.
 ** Authors: @Celz-Pch @Lukas-sgx @ErwanTheKing @sacha-lma @Jessymgadd
 */
 
diff --git a/src/utils/errors/foreach.c b/src/utils/errors/foreach.c
index d09e029..4c50a7b 100644
--- a/src/utils/errors/foreach.c
+++ b/src/utils/errors/foreach.c
@@ -2,9 +2,9 @@
 ** EPITECH PROJECT, 2026
 ** 42sh
 ** File description:
-** foreach error helper: put_error_var prints a tcsh-compatible
-** error message to stderr when the foreach loop variable name
-** is invalid (must start with a letter, alphanumeric + _ only).
+** foreach error helper: put_error_var prints "VAR: Undefined variable."
+** to stdout via my_putstr and returns FAILURE; called when a loop
+** variable cannot be resolved during foreach execution.
 ** Authors: @Celz-Pch @Lukas-sgx @ErwanTheKing @sacha-lma @Jessymgadd
 */
 
diff --git a/src/utils/io/my_putnbr.c b/src/utils/io/my_putnbr.c
index e368885..c1e1aec 100644
--- a/src/utils/io/my_putnbr.c
+++ b/src/utils/io/my_putnbr.c
@@ -2,9 +2,9 @@
 ** EPITECH PROJECT, 2026
 ** 42sh
 ** File description:
-** Integer output: my_putnbr recursively decomposes an integer
-** into decimal digits (with INT_MIN handled separately) and
-** writes each digit to stdout with my_putchar.
+** Integer output: my_putnbr writes the sign if negative, then
+** recursively decomposes the absolute value into decimal digits
+** and writes each to stdout via write(1); INT_MIN is not handled.
 ** Authors: @Celz-Pch @Lukas-sgx @ErwanTheKing @sacha-lma @Jessymgadd
 */
 
diff --git a/src/utils/validation/my_str_is_alphanum.c b/src/utils/validation/my_str_is_alphanum.c
index 4adeaa1..725edb7 100644
--- a/src/utils/validation/my_str_is_alphanum.c
+++ b/src/utils/validation/my_str_is_alphanum.c
@@ -2,9 +2,9 @@
 ** EPITECH PROJECT, 2026
 ** 42sh
 ** File description:
-** Full key name check: my_str_is_alphanum returns 1 if every
-** character is a letter, digit, or underscore, used by setenv
-** to validate the complete variable key name.
+** Variable name validator: my_str_is_alphanum returns 1 if any
+** character in the string is not in [a-z A-Z 0-9], used by setenv
+** and foreach to reject invalid environment variable names.
 ** Authors: @Celz-Pch @Lukas-sgx @ErwanTheKing @sacha-lma @Jessymgadd
 */