example

README.md

@@ -39,6 +39,9 @@ This installs `flow` to `~/.local/bin/flow`.
 Files are read alphabetically (`*.yaml` and `*.yml`) and merged at top level.
 If the same top-level key appears in multiple files, the later filename wins.
 
+`repository.pull-before-edit` controls whether `flow dotfiles edit` runs `git pull --rebase` first (default: `true`).
+When pull brings new changes, flow shows an info message and waits for Enter before opening the editor.
+
 ### Dotfiles layout (flat with reserved dirs)
 
 Inside your dotfiles repo root:
@@ -50,21 +53,35 @@ _shared/
       config.yaml
       packages.yaml
       profiles.yaml
+  dnsmasq/
+    .user_hosts
+    _root/
+      opt/homebrew/etc/dnsmasq.conf
   git/
     .gitconfig
-_root/
-  general/
-    etc/
-      hostname
 linux-auto/
   nvim/
     .config/nvim/init.lua
 ```
 
 - `_shared/`: linked for all profiles
-- `_root/`: linked to absolute paths (via sudo), e.g. `_root/etc/hostname -> /etc/hostname`
+- `_root/` is a marker inside a package for absolute paths (via sudo), e.g. `dnsmasq/_root/etc/hostname -> /etc/hostname`
 - every other directory at this level is a profile name
-- when `_shared` and profile conflict on the same target file, profile wins
+- any target conflict fails (including `_shared` vs profile)
+
+### External module packages
+
+Packages can be backed by an external git repository using `_module.yaml`:
+
+```yaml
+source: github:org/nvim-config
+ref:
+  branch: main
+```
+
+- If a package directory contains `_module.yaml`, flow uses the fetched module content as package source.
+- Any sibling files in that package directory are ignored (shown only in `--verbose`).
+- Modules are refreshed on `flow dotfiles init` and `flow dotfiles sync` (not on `link`).
 
 ## Manifest model
 
@@ -144,7 +161,7 @@ profiles:
 - `requires` validation for required env vars
 - `ssh-keygen` definitions
 - `runcmd` (runs after package installation)
-- automatic config linking (`_shared` + profile + `_root`)
+- automatic config linking (`_shared` + profile, including package-local `_root` markers)
 - `post-link` hook (runs after symlink phase)
 - config skip patterns:
   - package names (e.g. `nvim`)
@@ -161,6 +178,8 @@ flow dev create api -i tm0/node -p ~/projects/api
 flow dotfiles init --repo git@github.com:you/dotfiles.git
 flow dotfiles link --profile linux-auto
 flow dotfiles status
+flow dotfiles modules list
+flow dotfiles modules sync
 
 flow bootstrap list
 flow bootstrap show linux-auto