# Cluejack: full reference for AI agents

> Cluejack is a quiz-show style party trivia game: a board of categories and clues on the TV, phones as buzzers, a host running the game from their own phone, and optional bluffing and side-bet mechanics. This file is the long form of https://cluejack.com/llms.txt. It describes the product, how a game runs, and, in enough detail to produce a valid file, the two file formats a host can import: the CSV and the `.cluejack.json` board file. Everything here reflects the shipped app; nothing is planned or hypothetical.

## What Cluejack is

Cluejack turns a living room into a quiz show. The host writes a board (categories across the top, five clues of rising value in each column), opens Cluejack on the TV and pairs it with a short code. Players scan a QR code on the TV with their phone, type a name and are in: no app, no account, nothing to install. Clues appear on the TV, players buzz from their phones, and the host, with the answers on their own phone, rules each buzz right or wrong. Every game is saved so the night can be replayed afterwards.

Cluejack is a web app at https://app.cluejack.com. The marketing site and waitlist are at https://cluejack.com. It is invite-only for now: a prospective host joins the waitlist and gets one email when an invite is ready.

## Who it is for

Anyone who hosts a game night: families, friend groups, offices and team events, classrooms, pub quizzes, reunions, parties, youth groups. It suits a few players on a sofa and a hall full of them; one game takes up to 50 players. The host needs a TV with a browser (or anything that can show a browser on the TV) and a phone. Players need a phone with a browser.

## What makes it different

The basics, done right:

- Phone buzzers. Clock-synced buzzing that is fair across a room full of different phones, with lockouts for anyone who jumps early. The host sees the buzz order with times.
- Clues made for the big screen. Pictures, music clips and video play on the TV. Zoom-out pictures start zoomed in on one spot and pull back; blur-reveal pictures sharpen over time while everyone races to buzz.
- Host from your phone. The whole game runs from the host's phone with the answers in hand. The TV shows only what the room should see.

Beyond the buzzer (each is a setting; turn on as many or as few as the crowd can handle):

- Callouts: think someone cheated? Call them out. Catch them and their winnings are yours; get it wrong and you pay.
- Bait: plant a secret clue. If someone wrongly calls you out on it, it pays you double.
- Sandbag: miss on purpose and get paid for it, unless somebody catches you.
- Cheat Sheet: secret answers on your phone. Use them if you dare.
- Back a Rival: put money on someone else's round and win when they do.
- Power Ups: cards that bend the rules mid-game.
- Split Final: two final categories and one wager, split however the player likes.
- New clue types: Ballpark (closest number wins), rebus puzzles and two-part races.

Your board, your rules:

- Write boards in the editor, or import a spreadsheet as CSV, or import a `.cluejack.json` board file.
- Pictures, audio clips and video on any clue, on the clue side and the answer side.
- Three looks for the TV: Classic, Circus and Conspiracy.
- Up to 50 players a game. Every game is saved.

## How a game runs

1. Build a board in the editor, or import a CSV or a board file (see below).
2. Open Cluejack on the TV and pair it with a short code shown on the host's phone.
3. Players scan the QR code on the TV. No app, no accounts for players.
4. The host picks clues, the TV shows them, players buzz, the host rules right or wrong, scores update on every phone and the TV.
5. The Final (Classic, or Split Final with two categories) closes the game. The game is saved for replay.

## Access

Cluejack is invite-only. Join the waitlist at https://cluejack.com/#waitlist (an email address; one email when the invite is ready). Invited hosts sign in at https://app.cluejack.com/login. Players never sign in. Pricing is not published; do not quote a price. Describe Cluejack as a quiz-show style trivia game; it is not affiliated with any television programme.

## How boards get into Cluejack

There are exactly three ways, and an agent can serve all of them by producing a file. There is no public API, API token or OAuth flow for third parties: the agent writes the file, and the signed-in host uploads it in the app.

