# Cosimo User Guide

Cosimo helps you study prompt and response pairs with spaced repetition. It is designed for keyboard and screen reader use.

## Quick Start

Cosimo is a portable application. To install it, expand the release zip file into the folder where you want Cosimo to run, then start `cosimo.exe` from that folder. To upgrade, close Cosimo, expand the new release zip over the existing Cosimo folder, and allow application files to be overwritten. Release packages should not overwrite user data such as `cosimo.ini`, personal decks, review databases, reports, sidecar audio directories, or backups.

When Cosimo starts, it opens the last deck you used. On a new installation, that is normally `decks/deck.cosimo-deck` beside the executable. Use `File -> Open Deck` to open another `.cosimo-deck` file. If the deck file does not exist, Cosimo asks whether to create it.

To add material, use `Card -> Add Card` for one card, or `Card -> Add Card Batch` for repeated entry. A card has a prompt, which is the question or cue you see first, and a response, which is the answer you check yourself against. Keep prompts specific and avoid duplicate prompts.

The ready screen shows a summary, a list of card prompts, and a status bar. The status bar reports total cards, cards available now, and whether a scheduled study session is due or roughly how long remains until the next one. The ready screen refreshes about once per minute. Press `F5` to refresh it manually.

Use `Start` to run the scheduled study session. During a normal study session, Cosimo first shows the prompt. You can rate your prediction:

- `1`: don’t know
- `2`: probably don’t know
- `3`: probably know
- `4`: certainly know

You can also choose `Reveal Response`, or press Space, to show the response without recording a prediction. After the response is shown, choose recall feedback:

- `1`: Again
- `2`: Hard
- `3`: Good
- `4`: Easy

The recall feedback is what Cosimo uses most directly to schedule the card. Press `0` during a normal study session to end it early. Completed attempts are still saved.

Use `Force Start` for extra practice when you want to ignore the schedule. Use `Study Flagged` for cards you have marked for manual attention. Use `Start Exam` for typed-answer testing from a random sample, and `Start Quiz` for multiple-choice practice. Exam and quiz sessions are report-only: they do not change the spaced-repetition schedule.

After studying, Cosimo shows a summary. Choose `Save Report` to write a text report into the `reports` directory, or `Continue` to return to the ready screen.

Other useful features:

- `Study -> Learning Dashboard` or `Ctrl+L` shows deck-wide progress, calibration, workload, and diagnostic information.
- `Tools -> Options` configures language, minimum cards per session, backups, review audio, notifications, tray minimisation, and dashboard calibration.
- `Tools -> Generate Audio` can create Opus or WAV review audio when a deck has voice metadata.
- `File -> Export Full Deck`, `File -> Full Deck Backup`, and `File -> Restore Full Deck` handle compressed deck bundles for sharing, migration, and manual backup.
- `Deck -> Sync` can upload or download the current deck through a configured sync server.
- `Help -> User Guide`, `Help -> Project Wiki`, and `Help -> Report Bug` open local or project help resources.

## Menu Organisation

Cosimo groups commands by what they act on:

- `File` is for opening decks, recent decks, compressed bundle export, backup, restore, and quitting.
- `Deck` is for deck-wide operations such as properties, metadata, sync, bulk reversibility, and duplicate-prompt repair.
- `Card` is for actions and details for the selected card or the current card in a study session.
- `Study` is for starting study sessions, flagged study, exams, and the learning dashboard.
- `Tools` is for application options, audio generation, and review-database maintenance.
- `View` controls how the ready-list is sorted.
- `Help` opens the guide, project links, and the About dialogue.

## How Cosimo Studies Cards

Spaced repetition is a study method based on reviewing material at increasing intervals. When something is new, difficult, or recently missed, it should come back soon. When something is easy and consistently remembered, it can wait longer. The goal is to spend more time on material that needs attention and less time repeating what is already secure.

Cosimo records your answers and ratings and uses that history to decide which cards are due.

Cosimo uses a few terms consistently:

- A `card` is one prompt and response pair in the deck.
- A `study item` is one schedulable direction of a card. A normal card has one study item; a generated reverse card adds a second study item with prompt and response swapped.
- A `study session` is one run from Start, Force Start, or Study Flagged through to the summary.
- A `question` is one prompt shown during a study session.
- An `attempt` is one stored answer with recall feedback and, optionally, a confidence rating from before the response was revealed.

Cosimo still uses `review database`, `review history`, `scheduled review`, and `review audio` for established parts of the application. In those phrases, review refers to the broader spaced-repetition process or to stored study history, not necessarily to one whole session.

Cosimo stores each completed attempt in the review database. For each card, it looks at the review history and estimates when the card should come back.

In general:

- cards with no review history are due immediately
- missed or wrong cards come back sooner
- answers marked `Hard` progress more cautiously than answers marked `Good` or `Easy`
- cards that are recalled easily wait longer

Cosimo uses an FSRS-6 scheduling algorithm. It tracks each card’s difficulty and stability. Repeated correct answers make the card more stable and lengthen the interval, while missed or wrong answers move the card back towards learning. Short learning steps are automatic: new cards normally use 1-minute and 10-minute learning steps, and review-state cards marked `Again` use a 10-minute relearning step. Cards marked `Again` are not automatically repeated at the end of the current session; Cosimo waits until the scheduled learning or relearning step is due.

The four recall buttons have the same labels in every state, but their scheduling effect depends on whether the study item is new, learning, review, or relearning:

- `Again` means you did not recall the answer well enough. On a new or learning card, it keeps the card in learning and restarts the first short learning step. On a review card, it is a lapse: the card moves into relearning and is due after the short relearning step. On a card already in relearning, it keeps the card in relearning without counting another lapse.
- `Hard` means you recalled the answer, but with difficulty. On a learning or relearning card, it keeps the card in that short-step state rather than graduating it immediately. On a review card, it remains a successful recall but schedules a more cautious interval than `Good` or `Easy`.
- `Good` means you recalled the answer acceptably. On a learning card, it moves to the next learning step, or graduates the card to review if the learning steps are complete. On a relearning card, it returns the card to review. On a review card, it schedules the normal next interval.
- `Easy` means the answer was recalled easily. On a new, learning, or relearning card, it graduates directly to review. On a review card, it schedules a longer interval than `Good`.

Decks first studied with older beta versions may contain existing schedule rows from Cosimo’s earlier FSRS-like scheduler. Current versions migrate those derived schedule rows by replaying the stored review history with the current FSRS-6 scheduler. This does not delete review history, but due dates and dashboard lapse diagnostics may change once when an older review database is opened by a newer Cosimo build.

In scheduler terms, a `lapse` is narrower than any `Again` answer. It means a card that had already reached review state was marked `Again` and moved into relearning. `Again` while a card is new, learning, or already relearning is still recorded as an answer, but it does not add another scheduled lapse.

The exact interval is automatic. You do not need to manage dates yourself. For ordinary review-state cards, Cosimo may vary longer intervals slightly and deterministically. This avoids cards repeatedly clumping on the same future date. Short learning and relearning steps are not varied.

The minimum cards per session controls how many cards Cosimo tries to include when you press `Start`. For example:

- if the minimum is `0`, Cosimo includes only cards that are due
- if the minimum is `10` and only 6 cards are due, Cosimo adds 4 random extra cards
- if 20 cards are due and the minimum is `10`, Cosimo includes all 20 due cards

The minimum is not a maximum. Due cards are not hidden just because there are more of them than the minimum.

When a session starts, due learning and relearning cards are shown before ordinary review cards, then new cards follow. Within the learning/relearning and review groups, the most overdue cards are shown first. Cards with the same due time, or due times within about one hour of each other, are ordered randomly within that group. New cards are also ordered randomly, so cards added in thematic groups are not shown in deck order.

Good cards are specific and unambiguous. A prompt should ask for one thing, and the expected response should be short enough that you can judge it consistently. Avoid duplicate prompts: one prompt should identify one card only. Duplicate responses are fine, but generated reverse cards need extra care because a duplicated response would become a duplicated reverse prompt.

