diff --git a/README.it.md b/README.it.md
new file mode 100644
index 0000000..cd2dea0
--- /dev/null
+++ b/README.it.md
@@ -0,0 +1,399 @@
+
+
+# โก Modular Bashrc Manager
+
+**Un sistema moderno, modulare e velocissimo per organizzare, gestire e scalare la configurazione di Bash su Linux e macOS.**
+
+[](#)
+[](README.md)
+[](https://www.gnu.org/software/bash/)
+[](LICENSE)
+[](https://www.kernel.org/)
+[](https://gitea.sld-server.org/sld-admin/Modular-Bashrc-Manager)
+
+[๐ฌ๐ง **English**](README.md) โข [๐ฎ๐น **Italiano**](README.it.md)
+
+
+
+---
+
+## ๐ Indice dei Contenuti
+
+- [Panoramica](#-panoramica)
+- [Perchรฉ Modular Bashrc Manager?](#-perch%C3%A9-modular-bashrc-manager)
+- [Caratteristiche Principali](#-caratteristiche-principali)
+- [Architettura e Flusso di Caricamento](#-architettura-e-flusso-di-caricamento)
+- [Installazione e Avvio Rapido](#-installazione-e-avvio-rapido)
+ - [Installazione Automatica](#installazione-automatica)
+ - [Cosa fa l'Installer](#cosa-fa-linstaller)
+- [Guida ai Comandi CLI (`brc-script`)](#-guida-ai-comandi-cli-brc-script)
+ - [Tabella Rapida dei Comandi](#tabella-rapida-dei-comandi)
+ - [Esempi di Utilizzo Pratico](#esempi-di-utilizzo-pratico)
+- [Moduli Predefiniti Inclusi](#-moduli-predefiniti-inclusi)
+- [Creazione di Moduli Personalizzati](#-creazione-di-moduli-personalizzati)
+- [Utility Integrate (`ccecho`)](#-utility-integrate-ccecho)
+- [Distribuzioni Supportate](#-distribuzioni-supportate)
+- [Risoluzione Problemi e FAQ](#-risoluzione-problemi-e-faq)
+- [Licenza e Autore](#-licenza-e-autore)
+
+---
+
+## ๐ Panoramica
+
+**Modular Bashrc Manager** sostituisce il tradizionale file unico e disordinato `~/.bashrc` con un'architettura pulita, modulare e disaccoppiata, ispirata al paradigma `available`/`enabled` utilizzato da Debian, Apache e Nginx.
+
+Invece di accumulare centinaia di alias, funzioni, variabili d'ambiente e prompt in un unico file monolitico, la configurazione della shell viene suddivisa in script indipendenti che possono essere abilitati, disabilitati, visualizzati in anteprima, creati o aggiornati in modo sicuro con un solo comando.
+
+```
+~/.bashrc โโโถ Loader โโโถ ~/.bashrc.d/scripts-needed/ (Motore e utility di base)
+ โโโถ ~/.bashrc.d/scripts-enabled/ (Personalizzazioni attive)
+```
+
+---
+
+## ๐ก Perchรฉ Modular Bashrc Manager?
+
+| `~/.bashrc` Monolitico Tradizionale | Con Modular Bashrc Manager |
+| :--- | :--- |
+| โ Centinaia di righe confuse in un solo file | โ
Script modulari, ordinati e dedicati a compiti specifici |
+| โ Difficile isolare bug e testare modifiche | โ
Attiva o disattiva i moduli all'istante (`brc-script -e` / `-d`) |
+| โ Rischio di rompere l'intera shell per un errore | โ
Attivazione sicura tramite symlink e backup automatici |
+| โ Complesso condividere o sincronizzare snippet | โ
File modulari pronti per essere condivisi o versionati |
+| โ Necessitร di aprire editor di testo per leggere i file | โ
Anteprima immediata da terminale con numeri di riga (`brc-script -p`) |
+
+---
+
+## โจ Caratteristiche Principali
+
+- ๐ **Installer Intelligente Multi-Distribuzione**
+ Riconosce automaticamente il gestore di pacchetti del sistema (`apt`, `dnf`, `yum`, `pacman`, `zypper`, `apk`, `brew`) e installa in autonomia le dipendenze necessarie (`jq`, `curl`).
+
+- ๐ **Migrazione Sicura a Rischio Zero**
+ Crea un backup con data/ora del `~/.bashrc` attuale e trasferisce automaticamente tutte le tue impostazioni pregresse in `00_default.sh`: **non perderai nessuna configurazione**.
+
+- โก **Gestione Massiva Multi-Script**
+ Abilita, disabilita, visualizza o rimuovi piรน script simultaneamente passando gli ID numerici o i nomi dei file (es. `brc-script -e 1 3 4` oppure `brc-script -d 03_bashboard 04_aliases`).
+
+- ๐๏ธ **Anteprima Rapida del Codice (`cat`)**
+ Ispeziona il contenuto e la sintassi di uno script direttamente nel terminale con intestazioni colorate e numerazione delle righe senza dover aprire editor esterni (`brc-script -p `).
+
+- ๐ฅ๏ธ **Bashboard di Sistema Intelligente**
+ Include `03_bashboard.sh`, una dashboard stile MOTD veloce che mostra CPU, RAM, dischi, temperatura, IP locali/pubblici, aggiornamenti di sistema e il **rilevamento dinamico automatico della Web UI di Cockpit**.
+
+- ๐ฟ **Evidenziazione Git nel Prompt della CLI**
+ Include hook per il prompt dinamico (`01_git-cli-highlitgh.sh` e `02_git-cli-highlitgh-root.sh`) per mostrare branch Git, file indicizzati (`+`), modificati (`M:`), non tracciati (`N:`) e stato di sincronizzazione remota (`โ`/`โ`).
+
+- ๐ **Aggiornamenti Gitea e Upgrade Sicuro**
+ Verifica la presenza di aggiornamenti sul repository con `brc-script -u` ed effettua l'aggiornamento sicuro del motore con `brc-script --upgrade` senza toccare `00_default.sh` o i tuoi script personali.
+
+- ๐จ **Utility Integrata di Stile `ccecho`**
+ Libreria leggera per stampare testi colorati e formattati su terminale (grassetto, sottolineato, lampeggiante, colori di testo e sfondo).
+
+---
+
+## ๐๏ธ Architettura e Flusso di Caricamento
+
+All'avvio della shell, `~/.bashrc` esegue un loader leggero che carica i moduli in ordine deterministico:
+
+```text
+~/.bashrc.d/
+โโโ .version # Hash di commit/versione installata
+โโโ .update_cache # Cache per i controlli passivi di update da Gitea
+โโโ scripts-needed/ # Script fondamentali del motore (caricati SEMPRE per primi)
+โ โโโ brc-script.sh # Logica centrale e funzioni della CLI
+โ โโโ ccecho.sh # Libreria di output a colori
+โ
+โโโ scripts-available/ # Tutti gli script installati (Libreria dei moduli)
+โ โโโ 00_default.sh # La tua configurazione migrata (Protetta da modifiche)
+โ โโโ 01_git-cli-highlitgh.sh # Prompt Git per utenti standard
+โ โโโ 02_git-cli-highlitgh-root.sh # Prompt Git con distinzione cromatica Root/User
+โ โโโ 03_bashboard.sh # Dashboard metriche e rilevamento Cockpit
+โ โโโ 04_aliases.sh # Alias e scorciatoie di uso comune
+โ
+โโโ scripts-enabled/ # Symlink agli script attivi in scripts-available/
+โ โโโ 00_default.sh -> ../scripts-available/00_default.sh
+โ โโโ 03_bashboard.sh -> ../scripts-available/03_bashboard.sh
+โ
+โโโ scripts-removed/ # Cestino con backup marcati con timestamp degli script eliminati
+```
+
+### Ordine di Esecuzione:
+1. Vengono caricati sequenzialmente tutti i file presenti in `scripts-needed/*.sh`.
+2. Vengono caricati in ordine alfabetico tutti i symlink attivi in `scripts-enabled/*.sh`.
+
+---
+
+## ๐ฅ Installazione e Avvio Rapido
+
+### Installazione Automatica
+
+1. **Clona il repository ufficiale:**
+ ```bash
+ git clone https://gitea.sld-server.org/sld-admin/Modular-Bashrc-Manager.git
+ cd Modular-Bashrc-Manager/installer
+ ```
+
+2. **Avvia lo script di installazione:**
+ ```bash
+ chmod +x brc-script-install.sh
+ ./brc-script-install.sh
+ ```
+
+3. **Ricarica la sessione della shell:**
+ ```bash
+ refresh-brc
+ # oppure: source ~/.bashrc
+ ```
+
+> [!TIP]
+> Puoi eseguire l'installer sia come utente normale che come `root` per configurare qualsiasi utente presente sul sistema.
+
+### Cosa fa l'Installer:
+- ๐ Rileva la distribuzione Linux/macOS e installa `jq` e `curl` se mancanti.
+- ๐พ Crea un backup con data e ora del tuo `~/.bashrc` originale (es. `~/bashrc-backup-2026-08-26_16-00-00`).
+- ๐ Migra il contenuto del vecchio `.bashrc` in `~/.bashrc.d/scripts-available/00_default.sh` e lo abilita immediatamente.
+- ๐งน Sostituisce `~/.bashrc` con il blocco loader minimale e pulito.
+- ๐ฆ Copia i file essenziali in `scripts-needed/` e i moduli standard in `scripts-available/`.
+- ๐ท๏ธ Crea il file `.version` con il commit hash di riferimento.
+
+---
+
+## ๐ป Guida ai Comandi CLI (`brc-script`)
+
+Il comando principale per gestire l'intero ambiente รจ `brc-script`.
+
+### Tabella Rapida dei Comandi
+
+| Azione | Flag / Alias | Argomenti | Descrizione |
+| :--- | :--- | :--- | :--- |
+| **Elenco Script** | `-l`, `--list`, `list` | *nessuno* | Mostra tutti gli script, l'ID numerico e lo stato di attivazione (`-` blu) |
+| **Anteprima / Cat** | `-p`, `-v`, `--cat`, `--show`, `cat` | `` | Stampa a terminale il codice con numeri di riga senza aprire editor |
+| **Abilita** | `-e`, `--enable`, `enable` | `` | Attiva uno o piรน script creando il symlink in `scripts-enabled/` |
+| **Disabilita** | `-d`, `--disable`, `disable` | `` | Disattiva uno o piรน script rimuovendo il symlink |
+| **Abilita Tutti** | `-ea`, `--enable-all`, `enable-all` | *nessuno* | Attiva contemporaneamente tutti gli script disponibili |
+| **Disabilita Tutti**| `-da`, `--disable-all`, `disable-all` | *nessuno* | Disattiva contemporaneamente tutti gli script abilitati |
+| **Crea Script** | `-c`, `--create`, `create` | *nessuno* | Procedura guidata per creare un nuovo script da template e aprirlo nell'editor |
+| **Modifica Script** | `-m`, `--modify`, `modify` | `` | Apre lo script nell'editor (`$EDITOR` o `vim`) con possibilitร di rinominarlo |
+| **Rimuovi Script** | `-r`, `--remove`, `remove` | `` | Sposta in modo sicuro lo script nel cestino `scripts-removed/` con timestamp |
+| **Verifica Update** | `-u`, `--update`, `update` | *nessuno* | Interroga il repository Gitea per rilevare nuovi commit e versioni |
+| **Aggiorna Sistema**| `--upgrade`, `upgrade` | *nessuno* | Aggiorna il motore e i moduli predefiniti senza toccare il tuo codice personale |
+| **Ricarica Shell** | `refresh-brc` | *nessuno* | Ricarica istantaneamente la configurazione `.bashrc` nella sessione corrente |
+
+---
+
+### Esempi di Utilizzo Pratico
+
+#### 1. Elencare i Moduli Disponibili
+```bash
+brc-script -l
+```
+*Esempio di output:*
+```text
+------------------------------------
+ Scripts List
+------------------------------------
+1) 00_default.sh -
+2) 01_git-cli-highlitgh.sh
+3) 02_git-cli-highlitgh-root.sh
+4) 03_bashboard.sh -
+5) 04_aliases.sh
+------------------------------------
+ '-' (blue) = Active / Enabled
+------------------------------------
+```
+
+#### 2. Abilitare Piรน Script in un Solo Comando
+Puoi specificare gli ID numerici o i nomi (con o senza estensione `.sh`):
+```bash
+# Abilita tramite ID numerici
+brc-script -e 2 5
+
+# Abilita tramite nomi degli script
+brc-script -e 01_git-cli-highlitgh 04_aliases
+```
+
+#### 3. Disabilitare Piรน Script Contemporaneamente
+```bash
+# Disabilita per ID
+brc-script -d 2 4 5
+
+# Disabilita per nome
+brc-script -d 03_bashboard 04_aliases
+```
+
+#### 4. Visualizzare l'Anteprima del Codice Direttamente nel Terminale
+Esamina cosa fa uno script prima di attivarlo:
+```bash
+# Anteprima tramite ID numerico
+brc-script -p 4
+
+# Anteprima tramite nome script
+brc-script --cat 03_bashboard
+```
+
+#### 5. Creare un Nuovo Script Personalizzato
+```bash
+brc-script -c
+```
+Verrร richiesto il nome del file (es. `scorciatoie-docker`), verrร generato un template pronto e aperto direttamente nel tuo `$EDITOR` (o `vim`).
+
+#### 6. Verificare e Applicare gli Aggiornamenti
+```bash
+# Controlla la presenza di novitร su Gitea
+brc-script -u
+
+# Effettua l'aggiornamento sicuro del motore
+brc-script --upgrade
+```
+
+> [!NOTE]
+> `brc-script --upgrade` non sovrascrive **mai** il tuo file `00_default.sh` o i tuoi moduli creati manualmente. Vengono aggiornati solo i moduli ufficiali e i componenti di sistema in `scripts-needed/`.
+
+---
+
+## ๐ฆ Moduli Predefiniti Inclusi
+
+### `00_default.sh` โ Configurazione Personale Migrata
+- **Scopo:** Contiene tutti i tuoi alias, funzioni pregresse, variabili d'ambiente ed esportazioni `PATH` migrate durante l'installazione.
+- **Sicurezza:** **Strettamente protetto**. Gli aggiornamenti non modificheranno o sovrascriveranno mai questo file.
+
+### `01_git-cli-highlitgh.sh` โ Prompt Git Interattivo (Utente)
+- **Scopo:** Mostra nel prompt del terminale lo stato del repository Git corrente:
+ - Nome del branch in **Verde** (clean) o **Viola** (file modificati).
+ - `+N`: Numero di file in stage (Verde).
+ - `M:N`: Numero di file modificati (Giallo).
+ - `N:N`: Numero di file non tracciati (Rosso).
+ - `โN` / `โN`: Commit in anticipo o ritardo rispetto al remote (Ciano).
+
+### `02_git-cli-highlitgh-root.sh` โ Prompt Git con Evidenziazione Root
+- **Scopo:** Versione del prompt Git avanzata con colorazione ad alta visibilitร (rosso acceso `#` per l'utente `root`, verde/blu `>` per gli utenti normali).
+
+### `03_bashboard.sh` โ Bashboard di Sistema & Rilevamento Cockpit
+- **Scopo:** Mostra un riepilogo grafico all'apertura del terminale:
+ - Dati della distribuzione e Hostname
+ - Indirizzi IP locali e IP pubblico (con sistema di caching per non rallentare l'avvio)
+ - Uptime di sistema e Carico
+ - Utilizzo di RAM e Disco con soglie di allarme colorate
+ - Temperatura CPU (con riconoscimento automatico delle macchine virtuali)
+ - Pacchetti di aggiornamento disponibili (`apt`, `dnf`, `yum`, `pacman`, `zypper`, `apk`)
+ - **Rilevamento Dinamico di Cockpit:** Riconosce se Cockpit Web UI รจ attivo sul sistema, ne individua la porta d'ascolto e stampa l'URL diretto di accesso.
+
+### `04_aliases.sh` โ Alias Comuni
+- **Scopo:** Raccolta di alias pratici (ad esempio `ls --color`).
+
+---
+
+## ๐ ๏ธ Creazione di Moduli Personalizzati
+
+Aggiungere un nuovo modulo personalizzato รจ estremamente semplice:
+
+1. Avvia la procedura guidata:
+ ```bash
+ brc-script -c
+ ```
+2. Inserisci il nome desiderato (es. `mie-funzioni-docker`).
+3. Scrivi i tuoi alias, funzioni o variabili:
+
+```bash
+#!/bin/bash
+# ============================================================
+# Modular Bashrc - mie-funzioni-docker.sh
+# ============================================================
+
+# Alias personalizzati
+alias dps="docker ps --format 'table {{.Names}}\t{{.Status}}\t{{.Ports}}'"
+alias dlogs="docker logs -f --tail=100"
+
+# Funzione personalizzata con feedback a colori
+dclean() {
+ ccecho -t byellow "Pulizia dei container e immagini inutilizzate..."
+ docker system prune -af --volumes
+ ccecho -t bgreen "Docker pulito con successo!"
+}
+```
+
+4. Salva ed esci dall'editor.
+5. Abilita il nuovo modulo e ricarica:
+ ```bash
+ brc-script -e mie-funzioni-docker
+ refresh-brc
+ ```
+
+---
+
+## ๐จ Utility Integrate (`ccecho`)
+
+Modular Bashrc Manager include l'utility `ccecho` in `scripts-needed/ccecho.sh`, utilizzabile in qualsiasi script per formattare testo e colori ANSI nel terminale:
+
+```bash
+ccecho -t green -s bold "Operazione completata con successo!"
+ccecho -t red -b black -s underline "Errore Fatale: Connessione rifiutata"
+```
+
+### Parametri Supportati:
+- **Colori Testo (`-t` / `--text`):**
+ `black`, `red`, `green`, `yellow`, `blue`, `magenta`, `cyan`, `white`
+ *Varianti brillanti:* `bblack`, `bred`, `bgreen`, `byellow`, `bblue`, `bmagenta`, `bcyan`, `bwhite`
+- **Colori Sfondo (`-b` / `--bg`):**
+ `black`, `red`, `green`, `yellow`, `blue`, `magenta`, `cyan`, `white`
+ *Varianti brillanti:* `bblack`, `bred`, `bgreen`, `byellow`, `bblue`, `bmagenta`, `bcyan`, `bwhite`
+- **Stili del Testo (`-s` / `--style`):**
+ `bold`, `dim`, `italic`, `underline`, `blink`, `reverse`, `hidden`, `strike`
+
+---
+
+## ๐ง Distribuzioni Supportate
+
+Modular Bashrc Manager รจ compatibile e testato con:
+
+| Famiglia | Distribuzioni / Sistemi Operativi | Gestore Pacchetti |
+| :--- | :--- | :--- |
+| **Debian** | Debian, Ubuntu, Linux Mint, Pop!_OS, Raspberry Pi OS | `apt` / `apt-get` |
+| **Red Hat** | Fedora, RHEL, CentOS, Rocky Linux, AlmaLinux | `dnf` / `yum` |
+| **Arch** | Arch Linux, Manjaro, EndeavourOS | `pacman` |
+| **SUSE** | openSUSE Leap, openSUSE Tumbleweed | `zypper` |
+| **Alpine** | Alpine Linux (server e container) | `apk` |
+| **macOS** | Apple macOS (Intel e Apple Silicon) | `brew` (Homebrew) |
+
+---
+
+## โ Risoluzione Problemi e FAQ
+
+### 1. Ho abilitato uno script ma i nuovi comandi non funzionano ancora!
+Esegui il comando di ricarica rapida nel terminale:
+```bash
+refresh-brc
+```
+*(Oppure riapri una nuova scheda del terminale).*
+
+### 2. Come ripristino il mio vecchio `.bashrc` originale?
+L'installer crea automaticamente una copia di backup prima di qualsiasi modifica. Per ripristinarlo:
+```bash
+cp ~/bashrc-backup-* ~/.bashrc
+```
+
+### 3. Dove finiscono gli script che elimino?
+Quando elimini uno script con `brc-script -r `, il file non viene perso in modo irreversibile, ma viene archiviato con marcatura oraria nella cartella:
+```text
+~/.bashrc.d/scripts-removed/
+```
+
+### 4. Come posso cambiare l'editor predefinito di `brc-script`?
+Imposta la variabile d'ambiente `EDITOR` all'interno di `00_default.sh`:
+```bash
+export EDITOR="nano" # oppure "code", "vim", "nvim", "micro"
+```
+
+---
+
+## ๐ Licenza e Autore
+
+- **Autore:** Simone Cusano ([sld-server.org](https://sld-server.org))
+- **Repository Ufficiale:** [https://gitea.sld-server.org/sld-admin/Modular-Bashrc-Manager](https://gitea.sld-server.org/sld-admin/Modular-Bashrc-Manager)
+- **Licenza:** GNU General Public License v3.0 ([GPL-3.0](LICENSE))
+
+---
+
+
+
Sviluppato con โค๏ธ da Simone Cusano. Se trovi utile questo progetto, lascia una stella sul repository!
+
-### A simple, modular, and clean way to manage your `.bashrc` file in Linux.
+# โก Modular Bashrc Manager
+
+**A modern, modular, and blazing-fast system to organize, manage, and scale your Bash configuration in Linux & macOS.**
+
+[](#)
+[](README.it.md)
+[](https://www.gnu.org/software/bash/)
+[](LICENSE)
+[](https://www.kernel.org/)
+[](https://gitea.sld-server.org/sld-admin/Modular-Bashrc-Manager)
+
+[๐ฌ๐ง **English**](README.md) โข [๐ฎ๐น **Italiano**](README.it.md)
+
+
---
-`Modular Bashrc Manager` is a shell-based system designed to keep your Bash configuration clean, structured, and easy to maintain.
-Instead of placing everything directly inside `.bashrc`, this project lets you split your configuration into modular scripts that are loaded automatically at shell startup.
+## ๐ Table of Contents
-The project includes:
-
-- an automated intelligent installer with OS detection and automatic migration
-- a command-line management tool (`brc-script`)
-- a modular directory layout (`scripts-available`, `scripts-enabled`, `scripts-needed`, `scripts-removed`)
-- default ready-to-use scripts (Git highlights, multi-distro bashboard with Cockpit auto-detection, aliases)
-- a reusable colored echo utility (`ccecho`)
-- Gitea update and self-upgrade mechanism
-
-This makes it easier to add, remove, enable, disable, preview, and maintain shell customizations without turning `.bashrc` into a long and messy file.
+- [Overview](#-overview)
+- [Why Modular Bashrc Manager?](#-why-modular-bashrc-manager)
+- [Key Features](#-key-features)
+- [Architecture & Loading Flow](#-architecture--loading-flow)
+- [Installation & Quick Start](#-installation--quick-start)
+ - [Automated Installation](#automated-installation)
+ - [What the Installer Does](#what-the-installer-does)
+- [CLI Reference (`brc-script`)](#-cli-reference-brc-script)
+ - [Command Cheat Sheet](#command-cheat-sheet)
+ - [Usage Examples](#usage-examples)
+- [Included Default Modules](#-included-default-modules)
+- [Creating Custom Modules](#-creating-custom-modules)
+- [Extra Utilities (`ccecho`)](#-extra-utilities-ccecho)
+- [Supported Distributions](#-supported-distributions)
+- [Troubleshooting & FAQ](#-troubleshooting--faq)
+- [License & Author](#-license--author)
---
-## Features
+## ๐ Overview
-- **Modular setup**
- Keep `.bashrc` organized by loading only the scripts you need.
+**Modular Bashrc Manager** replaces the traditional, chaotic, single-file `~/.bashrc` with a clean, decoupled, and modular architecture inspired by the `available`/`enabled` paradigm used by Debian, Apache, and Nginx.
-- **Intelligent Installer & Migration**
- Automatically migrates your pre-existing `.bashrc` into `00_default.sh` and enables it, cleans `.bashrc` to only contain the loader, and installs required tools (`jq`, `curl`) matching your Linux distribution.
+Instead of stuffing hundreds of aliases, functions, exports, and prompt customizations into one monolithic file, you break your shell configuration into distinct, self-contained scripts that can be enabled, disabled, previewed, created, or safely upgraded with a single command.
-- **Multi-Script Management**
- Enable or disable multiple scripts in a single command using numerical IDs or script names (e.g. `brc-script -d 1 5 12 10` or `brc-script -e 01_git-cli-highlitgh 03_bashboard`).
-
-- **Quick Script Preview (`cat`)**
- Inspect script content and line numbers directly from the terminal with `brc-script -p ` without opening text editors.
-
-- **Cockpit Auto-Detection**
- `03_bashboard.sh` automatically detects if Cockpit is installed and running, discovers its listening port dynamically (from `/etc/cockpit/cockpit.conf`, systemd sockets, or 9090), and shows the direct URL.
-
-- **Gitea Updates & Upgrades**
- Check for project updates directly from Gitea with `brc-script --update` and upgrade core and standard scripts safely with `brc-script --upgrade` without touching your personal customizations.
-
-- **Reusable utility functions**
- Includes `ccecho`, a colored echo helper for cleaner terminal output.
+```
+~/.bashrc โโโถ Loader โโโถ ~/.bashrc.d/scripts-needed/ (Core engine & utilities)
+ โโโถ ~/.bashrc.d/scripts-enabled/ (Active customizations)
+```
---
-## How It Works
+## ๐ก Why Modular Bashrc Manager?
-The installer backs up your existing `.bashrc`, migrates its content into `~/.bashrc.d/scripts-available/00_default.sh`, enables it, and replaces `.bashrc` with a minimal loader block.
-
-That block sources scripts from the modular directories:
-
-- `scripts-needed/`
- Essential logic scripts required for the system to work (`brc-script.sh`, `ccecho.sh`).
-- `scripts-enabled/`
- Scripts that should be loaded at shell startup (symlinks to `scripts-available/`).
-- `scripts-available/`
- Scripts that are installed and ready to be enabled or customized.
-- `scripts-removed/`
- Scripts that were removed and stored as timestamped backups.
+| Monolithic `~/.bashrc` | With Modular Bashrc Manager |
+| :--- | :--- |
+| โ Hundreds of lines in a single messy file | โ
Decoupled single-purpose scripts |
+| โ Hard to debug errors and test changes | โ
Enable or disable modules instantly (`brc-script -e` / `-d`) |
+| โ Risk of accidentally breaking the whole shell | โ
Safe symlink-based activation and automatic backups |
+| โ Impossible to share individual snippets | โ
Modular files ready to share, version-control, or reuse |
+| โ Manually editing files to preview snippets | โ
Instant terminal preview with line numbering (`brc-script -p`) |
---
-## Directory Structure
+## โจ Key Features
-After installation, the system uses the following layout:
+- ๐ **Intelligent Multi-Distro Installer**
+ Auto-detects your operating system package manager (`apt`, `dnf`, `yum`, `pacman`, `zypper`, `apk`, `brew`) and automatically installs required dependencies (`jq`, `curl`).
+
+- ๐ **Zero-Loss Safe Migration**
+ Creates a timestamped backup of your current `~/.bashrc` and automatically migrates your pre-existing customizations into `00_default.sh` so you lose **nothing**.
+
+- โก **Multi-Script Batch Management**
+ Enable, disable, preview, or remove multiple scripts at the same time using either their numeric ID or script name (e.g. `brc-script -e 1 3 4` or `brc-script -d 03_bashboard 04_aliases`).
+
+- ๐๏ธ **Instant Script Code Preview (`cat`)**
+ View script contents with colored status headers and line numbering without opening an external editor (`brc-script -p `).
+
+- ๐ฅ๏ธ **Smart System Bashboard**
+ Includes `03_bashboard.sh`, a fast MOTD-style dashboard showing CPU, RAM, disk usage, uptime, distro details, IP addresses, package update counts, and **automatic dynamic discovery of Cockpit Web UI**.
+
+- ๐ฟ **Git CLI Status Highlighting**
+ Includes dynamic prompt hooks (`01_git-cli-highlitgh.sh` & `02_git-cli-highlitgh-root.sh`) that show current Git branch, staged (`+`), modified (`M:`), untracked (`N:`), and remote sync (`โ`/`โ`) status directly in your prompt.
+
+- ๐ **Gitea Updates & Safe Upgrades**
+ Check for official updates with `brc-script -u` and safely upgrade core files with `brc-script --upgrade` without touching personal configurations or `00_default.sh`.
+
+- ๐จ **Built-in `ccecho` Styling Utility**
+ Lightweight utility for terminal coloring and styling (bold, underline, dim, blink, colors, backgrounds).
+
+---
+
+## ๐๏ธ Architecture & Loading Flow
+
+When your shell starts, `~/.bashrc` executes a minimal loader loop that sources modules in a deterministic order:
```text
~/.bashrc.d/
-โโโ .version
-โโโ scripts-needed/
-โ โโโ brc-script.sh
-โ โโโ ccecho.sh
-โโโ scripts-available/
-โ โโโ 00_default.sh
-โ โโโ 01_git-cli-highlitgh.sh
-โ โโโ 02_git-cli-highlitgh-root.sh
-โ โโโ 03_bashboard.sh
-โ โโโ 04_aliases.sh
-โโโ scripts-enabled/
-โ โโโ 00_default.sh -> ~/.bashrc.d/scripts-available/00_default.sh
-โโโ scripts-removed/
+โโโ .version # Current commit/version tracking hash
+โโโ .update_cache # Cache for passive Gitea update checks
+โโโ scripts-needed/ # Essential engine scripts (Always loaded first)
+โ โโโ brc-script.sh # Main CLI manager logic & functions
+โ โโโ ccecho.sh # Colored terminal printing engine
+โ
+โโโ scripts-available/ # All installed scripts (Library of modules)
+โ โโโ 00_default.sh # Your personal migrated config (Protected)
+โ โโโ 01_git-cli-highlitgh.sh # Git branch & status prompt (User)
+โ โโโ 02_git-cli-highlitgh-root.sh # Git branch & status prompt (Root/User color-coded)
+โ โโโ 03_bashboard.sh # System metrics & Cockpit auto-detection
+โ โโโ 04_aliases.sh # General utility aliases
+โ
+โโโ scripts-enabled/ # Symlinks pointing to active scripts in scripts-available/
+โ โโโ 00_default.sh -> ../scripts-available/00_default.sh
+โ โโโ 03_bashboard.sh -> ../scripts-available/03_bashboard.sh
+โ
+โโโ scripts-removed/ # Recycle bin with timestamped backups of removed scripts
```
+### Loading Order:
+1. All files in `scripts-needed/*.sh` are sourced sequentially.
+2. All active symlinks in `scripts-enabled/*.sh` are sourced alphabetically.
+
---
-## Installation
+## ๐ฅ Installation & Quick Start
### Automated Installation
-1. Clone the repository from the official Gitea server:
+1. **Clone the repository:**
+ ```bash
+ git clone https://gitea.sld-server.org/sld-admin/Modular-Bashrc-Manager.git
+ cd Modular-Bashrc-Manager/installer
+ ```
-```bash
-git clone https://gitea.sld-server.org/sld-admin/Modular-Bashrc-Manager
-cd Modular-Bashrc-Manager/installer
-```
+2. **Run the installer:**
+ ```bash
+ chmod +x brc-script-install.sh
+ ./brc-script-install.sh
+ ```
-2. Make the installer executable and run it:
+3. **Reload your shell:**
+ ```bash
+ refresh-brc
+ # or: source ~/.bashrc
+ ```
-```bash
-chmod +x brc-script-install.sh
-./brc-script-install.sh
-```
+> [!TIP]
+> You can run the installer as a normal user or as `root` to configure any user on the system.
-### What the installer does:
-- Detects the Linux distribution (`apt`, `dnf`, `yum`, `pacman`, `zypper`, `apk`, `brew`) and automatically installs `jq` and `curl` if missing.
-- Creates timestamped backup of your current `.bashrc`.
-- Automatically copies your existing `.bashrc` content into `~/.bashrc.d/scripts-available/00_default.sh` and enables it.
-- Writes the clean modular loader block to `.bashrc`.
-- Copies core scripts to `scripts-needed/` and default scripts to `scripts-available/`.
-- Initializes the `.version` file for future update tracking.
-
-3. Reload `.bashrc`:
-
-```bash
-source ~/.bashrc
-# or run: refresh-brc
-```
+### What the Installer Does:
+- ๐ Detects OS distribution and installs `jq` and `curl` automatically.
+- ๐พ Creates a timestamped backup of your current `~/.bashrc` (e.g. `~/bashrc-backup-2026-08-26_16-00-00`).
+- ๐ Migrates existing `.bashrc` lines into `~/.bashrc.d/scripts-available/00_default.sh` and enables it immediately.
+- ๐งน Replaces `~/.bashrc` with the clean, non-intrusive modular loader block.
+- ๐ฆ Deploys the core logic to `scripts-needed/` and default modules to `scripts-available/`.
+- ๐ท๏ธ Initializes `.version` with the latest Git commit hash.
---
-## Usage (`brc-script`)
+## ๐ป CLI Reference (`brc-script`)
-The main command-line management tool is `brc-script`.
+`brc-script` is the central command-line utility for administering your modular configuration.
-### Available Commands
+### Command Cheat Sheet
-| Command | Alias / Flags | Description |
-| :--- | :--- | :--- |
-| **List Scripts** | `brc-script -l` / `--list` | Lists all available scripts and indicates active/enabled status (`-`). |
-| **Preview / Cat Script** | `brc-script -p` / `--cat ` | Prints script source code with line numbers and status without opening an editor. |
-| **Enable Script(s)** | `brc-script -e` / `--enable ` | Enables one or multiple scripts by numeric ID or name. |
-| **Disable Script(s)** | `brc-script -d` / `--disable ` | Disables one or multiple scripts by numeric ID or name. |
-| **Enable All** | `brc-script -ea` / `--enable-all` | Enables all available scripts. |
-| **Disable All** | `brc-script -da` / `--disable-all` | Disables all currently enabled scripts. |
-| **Create Script** | `brc-script -c` / `--create` | Prompts for a name, generates a template, and opens it in your editor. |
-| **Modify Script** | `brc-script -m` / `--modify ` | Opens a script in editor and allows renaming. |
-| **Remove Script** | `brc-script -r` / `--remove ` | Moves script(s) to `scripts-removed/` with a timestamp. |
-| **Check Updates** | `brc-script -u` / `--update` | Queries Gitea repository for latest commits and new updates. |
-| **Upgrade System** | `brc-script --upgrade` | Upgrades core and default scripts from Gitea (never touches `00_default.sh`). |
-| **Reload Shell** | `refresh-brc` | Reloads `.bashrc` in current session. |
+| Action | Flags / Aliases | Arguments | Description |
+| :--- | :--- | :--- | :--- |
+| **List** | `-l`, `--list`, `list` | *none* | Lists all scripts with IDs, names, and active status (`-` in blue) |
+| **Preview** | `-p`, `-v`, `--cat`, `--show`, `cat` | `` | Prints script code with line numbers without opening an editor |
+| **Enable** | `-e`, `--enable`, `enable` | `` | Activates one or more scripts by creating symlinks in `scripts-enabled/` |
+| **Disable** | `-d`, `--disable`, `disable` | `` | Deactivates one or more scripts by removing symlinks |
+| **Enable All** | `-ea`, `--enable-all`, `enable-all` | *none* | Enables all available scripts at once |
+| **Disable All** | `-da`, `--disable-all`, `disable-all` | *none* | Disables all enabled scripts at once |
+| **Create** | `-c`, `--create`, `create` | *none* | Interactive wizard to create a new script template and open it in `$EDITOR` |
+| **Modify** | `-m`, `--modify`, `modify` | `` | Opens a script in `$EDITOR` (or `vim`) and allows renaming |
+| **Remove** | `-r`, `--remove`, `remove` | `` | Safely moves script(s) to `scripts-removed/` with a timestamp |
+| **Update** | `-u`, `--update`, `update` | *none* | Queries Gitea repository for new commits/updates |
+| **Upgrade** | `--upgrade`, `upgrade` | *none* | Safely upgrades core scripts and default modules without altering your custom code |
+| **Reload** | `refresh-brc` | *none* | Immediately reloads `~/.bashrc` in the current shell session |
---
-### Command Examples
+### Usage Examples
-#### 1. Listing scripts
+#### 1. Listing All Available Modules
```bash
brc-script -l
```
-
-#### 2. Enabling multiple scripts at once (by ID or Name)
-```bash
-# Enable by multiple IDs
-brc-script -e 1 3 4
-
-# Enable by script names (with or without .sh)
-brc-script -e 01_git-cli-highlitgh 03_bashboard
+*Output preview:*
+```text
+------------------------------------
+ Scripts List
+------------------------------------
+1) 00_default.sh -
+2) 01_git-cli-highlitgh.sh
+3) 02_git-cli-highlitgh-root.sh
+4) 03_bashboard.sh -
+5) 04_aliases.sh
+------------------------------------
+ '-' (blue) = Active / Enabled
+------------------------------------
```
-#### 3. Disabling multiple scripts at once
+#### 2. Enabling Multiple Scripts in One Command
+You can pass numbers, names with `.sh`, or names without `.sh`:
```bash
-# Disable multiple IDs
-brc-script -d 1 5 12 10
+# Enable by numerical IDs
+brc-script -e 2 5
-# Disable by name
+# Enable by script names
+brc-script -e 01_git-cli-highlitgh 04_aliases
+```
+
+#### 3. Disabling Multiple Scripts
+```bash
+# Disable by IDs
+brc-script -d 2 4 5
+
+# Disable by names
brc-script -d 03_bashboard 04_aliases
```
-#### 4. Quick viewing / catting script contents
+#### 4. Previewing Script Code Directly in Terminal
+Inspect what a script does before enabling it:
```bash
-# Preview by name
-brc-script -p 03_bashboard
+# Preview using numeric ID
+brc-script -p 4
-# Preview by numerical ID
-brc-script --cat 2
+# Preview using script name
+brc-script --cat 03_bashboard
```
-#### 5. Checking and applying Gitea updates
+#### 5. Creating a New Custom Script
```bash
-# Check if new versions or commits are available
-brc-script --update
+brc-script -c
+```
+Prompts for a script name (e.g. `docker-shortcuts`), sets up a boilerplate header, and opens it directly in `$EDITOR` (or `vim`).
-# Perform safe self-upgrade from Gitea
+#### 6. Checking and Performing Upgrades
+```bash
+# Check if updates are available on Gitea
+brc-script -u
+
+# Upgrade core engine and default templates
brc-script --upgrade
```
----
-
-## Included Default Scripts
-
-### `00_default.sh` โ Personal Configuration & Migration
-Contains all your original aliases, functions, and environment variables migrated during installation. This file is yours and is never overwritten during upgrades.
-
-### `01_git-cli-highlitgh.sh` & `02_git-cli-highlitgh-root.sh` โ Git Prompt
-Shows branch name, uncommitted changes, staged files, untracked files, and ahead/behind remote indicators directly in your prompt.
-
-### `03_bashboard.sh` โ Terminal System Dashboard
-Displays CPU, RAM, disk usage, IP addresses, distro info, uptime, available packages updates, and automatically discovers **Cockpit Web UI** if installed (with dynamic port detection).
-
-### `04_aliases.sh` โ Common Aliases
-Useful starting aliases such as `alias ls="ls --color"`.
+> [!NOTE]
+> `brc-script --upgrade` will **never** overwrite your `00_default.sh` or custom scripts. Only standard upstream modules and `scripts-needed/` utilities are updated.
---
-## Extra Utilities: `ccecho`
+## ๐ฆ Included Default Modules
-The project includes `ccecho.sh` in `scripts-needed/` for formatted and colored terminal output.
+### `00_default.sh` โ Your Personal Migrated Configuration
+- **Purpose:** Houses all your existing aliases, functions, environment variables, and `PATH` exports migrated during installation.
+- **Safety:** **Strictly protected**. Upgrades will never touch or overwrite this file.
+
+### `01_git-cli-highlitgh.sh` โ Git Status Prompt (User)
+- **Purpose:** Adds a clean, color-coded Git branch and status indicator to your bash prompt:
+ - Branch name in **Green** (clean) or **Purple** (dirty).
+ - `+N`: Staged files count (Green).
+ - `M:N`: Modified files count (Yellow).
+ - `N:N`: Untracked files count (Red).
+ - `โN` / `โN`: Commits ahead / behind remote (Cyan).
+
+### `02_git-cli-highlitgh-root.sh` โ Git Status Prompt (Root / Multi-User)
+- **Purpose:** High-visibility Git prompt tailored for multi-user/root environments. Displays red alert styling for `root` (`#`) and green/blue for normal users (`>`).
+
+### `03_bashboard.sh` โ Terminal MOTD & Cockpit Discovery
+- **Purpose:** Displays an interactive system dashboard upon login:
+ - Distro details and Hostname
+ - Local and Public IP addresses
+ - System Uptime & Load
+ - Memory (RAM) & Disk usage with color-coded thresholds
+ - CPU Temperature (with VM detection)
+ - Pending Package Updates count (`apt`, `dnf`, `yum`, `pacman`, `zypper`, `apk`)
+ - **Dynamic Cockpit Web UI Detection:** Detects if Cockpit is installed and running, extracts its listening port from configuration/sockets, and displays the direct URL.
+
+### `04_aliases.sh` โ Essential Aliases
+- **Purpose:** Handy starting aliases (e.g., colorized directory listings).
+
+---
+
+## ๐ ๏ธ Creating Custom Modules
+
+Creating your own modular script is simple:
+
+1. Run the creator wizard:
+ ```bash
+ brc-script -c
+ ```
+2. Enter the script name (e.g. `my-docker-tools`).
+3. Add your custom functions, aliases, and environment variables:
```bash
-ccecho -t green -b black -s bold "Success!"
-ccecho -t red -s underline "Error!"
+#!/bin/bash
+# ============================================================
+# Modular Bashrc - my-docker-tools.sh
+# ============================================================
+
+# Custom aliases
+alias dps="docker ps --format 'table {{.Names}}\t{{.Status}}\t{{.Ports}}'"
+alias dlogs="docker logs -f --tail=100"
+
+# Custom function
+dclean() {
+ ccecho -t byellow "Cleaning unused Docker containers and images..."
+ docker system prune -af --volumes
+ ccecho -t bgreen "Docker cleaned successfully!"
+}
```
-**Text colors:** `black`, `red`, `green`, `yellow`, `blue`, `magenta`, `cyan`, `white`, `bblack`, `bred`, `bgreen`, `byellow`, `bblue`, `bmagenta`, `bcyan`, `bwhite`.
-**Styles:** `bold`, `dim`, `italic`, `underline`, `blink`, `reverse`, `hidden`, `strike`.
+4. Save and exit the editor.
+5. Enable your new module:
+ ```bash
+ brc-script -e my-docker-tools
+ refresh-brc
+ ```
---
-## Official Repository & Updates
+## ๐จ Extra Utilities (`ccecho`)
-- **Gitea:** [https://gitea.sld-server.org/sld-admin/Modular-Bashrc-Manager](https://gitea.sld-server.org/sld-admin/Modular-Bashrc-Manager)
-- **Author:** Simone Cusano ([https://sld-server.org](https://sld-server.org))
+Modular Bashrc Manager includes `ccecho`, a high-performance ANSI text formatting helper located in `scripts-needed/ccecho.sh`. You can use it in any of your custom scripts:
+
+```bash
+ccecho -t green -s bold "Operation succeeded!"
+ccecho -t red -b black -s underline "Fatal Error: Connection refused"
+```
+
+### Available Options:
+- **Text Colors (`-t` / `--text`):**
+ `black`, `red`, `green`, `yellow`, `blue`, `magenta`, `cyan`, `white`
+ *Bright variants:* `bblack`, `bred`, `bgreen`, `byellow`, `bblue`, `bmagenta`, `bcyan`, `bwhite`
+- **Background Colors (`-b` / `--bg`):**
+ `black`, `red`, `green`, `yellow`, `blue`, `magenta`, `cyan`, `white`
+ *Bright variants:* `bblack`, `bred`, `bgreen`, `byellow`, `bblue`, `bmagenta`, `bcyan`, `bwhite`
+- **Text Styles (`-s` / `--style`):**
+ `bold`, `dim`, `italic`, `underline`, `blink`, `reverse`, `hidden`, `strike`
---
-## License
+## ๐ง Supported Distributions
-This project is licensed under the GNU General Public License v3.0.
+Modular Bashrc Manager has been tested and includes native package detection for:
+
+| Family | Distributions / Systems | Package Manager |
+| :--- | :--- | :--- |
+| **Debian** | Debian, Ubuntu, Linux Mint, Pop!_OS, Raspberry Pi OS | `apt` / `apt-get` |
+| **Red Hat** | Fedora, RHEL, CentOS, Rocky Linux, AlmaLinux | `dnf` / `yum` |
+| **Arch** | Arch Linux, Manjaro, EndeavourOS | `pacman` |
+| **SUSE** | openSUSE Leap, openSUSE Tumbleweed | `zypper` |
+| **Alpine** | Alpine Linux (containers & servers) | `apk` |
+| **macOS** | Apple macOS (Intel & Apple Silicon) | `brew` (Homebrew) |
+
+---
+
+## โ Troubleshooting & FAQ
+
+### 1. I enabled a script, but new commands aren't working yet!
+Run the reload command in your terminal:
+```bash
+refresh-brc
+```
+*(Or restart your terminal session).*
+
+### 2. How do I restore my original `.bashrc`?
+The installer automatically creates a timestamped backup before touching anything. To restore:
+```bash
+cp ~/bashrc-backup-* ~/.bashrc
+```
+
+### 3. Where are removed scripts stored?
+When you delete a script with `brc-script -r `, it is never permanently deleted; it is timestamped and safely placed in:
+```text
+~/.bashrc.d/scripts-removed/
+```
+
+### 4. How can I change the default text editor for `brc-script`?
+Set the `EDITOR` environment variable in your `00_default.sh`:
+```bash
+export EDITOR="nano" # or "code", "vim", "nvim", "micro"
+```
+
+---
+
+## ๐ License & Author
+
+- **Author:** Simone Cusano ([sld-server.org](https://sld-server.org))
+- **Repository:** [https://gitea.sld-server.org/sld-admin/Modular-Bashrc-Manager](https://gitea.sld-server.org/sld-admin/Modular-Bashrc-Manager)
+- **License:** GNU General Public License v3.0 ([GPL-3.0](LICENSE))
+
+---
+
+
+
Made with โค๏ธ by Simone Cusano. If you find this project helpful, feel free to star and share it!
+