Stow based dotfiles structure

README.md

@@ -1 +1,78 @@
 # dotfiles
+
+This repository contains my personal dotfiles, managed using [GNU Stow](https://www.gnu.org/software/stow/). 
+
+Instead of a custom installation script, configurations are organized into logical "packages". Using `stow` ensures that all configuration files are cleanly symlinked into your home directory, mirroring the structure inside the package folder.
+
+## Requirements
+
+- [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 a specific package (e.g., `nvim`), navigate to the root of this repository and run:
+
+```bash
+stow nvim
+```
+
+To install all standard packages at once, run:
+
+```bash
+stow bash zsh nvim starship tmux
+```
+
+This will automatically create the necessary symlinks in your `$HOME` directory pointing to the files in this repository.
+
+### Removing a Package
+
+If you want to remove the symlinks for a specific package, use the `-D` flag:
+
+```bash
+stow -D nvim
+```
+
+## Directory Structure
+
+To keep things modular and easy to manage, each folder acts as a "package" that represents an application or environment. The folder structure *inside* the package strictly mirrors its target destination relative to the home (`~/`) directory.
+
+```text
+.
+├── bash/
+│   └── .bashrc                  # Symlinked to ~/.bashrc
+├── nvim/
+│   └── .config/
+│       └── nvim/                # Symlinked to ~/.config/nvim/
+├── starship/
+│   └── .config/
+│       └── starship.toml        # Symlinked to ~/.config/starship.toml
+├── tmux/
+│   ├── .tmux.conf               # Symlinked to ~/.tmux.conf
+│   └── .tmux.conf.local         # Symlinked to ~/.tmux.conf.local
+└── zsh/
+    └── .zshrc                   # Symlinked to ~/.zshrc
+```
+
+### Adding New Configurations
+
+When you want to add a new tool:
+1. Create a new directory for it (e.g., `wezterm`).
+2. Replicate the target directory structure inside this new folder (e.g., `wezterm/.config/wezterm/wezterm.lua`).
+3. Run `stow wezterm` from the root of this repository.