hook-my-lichess 0.1.0__tar.gz

hook_my_lichess-0.1.0/.claude/settings.json

@@ -0,0 +1,31 @@
+{
+  "hooks": {
+    "UserPromptSubmit": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "$CLAUDE_PROJECT_DIR/hooks/on-prompt.sh",
+            "timeout": 5
+          },
+          {
+            "type": "command",
+            "command": "$CLAUDE_PROJECT_DIR/hooks/on-start.sh",
+            "timeout": 5
+          }
+        ]
+      }
+    ],
+    "Stop": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "$CLAUDE_PROJECT_DIR/hooks/on-stop.sh",
+            "timeout": 5
+          }
+        ]
+      }
+    ]
+  }
+}

hook_my_lichess-0.1.0/.claude-plugin/marketplace.json

@@ -0,0 +1,21 @@
+{
+  "name": "hml",
+  "owner": {
+    "name": "0JCRG0",
+    "url": "https://github.com/0JCRG0"
+  },
+  "plugins": [
+    {
+      "name": "hook-my-lichess",
+      "source": ".",
+      "description": "Lichess puzzle overlay that appears in your terminal while Claude is working.",
+      "version": "0.1.0",
+      "author": {
+        "name": "0JCRG0"
+      },
+      "homepage": "https://github.com/0JCRG0/hook-my-lichess",
+      "license": "MIT",
+      "keywords": ["lichess", "chess", "puzzle", "overlay", "kitty-graphics"]
+    }
+  ]
+}

hook_my_lichess-0.1.0/.claude-plugin/plugin.json

@@ -0,0 +1,12 @@
+{
+  "name": "hook-my-lichess",
+  "version": "0.1.0",
+  "description": "Lichess puzzle overlay that appears in your terminal while Claude is working.",
+  "author": {
+    "name": "0JCRG0"
+  },
+  "homepage": "https://github.com/0JCRG0/hook-my-lichess",
+  "repository": "https://github.com/0JCRG0/hook-my-lichess",
+  "license": "MIT",
+  "keywords": ["lichess", "chess", "puzzle", "overlay", "kitty-graphics"]
+}

hook_my_lichess-0.1.0/.env.example

@@ -0,0 +1,3 @@
+# Get a personal API token at https://lichess.org/account/oauth/token
+# Scope needed: puzzle:read (and puzzle:write if you flip rated to true).
+LICHESS_TOKEN=

hook_my_lichess-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,23 @@
+name: Publish to PyPI
+
+on:
+  push:
+    tags: ["v*"]
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Build wheel and sdist
+        run: |
+          python -m pip install --upgrade build
+          python -m build
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

hook_my_lichess-0.1.0/.gitignore

@@ -0,0 +1,8 @@
+.env
+.venv/
+__pycache__/
+*.pyc
+*.egg-info/
+dist/
+build/
+.DS_Store

hook_my_lichess-0.1.0/CLAUDE.md

