From 8d96906eda19ac94613323deac3c039f88d466e0 Mon Sep 17 00:00:00 2001
From: cashmere <cashmere@autistici.org>
Date: Sun, 26 Apr 2026 21:33:26 +0200
Subject: 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.
---
 AGENTS.md | 18 ++++++++++++++----
 1 file changed, 14 insertions(+), 4 deletions(-)

(limited to 'AGENTS.md')

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`)
-- 
cgit v1.3.1