# 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 WAV review audio when a deck has voice
  metadata.
- `File -> Export Full Deck` and `File -> Full Deck Backup` write compressed
  deck bundles for sharing or manual backup.
- `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 exports and backups,
  and quitting.
- `Deck` is for deck-wide operations such as properties, metadata, bulk
  reversibility, and duplicate-prompt repair.
- `Card` is for actions on 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. If a failed card is
  repeated at the end of the same session, that repeat is another question.
- 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-style 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. Cards marked `Again` are scheduled for a short learning or
relearning step after about 10 minutes. They are also shown once more at the end
of the current session. When several cards need repeating, those repeats are
ordered randomly. If the repeat is still marked `Again`, it is recorded
normally but is not added again to the same session.

The exact interval is automatic. You do not need to manage dates yourself.

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

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

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 -> Make Selected Card Reversible`, 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 -> Allow Selected Card Reversal` 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
allowing reversal again 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`.

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. 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, and asymmetry issues. Its counts follow the current text
filter. The duplicated-response filter is especially useful before making cards
reversible.

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

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 unique cards were studied, not counting repeats
- how many questions were answered in total, including repeats
- total time, time per question, and time per unique card
- counts and percentages for prediction ratings, including responses revealed
  without a prediction
- counts and percentages for recall feedback ratings

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.

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.

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.

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, your selected response, and
the correct response, then shows a 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 response strings in the active deck so
each question can have one correct answer and three distractors.

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.

## 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 overdue scheduled cards, 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
- 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, time spent in completed sessions, recent recorded study
  time, and average study time per active study day when timing data exists

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 unscheduled cards and scheduled cards
whose due time has arrived. `Overdue scheduled cards` is a narrower subset of
that number: scheduled cards whose due time is already in the past and that are
not suspended or deferred. It does not include new unscheduled cards. 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 does not know whether failed cards will be
repeated during a future session.

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 answered `Again`.
`Low-confidence successes` means you chose `Don't know` or
`Probably don't know` and then recalled the answer under the active recall
rule.

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 into relearning.
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.

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

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 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 those WAV files from installed speech
voices.

Review audio playback is optional and currently supports WAV files only.
Configure it in `Tools -> Options -> Audio during reviews`:

- `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 review audio` option adds short
orientation cues when automatic review audio 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.

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

Audio files live in the same-stem directory beside the deck. For card `1` in
`Indonesian.cosimo-deck`, use `Indonesian/1.prompt.wav` for the prompt side and
`Indonesian/1.response.wav` for the response side. Generated reverse cards
reuse the parent card's files with prompt and response swapped. The audio
generation helper can write and overwrite files in this directory, so keep
separate copies of any recordings you created yourself.

Cosimo's automatic deck and review-database backups do not include sidecar
audio files. If you record or edit your own WAV files, back up the sidecar
directory yourself before using `Tools -> Generate Audio` or
`voice --overwrite`.

Windows packages also include `voice.exe`, a helper for generating these WAV
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"
```

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 does not overwrite existing audio unless the helper manifest says the
generated card text, selected voice, or selected voice engine has changed. If
no manifest exists yet, matching existing WAV files are regenerated once so the
new manifest reflects the current card text, voice selection, and engine
selection. If a manifest exists but an individual audio file has no entry, that
file is left untouched and added to the manifest so later card text, voice, or
engine changes can be detected. When it finishes, Cosimo reports the number of
cards for which audio was generated, how many audio files were new, how many
were regenerated because card text, voice selection, or engine selection
changed, how many untracked files were regenerated to seed a missing manifest,
how many existing files were added to the manifest, and how many files were
skipped.

This regeneration policy is intended for audio produced by `voice.exe`. If you
manually recorded or edited a file whose name matches a selected card side, a
later deck edit, voice change, or engine change can cause
`Tools -> Generate Audio` to overwrite that recording. Use `--dry-run` first if
in doubt, and keep your own backup of recordings before generating audio. 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, and to regenerate files when any of them has changed.
Existing audio files without manifest entries are regenerated if there is no
manifest at all; if a manifest already exists, they are left alone on the
current run but added to the manifest so future changes can be detected. Use
`--overwrite` if you want to refresh all selected files immediately.
`--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.

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 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; restore audio from your own backup of the sidecar
directory.

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

Support for these compressed bundles is preliminary. Cosimo can write them, but
does not yet have an in-application restore command. To restore one manually,
close Cosimo, open the zip file with your operating system's archive tool, and
extract its contents into Cosimo's `decks` directory, allowing files to be
overwritten only if you really intend to replace the current deck. Restoring a
bundle can cause data loss if it overwrites a newer `.cosimo-deck` file,
sidecar audio directory, `audio-manifest.tsv`, or `.reviews.sqlite3` review
database. 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.

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.

For step-by-step recovery help, see [Troubleshooting](troubleshooting.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 review audio
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

Set the minimum cards per session in `Tools -> Options`. The options dialogue
can also configure review-availability sounds, review audio, guiding tones,
exam grading/review audio, the learning-dashboard calibration recall rule,
deck and review-database backups, language, and minimise-to-tray behaviour.

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.

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.

Cosimo currently supports English, Spanish, and Galician. Change the language
in `Tools -> Options`. 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.

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.
