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.