docs: refresh README

Author: alexeyu

README.md

@@ -5,13 +5,11 @@
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
 
 A headless, config-driven uploader that fans one batch of files out to many
-FTP, FTPS, and SFTP endpoints at once, concurrently, with retries and
-post-upload verification. Built for unattended automation (cron, CI,
-folder-watchers), not interactive use. A single static binary and one YAML file.
-
-You point it at some files and a list of endpoints; it uploads every file to
-every endpoint in parallel, verifies each transfer, retries transient
-failures, and exits non-zero if anything failed so a wrapping script can react.
+FTP, FTPS, and SFTP endpoints concurrently. You point it at files and a list of
+endpoints; it uploads every file to every endpoint in parallel, verifies each
+transfer, retries transient failures, and exits non-zero if anything failed so
+a wrapping script can react. Run it from cron, CI, or a folder-watcher: one
+static binary, one YAML file.
 
 ```console
 $ ramify ./batch --config stocks.yml
@@ -27,24 +25,22 @@ $ ramify ./batch --config stocks.yml
 
 - **One batch, many destinations.** Declare endpoints in YAML; add or remove
   one without touching code. Every endpoint uploads in its own goroutine.
-- **Three protocols, one model:** `ftp`, `ftps` (explicit AUTH TLS), and
-  `sftp` (password or private-key auth, host keys checked against
-  `~/.ssh/known_hosts`).
-- **Verification on by default.** Every upload's remote size is checked
-  against the local file to catch truncation. Disable with `--no-verify`.
+- **Three protocols:** `ftp`, `ftps` (explicit AUTH TLS), and `sftp` (password
+  or private-key auth, host keys from `~/.ssh/known_hosts`).
+- **Verification on by default.** After each upload ramify compares the remote
+  size against the local file to catch truncation. Disable with `--no-verify`.
 - **Retries with reconnect.** A fixed number of attempts per file with a
   fixed delay, each attempt reconnecting from scratch. Configurable globally
   and per endpoint.
 - **Fail-fast preflight** (`--dry-run`): connect, authenticate, and prove the
   target directory is writable with a self-deleting probe file, without
-  touching the files you are actually sending.
+  touching the files you are sending.
 - **Automation-friendly output:** quiet / default / verbose text, or
-  newline-delimited JSON (`--json`), with meaningful exit codes and errors
-  always on stderr even under `--quiet`.
+  newline-delimited JSON (`--json`), with meaningful exit codes and errors on
+  stderr even under `--quiet`.
 - **Secrets via env vars:** `${ENV_VAR}` interpolation in any config field,
   resolved at load time. Literal values still allowed.
-- **Zero runtime dependencies:** one static binary, no daemon, no config
-  server.
+- **Zero runtime dependencies:** one static binary, no daemon.
 
 ## Install
 
@@ -90,14 +86,14 @@ amd64 and arm64 are built for every release; each archive is listed in
    ```
 
 Positional arguments may be files or directories, mixed freely. Directories
-expand **non-recursively**: every regular file is included; subdirectories and
-dotfiles are skipped. Two inputs that would land under the same remote name
-(same basename) are rejected up front.
+expand **non-recursively**: ramify takes every regular file and skips
+subdirectories and dotfiles. Two inputs sharing a basename would land under the
+same remote name, so ramify rejects them up front.
 
 ## Configuration
 
 Config is a YAML file with a list of `endpoints` plus optional global policy
-defaults. Every policy key can be overridden per endpoint.
+defaults. Any endpoint can override any policy key.
 
 ```yaml
 endpoints:
@@ -125,7 +121,7 @@ endpoints:
 # Global policy defaults (each overridable per endpoint):
 attempts: 3                     # total tries per file
 retry_delay: 2s
-connect_timeout: 30s            # bounds the whole connect + login, not just the TCP dial
+connect_timeout: 30s            # bounds the whole connect + login, TCP dial included
 stall_timeout: 5m               # fail a transfer idle this long; 0 disables
 max_consecutive_connect_failures: 3   # write an endpoint off after this many connect failures in a row
 ```
