@chessceo/mcp 0.36.4 → 0.36.6

package/docs/pgn-authoring.md

@@ -274,7 +274,19 @@ set_nags(id, path, ["$14"])
 
 ## Visual annotations (arrows + coloured squares)
 
-`set_annotations(id, path, {arrows, highlights})` sets both together (an atomic replacement — pass both current and new). Passing empty arrays clears.
+**Use them.** An arrow says what a sentence would. If a comment mentions a move, a plan, a square, a target — draw it. The reader sees the board; a green f2→f4 arrow replaces "White's plan is to break with f4"; a red square on h6 replaces "Black's weak point is h6". Annotations are the fastest LLM→reader channel we have.
+
+**When to reach for one (any of these triggers → add):**
+
+- Naming a pawn break in prose → arrow from the pawn to its target square (`green` for your break, `red` for the opponent's).
+- Naming a plan involving specific moves (castle long, Nc4-a5, Bxh6) → arrow(s) for the piece routes.
+- Naming a key square / weak square / target → highlight (`green` = key square for you, `red` = weak square you exploit or that Black attacks).
+- Naming a piece under pressure or a piece that will become the target → highlight the square it's on.
+- Showing multiple candidate moves in one comment → arrow per candidate, different colours.
+
+If the comment could be *replaced* by two arrows and a highlighted square, then the arrows + squares alone are better and the prose is redundant. Try that direction first.
+
+`set_annotations(id, node_id, {arrows, highlights})` sets both together — atomic replacement, pass both current and new. Empty arrays clear.
 
 Colours (both arrows and squares): `green`, `red`, `yellow`, `light-blue`, `dark-blue`, `orange`.
 
@@ -289,7 +301,7 @@ Usage conventions:
 | dark-blue  | Alternative / secondary idea                   |
 | orange     | Attention / warning                            |
 
-**Keep it light.** 1–3 arrows per node and 2–3 highlighted squares is plenty. Twenty arrows is noise, not signal — pick the most important ones. Highlights are labels, not decoration.
+**Keep it light.** 1–3 arrows per node and 2–3 highlighted squares is plenty. Twenty arrows is noise. Highlights are labels, not decoration. **But zero arrows on a strategic branch-point comment is usually a miss** — if the comment names a plan, a break, a square, or a piece, the corresponding annotation almost certainly exists and is worth adding.
 
 Example:
 ```

package/docs/prep-strategy.md

@@ -173,7 +173,7 @@ Depth calibrates to the *character* of the position, not to whether the DB has g
 
 - **Forcing → keep going.** Concrete tactics, only-moves, sharp sequences — analyse until the position calms (real endgame, stable middlegame structure). No game data doesn't matter; the moves are forced, so there's nothing to look up anyway. `describe_position` + engine is enough.
 - **Quiet → stop early.** Once the position is strategic — many reasonable moves, no immediate threats — one sentence of plans is worth more than another 6 plies of tree. Stop and describe.
-- **Novelties MUST branch.** If you're introducing a move nobody's played, "the DB has no games" is not a reason to stop — the reader will actually reach this position over the board and needs an answer. Predict the opponent's replies with `predict_human_move` (rating-conditioned to their level), sanity-check with Stockfish (objective best) and Lc0 (practical alternatives), then branch on the top ~2 predicted responses. This is precisely where all three signals matter most, because there's no historical answer to lean on. See also "Novelty burns" — save deep novelty-prep for the games that actually warrant it.
+- **Novelties still need coverage — but the position tells you HOW.** If you're introducing a move nobody's played, "the DB has no games" is not a reason to stop; the reader will reach this position over the board and needs an answer. The shape of that coverage follows the same forcing/quiet rule above: if the novelty forces a single reply, cover just that line; if it opens several plausible replies, branch on them. Predict the opponent with `predict_human_move` (rating-conditioned), sanity-check with Stockfish (objective) and Lc0 (practical alternatives). All three signals matter *most* here precisely because no game-database answer exists. See also "Novelty burns" — that's a separate rule about WHEN to spend a novelty.
 
 ## How to combine these
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chessceo/mcp",
-  "version": "0.36.4",
+  "version": "0.36.6",
   "description": "Model Context Protocol server for chess.ceo — 11.7M+ games, ~1.5M FIDE player profiles, opening preparation, live broadcasts.",
   "type": "module",
   "bin": {