Read what you see
Name every picture, word, number, and symbol. The first meaning is often only the beginning.
HEAD HEELS
Words can become objects
How to play
See it.
Say it.
Solve it.
Rebuzzle turns familiar words and phrases into visual clues. Your job is to work backwards—from what you see to the thought hiding underneath.
Practice boardEasy read
What familiar phrase is pictured here?
READING
Reveal the answer+
Reading between the lines
The word READING is literally placed between two lines.
The arrangement is part of the clue
The decoder
The clue is more than the clue.
A rebus can communicate through meaning, sound, count, direction, scale, or position. Read all of them before you settle on an answer.
Notice where it sits
Above, below, inside, outside, backwards, tiny, repeated—position is part of the sentence.
CYCLE CYCLE CYCLE
Three cycles → tricycle
Say it out loud
Pictures and letters may be sounds. Join them together and listen for a familiar word or phrase.
🐝 + 4
Bee + four → before
Your daily run
One board. A short conversation. One satisfying click.
- 01
Take in the whole board
Start with the relationship between the clues—not just each clue on its own.
- 02
Send your best read
Type the phrase you think the board represents. Close answers get useful feedback, not a dead end.
- 03
Ask for a nudge
Reveal a progressive hint when you need one. It points you toward the mechanism without giving away the answer.
- 04
Learn the trick
See the explanation, collect your score, and carry the pattern into tomorrow's puzzle.
Hard is good.
Hazy isn't.
The best puzzle makes you work, then makes perfect sense. Rebuzzle evaluates each board for clarity, fairness, and that unmistakable aha moment.
- Every visual should be recognizable at a glance.
- The intended answer should explain every clue.
- Difficulty should come from the wordplay—not blurry artwork.
- Hints should narrow the path without spoiling the finish.
Now you know the language
Today's answer is hiding in plain sight.
Look closely, trust the wordplay, and send the answer that makes everything click.
Start today's RebuzzleUnder the hood
Built for players. Documented for builders.
Rebuzzle is open source. Below is how the AI systems actually work—what each piece is for, why it exists, and where to look in the repo if you want to fork, critique, or contribute.
Architecture
System map
Generation is fail-closed: if evidence is thin, we fall back to a curated reserve rather than ship a weak board. Paths below live under apps/web/src/.
Master orchestrator
ai/services/master-puzzle-orchestrator.ts
Chooses Apex tournament vs classic Eve ToolLoop and returns a single publishable candidate or a reserve fallback.
Apex engine
ai/puzzle-agent/apex/engine.ts
Multi-candidate contest: curriculum → answer-first seeds → Eve slots → critique/repair → player sim → rubric → finalist.
Eve ToolLoop
ai/puzzle-agent/run-generation.ts
Tool-using agent that proposes boards, visuals, and explanations under a difficulty band.
Vercel AI Gateway
AI_PROVIDER / AI_GATEWAY_API_KEY
Model routing for generation, critique, embeddings, and quips without baking a single vendor into the app.
Generators
Apex tournament & Eve
Why Apex exists
A single model draft is optimistic. Apex runs a short tournament so we pick the board that survives critique, blind solve pressure, and a rubric—not the first fluent JSON blob. Curriculum + answer-first seeds force technique coverage and stop “pretty but unmoored” rebus art.
Why Eve still matters
Eve is the tool-loop workhorse inside each slot: proposing displays, calling visual tools, writing explanations and progressive hints. Apex orchestrates; Eve crafts. Difficulty bands (Hard → Impossible) constrain how far wordplay can stretch.
Quality contract
Publish gates
Shipping a daily puzzle is a privilege. Gates exist so “hard” never means “illegible” or “the answer leaked in the art.”
- 01
Cue-plan preflight
Deterministic check that every answer-seed cue is represented before we spend on judges.
- 02
Semantic alignment
semantic-alignment-v1 rejects boards where the visual story cannot plausibly land on the intended phrase.
- 03
Asset & recognition
Pictogram integrity, clarity, and multi-model recognition consensus so icons read at play size—not just in a design tool.
- 04
Blind solve / player sim
Independent solvers attempt the board without the answer. If they cannot converge, it does not ship.
- 05
Publish rubric
evaluatePublishGates enforces leak checks, technique coverage, uniqueness, difficulty band, and funScore thresholds.
- 06
Human calibration
Quarantined or edge candidates can require human playtest / icon naming evidence before the quarantine bit clears.
Visual stack
Pictograms
Boards prefer catalog-grounded icons (and carefully vetted generated paths) over decorative noise. We rasterize at play sizes, run pixel-integrity checks, and require recognition consensus before a symbol is publication-eligible. Third-party Material Symbol subsets are Apache-2.0 vendored and documented in docs/THIRD_PARTY_PICTOGRAMS.md.
In session
Play-loop AI
Authoritative guesses
POST /api/puzzles/guess is the only scorer. The active board never ships the answer; the DB is the source of truth.
Lenient validation
validateAnswer combines fuzzy string distance, contraction maps, and word-order tolerance so near-misses feel fair.
Reaction tiers
Instant feedback: correct · close (≥70) · warm (≥40) · cold · out. Built in lib/game/reactions.ts for a snappy first beat.
Eve quips
POST /api/puzzles/quip streams a short riff. The model is never told the answer—only the guess and tier—so it cannot spoil.
Closed loop
Self-learning signals
Difficulty perception
Post-solve Too easy / Just right / Brutal votes hit /api/puzzles/difficulty-feedback and feed AIFeedback.
Quality ratings
Like/dislike + reason tags via /api/puzzles/rating steer puzzle_quality learning.
Adaptive difficulty
Learning calibration adjusts the daily band (Hard → Impossible) from recent play and rejection digests—not vibes alone.
Local midnight unlock
One puzzle document per YYYY-MM-DD publication key; each player unlocks at their local midnight so the habit matches the calendar.
Operations
Daily content workflow
Cron jobs (see root vercel.json) drive /api/workflows/daily-content: calibrate → publish today → pre-generate tomorrow → open a draft blog PR for yesterday. Blog posts are human-merged before they go live (docs/AI_BLOG_PULL_REQUESTS.md).
00:00 UTCgenerate-puzzles → daily-content workflow (today + tomorrow pre-gen)
08:00 UTCsend-blog-emails
16:00 UTCsend-notifications (puzzle-ready)
20:00 UTCgenerate-blog PR + streak-reminder
Beyond today
Discovery AI
Puzzle embeddings (Gateway / Gemini embedding model) power semantic search and recommendations mixed with category affinity, difficulty fit, and novelty. Useful for archive play and “more like this”—not for spoiling tomorrow.
Contribute
Open source notes
- Monorepo:
apps/web(Next.js), sharedpackages/game-logic&packages/config. - Deeper writeups:
apps/web/docs/(generator v2, difficulty, blog PRs, pictogram licensing). - Security reports go through
SECURITY.md—not the public feedback form. - PRs welcome for gates, docs, UX, and tests. See root
CONTRIBUTING.md.
Feedback
Tell us what we got wrong—or what to build next.
Developers, players, and puzzle pedants welcome. Notes about gates, model choices, docs gaps, or product feel all help. Optional email if you want a reply.