## Cards and Decks

A deck is a file containing cards. Cosimo deck files use the `.cosimo-deck` extension.

You can edit cards inside Cosimo, or edit the deck file directly in a text editor. The deck file stores prompts, responses, deck metadata, and card markers such as non-reversible status. Review history and ratings are stored separately.

Deck files also contain a small numbered marker at the end of each card, such as `=1=`. Leave that number in place when editing by hand. It lets Cosimo keep the card’s review history even if you change the prompt or response text. If you add new cards by hand, end each new card with `===` instead of inventing a numbered marker. Cosimo will choose a safe unused ID the next time it opens the deck. Use `=i=` instead of `===` for a manually added card that should be non-reversible. Cosimo may also write `next_card_id` in the deck metadata; leave it in place, since it prevents new cards from reusing older IDs after cleanup. When Cosimo opens an older deck, it backs up the original according to your deck backup setting and upgrades the deck file to the current format.

Use `Deck -> Deck Properties` to view the deck format version and optional metadata fields such as title, author, description, URL, voice choices, and whether automatic audio generation is disabled. Use `Deck -> Edit Deck Metadata` to edit those metadata fields. The same dialogue also contains deck-specific sync settings such as visibility. The authenticated sync flow gets the owner from `Deck -> Sync -> Log In`. The optional local device name and default sync server URL are application settings in `Tools -> Options`, because they identify this Cosimo installation rather than a particular deck. If you copy the whole Cosimo folder to another computer or USB drive, change the local device name in one of the copies so future sync uploads can be told apart.

The default deck is `decks/deck.cosimo-deck` beside the Cosimo executable. On Windows portable installs, keep your decks in the `decks` folder beside the application. If the default deck is missing, Cosimo creates an empty one. You can open another deck from `File -> Open Deck`. If you choose a deck file that does not exist, Cosimo asks whether to create an empty deck there.

When Cosimo closes, it remembers the last opened deck and opens it again next time. It also keeps up to eight recently opened decks in `File -> Recent Decks`, omitting the current deck. If there is only one other recent deck, Cosimo shows it directly in the `File` menu instead of placing it in a submenu. It stores this and other application settings in `cosimo.ini` beside the executable. Cosimo also remembers the ready-list filter and sort mode. If Cosimo finds older `cosimo-settings.txt` or `cosimo-last-open-deck.txt` files, it migrates them into `cosimo.ini` and removes the old files.

### Adding and Editing Cards

Use `Card -> Add Card` to add one card. The editor has prompt and response fields. It also has a `Mark as non-reversible` checkbox. Leave it unchecked for an ordinary card; check it when the card should never be used to generate a reverse card.

For repeated entry, use `Card -> Add Card Batch`. Enter a prompt and response, then press `Ctrl+Enter` from either field to add the card and return to the prompt field. Pressing Tab from the response field also adds the card and returns to the prompt field when both fields contain text. Press Escape to close the batch dialogue. Batch add does not show the non-reversible checkbox, to keep the repeated-entry flow short.

Use `Card -> Edit Selected Card` to edit the selected card from the ready list. After a card has been revealed during a study session, this command changes to `Card -> Edit Current Card`. You can also choose `Edit Card` or press `e` at that point. Cosimo opens the same editor used elsewhere, saves the card text, and returns you to the post-response rating step. The scheduling decision is still made only after you choose the recall feedback rating.

Use `Delete` or `Card -> Remove Selected Card` to remove the selected card from the deck. Removing a parent card also removes its generated reverse card from the prompt list, because the reverse card is derived from the parent card. The reverse review data remains in the database, but it is only useful again if you restore a deck backup containing the original parent card.

Use `Alt+Enter`, `Card -> Card Details`, or the prompt-list context menu to show details and statistics for the selected card.

### Duplicate Prompts and Responses

Avoid duplicate prompts. A prompt should identify one card only. Cosimo refuses ordinary add and edit actions that would create a duplicate prompt. If a deck is edited by hand and duplicate prompts are introduced, Cosimo opens the deck with a warning. Use the `Duplicated prompts` filter to find them, or use `Deck -> Resolve Duplicate Prompts` to choose the response to keep for each duplicated prompt; the other cards with that prompt are removed from the deck, and their review data becomes dormant unless the review database is scrubbed. During duplicate resolution, `Skip Prompt` leaves the current duplicated prompt unchanged and continues with later duplicated prompts. `Cancel Resolution` stops the process entirely. Prompts already resolved remain changed.

Duplicate responses are allowed. They are often useful when different prompts share the same answer. The restriction is only on generated reverse cards: from each group of cards with the same response, at most one card may have an active generated reverse card. Otherwise, the generated reverse cards would have the same prompt and it would no longer be clear which original card was being asked. Cosimo blocks making or editing reverse cards when that would create this ambiguity. Mark a card non-reversible if its shared response should never be used as a reverse prompt.

### Reversible and Non-Reversible Cards

Use `Card -> Add Reverse Card`, or press `Ctrl+R` while the prompt list has focus, to add a generated reverse card. A reverse card asks for the original response and expects the original prompt. Reverse cards have their own scheduling state and review history. Cosimo blocks making a card reversible when another card with the same response already has an active generated reverse card, because the reverse prompt would be ambiguous. Reverse cards are marked with `(reverse)` in the prompt list and can be found with the `Reverse cards` filter. Removing a reverse card removes only the generated reverse direction; it does not remove the parent card. The reverse card’s review data remains in the database and is used again if you make the parent card reversible later. When a generated reverse card is selected, the card menu and context menu offer removal of that reverse direction, not marking the parent card non-reversible.

Use `Card -> Mark Selected Card Non-Reversible` when a card should not have a generated reverse direction. This writes a marker into the deck file, removes any active generated reverse card for that parent card, and prevents `Make Possible Cards Reversible` from adding it again later. Use `Card -> Clear Selected Card Non-Reversible Mark` to remove that marker. The card then becomes eligible for manual or bulk reversal again, provided its response is not already used by another active generated reverse card. Non-reversible cards are marked with `(non-reversible)` in the prompt list, can be found with the `Non-reversible cards` filter, and show the non-reversible marker on the card details state line. When a non-reversible card is selected, the menus offer clearing the non-reversible mark rather than making a reverse card directly.

Use `Deck -> Make Possible Cards Reversible` to mark every currently eligible card reversible in one operation. Cosimo asks for confirmation and tells you how many cards can be changed. Cards that are already reversible, cards marked non-reversible, and cards whose response group already has an active generated reverse card are excluded. If review database backups are enabled, this operation refreshes the retained review-database backup before writing and the confirmation warns that the retained backup will be overwritten.

Use `Deck -> Undo Last Bulk Reversal` to remove only the reverse cards created by the latest bulk reversal. Manually created reverse cards and earlier bulk batches are kept. Parent cards and reverse review history remain in the database.

### Suspending, Deferring, and Flagging

Use `Card -> Suspend Selected Card`, the context menu on the prompt list, or `Ctrl+S` while the prompt list has focus, to keep the selected card in the deck while preventing it from appearing in normal or forced study sessions. The prompt list marks suspended cards with `(suspended)`. Suspended cards can still be found with the `Suspended cards` filter and unsuspended from the same menu, context menu, or shortcut. Suspended cards are also ignored when the status bar reports whether a review is due now or when the next review is due.

Use `Card -> Defer Selected Card until Tomorrow`, or the context menu on the prompt list, to postpone the selected card temporarily without changing its stored schedule. A deferred card remains in the deck and returns automatically when the deferral expires. While deferred, it is marked with `(deferred)`, appears in the `Deferred cards` filter, and is excluded from scheduled sessions, forced sessions, ready-screen counts, and status-bar due calculations. Use `Card -> Clear Selected Card Deferral`, or the context menu, to make it available again immediately.

During a study session, before revealing the answer, use `Ctrl+D` or the `Defer Card until Tomorrow` button to postpone the current card and move on. Deferral is not available after the answer has been revealed. If every card in the session is deferred before any answer is recorded, Cosimo shows a notice that no cards were studied.

