From f4adee1e537c9b7733f1dfb6130b7c8bb775f8b9 Mon Sep 17 00:00:00 2001
From: fullstackjam <fullstackjam@outlook.com>
Date: Tue, 2 Jun 2026 23:29:19 +0800
Subject: [PATCH] docs: update dotfiles linking doc to reflect Makefile-first
 priority

OpenBoot now runs `make install` when the dotfiles repo has a Makefile
with an `install:` target, before falling back to stow or direct
symlinks. Update the Linking Methods section to document the priority
order and add Option A (Makefile) alongside the existing stow example.
---
 src/docs/dotfiles-shell.md | 31 +++++++++++++++++++++++++++----
 1 file changed, 27 insertions(+), 4 deletions(-)

diff --git a/src/docs/dotfiles-shell.md b/src/docs/dotfiles-shell.md
index 6f98740..f7a8aaa 100644
--- a/src/docs/dotfiles-shell.md
+++ b/src/docs/dotfiles-shell.md
@@ -1,6 +1,6 @@
 ---
 title: Dotfiles & Shell
-description: Automatic Oh-My-Zsh setup, dotfiles linking with GNU Stow, and developer-friendly macOS preferences.
+description: Automatic Oh-My-Zsh setup, dotfiles linking via Makefile or GNU Stow, and developer-friendly macOS preferences.
 group: Features
 order: 6
 ---
@@ -39,7 +39,19 @@ If you keep your config files in a Git repo (`.zshrc`, `.gitconfig`, `.vimrc`, e
 
 1. Set a **dotfiles repo URL** in your config (via the dashboard or config JSON)
 2. During install, OpenBoot clones the repo to `~/.dotfiles`
-3. Files are symlinked into your home directory using [GNU Stow](https://www.gnu.org/software/stow/)
+3. Files are symlinked into your home directory — OpenBoot detects the linking method automatically
+
+### Linking Methods
+
+OpenBoot tries three methods in order, using the first one that applies:
+
+| Priority | Condition | What happens |
+|----------|-----------|-------------|
+| 1 | `Makefile` with an `install:` target | Runs `make install` in `~/.dotfiles` |
+| 2 | Top-level subdirectories (stow packages) | Links each package with [GNU Stow](https://www.gnu.org/software/stow/) |
+| 3 | Flat file structure | Symlinks files directly into `$HOME` |
+
+This lets your dotfiles repo own its own deployment logic — directory pre-creation, custom stow flags, or any other setup — without requiring OpenBoot to know repo-specific details.
 
 ### Dotfiles Modes
 
@@ -48,7 +60,7 @@ Control how OpenBoot handles dotfiles with the `--dotfiles` flag:
 | Mode | What it does |
 |------|-------------|
 | `clone` | Clone the repo to `~/.dotfiles` |
-| `link` | Clone and symlink with `stow` |
+| `link` | Clone and link using the detected method above |
 | `skip` | Don't touch dotfiles |
 
 ```
@@ -58,7 +70,18 @@ openboot install --dotfiles skip
 
 ### Setting Up Your Dotfiles Repo
 
-Don't have a dotfiles repo yet? Here's the minimum structure that works with `stow`:
+**Option A — Makefile (recommended for custom setups)**
+
+Add a `Makefile` with an `install:` target. OpenBoot runs `make install`, so your repo controls everything:
+
+```makefile
+install:
+	stow -v --target="$(HOME)" git zsh vim
+```
+
+**Option B — Stow packages**
+
+Structure your repo so each top-level directory is a stow package. OpenBoot calls `stow` on each one automatically:
 
 ```
 ~/.dotfiles/