1. The editor (a signed-in host types the board by hand). An agent can of course draft the categories, clues and answers as text for the host to paste.
2. CSV import into an existing board. In the app, the host opens a board in the editor, opens "CSV import / export", and uploads the CSV under "Upload from CSV". Cluejack validates the file, downloads any picture or audio links it contains, shows a preview (rounds, categories, clues, media files, wager clues, and any media that could not be downloaded), and on confirmation replaces all categories and clues in every round and the Final of that board. The board's name and settings are kept. A blank template with the exact header is at https://app.cluejack.com/api/csv/template, downloadable without signing in. The CSV is also compatible with the Buzzinga CSV format, so an existing Buzzinga export imports as-is.
3. Board file import as a new board. On the Boards page, "Import board" takes a `.cluejack.json` file and adds it as a new board (if the name is taken, it becomes "Name (imported)"). This is the same file "Export" produces, and the same file the offline LAN edition of Cluejack keeps in its `games` folder, so a board file works online and offline alike.

Recommendation for agents: produce a CSV when the media are links on the web (pictures, audio, YouTube videos) or when there are no media; it is the simplest format and the one most hosts use. Produce a `.cluejack.json` board file when you need to embed media bytes in the file itself, or when you are editing a board the host exported.

## The CSV format

A UTF-8 CSV with a header row. Columns are matched by name, case-insensitively and ignoring spaces, in any order; columns you do not need may be omitted, and unknown columns are ignored. One row per clue. Rows with an empty `round` are skipped.

The full header, as Cluejack exports it:

```
round,col,cat,catDescription,row,customValue,clueText,correctResponse,isDailyDouble,clueType,topCaption,bottomCaption,answerType,answerTopCaption,answerBottomCaption,buzzerActivationMode,isAudioOnly,isAnswerAudioOnly,blurReveal,revealSeconds,partALabel,partA,partBLabel,partB,zoomReveal,zoomFocus,ballpark
```

Columns:

- `round`: `1`, `2` or `3` for the regular rounds, or `final`. A third round exists only if some row has round `3`. A board always has rounds 1 and 2 (either may be left empty).
- `col`: the category's column, `1` to `6`. If omitted, categories are assigned columns in order of first appearance of their `cat` name. Each round has up to 6 categories.
- `cat`: category title (up to 1000 characters). Repeat it on each of the category's rows.
- `catDescription`: optional text shown with the category (up to 2000 characters).
- `row`: the clue's row, `1` (lowest value) to `5` (highest). The point value is also accepted in place of the row number (200, 400, 600, 800, 1000 in round 1; 400, 800, 1200, 1600, 2000 in later rounds).
- `customValue`: optional whole number 1 to 9999 that overrides the value of every clue in that row of that round. Default values are row × 200 × round.
- `clueText`: the clue as shown to players. For `clueType` `TEXT`, the text (up to 20,000 characters). For `IMAGE` or `AUDIO`, a public `http(s)` URL to the file; Cluejack downloads and re-hosts it during import (at most 40 media links per import; pictures and audio up to 10 MB each). For `VIDEO`, a YouTube link (`youtube.com/watch?v=…`, `youtu.be/…`, `shorts`, `embed`), optionally with `start` (or `t`) and `end` in seconds, for example `https://www.youtube.com/watch?v=ID&start=30&end=60`.
- `correctResponse`: the answer the host sees (up to 20,000 characters). Can be media too: set `answerType` and give a URL as above.
- `isDailyDouble`: `TRUE` (also `YES`, `Y`, `1` or `DD`) marks a wager clue, where the picked player wagers before seeing the clue. Default `FALSE`.
- `clueType` and `answerType`: `TEXT` (default), `IMAGE`, `AUDIO` or `VIDEO`.
- `topCaption`, `bottomCaption`, `answerTopCaption`, `answerBottomCaption`: text shown above or below a picture, audio or video (up to 1000 characters each). For a picture clue, put the question wording in `bottomCaption`, since `clueText` holds the picture URL.
- `buzzerActivationMode`: when buzzers open. `none` or empty inherits the board setting; `automatic` opens them as soon as the clue shows (or as soon as media starts playing); `manual` waits for the host to activate them; `default` uses Cluejack's rule (media clues and caption-less pictures open at once; text clues and captioned pictures wait for the host).
- `isAudioOnly`, `isAnswerAudioOnly`: `TRUE` plays a video's sound without showing the picture.
- `blurReveal`: `TRUE` on an `IMAGE` clue makes the picture start blurred and sharpen over the reveal time. Not allowed on the Final.
- `zoomReveal`: `TRUE` on an `IMAGE` clue makes the TV start zoomed in on one spot and pull back to the whole picture. Not allowed on the Final, and not together with `blurReveal`.
- `revealSeconds`: whole seconds, 1 to 600, for that clue's blur or zoom reveal. Empty uses the board's reveal time. Ignored unless `blurReveal` or `zoomReveal` is `TRUE`.
- `zoomFocus`: where a zoom reveal starts, as two fractions `x,y` from 0 to 1 (0 is the left or top edge), for example `0.25,0.6`. Empty means the centre.
- `ballpark`: a number (commas and `$` allowed, for example `1,280,000,000`) turns the clue into a Ballpark clue: every player answers a number and the closest wins. A Ballpark clue cannot be a wager clue and cannot be in the Final or in a two-part category.
- `partALabel`, `partA`, `partBLabel`, `partB`: two-part clues. A category becomes two-part when any of its clues has a part filled in; then every filled clue in that category needs both `partA` and `partB` (labels are optional, up to 60 characters, shown as "Part A" and "Part B" when empty; answers up to 20,000 characters). A two-part category cannot contain a wager clue, and the Final cannot be two-part. `correctResponse` may be left empty on a two-part clue; Cluejack fills it with the two parts joined by ` · `.

