# Chess Puzzle Format

This document describes the JSON a teacher imports to create chess puzzles on
chess.fe50.net. It is written so you (an LLM) can generate valid puzzles: paste
this whole page into your context, then output a JSON array of puzzle objects.

## The object

A puzzle is a JSON object with these fields:

    {
      "title": "Back-rank mate",
      "intro": "White has a forced mate in one. Can you find the check?",
      "fen": "6k1/5ppp/8/8/8/6P1/8/R5K1 w - - 0 1",
      "playerColor": "white",
      "moves": [
        {
          "uci": "a1a8",
          "comment": "The rook slams down to a8. The king is boxed in by its own pawns.",
          "hint": "Look for a check the king has no escape from."
        }
      ]
    }

Field by field:

- "title"        A short human label. Optional but recommended.
- "intro"        Optional paragraph shown before the student's first move (the
                 setup / what to look for). Omit or "" for none.
- "fen"          The STARTING position in Forsyth-Edwards Notation.
- "playerColor"  "white" or "black" — the side the STUDENT controls.
- "moves"        The full solution line as an array of MOVE OBJECTS (see below).

To import many at once, submit a JSON ARRAY of these objects:

    [ { ...puzzle... }, { ...puzzle... }, ... ]

## Move objects

Every entry in "moves" is an object:

    { "uci": "e2e4", "comment": "optional note", "hint": "optional nudge" }

- "uci"      REQUIRED. The move in UCI (see "Move notation" below).
- "comment"  Optional. Shown AFTER this move is played (coaching / explanation).
             Comments on the opponent's moves are shown too.
- "hint"     Optional. Shown when the student presses Hint, and automatically as
             a suggestion when the student plays a WRONG move on this turn.
             Write it for the student's own moves.

Only "uci" is required. A bare move is just { "uci": "a1a8" }.

## Move notation (UCI)

Each move is the origin square followed by the destination square, lower case:

    "e2e4"   pawn e2 to e4
    "g1f3"   knight g1 to f3
    "e1g1"   castling is written as the KING's move (e1 to g1 = white O-O)

Promotion appends the promoted piece letter (q, r, b, or n):

    "e7e8q"  pawn e7 to e8, promoting to a queen

Do NOT use SAN ("Nf3", "Qxa8#") for "uci". Use UCI only.

## Whose turn — how the line alternates

The "fen" says whose turn it is (the field after the piece placement: "w" or
"b"). The "moves" array alternates sides starting from that turn.

1. STUDENT MOVES FIRST. The side to move in the FEN equals "playerColor".
   moves[0] is the student's move, moves[1] the opponent's reply, and so on.

2. OPPONENT MOVES FIRST (the chess.com feel). The side to move in the FEN is the
   OTHER color. moves[0] is played automatically as a "setup" move, then
   moves[1] is the student's first move, moves[3] the next, etc. In this case
   "moves" must contain at least two entries so the student gets a turn.

Every "uci" must be legal from the running position, or the puzzle is rejected.

## Worked examples

Student (white) to move, one-move mate:

    {
      "title": "Back-rank mate",
      "intro": "The black king is trapped behind its pawns.",
      "fen": "6k1/5ppp/8/8/8/6P1/8/R5K1 w - - 0 1",
      "playerColor": "white",
      "moves": [
        { "uci": "a1a8", "comment": "Checkmate on the back rank.", "hint": "A rook check the king can't run from." }
      ]
    }

Opponent (white) moves first, then student (black) wins material:

    {
      "title": "Win the queen with a fork",
      "fen": "r1bqkb1r/pppp1ppp/2n2n2/4p3/2B1P3/5N2/PPPP1PPP/RNBQK2R w KQkq - 0 1",
      "playerColor": "black",
      "moves": [
        { "uci": "f3g5", "comment": "White lunges at f7." },
        { "uci": "d7d5", "hint": "Hit the bishop and open the center." },
        { "uci": "e4d5", "comment": "Now the knight on c6 is loose." },
        { "uci": "c6d4", "comment": "A family fork — the knight forks queen and more." }
      ]
    }

## JSON Schema

    {
      "$schema": "http://json-schema.org/draft-07/schema#",
      "type": "array",
      "items": {
        "type": "object",
        "required": ["fen", "moves", "playerColor"],
        "properties": {
          "title": { "type": "string" },
          "intro": { "type": "string" },
          "fen": { "type": "string" },
          "playerColor": { "type": "string", "enum": ["white", "black"] },
          "moves": {
            "type": "array",
            "minItems": 1,
            "items": {
              "type": "object",
              "required": ["uci"],
              "properties": {
                "uci": { "type": "string", "pattern": "^[a-h][1-8][a-h][1-8][qrbn]?$" },
                "comment": { "type": "string" },
                "hint": { "type": "string" }
              }
            }
          }
        }
      }
    }

## Output rules for LLMs

- Output ONLY the JSON array, no prose, no markdown fences.
- Every FEN must be a real, legal position.
- Every "uci" must be legal from the preceding position.
- Prefer puzzles with a single clearly-best line (these are scripted, there is
  no engine checking alternatives).
- Write "hint" on the student's own moves so wrong-move suggestions are helpful.