Use `Card -> Flag Selected Card`, the context menu on the prompt list, or `Ctrl+F` while the prompt list has focus to flag or unflag the selected card. During a study session, `Ctrl+F` flags or unflags the current card. The review screen also has a Flag/Unflag button in both phases, after the relevant rating buttons. Flagging is for manual follow-up: use it when a card may need editing, feels confusing or ambiguous, has a dubious answer, or otherwise needs attention after the session. Flagging does not affect scheduling or whether the card appears in normal study. Flagged cards are marked with `(flagged)` in the prompt list and can be found with the `Flagged cards` filter.

## The Ready Screen

When Cosimo starts, it opens on the ready screen. This screen shows:

- how many cards are in the deck
- how many cards are scheduled now
- the minimum cards per session
- the review database file
- a list of card prompts

If the minimum cards per session causes Cosimo to add extra cards that are not due yet, the scheduled count also shows the due-card count in parentheses. For example, `Scheduled now: 10 (6 due)` means a study session would include 6 due cards and 4 extra cards to reach the minimum.

The main window status bar gives a short overview: total cards, cards due now, and either that a review is due now or roughly how long until the next scheduled review. Durations are rounded up to speech-friendly units such as `2 days`, `4 weeks`, or `3 months`. During a session, the status bar changes to session context, such as scheduled study session, unscheduled study session, exam, or quiz, with current progress.

While the ready screen is open, Cosimo refreshes the ready summary, list filters, and status bar about once per minute. A card that becomes due while the application is open will therefore become available for `Start` without closing and reopening the deck.

Useful keys on the ready screen:

- `Alt-S`: start the scheduled study session
- `Alt-T`: force-start all cards not suspended or deferred
- `Alt-X`: start an exam session from a random active-card sample
- `Alt-Z`: start a multiple-choice quiz session from a random active-card sample
- `Alt-L`: move to the text filter for the prompt list
- `F5`: refresh the ready summary, list filters, and status bar
- `Ctrl+L`: show the learning dashboard
- `Alt-Q`: quit
- `Alt+Enter`: show details and statistics for the selected card
- `Delete`: remove the selected card from the prompt list
- `Ctrl+S`: suspend or unsuspend the selected card
- `Ctrl+F`: flag or unflag the selected card
- `Ctrl+D`: defer the selected card until tomorrow, or clear its deferral
- `Ctrl+R`: make the selected card reversible, or remove the generated reverse card

Use `View -> Deck Order`, `View -> Next Scheduled Review`, `View -> Last Reviewed`, `View -> Prompt Text`, `View -> Response Text`, or `View -> Estimated Recall` to choose how the prompt list is sorted. Use `View -> Ascending` or `View -> Descending` to choose the direction. The checked View menu items show the current sort criterion and direction. When you choose a different sort criterion, Cosimo resets the direction to that criterion’s default. Last reviewed defaults to descending, putting the most recently reviewed cards first and new cards at the bottom; ascending last reviewed puts the oldest reviewed cards first and still leaves new cards at the bottom. Estimated recall uses the same scheduling estimate as the learning dashboard; ascending estimated recall puts cards estimated as less likely to be remembered first and leaves cards without an estimate, such as new cards, at the bottom.

The text filter narrows the list by matching text in the prompt or response. The filter combo box controls which type of cards are shown, including flagged cards, duplicated prompts, duplicated responses, non-reversible cards, deferred cards, problem cards, asymmetry issues, high-confidence failures, and low-confidence successes. Its counts follow the current text filter. The duplicated-response filter is especially useful before making cards reversible.

The Card menu can also act on the cards currently shown in the ready list. Use `Flag All Shown Cards` or `Unflag All Shown Cards` to mark a whole filtered set for manual follow-up, for example all problem cards before choosing `Study Flagged`. `Suspend All Shown Cards` and `Unsuspend All Shown Cards` work the same way. Cosimo asks for confirmation and reports how many shown cards will actually change; cards already in the requested state are left unchanged.

The `Problem cards` filter shows active study items that appear unusually troublesome in the current deck. It waits until an item has at least 4 attempts, then uses review behaviour rather than raw age. A card can appear there if at least 2 of its last 5 attempts were `Again`, if its lifetime `Again` rate is in the deck’s highest 20% and at least 25%, if its scheduled lapses per attempt are in the deck’s highest 20% and at least 20%, or if its scheduling difficulty is in the deck’s highest 20% and at least 8 on the FSRS 1-10 difficulty scale. Suspended and currently deferred study items are not shown there.

The `Asymmetry issues` filter is for reversible cards. When both directions have at least 4 attempts and one direction is substantially weaker, the filter shows the weaker study item. Cosimo compares a lightly smoothed strict recall rate, where only `Good` and `Easy` count as recalled, and treats a gap of 30 percentage points or more as substantial. This is useful when, for example, seeing an Indonesian word and remembering English is easy, but producing the Indonesian word from English is still unreliable.

The `High-confidence failures` and `Low-confidence successes` filters use recent confidence-rated attempts. `High-confidence failures` shows active study items where you recently chose `Probably know` or `Certainly know` but then did not recall the answer under the active calibration recall rule; the latest confidence-rated attempt is enough, or at least 2 of the last 5 confidence-rated attempts. `Low-confidence successes` shows active study items where at least 2 of the last 5 confidence-rated attempts were `Don't know` or `Probably don't know` followed by an answer that counts as recalled under the active calibration recall rule. With the lenient rule, `Hard`, `Good`, and `Easy` count as recalled; with the strict rule, only `Good` and `Easy` do. Suspended and currently deferred study items are not shown in either filter.

The card details dialogue shows the prompt, response, card ID, current card state, attempt count, last attempt, scheduling state, availability, estimated recall now, recent recall, lapse summary, and attempt history for the selected card. Card state combines visible markers such as suspended, flagged, deferred, reverse, has reverse, and non-reversible on one line. Availability explains whether a card is new, scheduled for later, ready for an ordinary scheduled review, or waiting for a learning or relearning step. When there is a scheduled time, the availability line includes both the relative time and the exact UTC timestamp.

Generated reverse cards show the parent card ID, because editing the parent card in the deck also changes its generated reverse direction. Date fields in the summary, such as last attempt and schedule last updated, are shown first as a complete relative duration, such as `1 day, 1 hour, 1 minute, 1 second`, followed by the exact UTC timestamp in parentheses. Past dates use the same complete relative duration followed by `ago`. The attempt history list at the bottom uses exact UTC timestamps only.

## Study Sessions

There are three normal study-session commands:

`Start` uses the schedule. It shows due cards first. If fewer cards are due than your configured minimum cards per session, Cosimo randomly adds extra cards from the rest of the deck.

`Force Start` ignores the schedule. It puts every card that is not suspended or deferred into a random order. Use this when you want to study even though no cards are due, or when you want a longer practice session.

`Study Flagged` starts an unscheduled study session through flagged cards only. This session includes flagged cards whether or not they are currently scheduled, but excludes cards that are suspended or deferred. The order is randomised, and the session does not clear the flags; remove flags manually when the cards no longer need follow-up. The button is disabled when there are no flagged cards available to study.

When a prompt is shown, you can rate how likely you think you are to know the response:

- `1`: don’t know
- `2`: probably don’t know
- `3`: probably know
- `4`: certainly know

This is your prediction before seeing the response.

You can also choose `Reveal Response`, or press Space, to show the response without recording a prediction. This is stored as `Not answered` in the session summary.

After you rate your prediction or reveal the response directly, Cosimo shows the response. Then rate what actually happened:

- `1`: Again
- `2`: Hard
- `3`: Good
- `4`: Easy

This feedback is what Cosimo uses most directly to schedule the card. The same recall rating can have a different scheduling effect depending on whether the card is still in a short learning step or has already reached ordinary review state; see `How Cosimo Studies Cards` for the details.

