Library and configuration

Flux’s reference system has two layers, and the split is what lets a permanent reading library coexist with fully self-contained projects:

• FluxLib — the machine-global library. One collection of papers for you, shared by every project on the machine. This is what the Library workspace manages: every paper you save, its PDF, your highlights and notes, tags, collections, reading status.
• The project’s cited subset — each project carries its own references/library.bib holding real copies of just the entries it cites. Citing a paper in a manuscript materializes its entry from FluxLib into the project.

The point of the split: your library can grow to thousands of papers without bloating any project, and a project still zips, clones, and compiles standalone — hand the folder to a collaborator and every citation resolves, no FluxLib required.

The citekey is the join key#

Every paper has one stable citation key (smithNeuralBasis2021-style — the same format Zotero’s Better BibTeX plugin uses, so keys arriving from a Zotero sync and keys Flux mints itself look alike). That key is how you cite it in any manuscript ([@smithNeuralBasis2021]), the name of its folder in the library, and the handle agents use to fetch, highlight, or discuss it. Keys are permanent join keys — they never change out from under a project.

What’s inside FluxLib#

FluxLib lives at <FluxConfig>/FluxLib (by default ~/FluxConfig/FluxLib; flux config prints this machine’s paths). Like projects, it’s plain files with a clear source-vs-derived split:

• library.bib — the canonical BibTeX file and the source of truth for your references. Any reference manager that reads BibTeX can open it.
• items/<citekey>/ — everything belonging to one paper: the PDF (or, when Zotero sync runs in linked mode, a small pointer file naming the PDF in Zotero’s folder), a supplements/ folder for supplementary files, your highlights, and the extracted text that powers full-text search.
• pdfs_to_assign/ — the watched inbox folder for PDFs (not the comment Inbox): drop PDFs here and Flux identifies each one from its own contents and files it under the right paper (refusing, rather than guessing, when it isn’t sure).
• .fluxlib/ — derived indexes (search, full-text, enrichment). Rebuildable caches, never the truth: delete them and Flux regenerates them from the files above.

Portability#

Because it’s all files, moving machines is copying a folder: ~/FluxConfig carries your library (FluxLib/), your agent context and skills (Context/UserContext/, including Skills/), and your global plot library (plot_library/). Back it up like you’d back up your documents — it is documents.