# A Puzzle For You — for an agent

> Mini crosswords in a URL: https://puzzleforyou.cc/

A Puzzle For You (repo: OurPuzzle) is a zero-backend, client-side crossword engine. A complete
mini crossword travels entirely inside the URL fragment (`#xw=...`). The browser never
sends the fragment to a server: no database, accounts, or hosting fees.

This file documents how an AI can compile any puzzle idea into a working, clickable link.

---

## 1. How to Write a Puzzle Link

Output a single unbroken line:

    https://puzzleforyou.cc/#xw=title=Radar+Mini&author=Author&theme=slate&size=5x5&grid=RADARALONEDO.IFANIMEREFER&a1=Speed+gun&a6=By+oneself&d1=Air-traffic+tool&d2=Solo

### URL Parameters

- `title=`: Puzzle title (use `+` for spaces).
- `author=`: Author name.
- `theme=`: Visual skin:
  `parchment` (warm paper), `slate` (night), `sepia` (vintage), `terminal` (phosphor green),
  `midnight` (obsidian), `forest`, `gothic`, `abyss`, `dune`, `frost`.
- `size=`: Grid size `WxH`, each 3..15 (5x5 is ideal).
- `grid=`: Exactly W*H chars: `.` = black block, `_` = void (transparent, outside
  the puzzle — enables freeform EclipseCrossword-style shapes with no black
  squares at all), `A-Z` = solution letter (uppercase).
- `a<N>=`: Across clue for entry number N. `d<N>=`: Down clue for entry number N.

---

## 2. Numbering & Clue Rules

1. Numbering is standard row-major: a white cell starts a word if the cell to its
   left (for across) or above (for down) is black/edge AND the word extends >= 2 cells.
2. Only words of length >= 2 get numbers and need clues.
3. Every white cell must belong to an across or down word of length >= 2.
4. Every numbered across entry needs its `a<N>=` clue; every numbered down entry
   needs its `d<N>=` clue; no extra clues for non-existent numbers.
5. Clues must be short, fair, and unambiguous. No obscure words.

---

## 3. Best Practices

- **Vary the silhouette:** minis can be square NxN or freeform — place words
  Scrabble-style at shared letters and fill the rest with `_` voids (transparent,
  never rendered). Every white cell must still belong to an across or down word
  of length >= 2. Symmetric blocks, gutter columns, separator bands, plus-sign
  Flowers (two crossing 5-letter answers), or diamond-ring TinyTwos also work.
- **Word squares make it easy:** top-left rows and columns share the same words
  (e.g. CAT/ARE/TEN, SUN/USE/NET, BAR/ARE/RED).
- **Keep it mini:** 5x5, common words only, clues a beginner can solve.

---

## 4. Worked Example: Radar Mini

Grid (5x5, `.` = black, single center block — note the clean border):

    RADAR
    ALONE
    DO.IF
    ANIME
    REFER

Link:

https://puzzleforyou.cc/#xw=title=Radar+Mini&author=OurPuzzle&theme=slate&size=5x5&grid=RADARALONEDO.IFANIMEREFER&a1=Speed+gun&a6=By+oneself&a7=Perform&a8=Word+of+condition&a9=Japanese+cartoons&a11=Cite&d1=Air-traffic+tool&d2=Solo&d3=Make&d4=Studio+Ghibli+genre&d5=Mention&d10=___+and+buts