# Cosimo User Guide

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

## What Spaced Repetition Means

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.

In Cosimo, each thing you learn is a card:

- the prompt is the question, cue, or sentence you see first
- the response is the answer you check yourself against

Cosimo records your ratings after each review and uses that history to decide
which cards are due.

## 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 only prompts and responses. 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.

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.

The options dialogue can also configure review-availability sounds 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 review pass is active, even
if more cards become due during that pass. 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.

## Backups

Back up both the deck file and its matching review database. The deck file
contains your cards. 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 `File -> 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 `File -> Options`:

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

Use `File -> 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, current flags, and current non-reversible
markers are kept. 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.

For the default deck, back up:

- `decks/deck.cosimo-deck`
- `decks/deck.reviews.sqlite3`, if it exists

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

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.

Use `File -> 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).

## 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 pass would include 6 due cards
and 4 extra cards to reach the minimum.

The main window status bar also 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.

You can add, edit, or remove cards before starting a pass. After a card has
been revealed during review, you can also edit that current card if you notice
a mistake in the prompt or response. `Cards -> Edit Selected Card` changes to
`Cards -> Edit Current Card` at that point.

For repeated entry, use `Cards -> 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.

Useful keys on the ready screen:

- `Alt-S`: start the scheduled pass
- `Alt-T`: force-start all cards not suspended or deferred
- `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+R`: make the selected card reversible, or remove the generated reverse
  card

The card details dialogue shows the prompt, response, card ID, current card
state, review count, last review, scheduling state, next scheduled review, and
review history for the selected card. Card state combines visible markers such
as suspended, flagged, deferred, reverse, has reverse, and non-reversible on
one line.
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 review, schedule last reviewed, and next scheduled
review, 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
review history list at the bottom uses exact UTC timestamps only.

Use `File -> Learning Dashboard`, or press `Ctrl+L`, to show a deck-wide
learning summary. It reports several kinds of information:

- card counts by scheduling state: new, learning, review, and relearning
- available-now and scheduled-and-overdue counts, ignoring suspended and
  deferred cards
- model-based recall estimates for active cards with scheduling data
- confidence calibration from your pre-response predictions and later recall
  ratings
- recent learning pace, based on how many reviews cards needed before first
  reaching 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 reviewed immediately. This includes new cards and scheduled cards whose due
time has arrived. `Scheduled and overdue` is the narrower count of scheduled
cards whose due time is already in the past and that are not suspended or
deferred, so it does not include new unscheduled cards.

`Average estimated recall` is the average of those per-card estimates. `Likely
known cards` counts estimated cards at or above 90% recall. `At-risk cards`
counts estimated cards below 70% recall. 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 pass.

The calibration section compares your prediction before seeing the response
with the recall rating you gave after seeing it. `Aligned confidence` means the
prediction and outcome matched. `Over-confident answers` means the prediction
was higher than the outcome. `Under-confident answers` means the outcome was
better than the prediction. Cards revealed without a prediction are counted
separately.

If the deck has generated reverse cards, the dashboard shows standard cards,
reversed cards, and total cards separately, because one direction can be much
easier than the other.

Use `View -> Deck Order`, `View -> Next Scheduled Review`, or
`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, and
duplicated responses, non-reversible cards, and deferred cards. Its counts
follow the current text filter. The duplicated-response filter is especially
useful before making cards reversible, because duplicate responses make reverse
prompts ambiguous.

Use `Cards -> 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 review passes. 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 `Cards -> 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 passes,
forced passes, ready-screen counts, and status-bar due calculations. Use
`Cards -> Clear Selected Card Deferral`, or the context menu, to make it
available again immediately.

Use `Cards -> 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 review pass, `Ctrl+F` flags or unflags the current card. The review
screen also has a Flag/Unflag button after the confidence buttons and after the
recall 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 pass. Flagging does not affect scheduling or whether the
card appears in review. Flagged cards are marked with `(flagged)` in the prompt
list and can be found with the `Flagged cards` filter.

Use `Cards -> 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 has the same response, 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.

Use `Cards -> Mark Selected Card Non-Reversible` when a card should not have a
generated reverse direction. This removes any active generated reverse card for
that parent card and prevents `Make Possible Cards Reversible` from adding it
again later. Use `Cards -> Allow Selected Card Reversal` to remove that marker.
The card then becomes eligible for manual or bulk reversal again, provided its
response is not duplicated. 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.

Use `Cards -> 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 responses are duplicated by another 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 `Cards -> 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.

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.

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.

## Starting a Pass

There are two ways to start reviewing.

`Start` uses the schedule. It reviews 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.

During either kind of pass, press `0` to end the pass early.

## Before the Response

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

## Rating After the Response

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

## How Scheduling Works

Cosimo stores each completed review 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
- hesitant correct cards progress more cautiously than easy correct cards
- confidently correct cards 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 toward 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
pass. 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 pass.

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 reviews 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 pass 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 reviewed in deck order.

Set the minimum in `File -> Options`.

## Statistics

At the end of a pass, Cosimo shows statistics for that pass:

- how many unique cards were reviewed, 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

Choose `Save Report` to write a text copy of this pass summary to the
`reports` directory beside the executable. Cosimo creates the directory if
needed. Report filenames use the deck file name without its extension and the
pass 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.

## Languages and Translation

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

## Tips

- Keep prompts specific. A card should ask for one thing.
- Keep responses short enough that you can judge them consistently.
- Use `Force Start` for extra practice, not as a replacement for the scheduled
  pass.
- If a card is confusing, edit it before the next pass. 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 pass early; your completed reviews are still
  saved.
