diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml
new file mode 100644
index 0000000..eecbd24
--- /dev/null
+++ b/.github/workflows/docs.yml
@@ -0,0 +1,51 @@
+name: docs
+
+on:
+  push:
+    branches:
+      - main
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+# Allow one concurrent deployment; cancel in-progress runs for the same ref.
+concurrency:
+  group: pages
+  cancel-in-progress: true
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.x"
+
+      - name: Install MkDocs Material
+        run: pip install mkdocs-material
+
+      - name: Build site
+        run: mkdocs build --strict
+
+      - name: Upload Pages artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: site
+
+  deploy:
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4
diff --git a/.gitignore b/.gitignore
index d576a96..771bc0f 100644
--- a/.gitignore
+++ b/.gitignore
@@ -32,6 +32,9 @@ temp/
 # Logs
 *.log
 
+# MkDocs build output
+site/
+
 # Local machine files
 *.local
 *.local.*
diff --git a/mkdocs.yml b/mkdocs.yml
new file mode 100644
index 0000000..391946b
--- /dev/null
+++ b/mkdocs.yml
@@ -0,0 +1,61 @@
+site_name: fnayou/dotfiles
+site_description: Personal dotfiles, terminal workflow, shell configuration and development environment.
+site_url: https://fnayou.github.io/dotfiles/
+repo_url: https://github.com/fnayou/dotfiles
+repo_name: fnayou/dotfiles
+
+docs_dir: website
+
+theme:
+  name: material
+  palette:
+    scheme: slate
+    primary: blue
+    accent: blue
+  features:
+    - navigation.sections
+    - navigation.expand
+    - navigation.top
+    - search.suggest
+    - search.highlight
+    - content.code.copy
+    - content.tabs.link
+
+extra_css:
+  - assets/stylesheets/catppuccin-macchiato.css
+
+markdown_extensions:
+  - admonition
+  - pymdownx.details
+  - pymdownx.superfences
+  - pymdownx.tabbed:
+      alternate_style: true
+
+nav:
+  - Home: index.md
+  - Getting Started:
+      - Overview: getting-started.md
+      - Installation: installation.md
+      - Philosophy: philosophy.md
+  - Features:
+      - Overview: features/index.md
+      - Shell (Zsh): features/shell.md
+      - Git: features/git.md
+      - Terminal: features/terminal.md
+      - Editor (Neovim): features/editor.md
+      - Packages: features/packages.md
+      - Scripts: features/scripts.md
+  - Usage:
+      - Overview: usage/index.md
+      - Daily Workflow: usage/daily-workflow.md
+      - Aliases: usage/aliases.md
+      - Functions: usage/functions.md
+      - Taskfile: usage/taskfile.md
+  - Reference:
+      - Overview: reference/index.md
+      - Repository Structure: reference/repository-structure.md
+      - GNU Stow Workflow: reference/stow.md
+      - Shell Dependencies: reference/shell-dependencies.md
+      - Supported Systems: reference/supported-systems.md
+      - Troubleshooting: reference/troubleshooting.md
+  - Screenshots: screenshots.md
diff --git a/website/assets/images/.gitkeep b/website/assets/images/.gitkeep
new file mode 100644
index 0000000..e69de29
diff --git a/website/assets/images/bat-output.png b/website/assets/images/bat-output.png
new file mode 100644
index 0000000..57ae227
Binary files /dev/null and b/website/assets/images/bat-output.png differ
diff --git a/website/assets/images/claude-statusline.png b/website/assets/images/claude-statusline.png
new file mode 100644
index 0000000..871b21a
Binary files /dev/null and b/website/assets/images/claude-statusline.png differ
diff --git a/website/assets/images/eza-listing.png b/website/assets/images/eza-listing.png
new file mode 100644
index 0000000..5c3a1d0
Binary files /dev/null and b/website/assets/images/eza-listing.png differ
diff --git a/website/assets/images/herdr-session.png b/website/assets/images/herdr-session.png
new file mode 100644
index 0000000..ecf0d1f
Binary files /dev/null and b/website/assets/images/herdr-session.png differ
diff --git a/website/assets/images/nvim-editor.png b/website/assets/images/nvim-editor.png
new file mode 100644
index 0000000..e826855
Binary files /dev/null and b/website/assets/images/nvim-editor.png differ
diff --git a/website/assets/images/repo-tree.png b/website/assets/images/repo-tree.png
new file mode 100644
index 0000000..ab4c0fa
Binary files /dev/null and b/website/assets/images/repo-tree.png differ
diff --git a/website/assets/images/stow-dryrun.png b/website/assets/images/stow-dryrun.png
new file mode 100644
index 0000000..e924a05
Binary files /dev/null and b/website/assets/images/stow-dryrun.png differ
diff --git a/website/assets/images/task-list.png b/website/assets/images/task-list.png
new file mode 100644
index 0000000..4f8498c
Binary files /dev/null and b/website/assets/images/task-list.png differ
diff --git a/website/assets/images/terminal-prompt.png b/website/assets/images/terminal-prompt.png
new file mode 100644
index 0000000..b79e052
Binary files /dev/null and b/website/assets/images/terminal-prompt.png differ
diff --git a/website/assets/stylesheets/catppuccin-macchiato.css b/website/assets/stylesheets/catppuccin-macchiato.css
new file mode 100644
index 0000000..307546a
--- /dev/null
+++ b/website/assets/stylesheets/catppuccin-macchiato.css
@@ -0,0 +1,52 @@
+/*
+ * Catppuccin Macchiato (Blue accent) — Material for MkDocs override.
+ * First-pass palette. Applies on the dark (slate) scheme.
+ * Palette reference: https://github.com/catppuccin/catppuccin
+ */
+
+[data-md-color-scheme="slate"] {
+  /* Base surfaces */
+  --md-default-bg-color:            #24273a; /* Base */
+  --md-default-fg-color:            #cad3f5; /* Text */
+  --md-default-fg-color--light:     #b8c0e0; /* Subtext1 */
+  --md-default-fg-color--lighter:   #a5adcb; /* Subtext0 */
+  --md-default-fg-color--lightest:  #6e738d; /* Overlay0 */
+
+  /* Primary / accent — Blue */
+  --md-primary-fg-color:            #8aadf4; /* Blue */
+  --md-primary-fg-color--light:     #91d7e3; /* Sky */
+  --md-primary-fg-color--dark:      #7dc4e4; /* Sapphire */
+  --md-primary-bg-color:            #1e2030; /* Mantle (text on primary) */
+  --md-primary-bg-color--light:     #cad3f5;
+
+  --md-accent-fg-color:             #8aadf4; /* Blue */
+  --md-accent-fg-color--transparent: rgba(138, 173, 244, 0.1);
+  --md-accent-bg-color:             #1e2030;
+
+  /* Code surfaces */
+  --md-code-bg-color:               #1e2030; /* Mantle */
+  --md-code-fg-color:               #cad3f5; /* Text */
+
+  /* Links */
+  --md-typeset-a-color:             #8aadf4; /* Blue */
+
+  /* Footer / header use Mantle for contrast against Base */
+  --md-footer-bg-color:             #1e2030;
+  --md-footer-bg-color--dark:       #181926; /* Crust */
+}
+
+/* Header bar — Mantle instead of full Blue for a calmer look */
+[data-md-color-scheme="slate"] .md-header {
+  background-color: #1e2030;
+  color: #cad3f5;
+}
+
+[data-md-color-scheme="slate"] .md-tabs {
+  background-color: #181926; /* Crust */
+}
+
+/* Inline code chips */
+[data-md-color-scheme="slate"] .md-typeset code {
+  background-color: #363a4f; /* Surface0 */
+  color: #cad3f5;
+}
diff --git a/website/features/editor.md b/website/features/editor.md
new file mode 100644
index 0000000..463b697
--- /dev/null
+++ b/website/features/editor.md
@@ -0,0 +1,58 @@
+# Editor (Neovim)
+
+The `stow/common/nvim/` package provides a [kickstart.nvim](https://github.com/nvim-lua/kickstart.nvim)-based
+Neovim configuration, themed Catppuccin Macchiato (blue accent `#8aadf4`) to match the rest of the
+terminal. It's meant to replace plain `vim` for quick local edits and server maintenance, while still
+being a full, learnable setup.
+
+Curated from `stow/common/nvim/README.md`. There is no separate setup guide for this package yet.
+
+![Neovim editing a file with the Catppuccin Macchiato colorscheme](../assets/images/nvim-editor.png)
+*Neovim editing inside the dotfiles repository.*
+
+## What it configures
+
+- Stock kickstart `init.lua`, kept close to upstream (LSP servers + treesitter languages edited).
+- Plugins managed by [lazy.nvim](https://github.com/folke/lazy.nvim), pinned via `lazy-lock.json`.
+- Feature files under `lua/custom/plugins/`: Catppuccin colorscheme, snacks picker, neo-tree file
+  explorer, flash jump motions, indent guides, and filetype scoping.
+
+Target path is `~/.config/nvim` (XDG), identical on macOS and Arch — only the system dependencies
+differ per platform.
+
+## Dependencies
+
+LSP servers are installed **inside** Neovim by [Mason](https://github.com/mason-org/mason.nvim)
+(`:Mason`), but they need runtimes and a few CLI tools on the system first — `neovim`, `ripgrep`,
+`fd`, `node`, `python` + `pipx`, a C compiler, and the `tree-sitter` CLI.
+
+Print the install commands (nothing installs automatically):
+
+```bash
+task deps:brew    # macOS
+task deps:arch    # Arch
+```
+
+!!! info "tree-sitter CLI"
+    nvim-treesitter builds parsers by shelling out to the `tree-sitter` binary. On macOS, Homebrew's
+    `tree-sitter` formula ships the library only, so install the CLI via `npm install -g tree-sitter-cli`.
+    Without it, parser builds fail with `ENOENT ... (cmd): 'tree-sitter'`. See the package README for
+    the full rationale.
+
+## Install
+
+This package uses the standard Stow workflow (no `--no-folding` needed):
+
+```bash
+stow --dir=stow/common --target="$HOME" --simulate nvim
+```
+
+⚠️  MANUAL STEP — review dry-run output before running
+
+```bash
+stow --dir=stow/common --target="$HOME" nvim
+```
+
+## Related
+
+- [Shell Dependencies](../reference/shell-dependencies.md) · [GNU Stow Workflow](../reference/stow.md)
diff --git a/website/features/git.md b/website/features/git.md
new file mode 100644
index 0000000..ac19551
--- /dev/null
+++ b/website/features/git.md
@@ -0,0 +1,87 @@
+# Git
+
+The `stow/common/git/` package provides a portable Git configuration — settings, aliases, and a
+global ignore file — without touching your identity or any secrets.
+
+This page is curated from the repository's `docs/guides/git-setup.md`.
+
+## What it manages
+
+Three files, stowed into `~/.config/git/`:
+
+| File | Purpose |
+|---|---|
+| `config-common` | Portable settings — editor, colors, pull strategy, merge conflict style, diff options |
+| `aliases` | Git aliases — shorthand for common operations |
+| `ignore` | Global ignore patterns — OS artifacts, editor files, logs |
+
+!!! info "Your identity stays yours"
+    This package **never** manages `~/.gitconfig`. `user.name`, `user.email`, signing keys,
+    credentials, and any `[includeIf]` work config stay in your own `~/.gitconfig`. The managed files
+    are wired in via `[include]` entries — your existing config is preserved.
+
+## Install
+
+Verify prerequisites (`git`, `stow`, `task`):
+
+```bash
+task check
+```
+
+Dry-run (this package requires `--no-folding`):
+
+```bash
+task dry-run AREA=common PACKAGE=git
+# or directly:
+stow --dir=stow/common --target="$HOME" --no-folding --simulate git
+```
+
+Expect three `LINK:` lines and no conflicts. Then apply:
+
+⚠️  MANUAL STEP — review dry-run output before running
+
+```bash
+stow --dir=stow/common --target="$HOME" --no-folding git
+```
+
+## Wire it into `~/.gitconfig`
+
+Stowing only places the symlinks. A bootstrap task adds the `[include]` entries to `~/.gitconfig`.
+Preview first — it changes nothing:
+
+```bash
+task git:bootstrap:dry-run
+```
+
+Then apply:
+
+⚠️  MANUAL STEP — review dry-run output before running
+
+```bash
+task git:bootstrap
+```
+
+!!! note "Safe by construction"
+    `task git:bootstrap` creates a **timestamped backup** of `~/.gitconfig` before any change, and only
+    **appends** the include entries — it never removes or overwrites existing content. Running it a
+    second time detects the entries already present and skips them.
+
+Set your identity directly (never managed by this repository):
+
+⚠️  MANUAL STEP — replace placeholders with your own values
+
+```bash
+git config --global user.name "Your Name"
+git config --global user.email "your-email@example.com"
+```
+
+## Verify
+
+```bash
+git config --global --get-all include.path   # shows the two managed includes
+git config --global core.excludesfile        # ~/.config/git/ignore
+```
+
+## Related
+
+- [GNU Stow Workflow](../reference/stow.md) · [Installation](../installation.md)
diff --git a/website/features/index.md b/website/features/index.md
new file mode 100644
index 0000000..a98ad3f
--- /dev/null
+++ b/website/features/index.md
@@ -0,0 +1,21 @@
+# Features
+
+What the repository configures, grouped by area. Each area maps to one or more Stow packages under
+`stow/common/`. Install them independently — none requires the others.
+
+| Area | Tools / packages | Page |
+|---|---|---|
+| **Shell** | Layered Zsh config (path, history, plugins, tools, prompt, per-OS layers) | [Shell](shell.md) |
+| **Git** | Portable config, aliases, global ignore (no secrets) | [Git](git.md) |
+| **Terminal** | Alacritty terminal, Herdr multiplexer | [Terminal](terminal.md) |
+| **Editor** | Neovim (Lua, Catppuccin Macchiato) | [Editor](editor.md) |
+| **Packages** | bat, eza, and the Claude Code status line | [Packages](packages.md) |
+| **Scripts** | Helper scripts, e.g. OS maintenance | [Scripts](scripts.md) |
+
+!!! note "One package per tool"
+    Everything here is a separate Stow package. You can stow the shell without git, git without
+    alacritty, and so on. See [Installation](../installation.md) for the dry-run-first workflow and
+    [GNU Stow Workflow](../reference/stow.md) for the mechanics.
+
+A shared thread across the visual tools (alacritty, bat, eza, oh-my-posh, neovim) is the
+**Catppuccin Macchiato** palette with a blue accent, so the terminal looks consistent across them.
diff --git a/website/features/packages.md b/website/features/packages.md
new file mode 100644
index 0000000..d71a867
--- /dev/null
+++ b/website/features/packages.md
@@ -0,0 +1,67 @@
+# Packages
+
+A handful of small CLI tools, each in its own Stow package, that make daily terminal work nicer. All
+share the Catppuccin Macchiato (blue) look. Install only the ones you want — every package is
+independent.
+
+Curated from the bat, eza, claude, and omp setup guides / READMEs.
+
+## bat — a better `cat`
+
+`stow/common/bat/` themes [bat](https://github.com/sharkdp/bat) (syntax-highlighted file viewer) with
+Catppuccin Macchiato. In daily use it's a readable pager for source and logs; the zsh package also
+wires `.md` / `.txt` / `.log` suffix aliases to it.
+
+![bat showing a syntax-highlighted file in the Macchiato theme](../assets/images/bat-output.png)
+*Syntax-highlighted file preview with bat.*
+
+!!! note "One activation step"
+    bat reads themes from a compiled cache. After stowing, build it once:
+
+    ```bash
+    bat cache --build
+    bat --list-themes | grep "Catppuccin Macchiato"
+    ```
+
+## eza — a better `ls`
+
+`stow/common/eza/` ships a Catppuccin Macchiato (Blue) theme for [eza](https://github.com/eza-community/eza).
+No cache step — the theme applies as soon as it's stowed. The `ls` / `ll` / `la` / `lt` aliases live
+in the zsh package. Quick check after stowing:
+
+```bash
+eza -la --git
+```
+
+![eza directory listing with icons and Catppuccin Blue colors](../assets/images/eza-listing.png)
+*Icon-aware project listing powered by eza.*
+
+## Claude Code status line
+
+`stow/common/claude/` provides a status line script for [Claude Code](https://code.claude.com),
+rendering **OS icon · model · path · git branch+status · context %** in the same palette as the
+prompt. It needs `jq`, `git`, and a Nerd Font.
+
+![Claude Code status line showing OS, model, path, git, and context segments](../assets/images/claude-statusline.png)
+*Claude Code status line integrated into the terminal workflow.*
+
+!!! warning "`~/.claude` holds secrets — stow carefully"
+    Only `statusline-command.sh` is managed; credentials and session data in `~/.claude` are never
+    tracked. This package requires `--no-folding`, and on most machines the dry-run reports a conflict
+    (Claude Code already wrote a real script there) — resolve it manually, never with `--adopt`. See
+    the repository's `docs/guides/claude-setup.md` for the wiring step in `~/.claude/settings.json`.
+
+## Oh My Posh prompt
+
+`stow/common/omp/` holds the [Oh My Posh](https://ohmyposh.dev/) theme (`omp.toml`) — prompt segments
+(path, git, status) in the Catppuccin Macchiato palette. The zsh package initialises it; `omp` is the
+theme source of truth that the Claude status line mirrors. Stow it with the standard workflow:
+
+```bash
+stow --dir=stow/common --target="$HOME" --simulate omp
+```
+
+## Related
+
+- [Shell (Zsh)](shell.md) — aliases and prompt integration.
+- [GNU Stow Workflow](../reference/stow.md) · [Installation](../installation.md)
diff --git a/website/features/scripts.md b/website/features/scripts.md
new file mode 100644
index 0000000..4db74a3
--- /dev/null
+++ b/website/features/scripts.md
@@ -0,0 +1,64 @@
+# Scripts
+
+Routine system maintenance runs through the project's `task` runner. The helper script
+(`scripts/os-maintenance.sh`) detects the OS and runs the matching package-manager commands, so the
+same tasks work on macOS and Arch.
+
+Curated from `docs/guides/os-maintenance.md` and `Taskfile.yml`.
+
+Two concerns are kept separate: **update** (sync + upgrade packages) and **clean** (orphan removal,
+cache pruning, journal vacuum). Clean is non-destructive by default — it reports only, and deletes
+only with the explicit apply step.
+
+## Update
+
+```bash
+task update
+```
+
+- **Arch:** `yay -Syu` (or `sudo pacman -Syu` if `yay` is absent).
+- **macOS:** `brew update && brew upgrade`.
+
+Interactive — you'll be prompted for confirmation / sudo as usual.
+
+## Clean — dry-run (default, safe)
+
+```bash
+task clean
+```
+
+Reports what cleanup *would* remove and deletes nothing:
+
+- **Arch:** orphans (`pacman -Qtdq`), cached versions beyond the last 3 (`paccache`), journal disk usage.
+- **macOS:** `brew cleanup --dry-run`, `brew autoremove --dry-run`, `brew doctor`.
+
+## Clean — apply (destructive)
+
+The apply path re-prints the report, then performs the removals.
+
+⚠️  MANUAL STEP — review the dry-run output first
+
+```bash
+task clean:apply
+```
+
+- **Arch:** `sudo pacman -Rns <orphans>` (only if any), `sudo paccache -rk3`, `sudo paccache -ruk0`,
+  `sudo journalctl --vacuum-size=200M`.
+- **macOS:** `brew cleanup`, `brew autoremove`.
+
+!!! note "Recoverable vs not"
+    Removed package caches and orphans can be re-fetched by the package manager. Journal reclaim is
+    bounded and non-recoverable.
+
+## Deliberately not automated (Arch)
+
+!!! warning "Mirrorlist and `.pacnew` merges stay manual"
+    The helper never runs `pacdiff`, edits `mirrorlist`, or re-ranks mirrors — these are interactive
+    and host-specific, and a blind `.pacnew` overwrite has emptied a mirrorlist before. Review pending
+    config merges yourself with `sudo pacdiff`, and keep your existing `mirrorlist` rather than
+    overwriting it with an empty `.pacnew` template. See the repository's `docs/guides/os-maintenance.md`
+    for the mirror re-ranking commands.
+
+## Related
+
+- [Installation](../installation.md) · [Repository Structure](../reference/repository-structure.md)
diff --git a/website/features/shell.md b/website/features/shell.md
new file mode 100644
index 0000000..58ceb0e
--- /dev/null
+++ b/website/features/shell.md
@@ -0,0 +1,115 @@
+# Shell (Zsh)
+
+The `stow/common/zsh/` package manages a layered Zsh configuration under `~/.config/zsh/`. After
+stowing, `~/.config/zsh/` is a **real directory** and each managed file inside it is a per-file
+symlink into the repository.
+
+This page is curated from the repository's `docs/guides/zsh-setup.md`.
+
+![Oh My Posh prompt with an active Git segment](../assets/images/terminal-prompt.png)
+*Shell prompt with Git context and Catppuccin Macchiato colors.*
+
+!!! warning "`~/.zshrc` stays yours"
+    This package never stows, overwrites, or reads `~/.zshrc`. After stowing, you add **one guarded
+    include block** to your own `~/.zshrc` to source the managed config. Your existing shell startup
+    is preserved.
+
+## Layered structure
+
+`index.zsh` is the entry point — it sources each layer in order. Layers separate concerns so a single
+file owns a single job:
+
+| Layer | Responsibility |
+|---|---|
+| `shared.zsh` | XDG vars + portable env (`EDITOR`, `PAGER`) |
+| `path.zsh` | PATH additions (`$HOME`-relative, safe) |
+| `history.zsh` | HISTFILE, HISTSIZE, SAVEHIST, history options |
+| `plugins.zsh` | Zinit guarded source; owns plugin order + `compinit` |
+| `fzf.zsh` | fzf shell integration (no-op without `fzf`) |
+| `completions.zsh` | Completion styles + fzf-tab previews |
+| `taskfile.zsh` | `task <Tab>` completion tuning (no-op without `task`) |
+| `herdr.zsh` | `herdr <Tab>` session-name completion (no-op without `herdr`) |
+| `keybindings.zsh` | Key bindings |
+| `aliases.zsh` | Portable aliases |
+| `tools.zsh` | zoxide integration (guarded) |
+| `prompt.zsh` | Oh My Posh (double-guarded; no-op if missing) |
+| `macos.zsh` / `arch.zsh` | Per-OS layers, runtime-selected |
+
+!!! info "Private overrides go in `local.zsh`"
+    `local.zsh.example` is a skeleton you copy to `~/.config/zsh/local.zsh` for private,
+    machine-specific content. `local.zsh` is git-ignored and lives outside the repository working tree —
+    it is never committed.
+
+## Prompt
+
+The prompt comes from **Oh My Posh** via the separate `stow/common/omp/` package (Catppuccin Macchiato
+palette). The zsh package works without it: `prompt.zsh` is double-guarded and is a no-op when
+`oh-my-posh` is not installed or `omp.toml` is missing. Stow `omp` separately if you want the prompt.
+
+## Aliases and tool integrations
+
+Aliases live in `aliases.zsh` (portable) with tool-specific behaviour gated behind `command -v`:
+
+- `eza` provides `ls` / `ll` / `tree`-style aliases when installed.
+- `bat` adds suffix aliases (`.md`, `.txt`, `.log`) for file preview.
+- `zoxide` powers a smarter `cd`.
+- `fzf` drives fuzzy completion and fzf-tab previews.
+
+Each integration disappears cleanly if its tool is absent.
+
+## Completions
+
+Tab completion is layered on top of Zsh's `compinit` (run once in `plugins.zsh`). When the optional
+plugins are installed via Zinit, the setup adds:
+
+- **`zsh-completions`** — extra completion definitions, loaded onto `fpath` before `compinit`.
+- **`fzf-tab`** — replaces the completion menu with an fzf picker. `completions.zsh` adds previews:
+  directory completions preview with `eza`, file completions with `bat` (falling back to `ls` / `cat`
+  when those tools are absent).
+- **`task` completion** — `taskfile.zsh` tunes the native `_task` completion shipped by the go-task
+  package, showing task descriptions and a read-only summary preview. No-op without `task`.
+- **`herdr` completion** — `herdr.zsh` authors session-name completion for `herdr <Tab>` (Herdr ships
+  no native completion), using the read-only `herdr session list`. No-op without `herdr`.
+
+!!! note "All guarded, all read-only"
+    Each completion layer is gated behind `command -v` and is skipped when its tool is missing. The
+    `task` and `herdr` previews only read state — they never run a task or mutate a session. The
+    plugins themselves require Zinit and `fzf`; see [Shell Dependencies](../reference/shell-dependencies.md).
+
+## Dependencies
+
+Required before stowing: `zsh`, `stow`, `git`. Everything else is optional and guarded — see
+[Shell Dependencies](../reference/shell-dependencies.md) for the full tier table and install commands,
+and check your machine with:
+
+```bash
+task deps:check:zsh
+```
+
+## Stowing the package
+
+Dry-run first. This package requires `--no-folding` (and `task dry-run` does **not** pass it, so use
+the direct command):
+
+```bash
+stow --dir=stow/common --target="$HOME" --no-folding --simulate zsh
+```
+
+Look for `LINK:` lines for each managed file, and no `CONFLICT` / `WARNING` lines. Then apply:
+
+⚠️  MANUAL STEP — review dry-run output before running
+
+```bash
+stow --dir=stow/common --target="$HOME" --no-folding zsh
+```
+
+After stowing, add the include block to `~/.zshrc` (see `docs/guides/zsh-setup.md` for the exact block)
+and start a new shell.
+
+!!! warning "Not claimed portable beyond macOS + Arch"
+    The layered config is tested on macOS (primary) and EndeavourOS / Arch Linux. Elsewhere, read it as
+    a reference and adapt rather than expecting a drop-in install.
+
+## Related
+
+- [Shell Dependencies](../reference/shell-dependencies.md) · [GNU Stow Workflow](../reference/stow.md) · [Installation](../installation.md)
diff --git a/website/features/terminal.md b/website/features/terminal.md
new file mode 100644
index 0000000..a665cb4
--- /dev/null
+++ b/website/features/terminal.md
@@ -0,0 +1,69 @@
+# Terminal
+
+Two packages shape the terminal: **Alacritty** (the emulator) and **Herdr** (an agent-oriented
+multiplexer). Both ship a Catppuccin Macchiato look with a blue accent, consistent with the rest of
+the setup.
+
+Curated from `docs/guides/alacritty-setup.md` and `docs/guides/herdr-setup.md`.
+
+## Alacritty
+
+The `stow/common/alacritty/` package manages two files in `~/.config/alacritty/`:
+
+| File | Purpose |
+|---|---|
+| `alacritty.toml` | Window, font, keybindings, shell, theme import |
+| `catppuccin-macchiato.toml` | Catppuccin Macchiato color theme |
+
+Alacritty loads the config on startup — no activation step beyond stowing.
+
+!!! note "macOS-specific lines are harmless on Linux"
+    `decorations = "Buttonless"` and `option_as_alt = "Both"` only affect macOS. Alacritty ignores
+    inapplicable values gracefully on Arch.
+
+Dry-run, then apply (requires `--no-folding`):
+
+```bash
+stow --dir=stow/common --target="$HOME" --no-folding --simulate alacritty
+```
+
+⚠️  MANUAL STEP — review dry-run output before running
+
+```bash
+stow --dir=stow/common --target="$HOME" --no-folding alacritty
+```
+
+## Herdr
+
+The `stow/common/herdr/` package manages a single file, `~/.config/herdr/config.toml` — theme,
+terminal, UI, and toast settings. Herdr is an agent-oriented multiplexer; it loads
+`~/.config/herdr/config.toml` automatically on startup, so there's no activation step beyond stowing.
+The default shell is `zsh` and new panes follow the active pane's working directory.
+
+The zsh package also ships **Herdr session-name completion** (`herdr <Tab>`) — see
+[Completions](shell.md#completions).
+
+![Herdr multiplexer session with panes and agent labels](../assets/images/herdr-session.png)
+*Herdr session layout for agent-oriented terminal work.*
+
+!!! warning "Only `config.toml` is managed"
+    Herdr also keeps session state and workspace data under `~/.config/herdr/`. The package manages
+    **only** `config.toml`. Never remove the whole `~/.config/herdr/` directory — if there's an
+    existing `config.toml`, back up and remove just that one file before stowing.
+
+Dry-run, then apply (requires `--no-folding`):
+
+```bash
+stow --dir=stow/common --target="$HOME" --no-folding --simulate herdr
+```
+
+⚠️  MANUAL STEP — review dry-run output before running
+
+```bash
+stow --dir=stow/common --target="$HOME" --no-folding herdr
+```
+
+## Related
+
+- [Shell (Zsh)](shell.md) — the prompt and shell that run inside the terminal.
+- [GNU Stow Workflow](../reference/stow.md) · [Installation](../installation.md)
diff --git a/website/getting-started.md b/website/getting-started.md
new file mode 100644
index 0000000..7d60972
--- /dev/null
+++ b/website/getting-started.md
@@ -0,0 +1,76 @@
+# Getting Started
+
+This page explains how to approach the repository before you change anything on your machine. The
+goal is to help you understand the setup first, then adopt only the parts you want.
+
+!!! warning "Don't run everything blindly"
+    This repository is meant to be **read and adopted deliberately**, not piped into a shell. There is
+    no one-shot install script, and that is intentional. Every step that touches your home directory is
+    something you run yourself after reviewing it.
+
+## Inspect the structure first
+
+Clone the repository and look around before doing anything else:
+
+```bash
+git clone https://github.com/fnayou/dotfiles.git
+cd dotfiles
+```
+
+The layout you care about as a visitor:
+
+```
+stow/
+  common/     # Packages that work on macOS and Arch (source of truth)
+  macos/      # macOS-specific packages (currently empty)
+  arch/       # Arch / EndeavourOS-specific packages (currently empty)
+docs/         # Internal project notes (kept as-is; not part of this site)
+website/      # The source of this documentation site
+README.md     # Repository overview and package table
+```
+
+Each package under `stow/common/` is self-contained and carries its own `README.md`. Start there —
+read the package that interests you and the matching guide before deciding what to do with it.
+
+See [Repository Structure](reference/repository-structure.md) for the full map.
+
+## Reading vs. copying vs. installing
+
+Three different levels of adoption — pick per package, not for the whole repo:
+
+| Level | What it means | Risk |
+|---|---|---|
+| **Read** | Open files to understand or learn from them | None |
+| **Copy** | Take a snippet (an alias, a setting) into your own config | You own the result |
+| **Install (stow)** | Symlink a whole package into `$HOME` via GNU Stow | Changes your home dir — do a dry-run first |
+
+!!! tip "Copying is often enough"
+    If you only want one alias or one prompt segment, copy it. You don't need to stow anything. Stowing
+    is for when you want this repository to *own* a config file as a live symlink.
+
+## Two paths
+
+### Beginner path — read and borrow
+
+1. Browse the [package table in the README](https://github.com/fnayou/dotfiles#readme) and this site's
+   [Features](features/index.md).
+2. Open the package and guide for anything that looks useful.
+3. Copy the specific lines you want into your own dotfiles. Done — nothing else required.
+
+### Advanced path — install with Stow
+
+1. Read [Installation](installation.md) end to end.
+2. Install the [required dependencies](installation.md#dependencies) for the packages you want.
+3. **Dry-run** each package with `--simulate` and review the output.
+4. Resolve any conflicts manually (never `--adopt`).
+5. Install one package at a time, only after its dry-run looks correct.
+
+!!! danger "Stow modifies your home directory"
+    Installing a package creates symlinks in `$HOME`. Always run the dry-run first and read it. If a
+    dry-run reports a conflict, **stop** and resolve it manually — see
+    [Troubleshooting](reference/troubleshooting.md) and the [GNU Stow Workflow](reference/stow.md).
+
+## Next
+
+- [Installation](installation.md) — the safe, dry-run-first install workflow.
+- [Philosophy](philosophy.md) — why the repository is shaped this way.
diff --git a/website/index.md b/website/index.md
new file mode 100644
index 0000000..52829f0
--- /dev/null
+++ b/website/index.md
@@ -0,0 +1,56 @@
+# fnayou/dotfiles
+
+Personal, cross-platform dotfiles for **macOS** and **EndeavourOS / Arch Linux**, managed with
+[GNU Stow](https://www.gnu.org/software/stow/) and themed around Catppuccin Macchiato (blue accent).
+
+This is the configuration that runs my own machines: shell, prompt, terminal, editor, and a handful
+of CLI tools, wired together so a fresh machine becomes familiar in a few deliberate steps.
+
+## What this is
+
+A version-controlled collection of dotfiles organised as small, self-contained **Stow packages**.
+Each package manages one tool (zsh, git, alacritty, neovim, …) and can be installed on its own. Nothing
+is installed automatically — every change to your home directory is a manual, reviewed step.
+
+## Who it's for
+
+- People who live in the **terminal** and want a documented, working reference setup.
+- Anyone who wants to **borrow ideas or specific configs** without adopting a whole framework.
+- macOS and Arch users who want the same configuration to behave consistently on both.
+
+!!! note "Take only what you need"
+    This is not an all-or-nothing install. You can read a single file, copy one alias, or stow one
+    package. The repository is built so that **using a part of it does not require using all of it.**
+
+## Philosophy in five words
+
+- **Documented** — every package has a README and a human setup guide; significant decisions are recorded.
+- **Modular** — one Stow package per tool; install them independently.
+- **Reproducible** — the repository is the source of truth; a new machine is set up from it deliberately.
+- **Terminal-focused** — shell, prompt, and CLI ergonomics come first.
+- **Safe to explore** — dry-run before anything touches `$HOME`; no secrets committed; nothing runs on its own.
+
+## Feature overview
+
+| Area | Tools |
+|---|---|
+| **Shell** | Layered Zsh config — path, history, plugins, tools, prompt, per-OS layers |
+| **Prompt** | Oh My Posh, Catppuccin Macchiato palette |
+| **Terminal** | Alacritty, Herdr multiplexer |
+| **Editor** | Neovim (Lua, Catppuccin Macchiato) |
+| **Git** | Portable config, aliases, global ignore — no secrets |
+| **CLI tools** | bat, eza, fzf, zoxide, and a Claude Code status line |
+
+See [Features](features/index.md) for the per-tool detail.
+
+![Shell prompt showing the current path and Git status in Catppuccin Macchiato colors](assets/images/terminal-prompt.png)
+*Shell prompt with Git context and Catppuccin Macchiato colors.*
+
+## Where to go next
+
+- [Getting Started](getting-started.md) — how to approach the repository safely.
+- [Installation](installation.md) — dependencies, dry-run, and the Stow workflow.
+- [Philosophy](philosophy.md) — the principles behind the setup.
+- [Features](features/index.md) — what each package configures.
+- [Usage](usage/index.md) — day-to-day workflow, aliases, functions, tasks.
+- [Reference](reference/index.md) — structure, Stow, dependencies, troubleshooting.
diff --git a/website/installation.md b/website/installation.md
new file mode 100644
index 0000000..3f789de
--- /dev/null
+++ b/website/installation.md
@@ -0,0 +1,127 @@
+# Installation
+
+This page describes the safe way to install packages from this repository. The approach is the same
+everywhere: install the tools you need, **dry-run**, review, then install one package at a time.
+
+!!! warning "Manual by design"
+    Nothing here runs automatically. There is no bootstrap script that installs everything. Each command
+    is something you run yourself after reviewing it. Commands that change your system are marked.
+
+## How installation works
+
+The repository uses [GNU Stow](https://www.gnu.org/software/stow/) with a **package-based layout**.
+Each package under `stow/common/` is a directory whose contents mirror your home directory. Stowing a
+package creates symlinks in `$HOME` pointing back into the repository.
+
+```
+stow/
+  common/     # works on macOS and Arch (source of truth)
+  macos/      # macOS-only packages (currently empty)
+  arch/       # Arch / EndeavourOS-only packages (currently empty)
+```
+
+## Dependencies
+
+The packages depend on a small set of tools. Two are required; the rest are optional and the shell
+config starts cleanly without them.
+
+| Tool | Used by | Required? |
+|---|---|---|
+| `git` | repository management | Yes |
+| `stow` | symlink manager | Yes |
+| [`go-task`](https://taskfile.dev/) | task runner; powers `task <Tab>` completion | Yes |
+| `fzf`, `zoxide`, `eza`, `bat`, `oh-my-posh`, `zinit`, `herdr` | shell/tooling enhancements | Optional |
+
+Install commands per platform (from the repository's packages guide):
+
+=== "macOS"
+
+    ⚠️  MANUAL STEP — review `brew bundle list` output before running
+
+    ```bash
+    # Preview, then install the full set from the repo's Brewfile
+    brew bundle list --file=packages/Brewfile
+    brew bundle --file=packages/Brewfile
+    ```
+
+=== "Arch / EndeavourOS"
+
+    ⚠️  MANUAL STEP — review before running
+
+    ```bash
+    sudo pacman -S git stow go-task fzf zoxide eza bat
+    # oh-my-posh is AUR-only:
+    yay -S oh-my-posh-bin
+    ```
+
+Want only specific tools? Install them individually — every optional tool is guarded in the zsh config
+and silently skipped when absent. See the repository's packages guide for the selective-install list and
+the `zinit` clone step.
+
+Verify what's installed:
+
+```bash
+task deps:check:zsh
+```
+
+## Install a package
+
+### Step 1 — list packages
+
+```bash
+task list
+```
+
+Output is `<area>/<package>` (for example `common/git`).
+
+### Step 2 — dry-run (mandatory)
+
+The dry-run shows exactly what Stow *would* do, without changing anything. Always do this first.
+
+```bash
+task dry-run AREA=common PACKAGE=git
+```
+
+Or directly:
+
+```bash
+stow --dir=stow/common --target="$HOME" --simulate git
+```
+
+Read the output carefully. If anything looks unexpected, stop and investigate.
+
+### Step 3 — install
+
+Only after the dry-run looks correct. Install one package at a time.
+
+⚠️  MANUAL STEP — review the dry-run output before running
+
+```bash
+stow --dir=stow/common --target="$HOME" git
+```
+
+!!! danger "Never use `--adopt`"
+    `--adopt` silently overwrites existing files with the repository version and cannot be undone. It is
+    forbidden in this repository. If a dry-run reports a conflict, resolve it manually instead — see
+    [Troubleshooting](reference/troubleshooting.md).
+
+## Package bootstrap helpers
+
+Some packages (git, zsh) need a one-time local file created before stowing. The repository provides
+dry-run-able task helpers for these:
+
+```bash
+task git:bootstrap:dry-run
+task zsh:bootstrap:dry-run
+```
+
+<!-- TODO: confirm and document the exact post-dry-run apply steps for git:bootstrap / zsh:bootstrap from docs/guides/{git,zsh}-setup.md when migrating the Features pages. -->
+
+## Full detail
+
+The complete dry-run / install / conflict-handling workflow lives in the
+[GNU Stow Workflow](reference/stow.md) reference page, adapted from the repository's own Stow usage
+guide.
+
+![Output of a stow --simulate dry-run listing the links it would create](assets/images/stow-dryrun.png)
+*GNU Stow simulation before applying a package.*
diff --git a/website/philosophy.md b/website/philosophy.md
new file mode 100644
index 0000000..636dda0
--- /dev/null
+++ b/website/philosophy.md
@@ -0,0 +1,76 @@
+# Philosophy
+
+The principles behind this repository. These explain *why* it is shaped the way it is — useful if you
+want to understand the choices, or borrow the approach for your own dotfiles.
+
+!!! note "Personal, not a framework"
+    This is my own setup, kept tidy enough to share. It is **not** a universal dotfiles framework and
+    doesn't try to be one. There's no plugin system, no abstraction layer to learn — just configuration
+    files organised so they're easy to read and easy to take pieces from.
+
+## Safe by default
+
+Nothing touches your home directory on its own. There is no install script that runs Stow, and Stow is
+always a deliberate, reviewed step:
+
+- **Dry-run first.** Every install is preceded by a `--simulate` run you read before applying.
+- **No `--adopt`, ever.** It silently overwrites files; conflicts are resolved by hand instead.
+- **One package at a time.** Small, reversible steps over a big-bang setup.
+
+If you only take one idea from here, take this one: a dotfiles repo should never surprise your home directory.
+
+## Modular, not monolithic
+
+Each tool is its own Stow package. You can install zsh without git, git without alacritty, and so on.
+This keeps the repository honest — a package that can't stand alone doesn't belong in `common/`. It also
+means **you can adopt one package and ignore the rest.**
+
+## Documented on purpose
+
+Configuration that isn't explained gets cargo-culted. So every package carries a README and a human
+setup guide, and significant technical choices are written down as decision records inside the
+repository. The intent is that you can always answer "why is this here?" without archaeology.
+
+!!! info "This site is a curated view"
+    The repository also contains a larger body of internal notes — product requirements, plans, reviews,
+    and decision records — used while building it. This public site is **curated** from that material:
+    it surfaces what's useful to a visitor and leaves the process documentation in the repository's
+    `docs/` directory for anyone who wants to dig deeper. The internal notes are not reproduced here
+    verbatim.
+
+## Reproducible and cross-platform
+
+The repository is the source of truth. A new machine is brought up *from* it, deliberately, rather than
+configured ad hoc. macOS and Arch are treated as first-class together: `common/` packages are written to
+behave identically on both, and anything genuinely platform-specific is isolated rather than mixed in.
+
+!!! warning "Honest about compatibility"
+    Tested on macOS (primary) and EndeavourOS / Arch Linux. It is not claimed to work on other systems —
+    if you're elsewhere, treat it as a reference to read and adapt, not a drop-in install.
+
+## Built for reuse and inspiration
+
+The repository is structured so the smallest useful unit is easy to lift out:
+
+- Want one alias? Copy the line.
+- Want the prompt? Take the Oh My Posh config.
+- Want the whole shell setup? Stow the zsh package.
+
+You don't have to agree with every choice to get value here. Read it, disagree where you like, and keep
+the parts that fit your own workflow.
+
+## Acknowledgements
+
+This project and its documentation were built through a mix of personal experience, manual curation, and
+AI-assisted work.
+
+Claude helped with repository-oriented implementation, refactoring, and documentation tasks. ChatGPT
+helped with planning, structure, review, and documentation guidance.
+
+The final decisions, testing, configuration choices, and publishing remain human-controlled.
+
+## Next
+
+- [Getting Started](getting-started.md) — how to approach the repo.
+- [Installation](installation.md) — the dry-run-first install workflow.
+- [Features](features/index.md) — what each package configures.
diff --git a/website/reference/index.md b/website/reference/index.md
new file mode 100644
index 0000000..6cbe47a
--- /dev/null
+++ b/website/reference/index.md
@@ -0,0 +1,18 @@
+# Reference
+
+Deeper technical detail for when you want to understand how the repository works under the hood. If
+you're just getting set up, start with [Getting Started](../getting-started.md) and [Usage](../usage/index.md)
+— those are the practical onboarding path. The pages here are for looking things up.
+
+| Page | What it covers |
+|---|---|
+| [Repository Structure](repository-structure.md) | The top-level layout — what `stow/`, `docs/`, `website/`, `Taskfile.yml`, and `.github/` are for |
+| [GNU Stow Workflow](stow.md) | How packages become symlinks: dry-run, install, conflicts, `--no-folding`, re-stow |
+| [Shell Dependencies](shell-dependencies.md) | The tools the shell config uses, their tiers, and how to check/install them |
+| [Supported Systems](supported-systems.md) | Which platforms are tested, and what's portable vs system-specific |
+| [Troubleshooting](troubleshooting.md) | Fixes for common issues — Stow conflicts, broken symlinks, missing deps, fonts |
+
+!!! note "Reference vs onboarding"
+    Getting Started and Usage tell you *what to do*. Reference tells you *how it works* and *why* — use it
+    when something doesn't behave as expected, or when you want the full picture before adapting a part of
+    the setup for yourself.
diff --git a/website/reference/repository-structure.md b/website/reference/repository-structure.md
new file mode 100644
index 0000000..03f3930
--- /dev/null
+++ b/website/reference/repository-structure.md
@@ -0,0 +1,52 @@
+# Repository Structure
+
+A map of the repository from a visitor's perspective — what each top-level entry is for, and which
+parts are meant for public reuse versus internal project history.
+
+```
+dotfiles/
+├── README.md          # Repository overview + package table (GitHub landing)
+├── AGENTS.md          # Internal operating contract (for automation; not part of this site)
+├── Taskfile.yml       # go-task targets: list, dry-run, deps checks, bootstraps
+├── mkdocs.yml         # Configuration for this documentation site
+├── stow/              # The actual dotfiles, as Stow packages (source of truth)
+│   ├── common/        # Works on macOS and Arch
+│   ├── macos/         # macOS-specific (currently empty)
+│   └── arch/          # Arch / EndeavourOS-specific (currently empty)
+├── packages/          # Dependency manifests (Brewfile, arch/packages.txt)
+├── scripts/           # Helper scripts (dependency checks, maintenance)
+├── docs/              # Internal project documentation (kept as-is)
+├── website/           # Public documentation source — this site
+└── .github/           # GitHub Actions workflows (CI + docs deploy)
+```
+
+## What each part is
+
+| Entry | Purpose | For visitors |
+|---|---|---|
+| `README.md` | Repository overview and the package table | Start here on GitHub |
+| `docs/` | Internal AI/process/project notes — PRDs, plans, reviews, decisions, guides | Source material; **not published to this site** |
+| `website/` | The Markdown source for this documentation site | **This is the public docs source** |
+| `stow/` | The configuration itself, organised as Stow packages | The thing you read, copy, or stow |
+| `Taskfile.yml` | [go-task](https://taskfile.dev/) targets for listing, dry-running, and checking deps | Run `task list` to explore |
+| `.github/` | GitHub Actions — hygiene CI and the Pages deploy workflow | Nothing to run yourself |
+
+!!! info "`docs/` vs `website/`"
+    `docs/` holds the repository's **internal** documentation — the product requirements, plans,
+    reviews, and decision records produced while building the setup. This site is **curated** from that
+    material and lives in `website/`; the internal notes are not republished here verbatim. If you want
+    the full project history, read `docs/` directly in the repository.
+
+!!! note "`stow/` is the source of truth"
+    The `stow/common/` directory defines which packages exist. Each package is self-contained and
+    carries its own `README.md`. `stow/macos/` and `stow/arch/` are reserved for platform-specific
+    packages and are currently empty.
+
+![Tree view of the stow directory showing one folder per package](../assets/images/repo-tree.png)
+*Package-based repository layout under stow/.*
+
+## Related
+
+- [Getting Started](../getting-started.md) — how to approach the repository.
+- [GNU Stow Workflow](stow.md) — how the `stow/` packages become symlinks.
+- [Features](../features/index.md) — what each package configures.
diff --git a/website/reference/shell-dependencies.md b/website/reference/shell-dependencies.md
new file mode 100644
index 0000000..1fcedf6
--- /dev/null
+++ b/website/reference/shell-dependencies.md
@@ -0,0 +1,128 @@
+# Shell Dependencies
+
+The managed Zsh configuration depends on a small set of external tools. They must be installed
+**before** stowing the zsh package or sourcing the managed config files. Nothing in this repository
+installs tools automatically — shell startup never runs `brew`, `pacman`, or `git clone`.
+
+This page is curated from the repository's `docs/shell-dependencies.md` and `docs/guides/packages-setup.md`.
+
+## Three separate concerns
+
+| Concern | What it means | How |
+|---|---|---|
+| **Check** | Detect which tools are present or missing | `task deps:check:zsh` |
+| **Install** | Place tools on the system | Manual — see below |
+| **Activate** | Wire tools into the shell | Happens when the zsh package is stowed and sourced |
+
+## Dependency tiers
+
+| Tool | Tier | Required? | macOS source | Arch source |
+|---|---|---|---|---|
+| `git` | core | Yes | `packages/Brewfile` | `pacman` |
+| `stow` | core | Yes | `packages/Brewfile` | `pacman` |
+| `go-task` | core | Yes | `packages/Brewfile` (tap) | `pacman` |
+| `fzf` | shell | Optional | `packages/Brewfile` | `pacman` |
+| `zoxide` | shell | Optional | `packages/Brewfile` | `pacman` |
+| `eza` | shell | Optional | `packages/Brewfile` | `pacman` |
+| `bat` | shell | Optional | `packages/Brewfile` | `pacman` |
+| `oh-my-posh` | shell | Optional | `packages/Brewfile` (tap) | AUR (`oh-my-posh-bin`) |
+| `zinit` | shell | Optional | manual git clone | manual git clone |
+
+!!! tip "Optional means optional"
+    Every shell-tier integration is guarded with `command -v` and is a no-op when its tool is absent.
+    The shell starts cleanly with none of them installed — install only what you want.
+
+!!! info "`go-task` and `task <Tab>` completion"
+    `go-task` is both the repo's task runner and a shell-tier dependency: the zsh package's
+    `taskfile.zsh` enables `task <Tab>` completion. That completion relies on the native `_task` file
+    shipped by the Homebrew (`go-task/tap`) and pacman (`go-task`) packages. Installing `task` another
+    way (`go install`, raw `install.sh`) omits `_task`, so completion is unavailable on those installs.
+
+## Step 1 — Check what is missing
+
+```bash
+task deps:check:zsh
+```
+
+Or directly:
+
+```bash
+bash scripts/check-zsh-deps.sh
+```
+
+Output is `PASS: <tool>` or `FAIL: <tool> (not installed)` per tool, with an install hint on failure.
+Exit code is non-zero if any required tool is missing.
+
+## Step 2 — Install
+
+=== "macOS"
+
+    All tools via the repo's Brewfile (preview first, then install):
+
+    ⚠️  MANUAL STEP — review `brew bundle list` output before running
+
+    ```bash
+    brew bundle list --file=packages/Brewfile
+    brew bundle --file=packages/Brewfile
+    ```
+
+    `zinit` is not in the Brewfile — clone it once per machine:
+
+    ⚠️  MANUAL STEP — review before running
+
+    ```bash
+    git clone https://github.com/zdharma-continuum/zinit.git \
+      "${XDG_DATA_HOME:-$HOME/.local/share}/zinit/zinit.git"
+    ```
+
+=== "Arch / EndeavourOS"
+
+    Pacman packages:
+
+    ⚠️  MANUAL STEP — review before running
+
+    ```bash
+    sudo pacman -S git stow go-task fzf zoxide eza bat
+    ```
+
+    AUR (requires `yay` or `paru`):
+
+    ⚠️  MANUAL STEP — review before running
+
+    ```bash
+    yay -S oh-my-posh-bin
+    ```
+
+    `zinit` (same as macOS):
+
+    ⚠️  MANUAL STEP — review before running
+
+    ```bash
+    git clone https://github.com/zdharma-continuum/zinit.git \
+      "${XDG_DATA_HOME:-$HOME/.local/share}/zinit/zinit.git"
+    ```
+
+    See `packages/arch/packages.txt` in the repository for a full annotated package list.
+
+## Step 3 — Verify
+
+```bash
+task deps:check:zsh
+```
+
+All lines should show `PASS`. Exit code `0` means all required shell-tier tools are present.
+
+## Taskfile reference
+
+| Task | What it does |
+|---|---|
+| `task check` | Check core prerequisites (`git`, `stow`, `task`) |
+| `task deps:check:zsh` | Check shell-tier tools |
+| `task deps:brew` | Print manual install commands for macOS / Homebrew |
+| `task deps:arch` | Print manual install commands for Arch / EndeavourOS |
+
+None of these tasks install anything — they check and report, or print instructions.
+
+## Related
+
+- [Installation](../installation.md) · [GNU Stow Workflow](stow.md) · [Shell feature page](../features/shell.md)
diff --git a/website/reference/stow.md b/website/reference/stow.md
new file mode 100644
index 0000000..7ad51ac
--- /dev/null
+++ b/website/reference/stow.md
@@ -0,0 +1,125 @@
+# GNU Stow Workflow
+
+This repository uses [GNU Stow](https://www.gnu.org/software/stow/) with a **package-based layout**
+to manage dotfile symlinks safely and incrementally. Stow is never run automatically — every install
+is a deliberate, manual action.
+
+This page is the curated reference. The full source lives in the repository at `docs/stow-usage.md`.
+
+## How Stow is used here
+
+A **package** is a directory under `stow/` whose internal structure mirrors your home directory.
+Stowing a package creates **symlinks** in the **target directory** (`$HOME`) that point back into the
+repository. Edit the file in the repo, and the change is live in `$HOME` immediately.
+
+```
+stow/
+├── common/          # Config that works on both macOS and Arch without modification
+│   ├── alacritty/   # Alacritty terminal config + Catppuccin theme
+│   ├── git/         # Git config templates
+│   ├── herdr/       # Herdr multiplexer config + Catppuccin overrides
+│   └── zsh/         # Zsh config (shared + macOS + Arch, runtime OS detection)
+├── macos/           # macOS-specific config only
+└── arch/            # EndeavourOS / Arch-specific config only
+```
+
+A package belongs in `common/` only if all three hold:
+
+1. The config file path is identical on macOS and Arch.
+2. The config values work unmodified on both platforms.
+3. No platform-specific tool or behavior is referenced.
+
+Otherwise it belongs in `macos/` or `arch/`.
+
+!!! note "Platform directories are not packages"
+    `stow/macos/` and `stow/arch/` currently contain only `.gitkeep` markers. They are platform
+    *areas*, not stowable packages. A valid dry-run needs a real package directory under an area, e.g.
+    `stow/common/git/`.
+
+## Dry-run before anything
+
+Always dry-run first. The simulation shows exactly what Stow *would* do, with no changes made.
+
+List available packages (output is `<area>/<package>`):
+
+```bash
+task list
+```
+
+Dry-run a package:
+
+```bash
+task dry-run AREA=common PACKAGE=git
+```
+
+Or directly:
+
+```bash
+stow --dir=stow/common --target="$HOME" --simulate git
+```
+
+Review the output carefully. If anything looks unexpected, **stop and investigate** before proceeding.
+
+![Output of a stow --simulate dry-run listing the links it would create](../assets/images/stow-dryrun.png)
+*GNU Stow simulation before applying a package.*
+
+## Install a package
+
+Install is a manual step, run only after a clean dry-run. Install one package at a time.
+
+⚠️  MANUAL STEP — review dry-run output before running
+
+```bash
+stow --dir=stow/common --target="$HOME" git
+```
+
+## Conflict handling
+
+If Stow reports a conflict (an existing file at the link target), **stop immediately**.
+
+1. Identify the conflicting file in `$HOME`.
+2. Decide whether to back it up, remove it, or keep it and not stow this package.
+3. Re-run the dry-run after resolving.
+4. Only then proceed with install.
+
+Stow may also report a **directory-ownership** conflict — the target directory exists but wasn't
+created by Stow, so Stow refuses to claim it. That is correct behaviour. Resolve by backing up and
+removing the directory, comparing manually file by file, or deferring the stow and using the
+`.example` template for reference until you're ready.
+
+!!! danger "Never use `--adopt`"
+    `--adopt` silently overwrites existing files with the repository version and cannot be undone
+    without the original file. It is **forbidden** in this repository. Resolve conflicts manually
+    instead.
+
+## Adding a file to an already-stowed package
+
+Stow does **not** pick up newly added files automatically. After adding a file to a package that is
+already stowed, re-stow it. Dry-run first:
+
+```bash
+stow --dir=stow/common --target="$HOME" --no-folding --simulate <package>
+```
+
+⚠️  MANUAL STEP — review dry-run output before running
+
+```bash
+stow --dir=stow/common --target="$HOME" --no-folding --restow <package>
+```
+
+!!! info "`--no-folding` only where needed"
+    Only `zsh`, `alacritty`, and `herdr` require `--no-folding`. `git` and `omp` do not — drop the
+    flag for those.
+
+## Forbidden
+
+- `stow .` — stows everything without control. Always use explicit package paths.
+- `stow --adopt` — silently overwrites existing files. Never use this.
+- Running stow without a prior dry-run.
+- Stow operations in scripts, hooks, or CI — all stow operations are manual only.
+
+## Related
+
+- [Installation](../installation.md) — the end-to-end install overview.
+- [Shell Dependencies](shell-dependencies.md) — tools to install before stowing the zsh package.
+- [Troubleshooting](troubleshooting.md) — common Stow problems.
diff --git a/website/reference/supported-systems.md b/website/reference/supported-systems.md
new file mode 100644
index 0000000..285127c
--- /dev/null
+++ b/website/reference/supported-systems.md
@@ -0,0 +1,56 @@
+# Supported Systems
+
+This is a personal setup, kept tidy enough to share. Two systems are actively used and tested; anything
+else should be treated as a reference to read and adapt, not a drop-in install.
+
+## Tested platforms
+
+| Platform | Status |
+|---|---|
+| **macOS** | Primary environment, frequently used |
+| **EndeavourOS / Arch Linux** | Also used and supported from the start |
+
+!!! warning "No broad-Linux claim"
+    The repository targets macOS and Arch / EndeavourOS specifically. Other Linux distributions are not
+    claimed to work — the package manager steps assume Homebrew (macOS) or `pacman` / AUR (Arch). On
+    another distro, the shell config and themes may still be useful, but you'll need to install
+    dependencies your own way.
+
+## What's portable vs system-specific
+
+| Layer | Portability |
+|---|---|
+| Zsh config, aliases, prompt, tool integrations | Portable across macOS and Arch; optional tools are guarded and no-op when absent |
+| Git config, aliases, ignore | Portable (no OS-specific assumptions) |
+| Alacritty, bat, eza, Neovim themes | Portable config paths (XDG); some Alacritty lines are macOS-only but harmless on Linux |
+| Package installation | System-specific — Homebrew on macOS, `pacman`/AUR on Arch |
+| OS maintenance (`task update` / `clean`) | Branches by OS inside the helper script |
+
+The zsh package separates per-OS concerns into `macos.zsh` and `arch.zsh`, selected at runtime, so the
+shared layers stay identical on both. See [Shell](../features/shell.md).
+
+## Check your machine
+
+The repository ships read-only dependency checks (they never install anything):
+
+```bash
+task check            # core prerequisites: stow, git, task
+task deps:check:zsh   # shell-tier tools: fzf, zoxide, eza, bat, oh-my-posh, zinit
+task deps:check:nvim  # Neovim-tier tools: nvim, tree-sitter, rg, fd, node
+```
+
+Detect which OS the helper scripts will assume:
+
+```bash
+task detect           # prints "macos" or "arch"
+```
+
+## Expect to adapt
+
+This configuration encodes personal preferences. Treat it as a starting point: read the parts that
+interest you, copy what fits, and change what doesn't. See [Philosophy](../philosophy.md) and
+[Getting Started](../getting-started.md).
+
+## Related
+
+- [Installation](../installation.md) · [Shell Dependencies](shell-dependencies.md) · [Troubleshooting](troubleshooting.md)
diff --git a/website/reference/troubleshooting.md b/website/reference/troubleshooting.md
new file mode 100644
index 0000000..e424461
--- /dev/null
+++ b/website/reference/troubleshooting.md
@@ -0,0 +1,157 @@
+# Troubleshooting
+
+Common problems and how to resolve them safely. **Inspect first, change second** — every section starts
+with read-only checks before any fix. Destructive or modifying steps are marked.
+
+!!! danger "Never use `stow --adopt`"
+    `--adopt` silently overwrites your existing files with the repository version and cannot be undone
+    without the original. It is forbidden in this repository. Resolve conflicts manually instead.
+
+## Stow reports a conflict
+
+A real file already exists at the link target. Inspect it:
+
+```bash
+ls -la ~/.config/<package>/
+```
+
+Resolve by moving the existing file aside, then re-running the dry-run:
+
+⚠️  MANUAL STEP — moves your existing file; review first
+
+```bash
+mv ~/.config/<package>/<file> ~/.config/<package>/<file>.bak
+stow --dir=stow/common --target="$HOME" --simulate <package>
+```
+
+Only apply once the dry-run is clean. Full detail in the [GNU Stow Workflow](stow.md).
+
+## A config directory became a symlink (directory folding)
+
+If `~/.config/<package>` is itself a symlink (leading `l`), Stow folded the directory. Several packages
+require `--no-folding` (`zsh`, `alacritty`, `herdr`, `git`, `bat`, `eza`, `claude`).
+
+Check:
+
+```bash
+ls -ld ~/.config/<package>    # leading "l" = folded symlink
+```
+
+Fix — unstow, recreate as a real directory, re-stow with `--no-folding`:
+
+⚠️  MANUAL STEP — review each command before running
+
+```bash
+stow --dir=stow/common --target="$HOME" --delete <package>
+mkdir -p ~/.config/<package>
+stow --dir=stow/common --target="$HOME" --no-folding <package>
+test ! -L "$HOME/.config/<package>" && echo "OK: real directory"
+```
+
+## Broken or wrong symlinks
+
+Confirm a symlink resolves back into the repository:
+
+```bash
+readlink ~/.config/<package>/<file>
+```
+
+If it points somewhere unexpected or is dangling, unstow and re-stow the package (dry-run first).
+
+## Missing dependencies / `command not found`
+
+Most tools are optional and guarded — the shell starts cleanly without them, and an alias simply won't
+exist. Check what's present:
+
+```bash
+task check            # core: stow, git, task
+task deps:check:zsh   # shell tools
+task deps:check:nvim  # editor tools
+```
+
+Install what's missing using the commands on the [Shell Dependencies](shell-dependencies.md) and
+[Installation](../installation.md) pages. Nothing installs automatically.
+
+## Shell not loading the managed config
+
+The zsh package never touches `~/.zshrc`; you add one guarded include block yourself. Preview what the
+bootstrap would add:
+
+```bash
+task zsh:bootstrap:dry-run
+```
+
+Apply it (idempotent, creates a timestamped backup):
+
+⚠️  MANUAL STEP — review the dry-run output first
+
+```bash
+task zsh:bootstrap
+```
+
+Then start a new shell. See [Shell](../features/shell.md).
+
+## Git config not applied
+
+Confirm the managed includes are wired into `~/.gitconfig`:
+
+```bash
+git config --global --get-all include.path   # expect the two managed paths
+git config --global core.excludesfile        # expect ~/.config/git/ignore
+```
+
+If empty, run the bootstrap (preview first):
+
+```bash
+task git:bootstrap:dry-run
+```
+
+⚠️  MANUAL STEP — review the dry-run output first
+
+```bash
+task git:bootstrap
+```
+
+See [Git](../features/git.md).
+
+## Icons or fonts not rendering
+
+OS glyphs, git symbols, and eza icons need a **Nerd Font** in your terminal. If the Oh My Posh prompt
+renders its glyphs, the Claude status line and `eza` icons will too. Set your terminal font to a Nerd
+Font and restart it.
+
+## bat theme not applied
+
+bat reads themes from a compiled cache — build it once after stowing:
+
+```bash
+bat cache --build
+bat --list-themes | grep "Catppuccin Macchiato"
+```
+
+## eza colors look default
+
+Usually `EZA_CONFIG_DIR` points away from `~/.config/eza`. Check:
+
+```bash
+echo "$EZA_CONFIG_DIR"
+readlink ~/.config/eza/theme.yml
+```
+
+If the variable is set, eza reads `theme.yml` from there instead — unset it or point it at
+`~/.config/eza`.
+
+## MkDocs local preview issues
+
+To preview this site locally without installing anything, serve it via Docker from the repository root:
+
+```bash
+docker run --rm -it -p 8000:8000 -v "$PWD":/docs squidfunk/mkdocs-material serve --dev-addr=0.0.0.0:8000
+```
+
+Open <http://localhost:8000>. The `--dev-addr=0.0.0.0:8000` binding is required so the container is
+reachable from the host.
+
+## Related
+
+- [GNU Stow Workflow](stow.md) · [Shell Dependencies](shell-dependencies.md) · [Installation](../installation.md) · [Taskfile](../usage/taskfile.md)
diff --git a/website/screenshots.md b/website/screenshots.md
new file mode 100644
index 0000000..c1a183c
--- /dev/null
+++ b/website/screenshots.md
@@ -0,0 +1,33 @@
+# Screenshots
+
+A look at the setup in use. The same images appear in context on the relevant feature and reference
+pages; this page collects them in one place.
+
+## Gallery
+
+![Oh My Posh prompt with an active Git segment](assets/images/terminal-prompt.png)
+*Shell prompt with Git context and Catppuccin Macchiato colors.*
+
+![eza directory listing with icons and Catppuccin Blue colors](assets/images/eza-listing.png)
+*Icon-aware project listing powered by eza.*
+
+![bat showing a syntax-highlighted file in the Macchiato theme](assets/images/bat-output.png)
+*Syntax-highlighted file preview with bat.*
+
+![Neovim editing a file with the Catppuccin Macchiato colorscheme](assets/images/nvim-editor.png)
+*Neovim editing inside the dotfiles repository.*
+
+![Claude Code status line showing OS, model, path, git, and context segments](assets/images/claude-statusline.png)
+*Claude Code status line integrated into the terminal workflow.*
+
+![Herdr multiplexer session with panes and agent labels](assets/images/herdr-session.png)
+*Herdr session layout for agent-oriented terminal work.*
+
+![Output of a stow --simulate dry-run listing the links it would create](assets/images/stow-dryrun.png)
+*GNU Stow simulation before applying a package.*
+
+![The task list printed by running task in the repository](assets/images/task-list.png)
+*Taskfile entrypoint listing safe checks, dry-runs, and maintenance commands.*
+
+![Tree view of the stow directory showing one folder per package](assets/images/repo-tree.png)
+*Package-based repository layout under stow/.*
diff --git a/website/usage/aliases.md b/website/usage/aliases.md
new file mode 100644
index 0000000..51c3be0
--- /dev/null
+++ b/website/usage/aliases.md
@@ -0,0 +1,85 @@
+# Aliases
+
+The aliases below come from the actual config in `stow/common/zsh/` (and the per-OS layers). Tool-backed
+aliases are guarded with `command -v` — if the tool isn't installed, the alias falls back or is skipped.
+
+## Listing and files
+
+Defined in `aliases.zsh`. When `eza` is installed:
+
+| Alias | Expands to |
+|---|---|
+| `ls` | `eza --icons --long` |
+| `ll` | `eza --icons --all --long` |
+| `tree` | `eza --icons --tree` |
+
+Without `eza`, `ll` falls back to `ls -ahl`.
+
+## Safety overrides
+
+These add confirmation/verbosity so destructive commands are less surprising:
+
+| Alias | Expands to |
+|---|---|
+| `grep` | `grep --color=auto` |
+| `cp` | `cp -iv` |
+| `rm` | `rm -i` |
+| `mv` | `mv -iv` |
+
+## File viewing (bat)
+
+When `bat` is installed:
+
+| Alias | Effect |
+|---|---|
+| `cat` | `bat` |
+| `*.md` / `*.txt` / `*.log` | suffix aliases — run the file through `bat` |
+
+Suffix aliases mean typing `./notes.md` opens it in `bat`.
+
+## Navigation
+
+`cd` is replaced by [zoxide](https://github.com/ajeetdsouza/zoxide) via `zoxide init --cmd cd zsh` in
+`tools.zsh`, so `cd <partial-name>` jumps to frequently used directories.
+
+## System / package management (Arch)
+
+From `arch.zsh` (sourced only on Arch / EndeavourOS):
+
+| Alias | Expands to |
+|---|---|
+| `aur` | `yay` or `paru` (whichever is installed) |
+| `sc` | `systemctl` |
+| `scu` | `systemctl --user` |
+| `pacs` | `pacman -Ss` (search) |
+| `paci` | `sudo pacman -S` (install) |
+| `pacu` | `sudo pacman -Syu` (upgrade) |
+
+## macOS
+
+From `macos.zsh`:
+
+| Alias | Expands to |
+|---|---|
+| `o` | `open` |
+
+## Git aliases
+
+The Git package defines a large set of short aliases in `stow/common/git/.config/git/aliases`. A few
+high-traffic ones:
+
+| Alias | Expands to |
+|---|---|
+| `git s` | `status` |
+| `git a` | `add --all` |
+| `git cm` | `commit -m` |
+| `git cam` | `commit -am` |
+| `git ps` | `push` |
+| `git pl` | `pull` |
+| `git lg` | `log --oneline --graph --decorate` |
+| `git b` | `branch` |
+| `git o` | `checkout` |
+
+!!! info "Full list in the repo"
+    There are many more (diff, rebase, stash, remote, and helper shortcuts). See the complete file at
+    `stow/common/git/.config/git/aliases` in the repository.
diff --git a/website/usage/daily-workflow.md b/website/usage/daily-workflow.md
new file mode 100644
index 0000000..94c90e8
--- /dev/null
+++ b/website/usage/daily-workflow.md
@@ -0,0 +1,69 @@
+# Daily Workflow
+
+A sketch of how the pieces fit together in normal use. This is *a* workflow, not a required one — take
+the parts that suit you.
+
+## Open a terminal
+
+Alacritty starts with `zsh` and the Oh My Posh prompt, which shows the current path and Git status. If
+you use Herdr, panes inherit the working directory of the active pane, so new panes open where you are.
+
+## Navigate
+
+`cd` is backed by [zoxide](https://github.com/ajeetdsouza/zoxide) (initialised as `cd` in `tools.zsh`), so it
+learns the directories you visit and lets you jump by partial name:
+
+```bash
+cd dotfiles      # jumps to a known path matching "dotfiles"
+```
+
+Changing directory automatically lists its contents — the `chpwd` hook runs `ll` after every `cd` (see
+[Functions](functions.md)).
+
+## List files
+
+With `eza` installed, listing is colorised and icon-aware:
+
+```bash
+ls       # eza --icons --long
+ll       # eza --icons --all --long
+tree     # eza --icons --tree
+```
+
+See [Aliases](aliases.md) for the full set and the `ls` fallback when `eza` is absent.
+
+## Work with Git
+
+The Git package ships a large set of short aliases. Common ones in a normal cycle:
+
+```bash
+git s      # status
+git a      # add --all
+git cm "message"   # commit -m
+git ps     # push
+git lg     # log --oneline --graph --decorate
+```
+
+The full alias list is on the [Aliases](aliases.md) page. Identity and includes are wired once during
+setup — see [Git](../features/git.md).
+
+## Run repository tasks
+
+Inside the dotfiles repo, `task` is the entrypoint for listing packages, dry-running Stow, and checking
+dependencies:
+
+```bash
+task             # list available tasks
+task list        # list Stow packages
+task deps:check:zsh   # check shell-tier tools
+```
+
+Safe (read-only) tasks versus system-modifying ones are spelled out on the [Taskfile](taskfile.md) page.
+
+With the optional plugins installed, `<Tab>` completion is fzf-backed and context-aware — `task <Tab>`
+lists tasks with descriptions, `herdr <Tab>` lists session names, and file/directory completions show
+`eza` / `bat` previews. See [Completions](../features/shell.md#completions).
+
+!!! warning "Tested on macOS + Arch only"
+    These conveniences are tested on macOS (primary) and EndeavourOS / Arch Linux. Elsewhere, treat them
+    as a reference and adapt.
diff --git a/website/usage/functions.md b/website/usage/functions.md
new file mode 100644
index 0000000..547b874
--- /dev/null
+++ b/website/usage/functions.md
@@ -0,0 +1,35 @@
+# Functions
+
+The shell config defines only a few functions. They're small and live in `stow/common/zsh/`. This page
+covers the ones useful in daily work — the rest are internal plumbing and are intentionally not
+highlighted.
+
+## `sizeof`
+
+From `aliases.zsh`. Prints the size of each entry in the current directory:
+
+```bash
+sizeof
+```
+
+Implementation is `du -sh ./*` — a quick "what's taking space here?" for the current folder.
+
+## `chpwd` (automatic listing on `cd`)
+
+Also in `aliases.zsh`. `chpwd` is a Zsh hook that runs whenever the working directory changes; here it
+runs `ll`, so every `cd` immediately lists the new directory. You don't call it directly — it fires on
+navigation.
+
+## Internal helpers (not for direct use)
+
+These exist for the config's own wiring and aren't meant to be called by hand:
+
+| Function | File | Role |
+|---|---|---|
+| `path_prepend` / `path_append` | `path.zsh` | Add directories to `PATH` safely during shell init |
+| `_herdr` / `_herdr_sessions` | `herdr.zsh` | Zsh completion plumbing for Herdr session names |
+
+!!! note "Deliberately minimal"
+    The setup leans on aliases and tool integrations rather than a large library of custom functions.
+    Anything more personal or machine-specific belongs in your own untracked `~/.config/zsh/local.zsh`
+    (see [Shell](../features/shell.md)).
diff --git a/website/usage/index.md b/website/usage/index.md
new file mode 100644
index 0000000..378c368
--- /dev/null
+++ b/website/usage/index.md
@@ -0,0 +1,15 @@
+# Usage
+
+This section is about **using** the setup day to day — once the packages you want are installed. For
+getting things onto a machine, see [Installation](../installation.md); this section assumes that's done.
+
+| Page | What it covers |
+|---|---|
+| [Daily Workflow](daily-workflow.md) | A typical terminal session with the shell, Git, and task helpers |
+| [Aliases](aliases.md) | The shell aliases the config defines, grouped by purpose |
+| [Functions](functions.md) | The shell functions worth knowing about |
+| [Taskfile](taskfile.md) | The `task` command entrypoint — safe vs. system-modifying tasks |
+
+!!! note "Take what fits"
+    None of this is mandatory. The aliases and helpers are conveniences — adopt the ones that match how
+    you already work and ignore the rest.
diff --git a/website/usage/taskfile.md b/website/usage/taskfile.md
new file mode 100644
index 0000000..2a6bcd7
--- /dev/null
+++ b/website/usage/taskfile.md
@@ -0,0 +1,65 @@
+# Taskfile
+
+The repository uses [go-task](https://taskfile.dev/) as its command entrypoint. `Taskfile.yml` wraps the
+common operations — listing packages, dry-running Stow, checking dependencies, bootstrapping config, and
+OS maintenance — so you run short, consistent commands instead of remembering flags.
+
+![The task list printed by running task in the repository](../assets/images/task-list.png)
+*Taskfile entrypoint listing safe checks, dry-runs, and maintenance commands.*
+
+## Discovering tasks
+
+```bash
+task          # list all available tasks (the default task)
+```
+
+!!! info "`task` vs `task list`"
+    `task` (the default) lists **tasks**. `task list` lists **Stow packages** as `<area>/<package>`, for
+    use with `task dry-run`. They're different — don't confuse them.
+
+## Safe, read-only tasks
+
+These never modify your system — they inspect, check, or print:
+
+| Task | What it does |
+|---|---|
+| `task` | List all available tasks |
+| `task detect` | Print detected OS (`macos` or `arch`) |
+| `task check` | Verify prerequisites (`stow`, `git`, `task`) are installed |
+| `task list` | List Stow packages |
+| `task dry-run AREA=<area> PACKAGE=<name>` | Dry-run a Stow package (simulation, no changes) |
+| `task deps:check:zsh` | Check zsh shell-tier deps (fzf, zoxide, eza, bat, oh-my-posh, zinit) |
+| `task deps:check:nvim` | Check Neovim-tier deps (nvim, tree-sitter, rg, fd, node) |
+| `task deps:brew` | Print macOS / Homebrew install commands (prints only) |
+| `task deps:arch` | Print Arch / EndeavourOS install commands (prints only) |
+| `task clean` | Report what OS cleanup *would* remove — dry-run, deletes nothing |
+| `task git:bootstrap:dry-run` | Show include entries that *would* be added to `~/.gitconfig` |
+| `task zsh:bootstrap:dry-run` | Show what `zsh:bootstrap` *would* do to `~/.zshrc` |
+
+Example dry-run:
+
+```bash
+task dry-run AREA=common PACKAGE=git
+```
+
+## System-modifying tasks
+
+These change your system or home config. Each is marked **MANUAL USE ONLY** in the Taskfile and creates a
+backup where it edits an existing file. Run the matching dry-run first.
+
+| Task | What it does |
+|---|---|
+| `task update` | Sync + upgrade packages (Arch: yay/pacman, macOS: brew) — interactive |
+| `task clean:apply` | Perform OS cleanup — **destructive** (orphans, cache, journal); re-prints report first |
+| `task git:bootstrap` | Wire `~/.gitconfig` to managed Git config — idempotent, timestamped backup |
+| `task zsh:bootstrap` | Wire `~/.zshrc` to the managed zsh layer — idempotent, timestamped backup |
+
+⚠️  MANUAL STEP — review the matching dry-run output before running any task in this table
+
+!!! note "Nothing installs automatically"
+    Even the `deps:*` tasks only check or print commands — no task in this repository installs software or
+    runs Stow on its own. Installation and stowing are always your own deliberate steps.
+
+## Related
+
+- [Installation](../installation.md) · [GNU Stow Workflow](../reference/stow.md) · [Shell Dependencies](../reference/shell-dependencies.md)