If you notice a mistake after the response is shown, choose `Edit Card`, use `Card -> Edit Current Card`, or press `e`. Cosimo opens the same editor used elsewhere, saves the card text, and returns you to the post-response rating step. The scheduling decision is still made only after you choose the recall feedback rating.

At the end of a study session, Cosimo shows a summary for that session:

- how many cards were studied
- total time and time per card
- counts and percentages for prediction ratings, including responses revealed without a prediction
- counts and percentages for recall feedback ratings

If an older session or future study mode contains repeated questions for the same study item, Cosimo shows the fuller distinction between unique cards, questions answered, time per question, and time per unique card. The normal current study modes do not repeat `Again` cards in the same session. A card and its generated reverse direction count as separate studied cards.

Cards deferred before the answer is revealed are not counted as answered questions in the session summary.

Choose `Save Report` to write a text copy of a normal session summary to the `reports` directory beside the executable. Cosimo creates the directory if needed. Normal report filenames use the deck file name without its extension and the session finish time in UTC, for example `Indonesian-2026-05-03-06-04.txt`. If a report with that name already exists, Cosimo adds a numeric suffix instead of overwriting it. The report text includes the full deck path.

Choose `Continue` to return to the ready screen.

## Exams and Quizzes

`Start Exam` samples from the active deck instead of using the schedule. Suspended and deferred cards are excluded. Cosimo asks you to choose a number of questions or a percentage of active cards, then randomly selects and orders the cards to reduce cues from deck order.

If the deck has generated reverse cards, exam setup includes a study-direction choice: standard only, reverse only, or both directions. If the deck has no generated reverse cards, this choice is hidden and the exam uses the standard direction.

During an exam, Cosimo shows each prompt and asks you to type the response. It does not show feedback while the exam is running. Exact answers are counted as correct automatically. At the end, for each answer that was not an exact match, Cosimo shows the prompt, your answer, and the expected response, then asks whether the answer should count as correct.

If the `Exact` checkbox is selected when starting the exam, non-exact answers are not graded manually. They count as incorrect, and Cosimo shows each one for review with the prompt, your answer, and the expected response. Choose `Next` or press `Alt-N` to continue reviewing inexact answers, or choose `Summary` to go straight to the exam summary.

If the `Timed exam` checkbox is selected, enter a whole number of minutes for the exam. The remaining time is shown in the status bar. Cosimo plays a very short tone at each 10% boundary of the time limit. When time runs out, any text currently in the answer field is submitted, four short tones play, and Cosimo shows a time-out notice with the number of submitted answers. The notice starts with its message focused; tab to `Next` to continue to grading, answer review, or the summary.

When a non-timed-out exam finishes with at least one submitted answer, Cosimo plays two long tones and shows an `Exam Finished` notice before grading, answer review, or the summary. This gives users who are relying on exam audio a clear boundary between answering questions and checking answers.

During an exam session, choose `End Exam` to stop after the answers submitted so far. If no answers were submitted, Cosimo shows a notice.

Exam sessions show a separate exam summary. It reports selected questions, submitted answers, correct answers and percentage correct, exact matches, accepted non-exact answers, incorrect answers, total time, time per question, whether the exam ended early, and whether a timed exam expired. Exam summaries do not change the review database. Choose `Save Report` to write a text copy of an exam summary to the `reports` directory. Exam report filenames add `-exam`, for example `Indonesian-exam-2026-05-03-06-04.txt`.

`Start Quiz` is also unscheduled and report-only. It is intended for multiple-choice recognition practice, such as preparing for external tests that use quiz-style questions. Cosimo samples active cards randomly and excludes suspended and deferred cards. Unless the requested quiz size makes this impossible, it avoids putting both directions of the same reversible card in one quiz, so one question does not cue the other direction.

If the deck has generated reverse cards, quiz setup includes a study-direction choice: standard only, reverse only, or both directions. If the deck has no generated reverse cards, this choice is hidden and the quiz uses the standard direction.

During a quiz, Cosimo shows the prompt and a list of response choices. Choose one answer and submit it. Feedback is withheld until the end. After the quiz, Cosimo shows each submitted answer with the prompt and your selected response. If the selected response was wrong, it also shows the correct response. Choose `Next` or press `Alt-N` to move through the answer review, or choose `Summary` to go straight to the quiz summary. Quiz mode does not record attempts, change card schedules, or add failed answers back into the same session. It needs at least four distinct answer choices in the current study direction, so forward questions draw choices from responses and reversed questions draw choices from prompts. Prompts from cards marked non-reversible are not used as choices for reversed questions.

Quiz sessions show a quiz summary with selected questions, submitted answers, correct and incorrect answers, percentage correct, total time, time per question, and whether the quiz ended early. Quiz summaries do not change the review database. Choose `Save Report` to write a text copy of the quiz summary to the `reports` directory. Quiz report filenames add `-quiz`, for example `Indonesian-quiz-2026-05-03-06-04.txt`.

## Learning Dashboard

Use `Study -> Learning Dashboard`, or press `Ctrl+L`, to show a deck-wide learning summary. The dashboard is split into separate read-only sections so you can tab between the summary, distribution, workload, diagnostics, and activity areas instead of reading one long field. It reports several kinds of information:

- card counts by scheduling state: new, learning, review, and relearning
- counts of available cards, and how many of those are already scheduled and due now, ignoring suspended and deferred cards
- model-based recall estimates for active cards with scheduling data
- estimated recall distribution, including median, weakest-card average, and recall bands
- workload forecast for the next 24 hours, 3 days, 7 days, and 30 days, with estimated study time when recorded timing data is available, plus cautious summary statements about workload shape and pressure
- confidence calibration from your pre-response predictions and later recall ratings
- recall trend, lapse counts, and conservative recent-trend statements when enough data exists
- diagnostics such as at-risk cards, repeated lapses, high-confidence failures, and recent learning retention
- study activity, including days with answers, stored answers, answers in recorded sessions, repeated-item counts when older sessions contain them, time spent in completed sessions, recent recorded study time, and average study time per active study day when timing data exists
- deck-card first-seen information, which helps compare newly introduced material with cards that have reached review state

The recall section is an estimate from Cosimo’s scheduling model, not a direct test result. For each active card with scheduling data that is not suspended or deferred, Cosimo uses the last review time, the stored stability, and the actual scheduled interval to estimate how likely you are to recall the card now. New cards without scheduling data, suspended cards, and currently deferred cards are not included in this estimate. Learning and relearning cards use their short scheduled interval as the effective 90% point, so a card due after a short failed-card step does not look safer than it is.

`Available now` counts active cards that are not suspended or deferred and can be studied immediately. This includes new cards, which Cosimo can place in a study session immediately, and cards with existing schedule data whose due time has arrived. `Of these, already scheduled and due now` is a subset of `Available now`: it counts only available cards with existing scheduling data. It uses the same due-time boundary as `Available now`, so a card due at the exact time the dashboard was generated is included. The dashboard puts `Available now` first because it is the operational number: how many cards can actually be studied now.

`Average estimated recall` is the average of those per-card estimates. The dashboard also shows the median estimate and the weakest estimated cards so an average does not hide a small set of weak material. The weakest-card average is the average estimated recall of the lowest 10% of estimated active cards, rounded up so at least one card is included. `Likely known` counts estimated cards at or above 90% recall. `Mostly stable` is 70-89%, `Fragile` is 50-69%, and `Very low` is below 50%. `At-risk cards` counts the fragile and very-low bands together. These numbers are best used for triage and trends, not as a promise that exactly that percentage of cards will be answered correctly in the next session.

The workload forecast shows how many active cards are scheduled now and within the next 24 hours, 3 days, 7 days, and 30 days. These counts are cumulative: a card available now is also included in the later horizons. Suspended cards and deferred cards are excluded. When Cosimo has recorded session timing, the forecast also estimates study time from the current average time per unique card studied. This is only an estimate: it reflects repeated attempts in previous recorded sessions, but it cannot know how many learning or relearning steps will become due during a future session.

