update

README.md

@@ -6,7 +6,32 @@ completion.
 
 ## Quick Start
 
-From the repository:
+Install from a release tarball (no `uv`, no `pipx`):
+
+```bash
+VERSION=0.1.0
+REPO=OWNER/REPO
+
+curl -fsSL "https://github.com/${REPO}/releases/download/v${VERSION}/flow-${VERSION}-python.tar.gz" \
+  -o "/tmp/flow-${VERSION}-python.tar.gz"
+curl -fsSL "https://github.com/${REPO}/releases/download/v${VERSION}/flow-${VERSION}-python.tar.gz.sha256" \
+  -o "/tmp/flow-${VERSION}-python.tar.gz.sha256"
+sha256sum -c "/tmp/flow-${VERSION}-python.tar.gz.sha256"
+tar -xzf "/tmp/flow-${VERSION}-python.tar.gz" -C /tmp
+/tmp/flow-${VERSION}-python/install.sh
+```
+
+Alternative one-shot path with `curl` and shell:
+
+```bash
+tmpdir="$(mktemp -d)"
+trap 'rm -rf "$tmpdir"' EXIT
+curl -fsSL "https://github.com/${REPO}/releases/download/v${VERSION}/flow-${VERSION}-python.tar.gz" \
+  | tar -xz -C "$tmpdir"
+sh "${tmpdir}/flow-${VERSION}-python/install.sh"
+```
+
+From the repository (development):
 
 ```bash
 uv sync --locked --extra dev --extra build
@@ -23,13 +48,6 @@ flow setup show linux-work
 flow setup run linux-work --dry-run
 ```
 
-Install the CLI as a local uv tool:
-
-```bash
-uv tool install --force .
-flow --help
-```
-
 Build a standalone binary:
 
 ```bash
@@ -39,8 +57,42 @@ make install    # installs dist/flow to ~/.local/bin/flow
 ```
 
 `build/`, `dist/`, and `flow.spec` are generated by packaging/binary builds and
-are ignored. `.venv/` is the uv-managed local environment. `venv/` is legacy
-local clutter and should not be used.
+are ignored. `.venv/` and `venv/` are local virtual environments and are also
+ignored.
+
+## Distribution
+
+The primary release artifact is a Python tarball published from GitHub Releases:
+
+```text
+flow-<version>-python.tar.gz
+flow-<version>-python.tar.gz.sha256
+```
+
+The tarball includes `install.sh` plus the `flow` wheel. End users need
+`python3` with `venv`; they do not need `uv` or `pipx`. The installer uses
+`pip` inside the isolated venv to install `flow` and resolve Python
+dependencies.
+
+Default install locations:
+
+- app environment: `~/.local/share/flow/venv`
+- command shim: `~/.local/bin/flow`
+
+Overrides:
+
+```bash
+PYTHON=/path/to/python3 FLOW_INSTALL_ROOT=~/.flow FLOW_BIN_DIR=~/bin ./install.sh
+```
+
+Release build:
+
+```bash
+make release-package
+```
+
+Native one-file binaries remain optional convenience artifacts. They are
+platform-specific; the Python release tarball is the portable default.
 
 ## Command Surface
 
@@ -71,7 +123,6 @@ flow setup run [PROFILE|--profile NAME] [--dry-run] [--var KEY=VALUE]
 # Remote targets
 flow remote list
 flow remote enter TARGET [--user USER] [--namespace NAME] [--platform NAME] [--session NAME] [--no-tmux] [--dry-run]
-flow enter TARGET
 
 # Dev containers
 flow dev create NAME --image IMAGE [--project PATH] [--dry-run]
@@ -87,7 +138,7 @@ flow dev list
 flow projects check [--fetch]
 flow projects fetch
 flow projects summary
-flow sync
+flow projects sync
 
 # Shell completion
 flow completion zsh
@@ -104,9 +155,8 @@ Aliases:
 - `dotfiles` -> `dot`
 - `dotfiles repos` -> `dotfiles repo`
 - `packages` -> `package`, `pkg`
-- `projects` -> `project`; `flow sync` -> `flow projects check --fetch`
+- `projects` -> `project`
 - `setup` -> `bootstrap`, `provision`
-- `remote enter` -> `enter`
 - `dev attach` -> `dev connect`
 - `dev remove` -> `dev rm`
 
@@ -240,6 +290,7 @@ make test          # unit tests, excluding e2e
 make test-e2e      # requires Docker or healthy Podman
 make check         # tests plus CLI smoke checks
 make package       # wheel and sdist in dist/
+make release-package # installable GitHub Release tarball
 make build         # PyInstaller binary in dist/flow
 make clean         # remove build/test artifacts
 make distclean     # also remove .venv/ and venv/