How Poussée Works.

What This Means for You

• Zero-friction start — open the page, you're playing. No signup wall, no email gate.
• Instant moves — engine and puzzles run on your CPU, not a server. There's no network round-trip on a move.
• Privacy by default — your games never leave your device unless you explicitly sign in to sync.
• Offline-first — once cached (~30 seconds on first visit), the entire app works on a plane.
• Same code everywhere — the web app, PWA, and Tauri desktop builds all run the same Svelte bundle.

How Sign-In Actually Works (Magic Link)

That's it. No password is ever created, so there's nothing to be stolen, reused, or forgotten. Sessions persist until you tap Sign out in the rail.

Sign-In Methods Available

What Happens to Anonymous Progress When You Sign In?

It's migrated, not erased. The first time you sign in, every key in localStorage (streak, XP, coins, history, DNA, settings) is uploaded to your new account. If you've already signed in elsewhere, the higher-of-two values wins per field, with the most recent timestamp breaking ties. You never lose progress.

How Bots Use the Engine

Each personality bot wraps Stockfish in a strength filter. We set:

• Skill Level (0–20) — Stockfish's built-in handicap, mapped from the bot's target rating.
• Search depth limit — lower for weaker bots so they can't see deep tactics.
• Move-time budget — from 50 ms (blitz bots) to 2 s (the boss tier).
• Personality noise — we sometimes pick the 2nd or 3rd best move to give a bot character (Maya prefers attacks, Knight Errant prefers exchanges, etc.).

This is why an 800-rated bot doesn't feel like 3500-Stockfish-with-handcuffs — it actually misses the same kinds of moves an 800-rated human would.

Engine Settings You Can Tune

Why Not a Cloud Engine?

Cloud engines are common (Chess.com, Chess24) but come with three real costs: latency (you wait for a network round-trip on every analysis), privacy (your games are sent to and stored by a third party), and price (someone has to pay for that compute). Running Stockfish locally fixes all three. The only downside is that the very deepest analysis (depth 30+) takes a few seconds on a phone — on a desktop it's instant.

What 1 Credit Buys

A credit is an abstraction over 1,500 tokens of LLM throughput (input + output combined). We deliberately bundle tokens so you don't have to think in fractions of a penny. Here's the rough mapping by request type:

How Tokens Are Counted

Tokens are not characters, words, or bytes — they're the LLM's internal subword units. A rough rule: 1 token ≈ 4 English characters ≈ 0.75 words. Every request has three token buckets:

