update

example/README.md

@@ -0,0 +1,78 @@
+# Example working scenario
+
+This folder contains a complete, practical dotfiles + bootstrap setup that exercises most `flow`
+features.
+
+## What this example shows
+
+- Dotfiles repository layout with `common/` packages and `profiles/work/` overrides
+- Self-hosted `flow` config + manifest in `common/flow/.config/flow/`
+- Bootstrap profiles for Linux (auto PM detection), Ubuntu (`apt`), Fedora (`dnf`), and macOS
+  (`brew`)
+- Bootstrap actions: `requires`, `hostname`, `locale`, `shell`, package install, binary install,
+  `ssh_keygen`, `configs`, and `runcmd`
+- Package name mapping via `package-map` (`apt`/`dnf`/`brew`)
+- Dotfiles repo workflows: `status`, `pull`, `push`, `sync --relink`, and `edit`
+
+## Layout
+
+- `dotfiles-repo/common/flow/.config/flow/config` example `flow` config
+- `dotfiles-repo/common/flow/.config/flow/manifest.yaml` profiles + package map + binaries
+- `dotfiles-repo/common/zsh/.zshrc`, `common/git/.gitconfig`, `common/tmux/.tmux.conf`
+- `dotfiles-repo/common/nvim/.config/nvim/init.lua`
+- `dotfiles-repo/common/bin/.local/bin/flow-hello`
+- `dotfiles-repo/profiles/work/git/.gitconfig` and `profiles/work/zsh/.zshrc` overrides
+
+## Quick start
+
+Use the absolute path to this local example repo:
+
+```bash
+EXAMPLE_REPO="/ABSOLUTE/PATH/TO/flow-cli/example/dotfiles-repo"
+```
+
+Initialize and link dotfiles:
+
+```bash
+flow dotfiles init --repo "$EXAMPLE_REPO"
+flow dotfiles link
+flow dotfiles status
+```
+
+Check repo commands:
+
+```bash
+flow dotfiles repo status
+flow dotfiles repo pull --relink
+flow dotfiles repo push
+```
+
+Edit package or file/path targets:
+
+```bash
+flow dotfiles edit zsh --no-commit
+flow dotfiles edit common/flow/.config/flow/manifest.yaml --no-commit
+```
+
+Inspect bootstrap profiles and package resolution:
+
+```bash
+flow bootstrap list
+flow bootstrap packages --resolved
+flow bootstrap packages --profile fedora-dev --resolved
+flow bootstrap show linux-auto
+```
+
+Run bootstrap in dry-run mode:
+
+```bash
+flow bootstrap run --profile linux-auto --var TARGET_HOSTNAME=devbox --var USER_EMAIL=you@example.com --dry-run
+flow bootstrap run --profile work-linux --var WORK_EMAIL=you@company.com --dry-run
+```
+
+## Manifest notes
+
+- `linux-auto` omits `package-manager` to demonstrate auto-detection.
+- `ubuntu-dev` uses legacy `packages.package` key to show compatibility.
+- `package-map` rewrites logical names like `fd` and `python-dev` per package manager.
+- If mapping is missing for the selected manager, `flow` uses the original package name and warns.