Projects and files
A Flux project is a folder you can open, inspect, back up, and share. Knowing what lives there makes the rest of the workspace easier to understand.
Your documents are plain-text Quarto files. Bibliographic entries live in BibTeX. Figure compositions and slide decks use readable JSON, with their accepted assets kept in the project. The application connects these files into a working environment.
A quick tour
Every project folder, here called my-project/, contains:
| Path | What it holds |
|---|---|
project.json |
Project identity and registered documents |
paper/ |
Manuscripts and working notes (.qmd) |
plots/ |
Plots produced by your analysis |
fig/ |
Figure compositions, captions, accepted assets |
slides/ |
Decks, animation steps, accepted assets |
references/ |
The bibliography cited by this project |
Context/ |
ProjectContext, Log, and project rules |
exports/ |
Generated documents and presentations |
Older projects may use manuscript/ for documents; Flux supports that layout too. The complete layout reference describes indexes, metadata, and additional folders.
Sources, compositions, and exports
These three kinds of files play different roles:
| Kind and examples | How to work with it |
|---|---|
Source material.qmd documents, plot outputs, references/ |
Edit with Flux, a text editor, or the analysis script that produces them. |
| Managed composition Figure and deck JSON, captions, accepted SVG or GLB assets |
Inspect freely. Make structural changes through Flux or its CLI so indexes and references stay coherent. |
Generated outputfig/renders/, exported PDF and Word files, previews |
Regenerate from sources. Keep a final export when it records a submitted or shared version. |
A rendered preview is replaceable. An accepted plot or mesh in fig/assets/ or a deck’s assets/ is part of the saved composition: retain it when sharing or backing up a project.
One plot, several uses
plots/. Flux keeps an accepted copy in fig/assets/ that every workspace reads and that follows the source when it changes.
Your analysis writes a source plot into plots/. Inserting it into Figure stores an accepted copy and the link to its source. The composition records placement, styling, and captions separately from the original data visualization.
When a linked SVG source changes, Flux refreshes the accepted SVG, manifest, and recipe. A 3D model instead offers an explicit Update from source action; its saved mesh stays in place until you accept that update. Figure, Paper, and Slides read that accepted version. Stable part identities let Flux retain edits to a named series while its data change.
The figure catalog makes the link visible:
- Linked · current — the accepted copy matches the source.
- Updating — a source change is being processed.
- Source missing or Update failed — the last good version is retained; review the error and retry Reload sources when ready.
- Frozen version — the figure deliberately keeps an independent saved version.
Use Relink… for a source that moved, or Resume updates to reconnect a frozen version. A slide copy has its own layout and annotations even when it shares source assets.
A title is not a file path. Figure titles, publication numbers, and permanent reference keys serve different purposes. Renaming a figure leaves its permanent reference intact. Moving an embedded figure in Paper does not change its designation.
Saving and outside edits
Flux autosaves as you work. A successful file replacement writes a temporary file before renaming it into place. Figure and deck saves also retain recovery information while related files change.
Edits still waiting to save are not yet on disk. If a save fails, Flux keeps the editor dirty and reports the problem. Resolve it before closing; autosave is not a substitute for a backup.
Flux also watches for edits made by another tool. If the affected file has no unsaved changes, the app reloads it. If you are mid-edit, it shows a conflict banner. Read the choices before deciding which version to keep. Figure’s Overwrite with mine preserves both versions in its conflict records before saving; newer or unreadable formats can refuse an overwrite.
Undo remains available in the editors, including for supported external edits brought into the live workspace.
Your library and a project’s references
FluxLib is your shared reference library. It contains the papers and attachments you collect across projects and lives inside your personal FluxConfig folder.
Each project keeps its own references/library.bib: real copies of the entries it cites. This means the manuscript’s bibliography can travel with the project. Your entire personal library does not have to travel with it.
Library PDFs and annotations may live outside the project. If a collaborator needs those attachments, share them separately or include the appropriate files deliberately. A project’s bibliography alone is not a copy of every PDF in FluxLib.
Working alongside an agent
Humans and agents work with the same project folder. The project’s Context/ records its background, Log, and rules. Your personal context lives in your FluxConfig folder and applies across projects.
Flux’s commands coordinate edits with the app. An advisory lock can defer a command while the app is writing; supported project mutations are journaled so you can inspect who changed what. Use the CLI or connected tools for managed figures and decks, and keep comments attached to the passage, figure, or slide they concern.
Connect an agent · Understand context · Comments and Inbox
Share, back up, and return
Keep the complete project folder, including composition files and accepted assets. Plain text and JSON work well with version control. Generated previews and caches can usually be excluded; exported deliverables are worth retaining when their exact published state matters.
An external analysis environment is a separate dependency. The accepted plot remains viewable when shared, but regenerating it may need the original script, data inputs, and Python environment. Share those alongside the project when reproducibility is part of the handoff.
For a clean handoff:
- Let pending saves finish and resolve any reported errors.
- Copy the project folder with its accepted assets.
- Include source scripts, inputs, and an environment lockfile when regeneration is needed.
- Open the copy and check the documents, figure links, and presentation.
Local save transactions do not make a cloud-sync snapshot atomic. Keep a separate backup, and check synchronization has finished before switching machines.