The Summary section describes the shape of the next 7 days of workload only when at least 5 cards are forecast. If at least half of the 7-day workload is due within 24 hours, Cosimo says most of it is due within 24 hours. If at least three quarters is due within 3 days, Cosimo says most of it is due within 3 days. Otherwise, Cosimo says the workload is spread across the week. When timing data exists for the last 7 days, the Summary also compares the estimated 7-day workload with your recorded study time in the last 7 days. If the difference is under 5 minutes and under 20% of the recent recorded time, Cosimo describes the estimate as close to recent study time; otherwise it describes it as higher or lower and shows both durations.

The calibration section treats your prediction before seeing the response as a target interval for whether you will recall the answer, not as a precise percentage. `Don't know` means a 0-5% recall target, `Probably don't know` 5-32%, `Probably know` 68-95%, and `Certainly know` 95-100%. The middle range is deliberately uncovered; reveal without a confidence rating if you do not want to make a prediction. The recall rule is configured in `Tools -> Options`. The lenient rule counts `Hard`, `Good`, and `Easy` as recalled, while `Again` counts as not recalled. The strict rule counts only `Good` and `Easy` as recalled. The dashboard shows the active rule before the calibration figures. The target recall range is the average of the target intervals for answered confidence ratings. The observed recall rate is what actually happened under the current recall rule. Calibration is within target if observed recall falls inside the target range, under-confident if observed recall is above the range, and over-confident if observed recall is below it. The per-confidence lines show the same comparison for each confidence rating. Cards revealed without a prediction are counted separately.

In the diagnostics section, `High-confidence failures` means you chose `Probably know` or `Certainly know` and then did not recall the answer under the active recall rule. This is a sign of overconfidence. `Low-confidence successes` means you chose `Don't know` or `Probably don't know` and then recalled the answer under the active recall rule. This is a sign of underconfidence. `Answers` counts stored answer events; one card can contribute more than one answer. `Cards affected` counts how many cards have at least one such answer. Parenthesised recent counts use the last 7 days: they say `all recent` if all counted answers or cards are recent, `none recent` if none are recent, or otherwise give the number of recent answers or cards. `Cards with significant recent overconfidence` and `Cards with significant recent underconfidence` use the stricter recent-pattern rule used for the ready-list diagnostic filters: the latest confidence-rated attempt is enough for overconfidence, or at least 2 of the last 5 confidence-rated attempts; for underconfidence, at least 2 of the last 5 confidence-rated attempts must match.

The recall trend section counts stored answers for cards in the current deck. `Overall recall` uses the ordinary dashboard rule that `Hard`, `Good`, and `Easy` count as recalled, while `Again` counts as not recalled. The feedback lines show percentages first, followed by counts in parentheses. The recent window compares the last 7 days with the previous 7 days; Cosimo only makes a qualitative trend statement when both windows contain at least 5 answers. A change of 5 percentage points or more is described as improved or declined; smaller differences are described as broadly stable. Reverse-card `Again` rate trends use the same 7-day windows, 5-answer minimum, and 5-point threshold, but a falling `Again` rate is better and a rising `Again` rate is worse. The lapse lines come from the current scheduling state of active cards and help identify whether the deck contains material that repeatedly falls back from review state into relearning. These scheduled lapses only count `Again` on cards that had already reached review state; ordinary `Again` rates are reported separately. Retention statements about recent learning count recently learned cards that have not had a later `Again` answer. Cosimo needs at least 5 recently learned cards before it describes recent retention; 90% or more retained is `retained well`, 70-89% is `mostly retained`, and below 70% is shown as follow-up lapses.

When timed session data exists, the Summary section includes average study time per active study day so this headline metric is visible without tabbing to the full activity section.

Cosimo records the first time the review database sees each physical deck card. This is not necessarily the card’s true creation date: existing decks will have their current cards recorded when the feature first sees them. For this reason the dashboard describes it as cards first seen by this review database. Once the database has older observations, the Summary can show a `Deck flow` line for the last 7 days: how many deck cards were first seen, and how many standard-direction cards reached review state. This is descriptive information only. It is meant to help you judge deck growth and learning throughput without Cosimo telling you whether to add more or fewer cards.

The study activity section is based on recorded attempts and study-session summaries. `Stored answers` counts individual stored answers. `Days with answers` counts UTC days on which at least one answer was recorded. Session, answer, and time totals labelled as recorded sessions come from completed session summaries. Study-time durations use seconds, minutes, hours, days, weeks, and years; Cosimo does not use months because their length varies. `Timed study days` counts UTC days with at least one completed session summary and is the basis for average study time per active study day. Recent recorded study time and recent recorded questions compare the last 7 days with the previous 7 days. This describes actual study activity recorded in completed sessions; it is not a historical forecast of how many cards were scheduled. The Summary describes recent study time as higher, lower, or broadly similar to the previous 7 days when timed session data exists; differences under 5 minutes and under 20% of the previous window are treated as broadly similar. If older data predates session summaries, the dashboard shows `Older answers without session timing` so the stored-answer total is not confused with the smaller timed-session total. That line is hidden when the value is zero. The same section also reports how many physical deck cards have been first seen by this review database, first-seen counts for the last 7 days, previous 7 days, and older observations when enough history exists, and active standard deck cards that have not yet been studied.

Use the dashboard’s `Save Report` button to save the complete dashboard report in the `reports` directory. The saved text uses Markdown-style section headings and includes every dashboard section, even though the dialogue shows them in separate fields. The report file name uses the deck name and the UTC time when the dashboard was opened, and the report includes the full deck and review database paths. Use `Copy to Clipboard` to copy the same complete report text to the clipboard.

If the deck has generated reverse cards, the dashboard adds a standard/reversed comparison section, because one direction can be much easier than the other. If the two estimated recall averages differ by less than 5 percentage points, Cosimo describes the directions as similar.

## Audio

Audio support has two separate parts. Playback uses existing Opus files, and legacy WAV files, while you are studying, previewing cards, or reviewing exam answers. Automatic generation uses `voice.exe`, either from the command line or through `Tools -> Generate Audio`, to create Opus or WAV files from installed speech voices.

Review audio playback is optional and supports `.opus` files, falling back to legacy `.wav` files with the same card ID and side when no Opus file exists. Configure it in `Tools -> Options -> Audio during study`:

- `No audio`: Cosimo ignores card audio.
- `Manual`: if the current prompt or response has audio, Cosimo indicates that audio is available and shows a `Play/Stop Audio` button.
- `Automatic`: Cosimo plays prompt audio when a prompt appears and response audio when a response appears during ordinary review. The same button can stop or replay the current audio.

The separate `Guiding tones for automatic audio` option adds short orientation cues when automatic audio during study is on: one short tone before prompt audio, two short tones before response audio, and a three-note arpeggio when the review summary is shown. The option is off by default.

`Tools -> Options -> Audio generation format` controls the format used by automatic generation. `Opus` is the default and is usually much smaller than WAV. `WAV` remains available for compatibility or for users who want uncompressed generated audio.

`Ctrl+P` activates the same play/stop action when review audio is available. On the ready card list, `Ctrl+P` or the `Play/Stop Audio` button previews the selected card by playing its prompt audio and then its response audio. Moving to the next card, revealing the response, finishing the session, or closing the window stops any current card audio immediately. In exam mode, prompt audio is available while answering the question.

`Tools -> Options -> Automatically play audio during exam grading and review` controls what happens after an exam answer has been submitted and Cosimo is showing a grading or review dialogue. `No automatic audio` leaves that phase silent unless you ask for audio manually. `Question`, `Answer`, and `Both` automatically play the prompt, the expected response, or the prompt followed by the expected response. In grading and review dialogues, `Ctrl+P` always plays the prompt followed by the expected response when those audio files exist, even when automatic exam grading/review audio is off.

