# How to organize your library for BOOKITCA

BOOKITCA needs no special format and no conversion. It reads ordinary book files from the library folder in your storage. This guide is written so that both a person and an AI agent can follow it.

## Where books go

- Default library, created by the app on first launch: iCloud Drive › BOOKITCA. Without iCloud, Files › On My iPhone › BOOKITCA (On My iPad on iPad).
- Dropbox: the folder Apps/Bookitca. It appears after you connect Dropbox in the app.
- Other storage: the app shows the exact location in Settings › Library storage › the storage name › Folder.
- Audiobookshelf: the app takes books from the libraries on your server as Audiobookshelf manages them. Organize them there; the rules below apply to folders in the other storage services.
- Several services at once: each has its own library folder. The same book in two services shows up twice in the app.
- Subfolders are fine, for example by author or genre. The app reads the whole library folder.

## Formats

- Ebooks: EPUB, PDF and DRM-free Kindle files (MOBI, AZW3, AZW, PRC).
- Older formats from long-kept archives: FB2, PDB (PalmDOC), RTF and TXT. The app reads them converted and leaves the original alone. A TXT under 20 kB and notes like readme.txt don't count as books.
- Audiobooks: M4B, M4A, MP3, or a ZIP of MP3s as stores offer them for download. Don't unzip it, BOOKITCA plays it as is.
- DRM: books locked with classic DRM (Adobe, Kindle, a store's own app) can't be opened. Social DRM (watermarking) is fine.
- Other files, hidden files (starting with a dot) and unfinished downloads (.download) are ignored.

## Rules

1. An ebook is one file. It can be anywhere in the library folder.
2. The same ebook in several formats side by side (Book.epub and Book.mobi) counts once. EPUB wins, then AZW3, MOBI, AZW, PRC, PDB, FB2, RTF and finally TXT. A Calibre folder (with metadata.opf) is one book even with several formats inside, and gets cover.jpg as its cover.
3. An audiobook made of several files is one folder. Each file is a chapter, in natural name order (01, 2, 10, like Finder).
4. Every folder with audio files is a separate book. An audiobook split into CD1 and CD2 subfolders would become two books: put all tracks in one folder and name them so they sort in order (CD1 01.mp3, CD1 02.mp3, CD2 01.mp3).
5. A single-file audiobook (M4B or MP3) goes straight into the library root, or alone into its own folder. Two such files in one folder would be one book with two chapters. A ZIP audiobook can be anywhere.
6. Title and author come from the file's own metadata (EPUB, MOBI, FB2, PDF, and M4B, M4A and MP3 tags). The file name is only a fallback.
7. Cover: if the file has none embedded, an image next to the book is used.
   - Ebook or single-file audiobook: an image with the same name (Book.epub and Book.jpg).
   - Audiobook folder: cover.jpg, folder.jpg or front.jpg (PNG works too). Otherwise an image named like the folder, otherwise the largest image in the folder.
8. Companion files in an audiobook folder (bookinfo.html, .opf, .nfo, .cue, .m3u, .pls) are read for book details.
9. The .bookitca folder belongs to the app (reading positions, collections, stats). Don't delete it or write into it.
10. Renaming or moving a book inside the library is fine. The app recognizes it by content and keeps the reading position (as long as the file itself is unchanged). Two copies of the same book in the library show up twice, though: inside the library, move, don't copy.

## Example

```
Bookitca/
  Karel Čapek, War with the Newts.epub
  Karel Čapek, War with the Newts.jpg
  The Count of Monte Cristo.m4b
  Saturnin.zip
  Old Czech Legends/
    cover.jpg
    01 Forefather Čech.mp3
    02 About Krok.mp3
  Crime/
    Murder on the Orient Express.epub
```

## Uploading many books at once

Copy the books from your computer into the library folder, hundreds at once if you like. Your storage uploads them and BOOKITCA adds them on the next sync. Large audiobooks aren't downloaded in full, they play straight from storage.

## Instructions for AI agents

- Download from a store only what the store itself lets you download as a file. Don't circumvent DRM and don't sign in on the user's behalf without their consent.
- Don't convert or unzip anything. Keep the original files.
- Don't delete or overwrite files already in the library folder. Don't touch the .bookitca folder.
- Follow rules 3 to 5: one multi-file audiobook = one folder.
- If a cover is missing and you have one, save it next to the book as in rule 7.
- Workflow: inventory first, then a proposal and the user's approval, only then any moves. Afterwards check that everything is in place (sizes or checksums where possible) and report, including what failed.
- Don't guess an ambiguous case, skip it and report it. Only report duplicates, don't delete them.
- Don't pretend operations happened or that playback was verified in the app.
- A ready-made AI librarian prompt covering all of this: https://www.bookitca.app/assets/guides/bookitca-ai-librarian-en.md
