update

example/README.md

@@ -1,34 +1,41 @@
-# Example Dotfiles Repository
+# Flow Example
 
-`example/dotfiles-repo` is a complete fixture for the current flow schema. It
-contains shared dotfiles, profile-specific dotfiles, package definitions, setup
-profiles, root-targeted files, templates, and shell hooks.
+`example/` is a single complete fixture for the current flow schema. It contains
+one dotfiles repository plus one local module repository, showcasing shared
+dotfiles, profile-specific dotfiles, package definitions, setup profiles,
+root-targeted files, external modules, templates, and shell hooks.
 
 ## Layout
 
 ```text
-dotfiles-repo/
-  _shared/
-    bin/.local/bin/flow-hello
-    flow/.config/flow/config.yaml
-    flow/.config/flow/packages.yaml
-    flow/.config/flow/profiles.yaml
-    git/.gitconfig
-    nvim/.config/nvim/init.lua
-    system/_root/etc/hostname
-    system/_root/usr/local/bin/custom-script.sh
-    tmux/.tmux.conf
-    zsh/.zshrc
-  linux-auto/
-    ssh/.ssh/config
-  macos-dev/
-    ghostty/.config/ghostty/config
+example/
+  dotfiles-repo/
+    _shared/
+      _root/etc/hostname
+      _root/usr/local/bin/custom-script.sh
+      bin/.local/bin/flow-hello
+      flow/.config/flow/config.yaml
+      flow/.config/flow/packages.yaml
+      flow/.config/flow/profiles.yaml
+      git/.gitconfig
+      nvim/.config/nvim/_module.yaml
+      tmux/.tmux.conf
+      zsh/.zshrc
+    linux-auto/
+      ssh/.ssh/config
+    macos-dev/
+      ghostty/.config/ghostty/config
+  module-repos/
+    nvim-config/
+      init.lua
+      lua/plugins.lua
 ```
 
 The fixture demonstrates:
 
 - `_shared/` plus profile-specific layers
 - `_root/` absolute-path planning for sudo-backed links
+- `_module.yaml` external module planning with a local module repository
 - flow config and manifest overlay under `_shared/flow/.config/flow`
 - package-manager, cask, and binary package definitions
 - profile package shorthand and object overrides
@@ -45,11 +52,21 @@ repo:
 DEMO="$(mktemp -d)"
 mkdir -p "$DEMO/home"
 cp -a example/dotfiles-repo "$DEMO/dotfiles-src"
+cp -a example/module-repos "$DEMO/module-repos"
+
+git -C "$DEMO/module-repos/nvim-config" init -q -b main
+git -C "$DEMO/module-repos/nvim-config" config user.email e2e@example.com
+git -C "$DEMO/module-repos/nvim-config" config user.name "flow example"
+git -C "$DEMO/module-repos/nvim-config" add -A
+git -C "$DEMO/module-repos/nvim-config" commit -q -m initial
+
 git -C "$DEMO/dotfiles-src" init -q -b main
 git -C "$DEMO/dotfiles-src" config user.email e2e@example.com
 git -C "$DEMO/dotfiles-src" config user.name "flow example"
 git -C "$DEMO/dotfiles-src" add -A
 git -C "$DEMO/dotfiles-src" commit -q -m initial
+
+cd "$DEMO"
 ```
 
 Run flow against that sandbox:
@@ -65,16 +82,16 @@ HOME="$DEMO/home" \
 XDG_CONFIG_HOME="$DEMO/config" \
 XDG_DATA_HOME="$DEMO/data" \
 XDG_STATE_HOME="$DEMO/state" \
-uv run flow dotfiles link --profile linux-auto --skip system --dry-run
+uv run flow dotfiles link --profile linux-auto --skip _root --dry-run
 
 HOME="$DEMO/home" \
 XDG_CONFIG_HOME="$DEMO/config" \
 XDG_DATA_HOME="$DEMO/data" \
 XDG_STATE_HOME="$DEMO/state" \
-uv run flow dotfiles link --profile linux-auto --skip system
+uv run flow dotfiles link --profile linux-auto --skip _root
 ```
 
-`--skip system` avoids `_root/` paths such as `/etc/hostname` during the demo.
+`--skip _root` avoids root-targeted paths such as `/etc/hostname` during the demo.
 
 Useful follow-up commands:
 
@@ -94,16 +111,17 @@ rm -rf "$DEMO"
 
 ## External Modules
 
-A package directory may mount a separate git repo by adding `_module.yaml` at
-the package root:
+A package directory may mount a separate git repo by adding `_module.yaml`
+under the desired mount path:
 
 ```yaml
-source: github:your-org/nvim-config
+source: module-repos/nvim-config
 ref:
   branch: main
 ```
 
-This fixture does not include a real module because that would make the example
-depend on an external network repo. After adding one, `flow dotfiles repos pull`
-clones or updates the module cache, and `flow dotfiles link` links from that
-cache.
+The example nvim package mounts `example/module-repos/nvim-config` at
+`.config/nvim`. Flow implements modules through `_module.yaml`; it does not
+implement a top-level `_modules/` dotfiles layout convention. `flow dotfiles
+repos pull` clones or updates module caches, and `flow dotfiles link` links
+from those caches.

example/dotfiles-repo/_shared/nvim/.config/nvim/_module.yaml

@@ -0,0 +1,3 @@
+source: module-repos/nvim-config
+ref:
+  branch: main

example/dotfiles-repo/_shared/nvim/.config/nvim/init.lua

@@ -1,6 +0,0 @@
-vim.opt.number = true
-vim.opt.relativenumber = true
-vim.opt.expandtab = true
-vim.opt.shiftwidth = 2
-
-vim.g.mapleader = " "

example/module-repos/nvim-config/init.lua

@@ -0,0 +1 @@
+vim.opt.number = true

example/module-repos/nvim-config/lua/plugins.lua

@@ -0,0 +1 @@
+return {}