Release 0.22.0 with composable feature extras

Add --cpu-offload flag for low-VRAM CUDA cards

.claude/rules/development.md

@@ -0,0 +1,31 @@
+---
+globs: ["src/**/*.py", "tests/**/*.py", "scripts/**/*.py", "pyproject.toml", "uv.lock", "maintain.sh", ".github/workflows/*.yml"]
+description: Command contracts, project gate, typing boundaries, and model-adjacent test invariants.
+---
+
+# Development invariants
+
+## Command contracts
+
+Every single-image command declares `source` with `dir_okay=False`; `batch` declares its directory with `file_okay=False`. Keep `tests/test_cli_robustness.py::TestDirectoryInputIsRejected` as the regression guard.
+
+Exit-code and no-signal behavior is a public contract. Read the command-line section of [`../../docs/module-internals.md`](../../docs/module-internals.md) before changing it.
+
+## Local gate
+
+Run `bash maintain.sh` from the repository root. The authoritative type gate is scoped to `src/`; full-project Pyright can exhaust Node memory on the ML dependency graph.
+
+Boundary modules for cv2, Torch, and Diffusers may carry narrow per-file relaxations for unknown third-party types. Keep pure-logic files strict, preserve the local piexif stub, and fix real errors before widening a pragma.
+
+## Model-adjacent tests
+
+Do not classify an entire module as untestable because its main path downloads a model. Keep pure behavior covered without downloads, including:
+
+- target-size selection in `test_invisible_engine.py`;
+- unsharp and adaptive-polish helpers in `test_humanizer.py`;
+- mocked device fallback in `test_img2img_runner.py`;
+- tiling geometry and blending in `test_tiling.py`.
+
+Use availability checks only for paths that actually load large models.
+
+Environment setup, dependency recovery, CI behavior, and fixture policy: [`../../docs/development.md`](../../docs/development.md).

.github/dependabot.yml

@@ -14,6 +14,21 @@ updates:
         update-types:
           - "minor"
           - "patch"
+    # The `all` extra must remain jointly resolvable. These candidates violate
+    # upstream constraints: TrustMark still requires NumPy 1.x, OpenCV 4.12+
+    # requires NumPy 2 on newer Python versions, and this project keeps tokenizers
+    # below 0.23 for the stable Transformers path. Keep Dependabot on the
+    # compatible lines until those constraints move.
+    ignore:
+      - dependency-name: "numpy"
+        versions:
+          - ">=2"
+      - dependency-name: "opencv-python-headless"
+        versions:
+          - ">=4.12"
+      - dependency-name: "tokenizers"
+        versions:
+          - ">=0.23"
 
   - package-ecosystem: "github-actions"
     directory: "/"

.github/workflows/distribute.yml

@@ -0,0 +1,208 @@
+name: Distribute on release
+
+# Fans a published GitHub Release out to the channels that need a nudge.
+# PyPI is handled by publish.yml; the conda-forge channel is handled by its
+# autotick bot. This workflow updates the repository recipe and event-drives
+# the three channels that would otherwise be manual:
+#   - Homebrew tap: rewrite the formula's url + sha256 to the new sdist.
+#   - HF Space: factory-rebuild so it reinstalls the latest sdist from PyPI.
+#   - ComfyUI: sync, test, and publish the node against the exact library release.
+# All wait for the freshly published sdist to appear on PyPI first, since the
+# Release event fires in parallel with publish.yml's upload.
+
+on:
+  release:
+    types: [published]
+  workflow_dispatch:
+    inputs:
+      version:
+        description: "Version to distribute (no leading v), e.g. 0.10.3. Blank = latest on PyPI."
+        required: false
+
+jobs:
+  resolve:
+    runs-on: ubuntu-latest
+    outputs:
+      version: ${{ steps.v.outputs.version }}
+      url: ${{ steps.sdist.outputs.url }}
+      sha: ${{ steps.sdist.outputs.sha }}
+    steps:
+      - name: Resolve target version
+        id: v
+        run: |
+          set -euo pipefail
+          if [ "${{ github.event_name }}" = "release" ]; then
+            v="${GITHUB_REF_NAME#v}"
+          elif [ -n "${{ github.event.inputs.version }}" ]; then
+            v="${{ github.event.inputs.version }}"
+          else
+            v=$(curl -fsSL https://pypi.org/pypi/remove-ai-watermarks/json \
+              | python3 -c "import sys,json;print(json.load(sys.stdin)['info']['version'])")
+          fi
+          echo "version=$v" >> "$GITHUB_OUTPUT"
+          echo "Target version: $v"
+
+      - name: Wait for the sdist on PyPI, capture url + sha256
+        id: sdist
+        run: |
+          set -euo pipefail
+          v="${{ steps.v.outputs.version }}"
+          for i in $(seq 1 30); do
+            if rel=$(curl -fsSL "https://pypi.org/pypi/remove-ai-watermarks/$v/json" 2>/dev/null); then
+              url=$(echo "$rel" | python3 -c "import sys,json;d=json.load(sys.stdin);print(next((u['url'] for u in d['urls'] if u['packagetype']=='sdist'),''))")
+              sha=$(echo "$rel" | python3 -c "import sys,json;d=json.load(sys.stdin);print(next((u['digests']['sha256'] for u in d['urls'] if u['packagetype']=='sdist'),''))")
+              if [ -n "$url" ] && [ -n "$sha" ]; then
+                echo "url=$url" >> "$GITHUB_OUTPUT"
+                echo "sha=$sha" >> "$GITHUB_OUTPUT"
+                echo "Found sdist for $v"
+                exit 0
+              fi
+            fi
+            echo "sdist for $v not on PyPI yet (attempt $i), waiting..."
+            sleep 20
+          done
+          echo "::error::sdist for $v did not appear on PyPI in time"
+          exit 1
+
+  homebrew:
+    needs: resolve
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout the tap
+        uses: actions/checkout@v7
+        with:
+          repository: wiltodelta/homebrew-tap
+          token: ${{ secrets.HOMEBREW_TAP_TOKEN }}
+      - name: Bump the formula
+        env:
+          URL: ${{ needs.resolve.outputs.url }}
+          SHA: ${{ needs.resolve.outputs.sha }}
+          VERSION: ${{ needs.resolve.outputs.version }}
+        run: |
+          set -euo pipefail
+          F=Formula/remove-ai-watermarks.rb
+          sed -i -E "s|url \"[^\"]*\"|url \"$URL\"|" "$F"
+          sed -i -E "s|sha256 \"[^\"]*\"|sha256 \"$SHA\"|" "$F"
+          git config user.name "github-actions[bot]"
+          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+          git add "$F"
+          git commit -m "remove-ai-watermarks $VERSION" || { echo "Formula already current"; exit 0; }
+          git push
+
+  conda-recipe:
+    needs: resolve
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - name: Checkout main
+        uses: actions/checkout@v7
+        with:
+          ref: main
+      - name: Bump the repository conda recipe
+        env:
+          SHA: ${{ needs.resolve.outputs.sha }}
+          VERSION: ${{ needs.resolve.outputs.version }}
+        run: |
+          set -euo pipefail
+          python scripts/sync_conda_recipe.py --version "$VERSION" --sha256 "$SHA"
+          git diff --check
+          if git diff --quiet -- packaging/conda/recipe.yaml; then
+            echo "Conda recipe already current"
+            exit 0
+          fi
+          git config user.name "github-actions[bot]"
+          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+          git add packaging/conda/recipe.yaml
+          git commit -m "Sync conda recipe with v$VERSION"
+          git push
+
+  hf-space:
+    needs: resolve
+    runs-on: ubuntu-latest
+    steps:
+      - name: Factory-rebuild the HuggingFace Space
+        env:
+          HF_TOKEN: ${{ secrets.HF_TOKEN }}
+        run: |
+          python3 -m pip install --quiet huggingface_hub
+          python3 - <<'PY'
+          import os
+          from huggingface_hub import HfApi
+          HfApi(token=os.environ["HF_TOKEN"]).restart_space(
+              "wiltodelta/remove-ai-watermarks", factory_reboot=True
+          )
+          print("HF Space factory rebuild triggered")
+          PY
+
+  comfyui:
+    needs: resolve
+    runs-on: ubuntu-latest
+    steps:
+      - name: Sync and publish the ComfyUI nodes
+        env:
+          GH_TOKEN: ${{ secrets.COMFYUI_RELEASE_TOKEN }}
+        run: |
+          set -euo pipefail
+          repo=wiltodelta/ComfyUI-remove-ai-watermarks
+          workflow=sync-library.yml
+          dispatched_at=$(date -u +%Y-%m-%dT%H:%M:%SZ)
+
+          gh workflow run "$workflow" \
+            --repo "$repo" \
+            --ref main \
+            --raw-field library_version="${{ needs.resolve.outputs.version }}"
+
+          run_id=""
+          for attempt in $(seq 1 30); do
+            run_id=$(
+              gh run list \
+                --repo "$repo" \
+                --workflow "$workflow" \
+                --event workflow_dispatch \
+                --limit 10 \
+                --json databaseId,createdAt \
+                | python3 -c '
+          import json
+          import sys
+
+          dispatched_at = sys.argv[1]
+          runs = json.load(sys.stdin)
+          print(next(
+              (run["databaseId"] for run in runs if run["createdAt"] >= dispatched_at),
+              "",
+          ))
+          ' "$dispatched_at"
+            )
+            if [ -n "$run_id" ]; then
+              break
+            fi
+            echo "ComfyUI sync run not visible yet (attempt $attempt), waiting..."
+            sleep 2
+          done
+
+          if [ -z "$run_id" ]; then
+            echo "::error::The dispatched ComfyUI sync run did not appear"
+            exit 1
+          fi
+
+          for attempt in $(seq 1 180); do
+            read -r status conclusion <<< "$(
+              gh run view "$run_id" \
+                --repo "$repo" \
+                --json status,conclusion \
+                --jq '[.status, (.conclusion // "")] | @tsv'
+            )"
+            if [ "$status" = "completed" ]; then
+              if [ "$conclusion" = "success" ]; then
+                echo "ComfyUI sync run $run_id succeeded"
+                exit 0
+              fi
+              echo "::error::ComfyUI sync run $run_id completed with $conclusion"
+              exit 1
+            fi
+            echo "ComfyUI sync run $run_id is $status (attempt $attempt), waiting..."
+            sleep 5
+          done
+          echo "::error::ComfyUI sync run $run_id did not finish in time"
+          exit 1

.github/workflows/publish.yml

@@ -13,7 +13,7 @@ jobs:
     runs-on: ubuntu-latest
     environment: pypi
     steps:
-      - uses: actions/checkout@v6
+      - uses: actions/checkout@v7
 
       - uses: astral-sh/setup-uv@v7
 
@@ -30,5 +30,12 @@ jobs:
       - name: Build package
         run: uv build
 
+      # Publish with `uv publish` (its own uploader, not the twine bundled in the
+      # old pypa action). Trusted publishing is automatic in GitHub Actions: the
+      # `id-token: write` permission + the `pypi` environment supply the OIDC token,
+      # and PyPI's trusted-publisher entry matches on repo + workflow filename +
+      # environment name (all unchanged from the pypa-action setup), so no API token
+      # is needed. uv's uploader also accepts Metadata-Version 2.5 -- the permanent
+      # fix that lets the hatchling pin be relaxed (see pyproject [build-system]).
       - name: Publish to PyPI
-        uses: pypa/gh-action-pypi-publish@release/v1
+        run: uv publish

.github/workflows/test.yml

@@ -13,7 +13,7 @@ jobs:
   lint:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v6
+      - uses: actions/checkout@v7
       - uses: astral-sh/setup-uv@v7
       - name: Sync dev environment
         run: uv sync --frozen --extra dev
@@ -36,7 +36,7 @@ jobs:
         os: [ubuntu-latest, macos-latest, windows-latest]
         python-version: ["3.10", "3.12"]
     steps:
-      - uses: actions/checkout@v6
+      - uses: actions/checkout@v7
       - uses: astral-sh/setup-uv@v7
         with:
           python-version: ${{ matrix.python-version }}

.gitignore

@@ -18,9 +18,6 @@ Thumbs.db
 *.swp
 *.swo
 
-# Test results
-data/results/
-
 # SynthID corpus reference fills (synthetic black/white calibration tiles,
 # regenerable; the labeled pos/neg/cleaned images ARE tracked, see README)
 data/synthid_corpus/refs/
@@ -46,3 +43,16 @@ data/jimeng_capture/seeds/
 data/jimeng_capture/captures/jimeng_content_*.png
 data/gemini_capture/seeds/
 data/gemini_capture/captures/gemini_content_*.png
+data/samsung_capture/seeds/
+data/samsung_capture/captures/samsung_content_*
+
+# Leftover GFPGAN weights dir from the retired face-restore experiments
+# (GFPGAN wrote RetinaFace/parsing weights to a CWD ./gfpgan/weights/ working
+# dir on first use). Runtime artifact, never committed.
+gfpgan/
+
+# Qwen ControlNet experiment outputs (throwaway eval; never the committed corpus)
+scripts/_qwen_exp_out/
+
+# Local-only working data for analysis (not a committed corpus; never tracked)
+.local-eval/

.python-version

@@ -0,0 +1 @@
+3.12

CLAUDE.md

@@ -1,91 +1,54 @@
-# Remove-AI-Watermarks
+# Remove AI Watermarks
 
-You are a **principal Python engineer** maintaining a CLI tool and library for removing visible and invisible AI watermarks from images.
+You are a **principal Python engineer** maintaining a CLI tool and library for removing visible and invisible AI provenance watermarks.
+
+## Scope and non-goals
+
+The project gives users control over provenance marks on content they generated or edited themselves. It does not automatically remove stock-agency, marketplace, classifieds, tiled-preview, or other marks that protect a third party's paid or copyrighted asset.
+
+- Add visible templates only for AI-generation labels.
+- Do not add stock, agency, or classifieds marks to `watermark_registry.py`.
+- Keep `erase --region` generic and user-directed; do not build an automatic stock-watermark remover on it.
+
+Full boundary and legal context: [`docs/legal-and-safety.md`](docs/legal-and-safety.md).
 
 ## How to run
 
-- `uv run remove-ai-watermarks all <image.png> -o <output.png>`
-- `uv run remove-ai-watermarks visible <image.png> -o <out.png>` — known-visible-mark removal, CPU, no GPU. Reverse-alpha based: each mark is removed by inverting its captured alpha map. `--mark auto` (default) picks the strongest detected of the Gemini sparkle, the Doubao "豆包AI生成" text strip, and the Jimeng "★ 即梦AI" wordmark; `--mark gemini` / `--mark doubao` / `--mark jimeng` force one. Gemini/Doubao recover pixels exactly with no inpaint at native; **Jimeng adds an always-on residual inpaint over the glyph footprint** (its mark re-rasterizes per image, so reverse-alpha alone leaves a faint outline). For arbitrary logos/objects use `erase`.
-- `uv run remove-ai-watermarks erase <image.png> --region x,y,w,h -o <out.png>` — universal region eraser (any logo/object, any position). `--backend cv2` (default, no deps) or `--backend lama` (big-LaMa via onnxruntime, extra `lama`); `--region` is repeatable.
-- `uv run remove-ai-watermarks identify <image>` — provenance verdict (platform + watermark inventory + confidence); `--json` for machine output, `--no-visible` to skip the cv2 sparkle detector
-- `uv run remove-ai-watermarks metadata <image.png> --check` — inspect AI metadata (C2PA, EXIF, PNG chunks)
-- `uv run remove-ai-watermarks metadata <image.png> --remove -o <out.png>` — strip all AI metadata
-- `uv run remove-ai-watermarks batch <directory>` — process every supported image in a directory (output defaults to `<directory>_clean/`, set with `-o`). `--mode visible|invisible|metadata|all` (default `visible`); the invisible/all path reuses the same `--strength`/`--steps`/`--pipeline`/`--device`/`--max-resolution`/`--seed`/`--hf-token` knobs as `invisible`, `--inpaint/--no-inpaint` for the visible pass, and `--humanize` for the Analog Humanizer
+```bash
+uv run remove-ai-watermarks --help
+bash maintain.sh
+```
 
-## Test and lint
-
-- **CI** (`.github/workflows/test.yml`): runs on push to `main` + every PR. A `lint` job (ubuntu: `ruff check` + `ruff format --check`) plus a `test` matrix (ubuntu/macos/windows x py3.10/3.12) that does `uv sync --frozen --extra dev` then `pytest`. The matrix installs only core + dev (no `gpu` extra), so the GPU/model-running tests skip there and it exercises the metadata/identify/visible/cv2-eraser surface on all three OSes. Keep `uv.lock` valid (don't break `--frozen`) when editing `pyproject.toml`. `publish.yml` stays release-only and now verifies the release tag matches the `pyproject.toml` version (fails the build on a mismatch) before building. **Release flow:** bump the version in `pyproject.toml` + `src/remove_ai_watermarks/__init__.py` + `uv.lock` (the project's own `[[package]]` entry, ~line 2868), commit `chore(release): vX.Y.Z`, `git tag -a vX.Y.Z -m vX.Y.Z` (annotated — `git tag` without `-m` errors here), push `main` + the tag, then `gh release create vX.Y.Z` — **PyPI publish triggers on the GitHub Release `published` event, NOT on the tag push**, so the tag alone does not publish. **Sdist must exclude `data/`** (`[tool.hatch.build.targets.sdist] exclude = ["/data"]`): hatchling's default sdist bundles all VCS-tracked files, so the committed `data/` test corpora (synthid_corpus images ~65 MB + the visible-mark captures) pushed the **0.8.0** sdist past PyPI's per-project file-size limit (400 "File too large") — the wheel uploaded but the sdist was rejected, so 0.8.0 shipped wheel-only and 0.8.1 carried the fix. The wheel only ships `src/` (via `[tool.hatch.build.targets.wheel] packages`), so it was never affected. **A failed PyPI upload of one artifact still leaves the other live and you cannot re-upload the same version** — fix the build and cut the next patch. **Build backend is pinned `hatchling<1.28`** (`[build-system] requires`): hatchling 1.28+ emits **Metadata-Version 2.5** (PEP 639), which the twine bundled in `pypa/gh-action-pypi-publish@release/v1` rejects (`"'2.5' is not a valid Metadata-Version"`) — this **failed the v0.8.3 PyPI upload on 2026-06-01** (tag-match + build passed, the upload step failed; nothing was uploaded, so the version stayed empty on PyPI). 1.27.x emits 2.4, which uploads fine (0.8.2 shipped on it). The pin is unpinned `requires = ["hatchling"]` no longer safe because `uv build` pulls the latest hatchling. Lift the pin only once the publish action's twine is ≥ 6.1.0 (2.5-aware) or the workflow moves to `uv publish`.
-- `bash maintain.sh` — uv-outdated, uv-secure, ruff check/fix, ruff format, pyright, pytest -n auto
-- **Strict pyright is clean across `src/` (0 errors).** The cv2/torch/diffusers boundary files (`gemini_engine`, `region_eraser`, `doubao_engine`, `face_protector`, `humanizer`, `invisible_engine`, `noai/watermark_remover`, and the whole `noai/ctrlregen/` subpackage) carry a documented per-file `# pyright:` relax pragma (or, for `ctrlregen`, a `tool.pyright.executionEnvironments` entry) that turns off only the unknown-type / untyped-third-party rules — those libs ship no usable types, so strict typing there fights the ecosystem. Pure-logic files stay fully strict; `typings/piexif/__init__.pyi` is a local stub so `metadata.py`/`extractor.py` resolve piexif. Public ndarray-returning signatures on the relaxed engines are still annotated `NDArray[Any]` so strict consumers (`cli.py`) stay clean. When touching a relaxed file, prefer fixing real issues over widening the pragma; keep the pragma scoped to genuinely-untyped boundaries. (`uv-secure` is clean since idna was bumped 3.11 -> 3.16, fixing GHSA-65pc-fj4g-8rjx.)
-- **Full-project `uv run pyright` (no path) OOMs/crashes node on this ML-heavy repo** (emits a `libnode` stack frame, no summary) — a known environment limit, not a code error. Gate with `uv run --extra dev --extra gpu pyright src/` (completes, authoritative) or scope to changed files; also run `uv run ruff check` and `uv run pytest` directly.
-- Run `uv run` from the repo root — from another cwd it falls back to a bare env without numpy/cv2/torch.
-- To add a dev tool (pytest/ruff/pyright) into the env, use `uv sync --frozen --extra dev --extra gpu`, **never `uv pip install`** — `uv pip install` re-resolves and rewrites `uv.lock`, which silently bumped `transformers` to a build incompatible with the pinned `diffusers` (`cannot import name 'Qwen3VLForConditionalGeneration'`) and broke every `identify`/metadata import. Recovery: `git checkout uv.lock && uv sync --frozen --extra gpu --extra dev`. The `gpu` extra holds `diffusers`/`transformers`/`torch`, so a bare `uv sync` (no extras) removes them; `noai/__init__` is now **lazy** (PEP 562 `__getattr__`, so importing `identify`/`metadata` no longer pulls `watermark_remover`/torch), so a bare env breaks only when the removal pipeline is actually invoked, not on import. `maintain.sh`'s `uv sync --all-extras` also pulls the heavy `trustmark`/`lama` wheels (pytorch-lightning, onnxruntime) — fine on a good connection, but on flaky DNS sync only `--extra gpu --extra dev` and run the lint/test steps by hand.
-- Metadata/C2PA tests assert against real committed fixtures in `data/samples/` (`chatgpt-*.png` = OpenAI C2PA, `firefly-1.png` = Adobe, `mj-*` = Midjourney IPTC, `doubao-1.png` = ByteDance Doubao with the China TC260 `<TC260:AIGC>` XMP label **and** a visible "豆包AI生成" text mark bottom-right; `grok-1.jpg` = xAI Grok with its EXIF-only `Signature:` blob + UUID `Artist` and no C2PA/SynthID/IPTC); synthetic byte blobs cover the JPEG/ISOBMFF format paths. The "non-AI / clean photo" control is no longer in `data/samples/` -- the `clean_photo` conftest fixture serves a verified-negative image from the corpus `neg/` set (skips if the corpus is absent).
-- SynthID reference corpus: `scripts/synthid_corpus.py` ingests labeled images into `data/synthid_corpus/`. The labeled `images/` (`pos/` `neg/` `cleaned/`) are **committed** (public repo -- review every image for private content before adding; `manifest.csv` is kept in sync with the files on disk, one row per tracked image); only the synthetic `refs/` calibration fills are gitignored. See its README for the collection protocol and verification oracles.
+Run `uv` from the repository root. Command selection, options, defaults, and examples live in [`docs/cli.md`](docs/cli.md). Before changing command routing, no-signal behavior, or exit codes, read the command-line section of [`docs/module-internals.md`](docs/module-internals.md).
 
 ## Configuration
 
-- GPU/ML modules (invisible_engine, ctrlregen, watermark_remover) are optional — guard imports with `is_available()` checks
-- Optional detection extras: `detect` (imwatermark — open SD/SDXL/FLUX watermark) and `trustmark` (Adobe TrustMark decoder; pulls torch + downloads weights). Both are guarded by `is_available()` and skipped by `identify` when absent.
-- Tests for the *model-running* paths are limited to availability checks (multi-GB downloads). But the **pure helpers inside ML-adjacent modules are unit-tested without any download** and must stay that way: `_target_size` (native-vs-downscale, `test_invisible_engine.py`), the MPS->CPU fallback control flow via mocked pipelines (`test_img2img_runner.py`, 100% cover), and the tiling math `tile_positions` (now raises `ValueError` when not `0 <= overlap < tile`)/`make_blend_weight`/`resize_center_crop` (`test_tiling.py`; `pytest.importorskip("torch")` since `tiling.py` imports torch at module top). Don't skip these as "ML, needs a model" — only `run_tiled`/`remove_watermark`/the diffusion bodies do.
+GPU and ML modules are optional. Guard their imports with `is_available()`.
 
-## Key modules
+Optional features and installation groups are documented in [`docs/installation.md`](docs/installation.md). Model-running paths may use availability tests, while pure helpers in ML-adjacent modules must remain unit-tested without downloads.
 
-- `noai/c2pa.py` — PNG chunk parser; use `extract_c2pa_chunk(path)` to get raw caBX payload, `has_c2pa_metadata(path)` to detect. Do not reimplement chunk parsing. `extract_c2pa_info(path)` sets `synthid_watermark`/`synthid_vendors` when the manifest is signed by a SynthID-using vendor, and `soft_binding`/`soft_binding_vendors` when a `c2pa.soft-binding` `alg` names a forensic-watermark vendor (`soft_binding_vendors_in(buffer)` is the shared byte-scan, used by both the PNG parser and the non-PNG binary path). PNG/caBX chunk reads are clamped to the remaining file size (`safe_length = min(length, remaining)`; skipped chunks use seek) so a malformed huge `length` cannot drive a multi-GB allocation (shared safety discipline matching `isobmff.scan_c2pa_region`).
-- `noai/constants.py` — PNG_SIGNATURE, C2PA_CHUNK_TYPE, C2PA_SIGNATURES, C2PA_ISSUERS, `SYNTHID_C2PA_ISSUERS` (issuers that pair SynthID with C2PA: Google, OpenAI), and `C2PA_SOFT_BINDINGS` (soft-binding `alg` prefix → forensic-watermark vendor: Adobe TrustMark, Digimarc, Imatag, Steg.AI, Microsoft, ...). Add a new issuer/binding here, not inline.
-- `metadata.py` — `scan_head(path, size=1MB)` is the shared input for every C2PA/AIGC/IPTC byte scan: first `size` bytes plus the payloads of any provenance metadata found beyond that window — for ISOBMFF, the late provenance boxes from `isobmff.scan_c2pa_region` (catches a manifest after a large `mdat`); for **PNG**, the late `tEXt`/`iTXt`/`zTXt`/`eXIf`/`iCCP` chunks from `_png_late_metadata` (catches an XMP/EXIF packet appended after a large `IDAT`, e.g. a TC260 AIGC label at ~2.7 MB). Behavior-neutral (`f.read(size)`) for non-ISOBMFF inputs and for any file that fits within `size`. Use it instead of `open().read(1MB)` for any new marker scan. `synthid_source(path)` returns the vendor name(s) if the C2PA manifest implies a SynthID pixel watermark, else None. Format-agnostic: PNG via the caBX parser, JPEG/WebP/AVIF/HEIF/JXL via a binary scan (C2PA marker + SynthID issuer + AI-source marker). `get_ai_metadata` surfaces the verdict, and `metadata --check` prints it as a callout. Both `get_ai_metadata` and `has_ai_metadata` guard the PIL open with `except Exception` (HEIC/unknown formats raise non-OSError) and fall through to the binary scan. `xai_signature(path)` detects xAI/Grok's EXIF-only scheme (`ImageDescription` = `Signature: <base64>` + UUID `Artist`); it feeds `has_ai_metadata`, `get_ai_metadata` (key `xai_signature`), and `identify`. `iptc_ai_system(path)` detects the IPTC Photo Metadata 2025.1 AI-disclosure XMP properties (`IPTC_AI_FIELD_MARKERS` = `AISystemUsed`/`AISystemVersionUsed`/`AIPromptInformation`/`AIPromptWriterName`) and returns the `AISystemUsed` generator name (or `"fields present"`). `remove_ai_metadata` routes **ISOBMFF video** (`.mp4`/`.mov`/`.m4v`) through the same `isobmff.strip_c2pa_boxes` as AVIF/HEIF (MP4 is ISOBMFF), and `_scrub_ai_exif` removes the xAI signature + AI-generator EXIF tags on JPEG output. `strip_c2pa_boxes` is **fail-safe** on a malformed box: it returns the original bytes unchanged with a logged warning instead of truncating the tail to EOF (detection-only `scan_c2pa_region` still stops at a malformed box). `_png_late_metadata` clamps each late-chunk read to the remaining file size (`safe_length = min(length, remaining)`) so a malformed `length` cannot drive a multi-GB allocation.
-- `identify.py` — the OpenAI rollout caveat is keyed on `_vendor_of(synthid) == "OpenAI"` (not a raw substring over the issuer + verdict blob). `identify(path)` aggregates every locally-readable signal (C2PA issuer→platform, C2PA soft-binding forensic-watermark vendor, IPTC "Made with AI" + IPTC 2025.1 `AISystemUsed`, embedded SD/ComfyUI params, SynthID proxy, xAI/Grok EXIF signature via `metadata.xai_signature`, the China TC260 AIGC label via `metadata.aigc_label`, the HuggingFace `hf-job-id` job marker via `metadata.huggingface_job`, the Samsung Galaxy AI editing marker via `metadata.samsung_genai`, the visible marks — Gemini sparkle plus the ByteDance Doubao 豆包AI生成 / Jimeng 即梦AI text marks via the `watermark_registry` — open invisible watermark, Adobe TrustMark via `trustmark_detector`) into one `ProvenanceReport`. `is_ai_generated` is True or None (never asserted False — stripped metadata is not proof of clean origin). The `hf_job`, visible-mark, and Samsung `samsung_genai` signals are **medium** confidence: each lifts an otherwise-Unknown verdict to a tentative AI (`hf_only` / `visible_only` / `samsung_only`, parallel branches; `visible_only` fires on any `visible_*` signal) but is excluded from the high-confidence `ai_from_metadata` set, so none overrides a hard metadata signal. **Visible-mark detection** (`check_visible`, signals `visible_sparkle` / `visible_doubao` / `visible_jimeng`): the Gemini sparkle keeps its own file-level path (`_visible_sparkle` → `gemini_engine.detect_sparkle_confidence`, promoted only at confidence ≥ `_SPARKLE_THRESHOLD` 0.5; corpus-tuned to separate Gemini sparkles ≥0.56 from non-sparkle ≤0.49), while Doubao/Jimeng reuse the registry detectors (`_visible_text_marks` → `watermark_registry`), each gated by its own engine NCC threshold via `MarkDetection.detected` (Doubao 0.4, Jimeng 0.45). Doubao/Jimeng are normally also caught by the TC260 AIGC metadata label, so the visible path is their stripped-metadata fallback. Visible marks set `platform` only when no harder signal already did, and (like the sparkle) are excluded from integrity-clash vendor claims. The cv2 dependency lives in the engines, not here. **`import identify` is deliberately light** (~21 MB; ~36 MB with cv2 loaded by a visible-mark run, ~106 MB for a full `check_visible` run): it imports only the pure `noai.c2pa`/`noai.constants` submodules, and `noai/__init__` is lazy (see "Test and lint"), so torch/diffusers are NOT pulled at import even in a full `gpu`/`detect` install — fits a 512 MB host. The heavy paths are opt-in: `check_invisible=True` needs the `detect`/`trustmark` extras (each pulls **torch**; TrustMark also **downloads weights**), so on a core-only deploy leave `check_invisible` off (it is a no-op there anyway). Before the lazy `__init__`, the mere presence of torch in the env inflated `import identify` to ~420 MB. **C2PA platform attribution is device-token-first, issuer-scan fallback** (`_device_platform` scans manifest bytes for `_DEVICE_C2PA_PLATFORM` tokens, then `_attribute_platform`/`_ISSUER_PLATFORM`). **Why, verified on real signed files 2026-05-26:** the old issuer-only byte-scan matched ANY issuer substring anywhere, so multi-entity manifests mis-attributed -- Leica→"Truepic" (a signing authority in the trust chain), Nikon→"Adobe Firefly" (XMP-toolkit "Adobe" + the sample's "Adobe_MAX" name), Pixel→"Google (Gemini)" ("Google LLC" cert org), Truepic→"Google". A distinctive device token wins instead. **Token distinctiveness is load-bearing:** bare `b"Truepic"` mis-fires (it appears in unrelated trust chains -- it mis-attributed the OpenAI `chatgpt-1.png` fixture), so the token is the specific `b"Truepic_Lens"` from the Lens SDK claim generator; likewise `b"Pixel Camera"` (cert CN) not bare `b"Pixel"`. `_DEVICE_C2PA_PLATFORM` lists ONLY tokens **verified against a real C2PA file**: Leica (`lc_c2pa`/`Leica Camera`), Nikon (`NIKON`), Pixel (`Pixel Camera` -- from a real Pixel 10 Pro file attached to c2pa-rs issue #1609/#1554), Sony (`sony.sig`/`sony.cert` -- Sony's own C2PA assertion namespace, verified on a real Sony PXW-Z300 file; NOT bare "Sony" which is a common EXIF Make), Truepic (`Truepic_Lens`). Canon/Bria have **no public direct-download C2PA sample** (checked exhaustively: GitHub issue/PR attachments, contentcredentials gallery, HF datasets -- all upload-to-verify or token-gated; Canon's only public file was a self-signed hobbyist CR3, not factory), so they stay unmapped until a real file is captured (same fixture discipline as Grok/Doubao). The Sony sample is video (MP4) -- our ISOBMFF C2PA path detects it; Sony Alpha stills likely share the `sony.*` namespace but are not separately verified. **Samsung Galaxy + ASUS Gallery live in a separate `_SIGNER_C2PA_PLATFORM` (scanned after `_device_platform`, before the issuer fallback), NOT in `_DEVICE_C2PA_PLATFORM`** — verified on real signed files 2026-05-29. Reason: a Galaxy phone stamps BOLine truncated
-- `watermark_registry.py` — **single catalog of known visible watermarks**, the unified "find known marks in their usual places, recognize, remove" entry. **Reverse-alpha based by policy**: a mark is listed only once a real alpha map has been captured for it, and removal inverts that map (`original = (wm - a*logo)/(1-a)`) — Gemini recovers cleanly with no inpaint (its sparkle alpha comes from a pure-black capture, so it is near-exact), while **Doubao and Jimeng both add an always-on THIN residual inpaint** over the glyph footprint (their text marks re-rasterize + jitter a few px per image, so a single capture cannot pixel-cancel them; the inpaint blends into the reverse-alpha-recovered pixels). Arbitrary-region inpainting still lives in `region_eraser`/`erase`. Each `KnownMark` ties a key to {usual `location`, `in_auto` flag, `recovery` (="reverse-alpha"), a `detect` adapter → uniform `MarkDetection`, a `remove` adapter}. Entries today: `gemini` (bottom-right sparkle), `doubao` (bottom-right "豆包AI生成"), and `jimeng` (bottom-right "★ 即梦AI"). `detect_marks` scans all; `best_auto_mark` picks the highest-confidence detection. **Cross-engine confidences aren't directly comparable**, so the gemini adapter applies the corpus-validated 0.5 sparkle threshold (`_GEMINI_AUTO_MIN_CONF`) for its `detected` flag — otherwise the gemini engine's loose internal threshold weakly fires (~0.36) on the Doubao text and hijacks `auto`. The shape-keyed Doubao/Jimeng NCC detectors don't cross-fire (jimeng scores ~0.22 on the Doubao strip, well under its 0.45 threshold), so `auto` picks the right one on a Doubao vs Jimeng image. `cli.cmd_visible` is registry-driven: `--mark auto` → `best_auto_mark`, `--mark <key>` → that mark; `--mark` choices come from `mark_keys()`. `_doubao_remove`/`_jimeng_remove` apply reverse-alpha only when the mark is detected AND `reverse_alpha_available`; outside that, removal is **skipped** (not inpainted). Add a new visible mark = one `KnownMark` entry + its engine (with a captured alpha map); do not re-add per-mark `if` branches in the CLI. **Alpha-on-save policy (issue #30):** `cli._write_bgr_with_alpha` rejoins the input's alpha plane **unchanged** — it must NOT zero alpha in the watermark bbox. Reverse-alpha (and `erase` inpaint) recover real pixels there, so zeroing alpha punched a transparent hole that renders as a solid **white box** on any non-transparent viewer (Gemini app exports are opaque RGBA, so every user hit it; regression-guarded by `test_visible_keeps_alpha_opaque_in_watermark_region`). The registry `remove()` still returns its region (used for `inpaint_residual` positioning), but the CLI no longer uses it to clear alpha.
-- `gemini_engine.py` — visible Gemini-sparkle remover/detector (cv2/numpy, no GPU). `detect_sparkle_confidence(path)` is the file-level entry point used by `identify.py`. The public entry points normalize a grayscale (2D) or RGBA (4-channel) input to BGR up front so a non-BGR image does not crash the cv2 pipeline. **Removal is reverse-alpha with NO inpaint** (`remove_watermark` → `_reverse_alpha_blend`): the sparkle alpha is computed (`alpha = max(R,G,B)/255`) from the bundled sparkle-on-black captures `assets/gemini_bg_{96,48}.png`, which are PURE-BLACK so the alpha is near-exact — re-verified clean on `demo_banana_before.png` 2026-05-31 (the registry's optional `inpaint_residual` is a no-op on a clean removal; an earlier "Gemini smears" read was a misjudged soft-fur original, not an artifact). **The bg assets are now rebuilt from OUR OWN controlled captures** (`data/gemini_capture/captures/`, committed) by `scripts/visible_alpha_solve.py gemini`, which locates the 96px sparkle on the black capture and crops it to the two logo sizes; our capture matched the previously third-party-sourced `gemini_bg_96.png` to **NCC 0.9998**, validating the asset and making it reproducible. Gemini's multi-size fixed-slot model is genuinely different from the Doubao/Jimeng text-strip engines (so it stays a separate engine, not part of the shared-base refactor).
-- `doubao_engine.py` — visible Doubao "豆包AI生成" remover/detector (cv2/numpy, no GPU). `DoubaoEngine.locate` anchors a bottom-right box by **geometry** (mark scales with image WIDTH), `extract_mask` pulls the light, low-chroma glyphs (the detection candidate) using a per-pixel channel-spread proxy `sat = roi.max(axis=2) - roi.min(axis=2)` (no HSV conversion). `detect` is **shape-consistent**: it matches the bundled alpha glyph silhouette (`assets/doubao_alpha.png`) against the candidate via zero-mean normalized correlation (`_template_match_score`, cv2 `TM_CCOEFF_NORMED`), gated at `DETECT_NCC_THRESHOLD` 0.4 over a small `DETECT_MIN_COVERAGE` floor. Keying on glyph SHAPE (not coverage heuristics) fixed #23 (corpus FP 7/1243). **Removal = reverse-alpha + thin residual inpaint** (`remove_watermark_reverse_alpha`): `original = (wm - a*logo)/(1-a)` from the bundled alpha map + `_ALPHA_LOGO_BGR` (pure white) + `_ALPHA_*_FRAC` geometry, then a deliberately THIN inpaint (`_RESIDUAL_*`, `INPAINT_NS`) over the glyph footprint clears leftover edges without smearing. **Alpha is rebuilt by `scripts/visible_alpha_solve.py` (the careful gray-self solve: cubic background fit, mean over channels, full halo, unblurred), same recipe as Jimeng** — the captures are committed in `data/doubao_capture/captures/`. **Removal aligns ALWAYS** (no `_ALPHA_NATIVE_BAND` fast-path): it tries fixed geometry AND `_aligned_alpha_map`'s `TM_CCOEFF_NORMED` scale+position search and keeps the lower-residual one — the mark is re-rasterized and a few px off per image, so fixed geometry alone leaves a visible outline even at 2048. **The locate box (`WM_*`) is generous (0.22 wide, margins 0.004) and reaches close to the corner** — a tight box (the old 0.185 / margin 0.012) let a corner-ward shift fall OUTSIDE the alignment search, so the align missed and a readable outline survived; regression-guarded by `test_recovers_shifted_mark_on_texture` (composes the alpha shifted on a known texture; old box ~29 vs new ~1 mean residual). **Issue #13 follow-up defect (found 2026-05-31): the SHIPPED Doubao removal left a clearly READABLE "豆包AI生成" outline on the real `doubao-1.png` sample, while `detect` returned conf 0.0 (it is fooled by a thin outline) so `test_reverse_alpha_removes_mark` passed and the old "56/56 clean" claim was detector-measured, not visual.** Root cause: bad alpha (under-estimated, max ~0.65) + fixed-no-inpaint + tight box; the careful rebuild + always-align + thin inpaint + wide box takes it from a readable outline to faint texture-level traces (parity with Jimeng — a single capture cannot pixel-cancel a per-image re-rasterized mark). **Lesson: a detector-only removal test is insufficient; assert visual residual (the textured-shift test).** **`extract_mask` guards a degenerate ROI (`bh < 16 or bw < 16` -> empty mask, skips cv2):** the always-align removal scores each placement with a residual `detect(out)`, and on an extremely wide/short image (e.g. 2048x1, `test_wide_short_does_not_raise`) that fed cv2's GaussianBlur a ~1-px-tall ROI and **faulted natively on Windows py3.12 (access violation, non-deterministic — one CI cell went red while a re-run passed)**; the old at-native path never ran `detect` on degenerate sizes. Real images always clear the guard (the `WM_*` box floors are `max(16, …)` height / `max(40, …)` width), so it only short-circuits slivers. `reverse_alpha_available` is just "asset present"; the registry gates removal on `detect`. The shipped third-party `_refs/zhengsuanfa_doubao_alpha_120x20.png` is NOT a usable alpha (verified 2026-05-29). Arbitrary-region inpainting is `region_eraser`/`erase`.
-- `jimeng_engine.py` — visible Jimeng / Dreamina "★ 即梦AI" remover/detector (cv2/numpy, no GPU), built 2026-05-30 from issue #13's solid captures (@powersee). Mirrors `doubao_engine`: `locate` anchors a bottom-right box by **geometry** (scales with WIDTH), `extract_mask` pulls the light low-chroma glyphs (white top-hat + grayish + min-luma), `detect` matches the bundled "即梦AI" glyph silhouette (`assets/jimeng_alpha.png`) via `TM_CCOEFF_NORMED` over a coverage floor. Threshold `DETECT_NCC_THRESHOLD` **0.45** cleanly separates real Jimeng marks (>=0.81) from the Doubao strip (0.21) and other AI output (0.0), so the two ByteDance marks don't cross-fire in `--mark auto`. **Logo is pure white (255,255,255)** (`_ALPHA_LOGO_BGR`; the white capture + an L-pair-solve confirm ~254.6); compositing is **sRGB, not linear** (a linear-light solve tripled the cross-residual). **Alpha rebuilt by `scripts/visible_alpha_solve.py` from the GRAY capture** (`data/jimeng_capture/captures/`, the solid captures now committed): `a = (I - B)/(255 - B)`, B a per-capture **cubic** background fit over the non-glyph pixels, **averaged over channels, full halo extent (down to a~0.02), unblurred**. Gray (bg ~132) is the deliberate choice over black: it is the best proxy for real content (the mark sits on bright photo areas, not on black), and the careful build drops the gray self-residual to ~1.3. **The mask quality, not the method, was the earlier limit** — a max-channel / quadratic-bg / blurred / halo-truncated build (and a black-dominated LS) left a visible outline (lesson from issue #13: when reverse-alpha leaves a ghost, suspect the captured alpha map before adding heuristics or switching method). Geometry emitted by the solver at `_ALPHA_NATIVE_WIDTH` 2048: `_ALPHA_WIDTH_FRAC` 0.202, `_ALPHA_HEIGHT_FRAC` 0.058, margins ~0.029. **Removal = reverse-alpha + a deliberately THIN residual inpaint** (`remove_watermark_reverse_alpha`, `_RESIDUAL_DILATE` 5 over the `_RESIDUAL_ALPHA_FLOOR` 0.05 footprint, `_RESIDUAL_INPAINT_RADIUS` 2, `INPAINT_NS`): a single 2048 alpha cannot pixel-cancel the mark re-rasterized at another resolution (alpha maps from independent captures correlate 0.998, not 1.0; off-native reverse-alpha alone only halves the mark), so a tight inpaint clears the residual edges WITHOUT the texture/edge smear a wide full-footprint pass caused. **Placement ALWAYS tries fixed geometry AND `_aligned_alpha_map`'s NCC scale+position search, keeping the lower-residual** — the mark re-rasterizes + jitters a few px per image even at the captured width, so fixed geometry alone misses (there is no `_ALPHA_NATIVE_BAND` fast-path; the scale search `_ALPHA_ALIGN_SEARCH` is fine-stepped, and the `WM_*` locate box is generous so a corner-ward shift stays inside the search — the same widen that fixed Doubao). Verified clean on the solid captures (native 2048; faint self-residual ~1.3 visible only on a dead-flat field, hidden by real texture) and a real 1440-wide Jimeng download (off-native, table edge preserved). `reverse_alpha_available` is just "asset present"; the registry gates on `detect`. **No committed real sample** (the real content download stays gitignored; only the solid calibration captures are committed) — `tests/test_jimeng_engine.py` synthesizes a mark from the bundled alpha asset, and `test_recovers_shifted_mark_on_texture` guards the align-on-shift path that the Doubao defect exposed. Jimeng images are independently caught by the China TC260 AIGC label in `metadata`/`identify`, so this engine is the visible-mark *removal* path, not a new `identify` signal.
-- `region_eraser.py` — universal region eraser (`erase` CLI). `erase(image, boxes=|mask=, backend=)` normalizes grayscale (2D) and RGBA (4-channel) inputs up front (`erase_cv2` splits off any alpha plane and re-attaches it on the result): `boxes_to_mask` → `cv2.inpaint` (`cv2` backend, default, no deps) or big-LaMa via onnxruntime (`lama` backend, extra `lama`, `Carve/LaMa-ONNX` Apache-2.0 model downloaded on first use, never bundled). `erase_lama` crops a padded region around the mask, runs LaMa at its fixed 512² input, pastes only masked pixels back (untouched areas stay pixel-exact). Lazy `_get_lama_session` singleton; `lama_available()` guards the optional import. **LaMa-ONNX costs ~3.5-4 GB peak RAM and ~5-6 s/call on CPU** (FFC working set, not arena — `enable_cpu_mem_arena=False` does not help), so it does NOT fit a minimal droplet; the cv2 backend (tens of MB, ~30 ms) does. LaMa quality at low RAM = serverless/GPU, mirroring how raiw.cc offloads SDXL to fal.
-- `invisible_watermark.py` — `detect_invisible_watermark(path)` decodes the OPEN DWT-DCT watermarks (public decoder, no key) embedded by Stable Diffusion / SDXL / FLUX via the `imwatermark` library. Known fixed patterns (verified against upstream source) live in `_BITS_48` (SDXL 48-bit, FLUX.2 48-bit) and `_SD1_STRING` ("StableDiffusionV1", SD 1.x/2.x). Optional dep (extra `detect`); returns None when absent. The `detect` extra pulls **torch** transitively (invisible-watermark declares torch a hard dep, and `WatermarkDecoder` eagerly imports `rivaGan` -> `torch` at import time), so detection needs torch present even though dwtDct runs CPU-only on cv2/numpy/pywavelets — no GPU and no separate `gpu` extra required. **Unlike SynthID this is locally detectable**, but the watermark is fragile (does not survive JPEG re-encode/resize — verified gone after JPEG q90), so it confirms origin only on pristine files. Add new known patterns here. The file carries a top-of-module pyright pragma because imwatermark/cv2 ship no type stubs.
-- `trustmark_detector.py` — `detect_trustmark(path)` decodes the OPEN, keyless **Adobe TrustMark** watermark (the soft binding behind Adobe Durable Content Credentials, `alg` `com.adobe.trustmark.P`) via the optional `trustmark` package (extra `trustmark`; pulls torch, downloads model weights on first use). Mirrors `invisible_watermark.py` (lazy singleton guarded by a double-checked `threading.Lock` so concurrent callers do not double-download the weights, top-of-module pyright pragma, returns None when absent). It detects *provenance*, not AI origin as such (TrustMark also marks human-authored content), so `identify` lists it as a watermark without setting `is_ai_generated`. Other soft-binding vendors (Digimarc/Imatag/Steg.AI/...) have no public decoder — they are only *named* via the `C2PA_SOFT_BINDINGS` scan, not decoded. **False-positive gate (added 2026-05-29):** TrustMark's `wm_present` is a BCH error-correction validity flag that spuriously validates on a content-correlated fraction of un-watermarked images — AI-generated textures trip it far more than camera photos (verified 2026-05-29 on real files: it fires on Gemini/OpenAI/Doubao output that *cannot* carry Adobe's watermark, with a random-bytes decoded secret, while signal-free camera photos did not trip it). A genuine TrustMark is a *durable* soft binding engineered to survive re-encoding, so `detect_trustmark` re-decodes after a mild JPEG round-trip (`_survives_reencode`, `_REENCODE_QUALITY` 95) and requires the same schema both times; every observed false positive collapsed (none survived even q95), so the gate is the durability property the watermark guarantees. The second decode runs only on the rare initial hit, so the cost is negligible. Do NOT remove the gate to "catch more" — a lone TrustMark hit without it is almost always content noise.
-- `text_protector.py` — text-region protection for the `invisible` SDXL img2img pass (issue #21: CJK/small text deforms at watermark-removal strengths). `is_available()` gates on `cv2.dnn.TextDetectionModel_DB`; `TextProtector.detect_text_boxes(bgr)` runs the **PP-OCRv3 DB** ONNX detector (~2.4 MB, Apache-2.0, opencv_zoo, returns rotated quad polygons) — downloaded+cached to `~/.cache/remove-ai-watermarks` on first use via atomic temp-rename, never bundled, **no torch (cv2.dnn only)**. **Detection is script-agnostic** (DB segments text *regions*, not characters), so Latin / Cyrillic / CJK / Hangul / Arabic / digits all detect identically — language was never the recall lever, **resolution was**. `_detection_input_size(h, w)` (pure, unit-tested) detects at the **native long side capped at `_DET_MAX_LONG_SIDE` (1536), never upscaled**: the old fixed 736 downscaled large canvases so small text fell below the detector and was missed (issue #14, e.g. ~16 px text on a 2048 image). `scripts/text_detection_benchmark.py` measures recall across scripts × sizes × canvas: the cap fix lifts overall hit-rate 0.91 → 1.00 (worst cell 2048/16 px: 0.06 → 1.00) at ~100 ms CPU. Very large canvases with tiny text may still need tiling (documented limit, not built). `build_change_map(boxes, h, w, preserve=0.9, feather=15)` paints a Differential-Diffusion change map. **Polarity (verified empirically):** white(1.0)=PRESERVE original pixels, black(0.0)=MAX change; map is black bg + `preserve` inside text polygons, Gaussian-feathered edges, clipped to [0,1]. `preserve` stays below a hard 1.0 freeze by default so text still scrubs lightly (SynthID survives cropping). **Default text protection is `watermark_remover._run_region_hires`, NOT the differential change map.** Differential Diffusion froze text in latent space (`preserve`<1.0), so the watermark survived *inside* text — violating the "remove SynthID everywhere" requirement; and the SDXL VAE's 8px latent cell softens sub-8px strokes regardless of `preserve` (architectural limit, confirmed by the DD authors — see `docs/text-protection-research.md`). `_run_region_hires` instead: (1) scrubs the whole image (plain img2img), (2) RE-scrubs each detected text block at HIGH resolution and feather-composites it back. `merge_text_regions(boxes,h,w)` groups boxes into local blocks; each crop is upscaled by `_REGION_HIRES_SCALE` 3.0 (applied as an integer factor via int(...), capped so a region stays under `_REGION_MAX_MEGAPIXELS` 1.3 to avoid OOM; skipped if it can't reach 2x — very large text areas then fall back to the global scrub, tiling is the future fix), img2img-scrubbed, downscaled, **phase-correlated back to the original crop to null the ~1-2px round-trip offset** (the shift is applied only on a confident, small correlation -- `response > 0.3` and `|shift| < 4` -- so a spurious large offset on a flat crop no longer garbles the composite; and after a CPU fallback the generator is dropped before the per-region passes to avoid an MPS-vs-CPU generator device mismatch) (a sub-pixel shift garbles the composite even when text is crisp; integer scale alone did NOT fix it because the diffusion pipeline rounds dims to a multiple of 8), then `feather_paste`d. Every pixel is regenerated, so the watermark is removed everywhere AND small text stays crisp (high-res strokes span >1 latent cell). Validated on synthetic 18px multilingual text: text-region SSIM 0.28 (plain) → 0.48 (region-hires), visually garbled → readable across Latin/Cyrillic/CJK, residual shift ~0.5px. Gated to the SDXL `DEFAULT_MODEL_ID` + detector (`_can_protect_text`); no text → plain global scrub (text-free inputs pay only the cheap cv2 detection). CLI opt-in `--protect-text` on `invisible`/`all` (**OFF by default** — see SynthID bullet). `merge_text_regions` + `feather_paste` are pure, unit-tested without a model (`tests/test_text_protector.py`). **The high-res re-scrub can shield SynthID in text regions** (verified 2026-06-01: same gpt-image, with `--protect-text` → SynthID detected by oracle; without → SynthID removed). The mechanism: the global pass at step 1 removes SynthID everywhere, but the per-region high-res re-scrub at step 2 regenerates those pixels from a higher-resolution crop -- if the per-region strength is insufficient at the effective upscaled resolution, SynthID can reconstitute. Until this is resolved, `protect_text` is EXPERIMENTAL and OFF by default. The legacy `_run_differential` / `build_change_map` / `_load_differential_pipeline` (community `pipeline_stable_diffusion_xl_differential_img2img`, `custom_revision="0.38.0"`) remain in the file but are no longer the default; the diff pipeline upcasts the VAE to fp32 internally, so do **not** add `upcast_vae()`/`enable_attention_slicing` there (NaN/black on fp16 MPS). `build_change_map` is still unit-tested.
-- `face_protector.py` — YOLO detect + soft-blend pattern; mirror this for any "protect region during diffusion" features. The expensive extract+blend already runs only when a face is found, but the YOLO detector itself always loads+runs to decide; CLI opt-in `--protect-faces` on `invisible`/`all` (**OFF by default**, experimental). **Face protection has an even more direct SynthID-preservation mechanism than text protection:** it extracts face regions from the ORIGINAL (watermarked) image BEFORE the diffusion pass, then blends those original pixels BACK after the global pass. Those restored pixels are the unprocessed originals -- SynthID is guaranteed to survive in face regions (not just possibly, as with text re-scrub). Any image with faces processed with `--protect-faces` will have SynthID intact in the face areas regardless of strength.
-- `humanizer.py` — optional post-process "humanize" effects (cv2/numpy). The chromatic-shift step replicates the border instead of wrapping opposite-edge pixels, so a shifted channel no longer bleeds the far edge into the near one.
-- `image_io.py` — Unicode-safe cv2 IO (issue #17). `imread(path, flags=None)` / `imwrite(path, img)` wrap `np.fromfile`+`cv2.imdecode` / `cv2.imencode`+`tofile` so non-ASCII paths work on Windows -- bare `cv2.imread`/`cv2.imwrite` use the platform ANSI code-page API there and fail (empty decode + `can't open/read file`) on Chinese/Cyrillic/accented filenames. `imread` keeps `cv2.imread` semantics (defaults to `IMREAD_COLOR`, returns `None` on missing/empty/undecodable). **Every cv2 file read/write in the package routes through here; do not call `cv2.imread`/`cv2.imwrite` directly.** `imwrite` returns `False` on an unwritable path (`OSError` caught) instead of raising, matching `cv2.imwrite` semantics. macOS/Linux already accept UTF-8 paths, so it is behavior-neutral there (the bug only reproduces on Windows). cv2/numpy are imported lazily inside the functions, so the module is cheap to import in a bare env.
+## Test and lint
 
-### Doubao clean-reverse-alpha distillation (re-investigated 2026-05-29)
+`maintain.sh` runs dependency freshness and security checks, Ruff, Pyright scoped to `src/`, and the parallel test suite. Full-project Pyright is not the project gate because the ML dependency graph can exhaust Node memory.
 
-**RESOLVED 2026-05-29: black+gray Doubao captures were obtained and a reverse-alpha is built** (`doubao_engine.remove_watermark_reverse_alpha`, `assets/doubao_alpha.png`; see the `doubao_engine.py` bullet above). The captures (`data/doubao_capture/captures/`, now committed) confirmed the alpha-composite model: on black `captured = a*logo`, logo pure white. **UPDATE 2026-05-31 (issue #13 follow-up): the first build was NOT "exact"** — it left a readable "豆包AI生成" outline on the real sample (the detector was fooled, conf 0.0). The alpha is now rebuilt by `scripts/visible_alpha_solve.py` (the careful gray-self solve shared with Jimeng), removal always-aligns + thin-inpaints, and the locate box was widened; see the `doubao_engine.py` bullet. The notes below (the failed content-image distillation) are retained as the record of why controlled captures were necessary.
+Command, gate, typing, and model-test invariants auto-load from [`.claude/rules/development.md`](.claude/rules/development.md). Environment recovery, CI behavior, and fixture policy live in [`docs/development.md`](docs/development.md).
 
-**Conclusion (historical): pure reverse-alpha distilled from content images does NOT work, and the blocker is the WRONG kind of data, not too little of it.** The earlier framing ("need ~5-8 PRISTINE same-resolution originals") is obsolete -- `data/spaces/originals/` holds plenty. Curate them with `DoubaoEngine.detect` + an NCC filter against a clean glyph template, keeping only marks at offset ≈ (0,0): that yields e.g. **15 pixel-aligned 2048² marks** (sub-pixel drift, not the ±50 px the old lossy/mixed-res scrapes had), plus 1086x1448 / 1792x2400 clusters. With those, LaMa-clean `O` + weighted-LS (and per-pixel I-on-O regression) for `α` (+ logo colour) was tried end-to-end and **still leaves a persistent ghost outline.**
+Before a release, read [`docs/release-and-distribution.md`](docs/release-and-distribution.md). Keep the source-distribution exclusion for `data/`.
 
-Diagnosed why, empirically (cached stacks, `/tmp/doubao_distill`): (1) the mark is a clean white overlay with **no dark halo** -- over glyph pixels ~54% are brighter than the clean bg, only ~4% darker -- so the white-logo model `I=(1-α)O+α·255` is correct; (2) but content backgrounds are almost never dark *under* the mark (median darkest available bg over glyph pixels = **58/255**; only ~13% of mark pixels are ever observed on a bg < 40), so on bright backgrounds the equation is ill-conditioned and `α` is unidentifiable; (3) LaMa's `O` is a plausible **hallucination**, not the true pre-mark background, which compounds the error, and per-pixel regression on ~15 obs overfits into colour noise.
+## Module architecture
 
-**Why Gemini's engine is clean (verified in GeminiWatermarkTool `src/core/watermark_engine.cpp`): its alpha map is the watermark stamped on a PURE-BLACK background**, where `watermarked = α·255 + (1-α)·0 = α·255`, so `alpha = capture/255` exactly -- no estimation. (`gemini_bg_*.png` is literally the sparkle in grey on black.) So the real Doubao unlock is the same controlled capture, **not more content images**. Black/white/gray seeds exist (`data/doubao_capture/seeds/seed_*_1x1_2048x2048.png`); a capture run (feed a black seed through doubao.com edit mode, download the *original*) was requested from the #13 reporter 2026-05-29. With ~2-3 black captures we get `α = capture/255` for free, Gemini-quality.
+[`docs/module-internals.md`](docs/module-internals.md) is the canonical per-module map, including design decisions, thresholds, calibration history, incident records, and regression guards. Read the relevant section before changing a subsystem.
 
-**Until black captures arrive, the shipped direction is precise canonical glyph mask + inpaint (cv2 default, lama optional), NOT reverse-alpha.** The consensus glyph silhouette across the aligned marks distills cleanly (proto: a tight "豆包AI生成" strip, width ≈ 0.156 × image-width) and is good both as an exact inpaint mask and as an NCC localiser -- the latter also fixes the #23 detector false-positives (match the real glyph shape, not any bright low-saturation corner). Do **not** retry content-image reverse-alpha: it is data-limited by physics (no dark-background observations), not by effort.
+Research and current constraints are routed through [`docs/index.md`](docs/index.md), especially [`docs/known-limitations.md`](docs/known-limitations.md), [`docs/supported-signals.md`](docs/supported-signals.md), [`docs/synthid.md`](docs/synthid.md), and [`docs/watermarking-landscape.md`](docs/watermarking-landscape.md).
 
-## Watermarking landscape (research 2026-05-24)
+## Data safety
 
-Who embeds what, and whether it is locally detectable (so we know which gaps are fillable). See `identify.py` for what we read.
-- **Locally detectable (open decoder, no key/API):** Stable Diffusion / SDXL / FLUX via `imwatermark` DWT-DCT (now covered by `invisible_watermark.py`). FLUX uses the same library (`black-forest-labs/flux2` `src/flux2/watermark.py`, 48-bit `0b001010101111111010000111100111001111010100101110`); SDXL is the diffusers `WATERMARK_MESSAGE` (`0b101100111110110010010000011110111011000110011110`). Caveat: fragile to re-encoding.
-- **C2PA / IPTC (covered by the issuer/marker scan):** OpenAI, Google, Adobe Firefly, Microsoft (Designer + **Bing Image Creator** — collected 2026-05-24; Bing now runs Microsoft's own **MAI-Image** model, signs C2PA as "Microsoft", NOT OpenAI/DALL-E), and **Stability AI** (collected from Brand Studio / DreamStudio successor; signs C2PA as "Stability AI Ltd", no SynthID, no imwatermark on its current Stable Image model — issuer added to `C2PA_ISSUERS`). Still unsampled: Canva (its downloads are re-encoded design *exports* that strip C2PA, so a Canva "positive" is inconclusive — skipped), Getty, Shutterstock. Midjourney embeds NO C2PA and no invisible watermark (our `mj-*` sample carried only the IPTC tag). **Samsung Galaxy AI** (Generative Edit / Sketch to Image / Portrait Studio on Galaxy S23 FE / S24 / S25, One UI 7+) signs C2PA as "Samsung Galaxy" with the standard `trainedAlgorithmicMedia` source type AND a proprietary `genAIType` marker; verified on real signed files 2026-05-29 (the standard scan catches the source type; `genAIType` additionally catches a Galaxy S24 file that omits it). **ASUS Gallery** also signs edited photos as C2PA (`com.asus.gallery`) but with no AI source type — a signer, not an AI marker. **Black Forest Labs (FLUX)** API output signs C2PA: `claim_generator_info "Black Forest Labs API"` + a `c2pa.ai_generated_content` assertion + `trainedAlgorithmicMedia` (issuer `b"Black Forest Labs"` added to `C2PA_ISSUERS`, platform "Black Forest Labs (FLUX)"). **ByteDance Volcano Engine (Volcengine)** — the cloud behind Doubao / Jimeng — signs its AI image output with a cert from `certificate_center@volcengine.com` + `trainedAlgorithmicMedia` (issuer `b"volcengine"` → "ByteDance (Volcano Engine)", platform "ByteDance (Doubao / Jimeng / Volcano Engine)"); note this is the C2PA-signed surface, distinct from the XMP/PNG TC260 `AIGC` label Doubao also uses. All three verified on real signed files 2026-05-29.
-- **EXIF/XMP generator tag (caught by `exif_generator`):** **Ideogram** writes EXIF `Make="Ideogram AI"` (collected 2026-05-24 — no C2PA, no SynthID, no imwatermark; the Make tag is the only signal).
-- **xAI / Grok — its own EXIF signature scheme, NOT C2PA (DETECTED by `metadata.xai_signature`, built 2026-05-26).** Grok JPEG downloads (Aurora model) carry **no C2PA, no XMP, no SynthID, no IPTC** — only EXIF `Artist` = a UUID and EXIF `ImageDescription` = `Signature: <base64>` (a crypto signature, unverifiable locally without xAI's public key). This empirically kills the earlier unverified "xAI signs C2PA as xAI" lead — xAI is not even a C2PA member. `exif_generator` misses it (neither field holds an `AI_GENERATOR_TOKENS` token), so a dedicated detector `xai_signature(path)` matches the pair (`ImageDescription ~ ^Signature: [A-Za-z0-9+/=]{64,}` AND UUID `Artist`); wired into `has_ai_metadata`, `get_ai_metadata` (key `xai_signature`), and `identify` (signal `xai_signature`, platform "xAI (Grok / Aurora)"). **Format confirmed stable across n=3 genuine generations:** exactly three EXIF tags (`Artist`, `ExifOffset`, `ImageDescription`), `Signature:` prefix constant, base64 payload 300-1004 chars. Two capture facts: (a) the `Artist` UUID **equals the public image id** in the asset URL (`https://imagine-public.x.ai/imagine-public/images/<uuid>.jpg`), so it is NOT a private per-user secret — only the `Signature` blob is; (b) the Grok web-UI image is a re-encoded **WebP with no signature** — the EXIF survives only in the *original* JPEG (download button or that public tokenless URL), which is why screenshots / re-encodes are metadata-stripped. A real fixture `data/samples/grok-1.jpg` plus **synthetic** JPEG fixtures (fake UUID + fake `Signature:` blob) cover the detector; never add a real Grok image carrying private content (the repo is public). **Stripped on removal too:** `remove_ai_metadata` now calls `_scrub_ai_exif` on the JPEG EXIF, which deletes the xAI Signature+UUID-Artist pair **and** any `Software`/`Make`/`Artist`/`ImageDescription` tag holding an `AI_GENERATOR_TOKENS` token (so Ideogram's `Make="Ideogram AI"` is scrubbed too), while keeping genuine camera/editor EXIF. The shared `_is_xai_signature_pair` helper (module-level compiled regexes) is the single source of truth for the pattern, used by both `xai_signature` and `_scrub_ai_exif`. (AVIF/HEIF/JXL still strip only C2PA boxes via `isobmff`, not EXIF — unchanged.)
-- **China TC260 AIGC label (caught by `AIGC_MARKERS` / `metadata.aigc_label`, surfaced by `identify` as the `aigc` signal):** China-served generators embed an XMP `<TC260:AIGC>{"Label":"1","ContentProducer":...}` block — China's mandatory AI-content labeling (TC260 namespace `tc260.org.cn/ns/AIGC`). **Doubao** (ByteDance) uses it (verified on the real #13 sample 2026-05-25; `ContentProducer` `001191110102MACQD9K64010000`, no C2PA/SynthID/imwatermark — the XMP block is the only signal; GitHub attachment upload did NOT strip it). The same standard is mandatory for Jimeng/Kling/Qwen/Ernie etc., so the one marker covers the whole China-AIGC-labeled ecosystem. `aigc_label` reads **three serializations** through a shared `_parse` helper: the HTML-entity-encoded XMP `TC260:AIGC` block in **either RDF form** — the nested element `<TC260:AIGC>{...}</TC260:AIGC>` (Doubao) or the attribute `TC260:AIGC="{...}"` (**PicWish**, `ContentProducer="picwish"`, verified on the corpus 2026-05-30) — via a container-agnostic raw-byte scan (any JSON object accepted), a raw-JSON PNG `AIGC` tEXt chunk (Doubao also writes the label this way, no namespaced marker at all — confirmed on the corpus 2026-05-28, `ContentProducer="doubao"`), **and** a bare raw-JSON `{"AIGC":{...}}` object embedded in **JPEG EXIF (UserComment)** by some China-served generators, brace-matched from the scan head with `json.JSONDecoder().raw_decode` (no namespaced marker, no PNG chunk — confirmed on the corpus 2026-05-30, `ContentProducer="001191440300708461136T1308L"`). Both generic forms (the PNG chunk and the bare `{"AIGC":...}` object) are gated on at least one TC260 field (`_TC260_FIELDS`) so a generic `AIGC` key cannot false-positive; the namespaced XMP element is unambiguous and needs no gate. In `identify`, `aigc` fires on the parsed label **or** the `AIGC_MARKERS` byte scan (the latter preserves the laundering-tell case where the JSON payload is truncated).
-- **HuggingFace-hosted job (caught by `metadata.huggingface_job`, surfaced by `identify` as the `hf_job` signal, MEDIUM confidence):** HuggingFace Jobs / Spaces stamp generated PNGs with an `hf-job-id` tEXt chunk holding the job UUID (3 on the corpus 2026-05-28, no other signal). It marks the *hosting job*, not a model — most commonly diffusion output — so it lifts an Unknown verdict to a tentative AI via `hf_only` (parallel to the visible sparkle) but never overrides a hard metadata signal; `_HF_JOB_CAVEAT` states the limit (job, not model; not proof of AI pixels). Stripped on removal (the PNG save whitelist keeps only `STANDARD_METADATA_KEYS`, so `hf-job-id` and the `AIGC` chunk are both dropped). The exact writer is not authoritatively documented (HF Jobs are generic GPU jobs), hence medium not high.
-- **No detectable signal on download (correctly reported `unknown`):** **Recraft** (PNG export is a re-encoded design export — strips everything), **Krea hosting FLUX 2** (no imwatermark despite FLUX — the host omits the encoder, same as Stability's hosted SDXL), and Midjourney (embeds nothing). Lesson: the imwatermark detector only fires on *pristine* output from a pipeline that runs the encoder (diffusers default, official BFL), not from re-hosts (Krea/Stability) or re-encoded exports (Recraft/Canva).
-- **Invisible but NOT locally detectable (proprietary, API/oracle only — same wall as SynthID):** Amazon Titan Image Generator + Nova Canvas (Bedrock `DetectGeneratedContent` API), Kakao (new SynthID image adopter, May 2026), NVIDIA Cosmos (SynthID video). No local detector possible; treat like SynthID.
-- **C2PA 2.4 "Durable Content Credentials" (April 2026; verified against the spec) raise the bar for metadata stripping.** 2.4 defines soft bindings (an invisible watermark or a content fingerprint) plus a server-side manifest repository and a new `c2pa.repository-receipt` assertion. Per the spec: "if a C2PA manifest is removed from an asset, but a copy of that manifest remains in a provenance store elsewhere, the manifest and asset may be matched using available soft bindings." So our local `metadata --remove` deletes the *embedded* manifest, but a fingerprint/watermark soft binding can still re-link the image to its manifest in a repository server-side. Stripping the file is becoming necessary-but-not-sufficient against durable provenance. (Our parsers target the stable embedded-manifest format documented in C2PA 2.1 §11; that format is unchanged in 2.4 -- the new pieces are repository/soft-binding infra, not the on-file box layout, so no parser change is implied.) Spec: https://spec.c2pa.org/specifications/specifications/2.4/specs/C2PA_Specification.html We now READ the soft-binding `alg` (`C2PA_SOFT_BINDINGS` / `soft_binding_vendors_in`) to name the forensic-watermark vendor, and locally DECODE the one open scheme, Adobe TrustMark (`trustmark_detector`); the rest (Digimarc/Imatag/Steg.AI/...) stay name-only (proprietary decoders).
-- **Built 2026-05-26 (this batch):** soft-binding `alg` vendor detection; IPTC Photo Metadata 2025.1 AI-disclosure fields (`AISystemUsed` etc.); **video C2PA metadata** detect + strip for MP4/MOV/M4V (free — `isobmff.py` is format-agnostic, MP4 is ISOBMFF); Adobe TrustMark open decoder. NOT done (out of cheap reach, per the feasibility review): visible video-logo removal (needs a video frame pipeline) and audio (SynthID/ElevenLabs/Resemble/Suno all oracle-only or unmarked). **Box detection window — now handled (v0.6.8):** detection no longer relies on a fixed first-MB read. `metadata.scan_head(path, size)` reads the first `size` bytes and, for ISOBMFF, appends the payloads of late provenance boxes found by `isobmff.scan_c2pa_region` (a file-seeking top-level box walker that skips past `mdat` by size without reading it), so a C2PA/AIGC/IPTC manifest placed AFTER a large `mdat` in a streaming/non-faststart MP4 is now caught. Every C2PA/marker byte scan (`has_ai_metadata`, `aigc_label`, `iptc_ai_system`, `synthid_source`, `exif_generator` XMP, `get_ai_metadata` soft-binding, and `identify`) goes through `scan_head`; it is behavior-neutral for non-ISOBMFF inputs (exactly `f.read(size)`). **Meta-box XMP removal — now handled (v0.6.9):** an AI-label XMP packet stored as a meta-box `mime` item (HEIF/AVIF; out of reach of the top-level box stripper) is blanked in place by `isobmff.blank_ai_xmp_packets` — it locates the packet by its `<?xpacket begin … end?>` delimiters and, if it carries an AI marker (`_AI_LABEL_MARKERS`), overwrites it with spaces of the SAME length, so box sizes / `iloc` offsets stay valid and the coded image is untouched (selective: plain non-AI XMP is left alone, mirroring the top-level uuid logic). Wired into `remove_ai_metadata`'s ISOBMFF branch after `strip_c2pa_boxes`. The remaining gap is an `Exif` meta-box *item* (rare; the AI labels are XMP) — still needs `iinf`/`iloc` surgery or exiftool.
-- **Regulatory driver (context, not a code change):** AI-content labeling mandates are expanding, which pushes more generators toward exactly the C2PA + watermark signals we read. The full per-jurisdiction table lives in README "## Legal" -- keep it there, not duplicated here. Newly added + primary-source verified 2026-05-26: **EU AI Act Article 50** machine-readable marking applicable **2026-08-02** (verified against the article text); **South Korea AI Framework Act Art. 31(3)** in force since **22 January 2026** (verified via Kim & Chang + FPF/Korea Times; Enforcement Decree accepts an invisible-watermark label); **California AB 853** (amends the CA AI Transparency Act) latent-disclosure duty operative **2026-08-02**, requiring a disclosure "permanent or extraordinarily difficult to remove" (verified against the leginfo bill text -- this is the exact disclosure our tool strips); **India IT Amendment Rules 2026** in force **2026-02-20** (verified via Chambers), which prominently-label + permanent-provenance-id all synthetic media AND **expressly prohibit removing/suppressing the label or metadata** -- the first major all-content removal ban outside China. **Removal liability (README "## Legal" disclaimer):** the tool is lawful general-purpose software; liability sits with the remover and is intent-gated -- downstream acts (fraud/deception/IP), plus US DMCA 17 USC 1202 (removing copyright-management info to conceal infringement), plus the removal-as-such bans in China + India. When extending the README table, verify each date/article against the statute/bill text before committing, not against search summaries.
+Follow [`data/README.md`](data/README.md) for public fixture, calibration, oracle, and evaluation layout. Store each tracked binary once and keep generated evaluation outputs outside the repository.
 
-## Known limitations
+## Rules and conventions
 
-- `invisible` pipeline processes at **native resolution by default** (`max_resolution=0`), matching the hosted raiw.cc backend (fal fast-sdxl, no pre-downscale). The old forced downscale-to-1024 -> upscale-back round-trip was the main quality loss (issue #10) and is gone; at strength ~0.05 SDXL img2img does not need the ~1024 downscale. `--max-resolution N` re-introduces an opt-in long-side cap purely to bound GPU/MPS memory on very large inputs (it reintroduces the lossy round-trip). For huge images that OOM at native, tile-based diffusion is still the proper long-term fix. **Concrete MPS data points (the OOM is memory-tier-dependent, NOT a hard MPS limit):** on a ~24 GB unified-memory machine (verified 2026-05-25, 1254x1254 gpt-image SDXL, fp32) native res OOMs at the *UNet* step (peak ~17 GiB), not only the VAE decode, and the auto-fallback in `img2img_runner` reloads on CPU and finishes (slow, ~13 min) -- the output is still weight-identical and defeats SynthID, so "looks hung/crashed" on Mac is usually this CPU fallback, not a pipeline error. On a **32 GB** unified-memory machine the same default SDXL pass runs entirely on MPS with **no CPU fallback** (verified 2026-05-31, 1122x1402 gpt-image, `all`/default, ~155 s end-to-end), so 32 GB clears the native-res UNet peak that 24 GB could not. Adding `enable_vae_tiling()` alone does NOT prevent the 24 GB OOM (the peak is the UNet, not the VAE). The fast Mac workarounds for memory-constrained machines are fp16 on MPS (roughly halves memory) or `--max-resolution` to cap the long side; neither is wired as the default. **ctrlregen is compute-bound, not memory-bound, on MPS:** the clean-noise profile tiles to 512px (e.g. ~12 tiles for a 1122x1402 image) and runs the full step count per tile (strength 1.0 -> ~50 effective steps/tile), so on a base-tier Apple-GPU laptop it is ~25-30 min/image after the one-time DINOv2-giant download, regardless of having 32 GB -- a discrete CUDA GPU (fp16, no tiling) is the right place for ctrlregen, while the default SDXL pass is comfortable on a 32 GB Mac. The native-vs-downscale decision lives in the pure helper `invisible_engine._target_size(w, h, max_resolution)` (returns `None` for native, a clamped target tuple otherwise) so it is unit-tested (`tests/test_invisible_engine.py::TestTargetSize`, the #10/#15 regression guard) without loading the model -- keep that logic in the helper, don't re-inline it.
-- **fp16 VAE black-output fix (issue #29, 2026-05-30):** on a **CUDA/XPU fp16** backend the stock SDXL VAE overflows to NaN and the *plain* img2img path decodes to an **all-black** image (reproduced on the raiw.cc result: a 1086x1448 input -> a uniformly black 4.6 KB PNG, mean 0). `watermark_remover._load_pipeline` now swaps in the fp16-fixed SDXL VAE (`madebyollin/sdxl-vae-fp16-fix` = `_SDXL_FP16_VAE_ID`) when `_needs_fp16_vae_fix(model_id, DEFAULT_MODEL_ID, is_fp16)` is true -- only the default SDXL checkpoint on fp16. **cpu/mps run fp32** (the stock VAE is fine there, which is why the bug never reproduces on Mac), and the **differential / region-hires** pipeline already upcasts the VAE itself (see the `text_protector` bullet). A custom non-SDXL `model_id` keeps its own VAE (the fp16-fix VAE is SDXL-architecture-specific). The decision is a pure helper, unit-tested without a download (`tests/test_platform.py::TestFp16VaeFix`); the actual black->clean recovery needs a CUDA GPU and was NOT verifiable on this MPS machine -- confirm on the backend / an NVIDIA box.
-- Pyright first run is slow (2-3 min) due to ML deps (torch/diffusers/transformers stubs); full-project `uv run pyright` can stall for many minutes — scope it to changed files.
-- `ultralytics` monkey-patches `PIL.Image.open` and tries to autoload `pi_heif`. When `pi_heif` is missing, opening files raises `ModuleNotFoundError`, not `UnidentifiedImageError`. Code that opens user-supplied or unknown-format files should `except Exception`, not just `OSError`/`UnidentifiedImageError`.
-- **rich was dropped (CLI + scripts print plain text via `click.echo`).** `cli.py` renders through small `_Console`/`_Table`/`_Progress` shims; the analysis scripts (`scripts/synthid_corpus.py`, `synthid_pixel_probe.py`, `text_detection_benchmark.py`, `corpus_gap_scan.py`) import `Console`/`Table` from the shared `scripts/_plain_console.py` shim (markup like `[bold]`/`[/]` is stripped, tables render aligned). Consequences: (1) `rich` is NOT a dependency, so anything that imports it breaks a clean `uv sync --frozen` (CI installs core+dev only) — this exact gap red-failed CI after the refactor when those 4 scripts still imported rich; if you add a script, use the `_plain_console` shim, not rich. (2) The old `[gpu]`-bracket-eaten bug (#19) is gone — plain `click.echo` prints `pip install 'remove-ai-watermarks[gpu]'` verbatim, no escaping needed (regression-guarded by `tests/test_cli.py::TestGpuHintMarkup`). (3) No Unicode glyphs / colors / progress bars in CLI output by design.
-- Metadata detection for AVIF/HEIF/JPEG-XL relies on a binary scan for `C2PA_UUID` + `IPTC_AI_MARKERS`, plus EXIF `Software` / XMP `CreatorTool` generator tags via `metadata.exif_generator` (validated with synthesized AVIF/JPEG fixtures + an XMP raw-scan fixture). C2PA removal in those containers is implemented via `noai/isobmff.py` (top-level ``uuid`` / ``jumb`` box stripper, no re-encoding), which now also drops a top-level XMP ``uuid`` box that carries an AI label (matched by AI-marker content, not by the XMP UUID, so byte-order-robust) and covers MP4/MOV/M4V/M4A by content sniff. **Non-ISOBMFF audio/video removal is via ffmpeg** (`_FFMPEG_STRIP_EXTS` -> `_strip_with_ffmpeg`): WebM/Matroska (EBML), MP3 (ID3), WAV/FLAC/OGG (RIFF/Vorbis) are stripped losslessly with `ffmpeg -map_metadata -1 -map_chapters -1 -c copy` (codec data untouched). Requires ffmpeg on PATH; raises `RuntimeError` if absent or if ffmpeg can't parse the file. Verified end-to-end (a real ffmpeg-made WAV/MP3 with a `title=Suno AI` tag -> tag gone, audio bytes preserved). **Meta-box XMP now handled (`isobmff.blank_ai_xmp_packets`, v0.6.9):** an AI-label XMP packet stored as a meta-box `mime` item (AVIF/HEIF) is blanked in place (overwritten with spaces of the same length, so `iloc` offsets and the coded image stay valid). **Still NOT built:** an `Exif` *item* inside the `meta` box (rare -- AI labels are XMP) needs full `iinf`/`iloc` surgery (offset rewrite) with corruption risk -- exiftool (R/W/C for HEIC/AVIF EXIF+XMP, verified on exiftool.org 2026-05-27) would do it but is a non-installed binary dep, so it stays a documented gap. **Audio watermark DETECTION (Resemble PerTh) was evaluated and NOT built (2026-05-26):** `resemble-perth`'s `PerthImplicitWatermarker.get_watermark()` returns a raw bit-array with **no presence/confidence flag** (clean audio decodes to arbitrary bits too), so reliably distinguishing watermarked-from-clean needs either Resemble's fixed payload or a confidence API -- neither is public, and there's no real Resemble sample to calibrate against. Same wall-class as the SynthID pixel detector: the decode exists, reliable presence-detection does not. (perth's top-level `PerthImplicitWatermarker` is also gated to None unless `librosa` is importable.)
-- **SynthID technical reference: `docs/synthid.md`** — primary-source-cited doc covering mechanism (post-hoc encoder/decoder pair, 136-bit payload at 512x512, pixel-space, model weights NOT modified), robustness numbers (arXiv:2510.09263: ~99.98% TPR@0.1%FPR across 30 transforms including JPEG/crop/resize/color/noise), removal attacks and forensic detectability (arXiv:2605.09203: all 6 attacks detectable at >98% TPR@1%FPR), detectability limits (no public decoder, metadata-proxy only), oracle scope, and adoption landscape. Read that doc first before adding notes here.
+Topic-specific rules live in `.claude/rules/*.md` and are auto-loaded when matching files are touched.
 
-- **SynthID detection is metadata-only.** There is no reliable *local* detector of the SynthID *pixel* watermark — Google's decoder is proprietary, no public spec or API (only a waitlisted portal). Authoritative confirmation: Google DeepMind's own paper "SynthID-Image: Image watermarking at internet scale" (Gowal et al., arXiv:2510.09263) states the verification service is restricted to "trusted testers" and does not release detector weights or a reproducible algorithm — so a local pixel detector is infeasible by design, not just unbuilt. https://arxiv.org/abs/2510.09263 We detect SynthID by its C2PA companion (`synthid_source` / `SYNTHID_C2PA_ISSUERS`), which is reliable while the manifest is intact but says nothing once C2PA is stripped. **Surface-dependent blind spot (verified 2026-05-24):** the same Google model emits different metadata per surface -- the Gemini *app* wraps outputs in Google C2PA, but the *API/playground* (AI Studio, Nano Banana / gemini-2.5-flash-image) emits the SynthID *pixel* watermark (confirmed via the Gemini-app oracle) + the visible sparkle but **no C2PA/IPTC at all**, so `synthid_source` returns None despite SynthID being present. Only the pixel oracle or the visible-sparkle detector catches those. (Meta AI is another surface mismatch: it writes the IPTC `digitalSourceType=trainedAlgorithmicMedia` marker, not C2PA and not SynthID.) Google→SynthID is long-standing; OpenAI→SynthID is confirmed by OpenAI's Help Center (ChatGPT/Codex/API "include both C2PA metadata and SynthID watermarks", updated 2026-05-21) but time-gated (pre-rollout OpenAI images carry C2PA without SynthID), so the OpenAI verdict is hedged "likely". Oracles: Gemini app "Verify with SynthID" (Google), openai.com/verify (OpenAI). **Each vendor's oracle detects only its OWN content (verified on the page 2026-05-31):** `openai.com/research/verify` states verbatim "OpenAI generation signals will only be detected if the image was generated with our tools" and "Content could also still be AI-generated by another company's model, which the tool currently does not detect" -- SynthID is shared tech but the verifier is keyed to its own vendor's payload, so a Google-SynthID image reads clean on OpenAI's verifier and vice-versa. **This explains the recurring "oracle says clean but `identify` still flags SynthID" report (#14):** the oracle reads the *pixel* watermark (gone after our SDXL pass), while `identify` reads the *C2PA-metadata proxy* (still present if the manifest survived). Different signals, not a contradiction -- strip the metadata too (`metadata --remove` / `all`) and the proxy goes quiet, but a quiet proxy is not proof the pixel watermark is gone. **SynthID is durable to JPEG re-encode by design, so a GitHub-recompressed issue attachment is still a valid SynthID test subject** (verified 2026-06-01 on issue #14's pic3: the GitHub-served JPEG survived re-encoding and openai.com/verify still detected SynthID). Do NOT dismiss issue-attachment JPEGs as "not faithful originals" when reproducing a SynthID-survival report: the recompression strips the **C2PA metadata** (so `identify` reads Unknown on the attachment) but NOT the **pixel watermark** that openai.com/verify reads. A true byte-original only matters for the metadata/C2PA path, not for the pixel-SynthID-removal test. (Contrast the open imwatermark above, which IS fragile to JPEG.) The spectral phase-coherence approach from `github.com/aloshdenny/reverse-SynthID` was evaluated (May 2026) and **does not work for real-content detection**: on its own shipped codebook + validation set, watermarked and cleaned images were indistinguishable (conf within noise, cleaned often higher); it only fires on pure-black 1024x1024 reference images at exact resolution (the controlled case it was calibrated on). The README's "90% / conf=0.91" reproduces only in that lab condition. Do not build a production detector on it; if revisited, it is experimental/diagnostic only and needs a per-resolution, per-model reference corpus. A from-scratch gpt-image pilot (2026-05-24) confirmed this independently: 5 independent solid-black gpt-image outputs share a near-identical fixed signature (pairwise residual correlation **0.92**, avg-template retains 97% energy), so the watermark/carrier IS strongly present and consistent on flat content — but the carrier frequencies extracted from it do NOT discriminate real content (carrier-to-random ratio: cleaned 1.86 > watermarked 1.53; a non-gpt-image image scored highest at 3.67). The signature drowns in content texture. Net: a perfectly consistent solid-color signature still yields no real-content pixel detector with magnitude/carrier methods. A corpus discrimination test (2026-05-24, `scripts/synthid_pixel_probe.py`, raw zero-mean residual NCC) independently re-confirms this: at matched resolution, SynthID positives do NOT cluster apart from negatives (within-Gemini 0.07; at 1024 px pos-vs-neg >= pos-vs-pos). The only high correlations Line truncated
-- **External AI-vs-real classifier models are out of scope (decided 2026-05-24).** Generic HuggingFace detectors (`Organika/sdxl-detector` Swin Transformer, `umm-maybe/AI-image-detector`, and fine-tunes) exist and report ~0.98 on their *own* SDXL-vs-real validation sets, but they are per-generator and the model cards themselves note degraded accuracy off-distribution; they are untested on gpt-image / Gemini Nano Banana (the metadata-stripped surfaces we care about), and our own light SDXL pass would likely defeat them the same way it defeats SynthID. Detection here stays local + signal-based (metadata + visible sparkle); do not add a bundled classifier dependency.
-- **DEFAULT STRENGTH IS NOW VENDOR-ADAPTIVE (2026-06-01, SUPERSEDES every fixed-default claim in this bullet and the next).** `resolve_strength(strength, profile, vendor)` + `vendor_for_strength(path)` (`watermark_profiles.py`) read the C2PA issuer (`metadata.synthid_source`) on the ORIGINAL input and pick `OPENAI_STRENGTH` **0.10** / `GEMINI_STRENGTH` **0.15** / `UNKNOWN_STRENGTH` **0.15** when `--strength` is unset; explicit `--strength` always wins. The CLI detects the vendor from the pristine source (before the visible pass / metadata-strip removes C2PA from the temp file) and passes it to the engine, so display and execution agree; `cmd_invisible`/`cmd_all`/`batch` + the module-level `remove_watermark` all thread `vendor`. **This replaces the single 0.30 default AND the prior "do NOT build a vendor-adaptive default" policy** -- both came from the now-debunked protect-text-contaminated study. Basis: the oracle-verified June 2026 controlled study (clean v0.8.6, protect OFF): OpenAI clears at 0.05 across 1024-1600 (n=4, resolution-independent); Google needs 0.15 on the capped-1536 path (n=4). `docs/synthid.md` §2.2 (data) + §5.2 (the adaptive default) are authoritative. CAVEAT: Google's 0.15 was validated only on `--max-resolution 1536`; native large Gemini (2816) was not locally measurable (OOM on M-series) and is pending GPU validation on raiw.cc -- if it survives 0.15 native, raise `--strength`. **Everything below in this bullet about a fixed 0.10/0.30 default is HISTORICAL; trust the vendor-adaptive constants + docs/synthid.md.**
-- **SynthID v2 vs default pipeline (HISTORICAL, see the vendor-adaptive correction above):** **CORRECTION (2026-05-31, oracle-verified GPU study, SUPERSEDES the 0.10 claim below): the current Gemini SynthID survives 0.10/0.15/0.2 and is REMOVED only at strength 0.3** (Modal A100, native res, Gemini-app "Verify with SynthID", n=3 FRESH Gemini images, `protect_text`/`faces` OFF; 0.2 still present, 0.3 removed). `DEFAULT_STRENGTH` was raised **0.10 -> 0.30** to match. The "0.10 removes it" finding below was n=1 and is now stale -- the threshold has climbed 0.05 -> 0.10 -> ~0.3 as Google hardens SynthID, so re-test against fresh Gemini periodically (moving target). 0.3 costs SSIM ~0.97 vs original (modest) but softens dense/fine typography, and is **overkill for non-SynthID sources** (OpenAI/ChatGPT carry C2PA, NOT Google SynthID -- their pixels read negative on the Gemini verifier at every strength, so 0.10 is plenty there; a per-source strength via `identify` was considered and deferred in favour of the simpler single 0.3 default). **`protect_text` is OFF by default (CORRECTED 2026-06-01, supersedes earlier A/B findings):** verified on a gpt-image at 1600x1600 (issue #14, June 2026 oracle study): same image, with `--protect-text` → SynthID detected by openai.com/verify; without → SynthID removed. The 2026-05-31 A/B finding ("protect_text does not block removal") was Gemini-SynthID-only and did not generalize to OpenAI gpt-image at 1600x1600. Mechanism: the global pass removes SynthID everywhere, but the per-region hires re-scrub regenerates those pixels from an upscaled crop -- at that effective resolution the per-region pass may be insufficient to re-destroy the payload. Both `protect_text` and `protect_faces` are now **EXPERIMENTAL, opt-in** (`--protect-text` / `--protect-faces`), OFF by default. **Oracle scope (load-bearing):** the Gemini app "Verify with SynthID" is the ONLY valid SynthID oracle (it detects Google's mark on any image); `openai.com/verify` is scoped to OpenAI provenance (its own C2PA) and is **NOT** a SynthID oracle, so a negative there is meaningless for SynthID and the older "OpenAI cleared at 0.05 on openai.com/verify" notes below are about provenance, not a pixel-SynthID measurement. **CORRECTION (2026-05-30): strength 0.05 does NOT remove the CURRENT Google SynthID (Nano Banana / Gemini 3).** Re-verified via the Gemini "Verify with SynthID" oracle on a real image: at 0.05 SynthID is still detected; at **0.10 it is removed** (OpenAI's SynthID was already cleared at 0.05). So the default strength was raised 0.05 -> **0.10** (`DEFAULT_STRENGTH` in `watermark_profiles.py`; CLI `--strength` defaults to 0.10), and that higher strength is exactly why text protection (`_run_region_hires`) runs by default (text deforms more at 0.10). Caveat: n=1 Google + n=1 OpenAI image so far -- broad oracle validation across the corpus is pending (different images may need a different strength). **Resolution dependence confirmed by a user report (#14, qw1212ss, 2026-05-31):** on 1600x1600 gpt-image outputs checked via openai.com/verify, 0.05 left SynthID detected on **7/8** images, while small images (376x429) cleared at ~100% -- so "OpenAI cleared at 0.05" was a low-resolution result; a larger canvas carries a stronger watermark and needs more strength. **CORRECTION (2026-06-01, oracle-verified controlled study, SUPERSEDES the resolution-dependence claim above): the "1600 needs more strength" result was the protect-text bug, NOT resolution.** qw1212ss ran v0.7.2 with `protect_text` ON by default; on dense-text infographics the hires text re-scrub re-introduced SynthID. Re-running the SAME 1600x1600 gpt-image on clean v0.8.6 (protect OFF) removes SynthID at **0.05**. Controlled June 2026 study (clean v0.8.6, protect OFF, oracle-verified per image; test set in `data/synthid_corpus/`): **OpenAI clears at 0.05 across 1024-1600 (n=4), resolution-independent; Google (Gemini) needs 0.15 on the capped-1536 path (n=4), 0.05/0.10 do NOT clear.** The dominant real factor is **vendor** (~3x: Google harder), not resolution. Native large Gemini (2816) was not locally measured (OOM/CPU on M-series) -- it plausibly needs >= 0.30. **`docs/synthid.md` section 2.2 is the authoritative source for these numbers; the year-over-year "0.05 -> 0.10 -> 0.30" progression in this bullet conflates real Google hardening with the now-debunked protect-text artifact.** **Policy (do NOT chase a single magic number or build resolution/vendor-adaptive defaults): 0.10 is the default because it is what clears the watermark today; if the oracle still reads SynthID, the guidance is simply to raise `--strength` (0.12, then 0.15), using the lowest value that verifies clean.** There is no local SynthID detector, so the tool cannot self-check and auto-tune; both vendors tighten the watermark over time, so any fixed value is a moving target. README "Removing SynthID" documents the strength-ladder guidance for users. The original claim below (0.0Line truncated
-- **CtrlRegen profile uses a clean-noise default strength, NOT the SDXL 0.10 (fixed 2026-05-31).** **CORRECTION (2026-05-31, same oracle-verified GPU study): ctrlregen at its clean-noise strength DESTROYS real images** -- smooth/background regions fill with hallucinated micro-text garbage; the pipeline is binary (low strength = no-op, high = destroy, no usable middle) and heavy (~8.5 min / ~$0.30 vs ~25 s / ~$0.02 for SDXL). So the literature's "clean-noise is the lever" (detailed below) did NOT survive empirical testing on real content. ctrlregen is now flagged **EXPERIMENTAL** (CLI `--pipeline` help, README, and the `watermark_profiles` comment) and is **NOT for production** -- SDXL img2img at ~0.3 is the shippable path. The clean-noise-default plumbing below is kept (so the profile at least does real work if anyone opts in), but do not recommend ctrlregen. `--pipeline ctrlregen` no longer inherits the SDXL img2img `--strength` default. `resolve_strength(strength, profile, vendor)` (`watermark_profiles.py`, pure + unit-tested in `test_platform.py::TestResolveStrength`) resolves an unset `--strength` to `CTRLREGEN_DEFAULT_STRENGTH` (**1.0**) for ctrlregen and to the **vendor-adaptive** SDXL default (`OPENAI_STRENGTH` 0.10 / `GEMINI_STRENGTH` 0.15 / `UNKNOWN_STRENGTH` 0.15, see the vendor-adaptive bullet above); an explicit `--strength` always wins (including `0.0` -- the resolver checks `is None`, not falsiness, so it does not repeat the old `strength or DEFAULT` bug). CLI `--strength` for `invisible`/`all` defaults to **None** (batch already did); the display (`cli.py`) and the engine (`watermark_remover.remove_watermark`) both route through `resolve_strength` with the SAME detected `vendor` so they never disagree. **Why (deep-research pass 2026-05-31, primary sources):** CtrlRegen's removal power comes from regenerating from (near) clean Gaussian noise, not the light partial-noise img2img the SDXL pass uses. CtrlRegen (ICLR 2025, arXiv:2410.05470) diagnoses verbatim that prior partial-noise regeneration "struggles with high-perturbation watermarks" because a small noise step "retains" watermark info that diffuses back into the output; the fix is a clean-noise start, which with `StableDiffusionControlNetImg2ImgPipeline` maps to strength ~1.0 (image structure held by the canny ControlNet + DINOv2 IP-Adapter, not by the watermarked latent). **Before the fix `--pipeline ctrlregen` ran at 0.10** -- a near-identity pass that loaded ControlNet + DINOv2-giant and then barely changed the image (a removal no-op). **NOT yet oracle-verified** that clean-noise ctrlregen clears the stubborn high-texture gpt-image class that 0.20 SDXL img2img could not (issue #14, qw1212ss: pic3/6/7 survived SynthID through 0.05->0.20); that is the pending controlled test (via openai.com/verify with the IP-country rate-limit bypass). **Forensic-stealth caveat applies harder here:** regeneration-family removal is the MOST detectable as "an image that went through a removal pipeline" (CtrlRegen+ 99.97% TPR@1%FPR, arXiv:2605.09203). **Two #14-investigation hypotheses the literature did NOT confirm:** (1) our "VAE round-trip drives removal, denoising strength does not" framing is only PARTIALLY supported -- arXiv:2510.09263 confirms SynthID was hardened against *weak* VAE re-generation (explaining survival) but does not name the VAE round-trip as the removal vector; (2) our "survival correlates with high-frequency CONTENT texture (Laplacian 466 vs 236)" is unconfirmed by any primary source -- the literature establishes *watermark-perturbation-strength* dependence (a different axis), so the texture correlation stays our own unverified observation, not a literature-backed fact.
+| File | Covers |
+|---|---|
+| `development.md` | Command contracts, project gate, typing boundaries, and model-adjacent tests |

LICENSE

@@ -1,21 +1,217 @@
-MIT License
 
-Copyright (c) 2025 wiltodelta
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
 
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
 
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
+   1. Definitions.
 
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.
+
+
+   Copyright 2025-2026 wiltodelta
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

README.md

@@ -1,411 +1,289 @@
-# Remove-AI-Watermarks
+# Remove AI Watermarks
 
-Remove **visible** and **invisible** AI watermarks from images generated by Google Gemini (Nano Banana), ChatGPT / DALL-E, Stable Diffusion, Adobe Firefly, Midjourney, and other AI models.
+Remove AI provenance marks from images you generated yourself:
 
-Strips SynthID, C2PA Content Credentials, EXIF/XMP "Made with AI" labels, and visible sparkle overlays — all in one command.
+- known visible labels such as the Gemini sparkle and vendor text marks;
+- invisible pixel watermarks through diffusion regeneration;
+- C2PA, EXIF, XMP, IPTC, and related AI metadata.
 
-> ## Try it online: [raiw.cc](https://raiw.cc)
->
-> No Python, no GPU, no setup. Visible-watermark and metadata removal are **free**. Invisible-watermark removal (SynthID / SDXL regeneration) normally needs a local GPU and ~2 GB of models. On **[raiw.cc](https://raiw.cc)** it runs on cloud GPUs in one click for a small per-image fee.
+> Try it online at [raiw.cc](https://raiw.cc) if you do not want to install Python
+> or run diffusion models locally.
 
+[![PyPI](https://img.shields.io/pypi/v/remove-ai-watermarks?logo=pypi&logoColor=white)](https://pypi.org/project/remove-ai-watermarks/)
+[![Python](https://img.shields.io/pypi/pyversions/remove-ai-watermarks?logo=python&logoColor=white)](https://pypi.org/project/remove-ai-watermarks/)
+[![Downloads](https://static.pepy.tech/badge/remove-ai-watermarks/month)](https://pepy.tech/project/remove-ai-watermarks)
+[![License](https://img.shields.io/pypi/l/remove-ai-watermarks?color=blue)](LICENSE)
 [![Tests](https://github.com/wiltodelta/remove-ai-watermarks/actions/workflows/test.yml/badge.svg)](https://github.com/wiltodelta/remove-ai-watermarks/actions/workflows/test.yml)
 [![Sponsor](https://img.shields.io/badge/Sponsor-GitHub-db61a2?logo=githubsponsors&logoColor=white)](https://github.com/sponsors/wiltodelta)
 
-If this tool saves you time, consider [sponsoring its development](https://github.com/sponsors/wiltodelta).
+> This project is for lawful use on content you own. It does not target stock
+> agency previews or other watermarks that protect third party paid content.
+> See [scope, safety, and legal notes](docs/legal-and-safety.md).
 
-> **Intended for lawful use only.** Publishing and running this software is lawful; responsibility for any downstream use, and for compliance with local law, rests entirely with the user. Some jurisdictions restrict removing an AI label as such (see [Legal](#legal)). The authors do not condone use for deception, fraud, or any unlawful activity.
+## Choose what you want to do
 
-## Features
+| Goal | Command | GPU |
+| --- | --- | --- |
+| Find provenance signals and watermarks | `identify` | No |
+| Remove known visible AI marks | `visible` | No |
+| Erase a region you select | `erase` | No |
+| Strip AI metadata | `metadata` | No |
+| Regenerate an image to disrupt invisible watermarks | `invisible` | Recommended |
+| Run visible, invisible, and metadata removal | `all` | Recommended |
+| Process a directory | `batch` | Depends on mode |
 
-- **Visible watermark removal** — a registry of known marks in their usual places: the Gemini / Nano Banana sparkle, the Doubao "豆包AI生成" text strip, and the Jimeng "★ 即梦AI" wordmark. Each is removed by **reverse-alpha blending** against a captured alpha map (`original = (wm − α·logo)/(1−α)`), recovering the true pixels rather than inpainting a guess. The Gemini sparkle recovers cleanly on its own; the Doubao and Jimeng text marks re-rasterize slightly per image, so a thin residual inpaint over the glyph footprint clears the leftover edges (the alpha maps are reproducibly rebuilt from controlled captures by `scripts/visible_alpha_solve.py`). Fast, offline, no GPU. `visible --mark auto` finds and removes the strongest detected mark. (For arbitrary logos/objects, see `erase`.)
-- **Universal region eraser (`erase`)** — remove any logo / watermark / object inside boxes you specify, regardless of position or colour. Default cv2 inpainting (CPU, instant); optional big-LaMa via onnxruntime (`lama` extra) for higher quality
-- **Invisible watermark removal** — SynthID, StableSignature, TreeRing via diffusion-based regeneration (needs a local GPU, or run it with no setup on [raiw.cc](https://raiw.cc))
-- **AI metadata stripping** — EXIF, PNG text chunks, C2PA provenance manifests (PNG / JPEG / AVIF / HEIF / JPEG-XL, **MP4 / MOV / M4V / M4A** at the container level, and **WebM / MP3 / WAV / FLAC / OGG** losslessly via ffmpeg), XMP DigitalSourceType
-- **"Made with AI" label removal** — removes the AI-disclosure metadata that platforms read to apply automatic labels (useful for clearing a false-positive label from a human-edited photograph)
-- **Analog Humanizer** — optional film grain and chromatic aberration post-processing
-- **Smart Face Protection** — automatic extraction and blending of human faces to prevent AI distortion
-- **Batch processing** — process entire directories
-- **Detection** — three-stage NCC watermark detection with confidence scoring
-- **Provenance detection (`identify`)** — aggregate C2PA issuer, the C2PA soft-binding forensic-watermark vendor (Adobe TrustMark, Digimarc, Imatag, ...), IPTC "Made with AI" plus the IPTC 2025.1 `AISystemUsed` field, embedded SD/ComfyUI params, EXIF/XMP generator tags, the xAI/Grok EXIF signature, the China TC260 AIGC label (XMP, PNG chunk, or EXIF), the HuggingFace `hf-job-id` job marker, the SynthID metadata proxy, the visible marks (Gemini sparkle plus the Doubao "豆包AI生成" / Jimeng "即梦AI" text marks), the open SD/SDXL/FLUX invisible watermark, and (with the `trustmark` extra) the open Adobe TrustMark watermark into one origin-platform + watermark-inventory verdict (`--json` for machine output)
+## Installation modes
+
+| Need | Install |
+| --- | --- |
+| Metadata inspection and stripping | `remove-ai-watermarks` |
+| Visible detection and removal | `remove-ai-watermarks[visible]` |
+| Torch-free DWT-DCT detection | `remove-ai-watermarks[detect]` |
+| Diffusion removal | `remove-ai-watermarks[diffusion]` |
+| Every production feature | `remove-ai-watermarks[all]` |
+
+Lower-level and specialized extras include `pixels`, `heif`, `trustmark`,
+`migan`, `lama`, `esrgan`, and `qwen-zimage`. The
+[installation guide](docs/installation.md#feature-extras) documents their exact
+dependency composition and model requirements.
+
+## Quick start
+
+Install the metadata-focused default CLI:
+
+```bash
+uv tool install remove-ai-watermarks
+```
+
+Inspect an image:
+
+```bash
+remove-ai-watermarks identify image.png
+```
+
+For visible watermark removal, install the pixel dependencies:
+
+```bash
+uv tool install --force "remove-ai-watermarks[visible]"
+```
+
+Then remove a known visible mark and AI metadata:
+
+```bash
+remove-ai-watermarks visible image.png -o clean.png
+```
+
+Strip metadata without running visible inpainting or diffusion:
+
+```bash
+remove-ai-watermarks metadata image.png --remove -o clean.png
+```
+
+For invisible watermark removal, install the diffusion dependencies:
+
+```bash
+uv tool install --force "remove-ai-watermarks[diffusion]"
+remove-ai-watermarks invisible image.png -o clean.png
+```
+
+If the local detectors cannot confirm an invisible watermark but you know the
+image came from an AI generator, add `--force`:
+
+```bash
+remove-ai-watermarks invisible image.png -o clean.png --force
+```
+
+See the [installation guide](docs/installation.md) for Homebrew, uv, optional
+features, and development setup.
 
 ## Examples
 
-| Before (Watermarked) | After (Cleaned) |
+### Visible Gemini mark
+
+| Before | After |
 | --- | --- |
-| ![Before](demo_banana_before.png) | ![After](demo_banana_after.png) |
+| ![Image with a visible Gemini watermark](demo_banana_before.png) | ![Image after visible watermark removal](demo_banana_after.png) |
 
-## Supported models
+### High quality invisible removal
 
-| AI model | Visible watermark | Invisible watermark | Metadata | Our approach |
-| --- | --- | --- | --- | --- |
-| **Google Gemini / Nano Banana / Gemini 3 Pro** | ✅ Sparkle logo | ✅ SynthID v1 + v2 (default SDXL pipeline, native resolution) | ✅ C2PA + EXIF | Alpha reversal + diffusion + metadata strip |
-| **OpenAI DALL-E 3 / ChatGPT** | — | — | ✅ C2PA manifest | Metadata strip |
-| **OpenAI ChatGPT Images 2.0** (gpt-image-2) | — | ✅ SynthID + content-specific pixel watermark (since May 2026; no local decoder, openai.com/verify oracle) | ✅ C2PA manifest (verified) | Diffusion regeneration + metadata strip |
-| **Stable Diffusion / SDXL (AUTOMATIC1111, ComfyUI)** | — | ✅ DWT-DCT (imwatermark — locally detectable) | ✅ PNG text chunks | Diffusion regeneration + metadata strip |
-| **Black Forest Labs FLUX** | — | ✅ DWT-DCT (imwatermark — locally detectable) | ✅ C2PA (FLUX.2 Pro) | Diffusion regeneration + metadata strip |
-| **Adobe Firefly** | — | — | ✅ Content Credentials (C2PA) | Metadata strip |
-| **Stability AI** (DreamStudio / Stable Image) | — | — | ✅ C2PA ("Stability AI Ltd") | Metadata strip |
-| **Microsoft Designer / Bing Image Creator** | — | ✅ SynthID via DALL-E backend (Designer) | ✅ C2PA (Bing runs MAI-Image, signed "Microsoft") | Metadata strip |
-| **xAI Grok (Aurora)** | — | — | ✅ EXIF signature scheme (no C2PA): `Signature:` blob + UUID `Artist` | Detected (`identify`); metadata strip |
-| **Midjourney** | — | — | ✅ EXIF + XMP (prompt, model, seed) | Metadata strip |
-| **Meta AI** | — | — | ✅ IPTC "Made with AI" (digitalSourceType) | Metadata strip (removes the label) |
-| **Doubao** (ByteDance) / China AIGC generators | ✅ "豆包AI生成" text strip (bottom-right) | — | ✅ TC260 AIGC label (`<TC260:AIGC>` XMP, `AIGC` PNG chunk, or EXIF JSON) **+ C2PA** signed by ByteDance Volcano Engine (`volcengine`) | Reverse-alpha (captured α map) + thin residual inpaint, NCC-aligned across resolutions, + metadata strip |
-| **Jimeng / Dreamina** (即梦AI, ByteDance) | ✅ "★ 即梦AI" wordmark (bottom-right) | — | ✅ TC260 AIGC label + C2PA (Volcano Engine) | Reverse-alpha (captured α map) + residual inpaint over the glyph footprint, NCC-aligned across resolutions, + metadata strip |
-| **Samsung Galaxy AI** (Generative Edit, Sketch to Image, ...) | — | — | ✅ C2PA (signer "Samsung Galaxy") + `trainedAlgorithmicMedia` / proprietary `genAIType` marker | Detected (`identify`) + metadata strip |
-| **Black Forest Labs** (FLUX API) | — | — | ✅ C2PA (`Black Forest Labs API` + `c2pa.ai_generated_content` + `trainedAlgorithmicMedia`) | Metadata strip |
-| **StableSignature** (Meta) | — | ✅ In-model watermark | — | Diffusion regeneration |
-| **TreeRing** | — | ✅ Latent space watermark | — | Diffusion regeneration |
+The `qwen-zimage` profile is the highest fidelity option for face heavy images.
+It is CUDA only and uses a much larger model stack than the default ControlNet
+profile.
 
-> Visible overlays are used by Google Gemini / Nano Banana (sparkle logo) and by ByteDance's Doubao ("豆包AI生成" corner text) and Jimeng / Dreamina ("★ 即梦AI" wordmark). All are removed on CPU by reverse-alpha against a captured alpha map (Jimeng adds a residual inpaint over the glyph footprint, since its mark re-rasterizes per image). Other services rely on invisible watermarks and/or metadata; our diffusion-based regeneration works against any invisible watermark in pixel or frequency domain. For a visible mark from any other source (any position, any colour), use the universal `erase --region` command.
+```bash
+uv tool install --force "remove-ai-watermarks[qwen-zimage]"
+remove-ai-watermarks invisible image.png -o clean.png \
+  --pipeline qwen-zimage --force
+```
 
-> **Detection:** `remove-ai-watermarks identify <image>` reports the origin platform and watermark inventory for all the signals above — C2PA issuer, the C2PA soft-binding forensic-watermark vendor (TrustMark / Digimarc / Imatag / ...), IPTC "Made with AI" plus the IPTC 2025.1 `AISystemUsed` field, the China TC260 AIGC label (XMP, PNG chunk, or EXIF), the HuggingFace `hf-job-id` job marker, embedded generation params, EXIF/XMP generator tags, the xAI/Grok EXIF signature, the SynthID metadata proxy, the visible marks (Gemini sparkle plus the Doubao "豆包AI生成" / Jimeng "即梦AI" text marks), and (with the `[detect]` / `[trustmark]` extras) the open SD/SDXL/FLUX and Adobe TrustMark invisible watermarks. SynthID and the proprietary soft-binding watermarks (Digimarc etc.) have no local decoder, so they are reported by metadata proxy / vendor name only.
+| OpenAI example before | OpenAI example after |
+| --- | --- |
+| [![OpenAI portrait grid before qwen-zimage](data/synthid/originals/ChatGPT%20Image%20May%2030,%202026,%2010_31_08%20AM.png)](data/synthid/originals/ChatGPT%20Image%20May%2030,%202026,%2010_31_08%20AM.png) | [![OpenAI portrait grid after qwen-zimage](docs/images/qwen-zimage/ChatGPT/ChatGPT%20Image%20May%2030,%202026,%2010_31_08%20AM_full_clean.png)](docs/images/qwen-zimage/ChatGPT/ChatGPT%20Image%20May%2030,%202026,%2010_31_08%20AM_full_clean.png) |
+
+| Gemini example before | Gemini example after |
+| --- | --- |
+| [![Gemini sign before qwen-zimage](data/synthid/originals/Gemini_Generated_Image_633uuy633uuy633u.png)](data/synthid/originals/Gemini_Generated_Image_633uuy633uuy633u.png) | [![Gemini sign after qwen-zimage](docs/images/qwen-zimage/Gemini/Gemini_Generated_Image_633uuy633uuy633u_full_clean.png)](docs/images/qwen-zimage/Gemini/Gemini_Generated_Image_633uuy633uuy633u_full_clean.png) |
+
+These exact output files were checked with the matching provider verifiers. That
+result applies to these files, not to every seed, image, or future watermark
+version.
+
+## Common recipes
+
+### Remove every detected visible mark
+
+```bash
+remove-ai-watermarks visible image.png -o clean.png
+```
+
+The default `--mark auto` checks all registered visible marks and removes every
+match. If the mark is visible to you but the detector misses it, select its
+region explicitly:
+
+```bash
+remove-ai-watermarks erase image.png \
+  --region 1640,1930,400,100 \
+  -o clean.png
+```
+
+`--region` uses `x,y,width,height` and may be repeated.
+
+### Use a learned fill backend
+
+The `visible` extra uses OpenCV inpainting when no learned backend is installed.
+For more difficult backgrounds, the learned-backend extras include the same
+pixel dependencies automatically:
+
+```bash
+uv tool install --force "remove-ai-watermarks[migan]"
+remove-ai-watermarks visible image.png -o clean.png --backend migan
+```
+
+```bash
+uv tool install --force "remove-ai-watermarks[lama]"
+remove-ai-watermarks visible image.png -o clean.png --backend lama
+```
+
+### Reduce CUDA memory use
+
+```bash
+remove-ai-watermarks invisible image.png -o clean.png \
+  --cpu-offload --force
+```
+
+CPU offload lowers CUDA memory pressure by moving model components between CPU
+and GPU. It is slower and has no effect on CPU or MPS.
+
+### Process a directory
+
+```bash
+remove-ai-watermarks batch ./images --mode visible
+remove-ai-watermarks batch ./images --mode all
+```
+
+## What the tool can recognize
+
+Visible mark support includes:
+
+- Google Gemini and Nano Banana sparkle;
+- Doubao, Jimeng, Qwen, Kling, Baidu, LibLibAI, and RunningHub labels;
+- one calibrated Samsung Galaxy AI label variant.
+
+Metadata and provenance inspection covers C2PA, EXIF, XMP, IPTC, common
+generator parameters, China TC260 AIGC labels, and several vendor specific
+signals. Optional decoders add support for open DWT-DCT watermarks and Adobe
+TrustMark.
+
+The exact support matrix, including important locale and detector limits, lives
+in [supported signals](docs/supported-signals.md).
 
 ## How it works
 
-### Removing the Gemini / Nano Banana sparkle watermark
+Visible removal follows three steps:
 
-Google Gemini (internally codenamed **Nano Banana**) adds a visible sparkle logo to generated images using alpha blending:
+1. Detect a registered mark in its expected area.
+2. Build a mask around the mark.
+3. Fill only the masked region with OpenCV, MI-GAN, or LaMa.
 
-```text
-watermarked = α × logo + (1 − α) × original
-```
+Metadata removal uses format aware stripping. JPEG metadata removal preserves
+the encoded image scan instead of recompressing it. Other supported containers
+use their corresponding metadata path.
 
-We reverse this with a known alpha map (extracted from Gemini / Nano Banana output on a pure-black background):
+Invisible removal is different. It regenerates the image through a diffusion
+pipeline to disrupt pixel and frequency domain watermarks. This changes the
+image and cannot guarantee that a proprietary verifier will reject every
+output.
 
-```text
-original = (watermarked − α × logo) / (1 − α)
-```
+See [supported signals](docs/supported-signals.md) and
+[known limitations](docs/known-limitations.md) for the full technical boundary.
 
-A three-stage NCC (Normalized Cross-Correlation) detector finds the watermark position and scale dynamically, so it works even if the image was resized or cropped. After removal, residual sparkle-edge artifacts are cleaned via gradient-masked inpainting.
+## Python API
 
-**Speed**: ~0.05s per image. No GPU needed.
-
-### Removing the Doubao "豆包AI生成" text watermark
-
-Doubao (ByteDance) stamps every output with a light, semi-transparent "豆包AI生成" text strip in the bottom-right corner — the visible AIGC label mandated by China's TC260 standard. It is a fixed semi-transparent white overlay, so it is removed by **reverse-alpha blending**: `original = (watermarked - α·logo) / (1 - α)`, recovering the true pixels instead of hallucinating them. The α map is solved from controlled black/gray captures (rebuildable with `scripts/visible_alpha_solve.py`). Like the Jimeng mark, Doubao re-rasterizes its text slightly per image, so reverse-alpha is followed by a thin residual inpaint over the glyph footprint to clear the leftover edges, and the α template is NCC-aligned to the actual mark (handling per-image scale/position jitter). Detection matches the same glyph silhouette against the corner (normalized correlation), so it keys on the "豆包AI生成" shape, not on textured corners.
-
-**Speed**: ~0.05s, no GPU needed.
-
-### Removing the Jimeng "★ 即梦AI" wordmark
-
-Jimeng / Dreamina (即梦AI, also ByteDance, distinct from Doubao) stamps a "★ 即梦AI" wordmark — a four-point sparkle followed by the 即梦AI characters — in the bottom-right corner. It is a fixed semi-transparent **pure-white** overlay, solved from controlled black / gray / white captures the same way as Doubao. `visible --mark auto` detects and removes it (or force it with `--mark jimeng`). One difference from Doubao: Jimeng re-rasterizes its mark slightly differently per image, so a single alpha map does not cancel it pixel-for-pixel — reverse-alpha knocks the mark down and a residual inpaint over the glyph footprint clears the remaining outline. The two ByteDance marks do not confuse `auto`: detection keys on each mark's own glyph shape (the Jimeng detector scores far below its threshold on a Doubao strip, and vice versa).
-
-```bash
-remove-ai-watermarks visible jimeng.png -o clean.png            # --mark auto picks Jimeng
-remove-ai-watermarks visible jimeng.png --mark jimeng -o clean.png
-```
-
-### Universal region eraser
-
-For any visible mark the dedicated engines do not cover — a logo anywhere, any colour — `erase --region x,y,w,h` inpaints the box you specify. The default `cv2` backend is instant and dependency-free; the optional `lama` backend (big-LaMa via onnxruntime, `lama` extra, ~200 MB model downloaded on first use) gives much cleaner fills on textured regions at the cost of ~3-4 GB RAM per call.
-
-### Removing SynthID and other invisible watermarks
-
-Google embeds **SynthID** into every image generated by Gemini / Nano Banana. Other AI services use StableSignature, TreeRing, and similar schemes. These imperceptible frequency-domain patterns survive cropping, resizing, and JPEG compression.
-
-The removal pipeline (default profile, SDXL):
-
-```text
-image → encode to latent space (VAE) at native resolution
-      → add controlled noise (forward diffusion)
-      → denoise (reverse diffusion, ~50 steps; strength is vendor-adaptive:
-        0.10 OpenAI / 0.15 Google / 0.15 unknown, override with --strength)
-      → decode back to pixels (VAE)
-```
-
-- Native resolution avoids shrinking the input to 1024 px first; that down-then-up round-trip was the main quality loss (issue #10). Use `--max-resolution N` only to cap GPU/MPS memory on very large inputs.
-
-> **Default strength is vendor-adaptive (no flag needed).** The tool reads the C2PA issuer to detect which vendor's SynthID is present and picks the strength that clears it with the least quality loss: **OpenAI gpt-image → `0.10`**, **Google Gemini → `0.15`**, **unknown source → `0.15`**. An oracle-verified June 2026 study (clean pipeline, per-image openai.com/verify or Gemini app) found OpenAI's watermark clears at `0.05` across `1024`-`1600` px (resolution-independent) while Google's is ~3x more robust and needs `0.15`. The dominant factor is the vendor, not resolution. There is no local SynthID detector, so if the oracle still reads SynthID, raise `--strength`; if you care more about preserving fine text, lower it. (Caveat: Google's `0.15` was validated on the capped `--max-resolution 1536` path; a very large native Gemini image may need more.)
->
-> **Text and face protection are OFF by default.** The high-resolution text re-scrub can shield SynthID in text regions, leaving the watermark intact there even after the global pass clears it everywhere else (verified June 2026: same image, with `--protect-text` → SynthID detected; without → SynthID removed). Both features are opt-in with `--protect-text` / `--protect-faces` and considered **experimental**. If you enable them, verify the result with the oracle.
->
-> **`--pipeline ctrlregen` is experimental and not recommended.** On paper CtrlRegen ([ICLR 2025](https://github.com/yepengliu/CtrlRegen)) regenerates from near-clean Gaussian noise to defeat robust watermarks, but in testing on real images it **destroys content** — smooth and background regions fill with hallucinated micro-text — and it is heavy (several GB of extra models, minutes per image). It has no usable middle setting (too low removes nothing, high enough to remove wrecks the image), so the shippable path is the default SDXL pipeline at the vendor-adaptive strength. CtrlRegen stays available for experimentation only.
-
-SDXL is the default since May 2026: empirically defeats SynthID v2 on Gemini 3 Pro outputs, where the older SD-1.5 pipeline at 768 px did not. The SD-1.5 path was removed once it was verified not to handle v2. Note the scope: this defeats the SynthID *verifier*, which is not the same as being forensically indistinguishable from a real photo. Recent work ([arXiv:2605.09203](https://arxiv.org/abs/2605.09203)) shows watermark-removal pipelines leave detectable traces, so a separate "this image was processed" classifier can still flag the output.
-
-> **Oracle vs `identify` can disagree, and that is expected.** An online verifier reads the actual SynthID *pixel* watermark and detects only its own vendor's content — [openai.com/research/verify](https://openai.com/research/verify/) states "OpenAI generation signals will only be detected if the image was generated with our tools". Our `identify` cannot decode the pixel watermark (no vendor ships a local decoder), so it infers SynthID from the **C2PA metadata** instead. So after the SDXL pass the oracle can read "no SynthID" (pixel watermark gone) while `identify` still reports SynthID from a surviving C2PA manifest. They measure different signals. Run `metadata --remove` (or `all`) to also strip the manifest; note that a quiet metadata proxy is not proof the pixel watermark itself is gone.
-
-> **Technical deep-dive:** see [`docs/synthid.md`](docs/synthid.md) for a primary-source-cited breakdown of how SynthID works mechanically (post-hoc encoder/decoder, 136-bit payload, pixel-space embedding), what it empirically survives (JPEG, crop, resize: ~99.98% TPR at 0.1% FPR from arXiv:2510.09263), what removes it, and the forensic-stealth tradeoff (all known removal attacks are detectable at >98% TPR@1%FPR per arXiv:2605.09203).
-
-**Face Protection** (experimental, opt-in `--protect-faces`): before diffusion, YOLO detects people in the image and extracts them; after diffusion the original faces are blended back. Off by default — enable only when face fidelity matters more than SynthID removal completeness.
-
-**Analog Humanizer**: optional film grain and chromatic aberration injection that mimics a photo of a screen, raising the bar for AI-generated image classifiers. (It frustrates generic classifiers but does not guarantee forensic invisibility — see the [arXiv:2605.09203](https://arxiv.org/abs/2605.09203) note above.)
-
-**Text Protection** (experimental, opt-in `--protect-text`): re-scrubs detected text blocks at high resolution after the global pass to keep small glyphs crisp. **Off by default** because the high-resolution re-scrub can preserve SynthID in text regions even after the global pass removes it elsewhere. Enable only when text fidelity matters more than watermark removal completeness, and verify the oracle result. SDXL pipeline only.
-
-### Stripping C2PA, EXIF, and "Made with AI" metadata
-
-AI tools embed generation metadata that social platforms use to show "Made with AI" labels:
-
-- **EXIF tags** — prompt, seed, model hash, sampler settings (Stable Diffusion, Midjourney)
-- **XMP DigitalSourceType** — `trainedAlgorithmicMedia` tag used by Instagram, Facebook, and X (Twitter) to show "Made with AI"
-- **PNG text chunks** — ComfyUI workflows, AUTOMATIC1111 parameters
-- **C2PA Content Credentials** — cryptographic provenance manifests from Google Imagen, OpenAI DALL-E, Adobe Firefly
-
-The cleaner parses each layer, removes AI-related fields, and preserves standard metadata (Author, Copyright, Title).
-
-## Installation
-
-### Recommended
-
-Install as an isolated CLI tool — no need to manage virtual environments:
-
-```bash
-# Using pipx (https://pipx.pypa.io)
-pipx install git+https://github.com/wiltodelta/remove-ai-watermarks.git
-
-# Or using uv (https://docs.astral.sh/uv)
-uv tool install git+https://github.com/wiltodelta/remove-ai-watermarks.git
-```
-
-To update to the latest version:
-
-```bash
-pipx upgrade remove-ai-watermarks
-
-# or
-uv tool upgrade remove-ai-watermarks
-```
-
-### Install from repository
-
-**Prerequisites:** Python 3.10+ and `pip` (or [`uv`](https://docs.astral.sh/uv/)).
-
-```bash
-# 1. Clone the repository
-git clone https://github.com/wiltodelta/remove-ai-watermarks.git
-cd remove-ai-watermarks
-
-# 2. Install the package in editable mode
-pip install -e .
-
-# Or, if you use uv:
-uv pip install -e .
-```
-
-After installation the `remove-ai-watermarks` command is available system-wide.
-
-> **Note**: The base install covers visible watermark removal and metadata stripping.
-> For invisible watermark removal (SynthID etc.), install GPU dependencies:
->
-> ```bash
-> pip install -e ".[gpu]"   # or: uv pip install -e ".[gpu]"
-> ```
->
-> To let `identify` decode the open Stable Diffusion / SDXL / FLUX invisible
-> watermarks, install the `detect` extra (adds the `invisible-watermark` decoder):
->
-> ```bash
-> pip install -e ".[detect]"   # or: uv pip install -e ".[detect]"
-> ```
->
-> To also decode the open **Adobe TrustMark** watermark (behind Adobe Durable
-> Content Credentials), install the `trustmark` extra (pulls torch and downloads
-> model weights on first use):
->
-> ```bash
-> pip install -e ".[trustmark]"   # or: uv pip install -e ".[trustmark]"
-> ```
-
-#### Invisible watermark removal
-
-Invisible removal uses diffusion models and a GPU for reasonable speed.
-
-```bash
-# On first run, the model (~2 GB) will be downloaded automatically.
-# Device is auto-detected: CUDA (Linux/Windows) > MPS (macOS) > CPU.
-# To force a device: --device cuda / --device mps / --device cpu
-
-# Optional: set a HuggingFace token for gated/private models
-cp .env.example .env
-# Edit .env and set HF_TOKEN=hf_your_token_here
-```
-
-#### Developer setup
-
-```bash
-# Install with dev dependencies (pytest, ruff, pyright)
-pip install -e ".[dev]"
-# Or with uv:
-uv pip install -e ".[dev]"
-
-# Run tests
-pytest
-
-# Run linters
-./maintain.sh
-```
-
-## Usage
-
-### CLI
-
-```bash
-# Remove all watermarks from a single image (visible + invisible + metadata)
-remove-ai-watermarks all image.png -o clean.png
-
-# Process an entire directory
-remove-ai-watermarks batch ./images/ --mode all
-```
-
-#### Individual commands
-
-```bash
-# Identify provenance: where an image was made + its watermark inventory.
-# Aggregates C2PA, IPTC "Made with AI", embedded SD/ComfyUI params, EXIF/XMP
-# generator tags (incl. inside AVIF/HEIF), the SynthID proxy, the visible Gemini
-# sparkle, and (with the [detect] extra) the open SD/SDXL/FLUX invisible
-# watermark into one verdict. Reports "unknown"
-# (never "clean") when no signal is found, since stripped metadata is not proof
-# of a clean origin. Add --json for machine-readable output.
-remove-ai-watermarks identify image.png
-
-# Visible watermark only — fast, offline, CPU. --mark auto (default) finds the
-# strongest known mark (Gemini sparkle / Doubao "豆包AI生成" / Jimeng "即梦AI"); force
-# one with --mark gemini / doubao / jimeng. Removed by reverse-alpha (true-pixel recovery).
-remove-ai-watermarks visible image.png -o clean.png
-
-# Erase arbitrary region(s) — universal, any logo/watermark/object, any position.
-# Default cv2 inpainting (CPU). --backend lama uses big-LaMa (extra 'lama').
-remove-ai-watermarks erase image.png --region 1640,1930,400,100 -o clean.png
-
-# Invisible watermark only (SynthID etc.) — requires GPU
-remove-ai-watermarks invisible image.png -o clean.png --humanize 4.0
-# Runs at native resolution by default. On a very large image that OOMs the
-# GPU/MPS, cap the long side: --max-resolution 2048
-# Strength is vendor-adaptive by default (OpenAI 0.10 / Google 0.15); override
-# with --strength. Text/face protection is opt-in (--protect-text /
-# --protect-faces, experimental: they can shield SynthID).
-
-# Check / strip AI metadata (C2PA, EXIF, "Made with AI" labels)
-# --check also flags SynthID-bearing sources: a C2PA manifest signed by
-# Google or OpenAI implies an invisible SynthID watermark in the pixels
-# (both vendors pair the two). Adobe Firefly / Microsoft sign C2PA without
-# SynthID, so they are reported as C2PA only.
-remove-ai-watermarks metadata image.png --check
-remove-ai-watermarks metadata image.png --remove
-
-# Batch with a specific mode
-remove-ai-watermarks batch ./images/ --mode visible
-```
-
-### Python API
+The visible-removal API requires `remove-ai-watermarks[visible]`.
 
 ```python
-from remove_ai_watermarks.gemini_engine import GeminiEngine
-import cv2
+import remove_ai_watermarks as raiw
 
-engine = GeminiEngine()
-image = cv2.imread("watermarked.png")
-
-# Detect
-result = engine.detect_watermark(image)
-print(f"Detected: {result.detected} (confidence: {result.confidence:.1%})")
-
-# Remove
-clean = engine.remove_watermark(image)
-cv2.imwrite("clean.png", clean)
+result, removed = raiw.remove_visible("watermarked.png", "clean.png")
+print(removed)
 ```
 
-### Metadata stripping
+The high level API accepts a file path or a BGR NumPy array. For path inputs it
+also reads provenance metadata, preserves alpha, and can strip AI metadata from
+the written result.
 
-```python
-from remove_ai_watermarks.metadata import has_ai_metadata, remove_ai_metadata
-from pathlib import Path
+See the [Python API guide](docs/python-api.md) for visible removal, provenance
+inspection, metadata stripping, and diffusion usage.
 
-if has_ai_metadata(Path("image.png")):
-    remove_ai_metadata(Path("image.png"), Path("clean.png"))
-```
+## ComfyUI
 
-## Requirements
+The separate
+[ComfyUI Remove AI Watermarks](https://github.com/wiltodelta/ComfyUI-remove-ai-watermarks)
+package provides nodes for visible removal, detection, region erasing, and
+invisible removal.
 
-- Python ≥ 3.10
-- **Visible removal / metadata**: CPU only, no GPU required
-- **Invisible removal**: GPU recommended (CUDA or MPS), works on CPU (slow)
+## Important limitations
 
-## Troubleshooting
+- A missing local signal means unknown, not clean. Proprietary pixel
+  watermarks may remain after metadata has been stripped.
+- Visible removal reconstructs a small region. Results depend on the background
+  and selected fill backend.
+- Invisible removal changes the whole image and may alter faces, text, or fine
+  detail.
+- `qwen-zimage` requires CUDA. The other diffusion profiles also support the
+  devices listed by `remove-ai-watermarks invisible --help`.
+- Provider watermark systems can change. Validate important outputs with the
+  provider's own verifier when one is available.
 
-**SSL certificate error** (`CERTIFICATE_VERIFY_FAILED`):
+## Documentation
+
+Start with the [documentation index](docs/index.md).
+
+- [Installation](docs/installation.md)
+- [CLI guide](docs/cli.md)
+- [Python API](docs/python-api.md)
+- [Supported signals](docs/supported-signals.md)
+- [Known limitations](docs/known-limitations.md)
+- [Scope, safety, and legal notes](docs/legal-and-safety.md)
+- [Module internals](docs/module-internals.md)
+- [Release and distribution](docs/release-and-distribution.md)
+
+Research notes and historical experiments are listed separately in the
+[documentation index](docs/index.md). They explain past decisions but do not
+define the current public API.
+
+## Contributing
+
+Install the development environment and run the project gate:
 
 ```bash
-# Install certifi (the tool auto-detects it)
-pip install certifi
-
-# macOS only: run the Python certificate installer
-/Applications/Python\ 3.*/Install\ Certificates.command
+uv sync --frozen --extra dev
+bash maintain.sh
 ```
 
-**First run is slow** — this is expected. The tool downloads model weights (~2 GB) on first launch. Subsequent runs use cached models.
-
-## Credits
-
-- [noai-watermark](https://github.com/mertizci/noai-watermark) by mertizci — invisible watermark removal engine
-- [GeminiWatermarkTool](https://github.com/allenk/GeminiWatermarkTool) by Allen Kuo (MIT) — visible watermark removal algorithm
-- [CtrlRegen](https://github.com/yepengliu/CtrlRegen) by Liu et al. (ICLR 2025) — controllable regeneration pipeline
-- NeuralBleach (MIT) — analog humanizer technique
-
-## Roadmap
-
-Tracked but not yet implemented:
-
-- **SynthID-Image v2 automated regression test**. The default SDXL profile defeats v2 per manual checks against the [Gemini app](https://support.google.com/gemini/answer/16722517)'s "Verify with SynthID" feature on a Gemini 3 Pro output (May 2026). An automated end-to-end test would need either programmatic access to the [SynthID Detector portal](https://blog.google/innovation-and-ai/products/google-synthid-ai-content-detector/) (waitlist for media professionals and researchers) or an offline surrogate detector. The spectral phase-coherence surrogate from [reverse-SynthID](https://github.com/aloshdenny/reverse-SynthID) was evaluated and does not separate watermarked from cleaned real-content images (it only fires on controlled solid-color references at exact resolution), so it is not a usable oracle. Open.
-- **Local SynthID *pixel* detector**. Not feasible today: Google's decoder is proprietary, and magnitude/carrier spectral methods do not separate real content (confirmed by three independent evaluations, including a from-scratch gpt-image pilot; see CLAUDE.md). Blocked on either (a) a programmatic generation path (OpenAI / Gemini API) to build a per-(model, resolution) labeled corpus at scale, or (b) a raw watermarked-output dataset. If data arrives, the next approach to try is a learned classifier on diverse content rather than a fixed carrier codebook.
-- **Grow the SynthID reference corpus** (`data/synthid_corpus/`) with oracle-labeled samples per model and resolution (Gemini app for Google, openai.com/verify for OpenAI). Prerequisite for any pixel-detector attempt and for an automated removal-regression set.
-- **Real non-PNG C2PA fixtures**. SynthID-source detection for JPEG / WebP / AVIF is currently covered only by synthetic byte blobs; replace with real vendor-emitted files to ground the binary-scan path.
-- **Maintenance debt**. Strict pyright is now clean across `src/` (0 errors): pure-logic files are fully typed, the cv2 / torch / diffusers boundary files carry a documented per-file relax pragma, and a local `typings/piexif` stub covers piexif. Remaining: full-project `pyright` (no path) still OOMs node on this ML-heavy repo, so it must be scoped to `src/`; narrowing the boundary pragmas back toward full strict (as upstream stubs improve) is the long tail. (`uv-secure` is already clean since `idna` was bumped to 3.16.)
-- **AVIF / HEIF `Exif` item inside the `meta` box**. An AI-label *XMP* packet in a `meta`-box item is now blanked in place (v0.6.9), but EXIF stored as a `meta`-box `Exif` *item* is still not removed — it needs full `iinf`/`iloc` surgery (offset rewrite, corruption risk) or `exiftool` (a non-bundled binary dependency). Low priority: the AI labels we target are XMP, not EXIF, so an EXIF-only meta-box case is rare.
-- **More C2PA device signers**. Leica, Nikon, Google Pixel, Sony, and Truepic capture cameras are mapped (each verified against a real signed file); **Samsung Galaxy AI**, **Black Forest Labs (FLUX)**, and **ByteDance Volcano Engine** (Doubao / Jimeng) are now attributed too (verified on real signed files). Canon is still deferred until a real signed sample surfaces — no public direct-download C2PA file exists for it today (upload-to-verify / news-agency-licensed only).
-- **Resemble PerTh audio detection** — evaluated, not feasible with the public API: `get_watermark()` returns a raw bit array with no presence/confidence flag, so watermarked vs. clean audio can't be reliably separated without Resemble's fixed payload or a confidence service. Same wall as the SynthID pixel detector.
-- **Video pipeline (`noai-video`)**: per-frame inpainting and tracking for Sora 2 dynamic logo, Veo 3.1 badge, Kling, Runway. Separate package, not folded into this repo.
-
-Won't fix:
-
-- **Nightshade / Glaze / PhotoGuard removal**. These are defensive perturbations used by artists to protect their work from being scraped into AI training sets. Removing them attacks artists, not AI provenance. Out of scope.
-
-## Legal
-
-Watermarking and provenance for AI-generated content is now regulated in several jurisdictions. The table below summarises the May 2026 status. None of this is legal advice.
-
-| Jurisdiction | Instrument | Status (May 2026) | Relevance |
-| --- | --- | --- | --- |
-| EU | AI Act, Article 50 | Transparency duties apply from **2 August 2026**. Legacy generative systems (placed on the market before that date) get a grandfathering period to **2 December 2026** for the Article 50(2) marking duty, under the Digital Omnibus (Commission proposal Nov 2025; co-legislator political agreement 7 May 2026). Article 50 guidelines and a marking Code of Practice are being finalised through 2026. | Removing mandated provenance markers with intent to deceive may be sanctioned under national implementations. |
-| US (federal) | COPIED Act (S. 1396, 119th Cong.) | **Reintroduced April 2025; not enacted** (referred to Senate Commerce Committee). | If passed, would set NIST provenance standards and prohibit tampering with / removing provenance information. The tool itself is lawful; usage may not be. |
-| US (state) | CA AB 2655, TX SB 751 (2019), similar | TX SB 751 (2019) in force; **CA AB 2655 struck down** by a federal court (E.D. Cal., Aug 2025, *Kohls v. Bonta*) as preempted by **Section 230**; the court did not reach the First Amendment (the companion law AB 2839 was separately enjoined on First Amendment grounds). | Content-specific (election deepfakes, sexual deepfakes). Not tool-specific. |
-| US (state) | CA AB 853 (amends the California AI Transparency Act) | Core provider duties operative **2 August 2026** (delayed from 1 January 2026); large platforms 1 January 2027; capture devices 1 January 2028. | Covered providers (1M+ monthly users) must embed a latent disclosure that is "permanent or extraordinarily difficult to remove" and offer a free detection tool. Removing that disclosure is what this tool does. |
-| South Korea | AI Framework Act (Basic Act on AI), Article 31 | In force since **22 January 2026** (one-year transition after promulgation). | Art. 31(3): AI output "difficult to distinguish from reality" must be labeled so users "clearly recognize" it; the draft Enforcement Decree accepts a machine-readable (invisible-watermark) label. Artistic/creative works get a presentation exception. |
-| China | Measures for Labeling AI-Generated Content (+ GB 45438-2025) | In force since **1 September 2025**. | Mandatory explicit (visible) + implicit (metadata) labels across image / audio / video; tampering with, forging, or removing labels is prohibited. |
-| India | IT (Intermediary Guidelines and Digital Media Ethics Code) Amendment Rules, 2026 | In force since **20 February 2026** (notified 10 February 2026). | All "synthetically generated information" must be **prominently labelled** and carry **permanent metadata / a provenance identifier**; the rules expressly **prohibit modifying, suppressing, or removing** that label or metadata. Covers image, audio, and audio-visual content. |
-| UK | Online Safety Act 2023 / Ofcom guidance | In force, but **no statutory AI-provenance or watermarking obligation**. | Ofcom encourages watermarking / provenance metadata as voluntary "attribution measures"; platform duties, not user obligations. |
-
-## Threat model
-
-This tool defends already-distributed AI imagery against automatic detection systems (social-platform "Made with AI" labels, third-party classifiers, content-policy filters). It does **not** retroactively anonymise generation.
-
-In particular, **SynthID** (Google DeepMind) is embedded across Google's generative media stack — Imagen (images), Veo (video), Lyria (audio) — and Gemini app image outputs (Nano Banana / Gemini 3 Pro, which we verified positive via the Gemini app's SynthID oracle); Google reported over 10 billion items watermarked by December 2025. It carries a **multi-bit payload** — the research paper's SynthID-O variant encodes 136-bit payloads in 512x512 images ([arxiv 2510.09263](https://arxiv.org/abs/2510.09263)). The payload is believed to encode a user / session identifier. If the original watermarked file ever passed through a system controlled by the prompt originator (a saved Gemini account history, a screenshot uploaded to a Google product, a backup), Google retains the ability to link that original to the generating account. Stripping the watermark from a copy you possess does not erase Google's server-side record.
-
-Use cases where the threat model fits:
-- You generated the image yourself, want to publish it as your own work, and accept the consequences if Google ever publishes their detector logs.
-- You are running a security / robustness evaluation.
-- You are preserving art or historical record against false-positive "AI-generated" labels.
-
-Use cases where the threat model **does not** fit:
-- Generating an image, expecting that removing the watermark anonymises you to Google. It doesn't.
-- Distributing AI-generated content while claiming human authorship. The watermark is one of several traceability layers.
-
-This tool is intended for legitimate purposes such as:
-
-- Privacy protection (removing metadata that leaks user account identifiers).
-- Art preservation and fair-use research.
-- Removing false-positive "Made with AI" labels from human-edited photographs.
-- Security research and watermark robustness study.
-
-**Who bears the liability.** This is general-purpose software and is itself lawful to publish and run; legal responsibility attaches to the person who removes a marker and to how the result is then used, and the hinge is intent. Removing AI provenance to pass AI-generated content off as human-made, to commit fraud, to produce non-consensual deepfakes, or to conceal copyright infringement can expose the remover to liability. Two kinds of exposure are worth knowing:
-
-- **The downstream act.** Deception, fraud, defamation, IP infringement, or breaking a platform's terms — judged by intent and harm, not by the act of editing metadata itself. In the US, the **DMCA (17 U.S.C. § 1202)** specifically bars removing "copyright management information" *with intent to conceal or enable infringement*.
-- **The removal itself.** Some jurisdictions penalise tampering with the label/metadata as such, regardless of downstream use — notably **China** (Labeling Measures) and **India** (IT Amendment Rules 2026), which expressly prohibit removing or suppressing the AI label and provenance metadata. The US **COPIED Act** would do the same if enacted.
-
-Legitimate uses — publishing your own work, privacy (stripping metadata that leaks an account identifier), security / robustness research, or removing a false-positive "Made with AI" label from a human-edited photograph — are generally lawful. Users are solely responsible for ensuring their use complies with all applicable laws. The authors do not condone use of this tool for deception, fraud, or any activity that violates applicable laws or regulations. None of this is legal advice.
+See [module internals](docs/module-internals.md) before changing a subsystem
+with documented invariants.
 
 ## License
 
-MIT
+[Apache 2.0](LICENSE). Copyright 2025-2026 wiltodelta.

data/README.md

@@ -0,0 +1,38 @@
+# Repository data
+
+Tracked data is organized by purpose:
+
+```text
+data/
+  fixtures/
+    provenance/   Real format and provenance fixtures used by tests
+  calibration/
+    <vendor>/     Minimal controlled inputs needed to rebuild detector assets
+  synthid/
+    originals/    Canonical provider-oracle fixtures, stored once
+    manifest.csv  Provenance and verification record for each original
+    full-pipeline-quality.csv
+                  Reusable full-pipeline evaluation selection
+  evaluations/
+    fidelity/     Evaluation instructions and hand-verified ground truth
+```
+
+## Storage rules
+
+1. Store each binary image once. Evaluation manifests and documentation point
+   to its canonical location.
+2. Put executable test fixtures in `fixtures/`.
+3. Put only the minimal reproducible detector inputs in `calibration/`.
+4. Put externally verified SynthID originals in `synthid/originals/` and keep
+   both CSV files synchronized.
+5. Keep evaluation outputs outside the repository. Record reproducible
+   commands, hashes, and oracle verdicts instead of committing another corpus
+   copy. A small curated before-and-after example may live in `docs/images/`
+   when it is part of the public documentation.
+6. Runtime detector assets belong in `src/remove_ai_watermarks/assets/`.
+   Unregistered research candidates belong in
+   `scripts/assets/visible-mark-candidates/` so they are not shipped in the
+   wheel.
+
+The source distribution excludes `data/`; the wheel contains only package
+runtime assets.

data/calibration/doubao/README.md

@@ -1,17 +1,17 @@
 # Doubao visible watermark capture
 
-> **Status (captured 2026-05-29; alpha rebuilt 2026-05-31):** the black/gray/white captures were
-> taken and are now **committed** in `captures/` (solid colour + watermark, content-free). The alpha
-> map is rebuilt by `scripts/visible_alpha_solve.py doubao` (the careful gray-self solve shared with
-> Jimeng). The first build claimed "pixel-exact" but left a readable outline on the real sample (issue
-> #13 follow-up); removal now reverse-alphas, NCC-aligns, and applies a thin residual inpaint. See the
-> `doubao_engine.py` notes in the root `CLAUDE.md`. The text below is kept as the historical capture plan.
+> **Status (captured 2026-05-29; asset rebuilt 2026-05-31):** the
+> black and gray captures are committed here. The generated alpha
+> asset is now a detection silhouette and mask-shaping input only. Current
+> removal localizes the mark and sends its footprint to the shared fill backend.
+> Reverse-alpha recovery was retired. The details below preserve the historical
+> capture rationale.
 
 Goal: capture the Doubao "豆包AI生成" visible watermark over known flat backgrounds so we can
-build a per-pixel alpha map and a reverse-alpha-blend remover, the same way the Gemini sparkle
-engine works (`src/remove_ai_watermarks/gemini_engine.py`).
+rebuild and validate the detection silhouette used by
+`src/remove_ai_watermarks/doubao_engine.py`.
 
-## What we already know (verified from prior art, 2026-05-26)
+## Historical findings from the capture work
 
 - Blend model: **alpha compositing with a white logo** `watermarked = a*logo + (1-a)*original`,
   `logo = (255,255,255)`. Inversion: `original = (watermarked - a*logo) / (1-a)`.
@@ -19,14 +19,13 @@ engine works (`src/remove_ai_watermarks/gemini_engine.py`).
   both say "alpha map"). One commercial blog (pixelcleanai) claims "screen blend" instead; the gray
   capture below settles it empirically.
 - Position: **bottom-right corner**, small margins (right ~8-20px, bottom ~5px), scales with image size.
-  Confirmed by our sample `data/samples/doubao-1.png` (2048x2048) plus three sources.
+  Confirmed by our sample `data/fixtures/provenance/doubao-1.png` (2048x2048) plus three sources.
 - Size **scales with resolution**. Third-party numbers (~90x18 at <=1024, ~180x40 at >1024) are
   approximate and calibrated for ~1024-1280 outputs; at 2048 the strip is much larger. A shipped
   third-party alpha map is only 120x20, too small for our 2K/4K target -> capture fresh.
-- The planning assumption was that clean inversion leaves residue on textured backgrounds, so the
-  remover would pair the alpha map with inpainting. After the capture this turned out unnecessary at
-  the native width (recovery is pixel-exact there and inpaint is off); the shipped remover is
-  reverse-alpha only, with a residual inpaint applied off-native only.
+- The original implementation used reverse-alpha recovery. That path was later
+  removed in favor of localize then fill because the latter also handles moved
+  and re-rendered marks.
 
 ## Use doubao.com specifically
 
@@ -35,7 +34,7 @@ the captured template matches our target.
 
 ## How to capture (image-edit path, most reliable)
 
-For each seed in `seeds/`:
+For each locally generated solid-color seed:
 
 1. Open Doubao image generation, use the image-edit / reference mode, upload the seed.
 2. Prompt (Chinese preferred):
@@ -70,16 +69,15 @@ extracted by per-pixel min/median.
 - Original download, never a screenshot. PNG preferred; if Doubao only gives JPEG, note it.
 - No crop / edit / re-save. Default settings, watermark left ON.
 
-## Naming, drop into `captures/`
+## Committed inputs
 
 ```
 doubao_black_1x1_1.png
-doubao_white_1x1_1.png
-doubao_gray128_1x1_1.png
-doubao_black_16x9_1.png
-doubao_content_1x1_1.png
+doubao_gray_1x1_1.png
 ```
 
+The black and gray captures feed `scripts/visible_alpha_solve.py doubao`.
+
 ## Also report back
 
 1. Which resolutions and aspect ratios the Doubao UI actually offers.

data/calibration/gemini/README.md

@@ -1,8 +1,10 @@
 # Gemini (Nano Banana) visible sparkle capture
 
-> **Status (captured 2026-05-31):** black/gray/white captures taken and **committed**
-> in `captures/` (solid colour + the sparkle, content-free). The sparkle-on-black assets
+> **Status (captured 2026-05-31):** the required black capture is committed
+> here. The sparkle-on-black assets
 > `gemini_bg_{96,48}.png` are rebuilt by `scripts/visible_alpha_solve.py gemini`.
+> They support detection and footprint geometry. Current pixel recovery uses the
+> shared fill backend, not reverse-alpha inversion.
 
 Google Gemini (Nano Banana) stamps a four-point sparkle icon in the bottom-right corner
 via alpha compositing: `watermarked = a*logo + (1-a)*original`. Unlike the Doubao/Jimeng
@@ -20,7 +22,7 @@ text marks, the sparkle is captured over a **pure-black** background, where
 
 ## How to capture (image-edit path)
 
-For each solid-colour seed (`seeds/seed_{black,gray,white}_2048.png`, gitignored):
+For each locally generated black, gray, or white 2048 px seed:
 
 1. Open Gemini image generation, image-edit / reference mode, upload the seed.
 2. Prompt: `Recreate this image exactly as it is, keep it identical, do not add or change anything`
@@ -28,16 +30,15 @@ For each solid-colour seed (`seeds/seed_{black,gray,white}_2048.png`, gitignored
 
 Black is the key one (sparkle on black -> exact alpha). Gray/white cross-check.
 
-## Naming, drop into `captures/`
+## Committed input
 
 ```
 gemini_black_2048.png   # the key capture (sparkle on black)
-gemini_gray_2048.png
-gemini_white_2048.png
 ```
 
-The solid captures are **committed** (content-free). The synthetic `seeds/` and any
-real-content `gemini_content_*.png` validation download are gitignored (local-only).
+The gray and white captures were calibration cross-checks and are not needed to
+rebuild the assets. Synthetic seeds and real-content validation downloads stay
+local.
 Rebuild the assets with:
 
 ```

data/calibration/jimeng/README.md

@@ -1,15 +1,13 @@
 # Jimeng (即梦AI) visible watermark capture
 
-> **Status (completed 2026-05-30):** solid black/gray/white Jimeng captures were
-> obtained (issue #13, from @powersee) and the alpha map was solved. Removal is
-> reverse-alpha plus a residual inpaint over the glyph footprint; see the
-> `jimeng_engine.py` notes in the root `CLAUDE.md`. The text below is kept as the
-> capture plan.
+> **Status (completed 2026-05-30):** solid black and gray Jimeng captures were
+> obtained and the detection asset was solved. The asset now supports detection
+> and mask geometry only. Current removal localizes the wordmark and uses the
+> shared fill backend. The text below records the capture and calibration work.
 
 Goal: capture the Jimeng / Dreamina "★ 即梦AI" visible wordmark over known flat
-backgrounds so we can build a per-pixel alpha map and a reverse-alpha remover, the
-same way the Gemini sparkle and Doubao strip engines work
-(`src/remove_ai_watermarks/gemini_engine.py`, `doubao_engine.py`).
+backgrounds so we can rebuild and validate the silhouette used by
+`src/remove_ai_watermarks/jimeng_engine.py`.
 
 ## What we learned (verified from the captures, 2026-05-30)
 
@@ -32,11 +30,10 @@ same way the Gemini sparkle and Doubao strip engines work
   width; a real 1440-wide download matched width_frac ~0.21.
 - **Per-image render variation:** the alpha maps solved independently from the
   black and the gray capture correlate 0.998 but not 1.0 (mean |Δa| ~0.02). Jimeng
-  re-rasterizes the mark per generation AND jitters its position a few px, so a
-  single alpha map does NOT pixel-cancel the mark the way Doubao's deterministic
-  overlay does. Removal therefore: NCC-aligns the alpha to the actual mark (always,
-  not only off-native), reverse-alphas, then clears the residual with a THIN inpaint
-  over the glyph footprint (a wide full-footprint pass smeared the texture/edges).
+  re-rasterizes the mark per generation and jitters its position a few pixels.
+  This was one reason the old reverse-alpha path needed alignment and residual
+  inpainting. The current path instead detects the silhouette, localizes the
+  glyph footprint, and fills that footprint.
 
 ## How to capture (image-edit path, most reliable)
 
@@ -56,19 +53,15 @@ pure white (the mark is nearly invisible on white, as expected).
 - Original download, never a screenshot. PNG preferred; if Jimeng only gives JPEG, note it.
 - No crop / edit / re-save. Default settings, watermark left ON.
 
-## Naming, drop into `captures/`
+## Committed inputs
 
 ```
 jimeng_cap_A.png   # black seed run through Jimeng
-jimeng_cap_B.png   # white seed
 jimeng_cap_C.png   # gray seed
-jimeng_content_1.png  # a normal-content download, for end-to-end validation
 ```
 
-The solid `jimeng_cap_{A,B,C}.png` captures are **committed** (content-free: a solid
-colour + the watermark; the source for `scripts/visible_alpha_solve.py jimeng`). The
-synthetic `seeds/` and the real-content `jimeng_content_*.png` validation download are
-gitignored (local-only). Rebuild the alpha asset with:
+The A and C captures feed
+`scripts/visible_alpha_solve.py jimeng`. Rebuild the detection asset with:
 
 ```
 uv run python scripts/visible_alpha_solve.py jimeng   # or: all

data/calibration/samsung/README.md

@@ -0,0 +1,61 @@
+# Samsung Galaxy AI visible watermark capture
+
+> **Status (built 2026-06-05):** flat black and gray Samsung Galaxy AI captures
+> were obtained and the detection asset was solved. The asset now supports
+> detection and mask geometry only. Current removal localizes the wordmark and
+> uses the shared fill backend. The text below records the capture plan and its
+> locale and resolution limits.
+
+Goal: capture the Samsung Galaxy AI "✦ Contenuti generati dall'AI" visible wordmark
+over known flat backgrounds so we can rebuild and validate the silhouette used
+by `src/remove_ai_watermarks/samsung_engine.py`.
+
+## What we learned (verified from the captures, 2026-06-05)
+
+- Mark: a sparkle icon followed by the locale string "Contenuti generati dall'AI"
+  (Italian), a light low-opacity (peak alpha ~0.38) semi-transparent **white**
+  overlay, anchored **bottom-LEFT** (Doubao/Jimeng are bottom-right). The string is
+  locale-specific, so the alpha template is per-locale; this build is the Italian
+  variant. Other locales need their own captured template.
+- Blend model: alpha compositing with a pure-white logo, `watermarked =
+  a*255 + (1-a)*original`, solved from the GRAY capture (same careful recipe as
+  Doubao/Jimeng: cubic-background fit, mean over channels, full halo extent,
+  unblurred). The white capture confirms the logo is white; on white the mark is
+  white-on-white and not detectable (no contrast), which is fine -- there is nothing
+  to recover there.
+- Geometry (fraction of image WIDTH): asset width ~0.32, height ~0.038, left margin
+  ~0.011, bottom margin ~0.006. The mark scales with width: a 1086-wide flat capture
+  and a 2958-wide real photo both measure width_frac ~0.31.
+- **Resolution caveat (open quality follow-up):** the flat black/gray/white captures
+  arrived at the phone's flat-edit size (1086 wide and a landscape 1920 set), while
+  the real photos are ~3000 wide, so the captured glyph (~334 px) is ~2.7x smaller
+  than on a real photo (~900 px). The alpha is solved at the capture size and
+  width-scaled + NCC-aligned per image, which removes the mark cleanly (verified on a
+  real 2958-wide photo: re-detect 0.79 -> 0.00, no readable text or outline), but a
+  flat capture taken at the real photo resolution (~3000 wide) would let the alpha be
+  pixel-sharp instead of upscaled. Not a blocker; a quality upgrade if a full-res
+  flat capture is provided.
+
+## Capture protocol (to re-capture or add a locale)
+
+On a Samsung Galaxy AI device (set the UI language to the target locale):
+
+1. Run the AI edit (Generative Edit / Sketch to Image) on a solid black image, so
+   the overlay lands on a flat black background. Download the ORIGINAL output file
+   (not a screenshot, no crop or re-save).
+2. Repeat over solid white and solid gray (those pin the exact glyph color).
+3. Ideally run all three flat edits at the same resolution as real photos (~3000
+   wide) so the alpha map is pixel-sharp rather than upscaled.
+4. Plus 3-5 real outputs with the visible mark over normal content for validation.
+
+## Files
+
+- `samsung_black_1.png` and `samsung_gray_1.png` are the retained solver inputs.
+- White, secondary-resolution, and real-content captures were validation
+  material and are not required to rebuild the asset.
+
+Rebuild the detection asset with:
+
+```
+uv run python scripts/visible_alpha_solve.py samsung
+```

data/evaluations/fidelity/README.md

@@ -0,0 +1,37 @@
+# Pipeline fidelity evaluation
+
+This evaluation compares diffusion pipelines with
+`scripts/fidelity_metrics.py`. The images themselves have one canonical home
+in `data/synthid/originals/`; this directory stores only evaluation-specific
+ground truth and instructions.
+
+| Original | Provider | Content | Exercises |
+| --- | --- | --- | --- |
+| `ChatGPT Image May 31, 2026, 02_03_55 PM.png` | OpenAI | Multilingual typography | Text preservation |
+| `Gemini_Generated_Image_633uuy633uuy633u.png` | Google | Landscape with a Chinese sign | CJK text preservation |
+| `Gemini_Generated_Image_y48j3cy48j3cy48j.png` | Google | Portrait grid | Face identity and skin texture |
+
+## Text ground truth
+
+`ground-truth.json` contains hand-verified OCR for the two text-bearing
+originals. To regenerate an OCR seed:
+
+```bash
+uv run scripts/fidelity_metrics.py ocr \
+  "data/synthid/originals/ChatGPT Image May 31, 2026, 02_03_55 PM.png" \
+  data/synthid/originals/Gemini_Generated_Image_633uuy633uuy633u.png \
+  --langs en,ru,ch \
+  --out data/evaluations/fidelity/ground-truth.json
+```
+
+Verify and correct the generated text by hand before using it as ground truth.
+
+## Compare
+
+```bash
+uv run scripts/fidelity_metrics.py compare \
+  --original data/synthid/originals/Gemini_Generated_Image_y48j3cy48j3cy48j.png \
+  --variant controlnet=<out>.png \
+  --variant qwen=<out>.png \
+  --ocr-langs ""
+```

data/evaluations/fidelity/ground-truth.json

@@ -0,0 +1,4 @@
+{
+  "ChatGPT Image May 31, 2026, 02_03_55 PM.png": "This is a longer sample text in English.\nTypography can flow smoothly from large to medium size.\nSmaller lines help demonstrate hierarchy, rhythm, and clarity.\nEven the finest text should remain clean and readable.\n这是一段较长的中文示例文本。\n排版可以从大字号逐渐过渡到中字号。\n更小的文字能够展示层次、节奏与清晰度。\n即使是最小的一行，也应该保持清楚易读。\nЭто более длинный пример текста на русском языке.\nТипографика может плавно переходить от крупного размера к среднему.\nБолее мелкие строки показывают иерархию, ритм и ясность.\nДаже самый маленький текст должен оставаться чистым и читаемым.",
+  "Gemini_Generated_Image_633uuy633uuy633u.png": "每天都是一个新的机会。\n用微笑开始它。\n世界也会向你微笑。"
+}

data/samples/openai-images-2/README.md

@@ -1,41 +0,0 @@
-# OpenAI ChatGPT Images 2.0 sample
-
-Reference image generated by OpenAI's ChatGPT Images 2.0 (`gpt-image-2`, launched 2026-04-21). Kept in the repo so the C2PA manifest parser and invisible-watermark pipeline can be re-verified against a real production output.
-
-## `amur-leopard.png`
-
-- Resolution: 1055 x 1491, PNG, 3.0 MB
-- Downloaded: 2026-04-22
-- Content: AI-generated infographic about the Amur leopard (*Panthera pardus orientalis*), chosen to exercise the model's new accurate-text-rendering feature
-
-### Embedded C2PA manifest (caBX chunk, 23607 bytes)
-
-Parsed by `remove-ai-watermarks metadata --check`:
-
-| Field | Value |
-| --- | --- |
-| `claim_generator` | GPT-4o |
-| `c2pa_spec` | 2.2.0 |
-| `digital_source_type` | http://cv.iptc.org/newscodes/digitalsourcetype/trainedAlgorithmicMedia |
-| `c2pa_actions` | created, converted |
-| Signer | OpenAI OpCo, LLC / OpenAI Media Service API |
-| Claim signing CA | Trufo C2PA Claim Signing CA (2025) -> Trufo C2PA Root CA (ECC P384) |
-| Timestamp authority | OpenAI TSA Issuing CA -> OpenAI TSA Root CA |
-
-The `trainedAlgorithmicMedia` tag is what triggers "Made with AI" labels on Instagram, Facebook, and X.
-
-### Invisible pixel-level watermark
-
-OpenAI's system card for Images 2.0 states the model embeds an "imperceptible, robust, and content-specific" pixel-level watermark alongside C2PA. This sample was downloaded 2026-04-22, before OpenAI's 19 May 2026 rollout of Google's SynthID watermark across ChatGPT / Codex / the API, so it likely predates SynthID and carries only the original content-specific watermark. Since that rollout, the openai.com/verify tool (in preview) is the public oracle for both signals; there is still no local decoder, so bypass cannot be verified empirically here without the oracle.
-
-## Reproducing the removal
-
-```bash
-# C2PA strip only
-remove-ai-watermarks metadata amur-leopard.png --remove -o amur-leopard.clean.png
-
-# Full pipeline (visible + diffusion regeneration + metadata)
-remove-ai-watermarks all amur-leopard.png -o amur-leopard.all.png --device mps
-```
-
-Note: the diffusion step runs at native resolution by default (no pre-downscale), so fine text on a text-heavy infographic like this one is preserved. Pass `--max-resolution N` only if a very large image OOMs the GPU/MPS (that reintroduces a lossy downscale then upscale round-trip).

data/synthid/README.md

@@ -1,11 +1,10 @@
-# SynthID reference corpus
+# SynthID oracle fixtures
 
-A locally-collected, labeled image corpus for SynthID work. Two downstream uses:
+A compact set of externally verified originals for two uses:
 
-1. **Per-resolution spectral codebook** for an experimental SynthID detector
-   (carrier frequencies are resolution-dependent, so labels must record the
-   exact native resolution).
-2. **Removal regression set** — verify that our pipeline turns a SynthID-positive
+1. **Signal and detector-limit research** with exact native resolutions and
+   recorded verification sources.
+2. **Removal regression set**: verify that a pipeline turns a SynthID-positive
    image into a negative one.
 
 There is no reliable local detector of the SynthID pixel watermark (Google's
@@ -15,23 +14,40 @@ external oracle, recorded per image in `verified_via` (see below).
 ## Layout
 
 ```
-data/synthid_corpus/
-  README.md        # this protocol (committed)
-  manifest.csv     # labels + provenance (committed; one row per tracked image)
-  images/          # the labeled corpus (committed)
-    pos/           # SynthID present
-    neg/           # SynthID absent (incl. reviewed real photos)
-    cleaned/       # our pipeline output from a pos image
-  refs/            # synthetic black/white calibration fills (gitignored, regenerable)
+data/synthid/
+  README.md                  # collection and verification protocol
+  manifest.csv               # one row per committed original
+  full-pipeline-quality.csv  # reusable evaluation selection
+  originals/                 # one canonical copy of each verified source
 ```
 
-The labeled images are committed so the corpus is reproducible and the removal
-regression set runs in CI. `manifest.csv` is kept in sync with the files on
-disk (one row per tracked image; dangling rows are pruned when files are
-removed). Before adding any image, confirm it carries no private or
-identifiable content you would not publish -- this is a public repo and git
-history is permanent. The synthetic `refs/` fills stay gitignored (regenerable,
-not part of the labeled set).
+The originals are committed so the evaluation set is reproducible and its
+hashes can be checked in CI. `manifest.csv` is kept in sync with
+`originals/`, one row per file. Generated outputs do not belong here. Store
+them outside the repository and record only a reproducible verdict in the
+evaluation manifest or documentation.
+
+## Reusable removal-quality set
+
+`full-pipeline-quality.csv` is the canonical reusable input set for
+full-pipeline visual-quality and watermark-removal tests. Its fixtures are
+cleared for permanent public test reuse. Tests, benchmarks, and manual
+evaluation bundles may read these images repeatedly without requesting new
+permission.
+
+The CSV preserves each platform's original filename and maps it to the one
+canonical corpus copy. Use `corpus_path` to read the input, but preserve
+`source_filename` in generated result names and keep OpenAI and Gemini outputs
+in separate provider groups. This avoids duplicating large PNGs while retaining
+the names needed for the corresponding provider oracle.
+
+Rows with a dated negative `final_clean_oracle` were checked after the complete
+`visible -> qwen-zimage -> metadata` route with the matching provider oracle.
+`not-checked-in-final-candidate` means the input is available as an additional
+quality stress fixture, but a newly generated output still needs the matching
+oracle before claiming removal. The checked result applies to those exact
+output bytes; re-run the oracle after changing the pipeline, seed, model
+versions, or runtime settings.
 
 ## Verification levels (`verified_via`)
 
@@ -44,33 +60,25 @@ Ground-truth quality, strongest first:
 - `third-party` — label asserted by an external dataset, not independently verified.
 - `none` — unverified.
 
-Prefer `gemini-app` for any image that will train the codebook or gate a test.
+Prefer `gemini-app` for any Google image that will gate a test.
 
 ## What to collect
 
-For the **codebook** (per target resolution, e.g. 1024x1024, 1024x1536, 1536x2816):
-
-- 30-50+ SynthID-positive outputs per resolution (more is better; ~150-200 per
-  resolution materially improves carrier discovery).
-- At each target resolution, also a batch of **pure-black (#000000)** and
-  **pure-white (#FFFFFF)** fills generated by the SynthID model — these isolate
-  the content-independent carrier (the watermark is most of the signal there).
-
 For the **regression set**:
 
-- A handful of `pos` images, their `cleaned` counterparts (run through our
-  pipeline), and the cleaned re-verified via `gemini-app` (should read negative).
-- `neg` controls: non-AI photos and outputs from non-SynthID models (SD,
-  Midjourney, Firefly) verified negative.
+- A small number of positive originals with a recorded provider oracle.
+- A quality-set row for every original used by repeatable evaluation.
+- Re-run the provider oracle on each newly generated output. Do not commit the
+  generated output as another corpus copy.
 
 The corpus is committed to a public repo: review every image before adding it
 and keep out anything private or identifiable you would not publish.
 
 ## Ingesting
 
-Use `scripts/synthid_corpus.py` — it copies a file in, records its sha256,
-resolution, format, and C2PA issuer (via our own detector), and appends a row
-to `manifest.csv`:
+Use `scripts/synthid_corpus.py` to copy a file into `originals/`, record its
+SHA-256, resolution, format, and C2PA issuer through our detector, and append a
+row to `manifest.csv`:
 
 ```bash
 uv run python scripts/synthid_corpus.py ingest path/to/*.png \
@@ -82,6 +90,10 @@ uv run python scripts/synthid_corpus.py status   # counts by label / resolution
 
 ## Autonomous collection via Chrome MCP
 
+> Historical collection notes. Browser interfaces and download behavior can
+> change independently of this repository. These steps do not define package
+> behavior.
+
 Generation can be driven through the browser (the account must be logged in):
 
 - **Gemini** (`gemini.google.com`): type `Create an image: <prompt>`, wait, hover the
@@ -122,8 +134,8 @@ Download; Leonardo serves the original JPEG in-chat (download button matches).
 
 ## Per-platform watermark map (observed, May 2026)
 
-What each platform actually embeds, verified by byte-scan (and Gemini-app oracle
-where noted). The detector's coverage is complementary: metadata catches C2PA /
+This is a dated observation table, not a live provider compatibility promise.
+The detector's coverage is complementary: metadata catches C2PA /
 IPTC; `exif_generator` catches EXIF `Make`/`Software` + XMP `CreatorTool`;
 `invisible_watermark.py` (imwatermark) catches the open SD/SDXL/FLUX DWT-DCT
 watermark on pristine files; the visible detector catches the Gemini-family

data/synthid/full-pipeline-quality.csv

@@ -0,0 +1,8 @@
+provider,source_filename,corpus_path,sha256,original_signal_verified_via,final_clean_oracle
+openai,"ChatGPT Image May 30, 2026, 10_31_08 AM.png","originals/ChatGPT Image May 30, 2026, 10_31_08 AM.png",28ff8732b037f98a4ef5bc277bbcdaa32e5eb9ccbd00b6c8c616e46ef68ae8a0,openai-verify,openai-verify-negative-2026-07-25
+openai,"ChatGPT Image May 31, 2026, 02_02_23 PM.png","originals/ChatGPT Image May 31, 2026, 02_02_23 PM.png",228e54413a3ef62b313176dcdba774a56a58c36b54227d1440bc26cbe0aefd82,c2pa-metadata,not-checked-in-final-candidate
+openai,"ChatGPT Image May 31, 2026, 02_03_55 PM.png","originals/ChatGPT Image May 31, 2026, 02_03_55 PM.png",05b836ecfe40fd689177fda74384ae4fdcc446505bbc4281cd3cbb6523eb669e,openai-verify,openai-verify-negative-2026-07-25
+gemini,"Gemini_Generated_Image_3mc4t93mc4t93mc4.png","originals/Gemini_Generated_Image_3mc4t93mc4t93mc4.png",2c33e75a2db614ce74c83cc0a6ac6c3ac735aca83ab88c9c9345843b124f7856,gemini-app,gemini-app-negative-2026-07-25
+gemini,"Gemini_Generated_Image_633uuy633uuy633u.png","originals/Gemini_Generated_Image_633uuy633uuy633u.png",4affd7f27767a445db6abf741355743ba8d95108ad922c9fff045feed8492236,gemini-app,gemini-app-negative-2026-07-25
+gemini,"Gemini_Generated_Image_akdbeiakdbeiakdb.png","originals/Gemini_Generated_Image_akdbeiakdbeiakdb.png",8c1a6fb03ef3d45a1f958fb3401e4264e409ff88c2a793061db7f29023454d0e,gemini-app,gemini-app-negative-2026-07-25
+gemini,"Gemini_Generated_Image_y48j3cy48j3cy48j.png","originals/Gemini_Generated_Image_y48j3cy48j3cy48j.png",45d79a683134fcba1b147b2aedb669783d474e1fb8a4df329729a0904fd1b46b,gemini-app,gemini-app-negative-2026-07-25

data/synthid/manifest.csv

@@ -0,0 +1,8 @@
+sha256,filename,label,source,model,width,height,format,c2pa_issuer,synthid_metadata,verified_via,added,notes
+05b836ecfe40fd689177fda74384ae4fdcc446505bbc4281cd3cbb6523eb669e,"ChatGPT Image May 31, 2026, 02_03_55 PM.png",pos,ChatGPT,gpt-image,1122,1402,png,OpenAI,yes,openai-verify,2026-06-04T00:07:53Z,June 2026 strength-study subject; openai.com/verify: SynthID detected (docs/synthid.md 2.2)
+28ff8732b037f98a4ef5bc277bbcdaa32e5eb9ccbd00b6c8c616e46ef68ae8a0,"ChatGPT Image May 30, 2026, 10_31_08 AM.png",pos,ChatGPT,gpt-image,1448,1086,png,OpenAI,yes,openai-verify,2026-06-04T00:07:53Z,June 2026 strength-study subject; openai.com/verify: SynthID detected (docs/synthid.md 2.2)
+4affd7f27767a445db6abf741355743ba8d95108ad922c9fff045feed8492236,Gemini_Generated_Image_633uuy633uuy633u.png,pos,Gemini app,gemini,2816,1536,png,Google LLC,yes,gemini-app,2026-06-04T00:08:05Z,June 2026 strength-study subject; Gemini-app Verify with SynthID: detected (docs/synthid.md 2.2)
+8c1a6fb03ef3d45a1f958fb3401e4264e409ff88c2a793061db7f29023454d0e,Gemini_Generated_Image_akdbeiakdbeiakdb.png,pos,Gemini app,gemini,2816,1536,png,Google LLC,yes,gemini-app,2026-06-04T00:08:05Z,June 2026 strength-study subject; Gemini-app Verify with SynthID: detected (docs/synthid.md 2.2)
+45d79a683134fcba1b147b2aedb669783d474e1fb8a4df329729a0904fd1b46b,Gemini_Generated_Image_y48j3cy48j3cy48j.png,pos,Gemini app,gemini,2816,1536,png,Google LLC,yes,gemini-app,2026-06-04T00:08:05Z,June 2026 strength-study subject; Gemini-app Verify with SynthID: detected (docs/synthid.md 2.2)
+2c33e75a2db614ce74c83cc0a6ac6c3ac735aca83ab88c9c9345843b124f7856,Gemini_Generated_Image_3mc4t93mc4t93mc4.png,pos,Gemini app,gemini,2816,1536,png,Google LLC,yes,gemini-app,2026-06-04T00:08:05Z,June 2026 strength-study subject; Gemini-app Verify with SynthID: detected (docs/synthid.md 2.2)
+228e54413a3ef62b313176dcdba774a56a58c36b54227d1440bc26cbe0aefd82,"ChatGPT Image May 31, 2026, 02_02_23 PM.png",pos,ChatGPT,gpt-image,1122,1402,png,OpenAI,yes,c2pa-metadata,2026-07-25T20:21:33Z,Reusable full-pipeline quality fixture; original filename preserved in quality-set manifest; cleared for public test reuse

data/synthid_corpus/manifest.csv

@@ -1,26 +0,0 @@
-sha256,filename,label,source,model,width,height,format,c2pa_issuer,synthid_metadata,verified_via,added,notes
-4ef377bde1a1d4eff141972841938643b173f5052992a018b9a21b31ac31731e,"4ef377bd-ChatGPT Image May 23, 2026, 02_43_02 PM.png",pos,ChatGPT,gpt-image,1254,1254,png,OpenAI,yes,openai-verify,2026-05-23T21:48:12Z,fresh post-rollout 2026-05-23; openai.com/verify: SynthID+C2PA detected
-d09f84c0e4c6d8b336bf4a9a7277314e940dcb5052ae7051e785cbb3bb42d656,d09f84c0-Gemini_Generated_Image_vq7wkwvq7wkwvq7w.png,pos,Gemini app,gemini,2816,1536,png,Google LLC,yes,c2pa-metadata,2026-05-23T21:52:40Z,"user: latest Gemini, SynthID v2"
-7b650522d42db09568e249c04d683c469fb3e280a2c53fcd1031cb9df27c619a,"7b650522-ChatGPT Image May 24, 2026, 12_19_54 PM.png",pos,ChatGPT,gpt-image,1602,982,png,OpenAI,yes,c2pa-metadata,2026-05-24T19:20:25Z,content: misty pine forest at dawn
-fb28dba2a82cc101a92fdee5714867b32610d0564f37737fe4bb70782b8ecf32,fb28dba2-Gemini_Generated_Image_dsjlnsdsjlnsdsjl.png,pos,Gemini app,gemini,2816,1536,png,Google LLC,yes,c2pa-metadata,2026-05-24T19:30:25Z,content: elderly fisherman portrait
-d20d4cc936dbdfe909c52502039a9e84ba93d97b42b24a0acee5b7d6c71930ae,d20d4cc9-Gemini_Generated_Image_ug6kdpug6kdpug6k.png,pos,Gemini app,gemini,2816,1536,png,Google LLC,yes,c2pa-metadata,2026-05-24T19:33:15Z,content: red coffee mug product shot
-28f323345f6496d936c3f1a72f671ddf59d0f81565c24a63bf3286860f633afe,28f32334-chatgpt_fisherman.png,pos,ChatGPT,gpt-image,1023,1537,png,OpenAI,yes,c2pa-metadata,2026-05-24T19:39:20Z,content: elderly fisherman portrait (fetch+blob dl)
-88e61a384c2e0b12d97bc66046e4a10542b2987448ba89c4b49e66311e969c84,88e61a38-chatgpt_tokyo.png,pos,ChatGPT,gpt-image,1023,1537,png,OpenAI,yes,c2pa-metadata,2026-05-24T19:42:02Z,content: tokyo street night (fetch+blob dl)
-1fa5f77f710c11a4cc69fed60195450def734401ed57c2600a84ce191f985440,1fa5f77f-IMG_0786.HEIC,neg,iPhone (me/post_photos),,4032,3024,heic,,,none,2026-05-24T20:58:47Z,post photo; no C2PA/SynthID (verified)
-2ea228ed270cd169e9d38bc3f1a162de7edbf54b6e5ad3c701a3c90010ec7067,2ea228ed-IMG_1791.HEIC,neg,iPhone (me/post_photos),,4032,3024,heic,,,none,2026-05-24T20:58:47Z,post photo; no C2PA/SynthID (verified)
-0bb4c176d83fbcbf4e628de7587d6183b9134c4f3fa85f55b96e94185273c7f6,0bb4c176-IMG_1790.HEIC,neg,iPhone (me/post_photos),,4032,3024,heic,,,none,2026-05-24T20:58:47Z,post photo; no C2PA/SynthID (verified)
-3fc0c4253f86427777904f41355eacbdcc1a29f6897ec694c7fc68b6e7f70846,3fc0c425-IMG_1450.HEIC,neg,iPhone (me/post_photos),,4032,3024,heic,,,none,2026-05-24T20:58:48Z,post photo; no C2PA/SynthID (verified)
-2b148db2b1a314a87647a03828b3d235e7c4c939252f448b572b7658c7bb9723,2b148db2-IMG_1832.HEIC,neg,iPhone (me/post_photos),,4032,3024,heic,,,none,2026-05-24T20:58:48Z,post photo; no C2PA/SynthID (verified)
-2d02fed0b6d60ce1142eadac9837a83896569dddbdad7cc5cfdec018f0506d36,2d02fed0-IMG_1520.HEIC,neg,iPhone (me/post_photos),,4032,3024,heic,,,none,2026-05-24T20:58:48Z,post photo; no C2PA/SynthID (verified)
-8f170c06f843c2bcf4cf6e249dd76365287fdb3a322637ba93c570f50cb19772,8f170c06-IMG_1078.HEIC,neg,iPhone (me/post_photos),,4032,3024,heic,,,none,2026-05-24T20:58:48Z,post photo; no C2PA/SynthID (verified)
-3fc4c8316012abc462df5534d4d995e5af84d35076a2927331107ff994293d9e,3fc4c831-IMG_2566.HEIC,neg,iPhone (me/post_photos),,5712,4284,heic,,,none,2026-05-24T20:58:48Z,post photo; no C2PA/SynthID (verified)
-5fe59521d579b536340253d2bcaa7c28ddd2485fa964fc27a9b9e5118ad0cdd1,5fe59521-IMG_1496.HEIC,neg,iPhone (me/post_photos),,4032,3024,heic,,,none,2026-05-24T20:58:48Z,post photo; no C2PA/SynthID (verified)
-4ead7918a5aeea7fba78b36af44358fea7ed1db7f46f4bc675152b9d04e68c38,4ead7918-IMG_1300.HEIC,neg,iPhone (me/post_photos),,4032,3024,heic,,,none,2026-05-24T20:58:48Z,post photo; no C2PA/SynthID (verified)
-4c795238b89178cf52a3674e721ed7f4cd5068028385491d12171a3c62545c35,4c795238-IMG_3034.HEIC,neg,iPhone (me/post_photos),,5712,4284,heic,,,none,2026-05-24T20:58:49Z,post photo; no C2PA/SynthID (verified)
-5abfaccb37c549de67c7f3a751a528a423e24a82c643fdb29094be8debbb206d,5abfaccb-IMG_3018.HEIC,neg,iPhone (me/post_photos),,4032,3024,heic,,,none,2026-05-24T20:58:49Z,post photo; no C2PA/SynthID (verified)
-5fed1923d513c1e9ffcba2f240e617fa9344fb39d35144169570ece8b0bd0f33,5fed1923-IMG_0272.HEIC,neg,iPhone (me/post_photos),,4032,3024,heic,,,none,2026-05-24T20:58:49Z,post photo; no C2PA/SynthID (verified)
-06b04d8fe8e1cd6bee9a973f93bfda37586924cbfec7d372f59d52aa9196160b,06b04d8f-IMG_1474.HEIC,neg,iPhone (me/post_photos),,5712,4284,heic,,,none,2026-05-24T20:58:49Z,post photo; no C2PA/SynthID (verified)
-8fdb574a94e65e14ac29017cf2d5a2ede18a8c4e3f12e04c64292b0d38570062,8fdb574a-IMG_3557.HEIC,neg,iPhone (me/post_photos),,4032,3024,heic,,,none,2026-05-24T20:58:49Z,post photo; no C2PA/SynthID (verified)
-c86973424817f62510e2a312b85c52e05adf47ace87a8e717fd442607596f501,c8697342-aistudio_lake.png,pos,Google AI Studio (Nano Banana),gemini-2.5-flash-image,1024,1024,png,,,gemini-app,2026-05-24T21:39:09Z,"API/playground: SynthID pixel CONFIRMED (Gemini-app oracle) + visible sparkle, but NO C2PA/IPTC -> synthid_source blind spot"
-1f81827c06d67cf6f6c7f5d53ec8f9738183942a6d1d2717b161fea0fdcc540a,1f81827c-Designer.png,pos,Microsoft Designer,dall-e (Designer),1024,1024,png,"OpenAI, Microsoft",yes,c2pa-metadata,2026-05-24T22:18:40Z,C2PA issuer OpenAI+Microsoft; synthid_source=OpenAI (DALL-E surface inherits OpenAI SynthID+C2PA)
-f6dd47a5ffd319aea21bf10dcf9877097666420b02c2620080bac12b03976e7e,f6dd47a5-4ef377bd-gpt-image-2-cleaned.png,cleaned,"our pipeline (invisible/SDXL, native-res default)",stabilityai/stable-diffusion-xl-base-1.0,1254,1254,png,,,openai-verify,2026-05-25T20:50:38Z,"cleaned from 4ef377bd via v0.5.3 'all' at native 1254x1254 (prod-equivalent); openai.com/verify: SynthID NOT detected. Re-confirms #10 native-res default defeats OpenAI SynthID (closes #15 root cause). Note: native res OOMs on 20GB MPS, auto-fell back to CPU."

docs/cli.md

@@ -0,0 +1,276 @@
+# CLI guide
+
+The command line interface is organized around the type of work you want to do.
+
+```text
+remove-ai-watermarks [OPTIONS] COMMAND [ARGS]
+```
+
+Run `remove-ai-watermarks COMMAND --help` for the complete option list and
+defaults. This page focuses on choosing the right command.
+
+## Command dependency map
+
+| Command or signal | Required installation |
+| --- | --- |
+| `metadata` and metadata-only `identify` | Default package |
+| Visible signals in `identify` | `remove-ai-watermarks[visible]` (`pixels` is the minimal runtime) |
+| Open DWT-DCT signals in `identify` | `remove-ai-watermarks[detect]` |
+| Adobe TrustMark signals in `identify` | `remove-ai-watermarks[trustmark]` |
+| `visible` and `erase` with OpenCV | `remove-ai-watermarks[visible]` (`pixels` is the minimal runtime) |
+| `visible` or `erase` with MI-GAN | `remove-ai-watermarks[migan]` |
+| `visible` or `erase` with big-LaMa | `remove-ai-watermarks[lama]` |
+| `invisible` | `remove-ai-watermarks[diffusion]` |
+| `invisible --pipeline qwen-zimage` | `remove-ai-watermarks[qwen-zimage]` |
+| HEIC/HEIF/AVIF pixel input | Add `remove-ai-watermarks[heif]` |
+| Every production command and backend | `remove-ai-watermarks[all]` |
+
+`batch` requires the same extra as its selected mode. Extras can be combined in
+one installation, for example `remove-ai-watermarks[visible,detect,heif]`.
+
+## Inspect an image
+
+```bash
+remove-ai-watermarks identify image.png
+```
+
+`identify` always inspects supported metadata. When pixel extras are installed,
+it also evaluates supported visible and invisible pixel signals. When no signal
+is found, it reports the origin as unknown. It does not claim the image is
+clean.
+
+Machine readable output:
+
+```bash
+remove-ai-watermarks identify image.png --json
+```
+
+Metadata only inspection:
+
+```bash
+remove-ai-watermarks identify image.png --no-visible
+```
+
+Despite the historical option name, `--no-visible` skips both visible and open
+invisible pixel detectors. Metadata inspection still runs.
+
+## Remove known visible marks
+
+Install `remove-ai-watermarks[visible]` before using `visible` or `erase`.
+
+```bash
+remove-ai-watermarks visible image.png -o clean.png
+```
+
+The default behavior:
+
+- checks every registered visible mark;
+- removes every detected match;
+- selects the best installed fill backend;
+- strips AI metadata from the output.
+
+Use a specific mark:
+
+```bash
+remove-ai-watermarks visible image.png --mark gemini -o clean.png
+```
+
+Available mark names are printed by:
+
+```bash
+remove-ai-watermarks visible --help
+```
+
+Keep metadata:
+
+```bash
+remove-ai-watermarks visible image.png --keep-metadata -o clean.png
+```
+
+Use the strict visual gate without metadata or sibling corroboration:
+
+```bash
+remove-ai-watermarks visible image.png --sensitivity strict -o clean.png
+```
+
+When no known mark is detected, the command does not write a new output. Use
+`erase` if you can identify the affected region yourself.
+
+## Erase a region
+
+```bash
+remove-ai-watermarks erase image.png \
+  --region 1640,1930,400,100 \
+  -o clean.png
+```
+
+The region format is `x,y,width,height`. Repeat `--region` to erase more than
+one box:
+
+```bash
+remove-ai-watermarks erase image.png \
+  --region 20,20,180,60 \
+  --region 1640,1930,400,100 \
+  -o clean.png
+```
+
+Choose the fill backend:
+
+```bash
+remove-ai-watermarks erase image.png \
+  --region 1640,1930,400,100 \
+  --backend migan \
+  -o clean.png
+```
+
+`erase` accepts `cv2`, `migan`, and `lama`. The corresponding optional extra
+must be installed for a learned backend.
+
+## Strip AI metadata
+
+Inspect metadata:
+
+```bash
+remove-ai-watermarks metadata image.png --check
+```
+
+Remove AI metadata and write a new file:
+
+```bash
+remove-ai-watermarks metadata image.png --remove -o clean.png
+```
+
+When `-o` is omitted, removal overwrites the source. Standard metadata is kept
+unless you pass `--remove-all`.
+
+The command also supports the audio and video containers listed in
+[supported signals](supported-signals.md). ffmpeg must be available for the
+non-ISOBMFF audio and video path.
+
+## Remove invisible watermarks
+
+Install the diffusion dependencies first:
+
+```bash
+uv tool install --force "remove-ai-watermarks[diffusion]"
+```
+
+Then run:
+
+```bash
+remove-ai-watermarks invisible image.png -o clean.png
+```
+
+The command normally skips regeneration when no supported local signal is
+detected. Use `--force` when you know the image should be processed:
+
+```bash
+remove-ai-watermarks invisible image.png -o clean.png --force
+```
+
+### Choose a pipeline
+
+| Pipeline | When to use it |
+| --- | --- |
+| `controlnet` | Default compatibility profile with structural conditioning |
+| `sdxl` | Lighter plain SDXL regeneration |
+| `qwen` | Large CUDA oriented Qwen Image profile |
+| `qwen-zimage` | CUDA only high fidelity profile with a separate face stage |
+
+Example:
+
+```bash
+remove-ai-watermarks invisible image.png -o clean.png \
+  --pipeline qwen-zimage --force
+```
+
+The legacy `default` value is an alias for `sdxl`. The `--auto` option is
+deprecated, emits a warning, and changes nothing.
+
+### Work with limited memory
+
+Lower CUDA memory pressure:
+
+```bash
+remove-ai-watermarks invisible image.png -o clean.png \
+  --cpu-offload --force
+```
+
+Keep large images at native resolution while processing them in overlapping
+tiles:
+
+```bash
+remove-ai-watermarks invisible image.png -o clean.png \
+  --tile --max-resolution 0 --force
+```
+
+Or set a resolution cap:
+
+```bash
+remove-ai-watermarks invisible image.png -o clean.png \
+  --max-resolution 2048 --force
+```
+
+Tiling avoids the explicit downscale but each tile is regenerated separately.
+It is a memory strategy, not a guarantee of better quality.
+
+## Run the full pipeline
+
+The `all` command and the `all` installation extra are separate concepts. The
+command runs every applicable stage. Installing `remove-ai-watermarks[all]`
+makes every production backend available; a smaller installation such as
+`remove-ai-watermarks[visible,diffusion]` can also run the command with fewer
+optional backends.
+
+```bash
+remove-ai-watermarks all image.png -o clean.png
+```
+
+The command runs:
+
+1. visible mark removal;
+2. invisible watermark removal when available and applicable;
+3. AI metadata stripping.
+
+The visible options and diffusion options are also available on `all`.
+
+If diffusion is required but the `diffusion` extra is unavailable, `all` still
+writes the result of the visible and metadata stages, prints a prominent
+warning, and exits with code 1. This prevents a partial result from being
+reported as complete.
+
+## Process a directory
+
+```bash
+remove-ai-watermarks batch ./images --mode visible
+```
+
+Modes:
+
+- `visible`;
+- `invisible`;
+- `metadata`;
+- `all`.
+
+Set an output directory:
+
+```bash
+remove-ai-watermarks batch ./images \
+  --mode all \
+  --output-dir ./clean
+```
+
+The invisible and full modes accept the same main diffusion controls as their
+single image counterparts. Run `batch --help` for the authoritative option
+list.
+
+## Exit behavior
+
+The CLI uses nonzero exit codes for meaningful incomplete outcomes, including
+no detected target on commands that would otherwise regenerate or create a
+misleading unchanged result, processing errors, and a required invisible step
+that could not run.
+
+Scripts should check the process exit code and the output path. The detailed
+per-command contract is maintained in
+[module internals](module-internals.md#command-line-interface).

docs/controlnet-removal-pipeline-research.md

@@ -0,0 +1,651 @@
+# ControlNet-as-removal-pipeline research: can structure-conditioned regeneration scrub SynthID and keep text?
+
+> Research archive. This document records experiments, superseded defaults, and
+> deployment considerations from the time of the study. It does not define the
+> current CLI or Python API. See `README.md`, `docs/cli.md`, and
+> `docs/known-limitations.md` for current behavior.
+
+Date: 2026-06-02. Source: a manual primary-source pass (WebSearch + WebFetch over the
+watermark-removal-attack and SDXL-ControlNet literature). Prompted by issue #35
+(@newideas99 / Jacob): "as we use SDXL even at low strength that kills small text ... Do you
+think ControlNet could be added to preserve and still remove the watermark?" Clarified scope:
+Jacob means **replacing the removal pipeline itself** with a ControlNet-conditioned
+regeneration (structure held by the control signal), NOT a separate text-protection add-on.
+
+A deep-research workflow run was attempted first (`wf_3244411d-ffd`) and failed at the harness
+level (97 agents completed without emitting StructuredOutput; ~4.3 M tokens, no report). This
+note is the hand-run replacement.
+
+## The question, precisely
+
+Can a single full-image ControlNet-conditioned diffusion pass **replace** plain SDXL base 1.0
+img2img as the watermark remover, so that one structure-guided regeneration removes the
+invisible robust pixel watermark (Google SynthID) **everywhere** while keeping fine detail and
+small/CJK **text** legible across the whole image? The hard constraint is unchanged from
+`text-protection-research.md`: the watermark must be scrubbed everywhere including inside text,
+so any path that freezes or composites original text pixels is disqualified.
+
+## Executive summary
+
+The idea is **already academically validated as a watermark remover and is literally what we
+already ship** — CtrlRegen (ICLR 2025) is a canny-ControlNet + DINOv2-semantic pipeline that
+regenerates from clean noise. But the make-or-break gap is exact: **none of the
+watermark-removal papers validate TEXT or fine-detail preservation at all** — CtrlRegen reports
+only FID/PSNR/quality-model scores and explicitly contains no text, fine-detail, or
+hallucination analysis. Our shipped ctrlregen's empirical failure ("destroys real content,
+hallucinates micro-text in smooth regions") is precisely this unstudied failure mode of the
+published method, most likely driven by our **512 px tiling** (text occupies too few pixels per
+tile to regenerate legibly; edge-free smooth regions get DINOv2-semantic hallucination). The
+constructive path is NOT to keep fixing the SD1.5 CtrlRegen, but to port the structure-control
+idea onto an **SDXL-native** ControlNet (xinsir tile-sdxl / ControlNet-Union-SDXL) as a control
+add to our existing SDXL base 1.0 img2img, run it at **1024+, not 512 tiles**, and empirically
+sweep the (denoise strength x conditioning scale x resolution) cube against the SynthID oracle
+AND a text-legibility check. The central tension may be fundamental and must be measured: the
+conditioning strong enough to keep text legible may suppress regeneration enough to let SynthID
+survive; the regeneration strong enough to scrub may deform text regardless of edges.
+
+## Oracle validation 2026-06-04 — measured answer (AUTHORITATIVE; supersedes pre-oracle "scrubs SynthID" claims below)
+
+The central tension the summary predicted is now MEASURED against the live oracles
+(OpenAI `openai.com/verify` for OpenAI content; the Gemini app "Verify with SynthID"
+for Google content — each detects only its own vendor's payload). **Verdict: at the
+shipped low vendor-adaptive strength, controlnet is NOT a drop-in SynthID remover.**
+It preserves structure so well that the watermark survives on exactly the photoreal
+content it protects. Controlnet is the text/structure PRESERVATION pipeline; removal
+is set by STRENGTH, separately calibrated, not by the pipeline choice.
+
+This section is the single consolidated reference for the controlnet pipeline's
+removal behavior. (Mirrored briefly in `docs/synthid.md` §5.5 and the CLAUDE.md
+controlnet / face_restore bullets, which point here.)
+
+### What we measured (real gpt-image + Gemini originals)
+
+**1. Content × pipeline — neither pipeline clears all content at low strength.**
+OpenAI set, strength = vendor-adaptive (0.10 OpenAI / 0.15 no-C2PA), `--max-resolution 1536`:
+
+| content | controlnet (`--auto`) | plain `default` |
+|---|---|---|
+| flat text card | clean | clean |
+| flat graphic (logo/poster, large flat fills) | clean | **SynthID detected** |
+| photoreal (9-face grid) | **SynthID detected** | clean |
+| photoreal (bracelet product photo) | **SynthID detected** | clean |
+
+Mechanism: controlnet's dense edge map keeps the regeneration very close to the original
+on photoreal, so the SynthID-destroying perturbation never happens; but it freely
+repaints large flat fills. Plain img2img at low strength perturbs photoreal texture
+enough yet barely touches flat fills. So the survivors FLIP by content type — pipeline
+choice alone does not guarantee removal.
+
+**2. Seed non-determinism near threshold.** img2img uses a random seed unless `--seed`
+is passed, and there is no local SynthID detector to self-verify. The bracelet survived
+controlnet @0.15 in one run and CLEARED @0.15 in another (same pipeline+strength+res).
+So a single clean run does NOT establish a strength as safe — characterizing a reliable
+floor needs a seed-repeatability sweep (N runs, varied seed), not one pass.
+
+**3. Per-vendor controlnet strength ladder (photoreal, oracle):**
+- **OpenAI:** 0.10 detected → 0.15 borderline/non-deterministic → 0.20 cleared (with margin).
+- **Gemini** (harder vendor; default 0.15 vs OpenAI 0.10): most cleared at 0.15–0.25.
+- **Resolution is NOT the lever:** SynthID is robust to downscaling, and the study's
+  trend says LOWER processing res needs LESS strength, so 1024 was never the wall. A
+  Gemini face that resisted 0.15/0.20/0.25 was blocked by face-restore (#4), not strength.
+
+**4. `--restore-faces` RE-INTRODUCES SynthID (was the "stubborn face" mystery).** A
+Gemini face image stayed SynthID-detected through controlnet 0.15/0.20/0.25 WITH restore,
+but CLEARED at 0.20 with `--no-restore-faces` (clean single-variable A/B). GFPGAN runs on
+the **ORIGINAL watermarked** face at fidelity weight 0.5, blends ~half its pixels with the
+StyleGAN2 prior, and composites that back OVER the diffusion-cleaned face → the watermark
+returns in the face region. Content-dependent (smaller faces can clear with restore). So
+raising strength cannot fix it — the face is re-pasted from the original after diffusion.
+This also corrects the prior "GFPGAN scrubs SynthID / oracle-confirmed clean" claim (it was
+checked on one lucky image).
+
+### Certified controlnet strength floors (Modal GPU sweep + oracle, 2026-06-04)
+
+Run via an isolated Modal certification harness:
+controlnet, `restore_faces` OFF (it re-introduces SynthID), `--max-resolution 1536`,
+each image checked on ITS OWN vendor oracle (OpenAI -> openai.com/verify, Gemini -> the
+Gemini app; the two payloads are vendor-specific and never cross-checked):
+
+| vendor | **floor** | evidence (oracle, restore OFF, <= 1536) |
+|---|---|---|
+| **OpenAI** | **0.20** | 2 photoreal images (9-face grid + bracelet) x seed {1,2,3} = **6/6 clean**; the bracelet that FLIPPED at 0.15 is seed-robust at 0.20 |
+| **Gemini** | **0.30** | hardest face (gemini_3): 0.20 detected -> 0.30 clean on **2/2 seeds**; Gemini is the harder vendor (default 0.15 vs OpenAI 0.10) AND resolution-sensitive |
+
+- **OpenAI 0.20 transfers to prod as-is** (OpenAI removal is resolution-independent:
+  the study clears it at 0.05 across 1024-1600).
+- **Gemini 0.30 is the floor at <= 1536 only.** Gemini is resolution-sensitive (study:
+  native 2816 likely needs >= 0.30 even on `default`). A native-resolution
+  deployment should either cap Gemini to <= 1536 and
+  use 0.30, or run a native-resolution Gemini cert and expect a higher floor (~0.35+).
+
+### Recommendations for a removal pipeline
+
+- **Treat controlnet as PRESERVATION, not removal.** Choose it for text/structure content,
+  `default` for photoreal; removal efficacy comes from STRENGTH in both.
+- **Give controlnet a higher, per-vendor strength than `default`** (today both share
+  `resolve_strength` 0.10/0.15, tuned for plain img2img). **Certified controlnet floors:
+  OpenAI 0.20, Gemini 0.30** (see table above) — add a controlnet-specific per-vendor
+  schedule to `resolve_strength` rather than reusing the `default` ladder.
+- **Fix the seed in prod.** The non-determinism is purely `seed=None` (random); a fixed
+  `--seed` makes every run reproduce the certified-clean result, so you ship a
+  deterministic, re-certifiable config (and the seed sweep collapses to one config).
+- **`--restore-faces` is OFF in prod and stays opt-in.** Two methods ship
+  (`instantid` default, `photomaker`), both NON-COMMERCIAL. They REGENERATE the face
+  from an ArcFace embedding via SDXL diffusion, making the output face look more
+  AI-generated than the cleaned image (gloss, symmetric pores, SDXL "clean skin"
+  aesthetic). For production face preservation the cleaned image from controlnet 0.20
+  is the LEAST-AI state we can reach — any restore on top trades original-look for
+  embedding-driven regeneration. Empirical sweep summary: GFPGAN-on-cleaned polished
+  without identity recovery; PhotoMaker-V2 produced a different person; InstantID
+  txt2img produced studio-portrait patchwork on group photos; InstantID
+  img2img-on-cleaned with three parameter settings integrated scene context cleanly
+  but never recovered original identity precisely — every setting traded one problem
+  for another. See `docs/synthid-robust-identity-research-2026-06-08.md`
+  "Empirical follow-up" for the full sweep.
+- **No local SynthID detector exists** → the service can't self-verify; bake in strength
+  margin and periodic oracle spot-checks.
+- **Lesson:** visual-quality / face-identity recovery does NOT prove removal — only the
+  oracle does, across MULTIPLE content types; never conclude from a partial result (the
+  photoreal-only data first read as "controlnet shields, default removes"; the flat-graphic
+  result reversed it; the face mystery was restore, not strength).
+
+## Findings (with confidence and sources)
+
+### Finding 1 — confidence: high
+
+**Claim.** "ControlNet as the removal pipeline" is exactly CtrlRegen (ICLR 2025), and our
+shipped `ctrlregen` profile is a faithful implementation of it. Its **spatial control is canny
+edges** extracted from the watermarked image; its **semantic control is DINOv2-giant** via a
+trainable projection + decoupled cross-attention. Clean-noise (full-strength) regeneration
+scrubs the watermark from both pixel and latent space while the two control nets hold structure.
+
+**Evidence.** CtrlRegen: spatial control "conditioned on Canny edge images extracted from the
+watermarked image," integrated into the U-Net decoder blocks via a ControlNet structure;
+semantic control on "DINOv2-giant" embeddings. Removal is strong: TPR@1%FPR driven from 1.00 ->
+0.01 (StegaStamp) and 0.99 -> 0.12 (TreeRing). This matches our `ctrlregen/engine.py` exactly
+(canny detector + `facebook/dinov2-giant` + spatial ControlNet from `yepengliu/ctrlregen`).
+
+**Sources.** https://arxiv.org/html/2410.05470v1 · https://github.com/yepengliu/CtrlRegen ·
+https://openreview.net/forum?id=mDKxlfraAn
+
+### Finding 2 — confidence: high
+
+**Claim.** Regeneration provably removes any bounded-perturbation pixel watermark **given enough
+noise** — the operative constraint is the amount of regeneration, which is the same knob that
+trades against fidelity.
+
+**Evidence.** Zhao et al., "Invisible Image Watermarks Are Provably Removable Using Generative
+AI" (NeurIPS 2024): a noise-then-reconstruct regeneration attack "guarantees the removal of any
+invisible watermark" that perturbs the image within a bounded L2 distance. The guarantee is a
+function of injected noise magnitude — low noise preserves detail but leaves the watermark; high
+noise scrubs but discards original signal. This is the knob ControlNet conditioning is meant to
+make survivable (push regeneration high while the control signal holds composition).
+
+**Sources.** https://arxiv.org/abs/2306.01953 · https://github.com/XuandongZhao/WatermarkAttacker
+
+### Finding 3 — confidence: high
+
+**Claim.** The make-or-break gap: **no watermark-removal paper validates text or fine-detail
+preservation.** CtrlRegen's "high perceptual quality" is FID/PSNR/quality-model only and
+explicitly omits text, fine-detail, and hallucination analysis. So the literature does NOT
+support the specific claim Jacob needs (text survives), it is simply unmeasured.
+
+**Evidence.** CtrlRegen reports CLIP-FID, PSNR, Q-Align, LIQE; the fetched analysis confirms
+"the paper contains no discussion of text preservation, fine-detail retention, or hallucination
+artifacts," and "explicitly avoids discussing failure modes." Pixel metrics like PSNR are
+acknowledged not to reflect perception, and text legibility is a different axis than FID.
+
+**Sources.** https://arxiv.org/html/2410.05470v1
+
+### Finding 4 — confidence: medium-high
+
+**Claim.** Resolution is the prime suspect for our shipped ctrlregen's content destruction. We
+tile to **512 px** and run full clean-noise per tile; at 512 px text occupies too few pixels per
+tile to regenerate legibly, and smooth edge-free regions (no canny signal) are filled by the
+DINOv2 semantic prior, which hallucinates texture/micro-text. The paper omits resolution
+entirely, so this is an implementation regime it never characterized.
+
+**Evidence.** Our `ctrlregen/engine.py`: `PROCESS_SIZE = 512`, `TILE_SIZE = 512`, full strength
+on each tile. This mirrors the `_run_region_hires` insight (text needs MORE pixels under
+regeneration so strokes exceed the VAE's ~8 px latent floor), but ctrlregen runs the regeneration
+at LOW res, the opposite. CtrlRegen's paper gives no resolution/tiling spec to contradict this.
+
+**Sources.** the former internal
+`src/remove_ai_watermarks/noai/ctrlregen/engine.py` (removed after this study);
+resolution-omission
+confirmed against https://arxiv.org/html/2410.05470v1
+
+### Finding 5 — confidence: high
+
+**Claim.** SDXL-native ControlNets exist, so the removal-pipeline upgrade need NOT be the SD1.5
+re-architecture our current ctrlregen is. xinsir `controlnet-tile-sdxl-1.0` and
+`controlnet-union-sdxl-1.0` (ControlNet++) run on SDXL base 1.0. The tile model has a `tile_var`
+image-variation mode purpose-built to regenerate detail while preserving structure, at
+`controlnet_conditioning_scale = 1.0`, optimal 1024 px. This is a drop-in control add to our
+existing SDXL img2img.
+
+**Evidence.** xinsir tile-sdxl model card: use cases = deblur/detail-repaint, **image variation
+(preserving structure)**, super-resolution; `controlnet_conditioning_scale = 1.0`, ~30 steps,
+optimal 1024x1024, works with `madebyollin/sdxl-vae-fp16-fix` (the same VAE our fp16 path
+already swaps in). ControlNet-Union-SDXL / ControlNet++ merges 10+ control types (canny, HED,
+tile, depth, lineart) into one SDXL model.
+
+**Sources.** https://huggingface.co/xinsir/controlnet-tile-sdxl-1.0 ·
+https://huggingface.co/xinsir/controlnet-union-sdxl-1.0 · https://github.com/xinsir6/ControlNetPlus
+
+### Finding 6 — confidence: high
+
+**Claim.** The community tile-ControlNet upscale workflow runs at **LOW denoise (0.3-0.4)** —
+the wrong regime for watermark removal. It preserves detail precisely by regenerating little, so
+a naive tile-upscale preserves text AND preserves the watermark. The open empirical question is
+whether at `conditioning_scale ~1.0` you can push denoise high enough to scrub SynthID while the
+tile conditioning still holds text — the exact cell to test.
+
+**Evidence.** Stable-Diffusion-Art ControlNet-tile upscale: denoise "typically 0.3, max ~0.4 to
+avoid artifacts"; some users push 0.6 with ControlNet strength 0.5. Our own data: SynthID
+survives below the removal-strength threshold (current Gemini needs notably higher denoise than
+the tile-upscale regime). So the detail-preserving regime and the watermark-scrubbing regime are
+on opposite ends of the denoise axis; ControlNet conditioning is the bet that they can meet.
+
+**Sources.** https://stable-diffusion-art.com/controlnet-upscale/ ·
+internal (`docs/synthid.md` strength data)
+
+### Finding 7 — confidence: high
+
+**Claim.** Forensic-stealth caveat: diffusion-based regeneration is among the MOST detectable
+removal families. Even a ControlNet-regeneration that fools the SynthID oracle leaves forensic
+traces flagging the output as "removal-processed" at >98% TPR@1%FPR. This bounds the claim (do
+not over-promise "indistinguishable from an original") but does not block the use case — the
+SynthID oracle still reads negative.
+
+**Evidence.** "Removing the Watermark Is Not Enough: Forensic Stealth in Generative-AI Watermark
+Removal" (arXiv:2605.09203, Goonatilake & Ateniese, GMU): across six removal attacks including
+diffusion-based regeneration, independent forensic detectors separate removal-processed from
+clean content at >98% TPR under a 1% FPR budget.
+
+**Sources.** https://arxiv.org/html/2605.09203v1
+
+### Finding 8 — confidence: low (watch, do not build on yet)
+
+**Claim.** Partial/semantic-guided regeneration is an active sub-direction that explicitly targets
+the removal-vs-fidelity tradeoff, but the specific fidelity-on-text claims were not verifiable
+from the source in this pass.
+
+**Evidence.** "Removing Watermarks with Partial Regeneration using Semantic Information"
+(arXiv:2505.08234) proposes focusing regeneration on watermarked regions with semantic (VLM)
+conditioning to preserve untouched areas; the PDF body did not render cleanly enough to confirm
+its quantitative text/detail results. Treat as a pointer, not evidence.
+
+**Sources.** https://arxiv.org/pdf/2505.08234
+
+## Recommendation / decision
+
+**ControlNet-as-removal-pipeline is worth prototyping — but not by fixing the SD1.5 ctrlregen.**
+Port the structure-control idea onto an SDXL-native ControlNet as a control add to the existing
+SDXL base 1.0 img2img, run it at full resolution (1024+, NOT 512 tiles), and treat the
+text-vs-scrub tension as an empirical question to measure, not assume.
+
+**Prototype (runs locally on 32 GB MPS — no dedicated GPU required):**
+
+Compute is NOT the bottleneck. On a 32 GB Apple-silicon machine (M5 here) native SDXL already
+runs entirely on MPS with no CPU fallback (~155 s at 1122x1402, verified — see `synthid.md` /
+CLAUDE.md). The prototype runs at **1024** (fewer pixels than that) with SDXL base + an SDXL
+ControlNet + activations in **fp32** (MPS fp16 decodes to all-black NaN — issue #29 — confirmed
+on run 1 below; fp32 is the required default on mps/cpu) — fits the 32 GB budget with vae-tiling +
+attention-slicing; ~1-2 min/image, so a coarse sweep is a sub-hour background run. A dedicated GPU
+is needed ONLY for the separate
+native-large-Gemini (2816 px) case, which OOMs even without a ControlNet (that requires a
+GPU task). The genuine external dependency is NOT compute but the **manual SynthID oracle**:
+there is no local SynthID detector, so removal is verified by hand in the Gemini app
+("Verify with SynthID") per image, regardless of where the diffusion runs.
+
+Runner: **`scripts/controlnet_sweep.py`** (built 2026-06-02) implements exactly this sweep —
+SDXL base 1.0 + an SDXL-native ControlNet img2img, one output per (control x strength x scale)
+cell, plus a `sweep_index.csv` with empty `synthid_oracle` / `text_legible` columns to fill by
+hand. It uses the dedicated single-type xinsir models (`controlnet-canny-sdxl-1.0`,
+`controlnet-tile-sdxl-1.0`) rather than the Union model to keep the diffusers API path robust.
+
+    uv run python scripts/controlnet_sweep.py watermarked.png -o sweep_out
+
+1. SDXL base 1.0 img2img + `xinsir/controlnet-canny-sdxl-1.0` / `controlnet-tile-sdxl-1.0`
+   (sweep both `tile` and `canny` control), full image at 1024, `sdxl-vae-fp16-fix`.
+2. Sweep the cube on fresh Gemini + gpt-image inputs that contain small/CJK text:
+   - denoise strength {0.15, 0.3, 0.5, 0.7, 1.0}
+   - `controlnet_conditioning_scale` {0.5, 0.8, 1.0}
+   - control type {tile, canny}
+3. Per cell, measure BOTH axes:
+   - **removal**: Gemini app "Verify with SynthID" oracle (the only valid SynthID oracle; for
+     gpt-image also openai.com/verify for provenance) — must read clean.
+   - **text**: OCR round-trip / visual legibility of the small text.
+   - secondary: SSIM/FID vs original for global fidelity.
+4. Find the Pareto cell where the oracle is clean AND text stays legible.
+
+**The honest fork the prototype resolves:**
+- If such a cell exists -> the answer to Jacob is YES, ship an SDXL-native ControlNet removal
+  profile (replacing the SD1.5 ctrlregen) tuned to that cell.
+- If no cell clears both (the tension is fundamental: scrub-strength always deforms text, or
+  text-preserving conditioning always spares the watermark) -> the canny/tile-ControlNet middle
+  path is dead for text, and the standing answer reverts to `text-protection-research.md`: a full
+  **glyph-conditioned re-render** (EasyText / TextSR on a FLUX-DiT base) is required, which is a
+  base-model migration, not a control add.
+
+**Do not:** keep tuning the 512 px SD1.5 ctrlregen for text (wrong resolution, wrong base model);
+run tile-ControlNet at the community 0.3-0.4 upscale denoise and expect watermark removal (that
+regime preserves the watermark); over-claim forensic invisibility (Finding 7).
+
+## Prototype run 1 — 2026-06-02 (text axis measured; watermark axis pending the oracle)
+
+First sweep on a real, SynthID-positive, text-dense input: the corpus tokyo-street-night
+gpt-image (`88e61a38-chatgpt_tokyo.png`, 1023x1537 -> 680x1024, dense small CJK + Latin neon
+signage; SynthID + C2PA confirmed, so its valid oracle is openai.com/verify). Grid: control
+{canny, tile} x strength {0.3, 0.5, 0.7, 1.0} x `conditioning_scale` 1.0, fp32 on MPS. Outputs +
+`sweep_index.csv` (text verdicts filled by visual inspection; `synthid_oracle` left for the
+manual run) are under `/tmp/cnsweep/` (not committed — derived regenerations of corpus content).
+
+**Measured — PSNR vs input (proxy for how much was regenerated):**
+- canny: 0.3 -> 16.91, 0.5 -> 15.91, 0.7 -> 14.82, 1.0 -> 13.22 (monotonic drop = progressively
+  more regeneration as strength rises; canny only pins edges, so flat regions change).
+- tile: 0.3 -> 17.89, 0.5 -> 17.84, 0.7 -> 17.83, 1.0 -> 17.74 (**flat and high — near-identity
+  even at strength 1.0**; tile@scale1.0 pins the whole image to the input and barely regenerates).
+
+**Measured — text legibility (visual, focused on SMALL text; large high-contrast glyphs survive
+everything because canny/tile hold their edges):**
+- canny: legible at 0.3, softening at 0.5 (partial), garbling at 0.7, hallucinated pseudo-glyphs
+  at 1.0 ("NEC" -> "NWENES"). Same plain-img2img small-text deformation, only big text protected.
+- tile: near-identity through 0.7, only tiny alterations at 1.0 — small text preserved throughout.
+
+**Reading (the make-or-break tension, now visible in the data):**
+- **tile@scale1.0 does not actually regenerate** (flat PSNR), so it preserves all text but almost
+  certainly leaves the watermark intact — it is a near-identity pass, exactly the community
+  "tile-upscale preserves detail by not regenerating" regime (Finding 6), confirmed.
+- **canny@scale1.0 regenerates progressively** (PSNR drops) and so could scrub — but small text
+  breaks at exactly the strength where scrubbing would start to bite. canny saves big edges, not
+  sub-stroke small text.
+- Net on the text axis: neither cell at scale 1.0 cleanly gives "high regeneration + legible small
+  text." This is the literature prior (Findings 3, 6) reproduced empirically. Lowering
+  `conditioning_scale` to force small-text regeneration is the same tradeoff knob, not an escape.
+
+**Still pending (the decisive half, cannot be done locally):** run the 8 cells through the SynthID
+oracle and fill `synthid_oracle`. The most informative cells: canny 1.0 (text dead — does it at
+least scrub? if not, the canny path is dead outright), canny 0.5 (text partial — does it scrub?),
+tile 1.0 (text perfect — predicted to still read present). If no cell is `oracle=clean` AND
+`text=yes`, the fork resolves to the glyph-re-render path (`text-protection-research.md`).
+
+**Incidental bug caught:** the first run used fp16 on MPS (the script's original default) and
+produced **all-black** outputs across every cell (2 KB PNGs, PSNR 9.22 flat) — the issue #29
+fp16-VAE-NaN failure, and the fp16-fix VAE did not save it on MPS. Fixed `scripts/controlnet_sweep.py`
+to default fp32 on mps/cpu (fp16 only on cuda/xpu), matching the production pipeline.
+
+## Tuning ControlNet for text preservation across image types (research 2026-06-03)
+
+Goal: how to configure the canny-ControlNet path to best preserve text (and faces) on diverse
+images. Primary sources: diffusers ControlNet doc, the ControlNet paper (arXiv:2302.05543),
+xinsir model cards, practitioner guides. The **critical reframe**: almost all community ControlNet
+advice optimizes a txt2img *generation* tradeoff (control vs creative freedom). OUR context is
+img2img *watermark removal*, where the objective is the opposite -- maximum faithful preservation
+while regenerating just enough to scrub. So several common recommendations INVERT here.
+
+**Removal is `strength`; everything below is preservation and does not change removal efficacy**
+(only the watermark-shielding risk -- see the caveat). Set `strength` by the oracle/vendor need;
+tune these to keep text/faces intact at that strength.
+
+Knobs, ranked by impact for text:
+
+1. **Canny edge density (the per-image lever, currently hardcoded `_CANNY_LOW=100`/`_CANNY_HIGH=200`).**
+   Lower thresholds capture more/finer edges; higher thresholds keep only major outlines (diffusers
+   doc + practitioner guides; ControlNet paper uses 100/200 as the default). Small-text strokes and
+   fine facial features fall below the default 100/200 and are missed. **For dense small text
+   (infographics, signage) lower the thresholds (~50/120, even 30/100 for facial likeness per
+   practitioner tests); for high-contrast large text 100/200 already suffices.** Denser canny is
+   still a BINARY thresholded edge map, so it does not carry the low-amplitude SynthID pixel pattern
+   -- it passes more shape, not the watermark (still oracle-verify). This is the single highest-value
+   unexplored lever and should become a CLI knob.
+
+2. **`controlnet_conditioning_scale` -> keep at 1.0 (max structure hold).** Community defaults to 0.5
+   for creative balance; we want maximum preservation, so 1.0 (xinsir canny/tile cards also recommend
+   1.0). We measured text on a clean high-contrast image surviving across strength 0.1-0.5 at scale
+   1.0 (PSNR ~26 flat), so scale 1.0 is the right default; only lower it if a specific image needs
+   more regeneration to scrub (raises shielding risk the other way).
+
+3. **`control_guidance_start=0.0`, `control_guidance_end=1.0` (full window) -- KEEP, do not shorten.**
+   The common "end=0.5: establish structure early then let the model render detail freely" is a
+   creative-generation recipe; for text it is HARMFUL -- the late free steps re-render and deform the
+   glyphs. We want the edge control active through ALL denoise steps so text stays pinned. (Our
+   pipeline already uses the 0->1 default; the point is to NOT adopt the shorten-the-window advice.)
+
+4. **Control type, per image type:**
+   - **Text / graphics / high-contrast -> canny** (the literature's reliable choice for defined edges
+     and text; what we ship).
+   - **Faces / smooth tonal content -> soft-edge / HED is a candidate worth testing.** Canny's hard
+     binary threshold fractures smooth skin gradients; HED/soft-edge gives gradual edges that may hold
+     faces better. UNVERIFIED for removal (softer edges may carry slightly more original signal ->
+     oracle-check). A face-heavy image is the test (gemini group photos).
+   - **tile -> NOT for removal.** It is near-identity (detail-enhancement at low denoise); it shields
+     the watermark (measured flat PSNR ~17.8 across strength on the tokyo sweep). Do not use it as the
+     removal control.
+
+5. **Resolution** -- higher long-side = strokes span more VAE latent cells = less softening, while
+   still fully regenerating. Already a knob (`--max-resolution`); for tiny text prefer native/large.
+
+**Multi-ControlNet (canny + soft-edge), list scales e.g. `[1.0, 0.8]`** (diffusers MultiControlNet):
+could hold text edges AND face geometry at once, but doubles ControlNet memory/latency and raises the
+shielding risk; defer to a v2 after the single-canny path is dialed in.
+
+**Image-type playbook (proposed, to validate with the oracle):**
+- Clean high-contrast text (openai_1-style): canny 100/200, scale 1.0, full window -- already optimal.
+- Dense small text / infographics (big_pic3, neon signage): canny **lower thresholds (~50/120)**,
+  scale 1.0, full window, larger resolution.
+- Faces / portraits: try **soft-edge/HED** control, scale 1.0; or multi-ControlNet canny+softedge.
+
+**Hard caveat:** every change that increases preservation (higher scale, denser canny, fuller window,
+softer edges) marginally REDUCES effective regeneration and so raises the chance the watermark
+survives -- exactly the shielding failure mode. There is no local SynthID detector, so each tuning
+change must be re-confirmed on the oracle. These are img2img-context recommendations derived from
+generation-context sources plus our own measurements; treat the playbook as hypotheses to verify, not
+settled defaults.
+
+**Sources.** https://huggingface.co/docs/diffusers/en/using-diffusers/controlnet ·
+https://arxiv.org/pdf/2302.05543 · https://huggingface.co/xinsir/controlnet-canny-sdxl-1.0 ·
+https://huggingface.co/xinsir/controlnet-tile-sdxl-1.0 · https://blog.cephalon.ai/canny-and-softedge/
+
+## FaceID research: identity-preserving face conditioning (research 2026-06-03)
+
+Motivation: canny alone preserves face STRUCTURE/position better than plain SDXL but does NOT hold
+IDENTITY -- verified on a real Gemini group photo (gemini_3, s015): faces drift in expression and
+likeness (the smile/mouth and eyes change), they are "a similar person," not the same one. Canny
+carries edges, not identity, so the regenerated face is identity-drifted. To hold identity WITHOUT
+copying original pixels (the hard constraint -- copied pixels carry SynthID), the conditioning must
+be an identity EMBEDDING, not pixels. Primary sources: diffusers IP-Adapter doc, InstantID
+(arXiv:2401.07519), IP-Adapter (arXiv:2308.06721), practitioner comparisons.
+
+### Findings
+
+**1. IP-Adapter FaceID conditions on an ArcFace identity VECTOR, not pixels (confidence: high).**
+FaceID extracts `insightface` ArcFace `normed_embedding` (a ~512-d identity vector) via
+`FaceAnalysis`, and passes it as `ip_adapter_image_embeds` -- NOT a CLIP image embedding, NOT the
+original pixels. So it is constraint-compatible: the watermark (a pixel-amplitude pattern) is not in
+the identity vector, and the img2img still regenerates the pixels (removal via `strength` unchanged).
+It loads on any SDXL via `load_ip_adapter` (~100 MB), is fast/low-VRAM, but identity fidelity on SDXL
+is ~5-10% lower than the SD1.5 line / dedicated methods.
+
+**2. Multiple distinct faces ARE handled, via regional attention masks (confidence: high -- THE key
+unlock).** This is the make-or-break for group photos (our hardest case). diffusers supports a LIST
+of IP-Adapter face images each with its own binary region mask: `IPAdapterMaskProcessor` builds the
+masks, `set_ip_adapter_scale([[s1, s2, ...]])`, and `cross_attention_kwargs={"ip_adapter_masks":
+masks}`. So you detect each face, extract its own ArcFace embedding, assign it a region mask, and one
+pass preserves N different identities simultaneously. (InstantID, by contrast, is single-subject --
+it averages embeddings for multiple refs, which is wrong for distinct people -- so for group photos
+**IP-Adapter FaceID + masks beats InstantID**.)
+
+**3. IP-Adapter + ControlNet + img2img compose (confidence: high).** The doc shows IP-Adapter +
+ControlNet (depth) in one pipeline and IP-Adapter + img2img (`strength`). Our target stack is the
+union: `StableDiffusionXLControlNetImg2ImgPipeline` (canny = structure) + `load_ip_adapter` (FaceID =
+identity) + `strength` (removal). `set_ip_adapter_scale` (1.0 = image-only, 0.5 = balanced) is the
+identity-hold knob. API friction to verify in implementation: that `ip_adapter_masks` via
+`cross_attention_kwargs` works on the *ControlNet img2img* pipeline (the masking is an attention-
+processor feature, so it should be pipeline-agnostic, but confirm).
+
+**4. InstantID / PuLID positioning (confidence: medium).** InstantID does not train the UNet so it
+composes with canny/depth ControlNets, and gives better single-face fidelity than FaceID -- but it is
+single-subject (needs its own landmark ControlNet + dedicated weights). PuLID has the best identity
+fidelity but is heaviest and Flux-leaning. For our multi-face, constraint-bound, SDXL-canny case,
+IP-Adapter FaceID + masks is the right first build; InstantID/PuLID are single-portrait upgrades.
+
+### Architecture (proposed)
+
+```
+detect faces (insightface) -> per face: ArcFace embed + region mask
+one img2img pass:
+  image=init, control_image=canny(init),                      # structure (existing)
+  ip_adapter_image_embeds=[face_embeds],                       # identity per face
+  cross_attention_kwargs={"ip_adapter_masks": face_masks},     # each face -> its region
+  controlnet_conditioning_scale=1.0, set_ip_adapter_scale(~0.6),
+  strength=vendor-adaptive                                     # removal (unchanged)
+```
+Pixels are regenerated (SynthID removed by `strength`), structure held by canny, each face's identity
+held by its masked ArcFace vector -- no original pixel copied.
+
+### Risks / honest costs
+
+- **Shielding risk (same wall):** FaceID conditioning, like canny, reduces effective regeneration ->
+  higher `set_ip_adapter_scale` raises the chance SynthID survives in the face region (echo of why the
+  old region-hires failed). MUST oracle-verify removal at the chosen FaceID scale; keep `strength` at
+  the vendor threshold.
+- **New heavy dependency:** `insightface` + `onnxruntime` + the `buffalo_l` model (~300 MB, downloaded
+  on first use). Detection + embedding is CPU/ONNX, separate from the diffusion.
+- **Detection floor:** insightface needs faces large enough (det_size ~640); tiny faces in a dense
+  group may not be detected -> not preserved (falls back to canny-only for those).
+- **Identity ceiling:** SDXL FaceID is ~5-10% off true identity -- a meaningful boost over canny-only
+  drift, NOT a perfect face swap. Set expectations; PuLID/InstantID are the higher-fidelity (heavier)
+  paths if needed.
+- **Value scales with strength:** at low strength (OpenAI 0.10) faces barely drift, so FaceID is
+  marginal; at the higher strength a hard vendor (Google 0.30) needs, FaceID earns its keep.
+
+### Build plan (staged)
+
+- v1: optional `--face-id` flag on `--pipeline controlnet`. Detect faces; if any, run the masked
+  FaceID pass (works for 1 or N faces -- masks generalize). If none detected, fall through to plain
+  canny. Oracle-verify SynthID removal is preserved at the default FaceID scale on a face image.
+- v2 (if identity still short): InstantID for single-portrait, or PuLID, as a higher-fidelity opt-in.
+
+**Sources.** https://huggingface.co/docs/diffusers/main/en/using-diffusers/ip_adapter ·
+https://huggingface.co/h94/IP-Adapter-FaceID · https://arxiv.org/pdf/2401.07519 (InstantID) ·
+https://instantid.github.io/ · https://arxiv.org/abs/2308.06721 (IP-Adapter)
+
+### FaceID prototype run 1 -- 2026-06-03 (NEGATIVE on dense small-face groups)
+
+Built and shipped the masked multi-face FaceID layer (`--face-id`, `face_id.py`, `faceid` extra).
+First real run on the gemini_3 group photo (Google, s015, scale 0.6, native 2816 via cap 1536):
+insightface detected **17 faces**, the masked multi-face pass composed and ran end-to-end (non-black
+output), so the API is correct. **At s015 the result is a clear FAILURE: every face corrupted --
+melted/discolored/psychedelic, materially WORSE than canny-only.**
+
+**ROOT CAUSE FOUND (confirmed by ablation, not speculation) -- it is STRENGTH, not scale/masks/faces.**
+Investigated the real data: masks are fine (max overlap depth 2, 33% coverage, only 0.2% of pixels
+double-covered -- NOT an overlap problem), embeddings are fine (`normed_embedding` norm 1.000), the
+FaceID LoRA is not required for SDXL (h94 model card), and faces span 34-181 px (7 medium + 10 tiny).
+None of those is the cause. The decisive test: the SAME image + FaceID at **strength 0.5** produces
+**clean, coherent faces across the whole group** (no psychedelic artifacts). So FaceID needs
+substantial regeneration: the h94 usage is full generation (txt2img, 30 steps); at our removal
+strength (0.10-0.15 = ~7 effective steps) the strong identity cross-attention cannot reconcile with
+a latent that is ~85% the untouched original, so it smears identity-colored noise onto the faces.
+
+**This is a FUNDAMENTAL tension, not a tuning bug:** watermark removal wants LOW strength (minimal
+degradation, just enough to scrub), FaceID wants HIGH strength (regenerate the face to impose
+identity). They are opposed. At strength 0.5 FaceID works AND removes the watermark, but the whole
+image regenerates much more (canny still holds text/edge structure, but texture/detail drifts well
+beyond the 0.15 "minimal degradation" target). So `--face-id` is a HIGH-STRENGTH option: it trades
+whole-image fidelity for face identity, and is a footgun at the low default strength (guaranteed
+garbage). Required follow-up code guard: when `--face-id` is set, floor `strength` at ~0.5 (or refuse
++ warn) -- never run FaceID at the vendor-adaptive removal strength. Open question: whether
+high-strength FaceID's whole-image drift is acceptable for face-centric images, or whether identity
+preservation at LOW strength needs a different mechanism entirely (FaceID structurally cannot do it). (Infra lesson: the `faceid` extra must
+stay numpy<2.0 -- pin `onnx<1.18` + `scipy<1.18`; pinning numpy UP, as the first build did, leaves a
+numpy-1.26 env with a numpy-2-only scipy that crashes the diffusers import via `np.long`.)
+
+## Face preservation, done properly (research 2026-06-03, after the FaceID failure)
+
+The FaceID run failed and I wrongly concluded "faces can't be preserved." Re-research corrected the
+understanding. The hard constraint is unchanged: to remove the watermark FROM a face the face MUST
+be regenerated (freezing it leaves SynthID), so the goal is identity-preserving REGENERATION of the
+face, at minimal overall image degradation. Three things I got wrong and the corrected picture:
+
+**What I got wrong:** (1) I applied FaceID at GLOBAL high strength -- the literature is clear the
+architecture must be REGION-ADAPTIVE (face region handled separately, background stays low-strength);
+(2) I used IP-Adapter FaceID, the WEAKEST identity tool -- InstantID uses an ArcFace encoder and hits
+82-86% face-recognition similarity vs FaceID's weak CLIP-ish signal; (3) I missed the entire
+face-restoration class (CodeFormer / GFPGAN), which is purpose-built for "regenerate a face, keep
+identity."
+
+**The most promising mechanism -- CodeFormer face-restoration post-pass (confidence: high on the
+mechanism, unverified on our watermark).** CodeFormer is a VQ-VAE: a frozen discrete CODEBOOK of HQ
+facial priors + a Transformer that predicts code *tokens* from the input, and a frozen decoder that
+regenerates the face FROM THE CODEBOOK ENTRIES -- "does not depend on feature fusion with low-quality
+cues." So the output face pixels come from a finite learned codebook, NOT from the input pixels:
+**the SynthID pixel-amplitude pattern physically cannot survive a codebook re-synthesis** -- a
+stronger scrub than low-strength img2img (which keeps ~85% of the latent). Fidelity knob `w` in
+[0,1]: higher w preserves identity but fuses MORE low-quality (input) cues (more watermark risk),
+lower w leans on the codebook (cleaner scrub, identity drift) -- the same scrub-vs-fidelity tension,
+settled per-image by the oracle; there is likely a `w` that holds identity AND clears the oracle.
+
+**Constraint-compatible architecture:** run the normal canny low-strength controlnet removal globally
+(minimal degradation everywhere), then detect+align each face, run CodeFormer on the **ORIGINAL** face
+crop (to capture true identity AND re-synthesize from the codebook = scrub), and composite the
+CodeFormer output (codebook-generated, not original pixels -> no copy, no watermark) into the cleaned
+image. Decouples whole-image minimal-degradation from face identity -- no high GLOBAL strength needed.
+
+**Honest costs/caveats:** (a) **License -- CodeFormer is NTU S-Lab 1.0 (non-commercial/research)**, so
+it cannot be bundled in this MIT tool for general use; the license-clean alternative is **GFPGAN
+(Apache-2.0)**, slightly lower quality. (b) Deps (basicsr/facexlib) are heavy and numpy-version-finicky
+(same class of conflict as insightface). (c) CodeFormer is a *restoration* model -- it can subtly
+alter expression/asymmetry; identity is held but not pixel-identical. (d) **The watermark-scrub is
+mechanistically strong but UNVERIFIED -- must oracle-check.** InstantID + region-adaptive strength is
+the alternative if the restoration route disappoints, but it is more complex (differential strength).
+Prototype plan: validate CodeFormer on a real face in a THROWAWAY env (identity held? oracle clean?)
+before any project-env integration or the license/GFPGAN decision.
+
+### CodeFormer prototype -- VALIDATED end-to-end 2026-06-03 (oracle-confirmed)
+
+Prototyped the CodeFormer face-restoration post-pass (codeformer-pip in a throwaway venv, forced CPU
+-- the pip wrapper has an MPS device-mismatch bug) on the gemini_3 group photo (18 faces). Pipeline:
+`all --pipeline controlnet --strength 0.15` (sparkle + SynthID removed from the whole image, minimal
+degradation) -> CodeFormer on the ORIGINAL faces -> feather-composite the CodeFormer faces into the
+all-cleaned image. Oracle results (Gemini app "Verify with SynthID"), isolating each part:
+- pure controlnet-0.15 background (no faces): **clean** -> the background scrub works at 0.15 (no
+  ControlNet-shielding problem for Google on this image).
+- composite with CodeFormer faces at **w0.7**: **SynthID DETECTED** -> high fidelity fuses too much of
+  the original face signal (the watermark) through.
+- composite at **w0.5**: **clean**. composite at **w0.3**: **clean**.
+So the scrub-vs-fidelity threshold is between 0.5 and 0.7; **w=0.5 is the sweet spot** (highest
+fidelity / best identity that still clears the oracle). Identity at w0.3-0.7 all looks like the same
+person (the face is large enough), so the lower w costs little.
+
+**This VALIDATES the corrected face-preservation approach** (and refutes my earlier "faces can't be
+preserved" / FaceID conclusion): controlnet low-strength background scrub + CodeFormer-codebook face
+re-synthesis at w~0.5 + feather composite = oracle-clean SynthID removal everywhere (background AND
+faces), identity preserved, minimal overall degradation, zero original-pixel copying (CodeFormer faces
+are codebook-generated). CodeFormer's discrete-codebook re-synthesis DOES scrub the pixel watermark,
+but only when w is low enough that the decoder leans on the codebook rather than fusing the input
+(watermark-carrying) features -- exactly the predicted fidelity-vs-scrub tension, with an empirical
+clean threshold at w<=0.5.
+
+**Production TODO (not built -- still a throwaway prototype):** (1) license -- CodeFormer is NTU S-Lab
+(non-commercial); decide CodeFormer-as-user-installed-extra vs GFPGAN (Apache-2.0, re-verify it scrubs
+at its fidelity setting); (2) wire a `--restore-faces` post-pass (detect -> restore w~0.5 -> feather
+composite) onto the controlnet pipeline; (3) handle the MPS device bug (force CPU for the face model
+or fix); (4) re-verify the w threshold on more images / vendors (w=0.5 confirmed on one Gemini group
+photo only).
+
+**Sources.** https://arxiv.org/abs/2206.11253 (CodeFormer) · https://github.com/sczhou/CodeFormer ·
+https://arxiv.org/pdf/2401.07519 (InstantID) ·
+https://openaccess.thecvf.com/content/WACV2024/papers/Suin_Diffuse_and_Restore... (region-adaptive) ·
+https://arxiv.org/pdf/2504.12809 (saliency-aware watermark removal)
+
+## Provenance
+
+Hand-run primary-source pass, 2026-06-02. Sources fetched and quoted above; the central
+make-or-break claim (structure-conditioned high-strength regeneration scrubs the watermark while
+keeping text) is **unverified and explicitly flagged as the thing the local prototype must
+measure** (against the manual Gemini SynthID oracle) — the literature supports removal (Findings 1, 2) and supports structure-preserving
+regeneration (Finding 5) but never jointly validated text (Finding 3). No code change implied
+until the prototype validates a Pareto cell on the SynthID oracle.

docs/development.md

@@ -0,0 +1,35 @@
+# Development
+
+Read this reference for environment setup, dependency recovery, CI behavior, and fixture policy. The always-loaded invariants remain in [`.claude/rules/development.md`](../.claude/rules/development.md).
+
+## Local environment
+
+- Use `uv sync --frozen --extra dev` and add only the feature extras needed for the task.
+- Do not use `uv pip install` for development tools. It can re-resolve `uv.lock` outside the compatible ML dependency set.
+- A default-only sync removes every pixel and model package by design. Package imports remain light through lazy exports.
+- On an unreliable connection, sync `dev` plus only the required feature extras, such as `diffusion`, and run the checks directly instead of downloading every optional learned backend.
+- Run `uv` from the repository root or it may create a bare environment without the project dependencies.
+
+The optional TrustMark decoder downloads weights into its installed package directory. After pruning that extra, a leftover weights directory can make availability checks see an empty namespace package. If Pyright reports an unknown `TrustMark` import and `find_spec("trustmark")` returns a loader-less spec, remove that regenerable remnant from the active virtual environment and resync.
+
+## CI
+
+`.github/workflows/test.yml` runs Ruff and a cross-platform supported-Python test matrix with default plus development dependencies. Diffusion and model-running tests skip in that matrix; metadata, identification, visible removal, the DWT-DCT decoder, and the OpenCV eraser remain covered across operating systems.
+
+Keep `uv.lock` compatible with `uv sync --frozen`. Dependency pull-request checks use GitHub's merge result against current `main`; if `main` moves, merge it locally and rerun the full gate because a newer linter can expose stale directives in later code.
+
+Release and distribution behavior is canonical in [`release-and-distribution.md`](release-and-distribution.md).
+
+## Fixture and data policy
+
+[`../data/README.md`](../data/README.md) is the source of truth:
+
+- executable provenance fixtures live under `data/fixtures/`;
+- minimal controlled detector inputs live under `data/calibration/`;
+- canonical provider-oracle originals and their manifests live under `data/synthid/`;
+- evaluation-only ground truth lives under `data/evaluations/`;
+- runtime detector assets live in the package; unregistered research candidates remain outside the shipped wheel.
+
+Store each binary once. Point tests and manifests at its canonical path. Keep generated and cleaned outputs outside the repository and retain only reproducible public records allowed by the data policy.
+
+Use synthetic byte blobs for unsupported format paths and deterministic generated negatives where a real negative fixture is unnecessary. Detection and removal tests must preserve their format-specific invariants.

docs/index.md

@@ -0,0 +1,38 @@
+# Documentation
+
+This documentation is split by purpose. Start with the user guides if you want
+to run the tool. Use the maintainer references only when changing the code.
+
+## User guides
+
+| Page | Use it when |
+| --- | --- |
+| [Installation](installation.md) | You need the CLI, an optional model backend, or a development environment. |
+| [CLI guide](cli.md) | You want a command for one image, a directory, or a specific watermark type. |
+| [Python API](python-api.md) | You want to call the package from Python. |
+| [Supported signals](supported-signals.md) | You need to know which visible marks, metadata formats, and invisible signals are covered. |
+| [Known limitations](known-limitations.md) | You need the quality, device, format, or verification boundaries. |
+| [Scope, safety, and legal notes](legal-and-safety.md) | You need the intended use and legal context. |
+
+## Maintainer references
+
+| Page | Purpose |
+| --- | --- |
+| [Module internals](module-internals.md) | Current architecture, invariants, and regression guards by module. |
+| [Verification plan](verification-plan.md) | Verification methods, completed measurements, and remaining validation gaps. |
+| [Release and distribution](release-and-distribution.md) | PyPI, Homebrew, Hugging Face Space, and release workflow. |
+| [Watermarking landscape](watermarking-landscape.md) | Vendor signals and detection approaches. |
+| [SynthID technical reference](synthid.md) | Mechanism, detector access, robustness, and implications for this project. |
+
+## Research archive
+
+These pages record experiments and the evidence behind past decisions. They are
+not command references and may describe prototypes that were later removed.
+The current behavior is defined by the code, tests, README, and user guides.
+
+- [ControlNet removal research](controlnet-removal-pipeline-research.md)
+- [Qwen improvement research](qwen-improvement-research.md)
+- [Doubao reverse-alpha research](research-doubao-distillation.md)
+- [SynthID identity research](synthid-robust-identity-research.md)
+- [SynthID identity follow-up](synthid-robust-identity-research-2026-06-08.md)
+- [Text protection research](text-protection-research.md)

docs/installation.md

@@ -0,0 +1,198 @@
+# Installation
+
+Python 3.10.1 or newer is required.
+
+## Default metadata mode
+
+The default package provides:
+
+- provenance inspection;
+- AI metadata inspection and removal.
+
+It installs Pillow, piexif, and c2pa-python for reading metadata directly from
+files. It does not install NumPy, OpenCV, pillow-heif, Torch, diffusion models,
+or invisible-watermark decoders.
+
+Install it as an isolated command with uv:
+
+```bash
+uv tool install remove-ai-watermarks
+```
+
+Or with pipx:
+
+```bash
+pipx install remove-ai-watermarks
+```
+
+You can also install the Homebrew package on macOS or Linux:
+
+```bash
+brew install wiltodelta/tap/remove-ai-watermarks
+```
+
+## Visible watermark removal
+
+Visible mark detection, OpenCV inpainting, and manual region erasing need the
+`visible` extra:
+
+```bash
+uv tool install --force "remove-ai-watermarks[visible]"
+```
+
+Add `heif` only when the pixel path must decode HEIC, HEIF, or AVIF:
+
+```bash
+uv tool install --force "remove-ai-watermarks[visible,heif]"
+```
+
+## Invisible watermark removal
+
+Diffusion based removal needs the `diffusion` extra:
+
+```bash
+uv tool install --force "remove-ai-watermarks[diffusion]"
+```
+
+The code supports CUDA, XPU, MPS, and CPU devices. A GPU is recommended because
+CPU inference is slow.
+
+For the CUDA only Qwen Image plus Z-Image profile:
+
+```bash
+uv tool install --force "remove-ai-watermarks[qwen-zimage]"
+```
+
+The `qwen-zimage` extra includes the normal `diffusion` dependencies.
+
+## Feature extras
+
+Extras are composable. Install only the capabilities and file formats the
+application actually uses:
+
+| Extra | Capability | Automatically includes | Torch or model download |
+| --- | --- | --- | --- |
+| `pixels` | Shared BGR array and image-processing runtime | NumPy, headless OpenCV | No |
+| `heif` | HEIC, HEIF, and AVIF pixel decoding | pillow-heif | No |
+| `visible` | Visible mark detection, OpenCV inpainting, and manual erasing | `pixels` | No |
+| `detect` | Open DWT-DCT detection for Stable Diffusion, SDXL, and FLUX | `pixels`, PyWavelets | No |
+| `trustmark` | Adobe TrustMark detection | trustmark | Yes |
+| `diffusion` | Diffusion-based invisible watermark removal | `pixels`, Torch, Diffusers | Yes |
+| `migan` | MI-GAN ONNX fill backend | `visible`, ONNX Runtime | Model download, no Torch |
+| `lama` | big-LaMa ONNX fill backend | `visible`, ONNX Runtime | Model download, no Torch |
+| `esrgan` | Real-ESRGAN upscaling before diffusion | `pixels`, spandrel | Yes |
+| `qwen-zimage` | CUDA-only Qwen Image plus Z-Image pipeline | `diffusion`, DiffSynth | Yes |
+| `all` | Every production feature | All rows above | Yes |
+| `dev` | Tests, linting, typing, and upstream parity checks | `visible`, `detect`, upstream invisible-watermark | Yes, for parity tests |
+
+Dependency composition:
+
+```mermaid
+flowchart LR
+    visible --> pixels
+    detect --> pixels
+    diffusion --> pixels
+    migan --> visible
+    lama --> visible
+    esrgan --> pixels
+    qwen["qwen-zimage"] --> diffusion
+    heif
+    trustmark
+```
+
+`heif` and `trustmark` are independent branches. Combine them explicitly with
+another feature when required. The `all` bundle contains every production
+branch but never includes `dev`.
+
+Examples:
+
+```bash
+# Metadata plus torch-free DWT-DCT detection
+uv tool install --force "remove-ai-watermarks[detect]"
+
+# Visible removal with HEIC/AVIF support and MI-GAN
+uv tool install --force "remove-ai-watermarks[migan,heif]"
+
+# DWT-DCT and TrustMark detection without diffusion removal
+uv tool install --force "remove-ai-watermarks[detect,trustmark]"
+
+# Every production capability
+uv tool install --force "remove-ai-watermarks[all]"
+
+# An arbitrary minimal combination
+uv tool install --force "remove-ai-watermarks[migan,detect]"
+```
+
+`heif` stays independent so applications that only process PNG, JPEG, or WebP
+do not install libheif. `detect` uses the in-tree torch-free decoder and does
+not install the upstream `invisible-watermark` package. Optional models download
+their weights on first use.
+
+The old `gpu` and `remove` aliases are intentionally not provided. Use
+`diffusion` and `visible` respectively.
+
+## Install from the repository
+
+```bash
+git clone https://github.com/wiltodelta/remove-ai-watermarks.git
+cd remove-ai-watermarks
+uv sync --frozen
+```
+
+Add the feature groups required for your work:
+
+```bash
+uv sync --frozen --extra dev
+uv sync --frozen --extra dev --extra diffusion
+```
+
+Run commands from the repository root:
+
+```bash
+uv run remove-ai-watermarks --help
+```
+
+## Development setup
+
+Install development dependencies:
+
+```bash
+uv sync --frozen --extra dev
+```
+
+Run the complete project gate:
+
+```bash
+bash maintain.sh
+```
+
+The script runs dependency checks, linting, formatting checks, type checking,
+and the test suite.
+
+## Hugging Face authentication
+
+Pass a Hugging Face token directly when the selected model or account requires
+one:
+
+```bash
+remove-ai-watermarks invisible image.png --hf-token "$HF_TOKEN"
+```
+
+The CLI also loads `HF_TOKEN` from the environment and from a local `.env`
+file. The same name is documented in `.env.example`.
+
+## Troubleshooting
+
+### The first model run is slow
+
+Diffusion and learned fill backends may download model weights on first use.
+Later runs reuse their caches.
+
+### The command skips invisible removal
+
+The normal behavior is to skip diffusion when no supported local signal is
+found. A missing signal does not prove that the image is clean. If you know the
+image came from a relevant generator, use `--force`.
+
+If the CLI reports that diffusion dependencies are unavailable, install the
+`gpu` extra.

docs/known-limitations.md

@@ -0,0 +1,219 @@
+# Known limitations
+
+This page describes current product limits. Historical measurements and
+superseded experiments live in the research archive listed in
+[the documentation index](index.md).
+
+## Visible removal
+
+### Fill quality depends on the background
+
+Visible removal changes only the selected mask, but the hidden pixels still
+have to be reconstructed.
+
+- OpenCV is fast and requires no model download. It works well on flat
+  backgrounds but
+  can smear texture or repeated structure.
+- MI-GAN is a lighter learned backend. It can improve natural texture but may
+  ghost or invent structure.
+- LaMa is the heaviest learned backend and is generally the strongest option
+  for difficult backgrounds.
+
+`--backend auto` selects LaMa when available, then MI-GAN, then OpenCV.
+
+No backend can recover detail that is completely hidden by an opaque mark. A
+successful detection therefore does not guarantee a visually perfect fill.
+
+### Automatic detection covers registered variants only
+
+The registry contains vendor and locale specific templates. A redesigned mark,
+an unsupported locale, a different position, or a crop may be missed.
+
+Known examples:
+
+- Samsung detection is calibrated for the Italian
+  `Contenuti generati dall'AI` text variant.
+- The Jimeng top-left pill has a weak visual detector and is intentionally
+  subject to additional product and background checks.
+- Kling support covers the calibrated variants rather than every Kling label.
+
+Use `erase --region` when you can see and select an unsupported or missed mark.
+
+### Strict and automatic sensitivity trade recall for precision
+
+`--sensitivity strict` uses the visual gate alone. The default `auto` mode may
+relax a mark only when metadata or a confidently detected sibling mark
+corroborates the same product.
+
+There is no blanket "this image is AI" relaxation. That information does not
+identify the vendor, mark, or location and caused unacceptable false
+detections in the removed experimental mode.
+
+## Invisible removal
+
+### Regeneration is lossy
+
+Invisible removal does not decode and delete a payload. It regenerates the
+image through a diffusion pipeline. Faces, text, colors, and fine detail can
+change even when the watermark is successfully disrupted.
+
+ControlNet is the default compatibility profile. It conditions on edges to
+preserve structure, but edges do not preserve identity or exact texture.
+
+The CUDA only `qwen-zimage` profile adds a separate face stage and is the
+highest fidelity option in the current implementation. It is larger, slower,
+and still may alter small text or difficult faces.
+
+### Removal cannot be verified locally for proprietary SynthID
+
+The project has no public local SynthID pixel decoder. It can infer likely
+presence from supported provenance metadata, but a missing metadata proxy is
+not a negative pixel verdict.
+
+For important outputs:
+
+1. preserve the original;
+2. process a copy;
+3. verify with the matching provider tool when available;
+4. do not assume one provider's verifier covers another provider's payload.
+
+Provider systems can change, so a result verified on one file, seed, or version
+is not a permanent certification.
+
+### Strength is content and seed dependent
+
+For SDXL and ControlNet, the CLI resolves an unset strength from the detected
+vendor:
+
+- OpenAI: `0.10`;
+- Google: `0.15`;
+- unknown: `0.15`.
+
+An explicit `--strength` overrides these defaults. The defaults are operating
+points, not universal guarantees. Near a removal threshold, different content
+or a different random seed may change the verifier result.
+
+The base Qwen and `qwen-zimage` profiles have profile specific strength
+behavior. Consult `remove-ai-watermarks invisible --help` and the source of
+[`watermark_profiles.py`](../src/remove_ai_watermarks/noai/watermark_profiles.py)
+for the current resolver.
+
+### Pipelines have different quality tradeoffs
+
+| Pipeline | Main limit |
+| --- | --- |
+| `controlnet` | Edge conditioning can preserve a watermark carrying region too closely, and faces may drift. |
+| `sdxl` | Flat graphics and precise structure may receive too little or unhelpful change. |
+| `qwen` | Large CUDA oriented model; face smoothing can still be significant. |
+| `qwen-zimage` | CUDA only, large model stack, and limited broad certification across seeds and content. |
+
+The legacy `default` profile name maps to `sdxl`. The `--auto` flag is
+deprecated, emits a warning, and changes nothing.
+
+## Resolution and memory
+
+### Small images are enlarged before SDXL based diffusion
+
+The SDXL, ControlNet, and base Qwen paths use a default minimum long side of
+`1024`. Smaller inputs are enlarged before diffusion and restored to their
+original dimensions afterward. Set `--min-resolution 0` to disable the floor.
+
+`qwen-zimage` does not apply this SDXL minimum resolution floor.
+
+### Large images stay at native resolution unless capped
+
+`--max-resolution 0` means no explicit downscale cap. A positive value caps the
+long side before diffusion and restores the result afterward. This reduces
+memory use but introduces a downscale and upscale round trip.
+
+`--tile` preserves the input dimensions while running the diffusion stage in
+overlapping tiles. It avoids the explicit downscale, but it is not pixel
+lossless: each tile is independently regenerated. With `qwen-zimage`, only the
+global Qwen stage is tiled; the face stage runs after tile blending.
+
+### CPU offload is CUDA only
+
+`--cpu-offload` moves Diffusers model components between CPU and CUDA instead of
+keeping the complete standard pipeline in GPU memory. For `qwen-zimage`, it
+forces the face stack to use its offload path.
+
+The option reduces CUDA memory pressure at the cost of speed. It has no effect
+on CPU or MPS and fails loudly when a CUDA Diffusers pipeline does not expose
+the required offload method.
+
+### MPS may fall back to CPU
+
+The SDXL paths include an MPS out-of-memory fallback that reloads on CPU. A run
+that appears much slower after an MPS failure may be continuing on CPU.
+
+Memory needs depend on the pipeline, input size, dtype, and machine. Use tiling,
+a resolution cap, or a lighter pipeline when necessary.
+
+## Metadata and formats
+
+### Missing metadata does not mean clean
+
+Screenshots, social platforms, and re-encoding can remove metadata while a
+pixel watermark remains. `identify` therefore reports unknown rather than
+clean when no supported signal is found.
+
+### JPEG XL is metadata only
+
+The metadata path recognizes JPEG XL containers, but the visible and diffusion
+image paths do not list `.jxl` as a supported pixel format because the package
+does not include a JPEG XL pixel decoder.
+
+### HEIC, HEIF, and AVIF pixel decoding uses an optional Pillow fallback
+
+OpenCV does not decode these formats in the project. `image_io.imread` falls
+back to Pillow with `pillow-heif` when the `heif` extra is installed alongside
+a pixel feature. The
+default metadata path scans these containers without that plugin. A corrupt or
+truncated file may still fail to decode.
+
+### Some metadata removal requires ffmpeg
+
+WebM, Matroska, MP3, WAV, FLAC, OGG, Opus, and AAC container metadata is stripped
+through ffmpeg with stream copying. The operation fails if ffmpeg is absent or
+cannot parse the input.
+
+### Metadata transformation is fail safe
+
+`remove_ai_metadata` may copy an undecodable file through unchanged instead of
+raising. User facing callers must use `strip_and_verify` and inspect its
+surviving marker mapping before reporting success. `strip_and_verify` recovers
+when `image_io` can still decode the raster by normalizing the container and
+checking again. A truly undecodable file still reports the surviving markers.
+The CLI uses this verified path.
+
+### Sixteen bit PNG output is not preserved
+
+The Pillow based PNG metadata rewrite uses the normal image save path and may
+reduce a sixteen bit PNG to eight bits. A byte-level PNG metadata stripper
+would be required to preserve that bit depth.
+
+## Detection extras
+
+The `detect` extra decodes an open DWT-DCT watermark used in some Stable
+Diffusion, SDXL, and FLUX workflows. That decoder is sensitive to the carrier
+and transformations. A negative result is not a universal negative.
+
+The `trustmark` extra adds Adobe TrustMark decoding. The implementation retains
+an additional JPEG re-encode gate because isolated decoder hits can otherwise
+be content noise.
+
+External AI versus real image classifiers are out of scope. The project
+identifies concrete local provenance signals instead of shipping a generic
+statistical classifier.
+
+## Output and traceability
+
+Removing file-local signals does not remove:
+
+- provider account history;
+- server side copies or provenance stores;
+- perceptual fingerprints;
+- evidence that an image passed through a removal pipeline;
+- legal disclosure duties.
+
+See [scope, safety, and legal notes](legal-and-safety.md).

docs/legal-and-safety.md

@@ -0,0 +1,88 @@
+# Scope, safety, and legal notes
+
+This page explains the project's intended boundary. It is not legal advice.
+Laws and platform rules change, so check the current rules that apply to your
+location and use case.
+
+## Intended scope
+
+The project removes AI provenance marks that a platform adds to content the
+user generated or edited themselves. Examples include:
+
+- visible AI generation labels;
+- invisible provenance watermarks;
+- C2PA and metadata based AI disclosures.
+
+The purpose is user control over the user's own output, false positive cleanup,
+interoperability work, and watermark robustness research.
+
+## Out of scope
+
+The project does not provide automatic removal for marks that protect a third
+party's paid or copyrighted asset, including:
+
+- stock agency previews;
+- marketplace and classifieds marks;
+- tiled overlays used to gate a purchase;
+- artist protection systems such as Nightshade or Glaze.
+
+The `erase` command is a generic region tool. Users are responsible for having
+the right to edit the selected content.
+
+## What removal does not prove
+
+Removing a local signal does not:
+
+- prove that an image is human made;
+- remove server side generation history;
+- anonymize the generating account;
+- defeat every statistical AI detector;
+- guarantee that a provider's current verifier will reject the result;
+- make deceptive or unlawful use permissible.
+
+An original file may remain linked to an account or generation session in a
+provider's systems even after a local copy is changed.
+
+## Legal context
+
+Some jurisdictions and platforms require AI generated content to carry visible
+or machine readable disclosures. Rules may apply to providers, publishers,
+users, or a combination of them. Some laws also restrict removing or
+suppressing provenance information.
+
+Before removing a mark, consider:
+
+1. whether you own or are authorized to edit the content;
+2. whether a disclosure is legally required where the content will be used;
+3. whether removal would mislead a viewer about authorship or origin;
+4. whether copyright management information is involved;
+5. whether a platform's terms prohibit the change.
+
+The repository does not provide jurisdiction specific legal advice. The user is
+responsible for checking current law and policy.
+
+## Appropriate uses
+
+Examples that fit the project scope include:
+
+- removing metadata that exposes an account identifier from your own file;
+- correcting an AI label applied to a human photograph after a limited edit;
+- publishing your own generated artwork under the disclosure rules that apply
+  to you;
+- testing the robustness of watermarking and provenance systems;
+- evaluating image processing pipelines in a controlled environment.
+
+## Uses the project does not condone
+
+- fraud or impersonation;
+- nonconsensual sexual imagery;
+- hiding copyright infringement;
+- presenting generated content as human made where that claim is deceptive;
+- evading a disclosure that the law requires;
+- removing protection from someone else's paid asset.
+
+## Reporting security or safety concerns
+
+Open a GitHub issue when the concern can be discussed publicly without exposing
+private data. Do not attach confidential images, credentials, or personal
+information to a public issue.

docs/module-internals.md

@@ -0,0 +1,421 @@
+# Module internals
+
+This page documents the current implementation contract. It intentionally
+avoids experiment logs, corpus counts, and calibration history. Those records
+live in [the verification plan](verification-plan.md) and the research archive
+listed in [the documentation index](index.md).
+
+Read the relevant section before changing a subsystem. When this page and the
+code disagree, the code and its tests are authoritative and this page must be
+updated in the same change.
+
+## Architecture
+
+The package has four main paths:
+
+```mermaid
+flowchart LR
+    Input[Input file] --> Identify[Identify provenance]
+    Input --> Visible[Visible mark removal]
+    Input --> Invisible[Diffusion regeneration]
+    Input --> Metadata[Metadata stripping]
+
+    Identify --> Report[ProvenanceReport]
+    Visible --> VisibleOutput[Localized and filled image]
+    Invisible --> InvisibleOutput[Regenerated image]
+    Metadata --> MetadataOutput[Container with AI metadata removed]
+```
+
+The `all` command runs visible removal, optional invisible regeneration, and
+metadata stripping in that order.
+
+## Command line interface
+
+[`cli.py`](../src/remove_ai_watermarks/cli.py) owns command parsing and
+user-facing exit behavior.
+
+Important contracts:
+
+- Single-image arguments reject directories.
+- `visible` writes no output when no registered mark is selected and exits with
+  `EXIT_NO_VISIBLE_MARK`.
+- `invisible` writes no output when no supported local signal is found, unless
+  `--force` is supplied.
+- The two no-signal conditions currently share exit code `2`.
+- Hard processing and write failures exit with code `1`.
+- `all` can still write the completed visible and metadata stages when the
+  diffusion dependencies are unavailable, but exits with code `1` so the
+  partial result is not reported as complete.
+- `batch` counts per-file failures and exits nonzero if any file failed or an
+  applicable invisible stage was skipped because its dependencies were absent.
+
+The decorators for diffusion options are shared by `invisible`, `all`, and
+`batch`. The runtime help generated by Click is the source of truth for option
+names and defaults.
+
+The deprecated `--auto` option does not select a pipeline or change adaptive
+polishing. [`_resolve_auto_polish`](../src/remove_ai_watermarks/cli.py) emits a
+warning and returns the explicit polish value unchanged.
+
+Regression coverage:
+
+- [`test_cli.py`](../tests/test_cli.py)
+- [`test_cli_robustness.py`](../tests/test_cli_robustness.py)
+- [`test_optional_deps.py`](../tests/test_optional_deps.py)
+
+## High-level Python API
+
+[`api.py`](../src/remove_ai_watermarks/api.py) provides:
+
+- `remove_visible`
+- `visible_provenance`
+
+The package root exposes both lazily through
+[`__getattr__`](../src/remove_ai_watermarks/__init__.py), keeping a plain package
+import free of the heavier image and model imports.
+
+For path inputs, `remove_visible` reads provenance metadata, preserves alpha,
+and optionally writes and strips metadata. Array inputs are treated as BGR
+arrays and have no file provenance or separate alpha plane.
+
+When no visible mark is removed, a same-format path copy preserves the original
+bytes. `write_noop=False` leaves the requested output path untouched instead.
+
+Regression coverage:
+
+- [`test_api.py`](../tests/test_api.py)
+- [`test_image_io.py`](../tests/test_image_io.py)
+
+## Metadata and provenance
+
+### C2PA
+
+[`noai/c2pa.py`](../src/remove_ai_watermarks/noai/c2pa.py) reads C2PA with the
+official `c2pa-python` reader first. Its byte-level PNG parser remains a fallback
+for partial and synthetic fixtures that the official reader rejects.
+
+Vendor attribution comes from the registry in
+[`noai/constants.py`](../src/remove_ai_watermarks/noai/constants.py). Derived
+issuer and platform maps should not be maintained separately.
+
+### Metadata scanning and stripping
+
+[`metadata.py`](../src/remove_ai_watermarks/metadata.py) contains the shared
+metadata scanners and `remove_ai_metadata`.
+
+Key contracts:
+
+- `scan_head` is the shared cached input for bounded byte scans.
+- JPEG stripping walks metadata segments and preserves the entropy-coded image
+  scan.
+- ISOBMFF containers use
+  [`noai/isobmff.py`](../src/remove_ai_watermarks/noai/isobmff.py).
+- Supported non-ISOBMFF audio and video containers use ffmpeg stream copying.
+- The low-level remover is fail-safe and can copy an undecodable file through
+  unchanged.
+- A caller that reports success must use `strip_and_verify`, which scans the
+  written output for surviving markers. If the metadata-preserving decoder
+  rejected the container but `image_io` can still decode its raster,
+  `strip_and_verify` normalizes that raster and scans again. A truly undecodable
+  file keeps the surviving-marker result.
+
+Detection and removal must stay in parity. A new marker is incomplete until the
+scanner can find it, the remover can reach every supported placement, and a
+test proves that it no longer appears in the output.
+
+Regression coverage:
+
+- [`test_metadata.py`](../tests/test_metadata.py)
+- [`test_noai.py`](../tests/test_noai.py)
+- [`test_security_clamp.py`](../tests/test_security_clamp.py)
+
+### Provenance report
+
+[`identify.py`](../src/remove_ai_watermarks/identify.py) separates file-backed
+metadata extraction from verdict logic:
+
+- `extract_provenance_evidence` reads the supported metadata signals into
+  `ProvenanceEvidence`.
+- `evidence_from_metadata_record` normalizes an externally collected nested
+  metadata record into the same evidence type without file access. Diagnostic
+  values under `error` and `kind` are excluded from evidence while nested raw
+  bytes remain available through encoded binary fields.
+- `identify_from_evidence` evaluates that evidence without reopening the source.
+- `identify` preserves the path-based API and adds the optional registered
+  visible-mark and open invisible-watermark decoders after extraction.
+
+The `detect` extra composes the shared `pixels` runtime with PyWavelets. Its
+in-tree [`dwt_dct.py`](../src/remove_ai_watermarks/dwt_dct.py) decoder preserves
+the upstream matrix algorithm without installing Torch or non-headless OpenCV.
+The upstream MIT notice ships inside the wheel under `licenses/`.
+
+`is_ai_generated` is `True` or `None`; absence of evidence is not reported as a
+human-made verdict. `ai_source_kind` distinguishes fully generated content from
+AI-enhanced composites when the source metadata provides that distinction.
+
+TrustMark is reported as a watermark signal but does not by itself assert AI
+origin because it can also protect human-authored content.
+
+Regression coverage:
+
+- [`test_identify.py`](../tests/test_identify.py)
+- [`test_trustmark_detector.py`](../tests/test_trustmark_detector.py)
+- [`test_invisible_watermark.py`](../tests/test_invisible_watermark.py)
+
+## Visible mark removal
+
+### Registry and decision flow
+
+[`watermark_registry.py`](../src/remove_ai_watermarks/watermark_registry.py) is
+the only visible-mark registry. `mark_keys()` supplies the CLI choices, so the
+CLI must not maintain a separate mark list.
+
+Automatic removal has three distinct stages:
+
+1. Perception: each registered detector produces strict and relaxed candidates.
+2. Decision: the pure `decide` arbiter applies sensitivity and corroborating
+   provenance.
+3. Action: each selected mark is localized to a mask and passed to the shared
+   fill function.
+
+`sensitivity="strict"` never relaxes a detector. `sensitivity="auto"` can relax
+one only when metadata or a sufficiently strong same-product sibling confirms
+that product. The removed blanket `assume_ai` mode is rejected explicitly.
+
+The Jimeng pill has an additional decision gate because its visual detector is
+weaker than the other registered marks. Keep that policy in the registry, not
+inside unrelated detector engines.
+
+`remove_auto_marks` removes every selected mark, not only the strongest one.
+This matters for images that carry marks in more than one corner.
+
+Regression coverage:
+
+- [`test_watermark_registry.py`](../tests/test_watermark_registry.py)
+- [`test_api.py`](../tests/test_api.py)
+
+### Gemini sparkle
+
+[`gemini_engine.py`](../src/remove_ai_watermarks/gemini_engine.py) uses a
+multi-scale shape search and a false-positive gate. Its captured sparkle assets
+serve detection and mask geometry only. Pixel recovery is performed by the
+shared fill backend.
+
+`detect_sparkle_confidence` uses a process-wide shared engine because its loaded
+assets and template ladder are immutable.
+
+Regression coverage:
+
+- [`test_gemini_engine.py`](../tests/test_gemini_engine.py)
+
+### Text mark engines
+
+[`_text_mark_engine.py`](../src/remove_ai_watermarks/_text_mark_engine.py)
+provides common localization, detection front ends, template caching, rival
+comparison, and footprint construction.
+
+Each vendor module supplies a `TextMarkConfig` and only the behavior that cannot
+be represented by the shared base:
+
+- [`doubao_engine.py`](../src/remove_ai_watermarks/doubao_engine.py)
+- [`jimeng_engine.py`](../src/remove_ai_watermarks/jimeng_engine.py)
+- [`qwen_engine.py`](../src/remove_ai_watermarks/qwen_engine.py)
+- [`kling_engine.py`](../src/remove_ai_watermarks/kling_engine.py)
+- [`yuanbao_engine.py`](../src/remove_ai_watermarks/yuanbao_engine.py)
+- [`samsung_engine.py`](../src/remove_ai_watermarks/samsung_engine.py)
+- [`runninghub_engine.py`](../src/remove_ai_watermarks/runninghub_engine.py)
+- [`baidu_engine.py`](../src/remove_ai_watermarks/baidu_engine.py)
+- [`liblib_engine.py`](../src/remove_ai_watermarks/liblib_engine.py)
+
+The detector and removal mask must use compatible geometry. A detector that
+fires while producing an empty or misplaced mask is a removal failure even if
+the detection test passes.
+
+Yuanbao uses the polarity-independent `contrast` front end because its standard
+two-line mark can be light on dark scenes or dark on light scenes. Its detector
+and footprint both use the same best-match box. The separate one-line overlay
+variant is not covered.
+
+The capture-less Jimeng pill lives in
+[`pill_engine.py`](../src/remove_ai_watermarks/pill_engine.py). It uses a
+synthetic silhouette for detection and a fixed top-left footprint.
+
+Each engine has a corresponding test module under [`tests/`](../tests/).
+Shared behavior is covered by:
+
+- [`test_text_mark_engine.py`](../tests/test_text_mark_engine.py)
+- [`test_text_mark_faint_mask.py`](../tests/test_text_mark_faint_mask.py)
+- [`test_text_mark_memory.py`](../tests/test_text_mark_memory.py)
+
+### Fill backends and region erasing
+
+[`region_eraser.py`](../src/remove_ai_watermarks/region_eraser.py) implements the
+same backends used by visible removal and the user-directed `erase` command:
+
+- `cv2`
+- `migan`
+- `lama`
+
+`watermark_registry.resolve_backend` selects LaMa first, then MI-GAN, then
+OpenCV for `auto`. A memory-constrained caller should explicitly select MI-GAN
+or OpenCV instead of relying on `auto`.
+
+MI-GAN and LaMa crop around the mask before model inference and paste back only
+masked pixels. Their model sessions are loaded lazily. MI-GAN uses the inverse
+mask polarity expected by its ONNX model.
+
+Regression coverage:
+
+- [`test_region_eraser.py`](../tests/test_region_eraser.py)
+- [`test_inpaint_fallback.py`](../tests/test_inpaint_fallback.py)
+
+## Invisible watermark regeneration
+
+### Profiles and strength
+
+[`noai/watermark_profiles.py`](../src/remove_ai_watermarks/noai/watermark_profiles.py)
+is the source of truth for:
+
+- profile aliases;
+- default model identifiers;
+- default steps and seeds;
+- vendor-adaptive strength resolution;
+- the minimum viable step calculation.
+
+The current profiles are `controlnet`, `sdxl`, `qwen`, and `qwen-zimage`.
+For serverless cold starts, `InvisibleEngine.preload(global_only=True)` loads the
+mandatory Qwen stage and YuNet while leaving the optional Z-Image and SAM face
+stack lazy until a face is detected. The default `preload()` still loads every
+stage.
+`default` is a legacy alias for `sdxl`. There is no content-dependent automatic
+router.
+
+[`invisible_engine.py`](../src/remove_ai_watermarks/invisible_engine.py) handles
+image sizing, optional pre-upscaling, postprocessing, and the public engine
+interface. It delegates model execution to
+[`noai/watermark_remover.py`](../src/remove_ai_watermarks/noai/watermark_remover.py).
+
+The Python engine and CLI do not have identical defaults for every optional
+postprocessing argument. Integrations that require reproducibility should pass
+the relevant values explicitly.
+
+Regression coverage:
+
+- [`test_watermark_profiles.py`](../tests/test_watermark_profiles.py)
+- [`test_invisible_engine.py`](../tests/test_invisible_engine.py)
+- [`test_img2img_runner.py`](../tests/test_img2img_runner.py)
+- [`test_platform.py`](../tests/test_platform.py)
+
+### CPU offload
+
+CPU offload is enabled only when requested on CUDA. The standard Diffusers
+profiles call `enable_model_cpu_offload`. The `qwen-zimage` profile uses the
+same flag to force its face stack out of automatic device residency.
+
+Regression coverage:
+
+- [`test_cpu_offload.py`](../tests/test_cpu_offload.py)
+
+### Qwen plus Z-Image
+
+[`noai/qwen_zimage_pipeline.py`](../src/remove_ai_watermarks/noai/qwen_zimage_pipeline.py)
+implements the fixed CUDA-only two-stage profile:
+
+1. Qwen Image with Canny conditioning regenerates the frame.
+2. YuNet locates faces, SAM builds masks, and Z-Image regenerates the selected
+   face regions.
+
+The profile rejects a custom model identifier. Its global and face model stack
+is fixed by the implementation. When tiling is enabled, only the global stage
+is tiled; the face stage runs once after the tiles are blended.
+
+The resolution and largest-face adaptive formulas remain exact ports of the
+reference workflow. The face stage applies half the reference result because
+this port uses a different sampler and composites regenerated SAM pixels rather
+than using the reference latent inpaint mask and noise feather. Paired face
+evaluations favored this scale on identity, perceptual distance, and full-image
+similarity, and the exact OpenAI and Gemini candidates both passed their
+matching provider oracle. The global stage stays unchanged.
+
+Regression coverage:
+
+- [`test_qwen_zimage_pipeline.py`](../tests/test_qwen_zimage_pipeline.py)
+- [`test_cpu_offload.py`](../tests/test_cpu_offload.py)
+
+### Tiling
+
+[`noai/tiling.py`](../src/remove_ai_watermarks/noai/tiling.py) contains pure
+tile planning, feather weights, tile orchestration, and region compositing.
+
+Tiling engages only when requested and the long side exceeds the tile size.
+It avoids an explicit full-image downscale but does not make diffusion
+pixel-preserving. Each tile is still regenerated.
+
+`feather_region_composite` changes only the requested box and leaves pixels
+outside it unchanged.
+
+Regression coverage:
+
+- [`test_tiling.py`](../tests/test_tiling.py)
+
+### Upscaling and postprocessing
+
+[`upscaler.py`](../src/remove_ai_watermarks/upscaler.py) is the optional
+Real-ESRGAN path used only when enlarging a small image to the minimum
+resolution floor. Failure or an absent extra falls back to Lanczos.
+
+[`humanizer.py`](../src/remove_ai_watermarks/humanizer.py) contains explicit
+grain, unsharp masking, and adaptive polish helpers.
+
+Regression coverage:
+
+- [`test_upscaler.py`](../tests/test_upscaler.py)
+- [`test_humanizer.py`](../tests/test_humanizer.py)
+
+## Image input and output
+
+[`image_io.py`](../src/remove_ai_watermarks/image_io.py) is the shared image
+codec boundary.
+
+Contracts:
+
+- All package OpenCV file reads and writes use `image_io.imread` and
+  `image_io.imwrite`.
+- `to_bgr` normalizes grayscale and alpha-bearing arrays.
+- `read_bgr_and_alpha` and `write_bgr_with_alpha` preserve the alpha plane.
+- `imwrite` returns a success flag; every caller must check it.
+- HEIC, HEIF, and AVIF pixel reads fall back to Pillow plus `pillow-heif` from
+  the independent `heif` extra. Metadata scanning does not require that plugin.
+- A visible no-op can preserve the original file bytes.
+
+Regression coverage:
+
+- [`test_image_io.py`](../tests/test_image_io.py)
+- [`test_cli_robustness.py`](../tests/test_cli_robustness.py)
+
+## Adding or changing behavior
+
+For a new visible mark:
+
+1. create a synthetic detection silhouette;
+2. add or extend a vendor engine;
+3. add one registry entry;
+4. test detection, false positives, localization, and actual pixel change;
+5. update [supported signals](supported-signals.md).
+
+For a new metadata signal:
+
+1. add the scanner;
+2. add every supported removal placement;
+3. verify the output through `strip_and_verify`;
+4. add identification and removal tests;
+5. update [supported signals](supported-signals.md) and, when relevant,
+   [the watermarking landscape](watermarking-landscape.md).
+
+For a diffusion change:
+
+1. keep model-free logic in pure helpers where possible;
+2. test option propagation and dispatch without downloading models;
+3. run a real model smoke for the changed model path;
+4. treat provider-verifier results as specific to the exact checked output;
+5. update [known limitations](known-limitations.md).

docs/python-api.md

@@ -0,0 +1,233 @@
+# Python API
+
+Use the high level API for normal application integration. Low level detector
+and pipeline modules are intended for maintainers and specialized workflows.
+
+Dependency groups are identical for the CLI and Python API. The default install
+covers metadata extraction, normalization, verdict logic, and stripping.
+Array/pixel APIs use `pixels`; visible removal uses `visible`; DWT-DCT detection
+uses `detect`; and diffusion removal uses `diffusion`. Add `heif` independently
+when path-based pixel APIs must decode HEIC, HEIF, or AVIF. See the complete
+[feature-extra matrix](installation.md#feature-extras).
+
+## Remove visible marks
+
+Install `remove-ai-watermarks[visible]` before using the visible-removal API.
+
+```python
+import remove_ai_watermarks as raiw
+
+result, removed = raiw.remove_visible(
+    "watermarked.png",
+    "clean.png",
+)
+```
+
+The function returns:
+
+- the result as a BGR NumPy array;
+- a list of labels that were removed.
+
+An empty `removed` list means that no registered visible mark was selected. It
+does not prove the image has no metadata or invisible watermark.
+
+### Path input
+
+For a path input, `remove_visible`:
+
+- reads metadata provenance for the default `auto` sensitivity;
+- preserves a separate alpha channel;
+- writes the output when an output path is supplied;
+- strips AI metadata from the written output by default;
+- preserves the original bytes for a same-format no-op copy.
+
+```python
+result, removed = raiw.remove_visible(
+    "watermarked.png",
+    "clean.png",
+    sensitivity="auto",
+    backend="auto",
+    strip_metadata=True,
+)
+```
+
+Set `write_noop=False` if the output path must remain untouched when nothing is
+removed:
+
+```python
+result, removed = raiw.remove_visible(
+    "input.png",
+    "clean.png",
+    write_noop=False,
+)
+```
+
+### Array input
+
+Array inputs are BGR NumPy arrays. They do not carry file metadata or a separate
+alpha plane:
+
+```python
+import cv2
+import remove_ai_watermarks as raiw
+
+image = cv2.imread("input.png")
+result, removed = raiw.remove_visible(image, backend="cv2")
+```
+
+## Inspect provenance
+
+The default installation evaluates file metadata. Add `visible`, `detect`, or
+`trustmark` to enable the corresponding optional pixel signals.
+
+Get the vendor keys used by visible removal:
+
+```python
+import remove_ai_watermarks as raiw
+
+vendors = raiw.visible_provenance("input.png")
+```
+
+Get the full provenance report:
+
+```python
+from pathlib import Path
+
+from remove_ai_watermarks.identify import identify
+
+report = identify(Path("input.png"))
+print(report.platform)
+print(report.signals)
+```
+
+Use `check_visible=False` and `check_invisible=False` for metadata-only
+inspection through the compatible path-based API:
+
+```python
+report = identify(
+    Path("input.png"),
+    check_visible=False,
+    check_invisible=False,
+)
+```
+
+Extraction and detection are also available as separate steps. This is useful
+when a file-reading worker collects the metadata once and another component
+evaluates the resulting evidence:
+
+```python
+from remove_ai_watermarks.identify import (
+    extract_provenance_evidence,
+    identify_from_evidence,
+)
+
+evidence = extract_provenance_evidence(Path("input.png"))
+report = identify_from_evidence(evidence)
+```
+
+If metadata was collected by another component, normalize its nested record
+without reopening the original file:
+
+```python
+from remove_ai_watermarks.identify import (
+    evidence_from_metadata_record,
+    identify_from_evidence,
+)
+
+record = {
+    "pil": {"info:parameters": "Steps: 20, Sampler: Euler"},
+    "exif": {"0th": {"Software": "Stable Diffusion"}},
+}
+evidence = evidence_from_metadata_record(record, path=Path("input.png"))
+report = identify_from_evidence(evidence)
+```
+
+The normalizer recursively preserves text and byte values. It also decodes
+strings prefixed with `hex:` and fields named `base64` or ending in
+`_base64`. Diagnostic values under `error` and `kind` are ignored because they
+describe the collector rather than the source file. Pass a C2PA manifest-store
+dictionary in `record["c2pa_store"]`, or through the explicit
+`c2pa_manifest_store` argument.
+
+`identify_from_evidence` does not reopen the source file. It evaluates metadata
+only; registered visible marks and pixel-backed invisible watermarks remain in
+the path-based `identify` call.
+
+## Strip metadata
+
+```python
+from pathlib import Path
+
+from remove_ai_watermarks.metadata import has_ai_metadata, strip_and_verify
+
+source = Path("input.png")
+output = Path("clean.png")
+
+if has_ai_metadata(source):
+    output_path, surviving_markers = strip_and_verify(source, output)
+    if surviving_markers:
+        raise RuntimeError(
+            f"AI metadata remains in {output_path}: {surviving_markers}"
+        )
+```
+
+Use `strip_and_verify` when your application reports that stripping succeeded.
+It checks the written output and returns `(output_path, surviving_markers)`.
+When the first strip leaves markers in a malformed but raster-decodable image,
+it normalizes the container through `image_io` and checks again. That recovery
+path preserves the pixels but drops standard metadata. Treat a nonempty
+`surviving_markers` mapping as a failure.
+
+`remove_ai_metadata` is the lower level fail-safe transformer. It may copy an
+undecodable input through unchanged, so its return alone must not be presented
+as proof that metadata was removed.
+
+## Remove invisible watermarks
+
+Install `remove-ai-watermarks[diffusion]` for the standard pipelines or
+`remove-ai-watermarks[qwen-zimage]` for the CUDA-only high-fidelity profile.
+
+```python
+from pathlib import Path
+
+from remove_ai_watermarks.invisible_engine import InvisibleEngine
+
+engine = InvisibleEngine(
+    pipeline="controlnet",
+    device=None,
+    cpu_offload=False,
+)
+
+engine.remove_watermark(
+    Path("watermarked.png"),
+    Path("clean.png"),
+)
+```
+
+`device=None` selects the device automatically. Supported explicit values are
+defined by the CLI and runtime device resolver.
+
+For limited CUDA memory:
+
+```python
+engine = InvisibleEngine(
+    pipeline="controlnet",
+    cpu_offload=True,
+)
+```
+
+For the CUDA only high fidelity profile:
+
+```python
+engine = InvisibleEngine(pipeline="qwen-zimage")
+```
+
+The `qwen-zimage` extra must be installed for that profile.
+
+The full `remove_watermark` signature includes strength, steps, guidance,
+seeding, tiling, resolution, upscaling, and postprocessing controls. Read the
+method signature in
+[`invisible_engine.py`](../src/remove_ai_watermarks/invisible_engine.py) or use
+the CLI guide for the concepts.
+Defaults can differ between the Python method and CLI profile resolution, so
+pass values explicitly when reproducibility matters.

docs/qwen-improvement-research.md

@@ -0,0 +1,270 @@
+# Qwen-Image improvement research (2026-06-20)
+
+> Research archive. This page records experiments and decisions from the date
+> above. It may mention prototypes or defaults that were later changed. Use the
+> user guides and current source code for the supported interface.
+
+Cited research behind the decision **"ship the `qwen` pipeline as-is, or improve it
+first?"** Produced by the multi-source deep-research harness (5 search angles, 22
+sources fetched, 85 claims extracted, 25 verified by a 3-vote adversarial check, 20
+confirmed / 5 killed, 104 agent calls). Findings carry their confidence and vote.
+
+## Context
+
+The `qwen` pipeline runs base Qwen-Image (20B MMDiT, Apache-2.0) as a low-strength
+img2img scrub (removal comes from the denoising `strength`). Certified oracle scrub
+floors: OpenAI 0.10 (seed-robust), Gemini 0.25 (pinned seed). Measured against the
+SDXL + canny-ControlNet pipeline (`scripts/fidelity_metrics.py`): Qwen preserves
+**text** markedly better (incl. CJK and Cyrillic, lower OCR CER) but preserves
+**faces** worse, smoothing skin (Laplacian-variance retention 0.40 vs 0.62, face
+LPIPS 0.17 vs 0.09, ArcFace identity 0.38 vs 0.55 at the scrub floors). The goal of
+the research: keep Qwen's text advantage while fixing the face-smoothing, and judge
+production-readiness.
+
+## Verdict
+
+Base Qwen-Image is **shippable now as an opt-in text-content lane** (Apache-2.0 on
+code and weights, scrub lever confirmed), but it is not a universal upgrade (it loses
+faces). The strongest verified improvement path is to **add structure conditioning**
+(a Qwen-Image ControlNet) to the existing base pass, the direct analog of the SDXL +
+canny conditioning that wins on faces. Separately, **Z-Image / Z-Image-Turbo** (6B,
+Apache-2.0) is the best-verified lighter alternative to evaluate before committing to
+the 20B cost. At research time none of the improvements had measured face-fidelity
+numbers at our scrub floors. The later `qwen-zimage` follow-up below adds a crowded
+fixture, two direct upstream comparisons, and a provider-oracle-negative final candidate.
+A broader seeded text/face matrix is still needed for general certification.
+
+## Follow-up: ControlNet experiment + deeper research (2026-06-20)
+
+The verdict's strongest lead -- adding a Qwen-Image ControlNet -- was **built, measured, and
+CLOSED**.
+
+**Experiment** (Modal A100-80GB; DiffSynth-Studio `QwenImagePipeline` + the Apache-2.0
+`DiffSynth-Studio/Qwen-Image-Blockwise-ControlNet-Canny` -- the only framework exposing
+Qwen-Image + canny ControlNet + img2img `denoising_strength` in ONE call; diffusers ships no
+`QwenImageControlNetImg2ImgPipeline`, its three Qwen ControlNet pipelines are txt2img only).
+Measured on `gemini_3` (18 faces) at the Gemini scrub floor 0.25 vs base-Qwen 0.25 with
+`scripts/fidelity_metrics.py`:
+- **The actual failure mode (face skin texture) was NOT restored:** Laplacian-variance
+  retention stayed flat (base 0.40 -> qwen+canny 0.40; per-face 13/16 within +-0.02 after a
+  one-to-one face match, sd 0.016 -- not an averaging artifact). The SDXL+canny target 0.62
+  was not approached.
+- Identity rose modestly and broadly (ArcFace 0.346 -> 0.415, 12/16 faces improved) but the
+  absolute stays ~0.42 ("a different person, slightly closer").
+- Mechanism (verified, not inferred): canny conditioning was applied fully (scale 1.0, full
+  denoise schedule); the canny edge map is clean facial geometry with BLANK skin (4.83% edge
+  density) -- canny carries edges, not skin grain. Root cause: Qwen's Gemini floor (0.25) is
+  higher than SDXL+canny's (0.15), forcing more denoising -> more smoothing; structure
+  conditioning cannot compensate for that.
+
+**Deeper research** (deep-research harness, 103 agents, 3-vote adversarial):
+- **[high, unanimous] No permissively-licensed Qwen-Image tile / detail / realism / skin
+  ControlNet exists anywhere** -- DiffSynth first-party is Canny/Depth/Inpaint only, InstantX
+  Union is canny/soft-edge/depth/pose, the official QwenLM repo ships none. Every Qwen
+  conditioning is GEOMETRY, the same class as the tested canny. **The "add a Qwen ControlNet to
+  fix faces" lead is closed for good.**
+- **[high, unanimous] Z-Image / Z-Image-Turbo (6B, Apache-2.0 on code AND weights, ~1/3 of
+  Qwen 20B)** ships a documented `ZImageImg2ImgPipeline` with standard strength denoising, so
+  it preserves the scrub mechanism. Its own SynthID scrub floor and broad text fidelity
+  remain unmeasured. The later `qwen-zimage` follow-up provides direct face metrics.
+- **[medium] Lowering Qwen's scrub floor has no off-the-shelf SynthID answer:** the "partial
+  img2img ~0.3 breaks robust watermarks" literature tests open schemes
+  (StegaStamp/TrustMark/VINE), NEVER SynthID (proprietary decoder) -- analogy, not proof. No
+  minimal-strength SynthID attack under a named permissive license was found.
+- **REFUTED [0-3]:** "re-injecting high-frequency detail from a clean diffusion output would
+  not carry the watermark back." So non-regenerative detail transfer is NOT safe by
+  assumption -- the transferred high-frequency band must be gated against the SynthID oracle.
+
+**Net for the single-pass `qwen` pipeline:** faces stay on SDXL+controlnet; Canny alone is not
+a Qwen face fix. The next distinct architecture was Z-Image-Turbo on original masked face
+crops, not another Qwen geometry conditioner.
+
+**Implementation follow-up (2026-07-24):** that distinct architecture now exists as the
+manual `qwen-zimage` profile. It ports the upstream Synthid-Bypass v2 graph: Qwen-Image-2512
+Lightning + DiffSynth Canny for the full frame, then SAM-masked Z-Image Turbo regeneration
+from original face crops. The upstream result supplied by the user was Gemini-oracle negative.
+The active upstream face path is YOLO + SAM, not the unconnected MediaPipe node. The port
+matches its center-point + box prompts, IoU-0.93 proposal selection, detector-box intersection,
+crop factor, and paste feather; YuNet is the intentional detector substitution.
+
+The first exact-path Modal run completed without SAM fallback or face seams. On one crowded
+18-face `gemini_3` fixture, ArcFace identity improved materially over controlnet
+(0.795 vs 0.587/0.588 raw/polished), while face LPIPS was 0.082 vs 0.087/0.078.
+Two official upstream before/after pairs then reproduced the same identity advantage:
+local `qwen-zimage` scored 0.950/0.947 ArcFace identity versus polished ControlNet's
+0.701/0.548. The published upstream outputs remained slightly higher at 0.976/0.976.
+On the matched-size group example, local face LPIPS essentially matched upstream
+(0.015 vs 0.014) while whole-image LPIPS and SSIM were better (0.085/0.896 vs
+0.111/0.777). ControlNet retained more texture but changed the identities.
+
+That comparison also caught a real /16 alignment defect: DiffSynth dimensions were floored
+without resizing the corresponding PIL input. The official non-grid input failed with a
+VAE/noise-grid shape mismatch. Regression assertions were observed failing before global
+and face pixels were aligned to the same grid as their explicit dimensions.
+
+The final verifier follow-up is positive but exact-output scoped. On 2026-07-25 the user
+checked all six current outputs in the provider-separated
+`full-clean-final-candidate-2026-07-25-by-oracle` bundle with the corresponding provider
+oracles and confirmed that none retained SynthID or the provider generation signal. The
+checked bytes used the complete `visible -> qwen-zimage -> metadata` route, the calibrated
+YuNet 0.5 gate, and the shipped prompt-cache/model-residency optimizations. This supersedes
+the earlier first-port batch check as the release-candidate result, but it is not a
+certification across seeds, resolutions, and content classes. YuNet's threshold was
+calibrated independently from upstream YOLO: 0.5 retained the visible faces in the
+comparison fixtures while removing the false and duplicate boxes admitted by the copied
+0.2 gate. The remaining questions are now narrower: how well does text hold across a
+broader set and how stable removal is across seeds and Google content types. See
+`docs/known-limitations.md`.
+
+The shipped profile therefore resolves an omitted seed to `0`; explicit seeds still
+override it, and every other pipeline keeps its existing random default. This makes the
+documented `--pipeline qwen-zimage` command reproduce the seed condition used for the
+release-candidate oracle evidence without claiming cross-seed certification.
+
+**Product recommendation:** keep ControlNet as the default because it is much cheaper and
+supports CUDA, XPU, MPS, and CPU. Treat it as the compatibility baseline, not the
+highest-fidelity result. When CUDA is available and visual quality matters more than
+latency or cost, recommend `qwen-zimage`, especially for face-heavy content. This
+recommendation is based on the measured identity advantage and the oracle-negative exact
+candidate; it does not upgrade that exact-output result into broad certification.
+
+**Follow-up (2026-06-20) — the content-routed lane / mixed dual-pass was tested and DROPPED.**
+A `--pipeline auto` router (Haar+MSER → text→qwen / faces→controlnet / both→mixed) and a
+faces+text mixed dual-pass (scrub the whole frame on both, graft qwen text regions onto the
+controlnet base) were built and run on Modal (the abba poster: faces + display text). On that
+canonical faces+text case **controlnet won EVERY metric, including text** (CER 0.114 vs qwen
+0.379; ID 0.64 vs 0.36) — canny holds existing letter shapes, qwen re-renders display text and
+garbles it, so grafting qwen text only hurts. Qwen beats controlnet on text ONLY for clean body
+text on a plain background with no faces (openai_1/2), a niche `--pipeline qwen` alone covers;
+the faces+clean-body-text intersection is near-empty, and "text→qwen" is undecidable cheaply
+(body-vs-display text is what matters). So the router + mixed modules were removed and **`qwen`
+is a manual `--pipeline qwen` opt-in only.** KEPT (independently valid): the qwen geometry fix
+(it squished non-square inputs to 1024²), the pipeline-aware `resolve_strength` Qwen ladder, and
+the `fidelity_metrics.py` one-to-one face matcher below.
+
+**Tooling fix surfaced by this run:** `scripts/fidelity_metrics.py` face matching was changed
+from per-face nearest-center to a collision-free one-to-one assignment
+(`assign_faces_one_to_one`, gated by face size), after the 18-face `gemini_3` exposed
+collisions (the regenerated variants detected 17 faces, so two originals mapped to the same
+variant face, corrupting the identity metric). lapvar/LPIPS were always anchored to the
+original bbox and stayed collision-immune. Regression-guarded by
+`tests/test_fidelity_matching.py`.
+
+## Findings
+
+1. **[high, 3-0] A permissively-licensed Qwen-Image ControlNet exists today and is
+   CUDA/diffusers-runnable.** InstantX Qwen-Image-ControlNet-Union supports
+   canny/soft-edge/depth/pose; DiffSynth-Studio maintains blockwise Canny/Depth/Inpaint
+   plus an In-Context-Control-Union; diffusers exposes `QwenImageControlNetPipeline`
+   and `QwenImageMultiControlNetModel` with `controlnet_conditioning_scale` (default
+   1.0) and `control_guidance_start`/`end`. This is the direct analog of the certified
+   SDXL+canny structure conditioning that wins on faces. Caveat: canny/depth preserve
+   geometric structure, not face identity per se, and none is a **tile**-ControlNet
+   (the variant most tied to fine-detail/skin retention in the SDXL world).
+   Sources: InstantX/Qwen-Image-ControlNet-Union, InstantX/Qwen-Image-ControlNet-Inpainting,
+   DiffSynth-Studio Qwen-Image docs, diffusers qwenimage pipeline docs.
+
+2. **[high, 3-0] The scrub mechanism is preserved, and the license is clean.**
+   `QwenImageImg2ImgPipeline.strength` (default 0.6, range 0-1; DiffSynth names it
+   `denoising_strength`) keeps the partial-regeneration scrub the project relies on,
+   lower values staying closer to the input. Qwen-Image and Qwen-Image-Edit-2509 are
+   Apache-2.0 on both code and weights.
+
+3. **[medium, mixed 2-1 / 3-0] Qwen-Image-Edit improves identity consistency, but that
+   is not proof it fixes our metric.** The instruction-edit pipeline (2511 better than
+   2509) improves identity/character consistency, but only for identity *through edits*
+   of an input portrait, which is not the same as measured face-skin Laplacian/LPIPS
+   fidelity at a low scrub strength. Architecture: 20B base + Qwen2.5-VL (semantic
+   control) + VAE Encoder (appearance control). Several stronger edit-model face claims
+   were refuted (see below).
+
+4. **[high, 3-0] Z-Image / Z-Image-Turbo is the best-verified lighter alternative.** A
+   6B model (~1/3 of Qwen-Image's 20B), Apache-2.0 on code and weights, strong bilingual
+   (Chinese + English) native text rendering, with an official diffusers
+   `ZImageImg2ImgPipeline` exposing the same 0-1 denoising-strength scrub lever; Turbo
+   runs at ~8 steps (guidance_scale=0.0) vs ~40. A material cost/footprint reduction vs
+   20B/A100-80GB (but see caveat 4 on the refuted consumer-GPU claim).
+
+5. **[high, 3-0] EliGen-V2 is NOT relevant** to the face-smoothing problem. It is an
+   entity-level/regional control model (LoRA + regional attention placing entities via
+   text + mask maps, plus entity-level inpainting); it provides no
+   ControlNet/canny/depth/tile structure conditioning or face-skin-detail retention.
+
+6. **[medium, 2-1] flymy-ai/qwen-image-realism-lora** is Apache-2.0 (code+weights) on
+   base Qwen-Image, so it is permissively usable with the existing base img2img pass,
+   but it is NOT verified to specifically fix the face/skin-smoothing failure mode.
+
+## Caveats
+
+1. The research did NOT surface verified evidence for two things specifically asked:
+   (a) a Qwen-Image **tile**-ControlNet (the variant most tied to fine-detail/skin
+   retention; only canny/soft-edge/depth/pose/inpaint were confirmed), and (b) any
+   **non-regenerative detail-restoration** technique (high-frequency residual transfer,
+   guided filtering) that recovers smoothed faces without re-introducing the watermark.
+   Research angle 4 produced zero surviving claims, so it is unanswered.
+2. No external claim provides measured face-fidelity numbers (ArcFace/LPIPS/Laplacian) for
+   any recommended intervention at the project's scrub floors. The later direct
+   `qwen-zimage` comparisons are the project's own measurements, not external evidence or
+   a certification.
+3. Several vendor model cards are marketing-register primary sources (Qwen blog,
+   Z-Image card). Load-bearing facts (license, params, API levers) are independently
+   corroborated, but comparative quality framings are author glosses.
+4. Z-Image's "sub-second" figure is H800-specific and author-benchmarked; consumer-GPU
+   third-party benchmarks are still limited (seconds, not sub-second, though within the
+   <16GB envelope).
+5. Time-sensitivity: Qwen-Image-Edit-2511 and Z-Image are late-2025/2026 releases; the
+   diffusers pipelines cited are on the main/dev branch, so confirm released-version
+   availability before pinning.
+6. Five claims were refuted (below), clustering on over-strong edit-model face-fidelity
+   and one over-strong Z-Image cost claim.
+
+## Open questions
+
+- Does a Qwen-Image **tile-ControlNet** (or equivalent high-resolution detail
+  conditioning) exist under a permissive license?
+- What **non-regenerative detail-restoration** method recovers smoothed faces WITHOUT
+  re-introducing SynthID? Note: residual transfer from the ORIGINAL risks copying back
+  watermark-carrying high frequencies, so it must be verified against the SynthID oracle.
+- Head-to-head: does `qwen-zimage` retain its measured ArcFace gain across more portraits
+  and mixed scenes, match Qwen's text advantage (CJK+Cyrillic CER), and clear SynthID
+  robustly across content types and seeds?
+- Can YuNet's serial face workload be bounded to foreground/relevant faces without losing the
+  small faces the upstream YOLO path would process?
+
+## Refuted claims (do NOT rely on these)
+
+- [0-3] "Qwen-Image-Edit-2511 specifically targets/mitigates image drift, the same
+  failure mode as face-detail loss in a low-strength scrub." (qwen.ai/blog, 2511)
+- [0-3] "Qwen-Image-Edit-2509 explicitly improves facial identity preservation and
+  supports portrait styles and pose transformations." (HF Qwen-Image-Edit-2509)
+- [0-3] "Qwen-Image-Edit-2509 has native built-in ControlNet support (depth/edge/
+  keypoint)." (HF Qwen-Image-Edit-2509)
+- [1-2] "flymy realism LoRA specifically targets facial and skin detail, the exact
+  failure mode." (HF flymy-ai/qwen-image-realism-lora)
+- [0-3] "Z-Image-Turbo runs on consumer 16GB-VRAM hardware, far below the A100-80GB of
+  Qwen-Image 20B, materially lowering per-image cost." (HF Tongyi-MAI/Z-Image-Turbo)
+
+## Sources
+
+1. https://qwen.ai/blog?id=qwen-image-edit-2511
+2. https://qwenlm.github.io/blog/qwen-image-edit/
+3. https://docs.comfy.org/tutorials/image/qwen/qwen-image-edit
+4. https://github.com/FurkanGozukara/Stable-Diffusion/wiki/Qwen-Image-Edit-2511-Free-and-Open-Source-Crushes-Qwen-Image-Edit-2509-and-Challenges-Nano-Banana-Pro
+5. https://myaiforce.com/qie-2511/
+6. https://huggingface.co/Qwen/Qwen-Image-Edit-2509
+7. https://huggingface.co/InstantX/Qwen-Image-ControlNet-Union
+8. https://huggingface.co/InstantX/Qwen-Image-ControlNet-Inpainting
+9. https://huggingface.co/DiffSynth-Studio/Qwen-Image-EliGen-V2
+10. https://github.com/modelscope/DiffSynth-Studio/blob/main/docs/en/Model_Details/Qwen-Image.md
+11. https://blog.comfy.org/p/day-1-support-of-qwen-image-instantx
+12. https://learn.thinkdiffusion.com/how-to-use-qwen-image-with-instantx-union-controlnet-in-comfyui-guide-workflow/
+13. https://huggingface.co/flymy-ai/qwen-image-realism-lora
+14. https://huggingface.co/lightx2v/Qwen-Image-Lightning/discussions/4
+15. https://huggingface.co/docs/diffusers/main/en/api/pipelines/qwenimage
+16. https://www.diyphotography.net/skin-retouching-technique-frequency-separation/
+17. https://link.springer.com/content/pdf/10.1007/978-3-642-15549-9_1.pdf
+18. https://github.com/ShieldMnt/invisible-watermark/wiki/Frequency-Methods
+19. https://huggingface.co/Tongyi-MAI/Z-Image-Turbo
+20. https://github.com/huggingface/diffusers/blob/main/src/diffusers/pipelines/z_image/pipeline_z_image_img2img.py
+21. https://arxiv.org/pdf/2511.22699
+22. https://github.com/ModelTC/LightX2V-Qwen-Image-Lightning

docs/release-and-distribution.md

@@ -0,0 +1,102 @@
+# Release and distribution
+
+This page describes the release behavior defined in this repository. External
+registry state can change independently, so verify it during a release.
+
+## Release sources of truth
+
+The package version appears in:
+
+- `pyproject.toml`;
+- `src/remove_ai_watermarks/__init__.py`;
+- the root package entry generated in `uv.lock`.
+
+Update the first two, then refresh the lock file with uv. Do not edit a
+line-number-specific location in `uv.lock`; its package order changes.
+
+## Publish flow
+
+PyPI publishing is triggered by a published GitHub Release, not by a tag push
+alone.
+
+The expected sequence:
+
+1. update the version sources and lock file;
+2. run the complete project gate;
+3. commit the release change;
+4. create an annotated `vX.Y.Z` tag;
+5. push the commit and tag;
+6. publish the GitHub Release.
+
+`.github/workflows/publish.yml` then:
+
+1. checks that the release tag matches `pyproject.toml`;
+2. builds the package with uv;
+3. publishes with `uv publish` through PyPI trusted publishing.
+
+The workflow uses GitHub OIDC through the `pypi` environment. It does not read a
+PyPI API token from the repository.
+
+## Post-release distribution
+
+`.github/workflows/distribute.yml` runs on the same published-release event. It
+waits for the matching source distribution to appear on PyPI, then:
+
+- updates the Homebrew tap formula URL and SHA-256;
+- updates the repository conda recipe version and source-distribution SHA-256;
+- triggers a factory rebuild of the Hugging Face Space.
+
+The workflow can also be started manually with an optional version input.
+Conda-forge updates are outside this workflow.
+
+If a distribution job fails because a repository or Hugging Face credential is
+invalid, rotate the corresponding GitHub secret and rerun the failed job. A
+manual Homebrew formula update is the fallback when its automation is blocked.
+
+The conda job uses the published artifact rather than a locally built archive
+as the hash source and commits the resulting recipe change to `main`. Runtime
+dependency mapping remains review-controlled: keep it aligned with the default
+metadata dependencies in `pyproject.toml`, do not copy optional pixel extras
+into the default recipe, and document any conda-forge package that is
+unavailable and must be omitted.
+
+## Source distribution boundary
+
+The wheel includes the package under `src/`.
+
+The source distribution explicitly excludes `/data` through
+`[tool.hatch.build.targets.sdist]` in `pyproject.toml`. Keep that exclusion:
+calibration captures and test corpora do not belong in the published package
+archive.
+
+## Build backend
+
+The package uses hatchling through the unpinned `hatchling` build requirement in
+`pyproject.toml`. Uploading uses uv rather than the older twine-based action.
+
+## Other channels
+
+The repository includes a conda recipe under `packaging/conda/recipe.yaml`.
+
+The ComfyUI nodes are maintained and versioned in their own repository. After
+the matching source distribution appears on PyPI, `distribute.yml` dispatches
+that repository's sync workflow with the exact library version and waits for it
+to finish. The sync updates the dependency floor, runs compatibility tests,
+bumps the node patch version, and publishes to the ComfyUI Registry only when
+those tests pass. Its daily schedule remains as a recovery path if a release
+dispatch is interrupted. The `COMFYUI_RELEASE_TOKEN` repository secret is a
+fine-grained token limited to the ComfyUI node repository, with Actions read and
+write access.
+
+## Release verification
+
+After publication, verify:
+
+- both wheel and source distribution exist on PyPI;
+- the package version matches the tag;
+- the Homebrew formula points to the new source distribution;
+- the distribution workflow completed successfully;
+- the repository's conda recipe matches the published version and source
+  distribution;
+- the ComfyUI Registry node requires the new library version;
+- a clean install can run `remove-ai-watermarks --version`.

docs/research-doubao-distillation.md

@@ -0,0 +1,33 @@
+# Doubao clean-reverse-alpha distillation (re-investigated 2026-05-29)
+
+> Research archive. Reverse-alpha pixel recovery is no longer part of the
+> current visible-removal pipeline. The current implementation uses
+> localize-then-fill; see `docs/module-internals.md`.
+
+> Relocated verbatim from `CLAUDE.md` on 2026-06-11 to keep the always-loaded
+> context small. Long single-line entries were reformatted into paragraphs;
+> no content was changed or summarized.
+
+**RESOLVED 2026-05-29: black+gray Doubao captures were obtained and a reverse-alpha was built.**
+That historical method, `doubao_engine.remove_watermark_reverse_alpha`, has since
+been removed. Its detection silhouette remains at
+`src/remove_ai_watermarks/assets/doubao_alpha.png`. The committed captures in
+`data/calibration/doubao/` confirmed the alpha-composite model: on black
+`captured = a*logo`, logo pure white.
+
+**UPDATE 2026-05-31 (issue #13 follow-up): the first build was NOT "exact"** — it left a readable "豆包AI生成" outline on the real sample (the detector was fooled, conf 0.0). The alpha is now rebuilt by `scripts/visible_alpha_solve.py` (the careful gray-self solve shared with Jimeng), removal always-aligns + thin-inpaints, and the locate box was widened; see the `doubao_engine.py` section in `docs/module-internals.md`. The notes below (the failed content-image distillation) are retained as the record of why controlled captures were necessary.
+
+**Conclusion (historical): pure reverse-alpha distilled from content images does NOT work, and the blocker is the WRONG kind of data, not too little of it.**
+
+Curate same-resolution originals with `DoubaoEngine.detect` and an NCC filter against
+a clean glyph template, keeping only aligned marks. Even with aligned inputs,
+LaMa-clean `O` plus weighted least squares and per-pixel regression for `α` and logo
+color still leaves a persistent ghost outline.
+
+Diagnosed why, empirically (cached stacks, `/tmp/doubao_distill`): (1) the mark is a clean white overlay with **no dark halo** -- over glyph pixels ~54% are brighter than the clean bg, only ~4% darker -- so the white-logo model `I=(1-α)O+α·255` is correct; (2) but content backgrounds are almost never dark *under* the mark (median darkest available bg over glyph pixels = **58/255**; only ~13% of mark pixels are ever observed on a bg < 40), so on bright backgrounds the equation is ill-conditioned and `α` is unidentifiable; (3) LaMa's `O` is a plausible **hallucination**, not the true pre-mark background, which compounds the error, and per-pixel regression on ~15 obs overfits into color noise.
+
+**Why Gemini's engine is clean (verified in GeminiWatermarkTool `src/core/watermark_engine.cpp`): its alpha map is the watermark stamped on a PURE-BLACK background**, where `watermarked = α·255 + (1-α)·0 = α·255`, so `alpha = capture/255` exactly -- no estimation. (`gemini_bg_*.png` is literally the sparkle in gray on black.) So the real Doubao unlock is the same controlled capture, **not more content images**. The retained black and gray outputs live in `data/calibration/doubao/`; local solid-color seeds are regenerable and are not committed.
+
+**Until black captures arrive, the shipped direction is precise canonical glyph mask + inpaint (cv2 default, lama optional), NOT reverse-alpha.**
+
+The consensus glyph silhouette across the aligned marks distills cleanly (proto: a tight "豆包AI生成" strip, width ≈ 0.156 × image-width) and is good both as an exact inpaint mask and as an NCC localiser -- the latter also fixes the #23 detector false-positives (match the real glyph shape, not any bright low-saturation corner). Do **not** retry content-image reverse-alpha: it is data-limited by physics (no dark-background observations), not by effort.

docs/supported-signals.md

@@ -0,0 +1,130 @@
+# Supported signals
+
+This page describes the current support boundary. A check mark means that the
+repository contains a corresponding code path. It does not guarantee detection
+or removal on every future vendor version.
+
+## Visible marks
+
+The `visible` command registers these mark keys:
+
+| Key | Mark | Expected area | Important limit |
+| --- | --- | --- | --- |
+| `gemini` | Google Gemini sparkle | Usually bottom right | Detection includes a false positive gate. |
+| `doubao` | `豆包AI生成` | Bottom right | Vendor specific text detector. |
+| `jimeng` | `★ 即梦AI` | Bottom right | Vendor specific text detector. |
+| `qwen` | `千问AI生成` | Bottom right | Strict visual gate. |
+| `kling` | `可灵AI 3.0` | Bottom right | Only calibrated variants are covered. |
+| `yuanbao` | `元宝` over `AI生成` | Bottom right | Standard two-line variant only. |
+| `samsung` | `✦ Contenuti generati dall'AI` | Bottom left | Calibrated for the Italian text variant. |
+| `runninghub` | `RunningHub AI生成` | Top left | Strict visual and position gates. |
+| `baidu` | `百度 AI生成` | Bottom right | Detector and extended removal footprint. |
+| `liblib` | `LibLibAI` | Bottom center | Includes a minimum image size gate. |
+| `jimeng_pill` | `AI生成` pill | Top left | Weak detector with additional product and background gates. |
+
+`--mark auto` evaluates all registered marks and removes every selected match.
+Known marks are localized to a mask, then the selected fill backend reconstructs
+the masked area.
+
+Marks from other vendors are not detected automatically. Use `erase --region`
+when you can select the affected area yourself.
+
+## Fill backends
+
+| Backend | Install | Behavior |
+| --- | --- | --- |
+| `cv2` | `remove-ai-watermarks[visible]` | Classical OpenCV inpainting |
+| `migan` | `remove-ai-watermarks[migan]` | MI-GAN through ONNX Runtime |
+| `lama` | `remove-ai-watermarks[lama]` | big-LaMa through ONNX Runtime |
+| `auto` | Depends on installed extras | Selects LaMa, then MI-GAN, then OpenCV |
+
+The learned backends download model files on first use.
+
+## Metadata and provenance
+
+The inspection and stripping code handles signals in these groups:
+
+- C2PA Content Credentials and supported cloud manifest references;
+- EXIF and XMP generator fields;
+- IPTC AI disclosure fields;
+- PNG text chunks and embedded generation parameters;
+- China TC260 AIGC labels in supported metadata placements;
+- xAI and Grok EXIF signature fields;
+- Samsung AI editing markers;
+- Hugging Face job metadata;
+- open Stable Diffusion style DWT-DCT watermarks with the `detect` extra;
+- Adobe TrustMark with the `trustmark` extra.
+
+`identify` combines detected signals into a `ProvenanceReport`. It reports
+unknown when evidence is absent. It never treats missing metadata as proof that
+an image is human made.
+
+## File and container formats
+
+Pixel based image commands discover these extensions:
+
+- PNG;
+- JPEG;
+- WebP;
+- HEIC and HEIF;
+- AVIF.
+
+HEIC, HEIF, and AVIF pixel decoding requires the independent `heif` extra in
+addition to the selected pixel feature. Metadata scanning does not.
+
+Metadata inspection and removal additionally have container paths for:
+
+- JPEG XL metadata;
+- MP4, MOV, M4V, and M4A;
+- WebM, MKV, MKA, MP3, WAV, FLAC, OGG, OGA, Opus, and AAC when ffmpeg is
+  available.
+
+JPEG image metadata stripping removes targeted metadata segments without
+re-encoding the entropy coded image scan. PNG and WebP removal preserves pixel
+values through lossless output paths. HEIC, HEIF, AVIF, and other containers
+use their format specific paths.
+
+## Invisible watermarks
+
+The `invisible` command uses diffusion regeneration. It targets watermark
+patterns by changing the image rather than decoding and deleting a known
+payload.
+
+Current pipeline values:
+
+- `controlnet`;
+- `sdxl`;
+- `qwen`;
+- `qwen-zimage`;
+- legacy alias `default`, which resolves to `sdxl`.
+
+SynthID does not have a public local pixel decoder in this project. The tool can
+infer likely presence from supported provenance metadata, but after that
+metadata is removed a local negative result is inconclusive.
+
+The optional `detect` extra is different: it provides a local decoder for the
+open DWT-DCT watermark used by some Stable Diffusion, SDXL, and FLUX workflows.
+That signal is carrier and transformation sensitive, so a negative is still
+not a universal clean verdict.
+
+## Provider overview
+
+| Provider or family | Visible | Invisible path | Metadata or provenance |
+| --- | --- | --- | --- |
+| Google Gemini | Sparkle | Diffusion regeneration for SynthID | C2PA and related source signals |
+| OpenAI image generators | None registered | Diffusion regeneration for supported invisible signals | C2PA and generator provenance |
+| Stable Diffusion and SDXL | None registered | Diffusion regeneration; optional open decoder | Embedded parameters and text metadata |
+| FLUX | None registered | Diffusion regeneration; optional open decoder | C2PA for supported sources |
+| Adobe Firefly | None registered | No proprietary local decoder | C2PA; optional TrustMark decoder |
+| Midjourney | None registered | No registered pixel decoder | EXIF, XMP, and IPTC signals |
+| ByteDance generators | Doubao and Jimeng marks | No registered pixel decoder | TC260 AIGC and supported C2PA signals |
+| Qwen | Qwen mark | No registered pixel decoder | TC260 AIGC |
+| Kling | Kling mark | No registered pixel decoder | TC260 AIGC |
+| Baidu | Baidu mark | No registered pixel decoder | TC260 AIGC |
+| LibLibAI | LibLibAI mark | No registered pixel decoder | TC260 AIGC |
+| RunningHub | RunningHub mark | No registered pixel decoder | TC260 AIGC |
+| Samsung Galaxy AI | One locale specific mark | No registered pixel decoder | C2PA and Samsung markers |
+
+For detector thresholds, measured limits, and incident history, see
+[module internals](module-internals.md) and
+[known limitations](known-limitations.md).

docs/synthid-robust-identity-research-2026-06-08.md

@@ -0,0 +1,188 @@
+# Deep research: SynthID-safe face-identity recovery for SDXL (2026-06-08)
+
+> Research archive. This dated follow-up records evidence available during the
+> study. It is not the current command reference.
+
+**Stats:** {"angles": 6, "sourcesFetched": 28, "claimsExtracted": 104, "claimsVerified": 25, "confirmed": 19, "killed": 6, "afterSynthesis": 6, "urlDupes": 1, "budgetDropped": 7, "agentCalls": 111}
+
+## Summary
+
+For SDXL-based SynthID-removal pipelines, the entire ArcFace-class identity-adapter ecosystem (PhotoMaker-V2, InstantID, PuLID, IP-Adapter FaceID, Arc2Face) is blocked from commercial use by a single chokepoint: InsightFace's pretrained model packs (buffalo_l, antelopev2, buffalo_s, buffalo_m) are explicitly non-commercial research-only, regardless of the adapter weights' Apache-2.0/MIT license. The InstantX maintainers themselves acknowledged this on HuggingFace ("cannot be Apache 2.0 if it is using Insight Face") and stated intent to retrain on commercially-licensed embedders — work that as of the verified sources has not shipped. The only verified commercial-safe SDXL adapter surfaced is MS-Diffusion (ICLR 2025), which uses CLIP-ViT-bigG-14 instead of ArcFace and runs on SDXL-base-1.0, but it is an IP-Adapter-class subject-similarity method, not a face-identity method — CLIP image embeddings are empirically weaker for face identity than ArcFace (~81% vs ~88% face-ID accuracy), so it solves the license problem but likely not the identity-fidelity problem. Arc2Face is SD1.5-only and so not a drop-in regardless of license; StyleGAN2-based methods (e4e) terminate in a GAN generator with no SDXL wiring. Net: no fully commercial-safe SynthID-robust SDXL identity-preservation stack with ArcFace-grade fidelity exists today — the space is genuinely blocked by InsightFace's grip on commercial ArcFace embeddings, and AdaFace as a permissive ArcFace alternative was REFUTED in verification.
+
+## Findings
+
+### 1. The InsightFace pretrained model packs (buffalo_l, antelopev2, buffalo_s, buffalo_m) are non-commercial research-only and this restriction propagates at runtime to any adapter that calls FaceAnalysis(), regardless of the adapter's own license tag.
+
+**Confidence:** high  
+**Vote:** 3-0 unanimous across 4 supporting claims
+
+
+InsightFace upstream: code is MIT but 'The training data containing the annotation (and the models trained with these data) are available for non-commercial research purposes only.' Licensing page enumerates buffalo_l, antelopev2, buffalo_s, buffalo_m as needing separate commercial licensing. InstantX maintainer on HF: 'cannot be Apache 2.0 if it is using Insight Face... we plan to train on other face encoders that support commercial license.' Mechanical propagation: the runtime FaceAnalysis() call pulls these packs.
+
+- https://github.com/deepinsight/insightface
+- https://www.insightface.ai/solutions/face-recognition-licensing
+- https://huggingface.co/InstantX/InstantID/discussions/2
+
+### 2. InstantID is Apache-2.0 on the adapter weights and architecturally a clean plugin to SDXL-base-1.0 (no UNet training, semantic IdentityNet conditioning + landmark weak-spatial, no pixel copying) — but at runtime it instantiates FaceAnalysis(name='antelopev2'), inheriting the InsightFace non-commercial restriction.
+
+**Confidence:** high  
+**Vote:** 3-0 across 5 claims
+
+
+HF model card: 'License: apache-2.0' AND 'For face encoder, you need to manutally download via this URL to models/antelopev2' with 'from insightface.app import FaceAnalysis' in usage. Diffusers community pipeline shows literal `app = FaceAnalysis(name='antelopev2', ...)` then `face_emb = face_info['embedding']`. Paper: 'IdentityNet by imposing strong semantic and weak spatial conditions, integrating facial and landmark images with textual prompts' + 'seamlessly integrates with SD1.5 and SDXL'. So mechanism is semantic (good for SynthID-no-pixel-leak) but license is blocked.
+
+- https://huggingface.co/InstantX/InstantID
+- https://github.com/huggingface/diffusers/blob/main/examples/community/pipeline_stable_diffusion_xl_instantid.py
+- https://arxiv.org/pdf/2401.07519
+- https://instantid.github.io/
+
+### 3. Arc2Face is SD1.5-only (not SDXL) AND requires InsightFace antelopev2 with arcface.onnx replacing glintr100.onnx — so it is doubly blocked: not a drop-in for the SDXL pipeline AND non-commercial via the model pack.
+
+**Confidence:** high  
+**Vote:** 3-0 across 3 claims
+
+
+Arc2Face README verbatim: 'Arc2Face is built upon SD1.5' with stable-diffusion-v1-5 checkpoint as base. Same README: 'manually download the antelopev2 package and place the checkpoints under models/antelopev2', 'Download arcface.onnx from HuggingFace', 'delete glintr100.onnx (the default backbone from insightface)'. Code is MIT but the runtime antelopev2 dependency carries the non-commercial restriction. No SDXL adaptation exists in the official repo.
+
+- https://github.com/foivospar/Arc2Face
+
+### 4. MS-Diffusion (ICLR 2025) is the one verified candidate that combines SDXL-base-1.0 as its foundation with a non-ArcFace image encoder (CLIP-ViT-bigG-14), so it avoids the InsightFace non-commercial blocker — but it is an IP-Adapter-class multi-subject personalization method, NOT a face-identity-recognition method, so license safety does not equal face-identity fidelity.
+
+**Confidence:** medium  
+**Vote:** 3-0 on the narrow factual claims (SDXL base + CLIP-G encoder)
+
+
+GitHub README explicitly instructs 'Download the pretrained base models from SDXL-base-1.0 and CLIP-G' (CLIP-ViT-bigG-14-laion2B-39B-b160k). Neither README nor arXiv 2406.07209 mention ArcFace/InsightFace/antelopev2/buffalo_l. Architecturally descended from IP-Adapter (CLIP-image-embedding family), not from FaceID/InstantID/PhotoMaker-V2. Verifier caveat (high confidence on the license-narrow claim, medium on suitability): CLIP-image face-ID accuracy ~80.95% vs specialized face recognition ~87.61% — license-safe but probably not identity-grade for portraits. Confidence is medium because suitability for portrait and group-photo inputs has not been validated empirically.
+
+- https://proceedings.iclr.cc/paper_files/paper/2025/file/ed4df1609bf7d8602435341c9ce2ab5f-Paper-Conference.pdf
+- https://github.com/MS-Diffusion/MS-Diffusion
+
+### 5. ID-Aligner and the StyleGAN2/e4e-based identity method (arXiv 2510.25084) do not solve the problem: the former does not disclose embedder/license in the primary source; the latter terminates identity in a StyleGAN2 generator with no SDXL adapter, so it cannot be wired into the SDXL+canny ControlNet pipeline.
+
+**Confidence:** high  
+**Vote:** 3-0 across 3 claims
+
+
+ID-Aligner paper: no license terms, no weight-release status, no specific face embedder named in the primary source — commercial-safety unresolved. arXiv 2510.25084: 'facial identity features... mapped into the W+ latent space of StyleGAN2 using the e4e encoder' — identity pixels come from StyleGAN2's generator, not from any SDXL-compatible adapter, so architecturally incompatible with our SDXL+canny ControlNet pipeline. Abstract also does not name the face embedder or disclose weights license.
+
+- https://arxiv.org/pdf/2404.15449
+- https://arxiv.org/pdf/2510.25084
+
+### 6. The honest verdict: no fully commercial-safe SynthID-robust ArcFace-grade face-identity stack for SDXL exists today; the space is blocked by InsightFace's grip on ArcFace-class pretrained packs, and the verified permissive alternative (AdaFace as a drop-in replacement) was REFUTED in this verification round.
+
+**Confidence:** high  
+**Vote:** 3-0 on the chokepoint claim, 0-3 against the AdaFace escape hatch
+
+
+Every ArcFace-grade SDXL adapter audited (PhotoMaker-V2, InstantID, PuLID, IP-Adapter FaceID, Arc2Face) instantiates an InsightFace FaceAnalysis pack at runtime. The maintainer-acknowledged commercial-retrain path (InstantX) has not shipped. AdaFace as a permissive ArcFace alternative was refuted 0-3 by the adversarial verifier (MIT-licensed claim and drop-in-replacement claim both failed). Outcome: commercial-safe option for SDXL today is CLIP-image-embedding-based (MS-Diffusion class), which is weaker for face identity than ArcFace. For non-commercial / research-only deployments, InstantID on SDXL is the strongest semantic-only (no-pixel-leak) candidate.
+
+- https://github.com/deepinsight/insightface
+- https://huggingface.co/InstantX/InstantID/discussions/2
+- https://github.com/mk-minchul/AdaFace
+
+## Caveats
+
+Six claims were refuted in adversarial verification, two of them load-bearing: AdaFace as a permissive ArcFace drop-in (both the MIT license and the drop-in characterization failed 0-3) — so the most attractive escape hatch from the InsightFace chokepoint did not survive verification. PuLID's superiority claim and ID-Aligner's embedder claim also failed, leaving those methods uncharacterized at the mechanism level. None of the verified claims directly answered the diffusers-0.38 compat question — InstantID's compat with our shipped diffusers version is unverified by primary source. MS-Diffusion's identity-fidelity for portraits is not empirically validated for the SynthID-removal use case; it is verified as a CLIP-G/SDXL adapter, not as a face-identity method. No 2025-2026 candidate other than MS-Diffusion was both surfaced AND verified as license-safe and SDXL-compatible — the verification round did not produce a confirmed CCSR-V2/ConsistencyID/OmniGen-V2/ConsistentID/MagicID candidate. The multi-face scenario (group photos) was not addressed by any verified claim — MS-Diffusion is the only multi-subject candidate but its face-identity strength is unmeasured. Time-sensitivity: InstantX's stated intent to retrain on commercial embedders ("We agree, we plan to train on other face encoders that support commercial license") is dated and unfulfilled per the verified sources; this could change.
+
+## Open questions
+
+- Does MS-Diffusion (or any CLIP-image-embedding SDXL adapter) achieve usable face-identity fidelity on portraits and group photos, or is the ArcFace gap (~7 pp face-ID accuracy) visually disqualifying — and can a face-specific CLIP fine-tune close it?
+- Has InstantX (or any community fork) actually shipped an InstantID variant retrained on a commercially-licensed face embedder since the maintainer's 2024 commitment, and if so what is its identity-fidelity vs the antelopev2 original?
+- What is the exact diffusers-0.38 compat status of InstantID, MS-Diffusion, and PuLID-FLUX inference scripts — does any need a fork the way PhotoMaker-V1 did, and if so what specifically breaks?
+- Is there a single-pipeline multi-subject identity-preservation method (mask-guided regional ID-adapters, multi-subject InstantID, MS-Diffusion multi-subject mode) that handles group photos without the per-face crop+composite patchwork that PhotoMaker-V2 produced?
+
+## Refuted claims
+
+- **AdaFace code is released under the MIT license, making it permissively licensed for commercial use (in contrast to InsightFace's research-only model packs).** — vote 0-3 — source: https://github.com/mk-minchul/AdaFace
+- **AdaFace produces 512-dim face recognition embeddings comparable to ArcFace, positioning it as a drop-in alternative for ID-conditioning adapters that currently depend on InsightFace ArcFace.** — vote 0-3 — source: https://github.com/mk-minchul/AdaFace
+- **The paper claims PuLID achieves superior performance in both ID fidelity and editability compared to prior ID-customization methods.** — vote 0-3 — source: https://arxiv.org/pdf/2404.16022
+- **Identity consistency in ID-Aligner is enforced by reward feedback from face detection and recognition models, implying dependency on an external face-recognition embedder (typically ArcFace/InsightFace-class) rather than a CLIP-only path.** — vote 1-2 — source: https://arxiv.org/pdf/2404.15449
+- **The pipeline decouples face detection from inference by accepting a pre-computed embedding via image_embeds, so any ArcFace-class embedder could be swapped in if a commercially-licensed equivalent existed.** — vote 1-2 — source: https://github.com/huggingface/diffusers/blob/main/examples/community/pipeline_stable_diffusion_xl_instantid.py
+- **The model card does not explicitly prohibit commercial use, but the license of the required InsightFace antelopev2 embedder is not specified on this page.** — vote 1-2 — source: https://huggingface.co/InstantX/InstantID
+
+## Sources
+
+- [source](https://huggingface.co/InstantX/InstantID/discussions/2)
+- [source](https://www.insightface.ai/solutions/face-recognition-licensing)
+- [source](https://github.com/mk-minchul/AdaFace)
+- [source](https://github.com/foivospar/Arc2Face)
+- [source](https://apatero.com/blog/instantid-vs-pulid-vs-faceid-ultimate-face-swap-comparison-2025)
+- [source](https://arxiv.org/pdf/2404.16022)
+- [source](https://instantid.github.io/)
+- [source](https://arxiv.org/pdf/2404.15449)
+- [source](https://arxiv.org/pdf/2511.11989)
+- [source](https://arxiv.org/pdf/2510.25084)
+- [source](https://github.com/huggingface/diffusers/blob/main/examples/community/pipeline_stable_diffusion_xl_instantid.py)
+- [source](https://huggingface.co/InstantX/InstantID)
+- [source](https://github.com/huggingface/diffusers/issues/9158)
+- [source](https://github.com/huggingface/diffusers/issues/5904)
+- [source](https://github.com/Mikubill/sd-webui-controlnet/discussions/2589)
+- [source](https://arxiv.org/pdf/2401.07519)
+- [source](https://proceedings.iclr.cc/paper_files/paper/2025/file/ed4df1609bf7d8602435341c9ce2ab5f-Paper-Conference.pdf)
+- [source](https://github.com/huggingface/diffusers/issues/8626)
+- [source](https://arxiv.org/pdf/2404.04243)
+- [source](https://huggingface.co/OmniGen2/OmniGen2)
+- [source](https://github.com/VectorSpaceLab/OmniGen)
+- [source](https://github.com/ToTheBeginning/PuLID)
+- [source](https://arc2face.github.io/)
+- [source](https://github.com/mk-minchul/AdaFace/blob/master/LICENSE)
+- [source](https://github.com/IrvingMeng/MagFace/blob/main/LICENSE)
+- [source](https://github.com/askerlee/AdaFace-dev)
+- [source](https://openreview.net/forum?id=Hc2ZwCYgmB)
+- [source](https://github.com/tencent-ailab/IP-Adapter/wiki/IP%E2%80%90Adapter%E2%80%90Face)
+
+## Empirical follow-up (2026-06-08, end of session)
+
+After the research synthesis above, InstantID was integrated end-to-end and cert-swept
+on Modal A100 in two phases:
+
+1. **Phase 1: InstantID txt2img per-face crop + composite.** Per-face InstantID
+   txt2img with the upstream `pipeline_stable_diffusion_xl_instantid`, ArcFace
+   embedding from the original face, landmark stick figure. Three composite
+   iterations:
+   - v1 (rectangular Gaussian alpha on the 2x square_box around each face):
+     visible patchwork on group photos, generated 1024 backgrounds clashing.
+   - v2 (tight crop on YuNet-detected face in the generated 1024 + elliptical
+     alpha 0.45*bw x 0.55*bh + soft feather): ellipse axis exceeded bbox
+     vertically, clipped forehead/chin on single portrait, group still had
+     visible elliptical seams + cool-vs-warm tone clash with scene.
+   - v3 (tighter ellipse 0.32*bw x 0.42*bh + per-channel mean color match to
+     local cleaned canvas + softer feather): patchwork visually softened; faces
+     still read as studio portraits inserted into the scene, not as people
+     shot in the scene. Single portrait identity drifted (tatsunari -> "round
+     Asian male" vs original's thin face).
+2. **Phase 2: InstantID img2img on cleaned crop.** Switched to the upstream
+   `pipeline_stable_diffusion_xl_instantid_img2img` (downloaded at first use
+   from raw.githubusercontent.com; requires `trust_remote_code=True`). Same
+   ArcFace + landmark conditioning but the SDXL diffusion source is the
+   CLEANED face crop, so the diffusion sees scene lighting / shoulders /
+   shadow direction directly. Multi-face composition jumped substantially:
+   faces sit in the bar scene with matching warm tone, no more elliptical
+   seams. Single-portrait identity at the default (`strength=0.55`,
+   `ip_adapter_scale=0.8`, `controlnet_conditioning_scale=0.8`) was "similar
+   person, not exactly the original"; raising to `strength=0.7`,
+   `ip_adapter_scale=1.0`, `controlnet_scale=1.0` brought identity closer to
+   original but introduced more "SDXL gloss / clean skin" aesthetic.
+
+**Net finding for a commercial deployment (load-bearing).** The fundamental issue is structural:
+ArcFace encodes "this person's general look" (ethnicity, gender, basic facial
+geometry) at 512 dimensions; SDXL decodes that embedding into pixels with the
+inherent SDXL aesthetic (smooth skin, symmetric pores, AI-photoreal look).
+Stronger identity push (higher strength / IP-Adapter scale) makes the face
+CLOSER to the embedded identity but MORE AI-looking; weaker push leaves
+identity to drift but face looks less AI-generated. There is no parameter
+setting that simultaneously recovers original identity AND looks less AI than
+the cleaned image, because the cleaned image is itself a controlnet-light
+denoise of the original (closer to original pixels) while a restore pass is a
+full SDXL regeneration (further from original pixels).
+
+**Operational conclusion.** Do not ship `--restore-faces` in any monetized
+deployment. The cleaned image from the main controlnet 0.20 pass is the
+LEAST-AI state we can reach without re-introducing SynthID; every restore
+method tested (GFPGAN-on-cleaned, PhotoMaker-V2, InstantID txt2img,
+InstantID img2img-on-cleaned at three parameter sweeps) trades original-look
+for embedding-driven regeneration and makes the face read as "AI-generated"
+rather than "the original person". The `instantid` and `photomaker` extras
+stay in the library as opt-in for research / personal use where users
+explicitly want identity regeneration; the CLI flag and module docstrings
+state the trade-off at every entry point.

docs/synthid-robust-identity-research.md

@@ -0,0 +1,287 @@
+# SynthID-robust face identity for an SDXL removal pipeline (research)
+
+> Research archive. This document evaluates approaches considered during the
+> study. It does not describe the current public interface. The current
+> pipelines and limits are documented in `docs/cli.md` and
+> `docs/known-limitations.md`.
+
+> **Status (2026-06-08): retired.** Every approach described below was empirically
+> tested and rejected -- see `docs/synthid-robust-identity-research-2026-06-08.md`
+> "Empirical follow-up" for the final conclusion. The library no longer ships any
+> face-restore extra: the cleaned image from the main controlnet 0.20 pass is the
+> least-AI face state we can reach without re-introducing SynthID. This document
+> is kept as historical record of the exploration.
+
+**Question.** Which face identity-preservation mechanism for an SDXL img2img +
+canny-ControlNet watermark-removal pipeline (denoise 0.20-0.30) is BOTH (a)
+commercial-safe end-to-end and (b) does not re-introduce the SynthID pixel
+watermark the removal pass just destroyed?
+
+**Constraint.** A paid deployment requires every component (adapter weights AND
+the face embedder it conditions on AND any base model) must be Apache-2.0 / MIT /
+BSD or otherwise clearly commercial-permitted. Non-commercial is disqualifying.
+
+**One-line verdict.** Today there is **ONE** SDXL identity-conditioning stack that
+is commercial-safe end-to-end: **PhotoMaker-V1** (Apache-2.0, identity encoded as a
+fine-tuned OpenCLIP-ViT-H/14 image embedding -- NO InsightFace). Every other
+candidate -- **including PhotoMaker-V2**, IP-Adapter FaceID, InstantID, PuLID,
+Arc2Face -- inherits InsightFace's non-commercial model-pack license through an
+ArcFace-class embedder and is therefore blocked for paid services, regardless of
+the adapter's own license header. Below is the evidence per component and the
+integration plan.
+
+**Correction notice (2026-06-04).** An earlier version of this doc claimed
+PhotoMaker-V2 was commercial-safe end-to-end. That was WRONG -- the V2 model card
+phrase *"id_encoder includes finetuned OpenCLIP-ViT-H-14 and a few fuse layers"*
+described one of TWO ID branches; the V2 source (model_v2.py) defines
+`PhotoMakerIDEncoder_CLIPInsightfaceExtendtoken` whose forward takes an
+ArcFace `id_embeds` from `insightface.app.FaceAnalysis`, and the upstream package
+`__init__.py` imports InsightFace at module load. A Modal cert sweep caught this
+empirically (`No module named 'insightface'` from `restore_faces_photomaker`). V1
+is the correct commercial-safe target: its `PhotoMakerIDEncoder` (model.py)
+forward takes only `(id_pixel_values, prompt_embeds, class_tokens_mask)` -- no
+ArcFace branch -- so identity is CLIP-only.
+
+**Status notice (2026-06-04, end of session).** Two commercial-safe paths were
+tried and abandoned:
+
+1. **PhotoMaker-V1** (commercial-safe by license but blocked by upstream compat).
+   The cert sweep hit a cascade of upstream compatibility issues with the diffusers
+   version we ship (0.38): missing `einops` declaration, missing `peft` declaration,
+   default `pm_version='v2'` that mis-loads V1 weights into the V2 encoder, custom
+   `id_encoder` left on CPU after `pipe.to(device)`, and a CFG-batch tensor-shape
+   mismatch in the denoising loop (`Expected size 2 but got size 1`). 7 cascading
+   fixes did not get the pipeline running end-to-end. The PhotoMaker `pipeline.py`
+   header notes it was forked from diffusers v0.29.1; SDXL prompt-encoder handling
+   changed significantly between 0.29 and 0.38.
+2. **GFPGAN on the diffusion-CLEANED image** (commercial-safe, but no identity
+   recovery). A one-line change made it SynthID-safe (input pixels are already
+   clean, so the partial blend cannot transport the watermark), but visual
+   inspection of the cert output showed it only polished the already-drifted face
+   without actually restoring identity. Trade-off was real and the value too low
+   to keep.
+
+**The shipped path is PhotoMaker-V2** (`photomaker_restore.py`, the `photomaker`
+extra). V2 uses a DUAL ID encoder (CLIP image features + ArcFace embedding),
+which delivers true identity-from-embedding face regeneration. The cost is that
+the ArcFace embedding comes from InsightFace's `antelopev2`/`buffalo_l` model
+packs, which are released under a non-commercial / research-only license. **So
+the shipped restore path is NON-COMMERCIAL.** Any monetized
+deployment must NOT install the `photomaker` extra. The CLI flag and module
+docstring both call this out at every entry point.
+
+A future commercial-safe path would need either (a) the PhotoMaker upstream to
+land its diffusers 0.38 compat fix so V1 can run, or (b) an equally good
+ArcFace-class face-recognition model released under a permissive license that
+PhotoMaker-V2 can be retargeted to. Neither is on a near-term horizon as of
+this writing.
+
+## 1. Why identity-by-embedding (not by pixel) is the only SynthID-robust path
+
+The pipeline regenerates pixels to destroy SynthID. Any identity-restoration that
+is "faithful to the input pixels" (GFPGAN, CodeFormer, face-swap-by-blending, our
+previous restore-on-original pass) reproduces the watermark, because SynthID is
+engineered to be robust to fidelity-preserving transforms (resize, JPEG, partial
+blend). Oracle-confirmed on a real Gemini face: controlnet @ 0.20/0.25 WITH the
+GFPGAN restore pass left SynthID detected; the SAME controlnet @ 0.20 with
+`--no-restore-faces` cleared it (clean A/B, see `docs/synthid.md` 5.5 and
+`docs/controlnet-removal-pipeline-research.md`).
+
+The only mechanism that can preserve identity AND not re-introduce SynthID is to
+carry identity in a SEMANTIC EMBEDDING (a vector that encodes "who is in this
+picture") and use it to CONDITION a fresh generation -- the pixels are new, so
+the watermark is not transported. Two embedding families exist in practice:
+
+- **ArcFace-class face-recognition embeddings** (the InsightFace family). Used by
+  IP-Adapter FaceID, InstantID, PuLID, Arc2Face. Highest identity fidelity, but
+  the embedder weights are non-commercial.
+- **CLIP image embeddings of a face crop**. Used by PhotoMaker (and the original
+  IP-Adapter image variant). Lower identity fidelity at small scale than ArcFace,
+  but the encoder (OpenCLIP-ViT-H/14, MIT) is commercial-safe.
+
+## 2. License table (verified against primary sources, 2026-06-04)
+
+| stack | adapter weights | identity encoder | end-to-end commercial-safe? |
+|---|---|---|---|
+| **PhotoMaker-V1** | **Apache-2.0** ([HF][pmhf]) | **OpenCLIP-ViT-H/14 (MIT)** finetuned, identity from `PhotoMakerIDEncoder` (`model.py`); forward takes only ``(id_pixel_values, prompt_embeds, class_tokens_mask)`` -- no ArcFace branch | **YES** |
+| PhotoMaker-V2 | Apache-2.0 (adapter) ([HF][pm2hf]) | DUAL encoder: OpenCLIP-ViT-H/14 AND InsightFace antelopev2/buffalo_l -- `PhotoMakerIDEncoder_CLIPInsightfaceExtendtoken` (`model_v2.py`) forward takes `id_embeds` from `insightface.app.FaceAnalysis`, and `photomaker/__init__.py` imports InsightFace at module load | NO -- InsightFace pack is non-commercial |
+| IP-Adapter FaceID | non-commercial per model card: *"AS InsightFace pretrained models are available for non-commercial research purposes, IP-Adapter-FaceID models are released exclusively for research purposes and is not intended for commercial use"* ([HF][ipafhf]) | InsightFace antelopev2 (non-commercial for the model pack) | NO -- both layers block |
+| InstantID | Apache-2.0 (adapter only) ([HF][insthf]) | requires InsightFace antelopev2 face-analysis at runtime (`FaceAnalysis(name='antelopev2', ...)` per the README usage snippet, [HF][insthf]) | NO -- embedder pack is non-commercial |
+| PuLID | apache-2.0 (HF model metadata, [HF][pulidhf]) | depends on InsightFace face-analysis for ArcFace embedding (per the upstream README; PuLID's own card is sparse and the GitHub README documents the InsightFace install step) | NO -- same embedder issue as IP-Adapter FaceID |
+| Arc2Face | MIT (HF model metadata, [HF][arc2hf]) | uses `insightface.app.FaceAnalysis` to extract the ArcFace embedding ([HF][arc2hf]); also based on SD-v1-5 (NOT SDXL) | NO -- non-commercial embedder + not SDXL |
+
+**The crux is InsightFace.** InsightFace explicitly splits its license: *"Code is
+MIT licensed; models require separate commercial licensing"* and frames the
+pretrained packs as *"Commercial licensing for InsightFace's open-source model
+packages"* requiring users to *"obtain commercial usage rights for model
+packages"* ([insightface.ai][iflic]). antelopev2 and buffalo_l fall under the
+model-pack license, not MIT. So any stack that calls
+`insightface.app.FaceAnalysis(name='antelopev2', ...)` to compute its ArcFace
+embedding is blocked by default, REGARDLESS of the adapter's own Apache header
+above it. This is the same reason IP-Adapter FaceID's card flags itself
+non-commercial.
+
+(Note on PuLID's HF metadata: the model card declares apache-2.0 for the adapter
+weights but the upstream repo's quickstart requires the InsightFace package to
+extract the ID embedding. So PuLID's adapter license is permissive; the BLOCKER
+is the embedder it expects at runtime. This is the same trap as InstantID.)
+
+[pmhf]: https://huggingface.co/TencentARC/PhotoMaker
+[pm2hf]: https://huggingface.co/TencentARC/PhotoMaker-V2
+[ipafhf]: https://huggingface.co/h94/IP-Adapter-FaceID
+[insthf]: https://huggingface.co/InstantX/InstantID
+[pulidhf]: https://huggingface.co/guozinan/PuLID
+[arc2hf]: https://huggingface.co/FoivosPar/Arc2Face
+[iflic]: https://www.insightface.ai/solutions/face-recognition-licensing
+
+## 3. Is there a commercial-safe ArcFace replacement?
+
+Short answer: **no clean drop-in**. The widely deployed pretrained ArcFace packs
+(antelopev2, buffalo_l, glint360k) come from InsightFace and are non-commercial.
+ArcFace as an ARCHITECTURE is published in a paper, so retraining is legally fine,
+but you would need:
+
+- a commercial-licensed training dataset (the big public ones -- MS-Celeb-1M,
+  Glint360K, WebFace -- carry research-only or licensing-uncertain restrictions);
+- compute + time to train an ArcFace-class model on the legal dataset;
+- the result would be a one-off effort, not a maintained dependency.
+
+For a removal service this is a multi-month side project that delivers what
+PhotoMaker already gives us with one pip install. So the practical answer is to
+take the CLIP-embedding path (PhotoMaker-V1; V2 adds InsightFace and is non-commercial), accept the identity-fidelity
+trade-off, and revisit ArcFace later if quality is insufficient.
+
+## 4. Does an identity embedding leak SynthID?
+
+This is the load-bearing assumption of the whole approach. The argument:
+
+- SynthID is a low-amplitude, perceptually-invisible pixel watermark engineered
+  to be robust to "fidelity-preserving" transforms (it survives JPEG, resize,
+  crop, color, noise at >=99% TPR -- see arXiv:2510.09263 referenced in
+  `docs/synthid.md`).
+- A face-recognition / CLIP-image embedding is by design INVARIANT to such low-
+  amplitude pixel changes (compression, brightness, small noise should not change
+  "who is in the photo"). That is the whole training objective.
+- Therefore the embedding extracted from a watermarked face vs. the same face
+  cleaned should be ~identical -- the embedding cannot CARRY the watermark
+  pattern, only the identity, because the watermark sits in exactly the
+  dimensions the embedding learned to discard.
+
+**MEASURED 2026-06-04 — hypothesis confirmed.** Ran a low-amplitude
+perturbation sweep on 31 face crops (3 photoreal originals: gemini_3, gemini_4,
+openai_3 grid), comparing `cos(embedding(orig), embedding(perturbed))` for OpenCLIP-
+ViT-H/14 (laion2B-s32B-b79K, the same OpenCLIP-ViT-H/14 encoder PhotoMaker V1 and V2 both finetune for CLIP-side identity):
+
+| perturbation | mean cos | min | max |
+|---|---|---|---|
+| **synthid_proxy** (±2 LSB low-freq noise, σ=4 px Gaussian carrier — same regime SynthID hides in) | **0.9977** | 0.9937 | 0.9996 |
+| noise3 (Gaussian σ=3, full-spectrum) | 0.9541 | 0.9055 | 0.9825 |
+| jpeg90 (SynthID survives this) | 0.9280 | 0.8806 | 0.9566 |
+| blur1 (Gaussian σ=1) | 0.9139 | 0.8103 | 0.9875 |
+| jpeg70 | 0.8945 | 0.8125 | 0.9603 |
+| (self check: identical crop) | 1.0000 | 1.0000 | 1.0000 |
+
+The SynthID-magnitude perturbation moves the embedding by **0.002** (cosine 0.9977),
+an order of magnitude less than JPEG90 — which SynthID survives at >=99% TPR by
+design. So the embedding cannot carry the watermark pattern: its discriminative
+signal is in dimensions the SynthID payload does not occupy. PhotoMaker-V1
+conditioned on a watermarked face will see ~the same identity vector as if
+conditioned on a clean face of the same person, so the freshly generated face
+inherits the identity, not the watermark.
+
+A first, naive smoke run measured `cos(orig, SDXL-cleaned)` instead — that test is
+about diffusion drift, not watermark invariance (diffusion at strength 0.20-0.30 is a
+much larger perturbation than SynthID), so its 0.56-0.93 spread is the identity
+drift the PhotoMaker pipeline is meant to fix in the first place. The
+synthid_proxy result above is the one that actually answers the load-bearing
+question. Script: `/tmp/identity_smoke/test2_proxy.py` (not committed; reproducible
+from the test set + this doc).
+
+## 5. PhotoMaker-V1 properties for our pipeline
+
+- **SDXL-native.** PhotoMaker v1 and v2 target Stable Diffusion XL; the pipeline
+  is a stacked-ID embedding fused into SDXL's cross-attention via the fuse layers
+  bundled in the released weights.
+- **Identity from a SINGLE reference image works** but the method was designed
+  for "stacked" multi-reference; with one image identity fidelity is lower than
+  with 3-4, and a service has only one (the upload). This is the failure mode to
+  guard.
+- **Compatibility with img2img + canny ControlNet.** PhotoMaker is typically
+  exposed in txt2img workflows in the upstream demo. SDXL img2img + ControlNet
+  is the same denoising backbone, so the cross-attention injection works the same
+  way; community examples on Diffusers and ComfyUI confirm PhotoMaker stacks with
+  ControlNet. Validate this on a representative image before adopting.
+- **Failure modes to expect:**
+  - identity drift on small / multi-face groups (the 9-face grid case);
+  - "plastic" / over-smoothed faces if PhotoMaker's identity weighting is high
+    while the img2img strength is low;
+  - canny ControlNet conditioning can fight the ID embedding (edges of the
+    ORIGINAL face vs identity of the SAME person regenerated) -- expect to tune
+    `controlnet_conditioning_scale` down a notch on photoreal faces;
+  - PhotoMaker was trained on a celebrity-skew distribution; representative faces
+    (especially non-white, non-Western, elderly, children) may have lower
+    fidelity. Measure on a representative evaluation distribution.
+
+## 6. Integration cost (rough)
+
+- New deps: `diffusers` already in the diffusion extra; PhotoMaker ships as a `.bin`
+  loaded via `pipeline.load_photomaker_adapter(...)`. The OpenCLIP encoder is the
+  same one diffusers already pulls. No new heavy pip dep.
+- Weight download: PhotoMaker-V1 weights are ~3 GB. Add to the Modal HF volume
+  alongside SDXL.
+- VRAM: SDXL + canny ControlNet + PhotoMaker-V1 fits comfortably in A100-40GB.
+- Latency: a few extra seconds on cold start (load PhotoMaker), negligible per
+  request after warm-up.
+- No InsightFace install: huge win for `restore` extra's basicsr/numpy hell --
+  this path simply does not touch that ecosystem.
+
+## 7. Recommended path
+
+1. **Embedding-invariance smoke test FIRST** (one afternoon, no codegen):
+   - For ~10 OpenAI / Gemini watermarked faces, compute OpenCLIP-ViT-H/14
+     embeddings; for the same images after our SDXL `default` pass at the
+     certified strength, compute the embeddings again; assert mean cosine
+     similarity > ~0.95.
+   - If yes -> the embedding does not carry SynthID, proceed.
+   - If no -> the assumption is wrong; PhotoMaker would re-introduce the
+     watermark. Stop and reconsider.
+2. **PhotoMaker-V1 prototype** in the existing `controlnet` pipeline:
+   - Mirror the `_load_controlnet_pipeline` path: add a PhotoMaker variant that
+     loads SDXL + canny ControlNet + PhotoMaker adapter on the same engine.
+   - Extract the OpenCLIP face embedding from the watermarked face crops (use
+     OpenCV YuNet, already bundled for `auto`, to find the face boxes).
+   - Pass the embedding as PhotoMaker's `id_embeds` to the SDXL pipeline; run
+     img2img at the certified strength (0.20 OpenAI, 0.30 Gemini-capped-1536)
+     with the canny edge map.
+3. **Oracle validation** on the cert sweep: run the new PhotoMaker variant
+   through the isolated Modal certification harness over the same 6 image set, certify on the
+   per-vendor oracles. Expected: SynthID cleared (the regeneration is the same)
+   AND identity recovered (the embedding adds it back).
+4. **Honest exit criteria.** Ship only if BOTH oracle reads clean AND a small
+   user-perception test on representative inputs says "looks like me". If identity is
+   still too soft on small faces -> add stacked-reference (multiple crops of the
+   same upload at different scales) before reaching for a non-commercial
+   embedder.
+
+## 8. What we are NOT doing, and why
+
+- **No InsightFace.** Non-commercial for model packs (see License table).
+- **No CodeFormer.** Non-commercial.
+- **No GFPGAN on the original image.** It re-introduces SynthID
+  (oracle-confirmed).
+- **No GFPGAN on the cleaned image.** It cannot RECOVER identity that the
+  diffusion pass already drifted -- it can only smooth/sharpen whatever face is
+  already there. Useful as cosmetic polish, not as identity restoration.
+- **No retraining of an in-house ArcFace.** Out of scope for a removal service.
+
+---
+
+## Process note
+
+The deep-research harness was run but its verifier subagents failed to call
+`StructuredOutput` (same harness bug as the prior 2026-05-XX run), so its synthesis
+was unusable. The license claims above were verified by directly fetching the HF
+model cards and the InsightFace licensing page and quoting them; the
+embedding-invariance argument is mechanistic and explicitly flagged as not yet
+measured (it is the first integration step). Do not treat the deep-research
+output as ground truth for this file.

docs/synthid.md

@@ -1,5 +1,10 @@
 # SynthID-Image: technical reference
 
+> Technical research reference. Current package behavior is defined by the
+> [supported signals](supported-signals.md), [known limitations](known-limitations.md),
+> and [module internals](module-internals.md). Dated measurements below are
+> historical evidence and should not be read as current CLI defaults.
+
 This document covers how Google SynthID for images works mechanically, what it
 survives, what removes it, and the current deployment landscape. It is written
 for engineers working on watermark detection and removal -- specifically to
@@ -175,12 +180,24 @@ A controlled study (June 2026, clean v0.8.6 with text/face protection OFF,
 native resolution on this repo's default SDXL pipeline) measured the minimum
 img2img strength that removes the SynthID pixel watermark, verified per image on
 the vendor's own oracle (openai.com/verify for OpenAI, the Gemini app "Verify
-with SynthID" for Google). The test set and per-image results are recorded in
-`data/synthid_corpus/` (manifest `verified_via` = `openai-verify` / `gemini-app`).
+with SynthID" for Google). The reusable originals are stored once in
+`data/synthid/originals/`, with their input verification in `manifest.csv`.
+Generated cleaned outputs are not committed; the table below is the durable
+record of the historical oracle verdicts. One third-party image from issue #14
+was oracle-verified but is not committed.
+
+**Oracle validation order: start with OpenAI.** When validating removal across
+vendors, run the OpenAI arm first. `openai.com/verify` is more accessible than the
+Gemini app -- fewer per-check restrictions, so it gives the fastest signal and is
+the strongest candidate for automation (Playwright / Chrome MCP driving
+`openai.com/verify`); the Gemini "Verify with SynthID" flow is more manual. This is
+an ordering/throughput choice, not a substitution: each oracle only reads its own
+vendor's SynthID (`openai.com/verify` is OpenAI-scoped), so Google content still
+needs the Gemini app.
 
 | Vendor | Images | Resolution(s) | Pipeline | Removed at |
 |--------|--------|---------------|----------|------------|
-| OpenAI (gpt-image) | n=4 | 1024x1536 .. 1600x1600 | native | **0.05** |
+| OpenAI (gpt-image) | n=4 (3 archived + 1 external-only) | 1024x1536 .. 1600x1600 | native | **0.05** |
 | Google (Gemini)    | n=4 | 2816x1536 -> capped 1536 | `--max-resolution 1536` | **0.15** (0.05 and 0.10 do NOT clear) |
 
 **Two findings, both oracle-verified:**
@@ -196,12 +213,11 @@ with SynthID" for Google). The test set and per-image results are recorded in
 **CORRECTION (supersedes the earlier "resolution dependence" claim).** A prior
 version of this doc and CLAUDE.md stated that strength 0.30 failed to remove
 SynthID on 1600x1600 gpt-image and that removal was resolution-dependent. That
-was an **artifact of the text-protection bug** (issue #14): those tests ran a
-build where `protect_text` was ON by default, and the high-resolution text
-re-scrub re-introduced SynthID in the dense-text regions of the infographic
-images tested. Re-running the *same* 1600x1600 image on clean v0.8.6 (protect
-OFF) removes SynthID at **0.05**. The "large images resist removal" conclusion
-was false; the resistance was the protect-text shielding, now fixed (v0.8.5).
+was a **measurement artifact of a since-removed per-region re-scrub step** (issue
+#14): on the dense-text infographics tested, that step could reconstitute SynthID
+in text regions. Re-running the *same* 1600x1600 image on the clean current
+pipeline removes SynthID at **0.05**. The "large images resist removal" conclusion
+was false; the resistance was that region-rescrub shielding, since removed.
 
 **Open / not locally testable:**
 
@@ -362,58 +378,119 @@ empirically from oracle tests:
 
 Google has hardened SynthID relative to OpenAI's (vendor gap measured at ~3x
 strength), but the year-over-year "0.05 -> 0.10 -> 0.30" progression above
-conflates a real hardening trend with the now-debunked protect-text artifact;
+conflates a real hardening trend with the now-debunked region-rescrub artifact;
 treat only the section 2.2 controlled numbers as authoritative.
 
 ---
 
 ## 5. Practical implications for this tool
 
-### 5.1 Text and face protection: OFF by default
+### 5.1 Preserving content means regenerating it, never copying it
 
-**Text protection (`--protect-text`) can preserve SynthID in text regions.**
-Verified June 2026 on gpt-image at 1600x1600: same image processed twice --
-with `--protect-text` the oracle detected SynthID; without it, SynthID was
-removed. The mechanism: the global img2img pass clears SynthID everywhere, but
-the text-protection high-resolution re-scrub regenerates those pixels from an
-upscaled crop. At the effective resolution of the upscaled crop, the per-region
-pass may be insufficient to re-destroy the payload, reconstituting SynthID in
-text regions.
+**Core rule:** SynthID is a pixel-amplitude pattern, so any approach that FREEZES
+or RESTORES original pixels in a region re-introduces the watermark there. Early
+region-based text/face "protection" (since removed) proved this: restoring the
+original face pixels guaranteed SynthID survived in faces, and even a per-region
+high-resolution re-scrub from an upscaled crop could be insufficient to destroy
+the payload, reconstituting SynthID in text. The lesson held and shaped the
+current design: **content is preserved by REGENERATING it under structural
+conditioning, never by copying original pixels.**
 
-**Face protection (`--protect-faces`) has an even more direct preservation
-mechanism.** The pipeline extracts face regions from the ORIGINAL (watermarked)
-image BEFORE the diffusion pass, runs the global pass (which removes SynthID
-everywhere), then blends the original face pixels BACK onto the result
-(`invisible_engine.py`: `original_faces = protector.extract_faces(cv_img)`
-before `remove_watermark`, then `protector.restore_faces(out_cv, original_faces)`
-after). Those restored pixels are the original watermarked pixels -- SynthID is
-guaranteed to survive in face regions, not just possibly. The text-protection
-case is at least re-generating (uncertain); face protection is literally
-restoring the original SynthID-bearing pixels.
-
-Both `--protect-text` and `--protect-faces` are therefore **experimental and
-OFF by default**. Enable only when text/face fidelity matters more than
-watermark removal completeness, and always verify the result with the oracle.
+- **Text + structure:** `--pipeline controlnet` (SDXL img2img + a canny ControlNet) is
+  **THE DEFAULT pipeline since 2026-06-09** (`--pipeline default` opts down to plain
+  SDXL img2img for inputs without text/faces). It conditions the regeneration on the
+  edge map, so text and structure stay sharp while every pixel is still regenerated. Text legibility is
+  better than plain img2img at the same strength (text stays readable where plain
+  garbles it). **BUT removal efficacy at the low vendor-adaptive strength is CONTENT ×
+  PIPELINE dependent and NEITHER pipeline clears all content -- oracle-validated
+  2026-06-04 (8 OpenAI images, strength 0.10/0.15, max-res 1536).** The survivors FLIP
+  by content type: **photoreal** (a 9-face grid, a bracelet product photo) SURVIVES
+  controlnet but CLEARS `default`; **flat graphic** (a logo/poster with large flat
+  color fills) SURVIVES `default` but CLEARS controlnet; a flat **text** card cleared
+  under both. Why: controlnet's dense edge map keeps the regen too close to the
+  original on photoreal (so SynthID survives) but freely repaints flat fills (so it
+  clears them); plain img2img at low strength perturbs photoreal texture enough but
+  barely touches flat fills. **Root cause = insufficient STRENGTH, not the pipeline:
+  the vendor-adaptive 0.10 is NOT universally sufficient (the June numbers below held
+  for the content they were measured on). The robust fix is a HIGHER strength,
+  oracle-revalidated per content type (controlnet can be cranked harder without losing
+  structure; a lower `controlnet_conditioning_scale` also frees the regen on
+  photoreal).** So neither `--pipeline controlnet` nor plain `default` is a drop-in
+  removal guarantee at today's strength -- pick by what you must PRESERVE (controlnet
+  for text/structure), then raise strength until the oracle reads clean. (The earlier
+  "reads clean on the oracle" claim held only for the one flat/text-background case it
+  was checked on; it does not generalize.) **UPDATE 2026-06-09: the default strengths
+  were raised and made pipeline-aware (controlnet ladder = the certified
+  0.20/0.30/0.30 floors, applied to BOTH pipelines as a single ladder -- see §5.2 for
+  why one ladder covers plain `sdxl` too) and controlnet is now the default pipeline.
+  The plain-SDXL profile was also renamed `default` -> `sdxl` (`default` stays as an
+  alias). The 0.10/0.15 numbers in this analysis are the PRE-raise values it was
+  measured at. See §5.2.**
+- **Highest-fidelity CUDA option:** `--pipeline qwen-zimage` is the recommended
+  quality mode when preserving face identity matters more than latency, model size,
+  and GPU cost. ControlNet remains the default because it is much cheaper and supports
+  CUDA, XPU, MPS, and CPU, but canny conditioning preserves edges rather than identity.
+  On two direct upstream comparisons, `qwen-zimage` retained substantially more
+  ArcFace identity than polished ControlNet. On 2026-07-25 the exact six-output
+  `visible -> qwen-zimage -> metadata` candidate was negative in the corresponding
+  OpenAI and Gemini oracles. This is a quality recommendation for the measured content,
+  not broad removal certification; very small text can still degrade.
+  See `docs/known-limitations.md` for the metrics, runtime, and validation scope.
+- **Face identity:** canny holds face *structure* but not *identity*. The standard
+  SDXL and ControlNet profiles do not run a separate face-restoration option.
+  Earlier GFPGAN, PhotoMaker, and FaceID experiments were removed after they
+  degraded identity or risked reintroducing source pixels. The separate
+  `qwen-zimage` profile now provides the only shipped face-specific stage:
+  YuNet and SAM locate faces, then Z-Image regenerates the selected original
+  face crops before a feathered composite. See
+  `docs/controlnet-removal-pipeline-research.md` for the historical experiments.
 
 ### 5.2 Strength setting
 
 There is no single permanent correct strength, but the controlled June 2026
 study (section 2.2) gives empirical floors:
 
-- **OpenAI**: 0.05 clears across 1024-1600 (n=4). 0.30 is large overkill here.
+- **OpenAI**: 0.05 clears across 1024-1600 (n=4) -- **but content-dependent, NOT
+  universal.** The follow-up oracle pass (2026-06-04, 8 images) found a flat-graphic
+  OpenAI logo/poster still SynthID-detected after `default` at 0.10, and photoreal
+  images still detected after controlnet at 0.10/0.15: at low strength the
+  low-change regions (large flat fills under `default`, dense edges under controlnet)
+  are not perturbed enough. So the 0.05 floor held only for the n=4 content it was
+  measured on; treat it as a lower bound, not a guarantee, and raise + oracle-recheck
+  per content type (see §5.1 controlnet bullet).
 - **Google (capped 1536)**: 0.15 (n=4); 0.05 and 0.10 do not clear.
 - **Google native 2816**: not locally measured; likely needs >= 0.30 (vendor +
   resolution stack). Use a GPU or `--max-resolution 1536`.
 
 The default is **vendor-adaptive** (`watermark_profiles.resolve_strength` +
-`vendor_for_strength`): the tool reads the C2PA issuer on the original input and
-picks `OPENAI_STRENGTH` 0.10 / `GEMINI_STRENGTH` 0.15 / `UNKNOWN_STRENGTH` 0.15.
-This uses the vendor signal we DO have locally (the C2PA SynthID proxy) to avoid
-the overkill of a single high default on OpenAI images, without needing a local
-pixel detector. An explicit `--strength` always wins. If the watermark still
-survives (e.g. a large native Gemini beyond the capped-1536 validation), raise
-toward 0.30 then 0.35-0.40 (0.40 visibly corrupts dense text), using the lowest
-value that reads clean on the oracle.
+`vendor_for_strength`): the tool reads the C2PA issuer on the original input and picks
+`OPENAI_STRENGTH` 0.10 / `GEMINI_STRENGTH` 0.15 / `UNKNOWN_STRENGTH` 0.15 **(LOWERED
+2026-06-14 from the 2026-06-04 cert floors 0.20/0.30/0.30)**. **The SAME ladder applies
+to both pipelines** (`sdxl` and `controlnet`). The 2026-06-14 re-test on the deployed
+Modal controlnet worker (v0.10.0) cleared SynthID on the oracle at OpenAI 0.10 (2
+photoreal) and Google 0.15 (2 NATIVE 2816x1536, contradicting the "native >= 0.30" guess
+on line above), and a pixel sweep showed 0.20/0.30 over-regenerated for no efficacy gain.
+**This re-opens a genuine tension with the 2026-06-04 pass, which found photoreal STILL
+detected after controlnet at 0.10/0.15 (lines above):** either the v0.10.0 controlnet
+default improved the floor, or n=2 landed on the lucky side of the seed-non-determinism
+(§5.5). So a SERVICE on this ladder MUST pin a fixed, oracle-verified seed (not random),
+and flat-graphic hard cases (NOT in the n=2 re-test) still need a per-content oracle
+recheck -- raise `--strength` there. The prior cert floors are the §5.5 record. Why one ladder
+covers plain `sdxl` too: the certification was run on controlnet and does NOT transfer
+by symmetry (the two pipelines have OPPOSITE hard cases -- controlnet leaves SynthID on
+photoreal, `sdxl` on flat graphics, the §5.1 content-x-pipeline table), BUT on its own
+hard case (flat fills) `sdxl` is the WEAKER remover (plain img2img barely perturbs a
+flat region at low strength), so it needs AT LEAST controlnet's strength -- the
+certified floor is therefore the right floor for `sdxl` too. This is a MARGIN argument
+for `sdxl`, not a separate certification (no local SynthID detector to self-verify).
+The higher strength costs little quality where it matters, because `controlnet` is now
+the default pipeline, so `sdxl` is reached only via an explicit `--pipeline sdxl` (a
+deliberate opt-down), where over-regeneration has no faces/text to damage.
+This uses the vendor signal we DO have locally (the C2PA SynthID proxy) to avoid the
+overkill of a single high default on OpenAI images, without needing a local pixel
+detector. An explicit `--strength` always wins. If the watermark still survives (e.g. a
+large native Gemini beyond the capped-1536 validation), raise toward 0.35-0.40 (0.40
+visibly corrupts dense text), using the lowest value that reads clean on the oracle.
 
 ### 5.3 Test methodology
 
@@ -431,13 +508,106 @@ value that reads clean on the oracle.
   verifier is not the same as being forensically indistinguishable from clean
   content (arXiv:2605.09203).
 
-### 5.4 ctrlregen and img2img: the tradeoff
+### 5.4 Strength vs forensic detectability: the tradeoff
 
-Both the paper and our testing confirm: higher img2img strength removes the
-watermark but introduces detectable regeneration artifacts. The Goonatilake &
-Ateniese paper shows CtrlRegen+ (the most powerful remover) is simultaneously
-the most forensically detectable (AUROC 0.9999). The tradeoff is unavoidable
-with current diffusion-based approaches.
+Higher img2img strength removes the watermark but introduces detectable
+regeneration artifacts. The Goonatilake & Ateniese paper shows the strongest
+diffusion-based removers are simultaneously the most forensically detectable
+(AUROC up to 0.9999). The tradeoff is unavoidable with current diffusion-based
+approaches: defeating the vendor's verifier is not the same as being clean.
+
+### 5.5 Oracle validation log -- 2026-06-04 OpenAI pass
+
+Eight OpenAI `gpt-image` originals run through both pipelines and checked on
+openai.com/verify (the OpenAI SynthID oracle). `--max-resolution 1536`; strength
+is the vendor-adaptive default (`vendor_for_strength`): images with an OpenAI C2PA
+manifest get `OPENAI_STRENGTH` 0.10, the one without C2PA falls to
+`UNKNOWN_STRENGTH` 0.15. "detected" = SynthID still found (removal FAILED);
+"clean" = SynthID not detected.
+
+| image | content type | size | strength | `--auto`/controlnet | `default` |
+|---|---|---|---|---|---|
+| typography card | flat text | 1122x1402 | 0.10 | clean | clean |
+| Flat poster | flat graphic (logo + flat fills) | 1024x1536 | 0.10 | clean | **detected** |
+| 9-face grid | photoreal | 1448x1086 | 0.10 | **detected** | clean |
+| bracelet product photo | photoreal | 1600x1600 | 0.15 | **detected** | clean |
+
+(The other four cleared under both and are omitted.) **Reading:** at this strength
+NEITHER pipeline removes SynthID on all content -- the survivors flip by content
+type. Photoreal survives controlnet / clears `default`; flat graphic survives
+`default` / clears controlnet; flat text clears both.
+
+**Follow-up: removal near the threshold is NON-DETERMINISTIC (seed-dependent).**
+Re-running the two photoreal survivors through controlnet at an explicit
+`--strength 0.15` (`--auto`, same `--max-resolution 1536`) cleared BOTH on the
+oracle (SynthID not detected). But the bracelet had SURVIVED controlnet at the
+SAME 0.15 in the first pass (it was the no-C2PA image, so its vendor-adaptive
+strength was already 0.15) -- same pipeline + strength + resolution, only the
+random (unset) seed differed between runs. So **0.15 is the borderline floor for
+controlnet photoreal, not a robust guarantee**: at the threshold the same
+image+settings can pass or fail run-to-run. img2img runs with `seed=None` (random)
+unless `--seed` is passed, so a removal SERVICE gets a coin-flip near threshold and
+has no local SynthID detector to self-verify.
+
+**Controlnet strength ladder on the two photoreal images (oracle, `--auto`,
+`--max-resolution 1536`):**
+
+| controlnet strength | 9-face grid | bracelet photo |
+|---|---|---|
+| 0.10 | detected | (was 0.15) |
+| 0.15 | clean | **non-deterministic** (survived pass 1, clean pass 2) |
+| **0.20** | **clean** | **clean** |
+
+**Recommended robust controlnet strength = 0.20** (0.05 of margin above the 0.15
+non-deterministic borderline); both photoreal survivors cleared at 0.20. Honest
+caveat: 0.20 is one confirming run WITH margin, not an N-run repeatability proof --
+for a removal service, add a little more margin or validate repeatability, since
+there is no local SynthID detector to self-check. **Implications:** (1) the
+content×pipeline table above conflates a borderline/non-deterministic 0.15 result
+with deterministic content behavior -- the photoreal-survives-controlnet effect is
+solid at 0.10 but at 0.15 it is near-threshold noise; (2) for reliable removal pick
+a strength with MARGIN above the borderline (controlnet >= 0.20), not exactly on
+it; (3) **historical engineering conclusion:** this dated run argued for a
+higher ControlNet strength than the then-current default. That proposal was
+later superseded. The current resolver intentionally shares the 0.10/0.15
+ladder between SDXL and ControlNet and uses a separate Qwen ladder; see
+`noai/watermark_profiles.py`.
+Source images are private (faces / product shots), not committed; reproduce on any
+photoreal + flat-graphic gpt-image pair, varying the seed, and re-checking the
+oracle.
+
+**Gemini pass + the face-restore re-introduction (2026-06-04).** Four Gemini
+originals via the then-current `--auto` ControlNet path at `--max-resolution 1024`,
+checked on the
+Gemini "Verify with SynthID" oracle (Google content needs the Google oracle, not
+openai.com/verify):
+- Most cleared at controlnet 0.15-0.25; `gemini_3` (a large central FACE, +restore)
+  stayed **SynthID-detected at controlnet 0.15, 0.20 AND 0.25** -- raising strength
+  did not crack it.
+- **Root cause was the face-restore pass, not strength/resolution.** `gemini_3` at
+  controlnet 0.20 with `--no-restore-faces` read **SynthID-NOT-detected** (clean
+  A/B, only restore differed). GFPGAN runs on the ORIGINAL watermarked face and at
+  weight 0.5 blends ~half its pixels back, re-introducing SynthID into the
+  composited face over the diffusion-cleaned result (see §5.1 face-identity bullet).
+- (Side note: reducing the processing resolution does NOT weaken SynthID -- it is
+  robust to downscaling by design, and the study's resolution trend says LOWER
+  processing res needs LESS strength, so 1024 was never the wall.)
+
+**Historical controlnet certification, superseded by the current vendor-adaptive
+defaults (isolated GPU sweep + oracle,
+restore OFF, <= 1536, each vendor on its own oracle):** OpenAI **0.20** (2 photoreal x
+seed {1,2,3} = 6/6 clean; the 0.15-flipper is seed-robust at 0.20) and Gemini **0.30**
+(0.20 detected -> 0.30 clean on 2/2 seeds). OpenAI 0.20 transfers to prod
+(resolution-independent); Gemini 0.30 holds only <= 1536 -- Gemini is
+resolution-sensitive, so a native-resolution deployment should cap Gemini <= 1536 + use 0.30 or
+native-calibrate (~0.35+). See `docs/controlnet-removal-pipeline-research.md` for the
+table.
+
+**Current implication:** the old floor table remains evidence about the dated
+test set, not the current resolver. The shipped SDXL and ControlNet defaults are
+defined in `watermark_profiles.py`, and face restoration is available only
+through the separate `qwen-zimage` profile. Removal near a threshold remains
+seed dependent, so reproducible verification requires a fixed seed.
 
 ---
 

docs/text-protection-research.md

@@ -1,5 +1,8 @@
 # Text protection research: crisp text under a "watermark removed everywhere" constraint
 
+> Research archive. This page records evaluated ideas, including rejected
+> prototypes. Current behavior is documented in the user guides and source.
+
 Date: 2026-05-29. Source: a deep-research run (104 agents, 5 search angles, sources
 fetched and 3-vote adversarially verified). Not committed automatically — saved as a
 research note for the next session.

docs/verification-plan.md

@@ -0,0 +1,285 @@
+# Full verification plan
+
+> Verification log and historical plan. Dated results describe the code and
+> datasets at the time of each run. They are evidence for maintainers, not a
+> current CLI contract. Recheck open items against the current code and issue
+> tracker before treating them as work that remains.
+
+How we convince ourselves the library actually works, across its whole surface, on real data.
+
+This is the pre-release and periodic-audit plan. It is deliberately organized by **oracle
+strength** rather than by module, because the hard part is never "call the function" -- it
+is "know what the right answer was". A sweep with no oracle proves only that nothing threw.
+
+Performance depends on format, enabled extras, and hardware. Measure it locally with representative inputs; do not publish private dataset sizes or run statistics.
+
+## Public test sources
+
+| source | role |
+|---|---|
+| `data/synthid/` | labeled SynthID oracle fixtures and evaluation manifest |
+| `data/fixtures/provenance/` | deterministic format and provenance fixtures |
+| `data/calibration/<vendor>/` | minimal controlled inputs used to derive detection silhouettes |
+| synthesized inputs | constructed ground truth for pure and format-level checks |
+
+## Tier A -- self-evident oracles (full corpus, unattended)
+
+Properties that are true or false without anyone labelling anything. These are the
+backbone: they scale to large local datasets and catch regressions with zero human cost.
+
+### A1. Recorded-verdict regression
+
+A dated local cache of `identify` verdicts can be replayed against the same
+inputs to detect drift in verdict, platform, confidence, or signal set.
+
+Caveat that makes this honest: a diff is not automatically a bug -- the sidecars were
+written by older versions, so intended improvements also show up. The output is therefore a
+**classified diff** (new detections / lost detections / changed platform / changed
+confidence), reviewed once, then re-baselined. Lost detections are the alarm.
+
+Implemented as `scripts/sidecar_regression.py` (resumable, ~1.5 h at 8 workers).
+
+#### Local run protocol
+
+Re-run `identify` against locally recorded sidecars, classify losses separately from intended new detections, and keep generated reports under `.local-eval/`. Do not commit dataset-derived counts or identifiers.
+
+### A2. Parity: whatever we detect, we must be able to remove
+
+For every image where a signal fires: remove, re-scan with the same oracle, assert quiet.
+- metadata: `scripts/metadata_removal_audit.py`;
+- visible: `scripts/visible_removal_audit.py`, once per backend.
+
+Detection does not depend on the fill backend. Run `scripts/visible_positives.py` once
+and pass its output through the audit's `--paths-file` option.
+
+#### Local parity protocol
+
+Run detection, removal, and re-detection over a representative local set. Confirm that decoded pixels remain unchanged for metadata-only operations. Keep reports untracked.
+
+### A3. Byte-level invariants
+
+- no-op `remove_visible` returns the ORIGINAL bytes (not a re-encode)
+- pixels outside the fill mask are bit-identical to the input
+- JPEG metadata strip is pixel-lossless on the DEFAULT path (`--remove-all` re-encodes by
+  design -- see `metadata.py`; assert the split, not losslessness everywhere)
+- lossless source formats survive a misnamed extension
+
+### A4. Idempotence and order-independence
+
+- `remove_visible(remove_visible(x)) == remove_visible(x)`
+- `strip(remove(x)) == remove(strip(x))` in signal terms
+- a second `identify` on a cleaned output reports no metadata signals
+
+### A5. Contract sweep across every parameter choice
+
+`scripts/smoke_matrix.py` (exists, 68 rows, 0 skipped with `--diffusion`) covers every
+choice-valued flag on fixtures. Extend from fixtures to a stratified corpus slice
+(~500 images spanning format x provenance x aspect ratio), asserting exit-code semantics
+rather than just absence of crash.
+
+Known trap to encode: **exit 2 is triply overloaded** (no-visible-mark, no-invisible-signal,
+Click usage error). A wrapper cannot distinguish them without parsing stderr. Either the
+sweep asserts on stderr, or the codes get split -- the latter is the better fix.
+
+#### Coverage method
+
+Compare the flags and values exercised by the matrix against the options declared by
+the CLI. Include optional backends, batch modes, tiling, region-targeted composition,
+the ESRGAN upscaler, and the ffmpeg audio/video strip. The gap to find is not only
+"logic untested" but
+"never executed on real data", which is precisely what this campaign is for.
+
+#### Bug found by the extension: `--steps` below ~7 crashes inside torch
+
+Effective timesteps are `int(steps * strength)`. At the vendor-adaptive default strength
+(0.15, or 0.10 for OpenAI) any `--steps` under 7 rounds to **zero**, and the pipeline dies
+with a raw traceback:
+
+```
+$ remove-ai-watermarks invisible img.png --steps 5
+RuntimeError: cannot reshape tensor of 0 elements into shape [0, -1, 1, 512]
+```
+
+Fully valid CLI arguments, no special flags, no `--force`. The value is accepted, the
+crash is a torch internal, and nothing tells the user that steps and strength interact.
+Fix is either a clamp to >=1 effective step or an up-front validation naming both values.
+
+Method note: the first run of the knob rows failed 12 times with this identical error,
+which read like twelve broken features. It was one bad harness parameter (`--steps 4`)
+sitting on top of one real bug. An error that is IDENTICAL across unrelated rows is
+evidence of a common cause, not of many faults -- check the shared input first.
+
+## Tier B -- constructed ground truth (automatable, no labelling)
+
+Where reality gives no answer key, build one. This is the tier that closes the two biggest
+holes: fill quality and detector response at the edge of the operating range.
+
+### B1. Fill quality with a true reference
+
+Real marks have no clean counterpart, so quality has only ever been eyeballed. Construct it
+instead: take a clean corpus image, stamp a known mark at a known position (the captured
+alpha maps make this exact), remove it, and compare against the **true original**.
+
+Yields PSNR / SSIM per `--backend` (cv2 / migan / lama), sliced by background class, which
+is exactly the axis where the docs say quality varies but no number exists.
+
+Implemented as `scripts/fill_quality.py`. Two reporting rules are load-bearing: score
+INSIDE the footprint (whole-frame PSNR sits near 60 dB whatever the backend does), and use
+the MEDIAN (a fill that reproduces a flat background exactly scores PSNR=inf, and one inf
+makes a mean inf -- the first run reported "+inf" for every flat bucket).
+
+#### Local fill-quality protocol
+
+Construct marked images from clean local references, compare each backend against the known original inside the affected footprint, and keep the report under `.local-eval/`.
+
+### B2. Detector response curves
+
+Use `scripts/detector_response.py` to sweep mark size, opacity, background, and aspect. Report detection and maskability separately. Generated reports stay under `.local-eval/`.
+
+### B3. Invisible round-trip, positive-control gated
+
+The open DWT-DCT detector is positive-only and carrier-fragile: "not found" on a fragile
+carrier proves nothing (measured: `chatgpt-1.png` recovers 114/128, below the 118 gate).
+Every invisible assertion must first embed on the SAME carrier and confirm recovery, and
+**degrade to a skip rather than a pass** when the control fails. Already implemented in
+`smoke_matrix.py`; apply the same discipline anywhere else this detector is used.
+
+### B4. Resource ceilings
+
+Peak RSS and wall time per backend x input size, up to 25 MP. The memory-constrained CPU
+tier is a real constraint (MI-GAN must stay ~0.6-0.9 GB by cropping around the mask); a
+regression here is invisible today and would only surface under load.
+
+## Tier C -- human-labelled accuracy (bounded by labelling effort)
+
+The machinery exists: `visible_recall_sample.py` -> `visible_sheets.py` ->
+`visible_groundtruth.py` -> `visible_eval.py`.
+
+- **Recall** needs representative sampling per mark and aspect ratio.
+- **Precision** must be benchmarked before and after every detector change with
+  `--vs <snapshot>`.
+- **Coverage** is separate from tuning. A missing vendor detector cannot be repaired by
+  changing another detector's threshold.
+
+Three harness rules are load-bearing and must not be relaxed: score a mark only within its
+crop's adjudication scope; take provenance from metadata, never from labels; and never
+report recall from the detector-sampled set.
+
+## Tier D -- external oracles (manual, not automatable here)
+
+SynthID removal cannot be verified locally by design -- no public decoder exists. Each
+vendor has its own oracle and it covers only that vendor's content: `openai.com/verify` for
+OpenAI (more accessible, the automation candidate), the Gemini app for Google (manual,
+rate-limited). A quiet metadata proxy is **not** proof the pixel watermark is gone.
+
+Scope honestly: this tier certifies strength floors on a handful of images per vendor, and
+that is all it can do. See `docs/synthid.md`.
+
+### D1. Sampling frame
+
+Select a representative local sample without committing images, identifiers, dataset sizes, or oracle results. Stratify by signal family and preserve the sampling method outside the public repository.
+
+### D2. The oracle is the bottleneck, not the GPU
+
+Measured on MPS (2026-07-19), single invocation of `invisible`:
+
+| `--max-resolution` | 256 | 384 | 512 | 768 | 1024 |
+|---|---|---|---|---|---|
+| wall time | 37.9 s | 58.9 s | 59.4 s | 65.2 s | 118.3 s |
+
+384/512/768 are indistinguishable, so below ~768 the cost is dominated by **fixed model
+load, not diffusion**. Confirmed by batching: 4 images in one process took 105.5 s
+(26.4 s/image) against 59.4 s/image one at a time -- roughly 40 s fixed overhead per
+invocation and ~15 s marginal per image at 512 (rough: run-to-run variance is large).
+
+Two consequences for the harness:
+- **Amortize the fixed cost**: one long-lived process over many images, never one
+  invocation per image. That is a 2-4x win. Shrinking below 512 is not.
+- The binding constraint is the **external oracle's throughput**, which is manual and rate
+  limited. So do not run a uniform grid; spend each oracle check where the answer is
+  uncertain -- **bisect strength per content class** to certify a floor in ~10 checks
+  instead of ~100.
+
+### D3. Mandatory control before trusting any reduced-size run
+
+`--max-resolution` is downscale -> diffuse -> Lanczos upscale. If the **resize round trip
+alone** damages SynthID, the oracle goes quiet for a reason unrelated to removal and the
+result does not transfer to production at native resolution.
+
+Before any reduced-size sweep, run the resize round trip with **no diffusion** and put the
+result through the vendor oracle. If the watermark survives, the reduced size is a valid
+test bed; if it does not, reduced-size results are measuring the resizer. This is the same
+failure shape as the imwatermark carrier-fragility trap in B3: an oracle that falls silent
+for the wrong reason reads exactly like success.
+
+`docs/synthid.md` cites ~99.98% TPR across 30 transforms including resize, which predicts
+the control passes -- but that is Google's claim about their own decoder, not our
+measurement, so it is a hypothesis to test, not a reason to skip the control.
+
+## Tier E -- robustness and adversarial inputs
+
+Malformed and hostile inputs, including truncated files:
+at many offsets, corrupt headers, 16-bit and CMYK, absurd dimensions, decompression bombs,
+zero-byte files, unicode and RTL filenames, symlinks, read-only output dirs, concurrent runs
+on one file. The bar is never "handles it" but **never raises and never silently degrades**.
+
+## Build order
+
+1. **A1 sidecar regression** -- highest value per hour, unattended, needs no new labels.
+2. **A2/A3/A4 parity and invariants** -- representative local set, reusing existing audit scripts.
+3. **B1 fill quality** -- closes the oldest unmeasured claim in the project.
+4. **B2 detector curves** -- cheap, and directly guards the geometry class of bug.
+5. **A5 contract sweep over a representative local set**.
+6. **B4 resource ceilings**, **E robustness**.
+7. **C recall expansion** -- gated by labelling appetite.
+8. **D oracles** -- manual, per release.
+
+Every tier writes a versioned snapshot so runs are comparable over time; a run that cannot
+be diffed against the last one is a one-off, not a regression suite.
+
+## What the measurements imply for detection work
+
+Recorded here because each item is grounded in a number from this campaign, not because
+it is a prioritized plan (that lives elsewhere -- see the note at the end of this section).
+
+### Metadata absence does not disable the detectors -- it disables the RELAXATION
+
+The detectors are pixel-based and need no metadata. What metadata does is relax the
+false-positive gate (`auto` vs `strict`). So "work better without metadata" means
+strengthening the strict-path detectors themselves; it is not a gating problem.
+
+Per mark, what actually goes away when metadata is stripped:
+
+- **The pill loses its metadata-confirmed arm.** Without metadata it depends on the
+  bottom-right Jimeng wordmark.
+- **The sparkle already runs on pixels.** Its threshold remains a deliberate
+  recall-versus-precision trade.
+- **Uncovered vendors are metadata-independent gaps.** They require a detector of their
+  own.
+
+### Where the evidence points
+
+1. Prefer per-vendor CJK templates when fitted geometry separates similar marks.
+2. Recalibrate every detector when changing its front-end. Thresholds do not transfer
+   between `binary`, `tophat`, and `gray`.
+3. Treat the Jimeng wordmark as a load-bearing confirmation path for the pill.
+
+### Measure before improving
+
+Use Tier B2 detector-response curves before tuning a detector with sparse labelled
+examples. Sweep size, contrast, aspect, and background texture so geometry regressions
+are visible without exposing private evaluation statistics.
+
+This section records what the measurements imply technically. Prioritization is tracked
+separately, outside this repo.
+
+## Local end-to-end verification
+
+Run `scripts/real_examples_e2e.py` against representative local inputs before releases that affect image handling. The script must read from `.local-eval/`, write only untracked temporary output, and report behavior without exposing dataset provenance or aggregate private measurements.
+
+## Standing gap
+
+None of this is in `maintain.sh`, and it should not all be -- the sweeps take hours. But
+that means **no detector-accuracy or CLI-contract regression is caught automatically**
+today. The endpoint of this plan is a cheap subset (fixtures-only smoke + a sidecar diff on
+a fixed 500-image slice) that CI can run, with the full sweeps staying pre-release.

docs/watermarking-landscape.md

@@ -0,0 +1,108 @@
+# Watermarking landscape (research 2026-05-24)
+
+> Research and signal inventory. Code-facing statements are updated with the
+> implementation; dated vendor observations remain snapshots and may change
+> independently of the package.
+
+Who embeds what, and whether it is locally detectable (so we know which gaps are fillable). See `identify.py` for what we read.
+- **Locally detectable (open decoder, no key/API):** Stable Diffusion / SDXL / FLUX via `imwatermark` DWT-DCT (now covered by `invisible_watermark.py`). FLUX uses the same library (upstream `black-forest-labs/flux2`, file `src/flux2/watermark.py`, 48-bit `0b001010101111111010000111100111001111010100101110`); SDXL is the diffusers `WATERMARK_MESSAGE` (`0b101100111110110010010000011110111011000110011110`). **Caveat: the `imwatermark` dwtDct decode is carrier-fragile on a broad class of real images, NOT just re-encode-fragile, and it is a POSITIVE-ONLY signal.** A clean encode->decode round-trip (no re-encode at all) recovers 48/48 bits on some carriers (random noise, chatgpt-1.png 48/48, firefly-1.png 45/48) but FAILS on many others — verified 2026-06-19 that a *known-embedded* watermark only round-trips 28-39/48 (below the safe `_MATCH_48` = 44 gate, random baseline ~24) on the FLUX fox sample (28), doubao-1.png (39), a 1024² minimalist-flat FLUX image (28), AND a **clean synthetic bright-flat fill with NO watermark at all (28)**. The failure does NOT track texture (firefly lapvar ~11 passes; the flat FLUX lapvar ~56 fails); it correlates with a degenerate decode where the raw bits read **all-ones (48/48 ones)** — which a clean synthetic image reproduces, so **all-ones is a CARRIER ARTIFACT, NOT a watermark signal** (a double-embed test also showed a pre-existing embed does not corrupt a second embed — no interference). Net: trust a `detect_invisible_watermark` hit, but treat a `None`/no-match as **inconclusive** whenever a positive-control embed on the same carrier does not first recover >=44/48. The 44 gate is a deliberate precision choice (lowering it would admit false positives).
+
+  **Root cause and external confirmation (deep-research 2026-06-19, adversarially verified).** This is the SCHEME's ceiling, not our usage — there is no better decoder to adopt. The imwatermark maintainers state verbatim (both the ShieldMnt and Stability-AI READMEs) that the algorithm "cannot guarantee to decode the original watermarks 100% accurately even though we don't apply any attack." Independent measurement (WMAdapter, arXiv:2406.08337 Table 2) puts dwtDct at only **~0.79 bit accuracy on CLEAN images (~38/48 bits — already below our 44 gate)**, collapsing to ~0.50 (chance) under crop/JPEG. Two code-verified + locally-reproduced mechanisms drive the content-dependent failures: (1) the decoder reads each bit as the **highest-magnitude DCT coefficient per block**, so any content coefficient exceeding the encoded target flips the bit; (2) the default embed is in the **YUV chroma channel, which 8-bit-clamps on white/bright pixels** (a +36 chroma delta survives a white-fill round-trip as only +4, ~89% loss) — this is the mechanism behind the bright-flat / minimalist failures and the all-ones degenerate decode. No maintained fork or detector decodes this scheme reliably: the WAVES benchmark (arXiv:2401.08573) relegates DWT-DCT to supplementary appendix G.5 and targets Stable Signature / Tree-Ring / StegaStamp instead; learned encoder/decoder schemes reach ~0.98-0.99 clean but are a DIFFERENT watermark class (not what SDXL/FLUX stamp). `dwtDctSvd` does not help (SDXL embeds `dwtDct`; dwtDctSvd cannot decode it, and its clean accuracy ~0.72 is lower). **Authoritative conclusion: the open DWT-DCT mark cannot be turned from positive-only into a reliable real-world detector; keep it positive-only and rely on C2PA.** (Refuted along the way: that the library is unmaintained, and that it is robust to JPEG but only fails on geometric attacks — both did not survive verification.)
+
+  Consequence for the FLUX hosted-output question (BFL Playground, FLUX.2 [pro] + FLUX.1 [dev], 2026-06-19): all samples carry the signed C2PA manifest (issuer "Black Forest Labs"); the open DWT-DCT decode returned `None`, but every available FLUX carrier (textured fox AND a minimalist-flat generation) failed the positive control (28/48), so the detector is blind on them and **whether BFL hosted output embeds the open pixel watermark is UNRESOLVED** (an earlier note here wrongly asserted it absent — overstated; a later note blamed "high texture" — also wrong, flat carriers fail too). What IS established: C2PA is the reliable FLUX identifier; the `_BITS_48` pattern is correct (round-trips on chatgpt/firefly/random). Resolving the hosted question needs a hosted FLUX carrier that first passes a >=44/48 positive control, which neither a textured nor a flat prompt produced — low priority (the open mark is only a stripped-metadata fallback).
+- **C2PA / IPTC (covered by the issuer/marker scan):** OpenAI, Google, Adobe Firefly, Microsoft (Designer + **Bing Image Creator** — collected 2026-05-24; Bing now runs Microsoft's own **MAI-Image** model, signs C2PA as "Microsoft", NOT OpenAI/DALL-E), **Stability AI** (collected from Brand Studio / DreamStudio successor; signs C2PA as "Stability AI Ltd", no SynthID, no imwatermark on its current Stable Image model — issuer added to `C2PA_ISSUERS`), and **Canva** (Magic Media signs C2PA as "Canva" + `trainedAlgorithmicMedia` with a generic `c2pa-rs` claim generator, no SynthID — issuer `b"Canva"` → "Canva (Magic Media)"; verified samples disproved the earlier assumption that Canva downloads always strip C2PA). Still unsampled: Getty, Shutterstock. Midjourney embeds NO C2PA and no invisible watermark (our `mj-*` sample carried only the IPTC tag).
+
+**Samsung Galaxy AI** signs supported edits with C2PA and may carry the
+proprietary `genAIType` marker. The registered visible detector covers the
+Italian `✦ Contenuti generati dall'AI` bottom-left variant. Removal follows the
+same localize-then-fill path as other registered text marks. Other locales and
+icon-only variants need separate calibrated silhouettes.
+
+**ASUS Gallery** also signs edited photos as C2PA (`com.asus.gallery`) but with no AI source type — a signer, not an AI marker.
+
+**Black Forest Labs (FLUX)** API output signs C2PA: `claim_generator_info "Black Forest Labs API"` + a `c2pa.ai_generated_content` assertion + `trainedAlgorithmicMedia` (issuer `b"Black Forest Labs"` added to `C2PA_ISSUERS`, platform "Black Forest Labs (FLUX)").
+
+**ByteDance Volcano Engine (Volcengine)** — the cloud behind Doubao / Jimeng — signs its AI image output with a cert from `certificate_center@volcengine.com` + `trainedAlgorithmicMedia` (issuer `b"volcengine"` → "ByteDance (Volcano Engine)", platform "ByteDance (Doubao / Jimeng / Volcano Engine)"); note this is the C2PA-signed surface, distinct from the XMP/PNG TC260 `AIGC` label Doubao also uses. ByteDance's **international brand (BytePlus / Seedream / Seededit)** signs the same content as **"Byteplus Pte. Ltd."**. The bare `volcengine` needle missed it, so BytePlus output was mis-attributed to "Adobe Firefly" through an incidental "Adobe XMP" toolkit string. Issuer `b"Byteplus"` now maps directly to "BytePlus (ByteDance)". ByteDance's consumer app **Dreamina** (the international Jimeng brand) signs as **"Bytedance Pte. Ltd."** with a `Dreamina/x.y` claim generator but, unlike the Volcano Engine surface, ships **no `trainedAlgorithmicMedia`**. Issuer `b"Dreamina"` maps to "ByteDance (Dreamina)" with **`asserts_ai=True`**. Registering the broader **issuer** `b"Bytedance Pte"` was deliberately avoided because that same entity also signs non-AI CapCut edits; keying on the `Dreamina` generator token is precise.
+- **EXIF/XMP/PNG-text generator tag (caught by `exif_generator`):** **Ideogram** writes EXIF `Make="Ideogram AI"` (collected 2026-05-24 — no C2PA, no SynthID, no imwatermark; the Make tag is the only signal). Additional verified generator stamps include **NovelAI** (`Software`, `Source`, and `Title` PNG text chunks), **Reve** (`Software` or XMP `CreatorTool` = `reve.com`), and **Aphrodite AI** (`Make` or `Software` = `Aphrodite AI`).
+- **xAI / Grok — its own EXIF signature scheme, NOT C2PA (DETECTED by `metadata.xai_signature`, built 2026-05-26).**
+
+Grok JPEG downloads (Aurora model) carry **no C2PA, no XMP, no SynthID, no IPTC** — only EXIF `Artist` = a UUID and EXIF `ImageDescription` = `Signature: <base64>` (a crypto signature, unverifiable locally without xAI's public key). This empirically kills the earlier unverified "xAI signs C2PA as xAI" lead — xAI is not even a C2PA member. `exif_generator` misses it (neither field holds an `AI_GENERATOR_TOKENS` token), so a dedicated detector `xai_signature(path)` matches the pair (`ImageDescription ~ ^Signature: [A-Za-z0-9+/=]{64,}` AND UUID `Artist`); wired into `has_ai_metadata`, `get_ai_metadata` (key `xai_signature`), and `identify` (signal `xai_signature`, platform "xAI (Grok / Aurora)").
+
+**Format confirmed stable across n=3 genuine generations:** exactly three EXIF tags (`Artist`, `ExifOffset`, `ImageDescription`), `Signature:` prefix constant, base64 payload 300-1004 chars. Two capture facts: (a) the `Artist` UUID **equals the public image id** in the asset URL (`https://imagine-public.x.ai/imagine-public/images/<uuid>.jpg`), so it is NOT a private per-user secret — only the `Signature` blob is; (b) the Grok web-UI image is a re-encoded **WebP with no signature** — the EXIF survives only in the *original* JPEG (download button or that public tokenless URL), which is why screenshots / re-encodes are metadata-stripped. A real fixture `data/fixtures/provenance/grok-1.jpg` plus **synthetic** JPEG fixtures (fake UUID + fake `Signature:` blob) cover the detector; never add a real Grok image carrying private content (the repo is public).
+
+**Stripped on removal too:** `remove_ai_metadata` calls `_scrub_ai_exif` on
+JPEG EXIF, which deletes the xAI Signature and UUID Artist pair plus supported
+AI generator values while retaining unrelated camera and editor EXIF. The
+shared `xai_signature_pair` helper is the single source of truth for the
+pair. On the ISOBMFF path, `blank_ai_exif_tokens` provides the corresponding
+in-place scrub for supported EXIF values, TC260 AIGC blocks, and the xAI pair.
+- **China TC260 AIGC label (caught by `AIGC_MARKERS` / `metadata.aigc_label`, surfaced by `identify` as the `aigc` signal):** China-served generators embed an XMP `<TC260:AIGC>{"Label":"1","ContentProducer":...}` block — China's mandatory AI-content labeling (TC260 namespace `tc260.org.cn/ns/AIGC`).
+
+**Doubao** (ByteDance) uses it (verified on a public issue sample; `ContentProducer` `001191110102MACQD9K64010000`, no C2PA/SynthID/imwatermark — the XMP block is the only signal; GitHub attachment upload did NOT strip it). The same standard is mandatory for Jimeng/Kling/Qwen/Ernie etc., so the one marker covers the whole China-AIGC-labeled ecosystem. `aigc_label` reads **four serializations** through a shared `_parse` helper: the HTML-entity-encoded XMP `TC260:AIGC` block in **either RDF form** — the nested element `<TC260:AIGC>{...}</TC260:AIGC>` (Doubao) or the attribute `TC260:AIGC="{...}"` (**PicWish**, `ContentProducer="picwish"`, verified on compatible samples) — via a container-agnostic raw-byte scan (any JSON object accepted), a raw-JSON PNG `AIGC` tEXt chunk (Doubao also writes the label this way, no namespaced marker at all — confirmed on compatible samples, `ContentProducer="doubao"`), a bare raw-JSON `{"AIGC":{...}}` object embedded in **JPEG EXIF (UserComment)** by some China-served generators, brace-matched from the scan head with `json.JSONDecoder().raw_decode` (no namespaced marker, no PNG chunk — confirmed on compatible samples, `ContentProducer="001191440300708461136T1308L"`), **and** a bare `AIGC{...}` blob (the label glued straight to its JSON, no `"AIGC":` key wrapper) embedded in a **JPEG APP segment near the JFIF header** — confirmed on compatible samples. The two raw-JSON forms are scanned in one loop (`'"AIGC"'` then `AIGC{`) that **falls through on a non-TC260 / undecodable hit instead of returning** — a quoted `"AIGC"` can appear later in an XMP packet while the real label is a bare `AIGC{...}` earlier in the file, so an unconditional early return on the quoted form would shadow the bare form (the exact bug behind the 06-10 misses). All three generic forms (the PNG chunk, the bare `{"AIGC":...}` object, and the bare `AIGC{...}` blob) are gated on at least one TC260 field (`_TC260_FIELDS`) so a generic `AIGC` key cannot false-positive; the namespaced XMP element is unambiguous and needs no gate. `_TC260_FIELDS` covers **two schemas**: the producer-side one (`Label` / `ContentProducer` / `ProduceID` / `ContentPropagator` / `PropagateID`, Doubao and most China gens) and the **service-provider** one (`ServiceProvider` / `ServiceUser`, plus generic `Time` / `ContentId` which are NOT gated on) — **Tencent Cloud's** AIGC variant (`ServiceProvider` = `腾讯云`), embedded in **EXIF `ImageDescription`**, verified on compatible samples. In `identify`, `aigc` fires on the parsed label **or** the `AIGC_MARKERS` byte scan (the latter preserves the laundering-tell case where the JSON payload is truncated).
+- **HuggingFace-hosted job (caught by `metadata.huggingface_job`, surfaced by `identify` as the `hf_job` signal, MEDIUM confidence):** HuggingFace Jobs / Spaces can stamp generated PNGs with an `hf-job-id` tEXt chunk holding the job UUID. It marks the *hosting job*, not a model, so it lifts an Unknown verdict to a tentative AI via `hf_only` but never overrides a hard metadata signal. `_HF_JOB_CAVEAT` states the limit. Removal drops the chunk through the PNG metadata whitelist.
+- **No detectable signal on some downloads:** Recraft exports and some hosted
+  FLUX surfaces can arrive without a supported local signal. Midjourney samples
+  may carry IPTC metadata but no registered C2PA or pixel watermark. The open
+  DWT-DCT decoder only applies when the producing pipeline actually ran its
+  encoder and the carrier remains decodable.
+- **Invisible but NOT locally detectable (proprietary, API/oracle only — same wall as SynthID):** Amazon Titan Image Generator + Nova Canvas (Bedrock `DetectGeneratedContent` API), Kakao (new SynthID image adopter, May 2026), NVIDIA Cosmos (SynthID video). No local detector possible; treat like SynthID.
+- **C2PA 2.4 "Durable Content Credentials" (April 2026; verified against the spec) raise the bar for metadata stripping.** 2.4 defines soft bindings (an invisible watermark or a content fingerprint) plus a server-side manifest repository and a new `c2pa.repository-receipt` assertion. Per the spec: "if a C2PA manifest is removed from an asset, but a copy of that manifest remains in a provenance store elsewhere, the manifest and asset may be matched using available soft bindings." So our local `metadata --remove` deletes the *embedded* manifest, but a fingerprint/watermark soft binding can still re-link the image to its manifest in a repository server-side. Stripping the file is becoming necessary-but-not-sufficient against durable provenance. (Our parsers target the stable embedded-manifest format documented in C2PA 2.1 §11; that format is unchanged in 2.4 -- the new pieces are repository/soft-binding infra, not the on-file box layout, so no parser change is implied.) Spec: https://spec.c2pa.org/specifications/specifications/2.4/specs/C2PA_Specification.html We now READ the soft-binding `alg` (`C2PA_SOFT_BINDINGS` / `soft_binding_vendors_in`) to name the forensic-watermark vendor, and locally DECODE the one open scheme, Adobe TrustMark (`trustmark_detector`); the rest (Digimarc/Imatag/Steg.AI/...) stay name-only (proprietary decoders).
+- **Built in the dated batch:** soft-binding vendor detection, IPTC Photo
+  Metadata AI-disclosure fields, C2PA detection and stripping for supported
+  ISOBMFF video, and the optional Adobe TrustMark decoder. Visible video-logo
+  removal and proprietary audio-watermark detection remain outside the package.
+  Metadata stripping for supported audio containers is a separate implemented
+  path.
+
+**Box detection window — now handled (v0.6.8):** detection no longer relies on a fixed first-MB read. `metadata.scan_head(path, size)` reads the first `size` bytes and, for ISOBMFF, appends the payloads of late provenance boxes found by `isobmff.scan_c2pa_region` (a file-seeking top-level box walker that skips past `mdat` by size without reading it), so a C2PA/AIGC/IPTC manifest placed AFTER a large `mdat` in a streaming/non-faststart MP4 is now caught. Every C2PA/marker byte scan (`has_ai_metadata`, `aigc_label`, `iptc_ai_system`, `synthid_source`, `exif_generator` XMP, `get_ai_metadata` soft-binding, and `identify`) goes through `scan_head`; it is behavior-neutral for non-ISOBMFF inputs (exactly `f.read(size)`).
+
+**Meta-box XMP and EXIF removal are handled in place:** an AI-label XMP packet
+stored as a meta-box `mime` item is blanked by
+`isobmff.blank_ai_xmp_packets`. Supported EXIF items are handled by
+`blank_ai_exif_tokens`. Both paths preserve box sizes and coded media offsets.
+
+For current scope and legal context, see
+[scope, safety, and legal notes](legal-and-safety.md). Re-verify legal facts
+against primary sources before adding jurisdiction-specific claims.
+
+## Visible AI-generation marks + detection methods (deep-research 2026-07-10, adversarially verified)
+
+**Google Gemini visible "sparkle" -- tier-dependent, and spec-undocumented by Google.** Google primary sources (the Nano Banana Pro blog and the gemini.google image-generation page, both WebFetch-verified) confirm Gemini images carry BOTH the invisible SynthID (on ALL Google-AI media) AND a visible sparkle, but the visible mark is **tier-gated**: applied for FREE and Google AI **Pro** users, and **REMOVED** for Google AI **Ultra** subscribers, inside **Google AI Studio**, and on **API / dev** output. So a Google-C2PA image with NO visible sparkle is expected (Ultra / API), not evidence it is clean -- this reinforces the `identify` "no visible mark != clean" rule. The ONLY official verifier is the SynthID flow (upload to the Gemini app, ask if it is AI-generated), which reads the INVISIBLE mark; there is **no official visible-sparkle detector**, and Google publishes **no** glyph geometry / size / opacity / color / locale / placement spec. So our capture-based sparkle template is the only source of truth and cannot be validated against a vendor spec -- keep reverse-engineering from real captures (do not expect a published spec).
+
+**The faint-visible-mark precision/recall wall is fundamental, not a heuristic artifact.** The visible-watermark-detection literature has moved to LEARNED segmentation / object-detection (WDNet WACV'21 arXiv:2012.07616; SLBR ACM MM'21, open code+weights; the PRCV'18 large-scale detector; Su et al. survey 2025), but three verified findings bound what a learned detector actually buys: (1) a claim that a confidence threshold "cleanly separates" true from false matches even with a learned CNN front-end was **REFUTED** in verification (arXiv:1705.08593) -- the precision/recall wall persists even with learned features. (2) Learned detectors need a LARGE, pattern-diverse labeled dataset trained on synthetic composites (PRCV'18: 60k images / 80 watermark classes; CLWD: 60k / 160 marks), and off-distribution degradation is a documented real axis (models trained on limited-pattern LVW transfer worse; diversity of training patterns drives generalization). (3) Inference is cheap (WDNet ~8 ms at 256x256) -- the cost is the data pipeline, not runtime. Net: a learned detector shifts the frontier but does NOT remove the wall; for a SINGLE mark the cheapest next step is a small patch classifier (real-sparkle vs false-positive) on top of the existing NCC localizer, not a full segmentation model. SLBR is a ready baseline. The current NCC + false-positive gate (core-ring brightness margin + gradient-NCC crispness + white-core saturation) is a sound operating point, and the residual miss is the information-theoretic wall the literature confirms.
+
+**Visible-mark landscape beyond the registry.** Meta stamps a visible "Imagined with AI" mark (bottom-LEFT, a small symbol) on its OWN Meta AI / "Imagine" output; for third-party images it relies on C2PA / IPTC, not a visible mark. Samsung Galaxy AI additionally uses a **four-star icon** variant in a corner alongside the localized text wordmark `samsung_engine` calibrates (only the Italian text variant is covered) -- the icon is a distinct, uncovered variant. Every source agrees visible + metadata marks are trivially removable (crop / screenshot, ~2 s), which is the tool's premise.
+
+**Regulatory driver -- China GB 45438-2025 is the strongest VISIBLE-mark mandate.** The CAC / TC260 "Measures for Labeling AI-Generated Synthesized Content" (issued March 2025, **effective 2025-09-01**, technical standard **GB 45438-2025**, building on the TC260 Aug-2023 practice guide) MANDATE a **visible** label for AI images -- a visible textual mark whose height must be **>= 5% of the image's shortest side** -- plus the metadata (implicit) label. Several such CJK text marks are now registered; see [supported signals](supported-signals.md) for the current list. By contrast EU AI Act Article 50 mandates only the MACHINE-READABLE mark (enforceable 2026-08-02, grace to 2026-12-02); a visible label is proposed and modality-specific (visible for images) but is NOT a hard "fixed icon" mandate -- a claim that Art 50 requires a clearly-visible fixed icon for images was refuted in verification. Primary-source dates verified against the article/standard text, not search summaries.
+
+## Uncovered visible marks: implementation specs (deep-research 2026-07-18)
+
+Compatibility testing showed that TC260-labelled images can still produce no visible-mark
+detection. The main causes were a fixed Doubao localization defect and genuinely
+uncovered vendors. Verification status is labelled per claim; treat (b)/(c) as leads,
+not ground truth.
+
+**GB 45438-2025 clause 5.2, the binding constraint for every Chinese mark (VERIFIED (a) -- full standard text extracted from the TC260-hosted PDF).** Verbatim requirements for an image's explicit label:
+- 应采用文字提示 (must be a TEXT prompt);
+- must contain BOTH an AI element (`人工智能` or `AI`) AND a generation element (`生成` and/or `合成`);
+- 应位于图片的边或角 -- **edge OR corner**, so bottom-right is NOT mandated (Annex C.2's bottom-right figure is a non-normative example);
+- 字型应清晰可辨 (legible typeface -- no family named);
+- **文字高度不应低于画面最短边长度的 5%** -- glyph HEIGHT >= 5% of the frame's SHORTEST side, with a note defining the shortest side for non-rectangular images.
+
+Two consequences we can exploit: (1) the 5% floor is a **scale prior** -- a compliant CN mark's glyphs are large (>= 51 px on a 1024² image), so a CN silhouette ladder can be anchored at ~5-10% of the short side instead of swept broadly, which should cut false fires; (2) every compliant string shares the tail `AI生成` / `AI合成`, so a shared suffix silhouette plus a per-vendor prefix may beat five independent templates. NOT established: whether 文字高度 means cap height, em box, or rendered bounding box (a ~1.3x spread in template scale). Sources: `https://www.tc260.org.cn/upload/2025-03-15/1742009439794081593.pdf`, parent CAC measure `https://www.cac.gov.cn/2025-03/14/c_1743654684782215.htm` (the CAC text itself specifies no size or corner).
+
+**Alibaba Qwen -- two surfaces that differ (API tier VERIFIED (a)).** Model Studio docs state verbatim that the API adds a `Qwen-Image` watermark 在图像右下角 and 默认值为 false -- so API output is **unwatermarked by default**, and when enabled the mark is a LATIN wordmark, not CJK, and not GB-compliant in wording. The consumer app's `千问AI生成` (bottom-right) is (b) secondary only -- no Alibaba primary page states it. So Qwen needs TWO templates, and its absence is never evidence of a clean image. Source: `https://help.aliyun.com/zh/model-studio/qwen-image-api`.
+
+**星绘 is ByteDance (VERIFIED (a): Baidu Baike + App Store listing, now branded 豆包旗下, team folded into Doubao April 2025).** So `星绘AI生成` is very likely the Doubao house style -- same typeface, same corner, possibly the same top-left `AI生成` pill. Starting from the Doubao `TextMarkConfig` and swapping the two lead glyphs is the cheap path. String/position themselves are (c) inferred.
+
+**Baidu: RESOLVED 2026-07-22, registered (`baidu_engine.py`).** The mark is a white bold "百度" text run + a separate white rounded tag with dark "AI生成", bottom-right -- settled by the TC260 USCC cohort harvest (16 frames, USCC 91110000802100433B), not by web research. Detection keys on the text run only; details in `docs/module-internals.md`.
+
+**Tencent Yuanbao: RESOLVED 2026-07-25, registered (`yuanbao_engine.py`).** The standard mark is a compact two-line italic `元宝` over `AI生成` block at bottom-right. It switches between light and dark strokes with the scene, so detection uses polarity-independent local contrast rather than a white top-hat. The separate one-line overlay variant remains evidence-limited to one example.
+
+**Meta `Imagined with AI` (string VERIFIED (a) from Meta's own newsroom; POSITION NOT VERIFIED).** Sources conflict on placement. Do not encode a corner without a verified sample. `identify` reads the supported IPTC disclosure; it does not decode Meta's proprietary invisible watermark. Source: `https://about.fb.com/news/2024/02/labeling-ai-generated-images-on-facebook-instagram-and-threads/`.
+
+**Samsung English/other locales: still not established.** Samsung's own support page says only that "A Galaxy AI watermark will appear on AI-generated images" -- no string, no corner. Every community thread carrying the exact English string returned HTTP 403 to WebFetch, so the search paraphrase (bottom-left) is deliberately NOT recorded as fact. Feature-tier detail (b): the mark is applied by Generative Edit / sketch-to-image but reportedly NOT by Object Eraser, so Samsung absence is feature-dependent. The four-star icon variant: nothing found.
+
+**The one document that would settle ByteDance placement is BLOCKED.** Douyin's 《抖音关于人工智能生成内容标识的水印与元数据规范》 aims to give AI tools a unified watermark style and position, which would cover Doubao / Jimeng / 星绘 at once. Both mirrors return HTTP 403 to WebFetch; a secondary report (b, unconfirmed) says the watermark is `AI生成` + tool name + company name placed **top-left** -- which would explain the Jimeng pill's top-left position but contradicts the GB annex's bottom-right example. Worth one retry through Chrome MCP with a real browser session.
+
+**No vendor publishes typeface, color, opacity, plate, or margin for ANY of these marks.** The only font-adjacent requirement anywhere is GB's "legible typeface". So each synthetic silhouette's font must be calibrated against corpus positives exactly as the Jimeng pill was; candidate CJK families by platform convention (inference): HarmonyOS Sans / Source Han Sans / Noto Sans CJK SC for Android-origin apps, PingFang SC for iOS-origin.

maintain.sh

@@ -3,9 +3,27 @@
 set -euo pipefail
 
 uv sync --all-extras
-uv run uv-outdated
-uv run uv-secure --ignore-unfixed
+# uv-outdated / uv-secure run via uvx (isolated env), NOT `uv run`: resolving them
+# inside the project env crashes and, with set -e, aborts the whole gate before
+# ruff/pyright/tests (see CLAUDE.md "Test and lint").
+uvx uv-outdated
+# uv-secure prints its verdict but can then crash in an internal teardown with a
+# NON-ZERO exit -- observed as "annotated-doc raised exception" and later "anyio raised
+# exception"; both are bugs in uv-secure's OWN uvx env, not a project vulnerability. With
+# set -e that teardown crash aborts the whole gate before ruff/pyright/tests. So gate on
+# the VERDICT, not the exit code: capture the output, accept the run when uv-secure
+# reported all-safe (even if it then crashed), but still FAIL on a real finding (no
+# all-safe line) so a genuine CVE is never masked, and fail loud if it never got a
+# verdict at all (so a broken run is never silently skipped).
+secure_out="$(uvx uv-secure uv.lock 2>&1)" || true
+printf '%s\n' "$secure_out"
+if ! grep -qE "No vulnerabilities or maintenance issues detected|All dependencies appear safe" <<<"$secure_out"; then
+    echo "maintain.sh: uv-secure reported a finding or failed before its verdict -- triage before committing." >&2
+    exit 1
+fi
 uv run ruff check --fix
 uv run ruff format
-uv run pyright
+# Scoped to src/: a full-project pyright run OOM-crashes node on this ML-heavy
+# repo (see CLAUDE.md "Test and lint"); src/ is the authoritative strict gate.
+uv run pyright src/
 uv run pytest -n auto

packaging/conda/recipe.yaml

@@ -0,0 +1,61 @@
+schema_version: 1
+
+context:
+  version: "0.21.2"
+  python_min: "3.10"
+
+package:
+  name: remove-ai-watermarks
+  version: ${{ version }}
+
+source:
+  url: https://pypi.org/packages/source/r/remove-ai-watermarks/remove_ai_watermarks-${{ version }}.tar.gz
+  sha256: a013af322d40c137302c500638806c8864d5945699bdc2cdcbdcda3e2f37b3ac
+
+build:
+  noarch: python
+  number: 0
+  script: python -m pip install . -vv --no-deps --no-build-isolation
+
+requirements:
+  host:
+    - python ${{ python_min }}.*
+    - pip
+    - hatchling
+  run:
+    - python >=${{ python_min }}
+    - pillow >=10.0.0
+    - piexif >=1.1.3
+    - click >=8.0.0
+    - python-dotenv >=1.0.0
+    # c2pa-python is a default PyPI dependency but is not packaged on conda-forge.
+    # The guarded import falls back to the built-in C2PA byte scanner when it is
+    # absent. Add it here once a c2pa-python feedstock exists.
+
+tests:
+  - python:
+      imports:
+        - remove_ai_watermarks
+        - remove_ai_watermarks.identify
+        - remove_ai_watermarks.metadata
+      python_version: ${{ python_min }}.*
+      # pip_check defaults to true; disable it explicitly. `pip check` fails on
+      # the conda-forge piexif `py_2` build, whose stale 2019 metadata pip reads
+      # as "piexif 1.1.3 is not supported on this platform" -- even though the
+      # package installs, imports, and works. The imports test verifies loading.
+      pip_check: false
+
+about:
+  homepage: https://github.com/wiltodelta/remove-ai-watermarks
+  summary: Remove visible and invisible AI watermarks from images
+  description: |
+    Inspect and strip AI-provenance metadata (C2PA, EXIF, IPTC, and PNG text
+    chunks) from images. Optional pip extras add visible watermark removal,
+    SynthID diffusion removal, and additional invisible-watermark detectors.
+  license: Apache-2.0
+  license_file: LICENSE
+  repository: https://github.com/wiltodelta/remove-ai-watermarks
+
+extra:
+  recipe-maintainers:
+    - wiltodelta

pyproject.toml

@@ -1,31 +1,83 @@
 [project]
 name = "remove-ai-watermarks"
-version = "0.8.7"
-description = "Remove visible and invisible AI watermarks from images (Gemini / Nano Banana, ChatGPT, Stable Diffusion)"
+version = "0.22.0"
+description = "AI watermark remover: strip visible and invisible AI watermarks (Gemini / Nano Banana sparkle, SynthID) and provenance metadata (C2PA, EXIF) from images"
 readme = "README.md"
-requires-python = ">=3.10"
-license = {text = "MIT"}
+requires-python = ">=3.10.1"
+license = {text = "Apache-2.0"}
+keywords = [
+    "ai-watermark",
+    "ai-watermark-remover",
+    "watermark-remover",
+    "watermark-removal",
+    "remove-watermark",
+    "synthid",
+    "c2pa",
+    "content-credentials",
+    "nano-banana",
+    "gemini",
+    "gemini-watermark",
+    "ai-metadata",
+    "metadata-removal",
+    "provenance",
+    "exif",
+    "stable-diffusion",
+    "comfyui",
+    "ai-detection",
+]
 classifiers = [
-    "License :: OSI Approved :: MIT License",
+    "Development Status :: 4 - Beta",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "Intended Audience :: End Users/Desktop",
+    "License :: OSI Approved :: Apache Software License",
     "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3 :: Only",
     "Programming Language :: Python :: 3.10",
     "Programming Language :: Python :: 3.11",
     "Programming Language :: Python :: 3.12",
     "Programming Language :: Python :: 3.13",
     "Topic :: Multimedia :: Graphics",
+    "Topic :: Multimedia :: Graphics :: Graphics Conversion",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
     "Topic :: Scientific/Engineering :: Image Processing",
+    "Topic :: Security",
+    "Topic :: Utilities",
 ]
 dependencies = [
     "pillow>=10.0.0",
     "piexif>=1.1.3",
-    "numpy>=1.24.0",
-    "opencv-python-headless>=4.8.0",
     "click>=8.0.0",
     "python-dotenv>=1.0.0",
+    # Official C2PA reader (Content Authenticity Initiative, MIT/Apache-2.0). The
+    # primary, spec-tracking manifest parser for the identify/metadata path; the
+    # hand-rolled caBX/CBOR scanner in noai/c2pa.py is kept only as a fallback for
+    # synthetic/partial blobs the validator rejects. Binary wheel (Rust), but the
+    # import is light (no torch/numpy) so it fits the dependency-light identify
+    # host. Prebuilt wheels cover the full CI matrix (linux/macos/windows).
+    "c2pa-python>=0.35.0",
 ]
 
 [project.optional-dependencies]
-gpu = [
+pixels = [
+    "numpy>=1.24.0",
+    "opencv-python-headless>=4.8.0",
+]
+# Optional HEIC/AVIF pixel decode. Metadata scanning handles these containers
+# without this plugin; combine `heif` with any pixel feature only when needed.
+heif = [
+    "pillow-heif>=0.13.0",
+]
+visible = ["remove-ai-watermarks[pixels]"]
+# Open DWT-DCT watermarks used by Stable Diffusion / SDXL / FLUX. The in-tree
+# decoder avoids the upstream invisible-watermark package's mandatory torch and
+# non-headless OpenCV dependencies.
+detect = [
+    "remove-ai-watermarks[pixels]",
+    "PyWavelets>=1.1.1",
+]
+diffusion = [
+    "remove-ai-watermarks[pixels]",
     "torch>=2.0.0",
     # The default PyPI torch wheel is a CPU/CUDA build. To drive an Intel GPU
     # (Arc / Data Center) via ``--device xpu`` you need an XPU-enabled torch
@@ -33,7 +85,7 @@ gpu = [
     # XPU build). Install that build first, then this extra (torch is then
     # already satisfied and won't be re-pulled):
     #   pip install torch --index-url https://download.pytorch.org/whl/xpu
-    #   pip install 'remove-ai-watermarks[gpu]'
+    #   pip install 'remove-ai-watermarks[diffusion]'
     # uv users can target the ``pytorch-xpu`` index declared under [tool.uv]:
     #   uv pip install torch --index-url https://download.pytorch.org/whl/xpu
     "diffusers>=0.38.0",
@@ -49,20 +101,16 @@ gpu = [
     "transformers>=5,<6",
     "tokenizers>=0.22,<0.23",
     "accelerate>=0.25.0",
-    "controlnet-aux>=0.0.9",
     "safetensors",
-    "ultralytics>=8.0.0",
-    "color-matcher>=0.5.0",
 ]
-# Open invisible-watermark (imwatermark) decoder for detecting the DWT-DCT
-# watermarks embedded by Stable Diffusion / SDXL / FLUX. Optional because it
-# pulls non-headless opencv AND torch (invisible-watermark declares torch a hard
-# dependency, and WatermarkDecoder eagerly imports rivaGan -> torch at import
-# time, so the dwtDct-only detect path still needs torch present even though it
-# never runs on GPU). So `detect` alone pulls torch -- no need to add `gpu` for
-# detection. identify() guards the import and skips the signal when absent.
-detect = [
-    "invisible-watermark>=0.2.0",
+# Full two-stage high-fidelity profile: Qwen-Image-2512 Lightning + DiffSynth
+# Canny ControlNet for the frame, then SAM-masked Z-Image Turbo face repair.
+# CUDA-only and intentionally separate from the normal diffusion extra because the
+# additional model stack and DiffSynth runtime are large.
+qwen-zimage = [
+    "remove-ai-watermarks[diffusion]",
+    "diffsynth>=2.0.17,<3",
+    "torchvision>=0.20.0",
 ]
 # Adobe TrustMark decoder -- the open, keyless watermark behind Adobe Durable
 # Content Credentials (soft-binding alg ``com.adobe.trustmark.P``). Optional
@@ -76,28 +124,53 @@ trustmark = [
 # cached by huggingface_hub; it is never bundled in this repo. The default cv2
 # eraser backend needs none of this.
 lama = [
+    "remove-ai-watermarks[visible]",
     "onnxruntime>=1.16.0",
     "huggingface-hub>=0.20.0",
 ]
+# Lightweight inpaint backend -- MI-GAN via onnxruntime (andraniksargsyan/migan,
+# MIT). CPU, no torch. Model (~28 MB) downloaded on first use and cached by
+# huggingface_hub; never bundled. ~700-950 MB peak RAM / ~0.19 s/call -- the
+# memory-tight learned tier (vs big-LaMa's ~4.7 GB). Select it explicitly when
+# LaMa, the quality-first `auto` choice, is too large. Same runtime as `lama`.
+migan = [
+    "remove-ai-watermarks[visible]",
+    "onnxruntime>=1.16.0",
+    "huggingface-hub>=0.20.0",
+]
+# Optional pre-diffusion super-resolution for small inputs (Real-ESRGAN). Loaded via
+# spandrel (MIT) -- a pure model-loader with NO basicsr dependency (it pulls only
+# torch / torchvision / safetensors / numpy / einops).
+# The Real-ESRGAN weights (BSD-3-Clause) download on first use and are cached; they
+# are never bundled. CPU works but is slow on large inputs -- it is meant for the
+# pre-diffusion upscale of SMALL inputs (and the GPU worker). Guarded by
+# upscaler.is_available(); the default upscaler stays Lanczos (cv2, no deps). The
+# weights are fetched with torch.hub (bundled with spandrel's torch), so no extra
+# download dependency is needed.
+esrgan = [
+    "remove-ai-watermarks[pixels]",
+    "spandrel>=0.3.0",
+]
 dev = [
+    "remove-ai-watermarks[visible]",
+    "remove-ai-watermarks[detect]",
     "pytest>=8.0.0",
     "pytest-cov>=4.1.0",
+    "pytest-xdist>=3.5.0",
+    "packaging>=24.0",
     "ruff>=0.4.0",
     "pyright>=1.1.0",
     "invisible-watermark>=0.2.0",
+    # maintain.sh helpers; they only support newer Pythons, so gate them by
+    # marker to keep the py3.10 resolution (and CI matrix) solvable.
+    "uv-outdated>=0.1.0; python_version >= '3.12'",
+    "uv-secure>=0.12.0; python_version >= '3.12'",
 ]
-all = ["remove-ai-watermarks[gpu,detect,trustmark,lama,dev]"]
-
-# diffusers 0.38.0 (security fix for GHSA-98h9-4798-4q5v) declares a dependency
-# on safetensors>=0.8.0rc0 — a pre-release. Allow pre-releases globally so the
-# resolver can satisfy that. Drop once diffusers publishes a release with a
-# stable safetensors pin (or once safetensors 0.8.0 stable is out).
-[tool.uv]
-prerelease = "allow"
+all = ["remove-ai-watermarks[visible,heif,detect,trustmark,diffusion,qwen-zimage,lama,migan,esrgan]"]
 
 # PyTorch Intel-GPU (XPU) wheel index. ``explicit = true`` keeps it inert for
 # the default CPU/CUDA install: uv consults it only when a torch install
-# explicitly targets it (see the ``gpu`` extra comment), so it does not alter
+# explicitly targets it (see the ``diffusion`` extra comment), so it does not alter
 # the locked CPU/CUDA resolution. Linux/Windows only -- no macOS XPU build.
 [[tool.uv.index]]
 name = "pytorch-xpu"
@@ -111,22 +184,15 @@ remove-ai-watermarks = "remove_ai_watermarks.cli:main"
 Repository = "https://github.com/wiltodelta/remove-ai-watermarks"
 
 [build-system]
-# Pin hatchling < 1.28: 1.28+ emits Metadata-Version 2.5 (PEP 639), which the twine
-# bundled in pypa/gh-action-pypi-publish@release/v1 rejects ("'2.5' is not a valid
-# Metadata-Version"), failing the PyPI upload (v0.8.3, 2026-06-01). 1.27.x emits 2.4,
-# which uploads fine (0.8.2 shipped on it). Lift this pin once the publish action's
-# twine is upgraded to >= 6.1.0 (2.5-aware) or the workflow moves to `uv publish`.
-requires = ["hatchling<1.28"]
+requires = ["hatchling"]
 build-backend = "hatchling.build"
 
 [tool.hatch.build.targets.wheel]
 packages = ["src/remove_ai_watermarks"]
 
 [tool.hatch.build.targets.sdist]
-# Keep the source distribution small: ship the package + metadata, not the
-# committed test corpora / calibration captures under data/ (tens of MB --
-# synthid_corpus images + the visible-mark captures), which pushed the 0.8.0
-# sdist past PyPI's per-project file-size limit (the wheel ships only src/).
+# Keep the source distribution small: ship the package and metadata, not
+# calibration or evaluation data under data/. The wheel ships only src/.
 exclude = ["/data"]
 
 [tool.pytest.ini_options]
@@ -138,6 +204,7 @@ addopts = "-v --tb=short"
 target-version = "py310"
 line-length = 120
 exclude = ["_refs"]
+extend-exclude = ["*.md"]
 
 [tool.ruff.lint]
 select = ["E", "F", "B", "I", "S", "UP", "SIM", "RET", "COM", "C4", "G", "PT", "PIE", "T20", "DTZ", "ICN", "TCH", "RUF", "ANN"]
@@ -147,10 +214,10 @@ ignore = [
 ]
 
 [tool.ruff.lint.per-file-ignores]
+"scripts/*.py" = ["G004", "S108", "S310", "T20"]
 "tests/*.py" = ["ANN", "S101", "S105", "S106", "S108"]
 "src/remove_ai_watermarks/noai/watermark_remover.py" = ["S603", "S606", "S607", "T201"]  # subprocess calls for auto-install/CUDA fix
 "src/remove_ai_watermarks/noai/c2pa.py" = ["S110"]  # try-except-pass for corrupt file handling
-"src/remove_ai_watermarks/noai/ctrlregen/engine.py" = ["S101", "S603"]  # assert for loaded state, subprocess for auto-install
 
 [tool.ruff.format]
 quote-style = "double"
@@ -172,33 +239,3 @@ reportUnknownMemberType = false
 reportUnknownArgumentType = false
 reportUnknownVariableType = false
 reportMissingTypeArgument = false
-
-# CtrlRegen is a torch/diffusers/controlnet-aux boundary: those libs ship no
-# usable types, so strict pyright cannot know the tensor element types. Relax the
-# unknown-type rules for this subpackage only (mirrors the per-file pragmas used
-# for the cv2 engines); the rest of the codebase stays strict.
-[[tool.pyright.executionEnvironments]]
-root = "src/remove_ai_watermarks/noai/ctrlregen"
-reportUnknownMemberType = false
-reportUnknownArgumentType = false
-reportUnknownVariableType = false
-reportUnknownParameterType = false
-reportMissingTypeArgument = false
-reportMissingTypeStubs = false
-reportMissingImports = false
-reportArgumentType = false
-reportAssignmentType = false
-reportReturnType = false
-reportCallIssue = false
-reportIndexIssue = false
-reportOperatorIssue = false
-reportOptionalMemberAccess = false
-reportOptionalCall = false
-reportOptionalSubscript = false
-reportOptionalOperand = false
-reportAttributeAccessIssue = false
-reportPrivateImportUsage = false
-reportPrivateUsage = false
-reportInvalidTypeForm = false
-reportConstantRedefinition = false
-reportUnnecessaryComparison = false

scripts/ai_score.py

@@ -0,0 +1,436 @@
+"""AI-generation scorer for scanned datasets.
+
+Trains a gradient-boosted classifier on the metadata-derived labels of a
+scan_dataset.py output and scores every file, WITHOUT needing the
+metadata to be present at scoring time: the features are pixel and
+container statistics, so a metadata-stripped file still gets a score.
+The model is distribution-specific by design; evaluate it again before
+using it on an unrelated target distribution.
+
+Modes:
+    uv run --with scikit-learn python scripts/ai_score.py train <scan_glob> <model.pkl> [v1|v2]
+    uv run --with scikit-learn python scripts/ai_score.py score <scan_glob> <model.pkl> <out.jsonl>
+
+<scan_glob> is a glob of scan_dataset shards, e.g. 'data/scan/part_*.jsonl'.
+score output: one JSON line per file with file, sha256, ai_score, and the
+label evidence when a metadata label existed (for monitoring drift).
+"""
+
+import glob
+import json
+import math
+import pickle
+import sys
+from collections import defaultdict
+from pathlib import Path
+from typing import Any, Literal
+
+import numpy as np
+
+# AI-generator names in C2PA claim_generator_info (metadata-level truth).
+AI_GENERATORS = (
+    "openai",
+    "adobe firefly",
+    "adobe_firefly",
+    "microsoft responsible ai",
+    "microsoft_designer",
+    "black forest labs",
+    "fal-ai",
+    "bria",
+    "chatgpt",
+    "stability",
+    "dreamina",
+    "canva",
+)
+# Human-origin software (negative evidence, NOT proof by itself).
+HUMAN_SOFTWARE = (
+    "photoshop",
+    "lightroom",
+    "picsart",
+    "snapseed",
+    "paint.net",
+    "gimp",
+    "capture one",
+    "meitu",
+    "xingtu",
+    "snow",
+)
+
+_FEAT_SCALAR = [
+    ("noise", "noise_std"),
+    ("noise", "noise_kurtosis"),
+    ("fft", "cfa_peak"),
+    ("ela", "ela_mean"),
+    ("ela", "ela_p95"),
+    ("gradient", "laplacian_var"),
+    ("color", "saturation_mean"),
+    ("color", "value_mean"),
+    ("dct", "benford_mad"),
+]
+FeatureSchema = Literal["v1", "v2"]
+_FFT_BANDS = 8
+_GRADIENT_BINS = 10
+_COLOR_BINS = 64
+_DCT_AC_POSITIONS = 8
+_DCT_AC_BINS = 21
+_JPEG_QUANT_TABLES = 2
+_JPEG_QUANT_VALUES = 64
+_SCORE_BATCH = 4096
+
+_V1_FEATURE_NAMES = (
+    *(key for _, key in _FEAT_SCALAR),
+    *(f"fft_band_energy_{index}" for index in range(_FFT_BANDS)),
+    *(f"gradient_hist_{index}" for index in range(_GRADIENT_BINS)),
+    *(f"color_hist_4x4x4_{index}" for index in range(_COLOR_BINS)),
+    "jpeg_444",
+    "jpeg_progressive",
+    "megapixels",
+    "aspect_ratio",
+    "format_jpeg",
+    "format_png",
+)
+_V2_EXTRA_FEATURE_NAMES = (
+    "cfa_peak_0",
+    "cfa_peak_1",
+    *(f"dct_ac_{position}_{bin_index}" for position in range(_DCT_AC_POSITIONS) for bin_index in range(_DCT_AC_BINS)),
+    *(f"jpeg_quant_{table}_{index}" for table in range(_JPEG_QUANT_TABLES) for index in range(_JPEG_QUANT_VALUES)),
+    "jpeg_quant_table_count",
+    "jpeg_huffman_table_count",
+    "jpeg_huffman_total_bytes",
+    "jpeg_scan_count",
+    "jpeg_restart_interval",
+    "jpeg_precision_bits",
+    "jpeg_adobe_transform",
+    "jpeg_jfif_present",
+    "format_webp",
+    "format_isobmff",
+    "format_other",
+)
+_SCHEMA_FEATURE_NAMES: dict[str, tuple[str, ...]] = {
+    "v1": _V1_FEATURE_NAMES,
+    "v2": _V1_FEATURE_NAMES + _V2_EXTRA_FEATURE_NAMES,
+}
+
+
+def parse_schema(value: Any) -> FeatureSchema:
+    """Validate a feature-schema token (CLI argument or model-bundle field)."""
+    if value == "v1" or value == "v2":
+        return value
+    raise ValueError(f"Unknown feature schema: {value!r}")
+
+
+def feature_names(schema: FeatureSchema = "v1") -> tuple[str, ...]:
+    """Return the stable ordered feature names for a model schema."""
+    return _SCHEMA_FEATURE_NAMES[parse_schema(schema)]
+
+
+def _fixed_values(values: Any, count: int, *, normalize: bool = False) -> list[float]:
+    """Return a fixed-width float vector, padding absent values with NaN."""
+    if not isinstance(values, (list, tuple)):
+        return [float("nan")] * count
+    result = [float(value) for value in values[:count]]
+    if normalize and result:
+        total = sum(value for value in result if math.isfinite(value))
+        if total > 0:
+            result = [value / total for value in result]
+    return result + [float("nan")] * (count - len(result))
+
+
+def _optional_float(mapping: dict[str, Any], key: str) -> float:
+    value = mapping.get(key)
+    return float(value) if isinstance(value, (int, float)) else float("nan")
+
+
+def label_of(record: dict[str, Any]) -> int | None:
+    """1 = strong metadata AI, 0 = human-origin, None = unlabeled."""
+    store = record.get("c2pa_store") or {}
+    for m in (store.get("manifests") or {}).values():
+        for cgi in m.get("claim_generator_info") or []:
+            if any(g in str(cgi.get("name", "")).lower() for g in AI_GENERATORS):
+                return 1
+        for a in m.get("assertions") or []:
+            d = a.get("data") if isinstance(a.get("data"), dict) else {}
+            if "trainedAlgorithmicMedia" in str(d.get("digitalSourceType", "")):
+                return 1
+    for c in record.get("png_chunks", []):
+        t = c.get("text", "")
+        kw = t.split("\x00")[0]
+        if kw in ("prompt", "workflow", "parameters") or "AIGC" in t[:80]:
+            return 1
+    exif = record.get("exif", {})
+    z = exif.get("0th") or {}
+    e = exif.get("Exif") or {}
+    if z.get("Make") and z.get("Model") and (e.get("MakerNote") or e.get("LensModel") or e.get("LensMake")):
+        return 0
+    for c in record.get("png_chunks", []):
+        if c.get("apple_screenshot_marker"):
+            return 0
+    for v in (record.get("iptc") or {}).values():
+        if str(v).strip() == "Screenshot":
+            return 0
+    if any(t in str(z.get("Software", "")).lower() for t in HUMAN_SOFTWARE):
+        return 0
+    return None
+
+
+def features_of(record: dict[str, Any], *, schema: FeatureSchema = "v1") -> list[float]:
+    """The structural feature vector (pixel + container stats, no metadata)."""
+    v = [float((record.get(s) or {}).get(k, np.nan)) for s, k in _FEAT_SCALAR]
+    fft = record.get("fft") or {}
+    gradient = record.get("gradient") or {}
+    color = record.get("color") or {}
+    v.extend(_fixed_values(fft.get("fft_band_energy"), _FFT_BANDS))
+    v.extend(_fixed_values(gradient.get("gradient_hist"), _GRADIENT_BINS))
+    v.extend(_fixed_values(color.get("color_hist_4x4x4"), _COLOR_BINS))
+    jf = record.get("jpeg_forensics") or {}
+    v.append(1.0 if jf.get("subsampling") == "4:4:4" else 0.0)
+    v.append(1.0 if jf.get("progressive") else 0.0)
+    pil = record.get("pil") or {}
+    w, h = pil.get("width") or 0, pil.get("height") or 0
+    v += [float(w * h) / 1e6, float(w) / max(h, 1)]
+    fmt = record.get("content_format")
+    v += [1.0 if fmt == "jpeg" else 0.0, 1.0 if fmt == "png" else 0.0]
+    if schema == "v2":
+        v.extend(_fixed_values(fft.get("cfa_peaks"), 2))
+        dct_hist = (record.get("dct") or {}).get("dct_ac_hist")
+        for position in range(_DCT_AC_POSITIONS):
+            values = dct_hist[position] if isinstance(dct_hist, list) and position < len(dct_hist) else None
+            v.extend(_fixed_values(values, _DCT_AC_BINS, normalize=True))
+        quant_tables = jf.get("quant_tables")
+        for table in range(_JPEG_QUANT_TABLES):
+            values = quant_tables.get(str(table)) if isinstance(quant_tables, dict) else None
+            v.extend(_fixed_values(values, _JPEG_QUANT_VALUES))
+        is_jpeg = fmt == "jpeg"
+        huffman_tables = jf.get("huffman_tables_hex")
+        huffman_values = huffman_tables if isinstance(huffman_tables, list) else []
+        v.extend(
+            [
+                float(len(quant_tables)) if isinstance(quant_tables, dict) else (0.0 if is_jpeg else float("nan")),
+                float(len(huffman_values)) if is_jpeg else float("nan"),
+                (
+                    float(sum(len(value) // 2 for value in huffman_values if isinstance(value, str)))
+                    if is_jpeg
+                    else float("nan")
+                ),
+                _optional_float(jf, "scan_count"),
+                _optional_float(jf, "restart_interval"),
+                _optional_float(jf, "precision_bits"),
+                _optional_float(jf, "adobe_transform"),
+                1.0 if jf.get("jfif") else (0.0 if is_jpeg else float("nan")),
+                1.0 if fmt == "webp" else 0.0,
+                1.0 if isinstance(fmt, str) and fmt.startswith("isobmff:") else 0.0,
+                (
+                    1.0
+                    if fmt is not None and fmt not in {"jpeg", "png", "webp"} and not str(fmt).startswith("isobmff:")
+                    else 0.0
+                ),
+            ]
+        )
+    elif schema != "v1":
+        raise ValueError(f"Unknown feature schema: {schema}")
+    expected = len(feature_names(schema))
+    if len(v) != expected:
+        raise ValueError(f"Feature schema {schema} produced {len(v)} values; expected {expected}")
+    return v
+
+
+def grouped_stratified_split(
+    labels: np.ndarray,
+    hashes: np.ndarray,
+    *,
+    test_size: float = 0.3,
+    random_state: int = 0,
+) -> tuple[np.ndarray, np.ndarray]:
+    """Split records by hash while preserving label balance across hash groups."""
+    if len(labels) != len(hashes):
+        raise ValueError("labels and hashes must have equal length")
+    if not 0 < test_size < 1:
+        raise ValueError("test_size must be between 0 and 1")
+    groups: dict[str, list[int]] = defaultdict(list)
+    group_labels: dict[str, int] = {}
+    for index, (label, digest) in enumerate(zip(labels, hashes, strict=True)):
+        key = str(digest) if digest else f"__row_{index}"
+        int_label = int(label)
+        if key in group_labels and group_labels[key] != int_label:
+            raise ValueError(f"Hash {key!r} has conflicting labels")
+        group_labels[key] = int_label
+        groups[key].append(index)
+    keys_by_label: dict[int, list[str]] = defaultdict(list)
+    for key, label in group_labels.items():
+        keys_by_label[label].append(key)
+    rng = np.random.default_rng(random_state)
+    test_set: set[str] = set()
+    for class_keys in keys_by_label.values():
+        if len(class_keys) < 2:
+            raise ValueError("Each label needs at least two distinct hash groups")
+        shuffled = np.asarray(class_keys)
+        rng.shuffle(shuffled)
+        test_count = min(max(round(len(shuffled) * test_size), 1), len(shuffled) - 1)
+        test_set.update(shuffled[:test_count].tolist())
+    train_set = set(groups) - test_set
+    train = np.asarray([index for key, indices in groups.items() if key in train_set for index in indices])
+    test = np.asarray([index for key, indices in groups.items() if key in test_set for index in indices])
+    return np.sort(train), np.sort(test)
+
+
+def temporal_holdout_split(
+    dates: np.ndarray,
+    hashes: np.ndarray,
+    *,
+    train_fraction: float = 0.7,
+) -> tuple[np.ndarray, np.ndarray, str]:
+    """Split chronologically and remove later copies of training hashes."""
+    if len(dates) != len(hashes):
+        raise ValueError("dates and hashes must have equal length")
+    if not 0 < train_fraction < 1:
+        raise ValueError("train_fraction must be between 0 and 1")
+    unique_dates = sorted({str(date) for date in dates})
+    if len(unique_dates) < 2:
+        raise ValueError("Temporal holdout needs at least two distinct dates")
+    cutoff_index = min(int(len(unique_dates) * train_fraction), len(unique_dates) - 1)
+    cutoff = unique_dates[cutoff_index]
+    train = np.flatnonzero(dates < cutoff)
+    test = np.flatnonzero((dates >= cutoff) & ~np.isin(hashes, hashes[train]))
+    return train, test, cutoff
+
+
+def model_schema(bundle: dict[str, Any]) -> FeatureSchema:
+    """Read a model's feature schema, defaulting legacy bundles to v1."""
+    return parse_schema(bundle.get("feature_schema", "v1"))
+
+
+def iter_records(pattern: str) -> Any:
+    for path in sorted(glob.glob(pattern)):
+        with open(path) as fh:
+            for line in fh:
+                yield json.loads(line)
+
+
+def cmd_train(pattern: str, model_path: str, schema: FeatureSchema = "v2") -> None:
+    from sklearn.ensemble import HistGradientBoostingClassifier
+    from sklearn.impute import SimpleImputer
+    from sklearn.metrics import average_precision_score, roc_auc_score
+
+    # keep the feature vector, not the record: a parsed scan record is an order of
+    # magnitude larger than the row it collapses to.
+    labeled: dict[str, tuple[list[float], int, str]] = {}
+    missing_hash_index = 0
+    for r in iter_records(pattern):
+        if "noise" not in r:
+            continue
+        lab = label_of(r)
+        if lab is None:
+            continue
+        digest = r.get("sha256")
+        if not digest:
+            digest = f"__missing_{missing_hash_index}"
+            missing_hash_index += 1
+        date = Path(r["file"]).parent.name
+        previous = labeled.get(str(digest))
+        if previous is not None and previous[1] != lab:
+            raise ValueError(f"Hash {digest!r} has conflicting labels")
+        if previous is None or date < previous[2]:
+            labeled[str(digest)] = (features_of(r, schema=schema), lab, date)
+
+    rows, labels, row_dates = zip(*labeled.values(), strict=True)
+    X = np.asarray(rows)
+    y = np.asarray(labels)
+    dates = np.asarray(row_dates)
+    hashes = np.asarray(list(labeled))
+    print(
+        f"unique labeled: {len(y)} "
+        f"(pos {int(y.sum())}, neg {int((1 - y).sum())}, features {X.shape[1]}, schema {schema})"
+    )
+
+    def fit(train: np.ndarray) -> tuple[Any, Any]:
+        rows = X[train]
+        imputer = SimpleImputer(strategy="median")
+        classifier = HistGradientBoostingClassifier(
+            random_state=0,
+            max_iter=300,
+            l2_regularization=5.0,
+            early_stopping=False,
+        )
+        classifier.fit(imputer.fit_transform(rows), y[train])
+        return imputer, classifier
+
+    train, test = grouped_stratified_split(y, hashes, test_size=0.3, random_state=0)
+    imp, clf = fit(train)
+    p = clf.predict_proba(imp.transform(X[test]))[:, 1]
+    print(f"SHA-grouped holdout: AUC {roc_auc_score(y[test], p):.4f} | AP {average_precision_score(y[test], p):.4f}")
+
+    temporal_train, temporal_test, cutoff = temporal_holdout_split(dates, hashes)
+    if len(temporal_train) > 100 and len(temporal_test) > 100:
+        imp_t, clf_t = fit(temporal_train)
+        pt = clf_t.predict_proba(imp_t.transform(X[temporal_test]))[:, 1]
+        auc_t = roc_auc_score(y[temporal_test], pt)
+        ap_t = average_precision_score(y[temporal_test], pt)
+        print(f"temporal (<{cutoff}): AUC {auc_t:.4f} | AP {ap_t:.4f}")
+
+    all_indices = np.arange(len(y))
+    imp, clf = fit(all_indices)
+    bundle = {
+        "imputer": imp,
+        "clf": clf,
+        "feature_schema": schema,
+        "feature_names": feature_names(schema),
+    }
+    with open(model_path, "wb") as f:
+        pickle.dump(bundle, f)
+    print(f"model written: {model_path}")
+
+
+def cmd_score(pattern: str, model_path: str, out_path: str) -> None:
+    # the model file is produced locally by `train`; do not load third-party pickles
+    with open(model_path, "rb") as f:
+        bundle = pickle.load(f)  # noqa: S301
+    imp, clf = bundle["imputer"], bundle["clf"]
+    schema = model_schema(bundle)
+    stored_names = bundle.get("feature_names")
+    if stored_names is not None and tuple(stored_names) != feature_names(schema):
+        raise ValueError(f"Model feature names do not match schema {schema}")
+    n = 0
+    batch_rows: list[list[float]] = []
+    batch_meta: list[dict[str, Any]] = []
+
+    def flush(out: Any) -> None:
+        """Score one batch: per-record predict_proba is dominated by call overhead."""
+        nonlocal n
+        if not batch_rows:
+            return
+        scores = clf.predict_proba(imp.transform(np.asarray(batch_rows)))[:, 1]
+        for meta, score in zip(batch_meta, scores, strict=True):
+            out.write(json.dumps({**meta, "ai_score": round(float(score), 4)}) + "\n")
+        n += len(batch_rows)
+        batch_rows.clear()
+        batch_meta.clear()
+        print(f"  {n}", flush=True)
+
+    with open(out_path, "w") as out:
+        for r in iter_records(pattern):
+            if "noise" not in r:
+                continue
+            batch_rows.append(features_of(r, schema=schema))
+            batch_meta.append({"file": r["file"], "sha256": r.get("sha256"), "metadata_label": label_of(r)})
+            if len(batch_rows) >= _SCORE_BATCH:
+                flush(out)
+        flush(out)
+    print(f"scored {n} -> {out_path}")
+
+
+def main() -> None:
+    if len(sys.argv) < 2 or sys.argv[1] not in ("train", "score"):
+        print(__doc__)
+        sys.exit(2)
+    if sys.argv[1] == "train" and len(sys.argv) in (4, 5):
+        schema = parse_schema(sys.argv[4]) if len(sys.argv) == 5 else "v2"
+        cmd_train(sys.argv[2], sys.argv[3], schema)
+    elif sys.argv[1] == "score" and len(sys.argv) == 5:
+        cmd_score(sys.argv[2], sys.argv[3], sys.argv[4])
+    else:
+        print(__doc__)
+        sys.exit(2)
+
+
+if __name__ == "__main__":
+    main()