# Troubleshooting

This guide covers common recovery steps for Cosimo's portable beta builds.

## Before Changing Files

Close Cosimo before copying, replacing, or deleting deck and review database
files. The review database is a SQLite file, and closing Cosimo avoids copying
it while a write is in progress.

For the default deck, the main files are:

- `decks/deck.cosimo-deck`
- `decks/deck.reviews.sqlite3`
- `cosimo.ini`
- `backups/index.txt`
- `backups/review-db-index.txt`

For another deck, the review database sits beside the deck and uses the same
base name. For example, `spanish.cosimo-deck` uses
`spanish.reviews.sqlite3`.

## Deck Parse Errors

If Cosimo cannot parse a deck, open the `.cosimo-deck` file in a text editor
and check the card separators:

- `---` separates the prompt from the response.
- `=number=` ends a card and preserves its review history.
- Older `===` card endings are accepted, but Cosimo upgrades them to numbered
  endings when it can open and save the deck.

Each card needs a non-empty prompt and a non-empty response. If a prompt or
response accidentally contains a separator line by itself, Cosimo treats that
as deck structure rather than card text.

## Restoring Card Text

Automatic deck backups contain card text only. They do not contain review
history.

To restore card text:

1. Close Cosimo.
2. Open `backups/index.txt`.
3. Find the backup file whose original path matches the deck you want to
   restore.
4. Copy that backup file over the active `.cosimo-deck` file.
5. Start Cosimo again.

If you also need scheduling history, restore the matching `.reviews.sqlite3`
file from an external backup or from Cosimo's retained review database backup.

## Review Database Integrity and Consistency Errors

Cosimo checks the review database with SQLite when it opens a deck. If the
database fails the integrity check, Cosimo stops before migrating or writing
the deck.

Cosimo also checks whether the review database is logically consistent with the
deck that is being opened. For example, it rejects broken review-pass links,
invalid stored rating or scheduling values, and active reversible cards whose
responses are duplicated by another active card. Old review history for removed
cards, including removed reverse cards, is allowed to remain dormant.

To recover:

1. Close Cosimo.
2. Find the active review database. For the default deck it is
   `decks/deck.reviews.sqlite3`.
3. If the error mentions a duplicated response for a reversible card, edit the
   deck so the active reversible card's response is unique, or restore a deck
   version from before the duplicate was introduced. If Cosimo can still open
   the deck, the ready-list `Duplicated responses` filter can help find the
   conflicting cards.
4. For other integrity or consistency errors, move the damaged
   `.reviews.sqlite3` file aside.
5. Restore a known-good `.reviews.sqlite3` file.
6. Start Cosimo again.

If review database backups are enabled, `backups/review-db-index.txt` maps the
retained database backup file to the original database path. Copy the matching
backup over the damaged `.reviews.sqlite3` file.

If you have no usable review database backup, you can remove the damaged
`.reviews.sqlite3` file. Cosimo will create a new review database, but previous
ratings, scheduling state, and review history will be lost.

## Review Audio Does Not Play

Review audio currently supports WAV files only. Check that `File -> Options ->
Audio during reviews` is not set to `No audio`, and that the file is in the
same-stem directory beside the deck.

For example, card `1` in `decks/Indonesian.cosimo-deck` uses:

- `decks/Indonesian/1.prompt.wav`
- `decks/Indonesian/1.response.wav`

Generated reverse cards reuse those files with prompt and response swapped.
Cosimo does not create or back up these audio files automatically. Exam mode
currently uses prompt audio while answering questions, but does not play
response audio during exam grading or exact-exam answer review.

## Backup Settings

Deck backups are configured in `File -> Options`:

- `Full` keeps every automatic deck-content backup.
- `Last only` keeps only the newest automatic deck-content backup for each
  original deck path.
- `None` disables automatic deck-content backups.

Review database backups are configured separately:

- `On session start` refreshes one retained review database backup when a
  review pass starts.
- `Off` disables review database backups.

The retained review database backup is separate from numbered deck-content
backups.

## Runtime State

Cosimo stores portable application state in `cosimo.ini` beside the executable.
This file contains settings and the last opened deck path.

Older beta builds used `cosimo-settings.txt` and
`cosimo-last-open-deck.txt`. If Cosimo finds either file, it writes their
contents into `cosimo.ini` and then removes the old files.

If Cosimo opens the wrong deck on startup, close Cosimo and edit or remove the
`last_open_deck` entry in `cosimo.ini`.

## Locked or Read-Only Files

If Cosimo cannot save a deck, settings file, report, backup, or review
database change:

- Make sure the file is not open in another program.
- Check that the folder is writable.
- On portable installs, avoid running from a read-only location.
- Close Cosimo before copying files from `decks` or `backups`.

Cosimo blocks deck overwrites when required deck backups or backup index writes
fail. If this happens, fix the file or folder permission problem and try the
card edit again.

If a review answer cannot be recorded, Cosimo leaves the current card in the
review pass so the answer is not silently lost. If a review pass summary cannot
be recorded, the individual card answers may still have been saved, but later
pass-level analysis may be incomplete.

## Startup Cannot Open a Deck

If Cosimo starts with no open deck, the startup message should name the deck
file and review database it tried to use. This can happen when the default
`decks` folder cannot be created, the selected deck cannot be read, or the
review database cannot be opened or created.

To recover:

1. Close Cosimo.
2. Check that the named folder is writable and is not on read-only media.
3. Close other programs that may be using the named deck or review database.
4. If the review database is damaged and you have a backup, restore it.
5. Start Cosimo again, or open another deck.

## Screen Reader Notes

The ready-screen prompt list may announce the selected item twice with some
screen reader and wxWidgets combinations. This is a known native-control
behaviour. Once focus is inside the list, arrow-key navigation should still work
normally.

## Bug Reports

When reporting a problem, include:

- Cosimo version.
- Operating system version.
- Screen reader and version, if the problem involves accessibility.
- Whether the deck is the default deck or another deck path.
- The exact error message.
- Whether `cosimo.ini`, `backups/index.txt`, or `backups/review-db-index.txt`
  exists.
- The steps that led to the problem.
