Project layout

A Flux project is a plain folder whose marker is project.json. Here is the canonical tree:

<project>/
├── project.json                 # the map: title, authors, documents, figures, references
├── paper/                       # YOURS — documents and arbitrary nested folders
│   ├── notes.qmd                #   a starter document; no required main.qmd
│   ├── notes.comments.json      #   its margin-comment threads
│   └── _quarto.yml              #   shared export settings
├── plots/                       # YOURS — analysis output lands here, any structure you like
│   ├── growth.{svg,fluxplot.json,recipe.json}   #   a semantic plot + manifest + recipe
│   ├── neuron.{glb,fluxplot.json,recipe.json}   #   a 3D mesh + semantic manifest + recipe
│   ├── _dissections/growth/     #   growth's companion material (per-subject panels, stats CSVs)
│   ├── _lighttable/             #   Lighttable collections for exploratory image sets
│   ├── _videos/                 #   video clips for slides
│   ├── pasted/                  #   originals of images pasted from the clipboard
│   └── paper_snips/             #   regions snipped out of PDFs in Reader
├── fig/                         # APP-MANAGED — the figure subsystem
│   ├── index.json               #   canvases + figures rollup
│   ├── canvases/<id>.json       #   the real compositions (figures → elements)
│   ├── captions/<id>.md         #   composed caption mirror, reconciled with the composition
│   ├── assets/                  #   accepted SVG/GLB bundles + semantic sidecars
│   └── renders/                 #   derived static renders
│       └── model3d/             #   keyed PNG posters; meshes remain in assets/
├── slides/<deckId>/deck.json    # APP-MANAGED — one deck per folder (+ its assets/)
├── references/library.bib       # YOURS — the project's cited subset (BibTeX)
├── AGENTS.md                    # passive pointer to flux-connect
├── CLAUDE.md                    # imports AGENTS.md
├── Context/                     # the agent layer
│   ├── ProjectContext.qmd       #   background, goals, data and must-read links
│   ├── NOTEBOOK.md              #   append-only Log, written when requested
│   └── RULES.md                 #   your standing project rules
├── styles/  assets/  exports/   # figure styles · media · compiled output (derived)
└── .meta/                       # tool state: journal, annotation ledger, locks, schemas
    ├── feedback.ndjson          #   append-only annotations, routes, claims and status
    ├── feedback/                #   annotation pictures
    ├── live/sessions/           #   connected-session presence (disposable)
    └── archive/                 #   historical material moved by the one-shot migration

Ownership at a glance#

Notes on specific pieces#

• project.json is a derived rollup — a fast map of the project, rebuilt from the real files (flux reindex refreshes it if a script edited things directly).
• Figure identity lives in the composition. A permanent referenceKey survives title, number, and canvas changes; index.json and project rollups preserve it when rebuilt. Filenames use persistent IDs. Paper document order has no effect on those identities. Caption markdown is a readable mirror: independent edits reconcile against the last saved version, while conflicting edits are preserved and reported instead of silently replacing one another. .meta/figure-reference-update.json, when present, protects an interrupted panel-reference rewrite until recovery finishes.
• Comments live beside documents, never in them. New documents use <name>.comments.json. A legacy main manuscript retains its historical comments.json. Moving a document in Paper moves its comments too.
• Older layouts remain supported. manuscript/ is discovered alongside paper/; Flux never renames an existing project folder automatically. New manifests name documentRoot as paper and retain manuscript.path as a default export pointer for compatibility. That pointer may be empty when all ordinary documents have been deleted.
• Paper keeps render assets out of the file browser. Quarto support/cache trees (*_files, *_cache, _freeze, _site, _book, site_libs) are filtered from discovery; a *_files or *_cache suffix needs a matching source or recognizable generated contents. An unused legacy sections/ folder is hidden until used or explicitly created in Paper. New folders contain a hidden .flux-folder marker so intentional empty folders, including those with generated-looking names, remain visible. Existing ordinary folders need no marker. These visibility rules never remove files from disk.
• plots/ is a drop zone with no imposed structure — organize it however your analysis does. Flux only reads it, copying what you compose into fig/assets/. See semantic plots for the three-file contract.
  • Two subfolders are written for you and are yours to keep or delete: plots/pasted/ holds the original of every image you paste from the clipboard, and plots/paper_snips/ holds every region you snip out of a PDF. The pixels you contribute live somewhere you own, not only inside the app’s fig/assets/ copy.
  • Three names starting with _ are reserved: plots/_dissections/ holds each plot’s companion material (press D in Figure to view it); plots/_lighttable/ holds Lighttable collections, the sweeps and per-cell batches you triage before choosing a panel; and plots/_videos/ holds video clips for slides.
  • Reserved folders stay out of an ordinary plot-importer search, however many thousands of images they hold. Type _ in the importer to list them and Enter to search inside one.
• 3D fluxplots keep the source GLB and its .fluxplot.json beside each other in plots/. Import copies the accepted bundle into fig/assets/. Camera settings, shape weights and part restyles live in the figure composition. fig/renders/model3d/ contains rebuildable PNG posters keyed to the accepted mesh and view; deleting that cache does not delete the mesh or its edits. Exported SVG/PDF artwork combines those mesh pixels with vector labels.
• .meta/ holds the operational machinery: journal.ndjson (every write: who/what/when), feedback.ndjson (annotations and inbox status), advisory locks/, JSON schema/ for every file type, and the live-bridge descriptor while the app is open. Connected MCP sessions publish heartbeats in live/sessions/; these are disposable. Migration archives are stored in archive/2026-09-agent-workflow/.
• Context/ is explained in full in Context and memory.

For the ideas behind the layout — source versus derived files, crash safety, live reload — see Projects and files.