# 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`
- `decks/deck/`, if you use review audio
- `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.

## Restoring a Full Deck Bundle

Full deck bundle export and backup support is preliminary. Cosimo can create
the zip files, but restore is currently manual.

To restore a bundle:

1. Close Cosimo.
2. Make your own copy of the current files in `decks` if there is any chance
   you may need them again.
3. Open the bundle zip file with your operating system's archive tool.
4. Extract the zip contents into Cosimo's `decks` directory.
5. Allow overwrites only if you intend to replace the existing deck, sidecar
   audio, manifest, or review database.
6. Start Cosimo again and open the restored deck if it is not already selected.

Restoring a bundle can cause data loss. It may replace newer card text, newer
audio files, a newer `audio-manifest.tsv`, or newer scheduling and rating
history in the `.reviews.sqlite3` file. Bundles made with `Export Full Deck`
or `Full Deck Backup` do not contain the review database; bundles made with
`Export Full Deck with Study History` do.

## 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 collide with another active reversible 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 duplicated responses for active reversible cards, use
   a deck backup or manual database repair so that at most one card from that
   duplicated-response set has an active generated reverse card. 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 `Tools -> 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's automatic backups do not include these audio files. Windows packages
include `voice.exe`, which can generate WAV files from installed OneCore or SAPI
voices; see the user guide for the command-line workflow. Exam mode can use
prompt audio while answering questions. During exam grading or exact-exam answer
review, `Tools -> Options -> Automatically play audio during exam grading and
review` controls whether Cosimo automatically plays the prompt, the expected
response, both, or neither; `Ctrl+P` plays prompt audio followed by response
audio when those files exist.

If `voice.exe` has no `audio-manifest.tsv` for the deck's audio directory, it
regenerates existing selected WAV files once to seed the manifest. If a manifest
already exists, untracked WAV files are left untouched on the current run and
added to the manifest. After a file is tracked, later card text, voice, or
voice-engine changes can cause `Tools -> Generate Audio` or `voice.exe` to
overwrite it. Keep your own backup of manually recorded or edited audio files,
because Cosimo's automatic deck and review-database backups do not include them.
For decks whose audio you maintain manually, set `Manual audio deck (protect
against automatic audio generation)` in `Deck -> Edit Deck Metadata`. This
writes `audio_generation=disabled`, disables `Tools -> Generate Audio`, and
makes `voice.exe` refuse to generate audio for that deck.

## Backup Settings

Deck backups are configured in `Tools -> 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
  study session 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`.
- Back up any sidecar audio directory yourself; automatic Cosimo backups do not
  include WAV files, and audio generation can overwrite matching files.

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
study session so the answer is not silently lost. If a study session 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.
