# Cosimo Manual Release Checklist

Use this checklist for beta and stable release candidates after
`./tools/pre-release-check.sh` has passed. It is intended for manual Windows
testing with NVDA, not as a replacement for automated tests.

Record the release candidate:

- Version:
- Fossil checkout:
- Build type:
- Windows version and build:
- NVDA version:
- Languages tested:
- Decks tested:

General rule for every step: no crash, no wxWidgets debug alert, no unexpected
focus jump, no untranslated internal control name, and no operation that risks
user data without a clear warning.

## 1. Package And Startup

- [ ] Expand the candidate zip into a fresh folder.
- [ ] Confirm the folder contains `cosimo.exe`, `voice.exe`, `README.md`,
  `CHANGELOG.md`, `LICENSE`, `docs`, and the source zip.
- [ ] Confirm the package does not contain a `decks` directory.
- [ ] Start `cosimo.exe`.
- [ ] Confirm the application opens without a console window.
- [ ] Confirm a usable default or chosen deck state is reached.
- [ ] Confirm the ready summary is focused on startup.
- [ ] Confirm the ready list has a meaningful accessible name.
- [ ] Press `F5` on the ready screen and confirm the screen refreshes without
  moving focus unexpectedly.
- [ ] Quit and restart. Confirm the last deck and ready view settings persist.

## 2. Menus And Localisation

Repeat this section in English, Spanish, and Galician.

- [ ] Open each top-level menu: File, Deck, Card, Study, Tools, View, Help.
- [ ] Confirm menu names and menu items are localised.
- [ ] Confirm mnemonics are spoken and no obvious mnemonic clashes occur within
  a menu.
- [ ] Confirm unavailable actions are disabled rather than misleadingly active.
- [ ] Open Help -> About and confirm version, beta status when applicable,
  authorship, and support address.
- [ ] Open Help -> User Guide.
- [ ] Open Help -> Project Wiki.
- [ ] Open Help -> Report Bug.

## 3. Options Dialogue

Repeat at least once in English and once in another canonical language.

- [ ] Open Tools -> Options.
- [ ] Confirm focus starts on the language field, not a stray label.
- [ ] Tab through all fields.
- [ ] Confirm checkboxes are announced by their user-facing text, not internal
  names such as `checkbox_options_...`.
- [ ] Change language and press OK with Enter. Confirm the main window updates.
- [ ] Reopen Options and confirm the saved language is selected.
- [ ] Change review audio, guiding tones, notification, tray, backup, and
  calibration options. Confirm OK persists them and Cancel does not.
- [ ] Use the delete obsolete backups button if test backups exist. Confirm the
  destructive confirmation behaves correctly and focus remains in the
  application afterwards.

## 4. Ready List And Card Management

Use a copy of a non-trivial deck.

- [ ] Move through the ready list with arrow keys.
- [ ] Change View sorting: deck order, next scheduled, last reviewed, prompt,
  response, estimated recall, ascending and descending. Confirm selection stays
  on the same card when possible.
- [ ] Type in the text filter. Confirm selection is preserved when the selected
  card remains visible.
- [ ] Change the card filter combo box, including flagged, suspended,
  non-reversible, duplicate prompts/responses, problem cards, and asymmetry if
  available.
- [ ] Press `Alt+Enter` on a selected card. Confirm card details opens.
- [ ] Open card details from the Card menu and from the context menu.
- [ ] In card details, confirm dates are shown as deltas followed by absolute
  times, and old attempt-history rows are readable.
- [ ] Add a card. Confirm the new card is selected.
- [ ] Try adding a duplicate prompt. Confirm it is refused.
- [ ] Edit a card. Confirm the same card remains selected when possible.
- [ ] Remove a card. Confirm selection moves predictably to the next or
  previous visible card.
- [ ] Flag, unflag, suspend, unsuspend, defer, and clear deferral from the Card
  menu and context menu. Confirm list labels and card details update.
- [ ] Mark a card non-reversible and allow reversal again. Confirm list labels,
  filters, and card details update.
- [ ] Make a card reversible, remove the reverse card, and recreate it. Confirm
  the parent card remains and reverse-card history is preserved.

## 5. Batch Add And Duplicate Repair

- [ ] Open Card -> Add Card Batch.
- [ ] Enter prompt and response, then press `Ctrl+Enter`. Confirm the card is
  added and focus returns to prompt.
- [ ] Enter prompt and response, then Tab forward from response. Confirm the
  card is added and focus returns to prompt.
- [ ] Press `Shift+Tab` from response. Confirm focus moves back to prompt.
- [ ] Press Escape. Confirm the dialogue closes once.
- [ ] If using a deliberately duplicated deck, open Deck -> Resolve Duplicate
  Prompts. Choose a response and confirm duplicate prompt cards are removed as
  expected.

## 6. Ordinary Study Session

- [ ] Start a scheduled study session if available.
- [ ] Confirm startup focus is on the prompt/summary as documented for that
  phase.
