Skip to main content

Project Setup And Storage

CiteTraverse projects are local-first review workspaces. A project can live as an ordinary desktop folder, a browser-backed virtual project that can be exported as a zip archive, or a VS Code workspace folder that contains the same project layout.

CiteTraverse project file layout

A project keeps user-editable BibTeX boxes at the root and machine-managed state under .citetraverse/.

When To Use This Feature​

Use project setup and storage features when you want a review that can survive long sessions, be inspected outside the app, and move between CiteTraverse hosts without changing the review model.

Desktop projects are best for durable local folders and PDFs. Browser projects are useful for demos, lightweight exploration, and zero-install collaboration. VS Code projects are useful when the review folder already belongs beside source material or analysis scripts.

Core Files​

Each project has a boxes/ directory for user-visible paper state:

  • included.bib stores seed papers and accepted papers.
  • inbox.bib stores active discoveries ready for screening.
  • deferred.bib stores papers that need later review, including unresolved merge candidates.
  • excluded.bib stores rejected papers.
  • queued.bib mirrors queued discoveries for review, but the delivery queue is authoritative.
  • {custom}.bib files are derived exports for collections.

Machine-managed state lives under .citetraverse/, including the project manifest, paper index, citation edges, queued discoveries, provider cache, metrics, events, and snapshots.

Workflow​

  1. Choose a host: desktop for local folders and PDFs, browser for zero-install projects, or VS Code for a workspace-integrated review.
  2. Create or open a project.
  3. Import seed BibTeX into Included.
  4. Continue screening and expansion; CiteTraverse persists box files and internal state after each change.
  5. Export or back up the project folder when you need to move it.

Important Rules​

A paper belongs to exactly one built-in box at a time. Box membership is the authoritative screening state; CiteTraverse does not rely on a separate authoritative ct_status field.

User-authored bibliographic fields, notes, tags, and collections stay in BibTeX entries. System state that does not belong in BibTeX stays under .citetraverse/.