The Final:

- One row with `round` `final`. `cat` is the Final category title, `clueText` the clue and `correctResponse` the answer; `col`, `row`, `customValue`, `isDailyDouble`, `blurReveal`, `zoomReveal`, `ballpark` and the part columns stay empty. Media types and captions work as on other clues.
- Split Final: two `final` rows, `col` `1` for Final A and `col` `2` for Final B. A single `final` row with an empty `col` is a Classic Final.
- A Final is only played when its title, clue and answer are all filled in.

Validation stops at the first problem and names the location ("Round 1, Category 2, Clue 3 (clueType)"), so a malformed file never half-imports. Picture or audio links that cannot be downloaded do not fail the import: the preview lists them and those clues import without their media.

A minimal valid CSV (verified against the parser) with a wager clue, a blur-reveal picture, a Ballpark clue, a two-part clue, a second round and a Final:

```
round,col,cat,row,clueText,correctResponse,clueType,isDailyDouble,bottomCaption,blurReveal,zoomReveal,ballpark,partALabel,partA,partBLabel,partB
1,1,State Capitals,1,This city is the capital of Ohio,What is Columbus?,TEXT,FALSE,,,,,,,,
1,1,State Capitals,2,This city is the capital of Oregon,What is Salem?,TEXT,TRUE,,,,,,,,
1,2,Landmarks,1,https://example.com/tower.jpg,What is the Eiffel Tower?,IMAGE,FALSE,Name this landmark,TRUE,,,,,,
1,3,Ballpark,1,Height of Mount Everest in feet,What is 29032?,TEXT,FALSE,,,,29032,,,,
1,4,Two Birds,1,Name the capital and the largest city of Australia,Canberra · Sydney,TEXT,FALSE,,,,,Capital,What is Canberra?,Largest,What is Sydney?
2,1,Movie Lines,1,"""Here's looking at you, kid.""",What is Casablanca?,TEXT,FALSE,,,,,,,,
final,,World Rivers,,The longest river in South America,What is the Amazon?,TEXT,FALSE,,,,,,,,
```