- [ ] Use number keys for confidence.
- [ ] Use Space or the Reveal button to reveal without answering confidence.
- [ ] Confirm response is shown and recall buttons are reachable.
- [ ] Use number keys for recall.
- [ ] Flag and unflag during the prompt and response phases.
- [ ] Defer a card before reveal. Confirm it leaves the session and is not
  counted as answered.
- [ ] Edit a card after reveal. Confirm the edited value is visible when the
  dialogue closes and focus returns to the previous control.
- [ ] End the session early with `0`. Confirm the summary clearly says the
  session was unscheduled or partial when appropriate.
- [ ] Press Enter on the summary. Confirm Continue activates.
- [ ] Save the study-session report. Confirm a report file is written under
  `reports`.
- [ ] Continue from the summary. Confirm focus lands on the ready list.

## 7. Flagged Study

- [ ] Flag several available cards.
- [ ] Confirm Study Flagged is enabled.
- [ ] Start a flagged study session.
- [ ] Confirm only flagged, non-suspended, non-deferred cards are included.
- [ ] Confirm the summary identifies the session as unscheduled.
- [ ] Confirm flags are not cleared by studying.

## 8. Exam Mode

- [ ] Start an untimed exam by question count.
- [ ] Start an untimed exam by percentage.
- [ ] Confirm the setup toggle between count and percentage clears the value
  without moving focus unexpectedly.
- [ ] Answer one question exactly and one inexactly.
- [ ] Confirm exact answers are accepted automatically.
- [ ] In grading, confirm prompt, your answer, and expected answer can be read
  by tabbing.
- [ ] Use `Ctrl+Y` and `Ctrl+N` in grading.
- [ ] Confirm the summary is a read-only field and includes percentage correct
  and time per question.
- [ ] Save the exam report.

## 9. Exact And Timed Exam

- [ ] Start an exact exam.
- [ ] Give an inexact answer. Confirm it appears in the review phase rather
  than grading.
- [ ] Complete an exam without timing out. Confirm two long tones play, the
  `Exam Finished` notice is shown, and Tab to Next is required before grading,
  review, or summary.
- [ ] In exact review, use `Alt+N` for Next.
- [ ] Use Summary to leave review early.
- [ ] Start a timed exact exam with a short time limit on a disposable deck.
- [ ] Type a partial answer and wait for timeout.
- [ ] Confirm the typed answer is submitted on timeout.
- [ ] Confirm the timeout tone plays.
- [ ] Confirm the timeout dialogue is shown and Enter/Space from the read-only
  message does not accidentally continue.
- [ ] Tab to Next and continue.
- [ ] Confirm exact review works after timeout without wxWidgets debug alerts.

## 10. Quiz Mode

- [ ] Start a quiz by count.
- [ ] Start a quiz by percentage.
- [ ] Confirm choices are all responses for the current study direction, not a
  mixture of prompts and responses.
- [ ] Confirm there are four distinct choices when a quiz is available.
- [ ] Confirm feedback is withheld until the review phase.
- [ ] Use `Alt+N` in quiz review.
- [ ] Confirm quiz summary is report-only and does not change schedules.
- [ ] Save the quiz report.

## 11. Audio Playback

Use a deck with at least one prompt and response Opus file. If feasible, also
leave one legacy WAV-only card to confirm fallback playback.

- [ ] On the ready list, select a card with audio. Confirm Play/Stop Audio is
  available.
- [ ] Press `Ctrl+P`. Confirm prompt audio plays, then response audio.
- [ ] Press `Ctrl+P` during playback. Confirm current playback stops.
- [ ] Change list selection during playback. Confirm playback continues or
  stops according to the current documented behaviour, without freezing the
  list.
- [ ] In ordinary study, test review audio Off, Manual, and Automatic.
- [ ] With guiding tones enabled, confirm prompt tone, response tones, and
  session-end arpeggio are present and not excessive.
- [ ] In exam grading/review, test automatic audio Off, Question, Answer, and
  Both.
- [ ] In quiz mode, test quiz audio Off, Question, Answer, and Both if the deck
  has audio.

## 12. Audio Generation

Use a disposable deck copy.

- [ ] Open Deck -> Edit Metadata.
- [ ] Remove voice metadata and save. Confirm Tools -> Generate Audio is
  disabled.
- [ ] Add prompt and response voices and engines. Confirm Generate Audio becomes
  enabled immediately after save.
- [ ] Mark the deck as manual audio. Confirm Generate Audio becomes disabled.
- [ ] Unmark manual audio.
- [ ] In Tools -> Options, confirm Audio generation format defaults to Opus.
- [ ] Run Tools -> Generate Audio.
- [ ] Confirm the progress bar is exposed as a progress bar and is not read as
  repeated text.
- [ ] Confirm completion reports how many files were generated, skipped,
  regenerated or converted, preserved, or failed.
- [ ] Edit one card and run generation again. Confirm manifest-tracked audio
  for that side is regenerated, while untracked `.opus` or `.wav` files are
  preserved.