`Tools -> Options -> Automatically play audio during quizzes` controls quiz audio. `No automatic audio` keeps quiz sessions silent unless audio is played manually in the answer review. `Prompt` plays prompt audio when each quiz question appears. `Choices` plays the audio for a response choice when that choice is selected and stops it when the choice list loses focus or the selection changes. `Both` combines those behaviours. During quiz answer review, the same setting controls automatic prompt and correct-response playback; `Ctrl+P` plays the prompt followed by the correct response when those audio files exist. If guiding tones are enabled, quiz answer review also plays a short rising tone for a correct answer and a short falling tone for an incorrect answer before any automatic review audio.

Audio files live in the same-stem directory beside the deck. For card `1` in `Indonesian.cosimo-deck`, use `Indonesian/1.prompt.opus` for the prompt side and `Indonesian/1.response.opus` for the response side. Legacy `.wav` names such as `Indonesian/1.prompt.wav` still play when no `.opus` file exists. Generated reverse cards reuse the parent card’s files with prompt and response swapped. The audio generation helper writes new files in the selected format in this directory, so keep separate copies of any recordings you created yourself.

`Tools -> Remove Inoperative Audio from Deck` deletes Cosimo-recognised audio files in that same-stem directory when they cannot be used: files for card IDs that no longer exist in the deck, and lower-preference files hidden by a preferred format for the same card side, such as a `.wav` file when the matching `.opus` file exists. It also removes matching entries from `audio-manifest.tsv`. The command ignores other files in the directory, asks for confirmation, and cannot be undone.

Cosimo’s automatic deck-content and review-database backups do not include sidecar audio files. Full-deck bundle exports and full-deck backups do include the sidecar directory. If you record or edit your own audio files, make sure you either use full-deck backups or back up the sidecar directory yourself. Current generation preserves existing `.opus` and `.wav` files rather than overwriting them, but the sidecar directory is still outside Cosimo’s automatic deck-content and review-database backup system.

Windows packages also include `voice.exe`, a helper for generating these audio files from installed OneCore or SAPI voices. Run it from a command prompt. For example, if `voice.exe` is beside `cosimo.exe`, this command reads `decks/Indonesian.cosimo-deck` and writes audio files under `decks/Indonesian/`:

    voice Indonesian --prompt-voice "Indonesian voice name" --response-voice "English voice name"

By default, `voice.exe` writes Opus files. Use `--format wav` if you want WAV output instead.

You can also use `Tools -> Generate Audio` from Cosimo after opening a deck. That menu item is available only when the deck has `Prompt voice`, `Response voice`, `Prompt voice engine`, and `Response voice engine` metadata, so Cosimo does not silently generate audio with the wrong system default voice. If the menu item is disabled, use `Deck -> Edit Deck Metadata` to choose those voices and engines, and check whether the deck is marked as a manual audio deck. It shows a progress dialogue while `voice.exe` runs for the current deck and writes the helper output to a text file in the `reports` directory. The menu item only generates missing audio sides. If an individual `.opus` or legacy `.wav` file already exists outside the manifest, `voice.exe` leaves it untouched. When generation finishes, Cosimo reports the number of cards for which audio was generated, how many new files were created, how many managed files were regenerated or converted, how many untracked files were preserved, and how many already tracked files were skipped. If the report mentions files force-regenerated by explicit overwrite, that refers to an older or future command-line overwrite path, not ordinary GUI generation.

This conservative policy is intended to avoid replacing user recordings. For a deck whose audio you maintain manually, enable `Manual audio deck (protect against automatic audio generation)` in `Deck -> Edit Deck Metadata`. This writes `audio_generation=disabled` to the deck header, disables `Tools -> Generate Audio`, and makes `voice.exe` refuse to generate audio for that deck. It does not stop playback of existing audio.

Use `voice --list-voices` to see installed voices. For language learning, choose a voice that matches the language of each side: if the prompts are Indonesian and the responses are English, use an Indonesian prompt voice and an English response voice. If both sides are in the same language, `--voice "Voice name"` uses the same voice for both. Use `--engine onecore` or `--engine sapi` to list or generate with a specific engine; `--prompt-engine` and `--response-engine` can select different engines for the two sides.

Deck metadata can also store default voice filters and voice engines. Set `Prompt voice`, `Response voice`, `Prompt voice engine`, and `Response voice engine` in `Deck -> Edit Deck Metadata`, or add `prompt_voice=`, `response_voice=`, `prompt_voice_engine=`, and `response_voice_engine=` to the deck header. `voice.exe` uses those defaults when the matching command-line option is not supplied. The same editor can mark a deck as manual audio, which adds `audio_generation=disabled`. When `voice.exe` is available beside `cosimo.exe`, the metadata editor lists installed voices for the selected engine. The voice fields are still editable, so you can type a filter manually if listing fails or if you want to use a value not shown in the list. The engine selector can list OneCore voices, SAPI voices, or both; when you choose a listed voice, Cosimo saves the matching engine automatically. If you type or edit a voice filter manually, choose `onecore` or `sapi` before saving so `voice.exe` knows which engine to use. Command-line options still override deck metadata, but they do not override `audio_generation=disabled`.

The helper writes an `audio-manifest.tsv` file in the audio directory. It uses that manifest to skip audio whose card text, selected voice, and selected voice engine have not changed. Manifest-tracked audio is treated as Cosimo-managed and may be regenerated or converted to the selected output format. Existing untracked `.opus` and `.wav` files are treated as user-owned recordings and are left alone; in that case Cosimo does not create a new file for that card side, because doing so could shadow the user’s audio. `--dry-run` shows what would be generated without writing files.

## Files, Backups, and Maintenance

Back up both the deck file and its matching review database. The deck file contains your cards, deck metadata, and non-reversible card markers. The review database contains scheduling state, ratings, and review history.

Cosimo also creates automatic deck-content backups. Before it overwrites an existing deck, it copies the current deck into the app-level `backups` directory beside the executable. Backup files have rising numbers, for example `backups/000001-deck.cosimo-deck`. The `backups/index.txt` file records each backup filename and the original deck path.

Set automatic deck backups in `Tools -> Options`:

- `Full`: keep every automatic deck backup.
- `Last only`: keep only the newest automatic backup for each original deck path.
- `None`: do not create automatic deck backups.

Set review database backups in `Tools -> Options`:

- `On session start`: refresh one retained review-database backup when a study session starts.
- `Off`: do not create or refresh review-database backups.

Set automatic full deck backups in `Tools -> Options`:

- `Daily`: when Cosimo starts or opens a deck, it writes a retained compressed full-deck backup if the current deck has no full backup newer than 24 hours. This backup includes the deck file, same-stem sidecar directory, and review database. It is written only after the deck opens successfully and the review database integrity check passes.
- `Off`: do not create retained full-deck backups automatically.

For the default deck, back up:

- `decks/deck.cosimo-deck`
- `decks/deck.reviews.sqlite3`, if it exists
- `decks/deck/`, if you use sidecar audio

For another deck, the review database is beside the deck and uses the same base name. For example, `spanish.cosimo-deck` uses `spanish.reviews.sqlite3`; its sidecar audio directory, if present, uses the same base name as the deck.

Close Cosimo before copying or restoring backup files. Restoring only the `.cosimo-deck` file restores the cards but starts them without their previous review history. Restoring both files preserves the cards and their scheduling history.

Cosimo checks the review database integrity when opening a deck. If Cosimo says the review database failed an integrity check, close Cosimo and restore the matching `.reviews.sqlite3` file from your backup.

Automatic deck-content backups contain only the deck text, not review history. To restore one, close Cosimo and copy the chosen backup over the active `.cosimo-deck` file. To restore scheduling history, restore the matching `.reviews.sqlite3` file from your own backup or from Cosimo’s retained review-database backup. Automatic deck backups and review-database backups do not contain sidecar audio. Full-deck backups do contain the sidecar directory; otherwise restore audio from your own backup of the sidecar directory.

Automatic full deck backups are different: when enabled, they are retained compressed bundles that include the deck, sidecar directory, and review database. They are intended as a daily safety net for the currently used deck, not as a replacement for manual exports before risky changes.