@@ -140,29 +136,29 @@ max_consecutive_connect_failures: 3   # write an endpoint off after this many co
 | `port` | all | Optional; defaults to the protocol's standard port. |
 | `username` | all | Required. |
 | `password` | ftp, ftps, sftp | Required for ftp/ftps. For sftp, an alternative or complement to `private_key`. |
-| `private_key` | sftp | Path to an SSH private key (`~` expanded). If both this and `password` are set, the key wins and `password` is used only as its passphrase when the key is encrypted. |
+| `private_key` | sftp | Path to an SSH private key (`~` expanded). Set both this and `password` and the key wins; `password` then serves as the passphrase for an encrypted key. |
 | `overwrite` | all | `delete-first` (default) deletes any existing remote file first; `direct` uploads straight over it. |
 | `insecure_skip_verify` | ftps | Disables TLS certificate verification. For self-signed / test servers only; never use against a production endpoint. |
 
 ### Policy fields (global or per-endpoint)
 
 | Field | Default | Meaning |
 |---|---|---|
-| `attempts` | `3` | Total tries per file before it is counted as failed. |
+| `attempts` | `3` | Total tries per file before ramify counts it as failed. |
 | `retry_delay` | `2s` | Fixed wait between attempts (Go duration string). |
 | `connect_timeout` | `30s` | Bounds the entire connect + authenticate sequence. |
 | `stall_timeout` | `5m` | Fails a transfer that makes no forward progress for this long. `0` disables. |
-| `max_consecutive_connect_failures` | `3` | After this many connect failures in a row, the endpoint's remaining files are skipped as unreachable instead of each retrying. |
+| `max_consecutive_connect_failures` | `3` | After this many connect failures in a row, ramify skips the endpoint's remaining files as unreachable instead of retrying each one. |
 
 ### Secrets
 
-`${ENV_VAR}` interpolation works in any string field and is resolved when the
-config loads. A referenced variable that is unset is a load-time error, so a
-typo surfaces immediately instead of as a confusing auth failure mid-run.
+`${ENV_VAR}` interpolation works in any string field, resolved when the config
+loads. An unset variable is a load-time error, so you catch a typo before the
+run starts rather than as a confusing auth failure mid-run.
 
-Literal secrets are allowed but discouraged. Because a config file can hold
-plaintext credentials, `ramify` prints a warning if the file is readable by
-group or others; `chmod 600 stocks.yml` and keep it out of version control.
+Literal secrets work but invite leaks. `ramify` warns when the config file is
+readable by group or others; `chmod 600 stocks.yml` and keep it out of version
+control.
 
 ## Usage
 
@@ -182,7 +178,12 @@ ramify <path>... --config <file> [flags]
 | `--help` | Print usage and exit. |
 
 `--quiet` and `--verbose` are mutually exclusive. Flags and paths may appear in
-any order.
+any order. ramify treats everything after a bare `--` as a path, so you can
+upload a file whose name starts with `-`:
+
+```console
+$ ramify --config stocks.yml -- -weird-name.jpg
+```
 
 ### Output modes
 
@@ -192,9 +193,6 @@ any order.
 | default | per-file success + per-endpoint summary | errors |
 | `--verbose` | full event stream incl. byte-level progress | errors |
 
-Failure events always go to stderr, even under `--quiet`: an unattended job
-still needs to see what broke.
-
 ### JSON output
 
 `--json` reformats whatever the current verbosity level would print as one JSON
@@ -219,25 +217,25 @@ $ ramify ./batch --config stocks.yml --json
 
 ## How it works
 
