refactor-1

README.md

@@ -71,7 +71,14 @@ linux-auto/
 
 ### External module packages
 
-Packages can be backed by an external git repository using `_module.yaml`:
+Any directory inside a package can be backed by an external git repository using `_module.yaml`:
+
+```text
+_shared/
+  nvim/
+    .config/nvim/
+      _module.yaml
+```
 
 ```yaml
 source: github:org/nvim-config
@@ -79,8 +86,9 @@ 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`).
+- Flow mounts the module repo root at the directory containing `_module.yaml` (e.g. the example mounts into `~/.config/nvim/`).
+- Local files under that directory are ignored (shown only in `--verbose`).
+- Only one `_module.yaml` per package is supported.
 - Modules are refreshed on `flow dotfiles init` and `flow dotfiles sync` (not on `link`).
 
 ## Manifest model