diff --git a/docs/tools/diffs.md b/docs/tools/diffs.md
index 31ccdfbfa86..291fb33af69 100644
--- a/docs/tools/diffs.md
+++ b/docs/tools/diffs.md
@@ -118,9 +118,17 @@ All fields are optional unless noted:
 - `fileQuality` (`"standard" | "hq" | "print"`): quality preset for PNG or PDF rendering.
 - `fileScale` (`number`): device scale override (`1`-`4`).
 - `fileMaxWidth` (`number`): max render width in CSS pixels (`640`-`2400`).
-- `ttlSeconds` (`number`): viewer artifact TTL in seconds. Default 1800, max 21600.
+- `ttlSeconds` (`number`): artifact TTL in seconds for viewer and standalone file outputs. Default 1800, max 21600.
 - `baseUrl` (`string`): viewer URL origin override. Overrides plugin `viewerBaseUrl`. Must be `http` or `https`, no query/hash.
 
+Legacy input aliases still accepted for backward compatibility:
+
+- `format` -> `fileFormat`
+- `imageFormat` -> `fileFormat`
+- `imageQuality` -> `fileQuality`
+- `imageScale` -> `fileScale`
+- `imageMaxWidth` -> `fileMaxWidth`
+
 Validation and limits:
 
 - `before` and `after` each max 512 KiB.
@@ -164,11 +172,20 @@ File fields when PNG or PDF is rendered:
 - `fileScale`
 - `fileMaxWidth`
 
+Compatibility aliases also returned for existing callers:
+
+- `format` (same value as `fileFormat`)
+- `imagePath` (same value as `filePath`)
+- `imageBytes` (same value as `fileBytes`)
+- `imageQuality` (same value as `fileQuality`)
+- `imageScale` (same value as `fileScale`)
+- `imageMaxWidth` (same value as `fileMaxWidth`)
+
 Mode behavior summary:
 
 - `mode: "view"`: viewer fields only.
 - `mode: "file"`: file fields only, no viewer artifact.
-- `mode: "both"`: viewer fields plus file fields. If file rendering fails, viewer still returns with `fileError`.
+- `mode: "both"`: viewer fields plus file fields. If file rendering fails, viewer still returns with `fileError` and compatibility alias `imageError`.
 
 ## Collapsed unchanged sections
 
@@ -287,7 +304,7 @@ Example:
   - random token (48 hex chars)
   - `createdAt` and `expiresAt`
   - stored `viewer.html` path
-- Default viewer TTL is 30 minutes when not specified.
+- Default artifact TTL is 30 minutes when not specified.
 - Maximum accepted viewer TTL is 6 hours.
 - Cleanup runs opportunistically after artifact creation.
 - Expired artifacts are deleted.
diff --git a/extensions/diffs/README.md b/extensions/diffs/README.md
index 31a5e82c93e..c6cceca0eac 100644
--- a/extensions/diffs/README.md
+++ b/extensions/diffs/README.md
@@ -60,11 +60,20 @@ Useful options:
 - `fileMaxWidth`: max width override in CSS pixels (`640`-`2400`)
 - `expandUnchanged`: expand unchanged sections (per-call option only, not a plugin default key)
 - `path`: display name for before and after input
+- `lang`: language hint for before/after input; unknown values fall back to plain text
 - `title`: explicit viewer title
-- `ttlSeconds`: artifact lifetime
+- `ttlSeconds`: artifact lifetime for viewer and standalone file outputs
 - `baseUrl`: override the gateway base URL used in the returned viewer link (origin or origin+base path only; no query/hash)
 - `viewerBaseUrl` plugin config: persistent fallback used when a tool call omits `baseUrl`
 
+Legacy input aliases still accepted for backward compatibility:
+
+- `format` -> `fileFormat`
+- `imageFormat` -> `fileFormat`
+- `imageQuality` -> `fileQuality`
+- `imageScale` -> `fileScale`
+- `imageMaxWidth` -> `fileMaxWidth`
+
 Input safety limits:
 
 - `before` and `after`: max 512 KiB each