docs(sixel): hard-state img2sixel as the recommended encoder + warn loudly when none is on PATH

Users hit a silent-failure mode where `kitty-gfx--sixel-detect' returned
true (terminal supports Sixel) but no encoder was on `PATH', so every
`sixel-place' logged `no encoder found' and produced no image.  The
echo-area `message' from `sixel-encode' was easy to miss inside tmux,
which made the issue look like a refresh / tmux passthrough bug.

- README.org: Requirements section now explicitly lists a Sixel encoder
  as required and recommends `img2sixel' (libsixel) over ImageMagick,
  with the concrete numbers from PR #10's bench (~2.2x smaller payload,
  ~10x faster) and a note that this matters most inside tmux because
  every refresh re-emits the full DCS payload.  Known-Limitations
  reworded: missing encoder = silent failure surfaced via the debug log.
- AGENTS.md: Dependencies block reorganised the same way; adds a
  pointer to `just sixel-encoder' as the first step when diagnosing
  Sixel rendering bugs.
- kitty-graphics.el: when the active backend is Sixel and
  `kitty-gfx--sixel-resolve-encoder' returns nil at mode-enable time,
  fire a `display-warning' (`*Warnings*' buffer + visible message)
  pointing at img2sixel/ImageMagick, so the failure is no longer
  buried in /tmp/kitty-gfx.log.

3 files changed, 34 insertions, 6 deletions

diff --git a/AGENTS.md b/AGENTS.md
index b18f76c..bfd618b 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -269,10 +269,20 @@ Key design differences from images:
 
 - **Required**: Emacs >= 27.1, a supported terminal (Kitty/WezTerm/Ghostty
   for Kitty backend; foot/Konsole/xterm/mlterm/mintty for Sixel)
-- **Required for Sixel**: a Sixel encoder on PATH -- `img2sixel`
-  (libsixel, recommended) or ImageMagick (`magick`/`convert`).
-  Override via `kitty-gfx-sixel-encoder-program'; bound by
-  `kitty-gfx-sixel-encoder-timeout' (default 5s).
+- **Required for Sixel**: a Sixel encoder on `PATH`.
+  - **Strongly recommended**: `img2sixel` from libsixel (~2.2x smaller
+    payload, ~10x faster than ImageMagick on the same input).  Critical
+    inside tmux, where every refresh re-emits the full DCS payload --
+    using ImageMagick there leads to visible flicker.
+  - **Fallback**: ImageMagick 7 (`magick`) or 6 (`convert`).  Works,
+    just slower.
+  - Auto-detect order: `img2sixel` > `magick` > `convert`.  Override
+    via `kitty-gfx-sixel-encoder-program' (nil = auto, string = pin).
+  - With **no** encoder on `PATH`, the Sixel backend silently produces
+    no output and logs `no encoder found` (set `kitty-gfx-debug' to
+    surface this).  Always verify with `just sixel-encoder' before
+    diagnosing rendering bugs.
+  - Bounded by `kitty-gfx-sixel-encoder-timeout' (default 5s).
 - **Optional for Kitty**: ImageMagick for non-PNG formats and pixel-accurate sizing
 - **Optional for typst preview**: `typst` CLI on PATH (used by
   `kitty-gfx-typst-preview`)