@@ -0,0 +1,148 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Setup and common commands
+
+```bash
+# One-time setup (project uses an in-repo venv).
+python3 -m venv .venv
+.venv/bin/pip install -e .
+cp .env.example .env   # then put a Lichess token in LICHESS_TOKEN
+
+# The product. Two pieces:
+#   1. The hooks in .claude/settings.json wire UserPromptSubmit/Stop
+#      to .claude/hooks/{on-prompt,on-start,on-stop}.sh, which call
+#      `hml-overlay`. Drop those hooks (with absolute paths) into
+#      ~/.claude/settings.json to make the overlay appear in any
+#      project.
+#   2. `claude` itself — run it normally. There is no wrapper binary.
+.venv/bin/claude    # or just `claude` if the venv is activated
+
+# Standalone puzzle TUI — no overlay, no Claude. Useful for
+# exercising engine.py / board.py / api.py / render.py.
+.venv/bin/lichess-puzzle
+.venv/bin/lichess-puzzle --no-submit          # don't POST result to Lichess
+.venv/bin/lichess-puzzle --rated              # report as rated (puzzle:write)
+```
+
+There is no test suite, linter, or formatter wired up. The only
+verification path is manual: install/enable the plugin, submit a
+prompt in Claude Code, and confirm the puzzle appears.
+
+`HML_FORCE_OVERLAY=1` bypasses the terminal-detection heuristic and
+forces the overlay path on (useful when debugging on terminals that
+should support Kitty graphics but aren't detected).
+
+## Architecture
+
+One sidecar daemon, one engine, plus a shared overlay layer.
+
+- `lichess_puzzle/engine.py` — `PuzzleSession`, an I/O-agnostic state
+  machine that owns the board, current solution index, and `try_move()`
+  semantics (UCI/SAN parsing via `python-chess`, hint/solve/quit
+  commands, auto-playing the opponent's reply on a correct move). Both
+  the standalone CLI and the sidecar drive it. `_parse()` tries SAN
+  first, then falls back to UCI; UCI input is `.lower()`'d before
+  parsing but SAN is not, so `nf3` fails while `Nf3` and `g1f3` both
+  work.
+- `lichess_puzzle/board.py` — `parse_puzzle()` turns a Lichess
+  `/api/puzzle/next` payload into a `Puzzle` dataclass. Lichess
+  convention: replay `pgn[:initialPly]` to reach the position, then
+  push `pgn[initialPly]` as the opponent's *setup* move; `solution[0]`
+  is the user's first move.
+- `lichess_puzzle/api.py` — thin `httpx` wrapper around
+  `/api/puzzle/next` and `/api/puzzle/batch/mix`. Loads `LICHESS_TOKEN`
+  from `.env` at the project root via `python-dotenv`.
+- `lichess_puzzle/render.py` — ANSI Unicode board renderer used by the
+  standalone CLI only.
+- `lichess_puzzle/cli.py` — standalone `lichess-puzzle` TUI (plain
+  stdin loop, ANSI rendering).
+- `lichess_puzzle/overlay.py` — Kitty-graphics PNG renderer + protocol
+  helpers. Owns `OverlaySpec` (all dimensions live there;
+  `from_scale()` produces a scaled spec from `settings.size`),
+  `is_supported()` (capability sniff), and `kitty_transmit` /
+  `kitty_place` / `kitty_delete` (the three Kitty escapes the sidecar
+  sends).
+- `lichess_puzzle/settings.py` — Pydantic v2 settings loader. Looks at
+  `$HML_CONFIG`, then `<cwd>/hml.json`, then
+  `~/.config/hml/settings.json`. `size` accepts a preset
+  (`small|medium|large|xl|xxl`) or a positive numeric scale; `position`
+  accepts a preset (`top-right|top-left|bottom-right|bottom-left|center`)
+  or a `[row, col]` tuple (1-indexed cells). Invalid configs print a
+  warning and fall back to defaults. `settings.example.json` at the
+  repo root is a working sample.
+- `lichess_puzzle/sidecar.py` — the `hml-overlay` daemon. **This is
+  where the lifecycle/IPC design lives.**
+
+### How the sidecar overlays a puzzle on Claude's TUI (v6)
+
+This is the thing to understand before editing `sidecar.py`:
+
+1. Claude Code owns its terminal end-to-end — there is **no PTY proxy**.
+   The sidecar is a sibling process that opens the controlling tty for
+   writes and emits Kitty graphics escapes. We never see or buffer
+   Claude's I/O.
+2. **Lifecycle.** `hml-overlay start` (UserPromptSubmit hook) captures
+   `os.ttyname(0)` *before* daemonizing, double-forks, redirects
+   stdin/stdout/stderr to /dev/null, and re-opens the saved tty path
+   (NOT `/dev/tty` — after `setsid()` we have no controlling terminal).
+   The daemon writes a per-tty PID file to `~/.cache/hml/overlay-<key>.pid`
+   and binds a per-tty Unix datagram socket at
+   `/tmp/hml-overlay-<key>.sock` (key = sha1 of tty name, first 12 hex
+   chars). One daemon per controlling terminal so two Claudes in two
+   panes coexist. `start` is idempotent — if a daemon is already alive
+   it just sends `WORKING` over the socket and exits.
+3. **Redraw cadence.** The daemon's main loop sits on a `selectors`
+   poll with a 16 ms (~60 Hz) timeout. Every tick it re-emits
+   `kitty_place(IMAGE_ID=1729, placement_id=1)` to the tty, wrapped in
+   `ESC 7` / `ESC 8` (cursor save/restore) and a cursor `goto` to the
+   anchor. Kitty docs guarantee that an `a=p` with the same `(i, p)`
+   replaces the previous placement without flicker, so we don't need a
+   delete-then-place dance for re-anchors.
+4. **Image lifecycle.**
+   - On daemon start: emit a "fetching…" frame, kick off the API
+     fetch in a background thread, then transmit again with the
+     parsed puzzle (`a=T,C=1,c=…,r=…`). `C=1` so the cursor doesn't
+     move; `c`/`r` clamp the image to the available cell box.
+   - Every 16 ms tick: re-place the existing image so it snaps back
+     above scrolls.
+   - On `IDLE`: regenerate the image with the "✓ Claude is done"
+     banner. The daemon does NOT exit; the user keeps solving.
+   - On `WORKING` while a celebration is in progress (puzzle just
+     solved): cancel the celebration timer, fetch a new puzzle, redraw.
+   - On `MOVE <text>` / `HINT` / `SOLVE` / `QUIT`: drive
+     `PuzzleSession`, regenerate, retransmit.
+   - On puzzle finish (lost, gave up, or celebration timer expired):
+     delete the image with `kitty_delete` (`a=d,d=I`) and exit.
+   - On SIGTERM/SIGINT/SIGHUP or tty going away (`os.write` ENXIO/EIO):
+     same delete + clean exit.
+   - **Don't reintroduce DECSTBM** (`ESC[1;Nr`). Earlier designs used
+     scroll regions or PTY shrinks; both were brittle.
+5. **Move-input UX is a slash-command interception.**
+   `.claude/hooks/on-prompt.sh` (a UserPromptSubmit hook ordered
+   *before* `on-start.sh`) reads the JSON event, extracts the prompt,
+   and matches against:
+     - `^/p[[:space:]]+(.+)$` → forward to `hml-overlay move <text>`
+     - `^/(hint|solve|quit)$` → forward to `hml-overlay <cmd>`
+   On a match it prints `{"decision":"block","reason":"…"}` and
+   exits 0, suppressing the prompt before Claude sees it. Anything
+   else passes through untouched (including prompts that contain
+   `%` — no false-positive interception).
+6. **Puzzle fetch is async** (`threading.Thread` → `queue.Queue`)
+   so the redraw timer stays smooth.
+7. **On terminal resize** (`SIGWINCH`): refresh layout, rebuild the
+   spec at the new size, and retransmit.
+
+### Hook integration
+
+`.claude/settings.json` wires three hook scripts using
+`$CLAUDE_PROJECT_DIR`. The `UserPromptSubmit` block runs `on-prompt.sh`
+*then* `on-start.sh` — the first intercepts puzzle slash commands,
+the second nudges/spawns the daemon (always; the prompt hook's
+`block` decision only suppresses the prompt, not subsequent hooks).
+The `Stop` block runs `on-stop.sh`, which sends `IDLE`.
+
+To make the overlay appear in *any* project, copy the `hooks` block
+to `~/.claude/settings.json` with absolute paths to the hook scripts
+in this repo.

hook_my_lichess-0.1.0/PKG-INFO

@@ -0,0 +1,180 @@
+Metadata-Version: 2.4
+Name: hook-my-lichess
+Version: 0.1.0
+Summary: A Claude Code hook that opens a Lichess puzzle in your terminal while Claude is working.
+Project-URL: Homepage, https://github.com/0JCRG0/hook-my-lichess
+Project-URL: Repository, https://github.com/0JCRG0/hook-my-lichess
+Project-URL: Issues, https://github.com/0JCRG0/hook-my-lichess/issues
+Author: JCRG
+License: MIT
+Keywords: chess,claude-code,kitty-graphics,lichess,puzzle,terminal
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Games/Entertainment :: Board Games
+Classifier: Topic :: Terminals
+Requires-Python: >=3.10
+Requires-Dist: chess>=1.10
+Requires-Dist: httpx>=0.27
+Requires-Dist: pillow>=10.0
+Requires-Dist: pydantic>=2.0
+Requires-Dist: python-dotenv>=1.0
+Description-Content-Type: text/markdown
+
+# hook-my-lichess
+
+A Lichess puzzle that floats over the **same terminal** Claude Code
+is running in. While Claude is working, the puzzle hovers in the
+top-right corner. You play moves by typing `p:<move>` as a prompt —
+**including while Claude is mid-response** — and the board updates
+live, no PTY proxy, no wrapper binary in the launch path.
+
+## How it works (v6, sidecar architecture)
+
+Claude Code owns its terminal end-to-end. There is no wrapper. The
+overlay lives in a sibling process:
+
+- **Hook-launched daemon.** A `UserPromptSubmit` hook calls
+  `hml-overlay start`, which double-forks a Python daemon that opens
+  `/dev/tty` for writes and emits Kitty graphics escapes. Claude is
+  never resized, never has its I/O intercepted.
+- **Independent 16 ms redraw clock.** The daemon re-emits
+  `kitty_place(image_id, p=1)` on its own timer, decoupled from
+  Claude's stdout — so the image snaps back above scrolls without
+  waiting for Claude to emit a byte.
+- **Two input surfaces.** A turn-boundary path via the
+  `UserPromptSubmit` hook (`p:<move>` is intercepted with
+  `decision: "block"` so the prompt never reaches Claude). And a
+  **mid-turn path** via the daemon tailing Claude Code's session
+  JSONL transcript at `~/.claude/projects/<project>/<session>.jsonl`
+  for `queue-operation enqueue` and `attachment.queued_command`
+  records — Claude Code logs queued user input the moment you type
+  it, so the daemon dispatches mid-turn moves with no documented
+  hook involvement at all. An 8-second dedup window swallows the
+  duplicate when `UserPromptSubmit` later replays the same prompt.
+
+See `docs/v5-wrapper-vs-v6-sidecar.md` for the full architecture
+comparison and the bugs that drove the rewrite.
+
+## Install
+
+`hook-my-lichess` is distributed as a Claude Code plugin. Two slash
+commands and you're done.
+
+**Prereqs (one-time):**
+
+```bash
+# uv runs the Python daemon on demand and caches it
+curl -LsSf https://astral.sh/uv/install.sh | sh
+
+# Lichess personal token, see https://lichess.org/account/oauth/token
+export LICHESS_TOKEN=lip_xxxxxxxxxxxxxxxx   # add to your shell rc
+```
+
+**Install in Claude Code:**
+
+```
+/plugin marketplace add 0JCRG0/hook-my-lichess
+/plugin install hook-my-lichess@hml
+```
+
+That's it. The next prompt you submit will fire the hooks; `uvx`
+fetches `hook-my-lichess` from PyPI on first run (~2 s) and caches
+it. Subsequent invocations are instant.
+
+The daemon auto-detects whether the terminal supports Kitty graphics
+(Ghostty / Kitty / WezTerm); on terminals that don't (iTerm2,
+Terminal.app, tmux), it exits silently — Claude works as normal.
+
+## Playing the puzzle
+
+Submit any prompt to Claude. The board appears in the top-right
+within ~1 s.
+
+Type a puzzle command **as your prompt**:
+
+- `p:e2e4` — submit a UCI move
+- `p:Nf3` — submit a SAN move (piece letters uppercase: `Nf3`, not `nf3`)
+- `p:hint` — hint (which square the piece moves from)
+- `p:solve` — give up and reveal the move
+- `p:quit` — close the puzzle
+
+The hook intercepts these (`decision: "block"`) so Claude never
+sees them. **You can also type them while Claude is mid-response** —
+they'll queue, the daemon's transcript tailer will pick them up
+within ~100 ms, and the board updates without waiting for Claude's
+turn to finish. (Anything that doesn't start with `p:` passes
+through to Claude untouched.)
+
+When Claude finishes its turn, the banner flips to "✓ Claude is done"
+and you can keep solving at your own pace.
+
+## Customizing the board (size & position)
+
+Generate a default settings file:
+
+```bash
+uvx --from hook-my-lichess hml-overlay init-config
+# wrote default settings to ~/.config/hml/settings.json
+```
+
+Edit `~/.config/hml/settings.json`:
+
+```json
+{
+  "size": "xxl",
+  "position": "center"
+}
+```
+
+- **`size`** — one of `"small"` (0.75×), `"medium"` (1×, default), `"large"` (1.25×), `"xl"` (1.5×), `"xxl"` (2×), or any positive number for an exact scale (e.g. `"size": 1.7`).
+- **`position`** — one of `"top-right"` (default), `"top-left"`, `"bottom-right"`, `"bottom-left"`, `"center"`, or a `[row, col]` pair for an exact 1-indexed cell (e.g. `"position": [3, 80]`).
+
+The daemon checks three locations in order: `$HML_CONFIG`, then
+`<cwd>/hml.json`, then `~/.config/hml/settings.json`. The per-user
+file is the one you usually want.
+
+## Developing locally
+
+If you want to hack on the overlay itself instead of just using it:
+
+```bash
+git clone https://github.com/0JCRG0/hook-my-lichess
+cd hook-my-lichess
+python3 -m venv .venv
+.venv/bin/pip install -e .
+cp .env.example .env   # put LICHESS_TOKEN here
+```
+
+The hooks in this repo's `.claude/settings.json` reference
+`$CLAUDE_PROJECT_DIR/hooks/*.sh`, and those scripts prefer the local
+`.venv/bin/hml-overlay` over `uvx` when present — so working inside
+this repo always uses your in-tree code, no rebuild needed.
+
+If you also have the marketplace plugin installed, disable it for
+this repo (`/plugin disable hook-my-lichess`) so hooks don't double-fire.
+
+## Force-enable the overlay (debugging)
+
+Set `HML_FORCE_OVERLAY=1` to bypass the terminal-detection heuristic
+and always emit Kitty graphics escapes.
+
+`HML_DEBUG=1` writes diagnostic lines to `/tmp/hml-sidecar-debug.log`.
+
+## Standalone puzzle (no Claude, no overlay)
+
+Same engine, plain stdin loop:
+
+```bash
+.venv/bin/lichess-puzzle
+```
+
+Useful for exercising `engine.py`, `board.py`, `api.py`, `render.py`
+without touching the overlay code path.

hook_my_lichess-0.1.0/README.md

@@ -0,0 +1,150 @@
+# hook-my-lichess
+
+A Lichess puzzle that floats over the **same terminal** Claude Code
+is running in. While Claude is working, the puzzle hovers in the
+top-right corner. You play moves by typing `p:<move>` as a prompt —
+**including while Claude is mid-response** — and the board updates
+live, no PTY proxy, no wrapper binary in the launch path.
+
+## How it works (v6, sidecar architecture)
+
+Claude Code owns its terminal end-to-end. There is no wrapper. The
+overlay lives in a sibling process:
+
+- **Hook-launched daemon.** A `UserPromptSubmit` hook calls
+  `hml-overlay start`, which double-forks a Python daemon that opens
+  `/dev/tty` for writes and emits Kitty graphics escapes. Claude is
+  never resized, never has its I/O intercepted.
+- **Independent 16 ms redraw clock.** The daemon re-emits
+  `kitty_place(image_id, p=1)` on its own timer, decoupled from
+  Claude's stdout — so the image snaps back above scrolls without
+  waiting for Claude to emit a byte.
+- **Two input surfaces.** A turn-boundary path via the
+  `UserPromptSubmit` hook (`p:<move>` is intercepted with
+  `decision: "block"` so the prompt never reaches Claude). And a
+  **mid-turn path** via the daemon tailing Claude Code's session
+  JSONL transcript at `~/.claude/projects/<project>/<session>.jsonl`
+  for `queue-operation enqueue` and `attachment.queued_command`
+  records — Claude Code logs queued user input the moment you type
+  it, so the daemon dispatches mid-turn moves with no documented
+  hook involvement at all. An 8-second dedup window swallows the
+  duplicate when `UserPromptSubmit` later replays the same prompt.
+
+See `docs/v5-wrapper-vs-v6-sidecar.md` for the full architecture
+comparison and the bugs that drove the rewrite.
+
+## Install
+
+`hook-my-lichess` is distributed as a Claude Code plugin. Two slash
+commands and you're done.
+
+**Prereqs (one-time):**
+
+```bash
+# uv runs the Python daemon on demand and caches it
+curl -LsSf https://astral.sh/uv/install.sh | sh
+
+# Lichess personal token, see https://lichess.org/account/oauth/token
+export LICHESS_TOKEN=lip_xxxxxxxxxxxxxxxx   # add to your shell rc
+```
+
+**Install in Claude Code:**
+
+```
+/plugin marketplace add 0JCRG0/hook-my-lichess
+/plugin install hook-my-lichess@hml
+```
+
+That's it. The next prompt you submit will fire the hooks; `uvx`
+fetches `hook-my-lichess` from PyPI on first run (~2 s) and caches
+it. Subsequent invocations are instant.
+
+The daemon auto-detects whether the terminal supports Kitty graphics
+(Ghostty / Kitty / WezTerm); on terminals that don't (iTerm2,
+Terminal.app, tmux), it exits silently — Claude works as normal.
+
+## Playing the puzzle
+
+Submit any prompt to Claude. The board appears in the top-right
+within ~1 s.
+
+Type a puzzle command **as your prompt**:
+
+- `p:e2e4` — submit a UCI move
+- `p:Nf3` — submit a SAN move (piece letters uppercase: `Nf3`, not `nf3`)
+- `p:hint` — hint (which square the piece moves from)
+- `p:solve` — give up and reveal the move
+- `p:quit` — close the puzzle
+
+The hook intercepts these (`decision: "block"`) so Claude never
+sees them. **You can also type them while Claude is mid-response** —
+they'll queue, the daemon's transcript tailer will pick them up
+within ~100 ms, and the board updates without waiting for Claude's
+turn to finish. (Anything that doesn't start with `p:` passes
+through to Claude untouched.)
+
+When Claude finishes its turn, the banner flips to "✓ Claude is done"
+and you can keep solving at your own pace.
+
+## Customizing the board (size & position)
+
+Generate a default settings file:
+
+```bash
+uvx --from hook-my-lichess hml-overlay init-config
+# wrote default settings to ~/.config/hml/settings.json
+```
+
+Edit `~/.config/hml/settings.json`:
+
+```json
+{
+  "size": "xxl",
+  "position": "center"
+}
+```
+
+- **`size`** — one of `"small"` (0.75×), `"medium"` (1×, default), `"large"` (1.25×), `"xl"` (1.5×), `"xxl"` (2×), or any positive number for an exact scale (e.g. `"size": 1.7`).
+- **`position`** — one of `"top-right"` (default), `"top-left"`, `"bottom-right"`, `"bottom-left"`, `"center"`, or a `[row, col]` pair for an exact 1-indexed cell (e.g. `"position": [3, 80]`).
+
+The daemon checks three locations in order: `$HML_CONFIG`, then
+`<cwd>/hml.json`, then `~/.config/hml/settings.json`. The per-user
+file is the one you usually want.
+
+## Developing locally
+
+If you want to hack on the overlay itself instead of just using it:
+
+```bash
+git clone https://github.com/0JCRG0/hook-my-lichess
+cd hook-my-lichess
+python3 -m venv .venv
+.venv/bin/pip install -e .
+cp .env.example .env   # put LICHESS_TOKEN here
+```
+
+The hooks in this repo's `.claude/settings.json` reference
+`$CLAUDE_PROJECT_DIR/hooks/*.sh`, and those scripts prefer the local
+`.venv/bin/hml-overlay` over `uvx` when present — so working inside
+this repo always uses your in-tree code, no rebuild needed.
+
+If you also have the marketplace plugin installed, disable it for
+this repo (`/plugin disable hook-my-lichess`) so hooks don't double-fire.
+
+## Force-enable the overlay (debugging)
+
+Set `HML_FORCE_OVERLAY=1` to bypass the terminal-detection heuristic
+and always emit Kitty graphics escapes.
+
+`HML_DEBUG=1` writes diagnostic lines to `/tmp/hml-sidecar-debug.log`.
+
+## Standalone puzzle (no Claude, no overlay)
+
+Same engine, plain stdin loop:
+
+```bash
+.venv/bin/lichess-puzzle
+```
+
+Useful for exercising `engine.py`, `board.py`, `api.py`, `render.py`
+without touching the overlay code path.