pix-cli 0.1.2__tar.gz → 0.1.4__tar.gz

{pix_cli-0.1.2 → pix_cli-0.1.4}/AGENTS.md

@@ -1,6 +1,6 @@
 # AGENTS.md
 
-`pix` 是批量图片压缩（AVIF）与 rclone 图床同步 CLI。已实现 `shrink` / `backup` / `publish` / `doctor` / `config init`；行为规格见 `docs/architecture.md`。
+`pix` 是批量图片压缩（AVIF）与 rclone 图床同步 CLI。已实现 `shrink` / `mirror` / `publish` / `doctor` / `config init`；行为规格见 `docs/architecture.md`。
 
 ## 文档
 
@@ -31,10 +31,11 @@ uv build
 - `pyvips` 只在 `shrink` / `doctor` 内延迟导入。
 - 不通过 shell 调用 `vips` 或 `rclone`。
 - `-q` 是 quality，`--quiet` 是静默。
-- 退出码 0/1/2，日志走 stderr；`backup` / `publish` 透传 rclone 退出码。
-- `backup` / `publish` 使用 `rclone bisync`；首次运行必须显式 `--resync`，不要自动加。它们是双向镜像，不是单向备份。
-- `--max-delete` 默认 10（删除百分比，rclone bisync 语义）；`backup` / `publish` 源为空时默认拒绝，`--allow-empty` 加 `--resync` 才放行。
-- 修改排除项后必须提示用户先 `--resync`；`--exclude` 是配置在前、命令行追加并去重。
+- 退出码 0/1/2，日志走 stderr；`mirror` / `publish` 透传 rclone 退出码。
+- `mirror` / `publish` 使用 `rclone bisync`；调用前先 `rclone mkdir` 目标并用 `rclone lsjson --max-depth 1` 判空。目标为空时自动加 `--resync`，目标非空时必须显式 `--resync`。用户不需要手动运行 rclone。它们是双向镜像，不是单向备份。
+- `--max-delete` 默认 10（删除百分比，rclone bisync 语义）；`mirror` / `publish` 源为空时默认拒绝，`--allow-empty` 加 `--resync` 才放行。
+- `mirror` 默认只同步 `[mirror].include` 中的图片扩展名，`include = []` 关闭白名单；`publish` 固定只同步 `.avif`。两者用 rclone filters 文件（bisync `--filters-file`、判空 `--filter-from`）并加 `--ignore-case`。
+- 修改 include/exclude 后必须提示用户先 `--resync`；升级到带过滤的版本后首次运行也需要 `--resync`。`--exclude` 是配置在前、命令行追加并去重。
 - 增量状态固定在 `OUT/.pix/state.json`，每 200 个成功文件刷新并在 `finally` 落盘；`publish` 必须排除 `.pix/**`。
 - `shrink` 必须拒绝目标冲突，`--prune` 必须拒绝空源，非 dry-run 必须持有 `OUT/.pix/lock`。
 - `publish` 源必须至少有一个 `.avif`；`base_url` 必须以 `http://` 或 `https://` 开头。

