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

When adding new cards directly in a text editor, use `===` instead of choosing
your own card number. Keep existing `=number=` endings on existing cards.

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

Use `File -> Restore Full Deck` to restore a compressed bundle into Cosimo's
`decks` directory. Cosimo checks the zip before restoring and shows the deck
file name, number of cards, audio file count, total file count, and whether the
bundle contains review history.

If the restore would overwrite an existing deck, Cosimo asks for confirmation
and writes a full compressed backup of the current target deck before replacing
files. That backup includes the target review database when one exists. If
sidecar files would be overwritten but no matching target deck exists to back
up, Cosimo refuses the restore instead of overwriting those files.

Restoring a bundle can still 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. If a restore fails because the review
database is locked, close other Cosimo windows or tools using that database and
try again.

## 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 supports Opus files and falls back to legacy WAV files. Check that
`Tools -> Options -> Audio during study` 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.opus`
- `decks/Indonesian/1.response.opus`

Legacy `.wav` files with the same names, such as
`decks/Indonesian/1.prompt.wav`, still play when no matching `.opus` file
exists.

Generated reverse cards reuse those files with prompt and response swapped.
Cosimo's automatic deck-content and review-database backups do not include
these audio files; full-deck bundle backups do. Windows packages include
`voice.exe`, which can generate Opus or 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.

Current audio generation creates missing files in the selected generation
format, which defaults to Opus. If a matching `.opus` or legacy `.wav` file
already exists but is not tracked in `audio-manifest.tsv`, `voice.exe` treats
it as user-owned audio and leaves it untouched. Manifest-tracked generated
audio may be regenerated or converted when card text, voice metadata, or the
selected generation format changes. Keep your own backup of manually recorded
or edited audio files, or use a full-deck bundle backup, because Cosimo's
automatic deck-content 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.

Automatic full deck backups are configured separately:

- `Daily` writes one retained compressed backup per deck path when Cosimo starts
  or opens a deck, if the retained backup is older than 24 hours. It includes
  the deck file, sidecar directory, and review database.
- `Off` disables automatic full deck backups.

The retained review database backup and retained full deck backup are separate
from numbered deck-content backups.

A balanced everyday policy is deck backups `Last only` or `None`, review
database backups `On session start`, automatic full deck backups `Daily`, and
frequent sync when you use more than one device. This puts the strongest
automatic protection on review history and sidecar audio while avoiding a large
pile of redundant deck-text backups.

On USB sticks, SD cards, and other write-limited flash media, avoid `Full` deck
backup history and repeated manual full-deck bundles unless you need them.
Cosimo deliberately keeps durable writes for review answers and file
replacement, so lowering backup churn is the safer way to reduce wear.

`Tools -> Wipe Backup Directory` empties the whole `backups` directory after a
warning. It deletes files and folders whether or not Cosimo generated or
indexed them, so use it only after copying out anything you still need.

## 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, or use a full-deck bundle
  backup. Automatic deck-content and review-database backups do not include
  audio 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.

Cosimo should then offer to open another deck or quit. If you choose to open
another deck, you can select an existing `.cosimo-deck` file or choose a new
path and let Cosimo create an empty deck there. If that also fails, Cosimo
shows the new error and offers the same open-or-quit choice again.

To recover:

1. Try opening another deck from the startup prompt.
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. Restart Cosimo after correcting the file or folder problem.

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