refactor-1

docs/flows.md

@@ -0,0 +1,86 @@
+## Feature Inventory
+
+### Core Features
+
+- `enter`
+  - SSH into a named environment target with optional tmux auto-attach
+- `dev`
+  - create, exec into, attach to, list, stop, remove, and respawn development containers
+- `dotfiles`
+  - clone the dotfiles repo, link/unlink/relink configs, undo link transactions, inspect status, sync modules, clean broken links, edit packages, and interact with repo state
+- `bootstrap`
+  - run machine bootstrap profiles with packages, env validation, hostname/locale/shell setup, ssh-keygen, `runcmd`, config linking, and post-link hooks
+- `package`
+  - install/list/remove binary packages defined in the manifest
+- `sync`
+  - inspect git project health, fetch remotes, and summarize project state
+- `completion`
+  - dynamic zsh completion generation and installation
+
+### Supported Flows
+
+#### Access a host
+
+1. Resolve `[user@]namespace@platform`
+2. Expand platform host template or configured target override
+3. Optionally warn about missing remote terminfo
+4. Open SSH, optionally into tmux
+
+#### Start a dev container
+
+1. Resolve runtime (`docker` or `podman`)
+2. Normalize image shorthand
+3. Apply labels and common host mounts
+4. Start the container
+5. `flow dev connect` attaches through tmux or falls back to direct exec
+
+#### Manage dotfiles
+
+1. Clone dotfiles repo
+2. Optionally sync external module repos
+3. Resolve shared + profile packages
+4. Validate target conflicts
+5. Snapshot replaced targets
+6. Apply links transactionally
+7. Undo from persisted transaction state if needed
+
+#### Bootstrap a machine
+
+1. Load and validate a profile
+2. Detect or select the package manager
+3. Check required environment variables
+4. Apply hostname/locale/shell prerequisites
+5. Install profile packages
+6. Run package hooks
+7. Generate SSH keys
+8. Run `runcmd`
+9. Link dotfiles for the profile
+10. Run post-link hooks
+
+### Command Surface Review
+
+### Keep
+
+- `enter`
+- `dev`
+- `dotfiles`
+- `bootstrap`
+- `package`
+- `sync`
+- `completion`
+
+### Keep But Treat As Convenience Aliases
+
+- `dotfiles sync`
+  - effectively `repo pull` + `modules sync`
+- `dotfiles relink`
+  - effectively `unlink` + `link`
+- `sync summary`
+  - effectively `sync check --no-fetch`
+
+### Commands That Need Follow-Up Product Decisions
+
+- `package remove`
+  - today it forgets install state but does not uninstall files; either rename it to `forget` or implement real uninstall semantics
+- `dotfiles edit`
+  - current auto-commit/push behavior is powerful but risky; it may deserve an explicit confirm-or-dry-run mode before wider use