# 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 changes that would make reverse prompts ambiguous. 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. Editing a generated reverse card edits its parent
card in the deck's normal prompt-response order; the generated reverse direction
updates from that parent card.

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/`:

```bat
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.

For a language-learning deck, the strongest audio workflow is to make the deck
audio carry the language information instead of relying on the screen reader to
guess the language of ordinary controls. Choose prompt and response voices that
match the two sides of the deck, generate audio, set `Audio during study` to
`Automatic`, and enable `Guiding tones for automatic audio`. In ordinary study,
Cosimo then plays a tone before the prompt voice, two tones before the response
voice, and a three-note cue at the summary. This can make it practical to study
mostly from Cosimo's generated audio while keeping the screen reader quiet.
For example, NVDA users can use Speech Mode `On-demand`, and JAWS users can
turn speech off, while keeping braille or manual speech commands available as
needed. Use the screen reader's normal controls for this; Cosimo does not
change screen-reader speech mode itself.

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.

A balanced policy for daily use is:

- set deck backups to `Last only`, or to `None` if you already rely on daily
  full-deck backups and external backups. Deck text usually changes less often
  and is easier to reconstruct than study history.
- set review database backups to `On session start`. Review history, schedule
  state, and ratings change often and cannot be reconstructed from the deck
  text.
- set automatic full deck backups to `Daily`, especially if you use sidecar
  audio or maintain recordings by hand. Full deck backups include the deck,
  review database, and sidecar directory.
- sync frequently if you use more than one device or want off-machine
  protection. Sync complements local backups; it is not a substitute for a
  known-good backup before risky changes.

If you run Cosimo from a USB stick, SD card, or other flash media with limited
write endurance, avoid unnecessary backup churn: use `Last only` or `None` for
deck backups, prefer Opus audio over WAV, keep automatic full deck backups at
the daily setting rather than making repeated manual bundles, and sync
frequently. Cosimo still favours data safety over minimising writes: review
answers and file replacements are written durably so that a crash or accidental
unplug is less likely to damage study data.

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 numbered
deck backup and the newest automatic full-deck 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](troubleshooting.md).

## 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.

The sync system is new in this beta. The public project server and the
included sync-server tools are suitable for beta testing, but the sync API is
not yet a stable long-term compatibility promise. Until a stable release
declares the sync protocol stable, use matching Cosimo client and server
versions where practical.

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 before upload and asks whether to force the upload, download
the remote copy instead, or cancel. Force upload replaces the remote deck with
the local copy, so changes made elsewhere can be lost.

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:

```text
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.
Cosimo records this default URL explicitly in `cosimo.ini` when it writes the
configuration. 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 only on this
Cosimo copy. This is deliberate: if you copy the portable Cosimo folder to
another device, local logout on one copy should not unexpectedly log out the
other copy. Logging out does not delete your remote decks.

To invalidate server-side sync tokens, use the explicit invalidation commands.
`Deck -> Sync -> Invalidate This Token` clears the local login and asks the
server to revoke the stored Cosimo token. Other copied Cosimo folders that
share that exact token will also be logged out. `Deck -> Sync -> Invalidate All
Account Tokens` asks the server to revoke every Cosimo token for the logged-in
sync account, then clears the local login. Use it if a copied Cosimo folder or
device may be compromised.

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.
Cosimo checks the remote owner before creating the upload bundle, so it will
not waste time packaging a deck that belongs to a different sync owner. It also
checks whether the remembered remote revision is stale. If it is stale, choosing
download instead uses the normal restore path and writes a full compressed
backup before replacing local files.
`Deck -> Sync -> Download Synced Deck` restores the current deck UUID. If the
deck belongs to the logged-in account, Cosimo restores the owner snapshot with
study history; otherwise it restores the shared deck content without study
history. 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.

This also lets you follow a maintained public or unlisted deck without
publishing your own study history. If you download someone else's deck, study
it locally, and later download the same remote deck again, Cosimo applies the
maintainer's latest deck and sidecar files while keeping your local review
database. You can receive corrected cards, new cards, and improved maintained
audio this way. The limitation is that you cannot upload your private study
database for that deck unless you first make the deck an independent copy, which
breaks the automatic link to the maintainer's deck.

`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](sync-deployment.md).

## 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.

For language learning, this is intended to support a low-speech workflow:
generate card audio with the correct language voice for each side of the deck,
turn on automatic study audio and guiding tones, then set the screen reader to
an on-demand or silent mode if you want Cosimo's prompt and response audio to be
the main speech source.

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.

Known issue: when the ready list is empty, some screen reader and wxWidgets
combinations announce the empty list as "unknown" instead of saying that it has
no items. The ready summary and filter counts are the reliable way to confirm
that the current filter has no cards.

## 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](#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.
