feat: add support for ~/.zshrc.local for user customizations

conf/zshrc-linux.zsh

@@ -68,8 +68,8 @@ alias spup="uv tool upgrade specify-cli"        # Atualiza o Spec-Kit para a ver
 
 # --- Shell ---
 alias zconfig="nano ~/.zshrc"                   # Edita o arquivo de configuração do ZSH
-alias reload="source ~/.zshrc"                  # Recarrega as configurações do ZSH sem reiniciar o terminal
-alias path='echo -e ${PATH//:/\\n}'             # Exibe cada entrada do PATH em uma linha separada
+alias reload="source ~/.zshrc && source ~/.zshrc.local"  # Recarrega as configurações do ZSH e as personalizadas locais sem reiniciar o terminal
+alias path='echo -e ${PATH//:/\\n}'                      # Exibe cada entrada do PATH em uma linha separada
 alias h="history | grep"                        # Busca no histórico de comandos (ex: h docker)
 alias cls="clear"                               # Limpa o terminal
 alias please="sudo"                             # Atalho amigável para sudo
@@ -382,3 +382,13 @@ alias genpass="openssl rand -base64 32"         # Gera uma senha aleatória segu
 alias envls="env | sort"                        # Lista todas as variáveis de ambiente ordenadas
 alias envg="env | grep"                         # Filtra variáveis de ambiente (ex: envg PATH)
 alias dotenv="export \$(cat .env | grep -v '^#' | xargs)" # Carrega variáveis do arquivo .env atual
+
+# --- Configurações Personalizadas ---
+alias zlocal="nano ~/.zshrc.local"              # Edita o arquivo de configurações personalizadas
+
+
+# 6. USER CUSTOM CONFIGURATIONS
+# Load custom configurations from ~/.zshrc.local if it exists
+# Use this file to add your own aliases, functions, and variables.
+# This file is never overwritten by SetupVibe updates.
+[ -f "$HOME/.zshrc.local" ] && source "$HOME/.zshrc.local"

conf/zshrc-macos.zsh

@@ -66,8 +66,8 @@ alias spup="uv tool upgrade specify-cli"        # Atualiza o Spec-Kit para a ver
 
 # --- Shell ---
 alias zconfig="nano ~/.zshrc"                   # Edita o arquivo de configuração do ZSH
-alias reload="source ~/.zshrc"                  # Recarrega as configurações do ZSH sem reiniciar o terminal
-alias path='echo -e ${PATH//:/\\n}'             # Exibe cada entrada do PATH em uma linha separada
+alias reload="source ~/.zshrc && source ~/.zshrc.local"  # Recarrega as configurações do ZSH e as personalizadas locais sem reiniciar o terminal
+alias path='echo -e ${PATH//:/\\n}'                      # Exibe cada entrada do PATH em uma linha separada
 alias h="history | grep"                        # Busca no histórico de comandos (ex: h docker)
 alias cls="clear"                               # Limpa o terminal
 alias please="sudo"                             # Atalho amigável para sudo
@@ -362,3 +362,13 @@ alias genpass="openssl rand -base64 32"         # Gera uma senha aleatória segu
 alias envls="env | sort"                        # Lista todas as variáveis de ambiente ordenadas
 alias envg="env | grep"                         # Filtra variáveis de ambiente (ex: envg PATH)
 alias dotenv="export \$(cat .env | grep -v '^#' | xargs)" # Carrega variáveis do arquivo .env atual
+
+# --- Configurações Personalizadas ---
+alias zlocal="nano ~/.zshrc.local"              # Edita o arquivo de configurações personalizadas
+
+
+# 6. USER CUSTOM CONFIGURATIONS
+# Load custom configurations from ~/.zshrc.local if it exists
+# Use this file to add your own aliases, functions, and variables.
+# This file is never overwritten by SetupVibe updates.
+[ -f "$HOME/.zshrc.local" ] && source "$HOME/.zshrc.local"

conf/zshrc-server.zsh

@@ -45,8 +45,8 @@ alias skc="npx skills check"                    # Verifica atualizações dispon
 
 # --- Shell ---
 alias zconfig="nano ~/.zshrc"                   # Edita o arquivo de configuração do ZSH
