diff --git a/AGENTS.md b/AGENTS.md
index 191530b..5a28232 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -125,6 +125,10 @@ The following are generated and gitignored:
 
 `rust-analyzer.toml` excludes generated directories (`node_modules`, `public`, `.dioxus`, `.omc`, `dist`). If rust-analyzer shows spurious errors in generated files, check that the exclusion list is respected by your editor.
 
+## Image Processing
+
+- **WebP handling**: The `image` crate is configured without WebP support (`default-features = false, features = ["jpeg", "png", "gif"]`). All WebP encode/decode operations go through `zenwebp` via `src/webp.rs`. This ensures consistent WebP handling across the codebase. Do not add WebP to the image crate features.
+
 ## Notes
 
 - `rand` + `getrandom` with `js` feature are required for Argon2 salt generation in WASM builds.
diff --git a/Cargo.toml b/Cargo.toml
index 8d6f04c..4b6eaa2 100644
--- a/Cargo.toml
+++ b/Cargo.toml
@@ -25,6 +25,9 @@ axum = { version = "0.8", optional = true, features = ["multipart"] }
 serde_json = "1.0"
 ammonia = { version = "4", optional = true }
 syntect = { version = "5", default-features = false, features = ["default-syntaxes", "default-themes", "default-fancy", "html", "parsing", "dump-load", "yaml-load"], optional = true }
+# NOTE: WebP decoder is intentionally excluded from the image crate.
+# We use zenwebp for both encoding and decoding to ensure consistency.
+# Do NOT add "webp" to the features list without updating src/webp.rs.
 image = { version = "0.25", optional = true, default-features = false, features = ["jpeg", "png", "gif"] }
 zenwebp = { version = "0.3", optional = true }
 moka = { version = "0.12", features = ["future"], optional = true }