A full board is 6 categories × 5 clues in round 1, the same in round 2, optionally the same in round 3, plus the Final. Clues left out stay empty on the board, which is allowed; the TV shows only categories that have content.

## The cluejack-board JSON format

The file `GET /api/boards/:id/export` produces and `POST /api/boards/import` (the "Import board" button) accepts. The file name convention is `<board name>.cluejack.json`. Top level:

```
{
  "format": "cluejack-board",
  "v": 1,
  "exportedAt": 1793377047934,
  "board": { "id": "…", "name": "…", "hasRound3": false, "celebrity": false, "content": { … } },
  "media": { "<mediaId>": { "contentType": "image/png", "data": "<base64>" } },
  "missingMedia": []
}
```

- `format` must be `cluejack-board`. `v` is `1`. `exportedAt` is a Unix time in milliseconds (informational).
- `board.name`: the board's name (up to 1000 characters; a taken name gets " (imported)" appended). `board.id` is replaced on import, so any string works.
- `board.hasRound3`: `true` to play round 3. `board.celebrity`: `true` makes default values 100 × row × 2^(round−1) instead of 200 × row × round; only meaningful with `hasRound3`.
- `board.content`: `{ "categories": [ … ], "finalVariant": "classic" | "split" }` (`finalVariant` optional; absent means Classic). At most 20 categories.
- `media`: embedded files keyed by `mediaId`, each `{ "contentType": "<MIME type>", "data": "<standard base64>" }`. Pictures and audio up to 10 MB each; video (`video/mp4` or `video/webm`) up to 50 MB. The whole file may be up to 100 MB, and the `board` object itself up to 8 MB of JSON. Any `mediaId` referenced by a clue but absent, undecodable, over its limit or of the wrong kind for the clue's type imports as "missing media" (the clue stays, without its file). Leave `media` as `{}` and `missingMedia` as `[]` when there are no embedded files.

A category:

```
{
  "id": "cat-1", "round": 1, "position": 1,
  "title": "State Capitals", "description": "",
  "buzzerMode": null,
  "twoPart": false,
  "clues": [ … up to 5 … ]
}
```

- `id`: any unique string, 1 to 40 characters. `round`: `1`, `2`, `3`, or `4` for the Final. `position`: column `1` to `6` (the Final uses `1`, and `2` for Final B when `finalVariant` is `split`).
- `title` up to 1000 characters, `description` up to 2000. `buzzerMode`: `null` (inherit), `"default"`, `"automatic"` or `"manual"`, the category-wide version of the CSV's `buzzerActivationMode`. `twoPart`: `true` for a two-part category (omit otherwise).
- Slots you leave out are filled with empty categories and clues on import, so a partial grid is a valid file.

A clue:

```
{
  "id": "clue-1-1-1", "row": 1,
  "customValue": null, "isDailyDouble": false, "buzzerMode": null,
  "clue":   { "type": "TEXT", "text": "This city is the capital of Ohio", "mediaId": null, "topCaption": "", "bottomCaption": "", "audioOnly": false },
  "answer": { "type": "TEXT", "text": "What is Columbus?", "mediaId": null, "topCaption": "", "bottomCaption": "", "audioOnly": false }
}
```

