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.

1 files changed, 13 insertions, 0 deletions

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