`File -> Export Full Deck` writes a compressed `.zip` bundle containing the current `.cosimo-deck` file and its same-stem sidecar directory, including audio files and `audio-manifest.tsv` when present. It does not include the review database. Cosimo suggests a timestamped filename and lets you choose where to save the bundle. Use this export when you want to share deck content without your personal study history.

`File -> Export Full Deck with Study History` writes the same bundle plus a consistent snapshot of the review database. Use it for moving your own study setup to another machine or making a complete manual backup. The archive contains personal study data such as schedules, ratings, review history, suspensions, flags, and deferrals.

`File -> Full Deck Backup` writes the deck-and-sidecar bundle automatically into the app-level `backups` directory and records it in `backups/deck-bundle-index.txt`. It does not include the review database.

The optional daily automatic full deck backup also writes into `backups`, but uses `backups/automatic-deck-bundle-index.txt` and keeps a retained backup per deck path. It includes the review database.

`File -> Restore Full Deck` restores one of these compressed bundles into Cosimo’s `decks` directory. Cosimo first checks the bundle, then shows the deck file name, number of cards, number of audio files, file count, and whether the bundle contains study history. If existing files would be overwritten, Cosimo warns you and writes a full compressed backup of the existing target deck before restoring. If sidecar files would be overwritten but no matching target deck exists to back up, Cosimo refuses the restore instead of overwriting them.

Restoring a bundle can still cause data loss. It may replace newer card text, newer sidecar audio, a newer `audio-manifest.tsv`, or newer scheduling and rating history in the `.reviews.sqlite3` file. A bundle without study history will not restore scheduling or rating history; a bundle with study history will replace that history with the snapshot contained in the zip. Close other programs that may be using the same deck or review database before restoring.

Use `Tools -> Scrub Review Database` to permanently delete dormant review database rows for cards that are no longer in the current deck and for inactive generated reverse cards. Active cards, active generated reverse cards, current schedules, current suspensions, and current flags are kept. Non-reversible markers are stored in the deck file, not the review database. If review database backups are off, Cosimo warns that the scrub is irreversible. If review database backups are enabled, Cosimo refreshes the retained review-database backup before scrubbing and warns that the retained backup will be overwritten. After deleting inactive rows, Cosimo vacuums the database so the SQLite file can reclaim unused space.

Use `Tools -> Reclaim Database Space` to run the same SQLite vacuum without deleting dormant review data. This rewrites the review database file and may take some time on a large database. If review database backups are enabled, this command does not overwrite the retained backup; if backups are off, Cosimo reminds you to make sure you have a backup if concerned.

Use `Tools -> Options -> Delete Old Backups` to keep only the newest automatic backup for each original deck path. Cosimo asks for confirmation before deleting or renumbering backup files.

Use `Tools -> Wipe Backup Directory` only when you deliberately want to empty the application `backups` directory. Cosimo warns before doing this because the command deletes every file and folder in that directory, including files that may not have been generated or tracked by Cosimo. The command keeps the `backups` directory itself, but its contents are not recoverable from Cosimo after deletion.

For step-by-step recovery help, see Troubleshooting.

## Deck Sync

Deck sync stores a full snapshot of a deck on a configured Cosimo sync server. It is useful when you want to study the same deck on more than one machine, keep a private server copy of your study data, or download public and unlisted decks shared by other people.

Sync is not automatic merging. Cosimo uploads and downloads deck snapshots. If two machines independently change the same synced deck, Cosimo detects a revision conflict and asks you to download or otherwise choose which copy to continue from.

A typical two-machine setup looks like this:

1. On the desktop, open `Tools -> Options`, check the sync server URL, and set the local device name to something like `desktop`. New Cosimo installations use the public project server by default.
2. Use `Deck -> Sync -> Log In` and log in with a Mastodon-compatible account.
3. Open the deck you want to sync and use `Deck -> Sync -> Upload with Study History`.
4. On the laptop, check that the same sync server URL is selected, set the local device name to something like `laptop`, and log in with the same account.
5. Use `Deck -> Sync -> Remote Decks` to find your uploaded deck and download it.
6. After studying on either machine, upload from that machine before moving to the other one, then download on the other machine before continuing.

The local device name is only a label shown in sync status and remote deck details. It helps you recognise which machine last uploaded a deck. It is not part of your login or proof of ownership.

`Tools -> Options` stores the sync server URL and local device name. New Cosimo installations default to the public project sync server:

    https://cosimo.isonomia.net/sync.cgi

It is available to users with Mastodon-compatible Fediverse accounts. The current public-server quota is 20 decks and about 100 MB of storage per user. You can replace the URL with your own sync server. A deployed server should normally use `https://`. Plain `http://` URLs are accepted only for loopback testing, such as `http://127.0.0.1:44791`.

If you do not want this Cosimo installation to use sync at all, clear the sync server URL in `Tools -> Options` and save the options. Cosimo records that choice as `sync_server_url=none` in `cosimo.ini` and will not fall back to the public server until you set a URL again. You can also make the same opt-out by editing `cosimo.ini` manually and setting `sync_server_url=None`.

`Deck -> Sync -> Log In` starts the Mastodon-compatible login flow. Cosimo opens an authorisation URL in your browser, asks you to paste the authorisation code, and stores the returned sync identity and Cosimo bearer token locally. The local configuration file should therefore be treated as private. `Deck -> Sync -> Log Out` clears that local login state and asks the server to revoke the Cosimo bearer token when the server is reachable. Logging out does not delete your remote decks.

The login permission is deliberately narrow. The Fediverse instance asks you to approve only the `read:accounts` scope, which is enough for the sync server to confirm which account logged in. It is not permission to read private messages, post statuses, follow accounts, or act as you. The Cosimo desktop client never receives your Fediverse password or Fediverse access token. The sync server briefly receives a Fediverse access token during login, uses it to verify the account, and then revokes it before issuing a Cosimo sync token.

`Deck -> Sync -> Sync Status` shows the current deck’s sync identity, the configured server, your login state, the local device name, the remembered remote revision, server quota information, and whether the server currently has a copy of this deck. Use it when you are unsure whether the local deck is connected to a remote copy.

`Deck -> Sync -> Upload with Study History` uploads the deck file, sidecar directory, and review database. This includes card text, audio files, scheduling, ratings, suspensions, flags, deferrals, and review history. `Deck -> Sync -> Download with Study History` restores the owner snapshot for the same deck UUID and logged-in account. Before replacing local files, Cosimo writes a full compressed backup. Upload and download can take time for decks with audio, so Cosimo shows a progress dialogue while the transfer and restore work runs outside the main GUI thread.

Deck visibility controls how other users can find and download your deck content. Change it in `Deck -> Edit Deck Metadata`; the new visibility is sent to the server the next time you upload the deck.

- `Private` means only your logged-in sync account can download the deck.
- `Unlisted` means someone with the deck UUID or shared URL can inspect and download the deck content, but it does not appear in the public list.
- `Public` means the deck appears in public remote deck listings and can be downloaded by other users.

Public and unlisted downloads are content-only. They do not include your review database, ratings, schedule, flags, suspensions, or deferrals. Downloading one of your own decks uses the owner study-history snapshot.

`Deck -> Sync -> Remote Decks` opens a selectable list of decks on the configured sync server. If you are logged in, this includes decks owned by your sync account and public decks from other owners. If you are not logged in, it can still show public decks. Use `Details` to inspect the selected remote deck metadata, or `Download` to restore it. When the server has summary data, the list and details prioritise the deck title or file name, card count, audio file count, audio formats, visibility, owner, study-history availability, and last upload device. Opaque sync identifiers, revision numbers, and bundle hashes are shown later as technical details for sharing and troubleshooting. `Copy ID` copies the selected deck UUID. `Find by ID` asks for a shared deck UUID or URL and adds the matching public or unlisted deck to the list.

When you download the deck that is already open, Cosimo restores it in place. When you download a different deck, Cosimo chooses a local path that will not overwrite the currently open deck. If Cosimo has not seen that deck UUID locally, it also avoids overwriting existing deck files, review databases, or sidecar audio files.

