From 1d76b91434408e7cf359c3e81a68c927587385b5 Mon Sep 17 00:00:00 2001
From: rootiest <chris@rootiest.com>
Date: Mon, 27 Apr 2026 14:17:43 -0400
Subject: [PATCH] docs: implement initial documentation

---
 README.md | 73 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 73 insertions(+)
 create mode 100644 README.md

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..778c28b
--- /dev/null
+++ b/README.md
@@ -0,0 +1,73 @@
+# rootiest dotfiles
+
+Personal system configuration for Arch-based Linux, managed with [chezmoi](https://chezmoi.io/).
+
+## Overview
+
+This repository is the single source of truth for my system configuration. Rather than tracking config files directly, it uses chezmoi's **externals** feature to declaratively reference each config as its own versioned git repository. Chezmoi handles cloning and updating them automatically.
+
+| Config | Repository | Destination |
+|--------|-----------|-------------|
+| [Fish Shell](https://git.rootiest.dev/rootiest/fish-config) | `fish-config` | `~/.config/fish` |
+| [Kitty Terminal](https://git.rootiest.dev/rootiest/kitty-conf) | `kitty-conf` | `~/.config/kitty` |
+| [Neovim](https://git.rootiest.dev/rootiest/neovim-config) | `neovim-config` | `~/.config/nvim` |
+
+## Highlights
+
+- **Fish Shell** — Catppuccin Mocha theme, Starship prompt, Fisher plugins, smart CLI wrappers, and extensive abbreviations for keyboard-driven workflows
+- **Kitty Terminal** — Deeply customized GPU-accelerated terminal with scripted layouts, splits, and Neovim integration
+- **Neovim** — Modular, high-performance config using native `vim.pack` for plugin management, blink.cmp completion, and GitHub Copilot LSP
+
+## Prerequisites
+
+- Arch-based Linux (tested on [CachyOS](https://cachyos.org/))
+- [`chezmoi`](https://archlinux.org/packages/extra/x86_64/chezmoi/) — `sudo pacman -S chezmoi`
+- [`git`](https://archlinux.org/packages/extra/x86_64/git/) — `sudo pacman -S git`
+
+## Installation
+
+### Fresh setup
+
+```fish
+# 1. Clone this repo and initialize chezmoi against it
+chezmoi init --source=~/projects/dotfiles
+
+# 2. Apply — chezmoi will clone each external config repo into place
+chezmoi apply -v
+```
+
+### Or initialize directly from this repository
+
+```fish
+chezmoi init https://git.rootiest.dev/rootiest/dotfiles.git
+chezmoi apply -v
+```
+
+## Keeping up to date
+
+Each config repo is maintained independently. To pull the latest changes from all of them at once:
+
+```fish
+chezmoi update -v
+```
+
+This runs `git pull` in each external repo and reapplies any changes.
+
+## Repository structure
+
+```
+dotfiles/
+├── .chezmoiexternal.toml   # Declares the three external config repos
+├── .chezmoiignore          # Excludes repo-only files from the home directory
+└── README.md
+```
+
+## Related repositories
+
+- [fish-config](https://git.rootiest.dev/rootiest/fish-config) — Fish shell configuration
+- [kitty-conf](https://git.rootiest.dev/rootiest/kitty-conf) — Kitty terminal configuration
+- [neovim-config](https://git.rootiest.dev/rootiest/neovim-config) — Neovim configuration
+
+## License
+
+Each configuration repository carries its own license. See the individual repos for details.