> For AI agents: the complete documentation index is available at https://docs.flashnerd.com/llms.txt, the full documentation bundle is available at https://docs.flashnerd.com/llms-full.txt.

# Flashnerd file format

A `.flashnerd` file is an **unencrypted ZIP archive** containing structured records and, when needed, image or audio files. This reference defines the archive paths, record properties, field types, and relationships used to construct an importable file.

## How the data fits together

Record collections use **UTF-8 JSONL**, with one complete JSON object per physical line. Use the exact archive paths, such as `content/decks/` and `content/cards/`, without an extra enclosing folder. Portable user preferences use a single JSON object instead. See [package rules](https://docs.flashnerd.com/reference/flashnerd-format/package.md) for the exact paths, required properties, and limits.

A deck includes its template: field IDs, names, types, sides, and settings. Each card supplies its own content in a `values` map keyed by those field IDs, with matching value types. Ordinary card records use `deckId` to reference a deck included in the archive. Other record relationships also use explicit IDs, with companions determined by the [dependency rules](https://docs.flashnerd.com/reference/flashnerd-format/package.md#dependencies).

## Find a definition

| Reference                                                                                              | Defines                                                                               |
| ------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------- |
| [Package rules and dependencies](https://docs.flashnerd.com/reference/flashnerd-format/package.md)     | ZIP layout, JSONL, IDs, required input, dates, limits, and optional manifest metadata |
| [Decks and templates](https://docs.flashnerd.com/reference/flashnerd-format/decks.md)                  | Deck records, field definitions, deck settings, and preset selections                 |
| [Card records](https://docs.flashnerd.com/reference/flashnerd-format/cards.md)                         | Card identities, deck references, value maps, tags, and overrides                     |
| [Field values and settings](https://docs.flashnerd.com/reference/flashnerd-format/fields.md)           | All field types, their content structures, and inherited or overridden settings       |
| [Images and audio](https://docs.flashnerd.com/reference/flashnerd-format/media.md)                     | Bundled media files and the paths used to reference them                              |
| [Folders and tags](https://docs.flashnerd.com/reference/flashnerd-format/folders-and-tags.md)          | Folder hierarchy, deck placement, and tag records                                     |
| [SRS collections and settings](https://docs.flashnerd.com/reference/flashnerd-format/srs.md)           | SRS folders, sets, linked decks, and scheduling settings                              |
| [Preset records](https://docs.flashnerd.com/reference/flashnerd-format/presets.md)                     | Card-template, SRS, search, and AI-instruction presets                                |
| [Portable preferences](https://docs.flashnerd.com/reference/flashnerd-format/preferences.md)           | Supported user preferences and their values                                           |
| [Schedules and history](https://docs.flashnerd.com/reference/flashnerd-format/progress-and-history.md) | Exported study progress, review events, and restoration requirements                  |
| [Exact enum values](https://docs.flashnerd.com/reference/flashnerd-format/enums.md)                    | Accepted strings and numeric enum values                                              |
| [Validation and downloads](https://docs.flashnerd.com/reference/flashnerd-format/validation.md)        | Package checks, schemas, a comprehensive example, and common failures                 |

## Choose the import context

For an **ordinary archive**, use the record definitions above and include each record's required companions. A new deck needs its field definitions; its cards reference that deck and those fields. Packages can also contain supported presets or preferences without a deck. The [dependency table](https://docs.flashnerd.com/reference/flashnerd-format/package.md#dependencies) defines which collections can stand alone.

For **cards targeting an existing deck**, follow [Cards-only files](https://docs.flashnerd.com/reference/flashnerd-format/cards-only.md). Use that deck's **Download Starter Template** to obtain its field IDs and types. Cards-only files omit deck records and each card's `deckId`; the destination template supplies the context.

For new learning material, omit study schedules and history. When restoring genuine exported progress, follow [Schedules and history](https://docs.flashnerd.com/reference/flashnerd-format/progress-and-history.md). App steps for either import destination are in [Import Flashnerd files](https://docs.flashnerd.com/guide/import-export/flashnerd.md).

## Use with an AI tool

Give the AI this overview's URL or **Copy Markdown** content, the relevant record and field references, and your content requirements. For an existing deck, also supply its downloaded starter. The linked definitions describe the supported structures; choose the field types that suit the material.

Use the [JSON schemas](https://docs.flashnerd.com/reference/flashnerd-format/validation.md#json-schemas) to check individual records and the [validation checklist](https://docs.flashnerd.com/reference/flashnerd-format/validation.md#checks-before-importing) to check the package and its intended destination. Schemas alone cannot establish valid relationships across files or compatibility with an existing deck. Ask the tool to report which checks it actually performed, then review the content and import preview.