If a remote deck is owned by the account you are logged in with, `Remote Decks` also offers `Delete`. This removes the deck and stored bundles from the sync server, but it does not delete your local deck file, sidecar audio, or review database.

Each synced deck has a UUID. If a sync server already has that UUID under another authenticated owner, Cosimo refuses the upload instead of taking over the remote deck. If this happens because you downloaded someone else’s public or unlisted deck and now want to maintain your own synced copy, use `Deck -> Edit Deck Metadata -> Make Independent Copy`, then save. Cosimo assigns a new deck UUID, resets visibility to private, keeps the cards, audio, and local study history, and forgets the old local sync revision state.

Most users do not need to run a sync server. If you do want to run one, see Sync Server Deployment.

## Accessibility

Cosimo is designed for keyboard and screen reader use. Most study actions can be completed without opening menus:

- the number keys `1` to `4` choose confidence ratings before the response and recall ratings after the response
- the Space key reveals the response without recording a confidence rating
- `0` ends a normal study session early
- `e` edits the current card after the response has been revealed
- `Ctrl+D` defers the current card before the response is revealed
- `Ctrl+F` flags or unflags the current card
- `Ctrl+P` plays or stops available card audio

The ready screen also has direct keyboard commands for common actions:

- `Alt-S` starts the scheduled study session
- `Alt-T` force-starts available cards
- `Alt-X` starts an exam
- `Alt-Z` starts a quiz
- `Ctrl+L` opens the learning dashboard
- `Alt+Enter` opens card details for the selected card

Review audio can be used manually or automatically. When automatic audio during study is enabled, the optional guiding tones provide non-speech cues: one short tone before prompt audio, two short tones before response audio, and a three-note arpeggio when the review summary is shown. Timed exams also use tones to mark time progress and timeouts.

The learning dashboard is split into separate read-only sections so screen-reader users can tab between summary, distribution, workload, diagnostics, and activity instead of reading one long field. The dashboard also has `Save Report` and `Copy to Clipboard` buttons for reviewing the full report outside the dialogue.

The main status bar reports deck status and review timing in short, speech-friendly terms. Scheduled times in card details include relative durations before exact UTC timestamps, because relative times are easier to understand with speech.

Known issue: when you tab or shift-tab into the prompt list, some screen reader and wxWidgets combinations announce the selected item twice. Once you are in the list, arrow-key navigation should work normally.

## Settings and Language

Most application-wide settings are in `Tools -> Options`. Deck-specific metadata, such as title, voice choices, manual-audio protection, and sync visibility, are in `Deck -> Edit Deck Metadata` instead.

Use `Language` to choose English, Spanish, or Galician. The language choice is saved and used next time. If no language has been saved yet, Cosimo uses Spanish when the system locale is Spanish, Galician when the system locale is Galician, and otherwise falls back to English. Unknown locales also fall back to English.

`Minimum cards per session` controls how many cards Cosimo tries to include when you choose the scheduled `Start` action. It is a minimum, not a maximum: if more cards are due, all due cards are included. If fewer cards are due, Cosimo fills from other available cards up to the minimum.

`Deck backups`, `Review database backups`, and `Automatic full deck backups` control the three backup systems described in Files, Backups, and Maintenance.

Sound notifications can be set to `Always`, `When Cosimo is visible`, `When Cosimo is in the system tray`, or `Never`. When the chosen policy permits sound, Cosimo plays a short sound when the timed ready-screen refresh notices that reviews have become available, or that more reviews have become available since the last automatic refresh. User-triggered changes, such as adding or removing cards, and manual `F5` refreshes do not play this sound. Cosimo also stays silent while a study session is active, even if more cards become due during that session.

`Audio during study` controls ordinary scheduled, forced, and flagged study:

- `No audio`: Cosimo ignores card audio during ordinary study.
- `Manual`: Cosimo announces/shows that audio exists and lets you play it with `Ctrl+P` or the `Play/Stop Audio` button.
- `Automatic`: Cosimo plays prompt audio when a prompt appears and response audio when a response appears. `Ctrl+P` or `Play/Stop Audio` can still stop or replay audio.

`Guiding tones for automatic audio` adds non-speech orientation cues when ordinary study audio is automatic: one 200 ms tone before prompt audio, two 100 ms tones before response audio, and a three-note rising arpeggio before the study summary. The same setting also enables correct/incorrect cue tones during quiz answer review: a short rising two-tone cue for a correct answer and a short falling two-tone cue for an incorrect answer. Timed exam progress and exam timeout/finished sounds are separate exam signals; they are not controlled by this checkbox.

`Audio generation format` controls new generated audio from `voice.exe` and `Tools -> Generate Audio`. `Opus` is the default and normally much smaller. `WAV` is available for compatibility and uncompressed generated audio.

`Automatically play audio during exam grading and review` controls only the post-answer exam grading or review phase. `No automatic audio` keeps that phase silent unless you press `Ctrl+P`. `Question`, `Answer`, and `Both` play the prompt, the expected response, or both. During exam grading or review, `Ctrl+P` always plays prompt followed by expected response when those files exist.

`Automatically play audio during quizzes` controls quiz questions and quiz answer review. `No automatic audio` leaves quizzes silent except for manual `Ctrl+P` during answer review. `Prompt` plays the prompt when each quiz question appears. `Choices` plays a response choice when it is selected and stops it when focus or selection moves away. `Both` combines prompt and choice audio. During quiz answer review, `Prompt`, `Choices`, and `Both` control automatic prompt/correct-response playback; `Ctrl+P` plays prompt followed by the correct response when those files exist.

`Calibration recall rule` changes how confidence calibration and confidence mismatch diagnostics decide whether an answer counted as recalled. `Lenient` counts `Hard`, `Good`, and `Easy` as recalled. `Strict` counts only `Good` and `Easy` as recalled. Scheduling still uses the actual recall rating; this option affects dashboard and diagnostic interpretation, not the scheduler.

`Sync server URL` is the default server used by `Deck -> Sync`. New Cosimo installations use `https://cosimo.isonomia.net/sync.cgi`, the public project server. You can replace it with your own server. Deployed servers should normally use `https://`; local loopback testing can use plain `http://`. To disable sync for this installation, clear the field and save the options; this stores `sync_server_url=none` and prevents Cosimo from using the public default until a URL is set again. `Local device name` is an optional label such as `desktop` or `laptop`, shown in sync status and remote deck details so you can recognise which installation last uploaded a deck.

With minimise-to-tray enabled, using the normal window minimise action hides Cosimo in the system tray instead of leaving it on the taskbar. Activating the tray icon restores the window, and the tray context menu contains Restore and Quit. Closing Cosimo still exits the application.

Translations are maintained in gettext-style `.po` files, with a small amount of source-code wiring for each new language. If you want to work on a translation, contact David Picón Álvarez first at `@modulux@node.isonomia.net` so the work can be coordinated.

The `Help` menu opens the local user guide, the project wiki, and the new ticket page for bug reports. Bug reports are handled through Fossil tickets on the project site.

## Tips

- Keep prompts specific. A card should ask for one thing.
- Avoid duplicate prompts. They make a deck ambiguous; use the duplicate prompt filter and `Deck -> Resolve Duplicate Prompts` if a hand edit creates them.
- Keep responses short enough that you can judge them consistently.
- Duplicate responses are fine, but only one card from a duplicated-response group can have an active generated reverse card.
- Use `Force Start` for extra practice, not as a replacement for the scheduled study session.
- If a card is confusing, edit it before the next session. If you find a typo or wrong answer after revealing the card, edit it before rating the recall.
- Use `0` when you want to stop a session early; your completed attempts are still saved.

## Why the Name Cosimo?

Cosimo is named in honour of Cosimo Piovasco di Rondò, the protagonist of Italo Calvino’s novel The Baron in the Trees. Calvino’s Cosimo is a notorious polymath and polyglot, which makes his name a fitting one for a study tool.