- [ ] If feasible, switch Audio generation format to WAV on a disposable deck
  and confirm new generated files use `.wav`.
- [ ] Try metadata naming a missing voice if feasible. Confirm the error is
  clear and no unrelated files are overwritten.

## 13. Backups, Restore, And Database Maintenance

Use disposable deck copies only.

- [ ] Export full deck bundle. Confirm the zip contains the deck and sidecar
  files, not the review database.
- [ ] Export full deck with study history. Confirm the zip includes a review
  database snapshot.
- [ ] Write full deck backup. Confirm it appears in `backups` and is indexed.
- [ ] Restore a full deck bundle into an empty target. Confirm preview counts
  cards, audio files, and study history presence.
- [ ] Restore over an existing deck. Confirm overwrite warning and automatic
  backup of the existing target.
- [ ] Run Scrub Review Database. Confirm warnings match backup policy.
- [ ] Run Reclaim Database Space. Confirm focus returns to the previous ready
  control and no data visibly changes.
- [ ] Open a known corrupt or copied-invalid database if available. Confirm the
  error message identifies the path and consequence.

## 14. System Tray And Notifications

- [ ] Enable minimise to tray.
- [ ] Minimise with the Windows minimise action.
- [ ] Confirm the main window hides and the tray icon appears.
- [ ] Press Enter or Space on the tray icon. Confirm Cosimo restores and focus
  returns to the application without a stray announcement of the next tray
  item.
- [ ] Minimise again and use tray Restore from the context menu.
- [ ] Minimise again and use tray Quit. Confirm `cosimo.exe` exits.
- [ ] Restore from tray and then quit from the main window. Confirm the process
  exits.
- [ ] With sound notifications enabled, leave Cosimo open until cards become
  available if practical. Confirm notification policy respects visible,
  minimised, and never settings.

## 15. Deck Sync Branch

Run this section only for a build that includes the deck-sync work. Use
disposable deck copies and a private sync storage directory.

- [ ] Start `cosimo-sync-server` with a private storage root, for example
  `cosimo-sync-server --bind 127.0.0.1:44791 --storage-root PATH`.
- [ ] In Cosimo, set `Tools -> Options -> Sync server URL` to
  `http://127.0.0.1:44791`.
- [ ] Set or change the local device name and confirm it persists after OK.
- [ ] Confirm `Deck -> Sync -> Sync Status` shows the local device name and
  does not expose any separate local application ID.
- [ ] Open `Deck -> Edit Metadata`. Confirm visibility can be changed and that
  no editable sync owner field is present.
- [ ] Open `Deck -> Sync -> Sync Status` before logging in. Confirm the report
  explains that sync settings are incomplete or unavailable.
- [ ] Use `Deck -> Sync -> Log In` with a Mastodon-compatible test account.
  Confirm Cosimo opens the authorisation URL, accepts the out-of-band code, and
  reports the authenticated sync owner.
- [ ] Reopen Sync Status. Confirm owner identity, server URL, local device
  name, and remote missing/present state are understandable.
- [ ] Upload with study history. Confirm the result reports the deck UUID,
  revision, bundle hash, and study-history inclusion.
- [ ] Open Remote Decks. Confirm the uploaded deck is listed for the logged-in
  owner.
- [ ] In Remote Decks, use Copy ID on the uploaded deck. Confirm the clipboard
  contains the deck UUID.
- [ ] If testing an unlisted deck, use Find by ID with the copied UUID or a
  shared deck URL. Confirm the matching deck is added to the list and can be
  inspected before download.
- [ ] In a second portable copy or clean configuration, set the same sync
  server URL, log in as the same owner, and download with study history.
  Confirm a full compressed backup is written before any existing files are
  replaced.
- [ ] Confirm the downloaded deck opens, audio sidecar files are present when
  expected, and study history/schedules are present.
- [ ] Make an upload from one copy, then attempt an upload from a stale second
  copy. Confirm Cosimo reports a revision conflict rather than overwriting.
- [ ] Change deck visibility and upload again. Confirm the change is accepted
  when the local revision is current.
- [ ] Use `Deck -> Sync -> Log Out`. Confirm Cosimo clears the local sync owner
  and token, and that owner sync actions require logging in again. If testing
  against a durable server, confirm the previous bearer token no longer works.
- [ ] Confirm public/unlisted shared downloads, if tested through the server
  API, do not include the `.reviews.sqlite3` file.

## 16. Release Documentation

- [ ] Open `README.md` and confirm the current beta/stable wording is correct.
- [ ] Open `CHANGELOG.md` and confirm unreleased/released sections are correct.
- [ ] Open the English, Spanish, and Galician user guides if they changed.
- [ ] Confirm installation and upgrade instructions still match the release
  package contents.
- [ ] Confirm accessibility acceptance notes list the actual Windows and NVDA
  versions used for this pass.

## Result

- [ ] PASS: ready to tag/release.
- [ ] FAIL: do not tag/release. Record failing step numbers and observed
  behaviour.

Notes:
