docs: restore README.md

README.md

@@ -0,0 +1,82 @@
+# dotfiles
+
+This repository contains my personal dotfiles, managed using [GNU Stow](https://www.gnu.org/software/stow/). 
+
+Using `stow` ensures that all configuration files are cleanly symlinked into your home directory, mirroring the structure of this repository.
+
+## Requirements
+
+A script is provided to help install the core dependencies across macOS and common Linux distributions (Ubuntu/Debian, Arch, Fedora).
+
+To run the installation script:
+```bash
+./scripts/install_dependencies.sh
+```
+
+Alternatively, you can manually install the required tool:
+
+- [GNU Stow](https://www.gnu.org/software/stow/)
+
+To install Stow on macOS, use [Homebrew](https://brew.sh/):
+```bash
+brew install stow
+```
+
+To install Stow on Linux, use your distribution's package manager:
+
+**Ubuntu / Debian**
+```bash
+sudo apt install stow
+```
+
+**Arch Linux**
+```bash
+sudo pacman -S stow
+```
+
+## Installation
+
+To install all configurations at once, navigate to the root of this repository and run:
+
+```bash
+stow .
+```
+
+This will automatically create the necessary symlinks in your `$HOME` directory pointing to the files in this repository.
+
+### Removing Configurations
+
+If you want to remove the symlinks created by Stow, use the `-D` flag:
+
+```bash
+stow -D .
+```
+
+## Directory Structure
+
+The folder structure directly mirrors its target destination relative to the home (`~/`) directory.
+
+```text
+.
+├── .bashrc                      # Symlinked to ~/.bashrc
+├── .config/                     # Symlinked to ~/.config/
+│   ├── alacritty/
+│   ├── kitty/
+│   ├── nvim/
+│   ├── starship.toml
+│   └── ...
+├── .fonts/                      # Symlinked to ~/.fonts/
+├── .tmux.conf                   # Symlinked to ~/.tmux.conf
+├── .tmux.conf.local             # Symlinked to ~/.tmux.conf.local
+├── .vimrc                       # Symlinked to ~/.vimrc
+├── .zshrc                       # Symlinked to ~/.zshrc
+├── scripts/                     # Symlinked to ~/scripts/
+├── shell/                       # Symlinked to ~/shell/
+└── wezterm.lua                  # Symlinked to ~/wezterm.lua
+```
+
+### Adding New Configurations
+
+When you want to add a new tool:
+1. Replicate the target directory structure inside this repository (e.g., `.config/new_tool/config.toml`).
+2. Run `stow .` from the root of this repository to link the new files.