wip

README.md

@@ -1,16 +1,15 @@
 # flow
 
-`flow` is a CLI for managing development instances, containers, dotfiles,
-bootstrap profiles, and binary packages.
+`flow` is a CLI for managing development instances, containers, dotfiles, bootstrap profiles, and
+binary packages.
 
-This repository contains the Python implementation of the tool and its command
-modules.
+This repository contains the Python implementation of the tool and its command modules.
 
 ## What is implemented
 
 - Instance access via `flow enter`
-- Container lifecycle commands under `flow dev` (`create`, `exec`, `connect`,
-  `list`, `stop`, `remove`, `respawn`)
+- Container lifecycle commands under `flow dev` (`create`, `exec`, `connect`, `list`, `stop`,
+  `remove`, `respawn`)
 - Dotfiles management (`dotfiles` / `dot`)
 - Bootstrap planning and execution (`bootstrap` / `setup` / `provision`)
 - Binary package installation from manifest definitions (`package` / `pkg`)
@@ -72,35 +71,35 @@ Example:
 
 ```yaml
 profiles:
-    linux-vm:
-        os: linux
-        hostname: "$HOSTNAME"
-        shell: zsh
-        locale: en_US.UTF-8
-        requires: [HOSTNAME]
-        packages:
-            standard: [git, tmux, zsh]
-            binary: [neovim]
-        ssh_keygen:
-            - type: ed25519
-              comment: "$USER@$HOSTNAME"
-        runcmd:
-            - mkdir -p ~/projects
+  linux-vm:
+    os: linux
+    hostname: "$HOSTNAME"
+    shell: zsh
+    locale: en_US.UTF-8
+    requires: [HOSTNAME]
+    packages:
+      standard: [git, tmux, zsh]
+      binary: [neovim]
+    ssh_keygen:
+      - type: ed25519
+        comment: "$USER@$HOSTNAME"
+    runcmd:
+      - mkdir -p ~/projects
 
 binaries:
-    neovim:
-        source: github:neovim/neovim
-        version: "0.10.4"
-        asset-pattern: "nvim-{{os}}-{{arch}}.tar.gz"
-        platform-map:
-            linux-amd64: { os: linux, arch: x86_64 }
-            linux-arm64: { os: linux, arch: arm64 }
-            macos-arm64: { os: macos, arch: arm64 }
-        install-script: |
-            curl -fL "{{downloadUrl}}" -o /tmp/nvim.tar.gz
-            tar -xzf /tmp/nvim.tar.gz -C /tmp
-            rm -rf ~/.local/bin/nvim
-            cp /tmp/nvim-*/bin/nvim ~/.local/bin/nvim
+  neovim:
+    source: github:neovim/neovim
+    version: "0.10.4"
+    asset-pattern: "nvim-{{os}}-{{arch}}.tar.gz"
+    platform-map:
+      linux-amd64: { os: linux, arch: x86_64 }
+      linux-arm64: { os: linux, arch: arm64 }
+      macos-arm64: { os: macos, arch: arm64 }
+    install-script: |
+      curl -fL "{{downloadUrl}}" -o /tmp/nvim.tar.gz
+      tar -xzf /tmp/nvim.tar.gz -C /tmp
+      rm -rf ~/.local/bin/nvim
+      cp /tmp/nvim-*/bin/nvim ~/.local/bin/nvim
 ```
 
 ## Command overview
@@ -113,6 +112,9 @@ flow enter root@personal@orb
 flow enter personal@orb --dry-run
 ```
 
+If your local terminal uses `xterm-ghostty` or `wezterm`, `flow enter` shows a terminfo warning and
+a manual fix command before connecting. `flow` never installs terminfo on the target automatically.
+
 ### Containers
 
 ```bash
@@ -184,14 +186,13 @@ Passing an explicit file path to internal loaders bypasses this cascade.
 
 ## State format policy
 
-`flow` currently supports only the v2 dotfiles link state format
-(`linked.json`). Older state formats are intentionally not supported.
+`flow` currently supports only the v2 dotfiles link state format (`linked.json`). Older state
+formats are intentionally not supported.
 
 ## CLI behavior
 
 - User errors return non-zero exit codes.
-- External command failures are surfaced as concise one-line errors (no
-  traceback spam).
+- External command failures are surfaced as concise one-line errors (no traceback spam).
 - `Ctrl+C` exits with code `130`.
 
 ## Zsh completion
@@ -216,9 +217,8 @@ fpath=(~/.zsh/completions $fpath)
 autoload -Uz compinit && compinit
 ```
 
-Completion is dynamic and pulls values from your current config/manifest/state
-(for example bootstrap profiles, package names, dotfiles packages, and
-configured `enter` targets).
+Completion is dynamic and pulls values from your current config/manifest/state (for example
+bootstrap profiles, package names, dotfiles packages, and configured `enter` targets).
 
 ## Development
 
@@ -236,22 +236,16 @@ Useful targets:
 make clean
 ```
 
-Run a syntax check:
-
-```bash
-python3 -m compileall .
-```
-
-Run tests (when `pytest` is available):
+Run tests:
 
 ```bash
 python3 -m pytest
 ```
 
-Optional local venv setup:
+Local development setup:
 
 ```bash
 python3 -m venv .venv
-.venv/bin/pip install -U pip pytest pyyaml
-PYTHONPATH=/path/to/src .venv/bin/pytest
+.venv/bin/pip install -e ".[dev]"
+.venv/bin/pytest
 ```