Tutorial

The tutorial follows one literature search from the first query to a library you can question: papers on particle-in-cell simulation of Hall thrusters, the electric engines of many satellites. Each chapter runs real commands; the output on these pages is what they printed, captured in a fresh home directory by docs/scripts/docs_examples.py. Your results will differ in the details: the sources answer with what they hold today.

Chapter	You learn
1. A first search	mosaic search, the results table, which sources answer
2. Narrowing the results	one source, years, title-only queries, authors, open access, sorting, per-source counts
3. The local cache	what mosaic remembers, searching offline, mosaic cache
4. Getting the PDFs	--download, mosaic get, a BibTeX file of DOIs, file names, checking the library
5. Paywalled papers	your own browser with --handoff, mosaic import, saved sessions
6. Exporting	BibTeX, RIS, CSV, JSON and Markdown files, citations, Obsidian notes, Zotero
7. Following a field	papers related to one you like, saved searches that report what is new
8. A local model	relevance ranking, a summary of the results, a comparison table
9. Asking your library	the vector index, search by meaning, questions answered from your papers
10. The citation network	citation edges, hub papers, clusters, a graph file

Chapters 1–7 need only mosaic and a network connection. Chapters 8–10 use a language model and an embedding model; the tutorial runs both on the same machine with Ollama, and an OpenAI-compatible server or a cloud API works the same way.

Before you start

Install mosaic (Installation) and check it runs:

$ mosaic --version
mosaic 1.9.2

mosaic keeps its configuration in ~/.config/mosaic/config.toml, its cache in ~/.local/share/mosaic/cache.db and the PDFs in ~/mosaic-papers/. It writes nothing else outside the folders you name.

Then

The Cookbook answers one task per recipe; the Guides explain each feature in depth; the Reference lists every command and option.