{pix_cli-0.1.2 → pix_cli-0.1.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: pix-cli
-Version: 0.1.2
+Version: 0.1.4
 Summary: Batch AVIF shrink and image-host sync CLI
 Project-URL: Homepage, https://github.com/uzvg/pix
 Project-URL: Repository, https://github.com/uzvg/pix
@@ -21,7 +21,7 @@ Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
 Classifier: Programming Language :: Python :: 3.14
 Classifier: Topic :: Multimedia :: Graphics :: Graphics Conversion
-Classifier: Topic :: System :: Archiving :: Backup
+Classifier: Topic :: System :: Archiving :: Mirroring
 Requires-Python: >=3.11
 Requires-Dist: pyvips[binary]>=3.2
 Description-Content-Type: text/markdown
@@ -41,9 +41,9 @@ Description-Content-Type: text/markdown
 | Command | Purpose |
 |---|---|
 | `pix shrink` | Recursively compress images to AVIF, re-encoding only changed files |
-| `pix backup` | Bidirectionally mirror an original photo directory to a cloud drive |
+| `pix mirror` | Bidirectionally mirror an original photo directory to a cloud drive |
 | `pix publish` | Bidirectionally mirror AVIF output to an image host; optionally emit public URLs |
-| `pix doctor` | Check Python, libvips, rclone and configuration |
+| `pix doctor` | Report Python, libvips and rclone versions, plus the config path |
 | `pix config init` | Write a commented default configuration file |
 
 `pix` is deliberately narrow:
@@ -58,32 +58,41 @@ Description-Content-Type: text/markdown
 photos/ ── shrink (pyvips) ──> out/*.avif + out/.pix/state.json
                                      │
                                      └── publish (rclone bisync) ──> r2:images
-photos/ ── backup (rclone bisync) ────────────────────────────────> onedrive:photos
+photos/ ── mirror (rclone bisync) ────────────────────────────────> onedrive:photos
 ```
 
 | Command | What actually runs | Who does the work |
 |---|---|---|
 | `shrink` | pyvips thumbnail + AVIF encode | pix |
-| `backup` | `rclone bisync SRC REMOTE` | pix composes arguments, rclone executes |
+| `mirror` | `rclone bisync SRC REMOTE` | pix composes arguments, rclone executes |
 | `publish` | `rclone bisync OUT REMOTE`, excluding `.pix/**` | pix + rclone |
-| `doctor` / `config init` | Dependency checks / config scaffold | pix |
+| `doctor` / `config init` | Runtime report / config scaffold | pix |
 
-**Sync is rclone.** `backup` and `publish` only compose `rclone bisync` arguments; rclone handles authentication, transfers and conflict handling. Configure remotes with `rclone config` before using them. `pix` never reads or writes `rclone.conf`.
+**Sync is rclone.** `mirror` and `publish` only compose `rclone bisync` arguments; rclone handles authentication, transfers and conflict handling. Configure remotes with `rclone config` before using them. `pix` never reads or writes `rclone.conf`.
 
-`backup` / `publish` are **bidirectional mirrors**, not one-way backups. Deletions propagate in both directions.
+`mirror` / `publish` are **bidirectional mirrors**, not one-way copies. Deletions propagate in both directions.
 
 ## Requirements
 
 - Python 3.11+
 - [uv](https://docs.astral.sh/uv/)
-- rclone >= 1.66 for `backup` / `publish`
+- rclone >= 1.66 for `mirror` / `publish` (and for `pix doctor` to report a clean environment)
 - At least one remote already configured in rclone
 
 `pyvips[binary]` bundles libvips, so no separate vips installation is required.
 
 ## Install
 
-Not yet published on PyPI; install from source:
+Install from PyPI:
+
+```bash
+uv tool install pix-cli
+pix --version
+```
+
+Upgrade with `uv tool upgrade pix-cli`; remove with `uv tool uninstall pix-cli`. Linux installs `~/.local/bin/pix`; Windows installs `%USERPROFILE%\.local\bin\pix.exe`.
+
+To work on pix itself, install the checkout in editable mode:
 
 ```bash
 git clone https://github.com/uzvg/pix.git
@@ -92,11 +101,11 @@ uv tool install --editable .
 pix --version
 ```
 
-Linux installs `~/.local/bin/pix`; Windows installs `%USERPROFILE%\.local\bin\pix.exe`. An editable install picks up source changes immediately. Reinstall with `uv tool install --force --editable .`, or remove it with `uv tool uninstall pix-cli`.
+An editable install picks up source changes immediately. Reinstall with `uv tool install --force --editable .`.
 
 ## Configure rclone
 
-Only needed for `backup` / `publish`:
+Only needed for `mirror` / `publish`:
 
 ```bash
 rclone config         # create a remote, for example onedrive or r2
@@ -118,7 +127,7 @@ If the file is missing, built-in defaults are used. Generate a commented file wi
 pix config init
 ```
 
-Existing files are not overwritten; pass `--force` to replace one. Use `--config PATH` before the subcommand to point at another file.
+Existing files are not overwritten; pass `--force` to replace one. Use `--config PATH` before the subcommand to point at another file; an explicit path must exist, while a missing default path is fine.
 
 Common keys:
 
@@ -129,15 +138,18 @@ Common keys:
 | | `effort` | `5` | libvips effort, 0–9 |
 | | `min_size` | `0` | Skip sources smaller than this; accepts `500K`, `1M`, `2G` |
 | | `include` | `jpg`, `jpeg`, `png`, `webp` | Extensions to scan, without dots |
-| `[backup]` | `exclude` | `[]` | rclone exclude globs; command-line values are appended |
+| `[mirror]` | `include` | common image extensions | Extensions to mirror, without dots; `[]` disables the whitelist |
+| | `exclude` | `[]` | rclone exclude globs; command-line values are appended |
 | | `max_delete` | `10` | Delete limit as a percentage; `-1` disables, `0` forbids |
 | `[publish]` | `base_url` | `""` | Public URL prefix; must start with `http://` or `https://` |
 | | `urls` | `false` | Emit a JSON URL manifest |
-| | `exclude` | `[]` | Same as backup |
-| | `max_delete` | `10` | Same as backup |
+| | `exclude` | `[]` | Same as mirror; `.pix/**` is always excluded first |
+| | `max_delete` | `10` | Same as mirror |
 | `[rclone]` | `binary` | `rclone` | rclone executable name or path |
 
-Precedence is **command line > pix config > built-in defaults**. `--exclude` is appended to config excludes rather than replacing them. `-q` means quality; silence is `--quiet` (no short form).
+Precedence is **command line > pix config > built-in defaults**. `--exclude` is appended to config excludes rather than replacing them. `-q` means quality; `--quiet` is errors-only; `-v` / `--verbose` adds per-file detail and rclone progress. `--no-urls` overrides `[publish].urls = true` for one run.
+
+The default `[mirror].include` is `jpg`, `jpeg`, `png`, `webp`, `gif`, `bmp`, `tif`, `tiff`, `heic`, `heif`, `avif`, `jxl`, `svg`, `ico`, `cr2`, `cr3`, `nef`, `arw`, `dng`, `orf`, `raf`, `rw2`. Set it to `[]` to mirror every file.
 
 ## Quick start
 
@@ -154,16 +166,16 @@ Precedence is **command line > pix config > built-in defaults**. `--exclude` is
    pix shrink -s ~/Pictures -d ~/Pictures-avif -w 1920 -q 85
    ```
 
-   The first run encodes everything; later runs skip unchanged files. State lives in `OUT/.pix/state.json`. Changing `width`, `quality` or `effort` triggers a full re-encode. `--dry-run` only prints the plan.
+   The first run encodes everything; later runs skip unchanged files. State lives in `OUT/.pix/state.json`. `-w` is a maximum long edge, so smaller images are not upscaled; relative directories are preserved under OUT. Change detection uses source size/mtime and output size, not content hashes. Changing `width`, `quality` or `effort` triggers a full re-encode. `--dry-run` only prints the plan. `--prune` removes only outputs recorded in state; extra files in OUT are left alone.
 
-3. Back up originals:
+3. Mirror originals:
 
    ```bash
-   pix backup -s ~/Pictures -d onedrive:photos --dry-run
-   pix backup -s ~/Pictures -d onedrive:photos --resync
+   pix mirror -s ~/Pictures -d onedrive:photos --dry-run
+   pix mirror -s ~/Pictures -d onedrive:photos
    ```
 
-   `--resync` is required on the first run. Always preview with `--dry-run` first.
+   The destination is created automatically. Only files matching `[mirror].include` are mirrored; other source files are ignored, and non-matching files already on the destination are left untouched. If no source file matches the filter, the source counts as empty and is refused unless you pass `--allow-empty --resync`. An empty destination initializes its own baseline, so no `--resync` is needed on the first run. Use `--resync` to rebuild the baseline when the destination already has matching content, or after changing `include`/`exclude`; `--dry-run` may create an empty destination but does not transfer or delete. After upgrading from a version without include filtering, the first run also needs `--resync`; preview with `--dry-run --resync` first (the preview does not write the baseline).
 
 4. Publish the AVIF output:
 
@@ -172,17 +184,18 @@ Precedence is **command line > pix config > built-in defaults**. `--exclude` is
      --base-url https://img.example.com --urls > urls.json
    ```
 
-   `publish` requires at least one `.avif` in the source and always excludes `.pix/**`. The URL manifest is printed to stdout as JSON only after a successful, non-dry-run sync.
+   `publish` requires at least one `.avif` in the source unless you pass `--allow-empty --resync`; it syncs only `.avif` files and always excludes `.pix/**`. The URL manifest is printed to stdout as JSON only after a successful, non-dry-run sync. It lists every `.avif` under OUT, not just files changed in this run, and is not filtered by `[publish].exclude` or `--exclude`; excluded files can still appear in it. If you rely on excludes to hide files, do not publish the manifest until this behavior is fixed.
 
 5. Re-run later:
 
    ```bash
    pix shrink -s ~/Pictures -d ~/Pictures-avif
-   pix backup -s ~/Pictures -d onedrive:photos
-   pix publish -s ~/Pictures-avif -d r2:images --urls
+   pix mirror -s ~/Pictures -d onedrive:photos
+   pix publish -s ~/Pictures-avif -d r2:images \
+     --base-url https://img.example.com --urls
    ```
 
-   Only changes are encoded and transferred.
+   Only changes are encoded and transferred. `--base-url` is not persisted between runs; set `[publish].base_url` in config to avoid repeating it.
 
 ## Command cheat sheet
 
@@ -190,9 +203,10 @@ Precedence is **command line > pix config > built-in defaults**. `--exclude` is
 |---|---|
 | Preview compression | `pix shrink -s SRC -d OUT --dry-run` |
 | Re-encode everything | `pix shrink -s SRC -d OUT --force` |
-| Remove outputs whose source is gone | `pix shrink -s SRC -d OUT --prune` |
-| Preview a sync | `pix backup -s SRC -d REMOTE --dry-run` |
-| First run, or after changing excludes | `pix backup -s SRC -d REMOTE --resync` |
+| Remove tracked outputs whose source is gone | `pix shrink -s SRC -d OUT --prune` |
+| Preview a sync | `pix mirror -s SRC -d REMOTE --dry-run` |
+| First sync (new or empty destination) | `pix mirror -s SRC -d REMOTE` |
+| Rebuild the baseline (non-empty destination, or after changing include/exclude) | `pix mirror -s SRC -d REMOTE --resync` |
 | Emit a URL manifest | `pix publish -s OUT -d REMOTE --base-url https://img.example.com --urls` |
 | Diagnose the environment | `pix doctor` |
 | Generate a config file | `pix config init` |
@@ -202,19 +216,21 @@ Precedence is **command line > pix config > built-in defaults**. `--exclude` is
 | Situation | What happens | Protection |
 |---|---|---|
 | Deletions on either side | Propagated in both directions; accidental deletion is irreversible | Preview with `--dry-run`; default `--max-delete 10` (percentage) |
-| First sync | rclone has no baseline and errors | Add `--resync` explicitly |
-| Excludes changed | The old baseline may treat excluded files as deletions | Run with `--resync` again after changing excludes |
-| Empty source | `backup` / `publish` refuse; `shrink --prune` also refuses | Use `--allow-empty` (plus `--resync` for sync) only when intentional |
+| First sync (destination empty) | `pix` creates the destination and initializes the baseline | Preview with `--dry-run`; it may create an empty destination but does not transfer or delete. No manual rclone needed |
+| Destination has matching content but no baseline | `pix` does not auto-resync; bisync fails instead of overwriting | Confirm which side is authoritative, then add `--resync` |
+| Include/exclude filters changed | When filters are active, rclone detects the changed filters file and exits 7 | Run with `--resync` after changing `include` or `exclude`; `--dry-run --resync` previews but does not write the baseline |
+| Non-image files in the source | `mirror` ignores them by default; `publish` ignores anything that is not `.avif`. If no file matches, the source counts as empty and is refused | Add extensions to `[mirror].include` if they should be mirrored; use `--allow-empty --resync` only for an intentional empty sync |
+| Empty source | `mirror` / `publish` refuse. `shrink --prune` refuses only while state still has entries; empty state is a no-op | Use `--allow-empty` (plus `--resync` for sync) only when intentional |
 | `a.jpg` and `a.jpeg` both exist | Both map to the same output | Detected before encoding; exits 2 |
 | Two concurrent shrinks | They would write the same state and outputs | `OUT/.pix/lock` blocks the second process |
-| State lost or corrupt | Warning, then a full rebuild | Only causes re-encoding; outputs stay valid |
+| State missing or corrupt | Full rebuild; corrupt state logs a warning | Only causes re-encoding; outputs stay valid |
 
 ## Output and exit codes
 
 - Logs and progress go to stderr.
-- stdout carries `doctor` reports, `--dry-run` plans and `--urls` JSON.
+- stdout carries `doctor` reports, `shrink --dry-run` plans, `config init`'s `wrote <path>`, and `--urls` JSON. `mirror` / `publish --dry-run` output comes from rclone.
 - Exit codes: `0` success, `1` runtime failure, `2` argument or configuration error.
-- `backup` / `publish` return rclone's exit code unchanged.
+- `mirror` / `publish` return rclone's bisync exit code unchanged; destination preflight failures return 1.
 
 URL manifest example:
 
@@ -230,9 +246,9 @@ URL manifest example:
 |---|---|
 | `pyvips/libvips unavailable` | Reinstall to bring libvips: `uv tool install --force --editable /path/to/pix`; or install libvips manually (Linux: `apt install libvips42`, Windows: libvips release zip on `PATH`) |
 | rclone is older than 1.66 | Upgrade rclone |
-| bisync reports a missing baseline | Add `--resync` on the first run |
+| bisync reports a missing baseline or changed filters file | The destination has matching content, or the include/exclude rules changed (including the first run after upgrading). Confirm local should win, then add `--resync`; an empty destination initializes automatically. `--dry-run --resync` previews but does not write the baseline. |
 | `OUT/.pix/lock` already exists | Check for another `shrink`, then remove a stale lock |
-| Configuration fails to parse | Run `pix doctor` to locate the file; fix the TOML or remove the file to fall back to defaults |
+| Configuration fails to parse | The error names the file and location; fix the TOML or remove the file to fall back to defaults. `pix doctor` cannot run until the config parses |
 | `publish` says the source has no `.avif` | Run `pix shrink` first |
 | URL-related error | `base_url` must start with `http://` or `https://`, and `--urls` requires it |
 

{pix_cli-0.1.2 → pix_cli-0.1.4}/README.md

@@ -13,9 +13,9 @@
 | Command | Purpose |
 |---|---|
 | `pix shrink` | Recursively compress images to AVIF, re-encoding only changed files |
-| `pix backup` | Bidirectionally mirror an original photo directory to a cloud drive |
+| `pix mirror` | Bidirectionally mirror an original photo directory to a cloud drive |
 | `pix publish` | Bidirectionally mirror AVIF output to an image host; optionally emit public URLs |
-| `pix doctor` | Check Python, libvips, rclone and configuration |
+| `pix doctor` | Report Python, libvips and rclone versions, plus the config path |
 | `pix config init` | Write a commented default configuration file |
 
 `pix` is deliberately narrow:
@@ -30,32 +30,41 @@
 photos/ ── shrink (pyvips) ──> out/*.avif + out/.pix/state.json
                                      │
                                      └── publish (rclone bisync) ──> r2:images
-photos/ ── backup (rclone bisync) ────────────────────────────────> onedrive:photos
+photos/ ── mirror (rclone bisync) ────────────────────────────────> onedrive:photos
 ```
 
 | Command | What actually runs | Who does the work |
 |---|---|---|
 | `shrink` | pyvips thumbnail + AVIF encode | pix |
-| `backup` | `rclone bisync SRC REMOTE` | pix composes arguments, rclone executes |
+| `mirror` | `rclone bisync SRC REMOTE` | pix composes arguments, rclone executes |
 | `publish` | `rclone bisync OUT REMOTE`, excluding `.pix/**` | pix + rclone |
-| `doctor` / `config init` | Dependency checks / config scaffold | pix |
+| `doctor` / `config init` | Runtime report / config scaffold | pix |
 
-**Sync is rclone.** `backup` and `publish` only compose `rclone bisync` arguments; rclone handles authentication, transfers and conflict handling. Configure remotes with `rclone config` before using them. `pix` never reads or writes `rclone.conf`.
+**Sync is rclone.** `mirror` and `publish` only compose `rclone bisync` arguments; rclone handles authentication, transfers and conflict handling. Configure remotes with `rclone config` before using them. `pix` never reads or writes `rclone.conf`.
 
-`backup` / `publish` are **bidirectional mirrors**, not one-way backups. Deletions propagate in both directions.
+`mirror` / `publish` are **bidirectional mirrors**, not one-way copies. Deletions propagate in both directions.
 
 ## Requirements
 
 - Python 3.11+
 - [uv](https://docs.astral.sh/uv/)
-- rclone >= 1.66 for `backup` / `publish`
+- rclone >= 1.66 for `mirror` / `publish` (and for `pix doctor` to report a clean environment)
 - At least one remote already configured in rclone
 
 `pyvips[binary]` bundles libvips, so no separate vips installation is required.
 
 ## Install
 
-Not yet published on PyPI; install from source:
+Install from PyPI:
+
+```bash
+uv tool install pix-cli
+pix --version
+```
+
+Upgrade with `uv tool upgrade pix-cli`; remove with `uv tool uninstall pix-cli`. Linux installs `~/.local/bin/pix`; Windows installs `%USERPROFILE%\.local\bin\pix.exe`.
+
+To work on pix itself, install the checkout in editable mode:
 
 ```bash
 git clone https://github.com/uzvg/pix.git
@@ -64,11 +73,11 @@ uv tool install --editable .
 pix --version
 ```
 
-Linux installs `~/.local/bin/pix`; Windows installs `%USERPROFILE%\.local\bin\pix.exe`. An editable install picks up source changes immediately. Reinstall with `uv tool install --force --editable .`, or remove it with `uv tool uninstall pix-cli`.
+An editable install picks up source changes immediately. Reinstall with `uv tool install --force --editable .`.
 
 ## Configure rclone
 
-Only needed for `backup` / `publish`:
+Only needed for `mirror` / `publish`:
 
 ```bash
 rclone config         # create a remote, for example onedrive or r2
@@ -90,7 +99,7 @@ If the file is missing, built-in defaults are used. Generate a commented file wi
 pix config init
 ```
 
-Existing files are not overwritten; pass `--force` to replace one. Use `--config PATH` before the subcommand to point at another file.
+Existing files are not overwritten; pass `--force` to replace one. Use `--config PATH` before the subcommand to point at another file; an explicit path must exist, while a missing default path is fine.
 
 Common keys:
 
@@ -101,15 +110,18 @@ Common keys:
 | | `effort` | `5` | libvips effort, 0–9 |
 | | `min_size` | `0` | Skip sources smaller than this; accepts `500K`, `1M`, `2G` |
 | | `include` | `jpg`, `jpeg`, `png`, `webp` | Extensions to scan, without dots |
-| `[backup]` | `exclude` | `[]` | rclone exclude globs; command-line values are appended |
+| `[mirror]` | `include` | common image extensions | Extensions to mirror, without dots; `[]` disables the whitelist |
+| | `exclude` | `[]` | rclone exclude globs; command-line values are appended |
 | | `max_delete` | `10` | Delete limit as a percentage; `-1` disables, `0` forbids |
 | `[publish]` | `base_url` | `""` | Public URL prefix; must start with `http://` or `https://` |
 | | `urls` | `false` | Emit a JSON URL manifest |
-| | `exclude` | `[]` | Same as backup |
-| | `max_delete` | `10` | Same as backup |
+| | `exclude` | `[]` | Same as mirror; `.pix/**` is always excluded first |
+| | `max_delete` | `10` | Same as mirror |
 | `[rclone]` | `binary` | `rclone` | rclone executable name or path |
 
-Precedence is **command line > pix config > built-in defaults**. `--exclude` is appended to config excludes rather than replacing them. `-q` means quality; silence is `--quiet` (no short form).
+Precedence is **command line > pix config > built-in defaults**. `--exclude` is appended to config excludes rather than replacing them. `-q` means quality; `--quiet` is errors-only; `-v` / `--verbose` adds per-file detail and rclone progress. `--no-urls` overrides `[publish].urls = true` for one run.
+
+The default `[mirror].include` is `jpg`, `jpeg`, `png`, `webp`, `gif`, `bmp`, `tif`, `tiff`, `heic`, `heif`, `avif`, `jxl`, `svg`, `ico`, `cr2`, `cr3`, `nef`, `arw`, `dng`, `orf`, `raf`, `rw2`. Set it to `[]` to mirror every file.
 
 ## Quick start
 
@@ -126,16 +138,16 @@ Precedence is **command line > pix config > built-in defaults**. `--exclude` is
    pix shrink -s ~/Pictures -d ~/Pictures-avif -w 1920 -q 85
    ```
 
-   The first run encodes everything; later runs skip unchanged files. State lives in `OUT/.pix/state.json`. Changing `width`, `quality` or `effort` triggers a full re-encode. `--dry-run` only prints the plan.
+   The first run encodes everything; later runs skip unchanged files. State lives in `OUT/.pix/state.json`. `-w` is a maximum long edge, so smaller images are not upscaled; relative directories are preserved under OUT. Change detection uses source size/mtime and output size, not content hashes. Changing `width`, `quality` or `effort` triggers a full re-encode. `--dry-run` only prints the plan. `--prune` removes only outputs recorded in state; extra files in OUT are left alone.
 
-3. Back up originals:
+3. Mirror originals:
 
    ```bash
-   pix backup -s ~/Pictures -d onedrive:photos --dry-run
-   pix backup -s ~/Pictures -d onedrive:photos --resync
+   pix mirror -s ~/Pictures -d onedrive:photos --dry-run
+   pix mirror -s ~/Pictures -d onedrive:photos
    ```
 
-   `--resync` is required on the first run. Always preview with `--dry-run` first.
+   The destination is created automatically. Only files matching `[mirror].include` are mirrored; other source files are ignored, and non-matching files already on the destination are left untouched. If no source file matches the filter, the source counts as empty and is refused unless you pass `--allow-empty --resync`. An empty destination initializes its own baseline, so no `--resync` is needed on the first run. Use `--resync` to rebuild the baseline when the destination already has matching content, or after changing `include`/`exclude`; `--dry-run` may create an empty destination but does not transfer or delete. After upgrading from a version without include filtering, the first run also needs `--resync`; preview with `--dry-run --resync` first (the preview does not write the baseline).
 
 4. Publish the AVIF output:
 
@@ -144,17 +156,18 @@ Precedence is **command line > pix config > built-in defaults**. `--exclude` is
      --base-url https://img.example.com --urls > urls.json
    ```
 
-   `publish` requires at least one `.avif` in the source and always excludes `.pix/**`. The URL manifest is printed to stdout as JSON only after a successful, non-dry-run sync.
+   `publish` requires at least one `.avif` in the source unless you pass `--allow-empty --resync`; it syncs only `.avif` files and always excludes `.pix/**`. The URL manifest is printed to stdout as JSON only after a successful, non-dry-run sync. It lists every `.avif` under OUT, not just files changed in this run, and is not filtered by `[publish].exclude` or `--exclude`; excluded files can still appear in it. If you rely on excludes to hide files, do not publish the manifest until this behavior is fixed.
 
 5. Re-run later:
 
    ```bash
    pix shrink -s ~/Pictures -d ~/Pictures-avif
-   pix backup -s ~/Pictures -d onedrive:photos
-   pix publish -s ~/Pictures-avif -d r2:images --urls
+   pix mirror -s ~/Pictures -d onedrive:photos
+   pix publish -s ~/Pictures-avif -d r2:images \
+     --base-url https://img.example.com --urls
    ```
 
-   Only changes are encoded and transferred.
+   Only changes are encoded and transferred. `--base-url` is not persisted between runs; set `[publish].base_url` in config to avoid repeating it.
 
 ## Command cheat sheet
 
@@ -162,9 +175,10 @@ Precedence is **command line > pix config > built-in defaults**. `--exclude` is
 |---|---|
 | Preview compression | `pix shrink -s SRC -d OUT --dry-run` |
 | Re-encode everything | `pix shrink -s SRC -d OUT --force` |
-| Remove outputs whose source is gone | `pix shrink -s SRC -d OUT --prune` |
-| Preview a sync | `pix backup -s SRC -d REMOTE --dry-run` |
-| First run, or after changing excludes | `pix backup -s SRC -d REMOTE --resync` |
+| Remove tracked outputs whose source is gone | `pix shrink -s SRC -d OUT --prune` |
+| Preview a sync | `pix mirror -s SRC -d REMOTE --dry-run` |
+| First sync (new or empty destination) | `pix mirror -s SRC -d REMOTE` |
+| Rebuild the baseline (non-empty destination, or after changing include/exclude) | `pix mirror -s SRC -d REMOTE --resync` |
 | Emit a URL manifest | `pix publish -s OUT -d REMOTE --base-url https://img.example.com --urls` |
 | Diagnose the environment | `pix doctor` |
 | Generate a config file | `pix config init` |
@@ -174,19 +188,21 @@ Precedence is **command line > pix config > built-in defaults**. `--exclude` is
 | Situation | What happens | Protection |
 |---|---|---|
 | Deletions on either side | Propagated in both directions; accidental deletion is irreversible | Preview with `--dry-run`; default `--max-delete 10` (percentage) |
-| First sync | rclone has no baseline and errors | Add `--resync` explicitly |
-| Excludes changed | The old baseline may treat excluded files as deletions | Run with `--resync` again after changing excludes |
-| Empty source | `backup` / `publish` refuse; `shrink --prune` also refuses | Use `--allow-empty` (plus `--resync` for sync) only when intentional |
+| First sync (destination empty) | `pix` creates the destination and initializes the baseline | Preview with `--dry-run`; it may create an empty destination but does not transfer or delete. No manual rclone needed |
+| Destination has matching content but no baseline | `pix` does not auto-resync; bisync fails instead of overwriting | Confirm which side is authoritative, then add `--resync` |
+| Include/exclude filters changed | When filters are active, rclone detects the changed filters file and exits 7 | Run with `--resync` after changing `include` or `exclude`; `--dry-run --resync` previews but does not write the baseline |
+| Non-image files in the source | `mirror` ignores them by default; `publish` ignores anything that is not `.avif`. If no file matches, the source counts as empty and is refused | Add extensions to `[mirror].include` if they should be mirrored; use `--allow-empty --resync` only for an intentional empty sync |
+| Empty source | `mirror` / `publish` refuse. `shrink --prune` refuses only while state still has entries; empty state is a no-op | Use `--allow-empty` (plus `--resync` for sync) only when intentional |
 | `a.jpg` and `a.jpeg` both exist | Both map to the same output | Detected before encoding; exits 2 |
 | Two concurrent shrinks | They would write the same state and outputs | `OUT/.pix/lock` blocks the second process |
-| State lost or corrupt | Warning, then a full rebuild | Only causes re-encoding; outputs stay valid |
+| State missing or corrupt | Full rebuild; corrupt state logs a warning | Only causes re-encoding; outputs stay valid |
 
 ## Output and exit codes
 
 - Logs and progress go to stderr.
-- stdout carries `doctor` reports, `--dry-run` plans and `--urls` JSON.
+- stdout carries `doctor` reports, `shrink --dry-run` plans, `config init`'s `wrote <path>`, and `--urls` JSON. `mirror` / `publish --dry-run` output comes from rclone.
 - Exit codes: `0` success, `1` runtime failure, `2` argument or configuration error.
-- `backup` / `publish` return rclone's exit code unchanged.
+- `mirror` / `publish` return rclone's bisync exit code unchanged; destination preflight failures return 1.
 
 URL manifest example:
 
@@ -202,9 +218,9 @@ URL manifest example:
 |---|---|
 | `pyvips/libvips unavailable` | Reinstall to bring libvips: `uv tool install --force --editable /path/to/pix`; or install libvips manually (Linux: `apt install libvips42`, Windows: libvips release zip on `PATH`) |
 | rclone is older than 1.66 | Upgrade rclone |
-| bisync reports a missing baseline | Add `--resync` on the first run |
+| bisync reports a missing baseline or changed filters file | The destination has matching content, or the include/exclude rules changed (including the first run after upgrading). Confirm local should win, then add `--resync`; an empty destination initializes automatically. `--dry-run --resync` previews but does not write the baseline. |
 | `OUT/.pix/lock` already exists | Check for another `shrink`, then remove a stale lock |
-| Configuration fails to parse | Run `pix doctor` to locate the file; fix the TOML or remove the file to fall back to defaults |
+| Configuration fails to parse | The error names the file and location; fix the TOML or remove the file to fall back to defaults. `pix doctor` cannot run until the config parses |
 | `publish` says the source has no `.avif` | Run `pix shrink` first |
 | URL-related error | `base_url` must start with `http://` or `https://`, and `--urls` requires it |