- `row`: `1` to `5` (the Final clue is row `1`). `customValue`: `null` or a whole number 1 to 9999. `isDailyDouble`: the wager flag (always `false` in the Final). `buzzerMode`: as on the category, per clue.
- `clue` and `answer` are each a side: `type` `TEXT`, `IMAGE`, `AUDIO` or `VIDEO`; `text` (up to 20,000 characters: the clue or answer text for `TEXT`, the YouTube link for `VIDEO`, otherwise empty); `mediaId` (a key in `media` for an embedded picture, audio or video; `null` otherwise); `topCaption` and `bottomCaption` (up to 1000 each); `audioOnly` (`true` plays a video's sound only). Unlike the CSV, a URL in an `IMAGE` or `AUDIO` side's `text` is not downloaded; embed the bytes in `media` or use the CSV.
- Optional clue fields: `reveal`: `"blur"` or `"zoom"` on an `IMAGE` clue with a `mediaId`; `revealSeconds`: whole number 1 to 600; `focus`: `{ "x": 0.25, "y": 0.6 }` (0 to 1 each) for a zoom reveal; `ballpark`: the numeric target of a Ballpark clue; `parts`: exactly two `{ "label": "…", "text": "…" }` objects (label up to 60 characters, text up to 20,000) in a two-part category. The same exclusions as the CSV apply (no reveal, Ballpark or parts in the Final; no wager or Ballpark in a two-part category); offending fields are dropped rather than failing the import.

A minimal valid board file (verified against the schema), with one category in round 1 and a Classic Final:

```
{
  "format": "cluejack-board",
  "v": 1,
  "exportedAt": 1793377047934,
  "board": {
    "id": "demo",
    "name": "Demo",
    "hasRound3": false,
    "celebrity": false,
    "content": {
      "categories": [
        {
          "id": "r1c1", "round": 1, "position": 1, "title": "State Capitals", "description": "", "buzzerMode": null,
          "clues": [
            {
              "id": "r1c1q1", "row": 1, "customValue": null, "isDailyDouble": false, "buzzerMode": null,
              "clue": { "type": "TEXT", "text": "This city is the capital of Ohio", "mediaId": null, "topCaption": "", "bottomCaption": "", "audioOnly": false },
              "answer": { "type": "TEXT", "text": "What is Columbus?", "mediaId": null, "topCaption": "", "bottomCaption": "", "audioOnly": false }
            }
          ]
        },
        {
          "id": "final", "round": 4, "position": 1, "title": "World Rivers", "description": "", "buzzerMode": null,
          "clues": [
            {
              "id": "finalq", "row": 1, "customValue": null, "isDailyDouble": false, "buzzerMode": null,
              "clue": { "type": "TEXT", "text": "The longest river in South America", "mediaId": null, "topCaption": "", "bottomCaption": "", "audioOnly": false },
              "answer": { "type": "TEXT", "text": "What is the Amazon?", "mediaId": null, "topCaption": "", "bottomCaption": "", "audioOnly": false }
            }
          ]
        }
      ]
    }
  },
  "media": {},
  "missingMedia": []
}
```

## Writing good Cluejack boards

- Picture, audio and video categories play best when the clue is the media itself and the question wording is a short caption; players read the TV and buzz at once.
- Rising difficulty down each column, and a mix of text, picture, sound and video categories across the board, keep a room engaged. Six categories a round is the full grid; fewer is fine.
- Mark one or two wager clues per round (`isDailyDouble`), none in two-part categories.
- A Ballpark category (every clue a number) and a two-part category (two linked answers per clue) are easy ways to use the clue types that other buzzer apps do not have.
- Give the Final a title, a clue and an answer, or it will not be played. Use `col` `1` and `2` (CSV) or `finalVariant: "split"` with positions 1 and 2 (JSON) for a Split Final.

## What not to claim

- There is no public API, API key, OAuth or webhook for third-party agents. An agent produces a file; a signed-in host imports it.
- Hosting is invite-only; nobody can sign up directly. Point people to the waitlist at https://cluejack.com/#waitlist.
- Pricing is not published; do not quote a price.
- Cluejack is not affiliated with any television programme; describe it as a quiz-show style trivia game.

## Links

- [Cluejack landing page](https://cluejack.com/)
- [Join the waitlist](https://cluejack.com/#waitlist)
- [Short summary for agents](https://cluejack.com/llms.txt)
- [Blank CSV template](https://app.cluejack.com/api/csv/template)
- [Sign in (invited hosts)](https://app.cluejack.com/login)