-- **Concurrency.** One goroutine per endpoint, fully parallel. Within an
-  endpoint, files upload sequentially over a single reused connection (connect
-  once, upload all, disconnect), which amortizes login cost and respects
-  servers that cap concurrent connections.
+- **Concurrency.** One goroutine per endpoint. Within an endpoint, files upload
+  sequentially over a single reused connection (connect once, upload all,
+  disconnect), which amortizes the login cost and keeps ramify inside server
+  limits on concurrent connections.
 - **Retries.** A fixed attempt count with a fixed delay between tries. Each
-  retry reconnects. Upload and verification are retried together: a
-  verification failure is treated the same as an upload failure.
-- **Verification.** After each upload the remote size is compared against the
-  local file (`SIZE` / `Stat`), which catches truncation cheaply and works on
-  all three protocols. Hash-based verification is planned but not in v1; SFTP
-  has no standard equivalent. `--no-verify` turns it off.
-- **SSH host keys.** SFTP endpoints are verified against `~/.ssh/known_hosts`.
-  There is no insecure-by-default fallback: a host you have not trusted yet
-  fails with an error, the same trust-on-first-use flow as OpenSSH. Connect
-  once with `ssh` (or `ssh-keyscan`) to record the key first.
+  retry reconnects from scratch and re-runs verification, so a failed
+  verification triggers a retry the same way a failed upload does.
+- **Verification.** After each upload ramify compares the remote size against
+  the local file (`SIZE` / `Stat`), which catches truncation cheaply on all
+  three protocols. Hash verification waits for a later release, since SFTP has
+  no standard equivalent. `--no-verify` turns it off.
+- **SSH host keys.** ramify checks SFTP hosts against `~/.ssh/known_hosts` and
+  errors out on an untrusted host, with no insecure fallback, the same
+  trust-on-first-use flow as OpenSSH. Record the key first by connecting once
+  with `ssh` or `ssh-keyscan`.
 - **Cancellation.** Ctrl-C / SIGTERM cancels cleanly: workers stop starting new
-  transfers and retries promptly, though an in-flight blocking transfer runs to
+  transfers and retries, though an in-flight blocking transfer runs to
   completion first. Each endpoint still reports its results. A second Ctrl-C
-  exits immediately (code 130) rather than waiting out a stuck transfer.
+  exits at once with code 130 rather than waiting out a stuck transfer.
 
 ## Use as a Go library
 
@@ -293,13 +291,12 @@ make lint               # golangci-lint
 ```
 
 Integration tests spin up real `pure-ftpd` and `atmoz/sftp` containers via the
-`docker` CLI and are gated behind the `integration` build tag, so a plain
-`go test ./...` never needs Docker. They skip themselves with a message if
-Docker is not reachable.
+`docker` CLI, behind the `integration` build tag, so a plain `go test ./...`
+needs no Docker. Without a reachable Docker they skip with a message.
 
 ## Releasing (maintainers)
 
-Releases are cut by [GoReleaser](https://goreleaser.com) from a tag:
+[GoReleaser](https://goreleaser.com) cuts releases from a tag:
 
 ```console
 git tag v0.1.0
@@ -309,15 +306,15 @@ git push origin v0.1.0
 The `Release` workflow then cross-compiles every target, attaches
 checksummed archives to the GitHub Release, and updates the Homebrew tap.
 Publishing the Homebrew cask requires a `HOMEBREW_TAP_GITHUB_TOKEN` repository
-secret: a token with write access to `alexeyu/homebrew-tap`. If that secret is
-absent the release still succeeds and only the cask push is skipped. Validate
+secret: a token with write access to `alexeyu/homebrew-tap`. Without that
+secret the release still succeeds and skips only the cask push. Validate
 config changes locally with `goreleaser check` and dry-run a full build with
 `goreleaser release --snapshot --clean`.
 
 ## Stability
 
-Pre-1.0. The tool works and is tested, but the config schema and the Go library
-API may still change between minor versions. `v1.0.0` will mark both as stable.
+Pre-1.0. The config schema and the Go library API may change between minor
+versions; `v1.0.0` will freeze both.
 
 ## License