diff --git a/README.org b/README.org
index 6b95ac4..258dde0 100644
--- a/README.org
+++ b/README.org
@@ -47,7 +47,11 @@ Integrations are provided for:
 - A supported terminal:
   - *Kitty backend*: [[https://sw.kovidgoyal.net/kitty/][Kitty]] >= 0.20.0, WezTerm, or Ghostty
   - *Sixel backend*: foot, Konsole, xterm (with ~+sixel~), mlterm, mintty, VS Code Terminal, and others with Sixel support
-- ImageMagick (~magick~ / ~convert~ / ~identify~) --- required for Sixel, and for non-PNG formats on Kitty
+- A Sixel encoder on ~PATH~ --- /required/ for the Sixel backend.
+  - *Strongly recommended*: ~img2sixel~ from [[https://github.com/saitoha/libsixel][libsixel]] (Nix: ~nixpkgs#libsixel~). Roughly =2.2x= smaller payloads and =~10x= faster than ImageMagick, which matters a lot in tmux where every refresh re-emits the full DCS payload.
+  - *Fallback*: ImageMagick 7 (~magick~) or 6 (~convert~). Works, but slower; on long sessions and in tmux you may notice flicker on redraw.
+  - Override the auto-detect order via ~kitty-gfx-sixel-encoder-program~. If neither is on ~PATH~ the Sixel backend logs ~no encoder found~ and silently produces no image, so make sure one is installed before launching Emacs.
+- ImageMagick (~magick~ / ~identify~) --- still needed for non-PNG formats on the Kitty backend (JPEG/WebP/SVG/TIFF/BMP -> PNG conversion) and for the dimension probe
 - For LaTeX preview: a TeX distribution with ~dvipng~ (e.g. ~texlive~)
 - For doc-view: ~ghostscript~ (for PDF), ~dvipng~ (for DVI) --- same tools as GUI Emacs
 - Launch Emacs with ~TERM=xterm-256color~ (Emacs often can't find the ~xterm-kitty~ terminfo)
@@ -146,7 +150,8 @@ TIFF, BMP) are converted to PNG via ImageMagick before transmission.
 - Partial tmux support: Sixel works inside tmux >= 3.4 (native sixel rendering, foot/Konsole/mintty/mlterm/WezTerm as outer terminal); set ~kitty-gfx-tmux-allow-sixel~ to ~nil~ to opt out. Images may stick to old positions after scrolling because tmux's cell buffer is not pixel-aware (upstream tmux limitation). Kitty graphics passthrough inside tmux is still unimplemented
 - Animated GIFs display only the first frame
 - Sixel is limited to 256 colors (vs truecolor on Kitty) and is stateless --- images are re-emitted on every scroll, which may be slower on large images
-- Without ImageMagick, only PNG files work on the Kitty backend; the Sixel backend requires ImageMagick unconditionally
+- The Sixel backend needs a Sixel encoder on ~PATH~. ~img2sixel~ (libsixel) is strongly recommended; ~magick~ / ~convert~ work as fallback but are noticeably slower. With no encoder on ~PATH~, the backend silently produces no output and only logs ~no encoder found~ to ~/tmp/kitty-gfx.log~ when ~kitty-gfx-debug~ is non-nil
+- Without ImageMagick, only PNG files work on the Kitty backend
 - Doc-view page may briefly flash at wrong position before centering on initial load
 
 * License
diff --git a/kitty-graphics.el b/kitty-graphics.el
index c5a1e9d..adfe6b7 100644
--- a/kitty-graphics.el
+++ b/kitty-graphics.el
@@ -2166,6 +2166,19 @@ The buffer should be writable (caller handles `inhibit-read-only')."
               (kitty-gfx--query-text-sizing-support))
             (kitty-gfx--install-hooks)
             (kitty-gfx--install-integrations)
+            ;; Sixel backend silently drops images when no encoder is on
+            ;; PATH.  Warn loudly so users notice before they wonder why
+            ;; nothing renders.
+            (when (and (eq kitty-gfx--active-backend 'sixel)
+                       (not (kitty-gfx--sixel-resolve-encoder)))
+              (kitty-gfx--log "mode: WARNING no Sixel encoder on PATH")
+              (display-warning
+               'kitty-graphics
+               "Sixel backend active but no encoder on PATH.
+Install `img2sixel' (libsixel; strongly recommended) or
+ImageMagick (`magick'/`convert').  Without an encoder, no images
+will render even though detection reports Sixel as supported."
+               :warning))
             (kitty-gfx--log "mode: enabled (backend=%s cell=%dx%d text-sizing=%s)"
                              kitty-gfx--active-backend
                              kitty-gfx--cell-pixel-width kitty-gfx--cell-pixel-height