• System prompt — the rules and persona (~300 tokens, cached on the model side so it's free after the first request).
• Context — your position, recent moves, your DNA profile (~300–600 tokens, varies with depth).
• Output — the answer the model writes (~400–1500 tokens, capped per request type).

Total = system + context + output. We round up to the nearest 1,500 and that's how many credits you spend. Failed requests don't cost credits — if the model errors out you get a full refund.

How to Get Credits

• Free monthly grant — signed-in users get 30 credits/month, refreshed on the 1st.
• Daily ritual reward — finish the Daily 5 → +1 credit.
• Streak milestones — +5 credits at 7-day, 30-day, 100-day streaks.
• Coin shop — convert coins to credits at 50 coins = 10 credits.
• Pro plan — 500 credits/month, plus access to longer game reviews.

Tips to Make Every Credit Count

• Use Stockfish first for "what's the best move" — it's free, fast, and more accurate than any LLM at finding moves.
• Ask the AI Coach for "why" questions, not "what" questions. The engine knows the move; the LLM is for the explanation.
• Review whole games in one shot — 5 credits for 40 moves is cheaper than 40 single-move questions.
• Tap a move once before asking — the position then auto-attaches and you don't pay tokens to describe it twice.

Exercise Variety

Duolingo uses 8+ exercise formats to test knowledge from different angles. We apply the same principle. A single lesson may include:

• Interactive board challenges — find the best move on the board
• Multiple-choice quizzes — test conceptual understanding
• Find the blunder — identify which move is the mistake from a list
• Move ordering — arrange moves in the correct sequence
• Concept matching — pair chess terms with their definitions
• Rapid-fire drills — timed yes/no questions to build instinct

Testing the same concept in multiple ways builds deeper neural pathways than repeating the same format.

Crown Mastery Levels

Each lesson has 5 crown levels that require progressively higher performance:

Higher crown levels don't just repeat the same lesson — they transform it. At crown 3+, the system inserts review exercises from past mistakes. At crown 4+, hints are removed and difficulty increases. This is progressive overload applied to chess learning.

Lesson Categories

How Lessons Work

1. Step-by-step progression — Each lesson is a sequence of steps: text explanations, board positions, interactive challenges, and quizzes. A progress bar at the top shows how far you are.
2. Mentor-guided — A mentor bot appears in the corner, offering encouragement, hints, and personality-specific reactions. Their dialogue adapts to your performance.
3. Unlimited practice — Wrong answers are learning opportunities. There is no limit on how many puzzles or lessons you can attempt.
4. Adaptive difficulty — At higher crown levels, lessons transform: quiz options are shuffled, review exercises from past mistakes are inserted mid-lesson, and hints are disabled.
5. XP & Crown rewards — Completing a lesson earns XP (with a bonus for perfect performance) and a crown level based on accuracy.
6. Spaced review — Steps you got wrong are added to your spaced repetition queue and resurface in your Daily Review.

Lesson Locking

Lessons within a category are sequential. You must earn at least 1 crown on a lesson before the next one unlocks. The first lesson in each category is always available. This prevents skipping fundamentals while still allowing you to explore different categories freely.

Puzzle Library Architecture

Puzzles are organized into shards — files grouped by rating bucket (400-2800, in 200-point increments) and tactical theme (30+ themes). When you need puzzles in a particular range, only the relevant shard is downloaded from our CDN.

Puzzle Rating (Glicko-2)

Your puzzle rating uses the Glicko-2 system. Every puzzle has its own rating. When you solve one, both your rating and the puzzle's rating are adjusted. The system accounts for rating deviation (uncertainty) — your first 20 puzzles will see larger swings as it calibrates.

• Solve a puzzle rated higher than you → big rating gain
• Solve a puzzle rated lower → small gain
• Fail a puzzle rated lower → significant loss
• Rating deviation decreases as you solve more puzzles

Adaptive Puzzle Queue

When you enable Adaptive Mode, puzzles are selected by an algorithm that balances four priorities:

A difficulty oscillator adjusts in real-time: solve 2 in a row and the target rises +50; fail one and it drops -25. This keeps you in your zone of proximal development throughout the session.

Puzzle Themes

Every puzzle is tagged with one or more tactical themes. There are 30+ themes across these categories:

• Tactical — Fork, pin, skewer, double attack, discovered check, sacrifice, pawn fork, knight fork
• Checkmate — Back-rank, smothered, Arabian, quiet move, removing defender
• Positional — Deflection, decoy, zugzwang, interference, overloading, trapped piece, X-ray, zwischenzug
• Endgame — Basic endgame, promotion, king & pawn
• Special — Mate-in-1, mate-in-2, opening trap, Greek gift, windmill

Puzzle Modes

• Daily Puzzle — A new puzzle every day, the same for everyone.
• Puzzle Rush — Solve as many as you can before time runs out. Sprint (3 min), Marathon (5 min), Survival (3 strikes).
• The Gauntlet — 7 daily puzzles themed by day of week (Fork Monday, Pin Tuesday, etc.).
• Puzzle Survival — Roguelike: each puzzle advances a floor. Rating increases ~50 per floor. 3 lives, choose perks every 10 floors.
• Puzzle Chains — 5 linked thematic puzzles with a narrative arc. 12+ chains available.
• Time Warp — Same difficulty puzzles with shrinking time limits (60s → 30s → 15s → 10s → 5s).
• Sacrifice or Safe — Judge whether a move is a brilliant sacrifice or a blunder.
• Puzzle Architect — Design your own puzzles and share them.
• Puzzle Audit — Rate and review community-submitted puzzles.

Unlimited Practice

There is no limit on how many lessons or puzzles you can attempt. Wrong answers are learning opportunities, not penalties. Practice as much as you want, whenever you want.

XP & Levels

XP (experience points) track your cumulative effort. You earn XP from:

• Completing lessons (amount varies by lesson length)
• Perfect lesson bonus (+25 XP for zero mistakes)
• Daily review sessions (+5 XP per reviewed puzzle)

XP accumulates into levels (50+ levels total). Each level requires more XP than the last. Your level is a rough measure of how much time you've invested in learning.

Coins

Coins are Poussée's in-app currency (1 crown = 30 coins). You earn coins from:

• Completing puzzles (varies by theme/difficulty)
• Finishing daily quests
• Gauntlet completion
• Review sessions (15 coins per session)
• Achievements

You spend coins on:

• Streak freezes (25 coins)
• Board themes & app themes
• Cosmetic items in the Coin Shop

Streaks

Your streak counts consecutive days of activity. Any qualifying activity (solving a puzzle, completing a lesson, doing a review) extends your streak by one day.

• Streak Freeze — Protects your streak for one missed day. Costs 25 coins. Max 3 freezes stored at a time.
• Streak Celebrations — Milestone messages at 3, 7, 14, 30, 50, 100, and 365 days
• Streak display — Visible in the sidebar nav and on your profile

Daily Quests

Five quests refresh daily (UTC midnight). Each has a coin reward. Quest types include:

• Solve the daily puzzle
• Complete a lesson
• Solve N puzzles of a specific theme
• Win a bot game
• Complete a review session

Completing all 5 quests unlocks a bonus reward.

Achievements

Long-term goals organized by rarity tier:

• Common — Getting started milestones (first puzzle, first lesson)
• Rare — Theme mastery (solve 50 fork puzzles, beat 5 bots)
• Epic — Serious milestones (1000 puzzles, 100-day streak)
• Legendary — Extraordinary feats (all bots defeated, all lessons mastered)

Achievements award coins, titles, and cosmetic items.

Spaced Repetition

Poussée uses a modified SM-2 algorithm (the same algorithm behind Anki) to schedule reviews of puzzles you've gotten wrong:

The Daily Review page shows all puzzles due for review. It works like a mini-lesson: progress bar, XP awarded. You can also review lesson steps you struggled with — not just puzzles.

Bot Personalities

Each bot has a unique identity: a name, avatar, emoji, play style (aggressive, defensive, tactical, positional), rating range, and dialogue set. Bots react emotionally to the game state — they taunt when ahead, panic when losing, and congratulate when you find a good move.

Bots are unlocked progressively. Beat one to unlock the next. The Climb mode structures this as a 10-floor ladder challenge.

Stockfish Engine

Bot play and analysis are powered by Stockfish 17 running as WebAssembly in your browser. Key technical details:

• Multi-threaded — Uses SharedArrayBuffer where available (routes with COEP/COOP headers)
• Configurable strength — Search depth and thinking time mapped to bot rating for realistic difficulty
• Runs locally — No server calls. Your moves never leave your device.
• Analysis mode — Full evaluation with move classification (best, good, inaccuracy, mistake, blunder)

Bot Mood System

During a game, each bot maintains an emotional state that evolves based on game events:

• Capturing their piece → frustration or surprise
• Putting them in check → panic or respect
• Blundering a piece → mockery or encouragement (personality-dependent)
• Winning → congratulations or "well played" depending on margin

This makes every bot game feel like a conversation, not just a calculation.

Opening Knowledge

The Opening Explorer contains a curated database of opening lines with ECO codes, variation trees, and trap warnings. The Opening Trainer lets you practice specific repertoire lines. Bots themselves follow openings consistent with their personality — aggressive bots play the Sicilian, positional bots play the Queen's Gambit.

Game Analysis

After any bot game, you can run a full analysis. Stockfish evaluates every move and classifies it:

• Best — The engine's top choice
• Good — A strong alternative
• Inaccuracy — Suboptimal but not punished immediately
• Mistake — Loses significant advantage
• Blunder — Loses material or the game

An accuracy percentage summarizes your overall play quality. You can step through the game move-by-move with engine evaluation at each position.

AI Coach

The AI coach provides plain-English explanations during puzzles and games:

• Move explanations — Why a move is good or bad, in words you understand
• Hints — Progressive hints that nudge without spoiling the answer
• Position summaries — "White is better because of the strong knight on d5 and weak dark squares around Black's king"
• Opponent move analysis — "Your opponent played Nf3 to develop the knight and prepare castling"

On iOS, the coach runs entirely on-device using Apple Foundation Models. On the web, it uses pre-built explanation templates. Your moves never leave your device.

PGN Import & Board Scanner

• Import PGN — Paste or upload a PGN file to replay and analyze any game
• Board Scanner — Capture a physical chess board position using your camera, or set up a position manually
• Replay Viewer — Step through recorded games with full analysis overlay

Player DNA

Your Player DNA is a radar chart of 8 chess dimensions, built from your puzzle and game data:

• Tactical Vision — Ability to spot forks, pins, skewers, and combinations
• Positional Sense — Understanding of pawn structure, piece placement, and long-term plans
• Opening Accuracy (White) — How well you play the opening as White
• Opening Accuracy (Black) — How well you play the opening as Black
• Middlegame Accuracy — Decision quality in complex middlegame positions
• Endgame Accuracy — Technical proficiency in endgame conversions
• Time Management — How efficiently you use your clock
• Blunder Rate — How often you make serious mistakes (lower is better)

The DNA is displayed as a radar chart on your profile. It updates after every game and puzzle session. Systems like the Adaptive Queue and Weakness Assassin use it to target your weakest areas.

Weekly Recap

Every week, you get a multi-card recap slideshow showing:

• Games played and win rate
• Puzzles solved and accuracy
• Rating change (up or down)
• Streak status
• Achievement unlocks
• A motivational message tailored to your progress

Themes & Customization

• Board Themes — Multiple color schemes for the chessboard (classic wood, midnight, coral, etc.)
• App Themes — Full app color customization (dark, light, and accent variations)
• Unlocking — Some themes are free, others are unlocked via achievements or the Coin Shop
• Preview — Try any theme before unlocking to see if you like it

Leaderboards

Multiple leaderboard dimensions so everyone can find something to compete on:

• Puzzle Rating — Highest Glicko-2 rating
• Duel Rating — Head-to-head competitive rating
• Theme-Specific — e.g., "Top Forkers," "Pin Masters"
• Longest Streak — Most consecutive days
• Achievement Hunters — Most achievements unlocked
• Coin Earners — Most coins earned (all time)

Filter by period: All Time, This Week, Today.

Tournaments

Create and join tournaments with configurable formats:

• Swiss — Multi-round, flexible player count, automatic pairing
• Round Robin — Everyone plays everyone
• Single Elimination — Win or go home
• Double Elimination — Two losses to eliminate

Time controls include Rapid (10 min), Blitz (5 min), and Bullet (1 min). Live standings update as results come in.

Friends & Profiles

• Search for friends by username
• View public profiles with stats, ratings, DNA, and game history
• Challenge friends to duels or tournament games
• See activity feed of what friends are doing

Content Ratings & Votes

Every puzzle and lesson can be liked/disliked and rated 1-5 stars. Ratings and votes are visible to everyone (no account needed to see them). You must be logged in to vote or rate. Counts update in real time via Supabase Realtime — you can see other people's votes appear live.

How Offline Works

Service Worker Caching Strategy

• Static assets (CSS, JS, fonts, images) — Cache-first. Served instantly from cache, updated in background.
• Navigation — Network-first with offline fallback. If the network is down, you see a cached version or the offline page.
• Stockfish WASM — Cached aggressively. The ~2MB engine binary is stored locally after first download.
• API requests (Supabase) — Network-only. These require connectivity. Changes made offline are queued.

PWA Installation

Poussée can be installed as a Progressive Web App on any platform:

• Desktop — Chrome/Edge: click the install icon in the address bar
• iOS Safari — Tap Share → Add to Home Screen
• Android Chrome — Tap the install banner or Menu → Add to Home Screen

Once installed, Poussée runs in a standalone window (no browser chrome), feels native, and works offline.

What Works Offline

Native Apps

For the best offline experience, use the native apps (iOS, macOS, Windows, Linux). They offer:

• Full offline play with no initial download needed
• Multi-threaded Stockfish (faster analysis)
• On-device AI coach (iOS 26+ via Apple Foundation Models)
• iCloud sync (iOS/macOS)
• Apple Watch companion app
• Haptic feedback, Siri Shortcuts, Live Activities

Local-First Architecture

All progression data is stored in your browser's localStorage first. This means:

• The app works without any account or internet connection
• Your data is yours — it lives on your device
• Server sync is optional and additive

Cloud Sync

When you sign in with your email (magic link, no password), your local data syncs to Supabase:

• On sign-in — All local data is pushed to the server, then server data is pulled and merged
• On page load — Any queued changes are drained, then latest server state is pulled
• Conflict resolution — Timestamp-based merge. Most recent change wins.

Sync Queue

If you make changes while offline (or before signing in), they're stored in a sync queue. When connectivity is restored and you're signed in, the queue is automatically drained — your offline progress is never lost.

Privacy

• No tracking cookies
• AI coach runs on-device (no move data sent to servers)
• Sentry crash reports have personal data scrubbed
• Analytics (PostHog) track feature usage, not personal data
• See our full Privacy Policy

Platforms

• Web — Any modern browser (Chrome, Firefox, Safari, Edge)
• iOS — iPhone and iPad
• macOS — Native app
• Windows — Native app
• Linux — Native app
• Apple Watch — Daily puzzle, streak, complications

Accessibility Features

• Keyboard navigation for all interactive elements
• ARIA labels on chess board squares (e.g., "a8 black king")
• Reduced motion support (prefers-reduced-motion)
• High contrast mode via app themes
• Sound effects with mute toggle
• Responsive design for all screen sizes

Browser Requirements

• Stockfish requires WebAssembly support (all modern browsers)
• Multi-threaded Stockfish requires SharedArrayBuffer (Chrome, Edge, Firefox with COEP/COOP headers)
• Service Worker required for offline caching
• localStorage required for progress persistence