flow/docs/flows.md

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