-alias reload="source ~/.zshrc"                  # Recarrega as configurações do ZSH sem reiniciar o terminal
-alias path='echo -e ${PATH//:/\\n}'             # Exibe cada entrada do PATH em uma linha separada
+alias reload="source ~/.zshrc && source ~/.zshrc.local"  # Recarrega as configurações do ZSH e as personalizadas locais sem reiniciar o terminal
+alias path='echo -e ${PATH//:/\\n}'                      # Exibe cada entrada do PATH em uma linha separada
 alias h="history | grep"                        # Busca no histórico de comandos (ex: h docker)
 alias cls="clear"                               # Limpa o terminal
 alias please="sudo"                             # Atalho amigável para sudo
@@ -279,6 +279,16 @@ alias envls="env | sort"                        # Lista todas as variáveis de a
 alias envg="env | grep"                         # Filtra variáveis de ambiente (ex: envg PATH)
 alias dotenv="export \$(cat .env | grep -v '^#' | xargs)" # Carrega variáveis do arquivo .env atual
 
+# --- Configurações Personalizadas ---
+alias zlocal="nano ~/.zshrc.local"              # Edita o arquivo de configurações personalizadas
+
+
+# 5. USER CUSTOM CONFIGURATIONS
+# Load custom configurations from ~/.zshrc.local if it exists
+# Use this file to add your own aliases, functions, and variables.
+# This file is never overwritten by SetupVibe updates.
+[ -f "$HOME/.zshrc.local" ] && source "$HOME/.zshrc.local"
+
 # --- Python / uv ---
 alias py="python3"                              # Atalho para Python 3
 alias pyv="python3 --version"                   # Exibe a versão ativa do Python

desktop.sh

