# Deck Format

Cosimo deck files store the editable learning material: prompt/response pairs,
optional deck metadata, stable card IDs, and authored card facts such as "this
card should not be reversed". Review history, prompt dates, scheduling data,
and user ratings belong in separate storage so decks stay easy to read and
edit.

Recommended extension: `.cosimo-deck`

## Format

Current decks begin with a metadata header. The header starts with
`deck_version=2` and ends with a line containing only `:::`. Metadata lines use
`key=value`.

Write the prompt first, then a line containing only `---`, then the response.
End each entry with a numbered terminator line such as `=1=`.

```text
deck_version=2
title=Spanish capitals
author=Example author
:::

Capital of Spain
---
Madrid
=1=

Translate this sentence:
I opened the window.
---
Abri la ventana.

Also acceptable:
He abierto la ventana.
=2=
```

The number is the card's stable identity. It is not shown during review, but it
lets Cosimo keep the same statistics when you edit a prompt or response.

When manually editing an existing card, keep its existing numbered terminator.
When manually adding a new card, prefer `===` and let Cosimo assign the number
on the next open. Hand-picking or reusing a numeric terminator can attach the
new card to old dormant review history.

The Deck menu can show deck properties and edit the standard metadata fields:
title, author, description, URL, prompt voice, prompt voice engine, response
voice, response voice engine, and whether automatic audio generation is
disabled for the deck. Unknown metadata keys are preserved when these standard
fields are edited.

The optional `deck_uuid` metadata key is a stable UUID for future deck sync and
sharing. It identifies the deck across file renames or copies. The optional
`visibility` metadata key is the deck author's default sharing preference and
uses `private`, `unlisted`, or `public`. Missing or unrecognised visibility is
treated as private by Cosimo. A future sync server will remain authoritative
for access control; these deck fields are shareable deck metadata, not login
credentials.

Cosimo may write `next_card_id` as internal metadata. It is a high-water mark
for future card IDs, so new cards continue to receive monotonic IDs even after
removed-card database history has been scrubbed. Users should normally leave it
unchanged.

The optional `prompt_voice` and `response_voice` metadata keys are default
voice filters for the Windows `voice.exe` helper. `prompt_voice_engine` and
`response_voice_engine` name the preferred synthesis engine for each side, for
example `onecore` or `sapi`.
Command-line voice and engine options override them. They are deck metadata
because the intended language, voice, or voice engine for each side is useful
when a deck is shared. The metadata editor can show both OneCore and SAPI voices
in one list, but the stored engine value remains a concrete engine rather than
`both`.

The optional `audio_generation=disabled` metadata key marks a deck as a manual
audio deck. Cosimo still plays existing sidecar audio, but `Tools -> Generate
Audio` is disabled and `voice.exe` refuses to generate or overwrite audio for
that deck. Missing `audio_generation` metadata, or any value other than
`disabled`, means generation is allowed when the required voice metadata is
complete.

Use `=1i=` instead of `=1=` to mark card 1 as non-reversible. This means the
card should not have a generated reverse direction, even during bulk reversal.
Plain `=1=` means the deck makes no statement about reversibility.

Legacy files may omit the metadata header or use `===` as the terminator.
Current v2 decks may also contain `===` if a user adds cards by hand without
choosing card IDs. This is the recommended form for manually added new
cards. Use `=i=` instead when manually adding a new card that should be
non-reversible, but should still let Cosimo assign the numeric ID. When the
application opens a deck with missing card numbers, it backs up the original
deck according to the deck backup setting, adds the v2 header if
needed, assigns unused card numbers, migrates any old database-only
non-reversible markers into `=numberi=` deck markers, and writes the deck back
in the current format.

## Sidecar Directory

Cosimo uses a same-stem directory beside a deck file for optional review audio.
For example, a deck named `Indonesian.cosimo-deck` may have a neighbouring
directory named `Indonesian/`. Cosimo reads audio files from this directory
during ordinary review, and reads prompt audio while answering exam questions,
when review audio is enabled. Current builds prefer `.opus` files and fall back to
legacy `.wav` files with the same card ID and side. Cosimo's automatic
deck-content and review-database backups do not include sidecar audio files,
but full-deck bundle exports and full-deck backups do. Windows packages also
include the `voice.exe` helper, which can generate Opus or WAV files in this
layout from installed OneCore or SAPI voices.

Audio files are keyed by the stable card ID and by deck side:

```text
Indonesian.cosimo-deck
Indonesian/
  1.prompt.opus
  1.response.opus
  2.prompt.wav
  2.response.wav
  audio-manifest.tsv
```

A generated reverse direction can then reuse the same files with prompt and
response swapped, rather than needing separate duplicate audio. If richer
per-card adjunct data is needed later, text or metadata files in the same
directory can be added without changing the core deck syntax.

`File -> Export Full Deck` and `File -> Full Deck Backup` write zip archives
containing the `.cosimo-deck` file and this same-stem sidecar directory. They
do not include the `.reviews.sqlite3` review database, because review history
and scheduling are separate learner data. `File -> Export Full Deck with Study
History` additionally includes a SQLite backup snapshot of that review database
for personal migration or complete manual backups.

`File -> Restore Full Deck` validates one of these bundles and restores it into
the `decks` directory. The bundle layout is intentionally narrow: one root
`.cosimo-deck` file, an optional matching root `.reviews.sqlite3` review
database, and optional files under the sidecar directory whose name matches the
deck stem. If files would be overwritten, Cosimo writes a full compressed
backup of the existing target deck before replacing them.

`voice.exe` maintains `audio-manifest.tsv` in the sidecar directory. It records
the text hash, selected voice filter, and selected voice engine used for
managed audio files. Generation is conservative around user recordings:
manifest-tracked audio is Cosimo-managed and may be regenerated or converted to
the selected output format, but existing untracked `.opus` or `.wav` files are
left untouched and block generation for that card side. `Tools -> Remove
Inoperative Audio from Deck` can later delete Cosimo-recognised sidecar audio
for card IDs that no longer exist, and lower-preference files hidden by a
preferred format for the same card side. It also prunes matching manifest
entries. The manifest is generated audio state, not authored deck content.

Users who keep their own recordings should either use full-deck bundle backups
or back up the sidecar directory separately from Cosimo's automatic
deck-content and review-database backups.

## Rules

- Prompt and response text may span multiple lines.
- Blank lines at the start or end of a prompt or response are ignored.
- Blank lines inside a prompt or response are preserved.
- Prompts should be unique. Cosimo refuses normal add and edit actions that
  would create duplicate prompts. If a deck is edited by hand and duplicate
  prompts are introduced, Cosimo opens it with a warning and can resolve them
  from `Deck -> Resolve Duplicate Prompts`.
- Duplicate responses are allowed. They become ambiguous only for generated
  reverse cards: from each group of cards with the same response, at most one
  card may have an active generated reverse card.
- Lines containing exactly `---`, `===`, `=i=`, `=number=`, or `=numberi=` are
  reserved inside prompts and responses as card separators.
- The line `:::` separates the metadata header from the cards. In current deck
  files it is only special before the card body starts, so it may appear inside
  prompt or response text.
- Do not renumber existing cards by hand unless you intentionally want to
  change which review history belongs to that card.
- No review history, prompt timestamps, scheduling state, or user ratings are
  stored in this file.
