The Chess Vault docs

One page per screen of the app — from what the screen is for, down to what every button does. Pick a page from the contents on the left. Everything here can be tried in the demo — no install, no account.

Chess Vault is a private, self-hosted chess workbench: engine analysis, an opening explorer, studies, notes, a curated game collection, and a puzzle trainer fed by real paper books — everything stored as plain files (PGN, markdown, JSON) in one folder you own.

If you are new

1. Getting started — how to install it, the first run, and what to do in the first minutes.
2. The vault — where your data lives and how. The key to understanding the app.
3. Around the app — how the screens are laid out.

After that, read in order or jump to the screen you are curious about — each page is written to stand alone.

Getting started

There are two ways to run Chess Vault, and both are the same app. The only difference is where the vault lives — the folder holding your games, studies, notes and puzzles.

• On this device. Download the installer for Windows, macOS or Linux from Releases and run it. No Node, no terminal; updates arrive through the app itself.
• On a server. One small Linux box owns the vault, and every device — phone, laptop, desktop — becomes a client of it. The README has the server setup.

When in doubt, start with the first. The vault is a folder, so moving to a server later is copying a folder.

First run

The desktop app's first question is where your vault lives:

Choosing On this computer, the “Open your vault” step offers two answers:

The choice is not permanent: Settings → Desktop app → Vault → Switch… changes it any time.

The band at the top of the window is the app's: one strip in the sidebar's colour, edge to edge, so the sidebar's column runs to the top of the window. From the left: the sidebar's “Fold the sidebar” switch (on the band, so the sidebar itself has none there), then ☰, which opens the application menu (“Switch vault…” · “Reload” · “Full screen” · “Zoom in” · “Zoom out” · “Reset zoom” · “Developer tools” · “Quit”), then “Back” and “Forward” through the app's history. Over a folded rail only the switch stays, and the rest sit to its right. In the middle of the band an “Open anything…” button, with its shortcut beside it, opens the quick switcher from any page (see Around the app); a browser has no band and no such button, and Ctrl/⌘ K reaches the same window. Minimize, maximize and close are the OS's own buttons, and dragging the band's empty part moves the window.

The first minutes

A fresh vault opens onto a Home page with a Set up your vault card suggesting three things, all done inside the app:

1. Add your Chess.com / Lichess usernames in Settings — the Games page fills itself from them.
2. Open Puzzles and accept the puzzle database it offers to fetch. It takes a few minutes, keeps running if you leave the page, and the trainer works offline from then on.
3. Import a scanned tactics book you own — see Puzzle books. This one can wait.

A Lichess token is only needed for the online extras — the online opening explorer, importing Lichess studies and puzzle history; see Settings. Everything else runs without one.

The vault

The vault is a folder of plain files: studies and games are PGN, notes are markdown, progress is JSON. Any editor opens them, Obsidian reads them as they are, and if this app ever goes away your chess opens in something else.

Backing up

Settings → Vault has “Download a copy”: one tar file of every document and the change history, named after the vault and the day, that any OS opens. Settings and tokens stay on the server. Copying the vault folder is a backup too — derived databases and indexes included. The derived things (the puzzle pool, reference game databases, indexes) can always be deleted and rebuilt; no database holds your work hostage.

Earlier versions

Every study, game and note carries a clock button in its header — Earlier versions (on a phone it sits with the other tools behind the title row's ⋯). Each save is kept automatically; pick a time to look at it and Restore this version brings it back. The version you have now is kept too, so you can always come back. A vault that keeps no history — a server without git, say — says so: “This vault is not keeping a history, so there is nothing earlier to show.”

Restoring, and starting over

• Settings → Deleted documents restores studies, notes and games that are gone entirely — Bring this back.
• Settings → Danger zone wipes the whole vault. It makes you type an arming phrase, then asks for the app password when one is set. There is no undo, so download a copy first.

What lives where

The Vault card in Settings shows the folder: its exact path, its size, and a row for each kind of thing in it. Copy the path from there.

Around the app, and Home

A left sidebar joins the pages on a wide screen, a bottom bar on a phone. Home leads with what you were last doing, and its arrangement is yours to decide.

Navigation

The sidebar, top to bottom: Games · Studies · Notes · Books · Puzzles (with Dashboard, Puzzle books and Themes under it) · Opening map · Insights · Tools (Board, Editor, Explorer, Workspace, Repertoire, Endgame drills — the Workspace row exists only on windows wide enough to hold that page; see The workspace) · Databases. The Puzzles and Tools sub-rows unfold only while that section is open. Below them sit the vault's name (the one given in Settings → Vault, else its folder's; the full path in the tooltip; unfolded only), the connection label (“This device”, your server's name, or “Offline”; wide windows only), the Settings gear, and the light/dark toggle. At the end of the brand row, beside the mark, “Fold the sidebar” folds the sidebar to its icons; folded, the same button on the first row of the column reads “Unfold the sidebar” and unfolds it, and hovering a row shows its name as a tooltip. Until you choose, the window decides: labels on a wide window, icons on a narrower one. One press keeps your choice on this device. Ctrl/⌘ B folds and unfolds it too, wherever there is a sidebar, and the keyboard list under ? names it (“Fold or unfold the sidebar”). In the desktop app the switch sits on the window's band instead; see Getting started.

A phone's bottom bar carries Home · Games · Studies · Puzzles · More; More lists Tools (Board, Editor, Explorer, Repertoire, Endgame drills) first, then Notes, Books, Opening map, Insights, Databases and Settings, in the sidebar's order. A tab returns to the page its section was on (a sidebar row does not: it always opens its section's first page); a second tap on the current tab goes up to the section's root, and from the root to the top of the page. On an iPhone the bar is a rounded capsule floating off the bottom edge, icons only. Drag along the bar and the pill follows your finger, the tab under it lights, and the app moves to whichever tab you let go on. On a page with a board the bar becomes that page's own controls; see On a phone.

Pages come back as you left them. Going into a note, a study, a game or a book and back, or switching tabs, returns to the shelf or page as it was, rows, scroll, search and filters included; the last three sections stay live. The Board, the Editor and the Workspace start fresh each time.

From anywhere, Ctrl/⌘ K opens the «Open anything» window; the desktop app's band carries an “Open anything…” button to it, and a browser's Home page a search button. With nothing typed, “Recent” names the documents this device opened last. Typing finds the sections (“Go to”, in the sidebar's order, Endgame drills among them) and every study, note, game, book and puzzle book in the vault by name, and by their text the notes, the comments in studies and games, and the titles of books and puzzle books that hold every word typed: names list first, and under them «In the text» lists each document with the sentence the words sit in and the match in bold. An “Actions” group holds the app's own verbs (the light, dark or system theme, the density, “Fold the sidebar”, “Keyboard shortcuts”), so each can be reached by name. Nothing found says “Nothing matches.”; on a desktop the window ends with its keys (↑ ↓ move, ↵ opens, Esc closes). On a phone the search button at the end of Home's title row opens the same window as a sheet.

Home

What Home is made of, top to bottom:

When the server does not answer, Home shows a “Vault server unreachable” card with a “Retry” button instead of drawing an empty vault.

Customise home

The sliders button (“Customise home”) opens a dialog that applies immediately — there is no save button. Inside:

• Cards — one switch per card the page can draw: Continue, Recent games, Set up your vault, Training, Puzzle books and Recent work. A card drawn only on a wide screen says so in its blurb (“Wide screens only.”).
• On the grid — per tile: “Move up” / “Move down” arrows, “Hide” (the crossed-eye icon), and a switch (off demotes it to the row below). There is no drag-and-drop; the arrows are the ordering.
• In the row below — the demoted destinations; their switch promotes them back to the grid.
• Off the page — the hidden ones, each with a “Bring back” eye.
• Reset to default, at the bottom.

The arrangement is stored on this device, not in the vault: a phone's home is its navigation and a desktop's is a dashboard, so each is arranged on its own.

Saving, and leaving

• A document header's save control has four states: Saved (a check) · Saving… (a spinner) · a Save button (unsaved changes — Ctrl/⌘ S does the same) · Retry save (failed, the reason in its tooltip).
• Leaving with unsaved changes raises the “Unsaved changes” question — save, Discard changes, or Cancel.
• Prefer changes written as you make them? Settings → Documents → Auto-save. Off by default.
• Windows open inside windows: the board's “Load a position” into a picture, say. A page opened inside a window slides in over it. The chevron in the title row steps back one page, while the X, Cancel, Escape, the platform's Back and a swipe all leave the whole chain. A confirmation is the exception: its buttons hand back to whatever asked it.

If a page hits an error it cannot recover from, a “Something went wrong” card offers Reload and Go home — nothing in the vault is affected. A single panel that fails says so in place (“This panel hit an error. The rest of the page still works.”) and offers Try again; everything beside it keeps working.

Keyboard and gestures

Press ? anywhere in the app for the shortcut list. The first table below is that list; after it come the habits the list leaves out.

The shortcuts

The board keys go quiet inside a text field or while a dialog is open — the open window owns the keyboard.

Not on the list

• Lists and tables — in a game table ↑ ↓ move the selection, Enter opens, Esc clears; in the game-details panel ← → Home End step through that game.
• Notes — typing [[ opens the wiki-link autocomplete: ↑ ↓ pick, Enter/Tab accept, Esc dismisses.
• Choosing a file — every dashed file box is a button: Tab to it, then Enter or Space opens the file chooser.
• Position from a picture — the image dialogs take a Ctrl+V paste.
• The mouse wheel — rolling it over the board steps through the moves.
• Press and hold — the board's previous/next move buttons repeat while held.

Drawing on the board

With the right button, drag for an arrow, click for a circle. Modifier keys pick the colour: plain = green, Shift/Ctrl = red, Alt = blue, Shift+Alt = yellow — these four are what PGN can store (in a study, drawing works in Edit mode). The engine's best-move arrow is a separate blue auto-arrow, so your drawings never clobber it.

The board

The Board, under Tools, is the free analysis board. Play moves and a tree grows — variations, comments, glyphs, arrows — while the panel beside it tabs between Moves, Engine and Explorer. What you learn here carries everywhere a board appears: studies, games, books, puzzles.

The Board starts fresh every time you open it: an empty board, the engine off, the explorer at its default. The exception is a position handed over by another page (the editor's Analyse, a game from your archive). If the board you left held moves or a loaded game, returning offers it back for a few seconds: “Started a new board”, with “Restore”, which puts back the moves and the move you were standing on — and, when you arrived through Tools › Explorer, points the explorer at that position. The engine stays off. The offer comes once, and reloading the page forgets it.

The board itself

• Moves go by drag or by two clicks (from-square, to-square). Promotion opens a piece picker. How castling is entered is a setting — Appearance → Castling: king two squares (g1) or king onto the rook (h1).
• The player bars on either side show names, ratings and clocks (when the PGN carries them). On the Board page the name fields are editable.
• The evaluation bar is drawn beside the board while the engine is on — always from White's point of view. The score is printed to one decimal at the leading side's end of it (#4 for a mate); the sign is left to that placement, and the tooltip carries the signed, more precise figure. On a phone, where the board is as wide as the screen, the bar lies along the top edge of the board instead and prints the same number at its leading end.
• When the current move carries a quality glyph, a coloured badge pins to its destination square — ! ? !! ?? !? ?! — and an open-book badge marks a book move.

The navigation buttons at a panel's foot

Where the panes are tabs — one at a time — they are pinned to the foot of the column, so they are in the same place whatever tab is open: Moves, Engine, Explorer, a study's Chapters. On a screen wide enough to show every pane at once they sit at the foot of the Moves panel. On a phone the bar at the bottom of the screen carries them instead, and nothing stands under the board.

The move tree (the Moves panel)

The panel is titled with the live opening name (“Starting position” at first). The mainline draws as number–White–Black rows, side lines as indented branches, comments as full-width rows. Clicking any move goes there. A small dot on a move means “Has a comment”; an open book, “Book move”. An empty tree says “No moves yet” over “Play a move on the board, or load a FEN or PGN.” and, where there is a keyboard, the two keys the panel answers under it (← → “Previous / next move”, f “Flip the board”).

At the foot of the panel is the move box (“Type a move…”). Type a move in any spelling (Nf3, g1f3, 0-0, e8Q) and Enter plays it on the board and empties the box; a move that is not legal stays in the box with “Not a legal move here” under it. This is the keyboard's way onto the board, and in the puzzle and book trainers a typed move is judged exactly as a dragged one. Settings › Appearance › “Move box” hides the row on this device.

A side line can be lifted two ways. Promote this line moves it one place up among the lines it sits beside, so a line nested inside another can be rearranged without being hoisted past everything at once — press it again and again and it ends on the mainline. Make mainline gets there in one. Both are in the panel's ⋯ menu at every width, acting on the move you are standing on; right-clicking a move offers the same two for that move. On a touch screen a long press does the same, except on iPhone and iPad, where it does nothing and the ⋯ is the way in. The Make mainline strip under the table, which appears whenever the cursor sits on a side line, is there from tablet width up.

The panel's header buttons, in order

Annotating

The annotation tools live in a pane at the foot of the Moves panel, in studies and games only, and only in Edit mode. The glyph palette comes in two groups — quality: ! ? !! ?? !? ?!, and assessment: ⩲ ± +− = ∞ ⩱ ∓ −+. One per group; pressing the active one clears it. Each glyph's tooltip names it (“Good move”, “Blunder”, “White is slightly better” and so on). The chevron beside the box (“Show glyphs” / “Hide glyphs”) folds the palette. The text box below is the comment on this move — at the root it becomes the chapter introduction, and there the glyphs and the chevron are gone with it, a chapter having no move to judge. Arrows and circles are not here: they are drawn on the board itself.

Typing [[ in the comment opens the wiki-link list above the box — the same list a note gets, and the same keys (↑↓ pick, Enter/Tab accept, Esc dismiss). A link written here reads as a link in the move list and shows up under the named document's “Linked mentions”. On a phone it works inside the comment sheet too.

Two things a comment cannot keep are rewritten as you type them. A } becomes a ) — a PGN comment ends at one and has no way to escape it — and anything shaped like [%eval 9.9] gets one space through it, or the prose would come back as an evaluation on the move, or an arrow nobody drew. A line under the box says so and clears itself.

Loading a position

The Load a position dialog takes three things: a FEN or PGN pasted into the field (Enter submits; while empty, a corner “Paste” button reads the clipboard), or a picture dropped on the dashed box — “click to choose, drop a file, or paste an image”. A screenshot or scan reads best; drag the four handles onto the diagram's corners and press Read position, ticking “Black at the bottom” when it is.

Game review

Engine review (the microscope — “judge every move (?!/?/??) and measure accuracy”) sweeps the whole game. Before it runs, a band under the move list offers it; on a phone that offer is a toast over the page for a few seconds instead, with an X. When it finishes, the strip under the move list holds:

• The evaluation graph — click or drag to jump; the move under the pointer marks itself with a blue dot and a guide line, so you see where a click lands before it does. Folds away.
• Per-side summaries: accuracy %, average loss, the book-move count (“known opening theory, not judged”), and how many !! ?! ? ?? each side earned — the verdicts land on the move list and the board too.
• Moves after the pieces run out — seven or fewer — are judged by the tablebase instead of the engine: on the result they left behind, not on how far the evaluation moved. A ?? is a move that turned a win into a draw or a draw into a loss, at any distance (mate in 5 becoming mate in 40 throws nothing away). There are no endgame inaccuracies, and no brilliancies. How many moves the tables judged sits beside the book count under a crown; accuracy and average loss stay the engine's own measurement. Settings → Tablebase switches this off with the rest.
• Close the review takes the strip away.

The engine

Stockfish 19 runs in the browser itself — no server, no internet. The Engine panel docks above the moves on a desktop and gets its own tab on a phone.

The panel header

Beside the word “Engine”, while it runs, sit the current score (in the text colour, not green or red: an evaluation is a quantity, not an outcome) and the depth readout. To the right, two controls:

Engine settings

The candidate lines

• Each line is a fixed-width score column and the variation in SAN. Clicking any move plays the line into the tree; hovering one (on a desktop) pops a mini-board preview of that point; under a thumb each row has a chevron (“Show the whole variation” / “Show one line”) to read past its first line.
• While it has nothing yet: “Thinking…”. A terminal position says so honestly — “Checkmate. There is nothing left to search.”
• Errors show with a warning triangle — even when the engine has switched itself off, the reason stays visible.

The explorer

What has been played from the current position — a move table with game counts and win/draw/loss, plus games you can open. Reach it as Tools → Explorer, or switch the Explorer panel on wherever a board is.

The panel header

Reading the table

The strip above names the ECO code and opening (“Out of book” where nothing does). Each row: the move in SAN, the game count (the exact number in its tooltip), and the win/draw/loss bar: the light segment is White wins, the grey middle draws, the dark one Black wins, and a segment prints its percentage only when it is wide enough to carry it. A screen reader hears the bar as one sentence, “White {w}% · Draw {d}% · Black {b}%”. Clicking a row plays that move. The top eight show; “Show all {n} moves” unfolds the rest.

Below the table, Top games (Recent games for My games, which lists newest first): a row opens that game, and one with an https source also carries an external link button named “{white} vs {black} on {host}, opens in a new tab (needs internet)”, with the address as its tooltip.

The tablebase

Once seven pieces or fewer are left, a Tablebase block appears above the move table — not statistics but the result. It gives the verdict for the side to play (“Win” · “Draw” · “Loss”, and “Cursed win” for a win the fifty-move rule turns into a draw), “White to move” or “Black to move”, and the distance as “DTM {n}” (to mate) or “DTZ {n}” (to the next capture or pawn move), both counted in half-moves. Under it, every legal move with its own verdict: winning moves first and shortest first, losing ones last and longest first — when nothing saves the game, the best move is the one that gives your opponent the most chances to go wrong. Clicking a row plays that move. A position that can still castle is in no table, so the block does not appear for one.

Answers come from Lichess's public tablebase — or from your own server, if you have set one in Settings — and are cached by your server for good, so an ending you have looked at once is answered offline afterwards. Which one answered is on the word “Tablebase”, under the pointer. Out of reach and not yet cached, the block becomes one amber line and “Try again”, and the explorer's own answer stays below it. Settings → Tablebase switches the whole thing off, or points it elsewhere.

The filters

• My games — Side (Any/White/Black), Result (All/Won/Drew/Lost), Time control (Bullet/Blitz/Rapid/Classical, multi-select), “Kept only” (only the games in your collection, not every archived one), Played between (dates). A live count sits under the controls.
• A reference database — Result, Strength (Any/2300+/2500+/2700+), Level, Player (with side and outcome conditions), Opening or ECO, Event, Played between.
• The Lichess database — Opponent strength (the rating bands); the Masters database has no filter window.

Past the table

• Search every game for this position — where the index ends, a scan of the whole database takes over: “Searching… {scanned} of {total} games” → “{n} games reach this position”. On an install with the native core it runs by itself, no button needed.
• Find this position in the databases browser — hands the position to the Games page's Databases tab, pre-filled, where relaxed and material search continue — Searching the databases.
• A database with no position index offers Index positions in the table's place.

The editor

Where any position gets set up — a diagram copied from a book, an exercise of your own, a structure laid from scratch. One button hands the finished position to the analysis board.

The piece palette

Six pieces per colour — one combined row above the board on a desktop (opponent's colour first), split above/below on a phone. Click a button to arm it as the tool — it shows as pressed, as Move and Erase on the toolbar do, and every square you click gets that piece — or press and drag to place one directly.

The toolbar

Position details

The panel's foot holds the legality line (a green “Legal position” check, or an amber line naming the problem), the full FEN, and Copy. Loading works here too — Load a position from FEN, PGN or an image — and reading a photo then fixing it up is the fastest way to copy a diagram. On a phone the details sheet commits only through Apply; closing it any other way reverts.

The workspace

Every analysis surface on one page: the board, the move list with the engine, the explorer with an Analysis panel — and the whole games browser as a full-width band underneath. It exists so that browsing games, consulting the explorer and analysing stop being page changes.

Nothing here is new, on purpose: every pane is the same component some other page shows one at a time, reading the same state. A position you were analysing on the Board page follows you in, and back out.

Wide screens only

The page's whole premise is simultaneity, so on a window that cannot hold its panes it steps aside: a card explains — “The workspace needs a window wide enough for the board, the moves, the explorer and the games browser side by side. On this screen each pane is a page of its own.” — and the sidebar's Workspace row is not drawn there at all. Widen the window and everything returns as it was: the state belongs to the app, not the page.

The layout

The top row is three columns: the board (as large as the window's height allows — every line it cannot use becomes a games-band row instead), the moves panel with the engine docked on top, and the explorer's column with the Analysis panel under it. The band below is the Games page's whole browser — Collection · Databases · Chess.com · Lichess, all four tabs, search, filters and the position hunt included.

Working in place

• One click on any band row puts that game on the board — archive games from your side — and the page goes nowhere. ↑↓ walk the rows, each game taking the board in turn.
• A collection game is a document: a double click (or Enter) opens its document page — annotating is a document's work, and the workspace board stays throwaway so browsing stays free. Database and archive games open in place even on a double click.
• The explorer's “Find this position in the databases browser” fills the band below with that hunt, instead of leaving the page.
• The keyboard's grammar: ←→ walk the moves, ↑↓ walk the games. Home and End jump the board to its start and end, and the board's jump buttons name those keys (“Start (Home)” · “End (End)”). f flips it.
• Loading a game over moves you played yourself raises a toast, “Loaded a game over your line”, that offers “Restore” for a few seconds.

The Analysis panel

The Analysis panel under the explorer is the Board page's review strip standing as a panel of its own: it offers “Review game” when a game lands, and when a review finishes it holds the evaluation graph (drawn taller here) and the per-side summaries. With nothing to show it says so: “Play moves or load a game, then run an engine review.” The switch in its header folds it — the same grammar as the explorer's own switch.

Studies

A study is a PGN document in chapters — an opening file, a set of exercises, a body of ideas. The shelf creates and imports them; opening one brings the board and its chapters together.

The shelf

The top row holds the title, with how much the shelf holds under it (“{n} studies”; while a search or the bookmark filter is on it reads “{shown} of {count}”, as in 3 of 12 studies), and its tools: the bookmark filter (“Show bookmarked only” / “Show all”), sorting (“Sort by”: Last modified · Title · Size, with a direction button), the view switch (“Grid view” / “List view”), and the create menu. The row below is search (“Search studies…”). On a phone there is no search row: a magnifier in the title row is the search, pressing it turns the title row itself into the field, and “Cancel” beside the field gives the title back. The create button draws as its plus alone on a phone. A card shows a preview board, the title and “{n} chapters” · “edited {when}” — a bookmarked one wears a left edge in the accent colour. Its ⋯ menu holds Rename · Move to a folder · Remove, with Bookmark first on touch (a desktop has the bookmark in the card's own corner, and a right-click on the card opens the same menu as its ⋯); on touch, swiping a card left removes it (undoable) and right bookmarks it.

The create menu

Inside a study

The header, left to right: back (“All studies”) · the title (double-click to rename) · the tag (“Other names for this study” — the comma-separated aliases, see Wiki-links) · the link (“Linked mentions”, only where something points here) · the clock (“Earlier versions” — see The vault) · the Edit toggle (“Show NAGs, comments and move tools” / “Hide the editing tools”) · the save control; on a phone the tag, the link and the clock fold behind one ⋯ in the same row. The pieces move whether you are reading or editing — Edit only brings out the annotation tools, so the board stays uncluttered when you are just stepping through.

The chapters panel

• The “Chapters” header carries the count, and its + adds one. Hovering a row (always, on touch) reveals its tray: Add a sub-chapter (top-level rows only) · Rename this chapter · Delete this chapter (only while more than one exists — and it warns “its sub-chapters move to the top level” when they would).
• A parent row's chevron folds: “Fold sub-chapters” / “Unfold {n} sub-chapters”. The row's own tooltip: “Double-click to rename”.

The rest is the board's own grammar: the move tree and annotation, the engine and its review, the explorer. Saving is a lossless round-trip, and a copy is parked in the vault so a browser that dies does not take the work with it.

Notes

Notes are markdown — and two things make them chess notes: live boards in the text, and wiki-links joining notes, studies and games.

Reading and writing

On a desktop a note opens ready to edit: click into the text and type. The header's Read (“Back to reading”) goes back to reading, where a plain click follows a wiki-link; while editing, Ctrl/⌘+click follows one. A phone opens a note to read, with no toolbar: its Edit (“Edit this note”) switches to writing, and the same spot becomes Done (“Back to reading”). The rest of the header matches every document: back, the title (double-click to rename), the tag (“Other names for this note”), the link (“Linked mentions”, only where something points here), the clock (“Earlier versions”), the save control; on a phone the tag, the link and the clock fold behind one ⋯. On a wide desktop window a note with two or more headings lists them in the margin left of the text, and a click on one scrolls to it.

The formatting toolbar

While editing only, pinned above the note. Ten buttons, in order:

Insert a board · Bold · Italic · Strikethrough · Code · Heading · Subheading · Bulleted list · Numbered list · Quote

A button lights while the caret sits inside its mark. The buttons work from the keyboard, and each tip names its shortcut: the board, “or type /board on a new line”; Bold Ctrl/⌘ B, Italic Ctrl/⌘ I, Strikethrough Ctrl/⌘ Shift S, Code Ctrl/⌘ E, Heading Ctrl/⌘ Alt 1, Subheading Ctrl/⌘ Alt 2, Bulleted list Ctrl/⌘ Shift 8, Numbered list Ctrl/⌘ Shift 7, Quote Ctrl/⌘ Shift B.

Boards in the text

Insert a board drops a ```chess fence: a real interactive board between paragraphs, holding a FEN or moves. The file stays plain markdown, so Obsidian shows the same block as code. A fence holding only a FEN draws that position in the note and on its card. A fence that cannot be read says “This board could not be read.” beside its text instead of drawing the starting position, and the board's load box refuses text it cannot read: “That could not be read as a FEN or a PGN.”

Wiki-links

Typing [[ opens autocomplete across notes, studies and games (↑↓ pick, Enter/Tab accept). A note links a study, the study links a game, the game links back to the note where you worked out what went wrong — the material becomes one connected body of work. The syntax is Obsidian's, so the links read there too.

Links are not only a Notes thing: [[ opens the same list in a move's comment — see annotating.

[[Target|shown]] reads as shown and opens Target; ![[Target]] unfolds as a card inside a note (inside a comment it reads as a plain link — a card wedged into a row of moves would push the moves apart). The tag in a document's header (“Other names for this study” / “Other names for this note”) takes other names, separated by commas, and the document answers to those too. “Save” or Enter keeps the names; “Cancel”, Esc or closing the window does not. Where two documents claim one name the app refuses to guess and asks which you meant. A link with nothing behind it is grey and dotted, and pressing it offers to make the game, study or note it names.

What links here

The link icon in a document's title row (“Linked mentions”) shows what points at it — from a note, a study or a game, with the icon saying which. Pressing one opens it, and for a study it opens the chapter the comment is in. Below, “Unlinked mentions” are places that write this document's name in prose without brackets; the Link beside one wraps that single occurrence. A document nothing points at carries no icon at all.

The shelf speaks the studies shelf's grammar — search, sorting, bookmarks, folders, the count under the name, the card's ⋯ menu (on a desktop a right-click on the card opens the same menu), and a create menu of New note / New folder. A card counts its links (“{n} links” · “edited {when}”) where a study's counts chapters.

Games

The Games page is four tabs — Collection · Databases · Chess.com · Lichess: the collection of games worth keeping, searching the reference databases, and your two online archives. On a wide screen the “Game details” panel stands beside them all — kept open where there is room for it, and arriving with the game you select where there is not.

The collection

• Search (“Search collection…”) and the bookmark filter on top, and a filter row under them: Whose games (Anyone's games · My games · Mine as White · Mine as Black) · Result · Notes (All games / With notes), then “More filters”. Below the tablet width the three selects live in the “More filters” window alone, and the button stands beside the search field carrying a count of what is on. The box speaks the same query language as the Databases tab — see Searching the databases. A right-click on a row gives Bookmark · Rename · Remove (undoable for a moment), with View online where a source exists; opening a game is the double click, not a menu item. Where rows are cards rather than a table, the same menu sits under the row's ⋯ and gains Preview the board and Game details in front — the work the panel beside a wide table does. On a phone the search is a magnifier in the title row (see below); “Cancel” beside the field empties it, puts the keyboard away and gives the title back. The same holds for the Databases tab; the archive tabs' username field closes with the name left in it.
• Import a game: paste a PGN: “Paste a PGN, or just moves: 1. e4 e5 2. Nf3 …”. Headers fill the detail fields (players, ratings, date, event) by themselves; Result is a segmented Auto · 1-0 · 0-1 · ½-½. Submit is Add to collection. A paste holding several games adds each as its own document: a line under the box counts them, and the toast says “Added {n} games” along with how many were already present or could not be read.
• Select… beside the count turns on selection: a checkbox on every row, “Select all” (what the filters show), a count, and Delete selected, which removes the lot under one undo. Esc or “Cancel” leaves it. The archive tabs and the reference databases select the same way, to add several games to the collection at once. On a phone the entry is in a game's ⋯ menu instead, and starts the selection with that game in it.
• Opening a collected game gives it a study's whole toolkit — variations, comments, glyphs, arrows, and its earlier versions.

The archives (Chess.com · Lichess)

• Usernames come pre-filled from Settings. Pick an Archive month and browse; “More filters” narrows by opponent, opening, dates, and the searched player's side and result. That window has no Player row: the player is fixed by the username you looked up. At phone width the month select leaves the search row and the window's own Archive month field takes its place, applied with the rest.
• Per game, Add to collection lives in the row's menu — a right-click on a table row, the ⋯ on a card row — or Select all new then Add selected for the lot (“Adding {done}/{total}…”). The entry dims once the game is in, and a card row carries an edge in the accent colour down its left as well. A fully collected month says so: “Every game shown is already in the collection”.
• A right-click on a table row opens the same menu the reference databases' rows have: “Open on the board” and “Add to collection”. A card row's ⋯ carries Add to collection · Game details · View online, the last only where the game has a link. Card rows print no time control: every game in a month is played at the same one, and it is on “Game details”.
• Browsed months are cached on disk — instant next time, and open offline (“offline, cached months only”). The inventory and its clear-all live in Settings → Browsed games.

The table, and the details panel

Every game list is the same table. Columns: White · Elo · Black · Elo · Result · Moves · ECO · Event · Date · Notation. Notation steps aside while the details panel stands beside the table, which prints the same moves in full. Elo is the two players' rating from the game header, the record of that game as the date is. Your seat is marked by your name in blue, and the winning digit of every result is bold, so a win and a loss do not differ by colour alone. An annotated game wears a notebook glyph in its White cell; a bookmarked one, an edge in the accent colour down its left. The nubs between headers resize columns (“Drag to resize · double-click to reset”). In the collection a heading is also the sort: click it to order the games by that column, click again to reverse, and the ordered column carries an arrow. A date, an Elo and a length come newest, strongest and longest first; a name and a code A to Z. The choice is kept on this device with the column widths. From the keyboard, a “Column widths” control before the table (unseen until it has focus) hands focus to the grips: ↑↓ walk them, ←→ step the width, Enter resets it and Esc comes back. One click selects (feeding the details panel) and a double click opens. The table is one Tab stop, entered on the selected row; ↑↓ carry the focus with the selection, so Enter opens the row the ring is on, and Esc behaves as the shortcuts page says.

The Game details panel: the two player rows (your side accented), the result badge, the opening (ECO and name), event and round, date · moves · time control · “View online” — then a coordinate-free preview board with its stepper (Start · Back · {idx} / {plies} · Forward · End) and the whole mainline as clickable SAN. On a phone the same arrives as a “{white} vs {black}” sheet. The pin in the panel's header (“Keep the panel open”) decides whether it holds its column with nothing selected; let go, it leaves with the selection, and the × beside it (“Close”) or Esc puts both away. It starts pinned on a window wide enough that the table loses no columns to it, and unpinned below that.

The four tabs are the page at every width; width changes only the dressing. A desktop adds the details column and the dense table, a phone gives the same tabs card rows (the third line is the opening's family and the date, with the full opening name in the row's tooltip) and opens a game's details from the row's own menu. Where the pane is wide enough to hold one line — the workspace's band, this page on a wide window — each tab's search, filters and count fold into a single row and everything under it is game rows; narrower panes keep the stacked bands described above. A phone goes one further: the tabs are drawn as chips, the count is the line under the title, and search, the bookmark filter and the filters are icons beside Import (on the Databases tab the same places hold search, the position search and the filters). Pressing the magnifier turns the title row itself into the search field, and “Cancel” beside it gives the title back; the Chess.com and Lichess username fields open the same way. Where there is more than one database, its name in the line under the title is the picker. The page scrolls as one column, as the shelves do, and a scroll up brings back a compact bar with the same icons and the chips. On a desktop “Import a game” stands on the title line, where the other shelves keep theirs; on a phone the create button is one press straight to the same import, since everything else it used to offer is a tab.

Searching the databases

The Games page's Databases tab searches a reference database the way a desktop chess database would — by text, by position, by material, by motif. The picker at the top chooses which database answers.

By text

One search box, speaking a small query language: player: · opponent: · white: · black: · opening: · eco: · event: · result: · year: · elo: — anything else stays plain text. Quotes hold a value's spaces together: event:"tata steel".

A qualifier's value colours itself in place — the whole query stays one line of text, edited like text. The field colours itself as you type but waits until you pause to warn; suggestions open unprompted and answer the keyboard, completing names and events from the database's own derived lookups; and while the box has focus a panel under it lists every qualifier with a live example. Picking a qualifier or a value from that panel puts the caret after what it added, with the field scrolled to show it. A query that cannot match anything — two scores, years that share no span, two names on one seat — or a term the surrounding filters leave no room for, says so rather than quietly finding nothing.

The Collection tab's box speaks the same language — the server compiles it to SQL for the reference databases, the browser answers it in the page over your own collection. “More filters” narrows things down further:

By position

The board-scan toggle beside the search box (“Search by position, material or motif”) opens the hunt row. Flip “Search by” to Position — “Paste a FEN” or “Set the position up on a board” — and Enter in the FEN field, or the ↵ button at the row's end, runs it. On a phone's Games page the same controls open as a sheet rather than a row: running a search closes it, the line under the title says what was found, and pressing the toggle again brings the sheet back with “Clear”. In the sheet the controls break in two, the kind and the field on the first line and the match rung with ↵ on the second; the button stays beside its select and never wraps alone. Two ladders then define what a match means:

The rungs nest only up to a point. An Exact position match is already a Same pawns & material match, and every game Same pawns & material finds is found again by each of the three rungs above it — each forgets one more thing. Past that they fan out rather than stack: Same pawn files & material frees the pawns' squares but keeps the forces, Same material keeps only the forces, and Same pawn structure keeps only the pawns (and lets the turn go too). So loosening from Exact through Same pawns & material into any one of the three can only add games — but switching between those three can lose and gain games at the same time.

By material

Material offers twenty-six presets, or Custom… — per-side, per-piece counts (“0–1”, “1–2”, “2+”). The presets are the symmetric endgames from pawns to queens, the unbalanced ones such as “Rook and pawns vs rook” and “Queen vs two rooks”, “Queenless middlegame” and “Major pieces only”, and the imbalances from “A pawn up” to “Three minor pieces vs queen”. An imbalance takes a side, “Which side has it”: “A queen up” for White or for Black; a symmetric endgame reads the same either way and shows no side. With no constraint at all the app objects: “Pick at least one count, or every game matches.”

By motif

Motif is two lists. “Patterns” holds twelve. The board patterns — Isolated queen's pawn (exactly one pawn on the d-file, none on c or e, and the opponent without a d-pawn), Doubled pawns, Passed pawn, Rook on the seventh, Fianchetto (the bishop with its pawn in front), Knight outpost (on its fifth or sixth rank, supported by a pawn, out of every enemy pawn's reach) and Opposite-coloured bishops (the ending) — ask whose it is (“Whichever side” / White / Black) and “How long it must hold”, with “Held 4+ moves” the default. Opposite-side castling and Same-side castling are found at the position after the second castle. Greek gift (a bishop taking h7 with check beside a king on g8), Underpromotion and En passant are the side that played the move's, remembered from the move on. “Pawn structures” holds twenty-nine, in opening order: the Giuoco Pianissimo and the Ruy Lopez, the Open Sicilian and its shapes (Scheveningen, Najdorf, Dragon, Sveshnikov, Maróczy bind, Hedgehog), the French, Caro-Kann and Pirc, then the Queen's Gambit and Carlsbad, Slav, Catalan, London, Stonewall, Nimzo-Indian, Grünfeld, King's Indian and Benoni — each a pawns-only sketch run on the Same pawn structure rung, so it finds what drawing that sketch on the board would.

The results

• Exact position search answers from the index, instantly. The relaxed and material hunts are scans, with visible progress — “Searching… {scanned} of {total} games” — and run many times faster when the database's Fast search is on (Managing databases).
• Found games land in the same game table: Open on the board · Add to collection · Game details. An overflowing result stops honestly: “{n}+ games found. The list stops here.”.
• The explorer's “Find this position in the databases browser” lands here with the position pre-filled.
• On the Insights page (sidebar, or More on a phone), the “Compare with a database” card checks your recent games against a database's players: “You play {mine} ({mineShare}), they answer {top} ({topShare} of {total})”. When nothing stands out it says so: “Nothing to flag…”. A row opens its position on the board. While an engine pass runs, Insights keeps its tables standing and only the accuracy figures wait; with games not yet analysed a strip says “{n} games are not analysed yet: their results count, their accuracy does not.” The month chart's bars can be pressed to print that month's figures under the chart.

Managing databases

Reference databases are built from PGNs you upload. Once built, one serves as an explorer source, a search target, a field for the repertoire trainer and a yardstick for the opening map. The page is one panel with two views — Databases and PGN files.

Building one

1. Upload. The PGN files view's Upload PGN files opens a window of that name; drop .pgn files on the big target inside it (“Choose .pgn files” / “Or drop them anywhere in this box”). Anything else is refused: “Only .pgn files can be uploaded here”. A refusal prints inside the window, which states the name rule: “A file name may use letters, digits, dots, dashes and underscores, with no spaces.”
2. Tick and build. Nothing is ticked until you tick it. Ticking files raises a “{n} selected” bar at the bottom; Build opens the “Build a database” window, which lists the ticked files and asks one name, or none: the box reads “Name, or leave blank for “{name}”” (“Letters, digits, dots, dashes and underscores, with no spaces.”), and says “Indexing {n} files into one searchable database of whole games.” Building keeps going if you leave the page. While it runs, a band above the list reads “Building {name}: {phase}, {percent}%” and carries a “Stop” button; during the replay itself the band reads “Building {name}: {done} of {total} games”, and an Optimise or an index pass runs on the same band, “Optimising {name}…” / “Indexing {name}…”, with the same Stop; Stop asks first, “Stop building “{name}”? What was indexed so far is discarded.” A failed build says “The build failed.” on its band.
3. Grow it. A row's + (“Add games to this database”) opens the “Add games to “{name}”” window and feeds it more files: “Only the games it does not already hold are indexed.” Building over an existing name offers “Add to it: index only the games it does not already hold.” first and “Replace: build this database again from the picked files.” second; with Replace chosen the button reads “Replace “{name}””.

Per-row tools

Row states: “{n} games” · “no position index” · “index behind”. A desktop install ships a starter database (one month of elite games, 38,977 of them) so the explorer answers from day one — deleting it is final. A server install or source checkout starts empty.

Books

A shelf of your chess books: upload any PDF and read it beside the analysis board. The signature is the diagram buttons — every printed diagram grows a button that sets its position up on the board.

The shelf

The create menu holds Import a PDF (the “Import a book” window — drop the PDF, set a title and folder, “Import”) and New folder; beside it, search, sorting (Title · Added · Size · Last read) and the bookmark filter. The count under the title reads “{n} books”, or “{shown} of {count}” while a search or the bookmark filter is on. A card shows “Page {page} of {pages}” once you have opened it, “{n} pages” before — your place is kept per book. Its menu, under ⋯ or a right-click on the card on a desktop: Read · Rename · Move to a folder · Read diagrams · Replace PDF… · Remove from the shelf (Bookmark joins the list on touch; a desktop has it in the card's corner) — replacing the PDF keeps your page, and removing warns “any puzzle book read from it is kept”. One line under the shelf, where there is a pointer to drop with, says “Drop a PDF on this page to import it.”

The reader's toolbar

In a narrow pane the middle tools fold into the ⋯ menu — contents, search and the board's fold alone always stay out.

The page's text can be dragged over and copied, as in print. A PDF with no text layer (a scan) has nothing to select, as it has nothing to search.

A big scan takes a few seconds to open the first time. The reader keeps it open behind you, so going back to the shelf and returning is immediate; after five minutes with nobody reading it the book is let go, and the next visit opens it again.

From diagram to board

The small button off a diagram's top-right corner (“Set up this position”) opens the same menu every row's ⋯ opens: a list under the button on a desktop and an iPhone, a bottom sheet on an Android phone, headed “Who is to move?”, with “White to move” and “Black to move” under the king icons and “Edit position…” under a pencil. The position then lands on the board beside it. The board side's toolbar (wide layouts): Load a position · Reset to the starting position · Fix this position in the editor · Show the moves under the board · Open on the board page — the editor being the road to fixing a square the recognition misread. “Show the moves under the board” lays the moves played out as one line under the board: click a move to return to that position, a sideline where the book branches sits in brackets, and the choice is remembered on this device. The button reads “Hide the moves under the board” while the strip is showing, which it is until you put it away. A phone splits into Book / Board / Edit tabs, the bottom bar carrying the open tab's tools — and standing empty on Edit, so the global navigation cannot return under a half-placed position.

A tactics book can go a step further: import it as a puzzle book and its diagrams become solvable puzzles. Read diagrams is on every book's card (whenever a read is not already running); a book that has a puzzle book gains Open the puzzle book besides.

Puzzles

The trainer runs on the Lichess puzzle database (CC0). The first visit offers to fetch and build it; from then on it is fully offline — over six million puzzles living on this device.

First visit: building the pool

With no database the page shows “No puzzle database yet” and a Download and build button. The stages report themselves (“Downloading the puzzle dump” → “Building the database” → “Indexing”), and — “This keeps running if you leave the page. It takes a few minutes.” — it does.

Solving

“White to move” / “Black to move”, and “Find the best move.” A right move brings the reply (“Opponent is moving…”); a wrong one, “Wrong move. The board rolls back.” Difficulty and themes stay hidden until you finish. The panel's buttons:

Puzzle settings

The settings row opens a dialog for Difficulty: Any · Adaptive (“follows your solving”) · Easy · Medium · Hard · Expert, and Theme (“All themes”, or one). The Themes page (“Puzzle themes”, with its “Find a theme” search) is the door to training a single theme. The search also finds group names and Lichess spellings, its result line reads “{n} of {total} themes match” beside “Clear search”, or “No theme matches it.” when nothing does, and Enter opens a single match. With no puzzle database the page says “No puzzle database yet” with “Set up”; when the server does not answer, the hub draws “Could not load…” cards with “Try again”.

The review ladder

What you miss comes back after a day, then 3, 7 and 21 — and retires after a clean solve at every step. The review banner explains itself: “Reviewing, not counted. Each clean solve spaces the puzzle further out, and enough in a row retire it.”

The dashboard

Puzzles → Dashboard: Attempts · Solved · To review, the “Attempts by difficulty” breakdown, book progress, and a history of every attempt — filtered by outcome and difficulty, any puzzle replayable via “Replay puzzle #{id}”. The page leads with its one button: “Review puzzles · {n} due” when something is waiting, “Review failed puzzles” with the count when nothing is due but misses remain, “Train” otherwise (with “Nothing due. The next review lands {when}” under it while the schedule holds something); under the history, last on the page, sits “Wipe history”. The history is one Tab stop: the arrows move between rows and Right opens a row's position preview. A phone gets a hub screen instead: three rows for “Themes” (with the theme “Worth practising: {theme}”), “Puzzle books” (the book you were last in, with its bar) and “Dashboard” (“Solved today: {n}”), and under them three boards, “Next puzzle”, “Missed puzzle” and your book's next puzzle. Pressing a board opens that very puzzle; the first one is how you start training, and carries the difficulty word.

Puzzle books

Hand the app a scanned PDF of a tactics book you own, and an ML pipeline — running entirely in the app — reads the diagrams, parses the printed solutions, verifies them by replaying every move, and imports each puzzle with an honest fidelity tier. Nothing leaves this device.

The import

1. Puzzles → Puzzle books → New book → Import PDF. Two options up front — “Ask the engine where the book cannot be read” and “Try harder on boards that fail” — and one request: “Import only a book you own.”
2. Progress reports page by page: “page {page}/{pages}, {n} diagrams so far” — “nothing leaves this device, and you can keep using the app while it runs”. Pause loses nothing (“Paused at page {page} of {pages}. Nothing is lost.”); the next visit offers “Carry on from page {page}”.
3. The review step: “{n} diagrams found. Untick any false positives, then add the rest as drafts.” Each has “Keep this diagram” and “Show the scan”; Add {n} as drafts finishes.
4. The report is honest by tier: “{n} puzzles imported with their solutions” · “{n} numbered diagrams had no solution we could read.” · “{n} had a square misread, found by the book's own solution.” What could not be read is not discarded — it stays a draft with its evidence attached (the original page scan), to finish by hand against the scan. Nothing is imported on a guess.

Re-importing an existing book asks: “This book already holds {n} puzzles. What should the import do with them?” — update in place (progress survives) or clear and rebuild.

Training from a book

The book page keeps its title on a phone and at a large text size, and the due review (“Review puzzles · {n} due”) is its one filled button. The ⋯ menu on the title row holds “Rename”, “Read the book”, “Read diagrams” and “Reset all progress in this book”; on a phone it also holds “Import PDF” and “Add puzzle”. A tile tells a screen reader its state, its tier and its tries.

• The book trainer is explore-then-submit: “Explore freely. Only the mainline is judged on submit.” The verdicts judge against the book's answer, fairly — “Exactly as the book has it.” / “Correct so far, but the book line goes further.” / “Off the book at the end, but the engine approves.” / “The marked move is where the line goes wrong.”
• Review rides the same spaced ladder as the main trainer (“Review puzzles · {n} due”); cycles are Woodpecker-style — the whole book in passes, every puzzle once per pass, scored by first attempts, “Cycle {n}” and past passes kept.
• Add a puzzle opens manual entry — three tabs, Diagram / Board / Solutions: make the board match the diagram, then “Record the solution, every move for both sides.” An opponent move clicked becomes “any move” (the book's ~), and Verify will “Ask Stockfish whether every solver move really wins”. A misread puzzle is fixed via “Correct this puzzle against the book scan”.

Repertoire trainer

Practise an opening against the field — the statistics of real games. Replies are drawn weighted-random from what was actually played in each position, so you meet the common moves often.

Setting up a game

During, and after

• The status line leads: “Your move.” → “Your opponent is replying…”. Stepping back mid-game: “Reviewing an earlier move. Step to the end to keep playing.”
• In a drill, a move your study does not play is refused: “Your study plays {moves} here. Try again.” A session ends one of three ways — “End of your prepared line. Every move matched the study.”, a gap (“The field answered {san}, played in {pct}% of games here, and your study holds no reply.”), or “This line has run past the database. You are on your own now.” A position the line passes through where the field also plays a reply your study does not answer is flagged in amber as it goes: “The field also plays {san} in {pct}% of games, and your study has no answer to it.” That reply is drawn on the board as an arrow and enters the moves panel as a variation beside the reply that was played, with “{pct}% of games. No answer in the study.” as its comment. Replies, refusals, gap notes and the ending are announced to a screen reader, and the move box keeps focus while the reply is fetched.
• In free play, when the line leaves book the engine takes over the replies and the game keeps going.
• Afterwards: an engine verdict, Analyse, then Save line to study (free play) or Go to study (drill), and New game.

The record

What you fumble comes back on the puzzle trainer’s own schedule — tomorrow, then 3, 7 and 21 days out after each clean recall, then graduated. The idle panel counts “{n} positions due for review”, says “Nothing due. The next position comes back {when}” when today is clear, and Drill a position due for review deals the most overdue first. A position fumbled minutes ago is drillable before its date comes round — the panel counts those as “{n} positions to review”. A gap is fixed by editing the study, not by drilling — so it is reported beside the pool as “{n} replies with no answer yet”, not drilled. The whole record clears through the “Forget the drill record” confirmation.

Endgame drills

Tools → “Endgame drills” (under Tools on a phone's More page) lists the games hunt's material presets by family: “Pawns and minor pieces”, “Rook endgames”, “Queen and major pieces”, “Middlegames and material edges”, and “Your own”, whose one row, “Custom material”, opens the same editor the hunt uses. Nothing is recorded. Opening a class draws a random position the tablebase calls a win for the side to move, or a drawn one with moves that lose in it, whichever is the sharper test the class has, and you play that side: the panel's headline says “White to move” or “Black to move”, as the puzzle trainer's does, the row under it names the family being drilled and returns to the list when pressed, and the tablebase answers with the move that takes longest to lose. A move that lets the win slip ends the attempt and arrows the move that would have kept it (“{san} lets the win slip. {best} keeps it.”); checkmate ends it the other way. Once it ends the headline is the verdict: “Checkmate”, “The win slipped” or “Stopped”. The ?? and ! badges and the kept-win arrow stay on the analysis board, and the kept-win move is a variation you can step into. When it ends the board becomes the analysis board with the engine, as the trainer's does, beside “Try again” and “Next ending”. “Skip” draws another position without recording anything, and “Analyse” beside it ends the attempt where it stands, with no grade, and turns the board into the analysis board with the engine the same way. When no tablebase can answer, the page says which case it is and “Open Settings” lands on the Tablebase card. While the attempt runs the panel says “Keep the win. A move the tablebase calls a draw or a loss ends the attempt.” When the position is a draw to hold, the tablebase attacks with the move that leaves you the fewest moves that still hold, the panel says “Hold the draw. A move the tablebase calls a loss ends the attempt, and ten held moves end it as a draw.”, a losing move ends it with “The draw slipped” (“{san} lets the draw slip. {best} holds it.”), and ten of your moves held, or the attacker left with nothing to mate with, end it with “Draw held”. The “Analyse” button's tip reads “Ends the attempt and opens the engine”. The demo has no tablebase and says “The demo reaches no tablebase. In the app, the drill plays against whichever tablebase Settings names.”

The opening map

Your preparation as a shape rather than a list: the moves that define your repertoire, one map per colour, drawn as a constellation or a tree. Link a study and everything below it is derived live from that study — so what the map claims you have prepared is what you have.

The map menu

Icons in the header on a desktop, the “Map menu” disc in the bottom-right corner on an Android phone, the same compass on the title row on an iPhone. In order:

Wheel/pinch zooms, dragging pans, and dragging a dot pulls the web. From the keyboard, + and - zoom, 0 fits the map, Shift+arrows pan, and selecting a dot with the arrow keys slides it into view. A label is drawn whole or not at all; none fades. The search field (“Search moves and opening names”) finds both; on a phone it folds into a magnifier on the title row, as the shelves' do.

Charting moves

• Add — “Every reply the field plays here. Tap one to chart it”, or type your own (“Type a move…”).
• Grow (“Chart what your games already play from here”) — choose the games (“From which games”: time controls, “Kept only”), set the floor (“Chart moves seen in at least” a count), preview (“{n} moves to chart, ending in {k} lines”), chart them all.

The field

Check coverage against… names the yardstick — your own games, the Lichess database (with a strength band), or a local reference database. From then on “gap badges, dot sizes and the statistics table all read from it”: dots size by how often each move is actually played, replies you have no answer for get badges, and the “Against the field” panel counts “{pct}% met” — the share of the field that runs into your preparation.

One move's panel

Select a dot and the opening catalogue names it, while its panel shows what covers it:

• Preparation depth — “Prepared {plies} plies deep, {lines} lines” / “Prepared to move {reached}, target {target}” — derived live from the linked studies. Intended depth (1–40 full moves) sets the target.
• Linked games, studies and notes — joined via “Link a game, study or note” (one chapter alone works too), or started fresh with “New study from this line”. Only studies get to say what is prepared; notes come along for the reader.
• Drill health — “{n} fumbled in drills, drill from here” · “{n} drill gaps, the studies lack an answer”.
• Games that left here — your games that left book at this position: the deviating move (“You left the book with this move” / “They left the book with this move”), “Chart it on the map”, “Analyse to the deviation”.
• Prepared, not on the map — continuations your studies hold that the map does not chart yet; a tap charts one.

The action row at the panel's foot, in order: Add · Grow · Drill (needs a linked study — “Link a study first. A drill needs prepared moves.”) · Prune (“Show only this line”, in the tree) · Analyse · Delete (“Delete this move and everything after it? Linked studies are untouched.”).

Insights

Your own games, summed. The page reads the same corpus as the explorer's “My games” source, your collection plus every Chess.com and Lichess month you have browsed, and shows your results by colour, time control and opening, and where each game left the opening catalogue. Nothing here is a verdict: the tables are counts of what happened, and a rating is nowhere on them. It sits beside the opening map in the sidebar, and under More on a phone.

The engine pass

The page fills once your games have been through the engine. Before that it is an empty state, “Not analysed yet”, with one button, Analyse games. Press it and the app's own engine walks your games move by move at a fixed depth, in this window, while you use the rest of the app. A strip under the title carries a progress bar, “{done} of {total} games analysed” and the time left; Pause in the header stops it and becomes Resume analysis. The server keeps every game finished, so a reload or a later visit picks up where it stopped. While a run is going the tables stand and only the accuracy figures wait. When it ends the strip leaves and the games count under the title gains “analysed at depth {d}”. Games that arrive after a pass do not close the page: an amber strip says “{n} newer games are not analysed yet: their results count, their accuracy does not.” and Analyse new games beside it analyses just those.

Filters

The explorer's filters plus a date range, in one row. The row remembers itself on this device, and Clear filters appears at its end whenever anything is narrowed. In order:

When no game fits, the page says “No games match” and offers Clear filters. With no games of yours at all it says “No games of yours yet”: a game counts once your side in it is known, and Open games leads to the Games page.

The cards

In page order. Every table of figures has a games count, a won/drew/lost bar, “Score” and, once the pass has run, an “Accuracy” column.

Settings

Everything you do as a user happens in the app — nothing needs a shell. The ? on each card's title (“Open the manual”) opens this page in a new tab, and the card names jump to their card: on a wide window they stand in a column to the left of the settings, follow the page as it scrolls and light the card you are reading, and the one you clicked until its scroll ends; on a narrower window they sit in a row at the top. Card by card, in order:

The page's last line is the summary: Vault: {path} “Every game, study and puzzle lives there as plain files. Display settings live on this device.”

On a phone

There is nothing to install: open your server's address in the phone's browser and add it to the home screen — a full app (a PWA) with an icon, splash screens and an offline shell. It wants the vault on a server — the second way from Getting started.

What changes

• The bottom bar carries Home · Games · Studies · Puzzles · More, the rest under More. On an iPhone the bar is a translucent rounded capsule floating off the bottom edge, icons only, with the page scrolling under it; it shrinks as you scroll down, and a scroll up or a tap on it brings it back. On Android the bar is docked to the edge. Each page's create/add actions sit on the title row as on a desktop (“Create”, or “Import” on Games); where a page can make several things the button opens an action sheet, or on an iPhone a menu under the button. On Android only the opening map keeps a round button in the bottom-right corner, the compass, which opens its menu; on an iPhone the compass is on the title row. A row's ⋯ menu goes the same way: a menu hanging from the button on an iPhone, a bottom sheet on Android.
• On a page with a board, the bar becomes that page's controls — the way the Chess.com and Lichess apps do it: move navigation on boards, puzzle navigation in the trainer, the open tab's tools in the book reader, the selected move's strip on the opening map. Leaving the page brings the tabs back.
• The panels beside a board become tabs — Moves / Engine / Chapters / Explorer — and the detail panels become bottom sheets. The tab strip is the panel card's own header, and the open tab sits on a filled segment that follows your thumb as you swipe. Swipe sideways across a panel to turn to the next tab, without reaching back up to the strip; it stops at either end, and a gesture that starts on a row that scrolls sideways or in a text field belongs to that control instead.
• The comment box opens as a sheet, and while a note is being edited the bottom bar steps aside for the keyboard.
• The opening map's move panel opens at its full height; a drag down stops at half the screen, with the map in view above it, and a drag past that closes it. A sheet becomes more of a card the lower it rests: its top corners round further and its sides stand a little in from the edges; at full height it is flush, as before. A finger drawn up anywhere on a half-height sheet raises it to full height again, and the sheet's content scrolls only once it stands at the top. The one-field questions (a new study, a new note, a rename) have no Cancel on a phone, where the sheet's handle is the way out.
• The page's name is a large title with the page's buttons beside it, and it scrolls with the page. On the shelves and on Games a scroll up brings back a compact bar with the same buttons, and a note's header likewise leaves while you read down and returns on the first scroll up. A page opened from a list slides in from the right and its back chevron slides it out; switching tabs is a cut, the new page there in one frame, while the bar's pill slides between tabs. Going back from a game or a study flies the board into the thumbnail it came from. All of it stays still under the system's reduced-motion setting.
• A tab returns to the page its section was on; a second tap on the current tab goes up to the section's root, and from the root to the top of the page.
• Pages come back as you left them: going into a note, a study, a game or a book and back, or switching tabs, returns to the shelf or page as it was, rows, scroll, search and filters included, and the last three sections stay live. The Board, the Editor and the Workspace start fresh each time.
• The search button at the end of Home's title row opens the quick switcher (“Open anything”): what this device opened last, the sections, every study, note, game, book and puzzle book by name, and the documents that hold the words typed, by their text; see Around the app.
• A document's tools (other names, what links here, earlier versions) fold behind one ⋯ in the title row; the row keeps the name, Edit and Save.
• The review offer is a toast over the page for a few seconds, with an X, instead of a band in the moves pane. Settings → Appearance → More options → Review offer switches it off.
• A two-finger spread does not enlarge the page. The app holds its own size the way an app does, so two fingers on the shell change nothing. To make text bigger, use the browser's or the device's own text size setting; the app follows it. The places that read two fingers themselves keep them: a book's page, the evidence pages and the opening map each enlarge what they show.
• The first, previous, next and last arrows under the board are 22px under a thumb.

Every device on the same server sees the same things: games and progress. Only the display settings (theme, board, density) and the home arrangement are per-device.

Common questions

What is different in the demo?

The demo is the real app running on a sample vault inside your browser tab — as its banner says: “Demo: a sample vault of your own. Edit anything, and a reload puts it back.” What needs a server of your own is absent: profile, password and 2FA, the Lichess token (and so importing from Lichess), and building databases or uploading books — the reference database and the sample book ship read-only instead, and Insights opens with its figures in place. A puzzle book made from that sample book ships with it. Install or host the app and those places become real.

The app will not open on macOS

The macOS build is unsigned. The first launch needs right-click → Open; after that it opens normally.

What works offline?

On a local install: essentially everything. The engine, fonts and icons ship with the app, and there are no runtime CDN calls. What needs the internet is the online database (Lichess), fetching new archive months, and importing from Lichess — archive months you have browsed open from the cache.

Where is my data?

All of it in the vault folder, as plain files. The Vault card in Settings shows the exact path, and its “Download a copy” is a backup; so is copying that folder — see The vault.

More than one device?

Move the vault to a server — a folder copy — and every device becomes a client: a phone as a PWA, the desktop app pointed at the server through its first question (or Settings → Desktop app). Same games, same progress, whichever device you opened.

Where to ask more

Bugs and questions go to GitHub issues. For how things work under the hood, the repository's docs folder holds detailed write-ups of the repertoire trainer, the opening map, the databases and book import.