@@ -1054,6 +1054,11 @@ step_11() {
 
         # macOS ZSHRC
         safe_download https://raw.githubusercontent.com/promovaweb/setupvibe/main/conf/zshrc-macos.zsh "$REAL_HOME/.zshrc"
+
+        # Create ~/.zshrc.local for user customizations if it doesn't exist
+        if [ ! -f "$REAL_HOME/.zshrc.local" ]; then
+            user_do touch "$REAL_HOME/.zshrc.local"
+        fi
     else
         sys_do apt-get install -y zsh
 
@@ -1088,6 +1093,11 @@ step_11() {
 
         # Linux ZSHRC
         safe_download https://raw.githubusercontent.com/promovaweb/setupvibe/main/conf/zshrc-linux.zsh "$REAL_HOME/.zshrc"
+
+        # Create ~/.zshrc.local for user customizations if it doesn't exist
+        if [ ! -f "$REAL_HOME/.zshrc.local" ]; then
+            user_do touch "$REAL_HOME/.zshrc.local"
+        fi
         sys_do chown $REAL_USER:$REAL_USER "$REAL_HOME/.zshrc"
 
         # Ensure ~/.local/bin is in .bashrc so tools like uv are accessible in bash sessions

docs/desktop/en/README.md

@@ -139,6 +139,7 @@ Installed via Homebrew on both platforms.
 - Downloads the appropriate `.zshrc`:
   - macOS → [`conf/zshrc-macos.zsh`](../../../conf/zshrc-macos.zsh)
   - Linux → [`conf/zshrc-linux.zsh`](../../../conf/zshrc-linux.zsh)
+- Creates `~/.zshrc.local` for your own aliases and settings (never overwritten on updates)
 
 ### Step 12 — Tmux & Plugins
 
@@ -187,8 +188,9 @@ Each platform gets a dedicated `.zshrc`:
 
 | Alias      | Command                                                                               |
 | ---------- | ------------------------------------------------------------------------------------- |
-| `reload`   | `source ~/.zshrc`                                                                     |
-| `zconfig`  | `nano ~/.zshrc`                                                                       |
+| `reload`     | `source ~/.zshrc && source ~/.zshrc.local`                                              |
+| `zconfig`    | `nano ~/.zshrc`                                                                         |
+| `zlocal`     | `nano ~/.zshrc.local`                                                                   |
 | `update`   | `brew update && brew upgrade` (macOS) / `sudo apt update && sudo apt upgrade` (Linux) |
 | `brewup`   | `brew update && brew upgrade && brew cleanup`                                         |
 | `ge`       | `gemini --approval-mode=yolo`                                                         |

docs/desktop/es/README.md

@@ -138,6 +138,7 @@ Instaladas mediante Homebrew en ambas plataformas.
 - Descarga el `.zshrc` adecuado:
   - macOS → [`conf/zshrc-macos.zsh`](../../../conf/zshrc-macos.zsh)
   - Linux → [`conf/zshrc-linux.zsh`](../../../conf/zshrc-linux.zsh)
+- Crea `~/.zshrc.local` para tus propios aliases y configuraciones (nunca sobrescrito en actualizaciones)
 
 ### Paso 12 — Tmux y Plugins
 
@@ -186,8 +187,9 @@ Cada plataforma recibe un `.zshrc` dedicado:
 
 | Alias      | Comando                                                                                   |
 | ---------- | ----------------------------------------------------------------------------------------- |
-| `reload`   | `source ~/.zshrc`                                                                         |
-| `zconfig`  | `nano ~/.zshrc`                                                                           |
+| `reload`     | `source ~/.zshrc && source ~/.zshrc.local`                                                |
+| `zconfig`    | `nano ~/.zshrc`                                                                           |
+| `zlocal`     | `nano ~/.zshrc.local`                                                                     |
 | `update`   | `brew update && brew upgrade` (macOS) / `sudo apt update && sudo apt upgrade` (Linux)      |
 | `brewup`   | `brew update && brew upgrade && brew cleanup`                                             |
 | `ge`       | `gemini --approval-mode=yolo`                                                         |

docs/desktop/fr/README.md

@@ -138,6 +138,7 @@ Installés via Homebrew sur les deux plateformes.
 - Télécharge le `.zshrc` approprié :
   - macOS → [`conf/zshrc-macos.zsh`](../../../conf/zshrc-macos.zsh)
   - Linux → [`conf/zshrc-linux.zsh`](../../../conf/zshrc-linux.zsh)
+- Crée `~/.zshrc.local` pour vos propres alias et paramètres (jamais écrasé lors des mises à jour)
 
 ### Étape 12 — Tmux et Plugins
 
@@ -186,8 +187,9 @@ Chaque plateforme reçoit un `.zshrc` dédié :
 
 | Alias      | Commande                                                                                 |
 | ---------- | ---------------------------------------------------------------------------------------- |
-| `reload`   | `source ~/.zshrc`                                                                        |
-| `zconfig`  | `nano ~/.zshrc`                                                                          |
+| `reload`     | `source ~/.zshrc && source ~/.zshrc.local`                                                 |
+| `zconfig`    | `nano ~/.zshrc`                                                                          |
+| `zlocal`     | `nano ~/.zshrc.local`                                                                    |
 | `update`   | `brew update && brew upgrade` (macOS) / `sudo apt update && sudo apt upgrade` (Linux)      |
 | `brewup`   | `brew update && brew upgrade && brew cleanup`                                            |
 | `ge`       | `gemini --approval-mode=yolo`                                                         |

docs/desktop/pt-br/README.md

@@ -139,6 +139,7 @@ Instaladas via Homebrew em ambas as plataformas.
 - Baixa o `.zshrc` adequado:
   - macOS → [`conf/zshrc-macos.zsh`](../../../conf/zshrc-macos.zsh)
   - Linux → [`conf/zshrc-linux.zsh`](../../../conf/zshrc-linux.zsh)
+- Cria `~/.zshrc.local` para seus próprios aliases e configurações (nunca sobrescrito em atualizações)
 
 ### Etapa 12 — Tmux e Plugins
 
@@ -187,8 +188,9 @@ Cada plataforma recebe um `.zshrc` dedicado:
 
 | Alias      | Comando                                                                                    |
 | ---------- | ------------------------------------------------------------------------------------------ |
-| `reload`   | `source ~/.zshrc`                                                                          |
-| `zconfig`  | `nano ~/.zshrc`                                                                            |
+| `reload`     | `source ~/.zshrc && source ~/.zshrc.local`                                                 |
+| `zconfig`    | `nano ~/.zshrc`                                                                            |
+| `zlocal`     | `nano ~/.zshrc.local`                                                                      |
 | `update`   | `brew update && brew upgrade` (macOS) / `sudo apt update && sudo apt upgrade` (Linux)      |
 | `brewup`   | `brew update && brew upgrade && brew cleanup`                                              |
 | `ge`       | `gemini --approval-mode=yolo`                                                                 |

docs/en/ALIAS.md

@@ -82,10 +82,16 @@ This is the exhaustive list of all aliases configured by SetupVibe on all platfo
 
 - **`reload`**
   - Availability: 🌐 Both
-  - Command: `source ~/.zshrc`
-  - Description: Reloads ZSH settings without restarting the terminal.
+  - Command: `source ~/.zshrc && source ~/.zshrc.local`
+  - Description: Reloads ZSH settings and local customizations without restarting the terminal.
   - Example: `reload`
 
+- **`zlocal`**
+  - Availability: 🌐 Both
+  - Command: `nano ~/.zshrc.local`
+  - Description: Edits the local ZSH custom configuration file (never overwritten by updates).
+  - Example: `zlocal`
+
 - **`path`**
   - Availability: 🌐 Both
   - Command: `echo -e ${PATH//:/\\n}`

docs/es/ALIAS.md

@@ -82,10 +82,16 @@ Esta é a lista exaustiva de todos os aliases configurados pelo SetupVibe em tod
 
 - **`reload`**
   - Disponibilidad: 🌐 Ambos
-  - Comando: `source ~/.zshrc`
-  - Descripción: Recarga la configuración de ZSH sin reiniciar la terminal.
+  - Comando: `source ~/.zshrc && source ~/.zshrc.local`
+  - Descripción: Recarga la configuración de ZSH y las personalizaciones locales sin reiniciar la terminal.
   - Ejemplo: `reload`
 
+- **`zlocal`**
+  - Disponibilidad: 🌐 Ambos
+  - Comando: `nano ~/.zshrc.local`
+  - Descripción: Edita el archivo de configuración personalizada de ZSH (nunca sobrescrito en actualizaciones).
+  - Ejemplo: `zlocal`
+
 - **`path`**
   - Disponibilidad: 🌐 Ambos
   - Comando: `echo -e ${PATH//:/\\n}`

docs/fr/ALIAS.md

@@ -82,10 +82,16 @@ Voici la liste exhaustive de todos os aliases configurados por SetupVibe sur tou
 
 - **`reload`**
   - Disponibilité : 🌐 Les deux
-  - Commande : `source ~/.zshrc`
-  - Description : Recharge les paramètres ZSH sans redémarrer le terminal.
+  - Commande : `source ~/.zshrc && source ~/.zshrc.local`
+  - Description : Recharge les paramètres ZSH et les personnalisations locales sans redémarrer le terminal.
   - Exemple : `reload`
 
+- **`zlocal`**
+  - Disponibilité : 🌐 Les deux
+  - Commande : `nano ~/.zshrc.local`
+  - Description : Modifie le fichier de configuration ZSH personnalisé local (jamais écrasé lors des mises à jour).
+  - Exemple : `zlocal`
+
 - **`path`**
   - Disponibilité : 🌐 Les deux
   - Commande : `echo -e ${PATH//:/\\n}`

docs/pt-br/ALIAS.md

@@ -82,10 +82,16 @@ Esta é a lista exaustiva de todos os aliases configurados pelo SetupVibe em tod
 
 - **`reload`**
   - Disponibilidade: 🌐 Ambos
-  - Comando: `source ~/.zshrc`
-  - Descrição: Recarrega as configurações do ZSH sem reiniciar o terminal.
+  - Comando: `source ~/.zshrc && source ~/.zshrc.local`
+  - Descrição: Recarrega as configurações do ZSH e as personalizações locais sem reiniciar o terminal.
   - Exemplo: `reload`
 
+- **`zlocal`**
+  - Disponibilidade: 🌐 Ambos
+  - Comando: `nano ~/.zshrc.local`
+  - Descrição: Edita o arquivo de configurações personalizadas do ZSH (nunca sobrescrito em atualizações).
+  - Exemplo: `zlocal`
+
 - **`path`**
   - Disponibilidade: 🌐 Ambos
   - Comando: `echo -e ${PATH//:/\\n}`

docs/server/en/README.md

@@ -93,14 +93,16 @@ APT packages:
 - Clones `zsh-autosuggestions` and `zsh-syntax-highlighting`
 - Installs Starship prompt to `~/.local/bin` and applies the **Gruvbox Rainbow** preset
 - Downloads [`conf/zshrc-server.zsh`](../../../conf/zshrc-server.zsh) to `~/.zshrc`
+- Creates `~/.zshrc.local` for your own aliases and settings (never overwritten on updates)
 - Sets ZSH as the default shell via `chsh`
 
 #### Shell Aliases
 
 | Alias          | Command                               |
 | -------------- | ------------------------------------- |
-| `reload`       | `source ~/.zshrc`                     |
-| `zconfig`      | `nano ~/.zshrc`                       |
+| `reload`       | `source ~/.zshrc && source ~/.zshrc.local` |
+| `zconfig`      | `nano ~/.zshrc`                           |
+| `zlocal`       | `nano ~/.zshrc.local`                     |
 | `update`       | `sudo apt update && sudo apt upgrade` |
 | `ge`           | `gemini --approval-mode=yolo`         |
 | `cc`           | `claude --permission-mode=auto --dangerously-skip-permissions` |

docs/server/es/README.md

@@ -93,14 +93,16 @@ Paquetes APT:
 - Clona `zsh-autosuggestions` y `zsh-syntax-highlighting`
 - Instala el prompt Starship en `~/.local/bin` y aplica el preset **Gruvbox Rainbow**
 - Descarga [`conf/zshrc-server.zsh`](../../../conf/zshrc-server.zsh) a `~/.zshrc`
+- Crea `~/.zshrc.local` para tus propios aliases y configuraciones (nunca sobrescrito en actualizaciones)
 - Establece ZSH como shell por defecto mediante `chsh`
 
 #### Aliases del Shell
 
 | Alias          | Comando                               |
 | -------------- | ------------------------------------- |
-| `reload`       | `source ~/.zshrc`                     |
-| `zconfig`      | `nano ~/.zshrc`                       |
+| `reload`       | `source ~/.zshrc && source ~/.zshrc.local` |
+| `zconfig`      | `nano ~/.zshrc`                           |
+| `zlocal`       | `nano ~/.zshrc.local`                     |
 | `update`       | `sudo apt update && sudo apt upgrade` |
 | `ge`           | `gemini --approval-mode=yolo`                                  |
 | `cc`           | `claude --permission-mode=auto --dangerously-skip-permissions` |

docs/server/fr/README.md

@@ -93,14 +93,16 @@ Paquets APT :
 - Clone `zsh-autosuggestions` et `zsh-syntax-highlighting`
 - Installe le prompt Starship dans `~/.local/bin` et applique le preset **Gruvbox Rainbow**
 - Télécharge [`conf/zshrc-server.zsh`](../../../conf/zshrc-server.zsh) vers `~/.zshrc`
+- Crée `~/.zshrc.local` pour vos propres alias et paramètres (jamais écrasé lors des mises à jour)
 - Définit ZSH comme shell par défaut via `chsh`
 
 #### Alias du Shell
 
 | Alias          | Commande                              |
 | -------------- | ------------------------------------- |
-| `reload`       | `source ~/.zshrc`                     |
-| `zconfig`      | `nano ~/.zshrc`                       |
+| `reload`       | `source ~/.zshrc && source ~/.zshrc.local` |
+| `zconfig`      | `nano ~/.zshrc`                           |
+| `zlocal`       | `nano ~/.zshrc.local`                     |
 | `update`       | `sudo apt update && sudo apt upgrade` |
 | `ge`           | `gemini --approval-mode=yolo`                                  |
 | `cc`           | `claude --permission-mode=auto --dangerously-skip-permissions` |

docs/server/pt-br/README.md

@@ -93,14 +93,16 @@ Pacotes APT:
 - Clona `zsh-autosuggestions` e `zsh-syntax-highlighting`
 - Instala o prompt Starship em `~/.local/bin` e aplica o preset **Gruvbox Rainbow**
 - Baixa [`conf/zshrc-server.zsh`](../../../conf/zshrc-server.zsh) para `~/.zshrc`
+- Cria `~/.zshrc.local` para seus próprios aliases e configurações (nunca sobrescrito em atualizações)
 - Define o ZSH como shell padrão via `chsh`
 
 #### Aliases do Shell
 
 | Alias          | Comando                               |
 | -------------- | ------------------------------------- |
-| `reload`       | `source ~/.zshrc`                     |
-| `zconfig`      | `nano ~/.zshrc`                       |
+| `reload`       | `source ~/.zshrc && source ~/.zshrc.local` |
+| `zconfig`      | `nano ~/.zshrc`                           |
+| `zlocal`       | `nano ~/.zshrc.local`                     |
 | `update`       | `sudo apt update && sudo apt upgrade` |
 | `ge`           | `gemini --approval-mode=yolo`                                  |
 | `cc`           | `claude --permission-mode=auto --dangerously-skip-permissions` |

server.sh

@@ -599,6 +599,11 @@ step_5() {
 
     # Server ZSHRC
     safe_download https://raw.githubusercontent.com/promovaweb/setupvibe/main/conf/zshrc-server.zsh "$REAL_HOME/.zshrc"
+
+    # Create ~/.zshrc.local for user customizations if it doesn't exist
+    if [ ! -f "$REAL_HOME/.zshrc.local" ]; then
+        user_do touch "$REAL_HOME/.zshrc.local"
+    fi
     sys_do chown $REAL_USER:$REAL_USER "$REAL_HOME/.zshrc"
 
     # Ensure ~/.local/bin is in .bashrc so tools like uv are accessible in bash sessions