# Learn with the practice project

The practice project is a small, editable research paper that connects several VersoFold tools. You can change every part of it. All six measurements, method names, and reviewer comments are invented for learning. They are not evidence for a real scientific claim. No AI account, remote connection, or downloaded dataset is needed for the exercises.

## Create your own copy

On **Home**, choose **Try a practice project**. Choose a destination and a new folder name, then choose **Create workspace**. You can also select **Practice project** under **New workspace → Start with**. Creation never replaces an existing folder: choose a different name if that folder already exists.

The walkthrough opens over your new workspace. Close it whenever you want to try a step; reopen it through **Documentation**, search for “practice”, or open `START-HERE.md` in the project's file list. **Help → Explore workflows** connects common goals to the relevant tools and guides. You can use just one of the exercises at a time.

Your copy contains:

| Item | What to try |
| --- | --- |
| `main.tex` | Edit the author, prose, equation, and captions. |
| `data/results.csv` | Six synthetic runs for two fictional methods. |
| Figures → Figure Studio | The saved “Scores by run (synthetic)” chart and its linked dataset. |
| Write → Table editor | “Practice scores”, an editable sheet with mean formulas. |
| Research → Linked results | “Guided mean score (synthetic)”, connected to a number and a sentence. |
| Write → Manuscript board | Cards linked to the existing sections; Discussion has a practice checklist. |
| `references.bib` | A BibTeX entry describing the local toy dataset, not a published paper. |
| `notes/reviewer-feedback.md` | Fictional reviewer requests to use in Rebuttal. |

## First success: edit and compile

1. Open `main.tex` under **Files** and find `\author{Your name}`. Replace the name. You can edit supported prose in **Visual** too.
2. Choose **Recompile**. The example uses pdfLaTeX and standard packages included with the desktop app. If using a development installation, a working TeX installation is needed.
3. Read the PDF. Find the equation, the two-series plot, the table, and the bibliography.
4. Use **Review → Versions** to save a named version such as “Before practice edits”.

Expected result: your name appears in the compiled PDF and the initial Guided mean is **82.0%**. Saving source and compiling a PDF are separate actions. See [Compilation & PDF](builds-pdf.md) if the build reports a problem.

## Trace and update a number

1. Open **Research → Linked results** and select **Guided mean score (synthetic)**. Inspect its definition: file `data/results.csv`, column `score`, filter `method = Guided`, operation **mean**, one decimal place, percentage display. Three rows match.
2. Close the tool. Open `data/results.csv` in Files. In the last row, change the score in `Guided,3,0.84,9.5` from `0.84` to `0.90`, and save.
3. Reopen **Linked results** and **Refresh**. The mean of 0.80, 0.82, and 0.90 is 0.84, so the new displayed value is **84.0%**.
4. Review the proposed numeric replacement and the connected comparison sentence. Decide whether the sentence is still justified within this synthetic example. Select the intended numeric update and acknowledge the statement only after reading it.
5. Apply the reviewed update, then recompile. The app preserves a checkpoint before changing the manuscript.

Expected result: the Results section displays **84.0%** after you accept the update. The sentence is reviewed by you; it is not automatically rewritten. The CSV-linked figure follows the changed input when regenerated during the build. The independent spreadsheet table still has its original values until you edit and publish it.

To reverse this exercise, change the CSV score back to `0.84`, refresh Linked results, review the return to 82.0%, and recompile. See [Linked results](linked-results.md) for ambiguous anchors, stale data, and recovery.

## Refine the figure

Open **Figures → Figure Studio** and select **Scores by run (synthetic)**. Inspect the source rows, then change a line color, marker, or axis label in the design controls. Preview the result and publish the figure. It is already included in the manuscript, so you do not need to insert another copy. Recompile to inspect the PDF at its actual printed size.

The chart uses the CSV directly and shows individual runs. If you edit data inside Figure Studio, it may create an editable dataset copy; use the CSV file for the linked-result exercise above. Read [Figure Studio](figures.md) for dataset preparation, uncertainty, themes, and publication.

## Edit and republish the table

1. Open **Write → Table editor** and select **Practice scores**.
2. Inspect cell E3: its formula is `=AVERAGE(B3:D3)`. The data cells use percentage formatting, while their underlying values are fractions.
3. If you changed the CSV in the number exercise, change D3 from `0.84` to `0.90` here too. This sheet is an independent copy, so CSV changes do not rewrite its cells. E3 should display 84.0%.
4. Choose **Save table**, inspect the publication preview, then **Publish to paper**. The existing manuscript already includes the generated table file; do not insert it a second time.
5. Recompile and compare the table with the figure and Results paragraph.

Expected result: publishing changes the table used by the paper; merely saving the sheet does not replace its previous published output. See [the table guide](tables.md#save-publish-and-insert-are-separate).

## Plan and review a revision

Open **Write → Manuscript board**. The cards are connected to the actual document sections. Select **Discussion**, inspect its word target and checklist, then add a sentence to that section explaining a limitation of the toy data. Return to the board, review the changed source, check the relevant task, and move the card to **In review**. A card's stage is your planning decision, not a guarantee of scientific quality.

For response practice, open `notes/reviewer-feedback.md`. Copy its fictional review, choose **Import reviews** in the Reviews tab (or move the paper to the Rebuttal phase), and paste it. In the Response view, decide how to address one comment, make the change in the paper, and write a short answer under the comment explaining what changed. See [Write the response](deadlines-rebuttal.md#write-the-response) and [Copy for OpenReview](deadlines-rebuttal.md#copy-for-openreview-or-export-the-letter).

## Choose your next workflow

- **Reading:** open one of your own PDFs from Home, then try notes and comparison in the [reading desk](reading.md). The practice bibliography has no external paper attached, so there are no source passages to check.
- **Sources:** add a real paper with its PDF to your library, cite it, then [check the sources](evidence.md) of the sentence that cites it. Synthetic practice results cannot support an external claim.
- **Page layout:** after a successful build, open [Page layout](page-layout.md) and inspect where the existing figure and table land.
- **Submission:** use [Submission rehearsal](submission.md) with requirements you have checked. No real venue or deadline has been preselected for this example.
- **Sharing:** create a [web edition](web-edition.md) draft or try a local export. Creating this practice project publishes nothing online.
- **Agent help:** if you connect a model, try “Read the practice-project documentation and explain how this paper's number is connected to its data.” Reading the handbook remains on demand; the local exercises do not start an agent conversation.

## Start fresh or keep the project

The example becomes an ordinary folder in your chosen location. Keep it, rename its library entry, or make an independent copy from Home. To repeat the initial exercise, create another Practice project in a different new folder. Removing a workspace from the library leaves its files on disk. You can always start a separate blank or article workspace for your real research.


---

# Your first paper

VersoFold is a writing and research workspace built around ordinary files. Your LaTeX sources, bibliography, figures and compiled PDF live in a folder you choose. You can use the same folder with a text editor, a terminal or an agent. VersoFold watches for saved changes and brings them into the app.

You do not need an AI account to write, compile, read PDFs, organize references or use the local research tools. Connect a model when you want assistant responses.

## Choose your starting point

- **Learn by doing:** choose **Try a practice project** on Home. It creates your own editable example with data, a figure, a table, linked results, and a writing board. Follow the [practice walkthrough](practice-project.md).
- **A new manuscript:** on Home, choose **New workspace**, give it a name and destination, and select Blank document, Research article, Research notes or Report.
- **An existing paper:** choose **Add a folder** and select the folder containing its `.tex` files and supporting assets. Add the whole project, not just an isolated chapter.
- **A paper to read:** choose **Open PDF** or drop a PDF on Home. VersoFold keeps a reading copy and leaves the original in place. Continue with the [reading guide](reading.md).
- **A long-term literature collection:** open **Reference library** from Home. It is shared across workspaces.

A saved workspace name is a library label. Changing it does not rename your source file or folder. Removing an entry from Home removes the library entry, not the files.

**Explore workflows**, available on Home and in Help, organizes the toolset around five goals: writing, reading and checking claims, connecting data, submitting and revising, and working with an agent. Each path explains the next steps and links to the relevant guides. In a manuscript, it can open the tools directly. Help also offers a task-specific starting point for the tool you are using.

## Write and compile your first document

1. Open the workspace and select its main `.tex` file from **Files**.
2. Use **LaTeX** to edit source or **Visual** to edit supported prose directly. **Split** lets you keep source and PDF together.
3. Make a small change, such as updating the title or adding a paragraph. Source editing autosaves; **⌘S** saves immediately.
4. Open the arrow beside **Recompile**. Confirm the document root and engine. For the standard article below, pdfLaTeX is suitable.
5. Choose **Recompile** or press **⌘Enter**. Look for a successful build and inspect its PDF. If the build fails, the build log opens with the errors; **⌘J** opens or closes it any time, and the footer's **Build log** button stays red until the errors are fixed.
6. Save a named milestone with **Save version** or **Review → Versions** before making a larger change.

```latex
\documentclass{article}
\usepackage{amsmath}
\usepackage{graphicx}
\usepackage{hyperref}

\title{My first paper}
\author{Your name}
\date{\today}

\begin{document}
\maketitle
\begin{abstract}
A short statement of the problem, approach, and result.
\end{abstract}
\section{Introduction}
Here is the first paragraph of the paper.

Here is another paragraph, separated by a blank line.
\end{document}
```

> **Remember:** saving changes the source on disk. Compiling produces a new PDF. A saved source can be newer than the PDF you are looking at.

To see where the paragraph you are writing landed on the page, press **⌘⇧J** (**Show in PDF**). Double-click a word in the PDF to jump back to its source.

## Add a reference and a figure

Open **Bibliography** to inspect the paper's entries or **Reference library** to collect a paper by DOI, arXiv link or BibTeX. In LaTeX, begin typing `\cite{` and search by title, author or citation key. Selecting a library entry adds its bibliography record to the workspace. Your document still needs a bibliography command or template configuration; see [references and citations](references.md).

For an existing image, use **Snippets & wrappers** and choose a figure template. Pick the image, check the caption and label, and insert it. For a plot from data, open **Figures → Figure Studio** and follow [Figure Studio](figures.md).

## Make a comfortable workspace

Choose the two views in **Split**, then use **Swap panes** or change the orientation. Drag the divider to give the writing pane more room. **Focus** folds away side panels temporarily. **Workspace memory** saves arrangements for writing and review.

The first time you open a paper, a one-minute tour points at these controls; replay it from **Help → Take the workspace tour**. Use **Write**, **Research**, **Review**, and **Publish** to browse tools, or **⌘K** to find a feature by name. **Help → Documentation & guides** opens this handbook at the relevant editor or reader. The handbook is searchable, works from bundled content, and leaves the current workspace open underneath.

## If something goes wrong

Open the build log when compilation fails and start with the first error. Check that the selected root is a complete document, the expected engine is available, and all referenced files are inside the project. Do not repeatedly rewrite unrelated text to fix a build. The [compilation guide](builds-pdf.md) and [troubleshooting guide](troubleshooting.md) explain the common cases.

Next: [Home & workspaces](workspaces.md), [LaTeX from the beginning](latex-basics.md).


---

# Home & workspaces

Home is your saved-workspace library. Each workspace points to a real folder. Several documents, bibliography databases, figures and datasets can live in that folder, while VersoFold keeps project settings and research records alongside them.

## Create, add and reopen

Choose **New workspace** to create a folder from a template. Choose its parent location and a new folder name. **Add a folder** registers an existing folder. On desktop, the native folder picker and folder dropping are available; browser mode can use the folder browser provided by the local server.

Open a workspace card or list row to resume writing. Click the VersoFold mark in the writing workspace to return Home. **Back to editor** returns to the currently open project. Opening a PDF creates a reading workspace labelled as a reading copy.

Use the card menu to rename the library entry, edit tags, make a copy, download the latest compiled PDF, or remove the entry. A download is the latest available PDF; compile first when you need recent edits included.

## Find and organize projects

Search by workspace name, choose tag filters and sort by last opened, saved date or name. Grid and compact-list views use consistent tag colors. Your choice of view is remembered.

Tags describe projects; they do not move their folders. Good examples include a conference name, a collaboration, a research topic or a status such as “revision”. Keep folder names useful outside the app as well.

**Make a copy** creates an independent folder containing sources, assets, notes and available compiled PDFs. Existing destination folders are not overwritten. Copies containing symbolic links are rejected so that the copy does not silently depend on files elsewhere.

## Understand where things live

| Information | Location and meaning |
| --- | --- |
| Manuscript and assets | Ordinary files in your chosen project folder. |
| Workspace names and tags | `~/.versofold/projects.json`, personal to this installation. |
| Project settings | `.versofold.json` in the project, including `collaboration.liveEditing` (see [live editing](sharing-export.md#turn-live-editing-off)). |
| Comments and tasks | `.versofold.comments.json`, `.versofold.comments.resolved.json` and `.versofold.tasks.json`. |
| Source history | `.versofold/history.git`, separate from your own Git repository. |
| Shared reference collection | `~/.versofold/references.json` and attached files in `~/.versofold/reference-files`. |
| Figure, table and results drafts | `.versofold.figures.json`, `.versofold.tables.json` and `.versofold.results.json`. |
| Device arrangements | Browser/device-local workspace memory. |
| Your name and cursor colour in shared workspaces | Browser/device-local, set from your chip in the workspace header. |

Project dotfiles are hidden from ordinary file browsing. Several older `versofold.*` metadata names are still readable; hidden files take precedence. Use the app's controls to maintain structured project records instead of editing their JSON during a running operation.

> **Backup:** copy the complete project folder, including hidden `.versofold` files, when preserving history and research records. A manuscript-only export is not a backup of your personal reference library or account settings.

## Preferences and appearance

Home and the editor provide Settings and a light/dark theme control. Home also has a motion toggle; reduced-motion preferences suppress decorative animation. Settings contains appearance and agent connection options. Changes to model settings do not connect an account automatically.

**Workspace memory** stores tabs, source cursors, PDF positions, panel widths, editor views and arrangements. Writing, Review and Focus presets are provided. You can save up to 12 named arrangements, disable automatic restoration, or clear saved positions. Layout memory is device-local. The same window also lists the notes the agent reads about the paper; those are saved with the project, not the device. See [workspace memory & procedures](memory-procedures.md).

## Several people, one workspace

A workspace can have several people in it at once: your own second window, collaborators on a share link, or members of a hosted workspace. Everyone with a file open edits the same document live, with each person's cursor in their colour; the header shows who is here, and the file tree marks files others have open. The folder on disk stays the one copy: what everyone types is written to the files a moment later, and "All changes saved" means it is there. Agents and other programs keep writing to the files as usual, and their changes reach every open editor. See [sharing and export](sharing-export.md#edit-together-live) for what collaborators can do at each level.

## Multiple documents and missing folders

A folder can contain a main paper, supplement and response letter. The compilation root determines which complete document builds. Opening a chapter in the editor does not make it the root. Select the intended document beside **Recompile**, and use **Compile all documents** when the workspace has multiple detected targets.

If a saved workspace becomes unavailable after moving its folder or disconnecting a drive, check its displayed path. Re-add the correct folder rather than creating an unrelated empty document with the same name. Keep relative paths within manuscripts so a copied project remains portable.

Related: [navigation](navigation.md), [versions and recovery](versions.md), [sharing and export](sharing-export.md).


---

# Find your way around

The writing workspace keeps the document in the center, navigation on the left (Files, Outline and Search, then Bibliography, Figures and Snippets), the side panel on its right and the agent in a column of its own at the far right. The paper's [phase](paper-phases.md) sits under its title. The main toolbar offers Write, Research, Review, and Publish menus, plus search, Workspace settings, Help, Share, and Recompile. The next row controls document views, the side panel's tabs, and **Agent**.

## Choose a view

| View | Best use |
| --- | --- |
| LaTeX | Exact source, structural changes, custom commands and advanced formatting. |
| Visual | Editing supported paragraphs, headings, captions and equations on a readable page. |
| PDF | Inspecting the compiled output and exact pagination. |
| Response | Answering the reviewers, in the Rebuttal and Camera-ready phases (see [Rebuttals & responses](deadlines-rebuttal.md)). |
| Split | Keeping any two of these visible together, for example Response beside LaTeX. |

LaTeX and Visual edit the same active source file. Switching views preserves tabs and source undo history. PDF shows the result of the last compilation; Visual is an approximation of the template rather than TeX's final layout.

When the paper has a preprint or other editions, the switcher next to the paper's phase (**Paper ▾**) chooses which edition the PDF and the LaTeX show, compares two editions side by side and colours their differences. See [switching the view](editions.md#switch-the-view).

To find the cursor's place in the PDF, press **⌘⇧J** or choose **Show in PDF**; the PDF opens beside the text if it is not on screen. Double-click the PDF to go back to the source. See [moving between the source and the PDF](builds-pdf.md#move-between-the-source-and-the-pdf).

## Arrange split panes

Select **Split** to open its layout menu. Choose each pane separately: source beside Visual, Visual beside PDF, Response beside source, and so on; the view already in the other pane is greyed out, and **Swap the panes** reverses them. Choose **Side by side** or **Stacked**, then drag the divider to resize.

While two views are shown, the view buttons work on one pane at a time. A view that is not on screen takes the place of the pane showing the same kind of view (LaTeX, Visual and Response replace one another; PDF replaces the pane you are not working in), and the other pane stays as it is. A view already on screen, marked with a dot, is shown alone; **Split** brings the pair back.

When one pane is the PDF, two small arrows sit on the divider: → shows the cursor position in the PDF, ← shows the part of the PDF on screen in the source. Divider controls support the keyboard: focus a divider and use arrow keys; Home restores equal pane sizes where offered. Narrow windows may temporarily stack panes or fold the sidebar so the document stays readable. These adaptations do not overwrite your saved orientation or widths.

Use **Focus** when you want the document to occupy more of the window. Restore panels when you need Files, comments or the agent. Saved arrangements in **Workspace memory** let you switch between writing, reviewing and reading without rebuilding your layout each time.

## The side panel and the agent

The side panel's tabs follow the paper's phase, at most three at a time (Comments, Changes, References, Checklist, Reviews or Plan); **⋯** lists the others. Click the active tab to close the panel. **Agent** (**⌘ShiftA**) opens the agent in its own column. When the window is too narrow for the document, the side panel and the agent, the one you are not using folds into a strip of icons; click an icon to bring it back.

Each workspace reopens the way you left it: its open tabs, views, pane sizes, right-hand panel and your place in the PDF. The build log is the exception and always starts closed.

## Windows and layouts

With more than one screen, give a view a window of its own: the PDF on the external display, say, with the LaTeX source and the agent on the laptop. Click the pop-out button (a small window with an arrow) at the right of the PDF toolbar, of the editor's tab bar, of the Response view's toolbar, or of the tabs above Agent, Comments, Review and References. The **Windows** menu (the overlapping windows beside the Workspace gear) and **⌘K** offer the same, for example **Open the PDF in its own window**. The new window shows only that view of the same paper: edits, builds, comments and collaborators reach it just as they reach the main window.

You can also drag a tab out of the window: drag **LaTeX**, **Visual**, **PDF** or **Response** above the editor, or **Agent**, **Comments**, **Review** or **References**, and release it outside the window to open that view where you let go; if the browser does not notice the pointer leaving, release it on the **Drop here to open in its own window** band that appears at the bottom. Escape cancels the drag. **⌥⌘O** (**Open this view in its own window**) does the same from the keyboard for the view you are working in: the editor or PDF you last clicked, a focused tab, or else the open tool. In a view's own window, **⌥⌘O** returns it, as does dragging the view's name in its header onto the main window.

While a view is out, the main window shows what is left. With the PDF out, a split falls back to the source or Visual editor; with the Response out, **Draft with agent** goes to the main window's agent and the sidebar's Outline scrolls the Response window; a tool in its own window leaves a card with **Show it** and **Bring it back**. Your chosen view is not changed and returns with the window. Jumps still cross windows: double-click the PDF, or use **Show in source** at the top of its window, to reach the source wherever the editor is; **Show in PDF** (**⌘⇧J**) scrolls the PDF in its own window; a file, comment or tracked change opened from a separate Agent, Comments or Review window opens in the window with the editor.

To bring a view back, click **Return to main window** at the top of its window, **Bring it back** in the main window, or just close the window. **Put everything back in one window** in the Windows menu brings them all back.

### Save and switch layouts

**Windows → Save current layout…** names the arrangement on screen: which views have their own windows, where each window sits and on which screen, and how the main window is set out (views, split, tool panel and sidebar). Choose a saved layout in the Windows menu, or type its name after **⌘K**, to switch to it; rename or delete layouts in the same menu. Switching saves your typing first, then opens, moves and closes windows. Positions are kept as a share of each screen, so a layout survives a change of resolution, and a window whose screen is missing moves to one that is there.

### Remembered for each set of screens

VersoFold also remembers the arrangement you last used with each set of connected screens. Layouts belong to this computer rather than to a paper, so they follow you from one workspace to the next. Plug in the external display and the PDF goes back to it; unplug it and everything returns to the laptop the way you last had it there. Turn this off with **Remember the layout for each set of screens** in the Windows menu.

In a browser, VersoFold asks to see all your screens (the browser calls it window management) only when you save or switch to a layout that spans several; without it, new windows open on the current screen. Browsers open windows only after a click, so a remembered layout offers **Open windows** when you return. If the browser still blocks them, allow pop-ups for the site from the icon at the end of the address bar and try again. In the desktop app, windows open and move without asking.

## Find files and tools

The left rail contains **Files**, **Outline** and **Search**. When the sidebar is narrow, its tabs keep only their icons, with the open tab's name beside its icon; point at a tab to see its name. The outline shows numbered headings and nesting; collapse branches or jump to a source line. **Bibliography** and **Figures** provide project resources.

Four short menus organize the workspace by the kind of work you are doing:

| Menu | What you will find |
| --- | --- |
| **Write** | Figures and Figure Studio, manuscript board, table editor, and page layout. |
| **Research** | Bibliography, linked results, and remote data. |
| **Review** | Versions, track changes, compare with the approved version, deadlines and reviews, rebuttal, and annotated PDF import. |
| **Publish** | Submission rehearsal, arXiv packaging, web edition, Overleaf, Word, and Git. |

The **Workspace** gear menu contains the file finder, **External agents**, saved arrangements and the agent's notes about the paper (**Workspace memory**), appearance, and Settings. External agents also has its own page under **Settings → AI & agent**. The **Windows** menu beside the gear opens views in their own windows and switches between saved layouts; see Windows and layouts above. **Help** contains contextual guides, Explore workflows, the workspace tour, Report a bug and Request a feature. Shared workspaces show only the tools available to the current reader.

Each menu item includes a short explanation. Click outside a menu or press Escape to close it. On narrow windows, the four menu names remain visible in their own row; menus scroll if the window is too short. Recently used tools and tools containing project data can appear as sidebar shortcuts. Removing a shortcut hides the shortcut, not the saved data. **More tools** and the command palette still reach it.

Click the **Search tools and actions** magnifying glass, or press **⌘K**, and type a tool, file, view or action. Select an item and press Return. **⌘P** is the direct file finder. Documentation is also a command-palette entry.

## Comments, references and the assistant

Open **Comments** to inspect threads and reference cards; the list shows the open file's threads, and says when others are open in other files (**this file** switches to **all files**). Source/PDF selections can create anchored comments. References can be narrowed to the visible PDF page where supported, and a cited reference's card offers **Check the sources** for the sentence that cites it. **Agent** opens conversations and research tools. Those tools have their own state and permissions; opening a panel does not run a model.

The right-hand panel stays on the tool you chose. It changes only when you ask for something another tool shows: writing or opening a comment, a PDF comment pin, a citation clicked in the PDF, a source check pinned as a comment, or a task handed to the agent. **Check the sources** itself opens a small card beside the sentence and leaves the panel alone. Clicking inside commented or cited text in the source just places the cursor.

The toolbar's **Help** menu opens the handbook and, in the writing workspace, the introductory tour. The tour starts by itself only the first time VersoFold opens a paper; replay it any time from **Help → Take the workspace tour** or **⌘K**. Source, Visual and PDF views open their own relevant guide. The reading desk, PDF reader, Figure Studio, table editor and web edition also expose documentation from their Help menus.

## Read the status indicators

Watch connection, save and build status while working. A changed source is not proof of a successful build. A current PDF is not proof that every scientific claim or reference is correct. Word/page counters combine source estimates with measurements from the last compiled PDF.

The deadline chip shows the nearest active due date; click it to open the tracker dock, which stays out of the way until you ask for it. Tool badges provide compact reminders; open the tool for the full record and its evidence.

## Search the handbook effectively

Documentation search covers guide titles, keywords, headings and body text, including code examples. Type a feature or a specific symptom such as “missing package”, “formula”, “frozen”, or “mean seeds”. Every query word must match somewhere in a guide's metadata or the section; fewer words can find more results.

Choose a topic filter to narrow the results. Select a result to jump directly to its section. The contents rail navigates within a guide. **Copy link** copies a local-server guide link; **Markdown** downloads a chapter, and the navigation rail offers the complete handbook.

Related: [keyboard shortcuts](shortcuts.md), [source editing](source-editor.md), [reading](reading.md).


---

# Paper phases

A paper goes through phases: you draft it, coauthors read it, you submit it, reviewers judge it, you answer them, and the final version goes out. VersoFold keeps the paper's phase under its title, and arranges the workspace around it: the tools in view, the tabs of the side panel, the checks that matter now. Nothing is locked. Every tool stays in the menus and in **⌘K**, and you can choose any phase at any time.

## Choose the phase

Click the phase under the paper's title (it starts as **Drafting**). The menu lists the seven phases with what each one brings, and **Move on to …** takes the paper to the next one. Coauthors see the same phase; only the workspace owner changes it. Home shows each paper's phase on its card.

| Phase | What it is for | Side panel |
| --- | --- | --- |
| Drafting | Shape the argument and get the words down. | Comments · References · Plan |
| Internal review | Coauthors and advisors read and suggest. | Comments · Changes · References |
| Submission | Choose the venue and pass its checklist. | Checklist · Comments · References |
| Under review | The paper is with the reviewers. | Reviews · Comments |
| Rebuttal or revision | Answer the reviewers and revise the paper. | Changes · Comments · References |
| Camera-ready | The final version for the proceedings. | Checklist · Changes · References |
| Published | The paper is out. | Comments · References |

**⋯** at the end of the side panel's tabs lists the other panels. One opened from there stays as an extra tab until you pick another.

## What each phase brings

- **Drafting.** The **Plan** tab shows each section's stage and word target from the manuscript board, your to-dos and the next deadlines. The agent suggests structural questions.
- **Internal review.** Your edits are tracked by default (switch **Track changes** off to edit plainly). Share a suggest-only link from **Share** so coauthors propose changes without overwriting yours.
- **Submission.** The **Checklist** tab starts with **Where are you submitting?**: choose a saved venue, or find one with the agent. Once a venue is chosen, **Run the checklist** compiles the paper and checks it against the venue: page limits, abstract length, unresolved citations, placeholders and the items you judge yourself. **Copy for the submission form** gives the title, abstract and keywords as plain text, with their lengths. **Editions** shows the preprint (create it, or view it) and where the appendix goes: in the paper, or **As supplementary material**, its own PDF. When you have submitted, **Mark as submitted**.
- **Under review.** A note reminds you that edits now count as changes since submission. The **Reviews** tab waits for the reviews: **Import reviews** takes the whole OpenReview page or pasted review text.
- **Rebuttal or revision.** The **Response** view opens beside the LaTeX: each reviewer comment with your answer under it, written together with your coauthors. Changes since submission show in colour. See [Rebuttals & responses](deadlines-rebuttal.md). In the phase menu, choose **Conference rebuttal** (one reply per reviewer, with a character limit, for OpenReview) or **Journal revision** (a response letter and a marked manuscript), the reply limit and the discussion round.
- **Camera-ready.** The **Checklist** tab checks what usually goes wrong after acceptance: the authors shown instead of an anonymous block, the venue style switched to its final version, acknowledgements, placeholders, the page limit with the extra camera-ready allowance, every font embedded with no Type 3 fonts, and each change promised in the rebuttal linked to the manuscript. When the paper has editions, **Name the authors in every edition** checks that the camera-ready version names them everywhere, with a button that does it; and **Update the preprint** lists what changed since the version on arXiv and opens the arXiv package for the next one. **Compile and check** runs them again.
- **Published.** The phase menu copies a BibTeX entry for your own paper and opens the arXiv package and the web edition.

From Submission on, **Preprint & editions…** in the phase menu opens the paper's editions: the named preprint, the supplementary material and a journal version, all built from the same source. See [Preprint & editions](editions.md).

## Phases and editions

The phase and the edition are two different choices, side by side under the paper's title.

| | Phase | Edition |
| --- | --- | --- |
| What it says | Where the paper is in its life | Which form of the paper you are looking at |
| How many | One at a time | Several at once: the paper, the preprint, the supplementary material |
| Examples | Drafting, Submission, Rebuttal, Camera-ready | Paper (or Submission), Preprint, Supplementary material |
| Where you choose it | The chip under the title | The button right after it |
| What it changes | The tools in view, the side panel's tabs, the checks, a few defaults | The PDF and the LaTeX on screen, and what gets built |
| Who sees the choice | Everyone in the workspace | Only you, in that window |
| Does it touch the LaTeX? | No | Text marked for some editions only, when you create one or mark text |

They work together. In Submission, the paper is anonymous and the [preprint](preprint.md) names you, both from the same source. Through Under review and Rebuttal, your revisions reach both, while changes since submission are measured on the paper. In Camera-ready, one click names the authors in every edition, and the checklist reminds you to update the preprint. Choosing a phase never creates an edition, and creating an edition never changes the phase.

## The submitted version

**Mark as submitted** (in the Checklist tab or the phase menu) saves the current paper as a named version, "Submitted to *venue*". Changes in Rebuttal and Camera-ready are measured against it, in the editor, on the PDF and in the marked PDF. To use another saved version instead, choose it under **Changes are measured from** in the phase menu.

## The agent and the side panel

The agent has its own column, opened with **Agent** at the right of the toolbar (**⌘ShiftA**). The side panel and the agent each open on their own. When the window is too narrow for both beside the document, the one you are not using folds into a thin strip of icons; click an icon to bring it back. **Snippets** sit in the left sidebar with Bibliography and Figures and open beside it, so you can drag them into the text.


---

# The LaTeX editor

LaTeX mode exposes the actual source files in your workspace. It is the place for structural changes, custom commands, bibliography source and precise edits that Visual does not support.

## Open and edit files

Use Files or **⌘P** to open a source. Tabs preserve each file's editor state. Source changes autosave, and **⌘S** saves immediately. Normal undo and redo operate on editor changes; source history provides longer-term recovery.

Use **Outline** to jump through sections and subsections. The currently edited file can be an included chapter; the compilation root remains the complete document selected beside Recompile. For example, edit `sections/method.tex` while compiling `main.tex`.

Use the file tree's controls to create or manage project files. Keep figures and bibliography paths relative to the document's project structure. Hidden metadata and dot-directories are omitted from ordinary browsing, even when build files are shown.

## Find and replace text

**⌘F** searches the active file. **⌘ShiftF** opens project search, with matches grouped by file and case-sensitive or regular-expression options. Clicking a result opens its exact source location.

Project-wide replacement is a previewed operation:

1. Search for the text and choose replacement text.
2. Inspect the preview and affected files.
3. Untick files that should remain unchanged.
4. Apply the replacement. VersoFold saves pending editor changes and creates a source checkpoint before writing.
5. Recompile and check the result when replacements affect LaTeX commands, labels or citations.

A literal search is easier to reason about for backslashes and braces. Use regular expressions when you specifically need pattern matching, and inspect matches before applying changes across the project.

## Citations and reusable source

Begin a citation command such as `\cite{`, `\citep{`, `\citet{` or `\parencite{`. Suggestions search titles, authors, years and venues as well as keys. The workspace's own bibliography comes first; choosing a shared-library paper also adds its full BibTeX entry.

You can narrow library suggestions with filters such as `is:checked`, `in:Related-work`, `tag:methods` or `sort:year`. The pinned actions open the full reference library or add a paper by link/BibTeX. See [references](references.md) for command/package compatibility.

Use **Snippets & wrappers** or **⌘ShiftI** for reusable blocks. Selecting text before applying a wrapper preserves the selection inside the template. A template insertion is an ordinary editor change and can be undone in one step.

## Work with another editor or agent

VersoFold watches the workspace on disk. When another program, a script or an agent changes a file you have open, the change streams into the editor within a moment and merges with what you are typing, like a collaborator's edit: nothing you typed is lost, and **⌘Z** still undoes only your own typing. A banner above the editor says how many lines were written outside it, with **Review** to see them and **Clear** to dismiss it.

Operations that need a stable source (table publishing, linked-result updates, layout adjustments) check the file's hash and refuse, with a message, when it changed since they read it; run them again.

**Track changes** (the switch in the editor header, **⌘ShiftE**) records your edits for review; everyone's pending changes show in their colours, insertions underlined and deletions struck through where they were. Hover one to accept or reject it, and move between them with **⌘Option]** and **⌘Option[**. Agents' edits are tracked too. The **Review** tab lists every pending change, and **Review → Compare with approved version** compares the whole draft with your last sign-off. See [tracked changes](comments-review.md#track-changes).

## Check prose and structure

Manuscript checks can surface misspellings, repeated words, unresolved labels and citation keys, missing graphics, unused bibliography entries and remaining TODOs. Source-aware checks skip math and literal environments where appropriate, but custom macros can limit what static inspection understands.

Review each finding in context. Add legitimate terminology to the project dictionary rather than replacing it with an unrelated word. A lint result is a writing aid; compile to verify LaTeX behavior and inspect the PDF for layout.

## Efficient habits

Keep one section per file when it helps navigation, use consistent labels such as `sec:method`, `fig:overview` and `tab:results`, and introduce macros for repeated notation. Write content before fine-tuning layout. Save a named version before a large restructuring or an agent-assisted revision.

Related: [Visual editor](visual-editor.md), [compilation](builds-pdf.md), [practical LaTeX](latex-advanced.md).


---

# The Visual editor

Visual mode turns supported LaTeX into an editable reading surface. It retains source ranges and writes changes back to the same `.tex` file used by the LaTeX editor. It is useful for drafting prose while keeping equations, figures and headings in context.

## Edit on the page

1. Open a `.tex` source and select **Visual**.
2. Click a supported paragraph, heading, list item or caption.
3. Edit the text. Inline emphasis is retained where supported.
4. Press Enter in ordinary prose to begin a new paragraph.
5. Use source undo/redo when needed, and compile to check the actual output.

The unchanged parts of the source are preserved. Visual editing is not an HTML-to-LaTeX conversion of the entire document. It shares autosave, conflict checks and undo history with LaTeX mode.

## Equations, citations and numbers

Click an equation to open its small LaTeX editor. The local math preview provides immediate feedback while you type, using the macros your preamble defines (`\newcommand`, `\DeclareMathOperator`, and files such as `math_commands.tex`). **Apply** writes the equation back with its original delimiters. If a math command is unsupported by the preview, inspect the source and compiled PDF; preview support and TeX support are different.

Numbers read as the PDF prints them. Sections (lettered after `\appendix`), figures, tables, algorithms, theorems, footnotes and equation rows are counted in order, and wherever the last build resolved a `\label`, Visual uses the number it printed. `\ref`, `\eqref`, `\cref` and `\autoref` show those numbers ("Fig. 2", "Section 3"), and `??` before a first build.

Click a citation or reference to edit its command. Citations show the build's own labels: `[3]` in numeric styles, "Smith et al. (2020)" for natbib's `\citet` and "(Smith et al., 2020)" for `\citep`. Before a first build they fall back to your bibliography's authors and years.

Use **Split → LaTeX + Visual** while learning. Editing a short passage and comparing its source is a practical way to understand commands without losing the readable view.

## Page layout and included files

After a build, Visual measures the PDF itself: the page size, margins and columns, the body font, size and leading, paragraph indent and spacing, how each heading level is set (size, weight, small capitals, spacing, run-in), the title block, the abstract, captions, the running header, page numbers and review line numbers. The toolbar then reads **Layout measured from the last PDF**. Before a first build, Visual reads the same things from the document class options, `geometry`, `titlesec` and the template's style files.

Pages are set the way TeX sets them:

- Paragraphs continue across pages and columns, keeping at least two lines on each side of a break. Click the continued part to go on typing there.
- Figures and tables go where LaTeX places them: here for `[h]` when they fit, otherwise at the top of this or the next page. `figure*` spans the columns, `wrapfigure` floats beside the text, and subfigures share a line.
- Space merges and drops as TeX's `\addvspace` does, and footnotes collect at the foot of their page or column.
- For paragraphs unchanged since the last build, Visual adjusts word spacing slightly so each takes as many lines as it does in the PDF. Page breaks then follow the PDF closely.

Documents set in Computer Modern are drawn in Latin Modern from your TeX installation, with real small capitals. Times documents use the system Times.

Tables render from `tabular` (booktabs rules, `\multicolumn`, `\multirow`, `\resizebox`), with their cells editable. Pseudocode from `algorithmic` shows with its keywords, nesting and line numbers, `verbatim` blocks as typed, and theorem-like environments with their names and numbers. The reference list is taken from the build's `.bbl`.

Included files (`\input`, `\include`) appear where they are, as the PDF shows them, and their text can be edited in place: the edit goes into that file. Commands the document defines for itself with `\newcommand` or `\def` appear as they expand (`\method` shows the method's name); click one to edit its LaTeX.

**Fit page** changes magnification instead of narrowing and reflowing the document into a different reading width.

## Reveal LaTeX controls

Comments and layout commands are hidden from the reading surface by default. Enable **LaTeX controls** to reveal them. Unsupported environments, and custom commands that do more than substitute their arguments (conditionals, catcode changes), retain source controls or placeholders. Use **LaTeX** for preamble changes, environment restructuring or template-specific formatting.

For example, writing a paragraph is a good Visual edit; introducing a custom theorem environment or changing document-class options belongs in source. A placeholder does not mean the content has been deleted.

## Keep the PDF current

**Refresh PDF after typing** compiles after a short idle period, approximately 1.5 seconds. If an edit arrives while a build is running, another refresh can be queued. Disable the toggle when frequent builds interrupt your workflow, and use **Recompile** explicitly.

> **Exact layout:** Visual follows the PDF closely but does not run TeX. Line breaks inside a paragraph can still differ, and pages drift after long edits until the next build. Use the PDF for submission limits and final proofreading.

## Selection workflows

Selections can become comments, agent context, source checks or linked results through the available selection actions. The source anchor matters: if another edit changes or duplicates the passage before an action runs, VersoFold may require a fresh selection.

Dragging a snippet onto a Visual gap maps the insertion point back to source. Figure templates then open the image picker. Review inserted captions and labels before compilation.

Related: [source editor](source-editor.md), [snippets](snippets.md), [check the sources](evidence.md), [linked results](linked-results.md).


---

# Compilation & PDF

Compilation turns LaTeX source into the PDF you submit or share. It depends on the selected document root, engine, packages, bibliography and any generated data assets. A source save and a successful build are separate events.

## Choose the root and engine

Open the dropdown beside **Recompile**. Choose the complete document containing `\documentclass` and `\begin{document}`. An included section usually cannot compile independently. If your paper and supplement have separate roots, choose the one you want or use **Compile all documents**.

Use the engine required by your template. pdfLaTeX is common for conventional templates. XeLaTeX and LuaLaTeX support workflows involving modern fonts and Unicode, but packages and templates can have engine-specific requirements. A command such as `\setmainfont` typically comes from `fontspec` and belongs with XeLaTeX or LuaLaTeX, not pdfLaTeX.

The packaged desktop app provides its prepared TeX runtime. A source checkout/browser installation needs the local toolchain described in the repository README. A missing tool is an environment problem, not necessarily a mistake in your manuscript.

## Build and inspect

Choose **Recompile** or press **⌘Enter**. The build pipeline first refreshes active remote dependencies, takes a consistent local data snapshot, generates required Figure Studio assets, and then invokes LaTeX. Required refresh or generation failures stop the build instead of silently replacing current data with old output.

The PDF toolbar says when the PDF no longer matches the source. The refresh button at its left turns the accent colour, and an **Out of date** dot appears beside **Auto**; point at the dot to see which files changed since the build. Click the refresh button (or **Recompile**) to update it. With **Auto** on, the PDF rebuilds by itself once you pause typing.

On success, inspect the PDF and the build status. Warnings can remain after a successful build; unresolved references, overflow and font substitutions may still need attention. Bibliography and cross-reference work can require repeated TeX passes handled by the build tooling.

On failure, the previous PDF may remain visible. Treat it as the last successful output, not evidence that the current source compiled.

The build log opens by itself only when a build you started (**Recompile**, **⌘Enter**, or the Visual editor's compile) fails, and only where it fits beside the source. Automatic builds after typing, the PDF's refresh button, and builds started by an agent or another window never open it; the **Build log** button in the footer turns red and shows the error count instead. In PDF-only view a failed build shows a short message rather than rearranging your panes. If you close the log, it stays closed for that same failure; a different failure, or one that comes back after a clean build, opens it again. Reopening the workspace always starts with the log closed.

## Navigate the PDF

Use the PDF toolbar for page navigation, zoom, fitting and text search. The PDF has a selectable text layer when available. Links can open external resources or scroll to destinations within the document.

The PDF keeps your place. A recompile, a document that gains or loses pages, a new zoom or pane width, a switch between views and reopening the app all bring you back to the same page and line rather than the top.

## Move between the source and the PDF

With a compiled source project and SyncTeX information, double-click a word in the PDF to jump to source.

To go the other way, put the cursor where you are working and choose **Show in PDF**: press **⌘⇧J**, click the → arrow on the divider between the source and the PDF, use **Show in PDF** in the editor's tab bar or the Visual toolbar, or search for it with **⌘K**. If the PDF is not on screen, it opens beside the text first. The matching spot on the page is highlighted for a moment. The ← arrow on the divider does the reverse for the part of the PDF you are looking at. When the PDF is already visible, double-clicking a word in the source also follows along; in a LaTeX-only view a double-click just selects the word.

The mapping comes from the last build, in any file the build included, not just the main one. If the PDF has no SyncTeX data (it was made elsewhere, or build files were cleaned), VersoFold asks you to recompile. A file that is not part of the last build, such as a new section not yet `\input`, says so. Lines edited since the last build map approximately until you recompile. An arbitrary imported PDF has no editable LaTeX source to jump to.

Clicking a citation in the PDF opens its card in **References**. In the LaTeX editor a click only places the cursor, and in the Visual editor clicking a citation edits its command. Select text to comment, attach context for the agent, check evidence or link a result when that action is available. Check the quote before saving when the PDF uses unusual columns, ligatures or reading order.

## Read the build log

Open **Build log** in the Recompile menu or press **⌘J**. Start with the first error, because later errors may be consequences. Open the source location when the compiler provides one and inspect the surrounding lines.

- **Undefined control sequence:** a misspelled command or missing package is common.
- **Missing file:** check relative paths and filename case.
- **Missing math delimiter or brace:** inspect the preceding equation or command, not only the reported line.
- **Undefined citations/references:** confirm keys, labels and bibliography configuration, then rebuild.
- **Overfull box:** the document compiled, but content may extend beyond its intended width.

Use [troubleshooting](troubleshooting.md) for a more detailed diagnostic sequence.

## Packages, cleanup and freshness

When a package is missing, inspect the package-management prompt and available runtime. Install the required package through the supported environment controls, then retry. Do not add random packages without identifying the missing command or file.

**Clean build files** removes generated build intermediates so the next build can start fresh. It is useful for stale auxiliary state after a structural change; it is not a substitute for correcting invalid source.

**Build with cached data** and **Build with last assets** are explicit fallback choices for dependency or asset failures. They produce visibly stale evidence and require a complete previous copy. Resolve freshness before claiming a final submission is reproducible.

Related: [page budgets](page-layout.md), [remote data](remote-data.md), [Figure Studio](figures.md).


---

# Snippets & wrappers

Snippets are reusable source blocks: figures, tables, equations, algorithms, theorem environments or recurring prose. Wrappers surround selected text with a template while keeping that text as the wrapper's content.

## Insert a built-in block

Open **Snippets** in the left sidebar (with Bibliography and Figures), from the tools menu, or press **⌘ShiftI**. The library opens beside the sidebar, over the edge of the manuscript; Escape or × closes it. Choose a card or drag it onto LaTeX source or a gap in Visual mode.

A snippet creates a new block at the insertion point. A wrapper uses the text you selected. The drop marker indicates where the block will go. If a block is accidentally dropped into the preamble, insertion can be redirected to the beginning of the document body.

Built-ins cover ordinary/full-width/wrapped figures, multi-image arrangements, several table styles, math environments, lists, theorem blocks, algorithms and reusable passages. Treat them as editable starting points rather than a mandatory paper style.

## Pick figure assets

Figure templates open a searchable image picker immediately. Search workspace images and inspect thumbnails. **Browse this computer** copies an external image into the project's figure folder with a collision-safe name; the original is left in place.

Multi-image templates accept an ordered selection. Reorder the images before inserting to keep panels and captions consistent. Cancelling leaves the source unchanged. VersoFold remembers the drop location by its surrounding source while the picker is open; stale locations require care rather than blind insertion.

After insertion, edit the caption and label. Refer to the figure using `\ref{fig:label}` instead of writing a fixed number.

## Review packages and labels

The insertion form shows the expanded source, packages not yet loaded by the document root, and potentially duplicated labels. **Add to the preamble** inserts missing package declarations while preserving existing package options. **Suggest unique labels** helps avoid duplicate cross-references.

For example, a booktabs-style table needs `booktabs`; a wrapped figure may need `wrapfig`. Adding the environment without its required package can produce an undefined-command error. Read the generated source so you understand what the template adds.

An insertion is one normal editor change. Undo reverses it, autosave persists it, and Review changes treats it like other source edits. Editing the template later does not rewrite blocks that were already inserted.

## Build your own reusable collection

Duplicate a built-in to adapt its source, name and shortcut. Save personally when you want it in every workspace, or in the paper when collaborators should receive it with the folder. Personal templates live in `~/.versofold/templates.json`; paper templates live in `.versofold.templates.json`.

A saved template that reuses a built-in ID customizes that built-in. Deleting that saved customization restores the built-in. Use distinct duplicates when you want both variants available.

Favorite common cards and group them into collections such as “Conference paper”, “Thesis” or “Rebuttal”. Select a preferred collection and default figure/table wrappers for the workspace. Import/export creates portable JSON bundles for transferring templates.

## Expand shortcuts

Type a template shortcut in the source editor and press **ControlSpace** to open its expansion form. Examples may include `fig`, `tabb` and `algo`, depending on the saved collection. The expansion form lets you inspect source and resolve required fields before inserting.

A practical workflow is to maintain a small collection of venue-compatible blocks, insert them with shortcuts, and customize the scientific content after insertion. Keep analytical data in Figure Studio or the table editor when you need repeatable generation rather than a static hand-edited table.

Related: [Figure Studio](figures.md), [table editor](tables.md), [LaTeX techniques](latex-advanced.md).


---

# Comments & reviewing edits

Comments explain a question or requested change. Tracked changes record who changed what in the source, so that each edit can be accepted or rejected. These are related activities, but resolving a comment and accepting a change are separate author decisions.

## Create an anchored discussion

Select a passage in the source or PDF and use the comment action; **⌘ShiftM** comments on the source selection. Inspect the saved quote and location. PDF comments preserve the selected text, so check reading order when selecting across columns or unusual typesetting.

Open **Comments/Notes** to read threads, reply, edit messages, filter them and inspect resolved discussions. Click a location to return to the relevant source or PDF passage. A general comment can describe a project-level concern, while an anchored comment is easier to act on precisely.

Write actionable comments: identify the issue, explain the desired outcome and preserve uncertainties. “Explain why the baseline uses a different split” is more useful than “Fix this”.

## Track changes

Tracked changes work as in Overleaf. The file always holds the text with every change accepted: an insertion is in it, a deletion is not, so compiling, search, the outline and every other tool read the paper as it currently stands. On top of that text the LaTeX editor shows what is still pending, in each author's colour: inserted text underlined and tinted, deleted text struck through where it was, and a bar in the gutter next to each changed line.

Switch **Track changes** on in the editor header (**⌘ShiftE**). While it reads **Track changes on**, everything you type, delete, paste or replace is recorded as your tracked change. The switch belongs to you, in this workspace, on this device; your collaborators each have their own. Turn it off to edit plainly again. Tracked changes need live editing, which is on unless the workspace switched it off.

How edits are recorded:

- Typing next to your own insertion from the last few seconds extends it; typing inside your own pending insertion always does.
- Deleting text you inserted and nobody has accepted yet just removes it; nothing is recorded.
- Deleting accepted text records a deletion that keeps the text. Backspacing or deleting forward through a passage makes one deletion, not one per character.
- Deleting someone else's pending insertion records a deletion over it, and both show. Accepting your deletion removes that text for good; rejecting it gives the text back to their insertion, still pending; rejecting their insertion removes it, and your deletion of part of it with it.
- Replacing a selection is a deletion followed by an insertion; the review shows it as one replacement.
- **Undo** takes back a tracked change together with its record.

Edits made by agents are tracked without asking, attributed to the agent (the built-in agent by model, an external agent by its connection name), with a link to the conversation that made them. Edits written to the files by another program (a second editor, a script, a Git pull) are not tracked unless you ask for it. Both choices are workspace settings at the bottom of the Review panel: **Edits made by agents** (on) and **Edits from other programs** (off).

## Accept and reject changes

Hover a change in the LaTeX editor to see who made it and when, with **Accept** and **Reject** (for a deletion, **Restore**); clicking struck-through text shows the same card. **⌘Option]** and **⌘Option[** move to the next and previous change in the file and open its card.

The **Review** tab on the right (**⌘ShiftR**, also **Review → Track changes**) lists every pending change of the workspace, by file and then by author, with the number of pending changes on the tab. Click a change to go to it. Accept or reject one change, all of one author's changes in a file, everything in a file, or everything the filters show: filter by author (for example only agents, then **Accept all**), by file and by kind.

Accepting keeps the text as it is: an insertion stays, a deletion stays gone. Rejecting removes an insertion or puts deleted text back where it was. A decision applies at once for everyone who has the file open, and is never recorded as a new change. **Show markup** off shows the final text only. The Visual editor marks changes the same way (insertions underlined, deletions struck through) and follows the same switch; the PDF always shows the final text.

People with write access to a file accept and reject its changes. Anyone may reject (withdraw) their own changes. A collaborator on a suggest link can do only that.

## Where tracked changes are kept

Pending changes live in each file's shared document while it is open, and on disk in `.versofold/track-changes.json`, written together with the file. They survive restarts and follow a file that is renamed in VersoFold. If a file is changed by another program while nothing has it open, its changes are carried through that edit the next time it opens; a change inside text that was rewritten can no longer be placed and is dropped, which the server log records.

Versions and automatic checkpoints save the text as it is, with pending insertions in and pending deletions out. **Save version** says how many changes are still pending.

## Compare with approved version

**Review → Compare with approved version** (also at the bottom of the Review panel) compares the whole draft with the version you last signed off: side by side, inline with word-level changes, or as two compiled PDFs. **Approve file** or **Approve all** moves that baseline forward; rejecting a hunk or reverting a file writes the approved text back. Use it before a submission, or for changes that were made without tracking.

Read the exact change before accepting it. A grammatically polished revision can still alter a scientific claim. Rejecting a hunk puts the source back only when the comparison is still current; newer changes can make an old decision stale.

## Understand review baselines

The review baseline is the source state against which **Compare with approved version** works. It is preserved through project history. **Mark as seen** changes your reading position, while shared approval is a separate record.

When old history objects are missing, the app can explain recovery using the oldest available snapshot. It cannot reconstruct lost snapshots. Preserve the hidden history directory when moving or backing up a workspace.

Historical PDFs may be compiled in temporary isolated folders and cached. A current PDF and a historical PDF may differ because the source changed; inspect their labels and build status before interpreting a comparison.

## Work with agent suggestions

Give the agent a focused request and the relevant selected passage or files. Discuss mode is for analysis. Edit mode can apply authorized live changes, while staged source proposals need explicit acceptance.

After the agent finishes:

1. Read its report and referenced source locations.
2. Open **Review** and filter by the agent: its edits are tracked changes in its colour. Look for removed qualifications and changed numbers.
3. Check the recorded build outcome and the actual PDF when layout matters.
4. Accept, reject or revise the changes, one by one or all of the agent's at once.
5. Resolve the original feedback only when the requested work is complete.

The agent can also read the pending changes and, when you ask (“accept my coauthor's changes in the method section”, “reject your edits to the abstract”), accept or reject them for you. A live agent edit is already in the working source before review; a staged proposal is separate until accepted, and becomes tracked changes when you accept it. Undoing an agent edit from its transcript takes its tracked changes with it.

## Collaborators and imported annotations

Shared workspaces can grant reading, comments, suggestions or writing according to the owner's choices. On a suggest link a collaborator edits the live files, but every edit is a tracked change for someone with write access to accept or reject. Reviewer access also depends on whether sources, compilation and history were granted. See [sharing](sharing-export.md).

Use **Import an annotated PDF** to inspect external PDF annotations and bring supported notes into comments. Imported annotation anchors depend on what the PDF contains; verify the result. For Word tracked changes, use the dedicated round-trip workflow instead of treating a DOCX as LaTeX source. Edits in a review file sent back by email arrive as a proposal in **Compare with approved version**.

Related: [versions](versions.md), [agent](agent.md), [deadlines and rebuttals](deadlines-rebuttal.md).


---

# Versions & recovery

Versions preserve manuscript milestones. Automatic history provides additional checkpoints while you work. Both are separate from any ordinary Git repository you maintain for sharing code or sources.

## Save meaningful milestones

Choose **Save version** in the editor header, next to **Track changes**, or open **Review → Versions**. Give the version a meaningful name such as “Before reviewer 2 revision” or “Camera-ready candidate”.

A named version preserves source and, when a matching successful build is available, that build's PDF. A source-only label means the version has no matching compiled PDF. Compile before saving when retaining an exact output is important.

You can also select an automatic checkpoint and choose **Mark as saved version**. This names that earlier source snapshot and retains its original PDF if it was successfully built. Your current draft stays in place.

Use named versions before substantial agent work, project-wide replacement, submission preparation or experimental formatting. Some guarded workflows, including table publishing and linked-result acceptance, create a checkpoint automatically before changing manuscript files.

## Compare versions and files

Select two versions or compare a saved version with the working draft. Use the searchable file list and inspect one file at a time. Side-by-side and unified views show line locations and changed words. Optional data and assets can be included when relevant; saved JSON can be displayed as readable fields.

A source comparison explains what changed. In **Compare**, switch between **LaTeX** and **PDF** to inspect the rendered pages side by side, with linked scrolling. PDF comparison finds retained successful builds for the selected sources, including an identical source snapshot saved under a different checkpoint. An existing PDF from a different draft is not presented as the output of this version.

**Highlight changes**, on by default, marks the words removed on the left PDF and the words added on the right. Text that only moved to another page, page numbers, running heads and words split by a line-end hyphen are not marked, and a page where most words changed says **Many changes on this page** instead of covering it in boxes. Turn it off to stop VersoFold reading the two PDFs' text; the choice is remembered in this browser.

If a side has no matching PDF, choose **Build this version**. VersoFold compiles the saved sources in a temporary folder with the named version’s saved main file and engine; automatic checkpoints use the current build settings. Your working sources and current PDF stay unchanged. The resulting PDF is labeled **Rebuilt from saved sources**, since today’s installed packages may differ from those used originally. Missing captured dependencies or build errors appear with a build log. **Build working draft** saves pending edits and compiles the current project directly from History.

Choose **Fullscreen** in the header to expand History to the whole window. **Exit fullscreen** or Escape returns it to the smaller view without losing your comparison.

## Delete a named version

Select a saved version and choose **Delete version…**. Confirm the named entry you want to remove. This removes its name from Saved versions; it keeps your working files, automatic source checkpoints, and retained build artifacts. You can name a retained checkpoint again later. Shared readers cannot delete versions or compile historical sources.

## Restore carefully

Restore the intended file from a saved version or automatic checkpoint. Choose it in **Compare** or **Saved files**, then select **Restore file**. VersoFold checks that the current revision has not changed since the decision and creates a safety checkpoint. If another editor has changed the file, refresh the comparison and inspect the new state instead of forcing an old decision.

To put a whole version back, select it and choose **Restore this version…**. The confirmation lists each file it would replace or bring back and how many already match. Data and assets are included only when you tick **Also restore data & assets**. Your current files are checkpointed first, and files added since that version stay as they are: a restore never deletes. Figures that Figure Studio publishes are not restored from history, because an older copy would look like an outside edit and stop the next build; the build makes them again from the data instead.

For a partial recovery, inspect the historical passage and restore only what you need through normal editing. A whole-file restore can intentionally replace newer work; choose it only after reviewing the comparison.

If a restore or guarded update reports a conflict, keep your current draft, inspect the conflicting versions and retry from fresh evidence. Do not delete project metadata to dismiss the error.

## Variants, forks and frozen versions

Open **Paper versions & variants** in the history tools for alternative document entries. **New shared variant** previews an extraction: a simple single-file document can become a shared `<entry>-body.tex` with separate entry files/preambles. Later variants reuse that body. Changes to the common body affect the entries that include it. Complex or already split projects can use **Register existing entry** instead.

**Create independent version** copies captured sources into `version/<name>/`. This is an independent working copy, not an automatically synchronized branch. You can start from a frozen submission when preparing a revision. Entry files preserve the original relative-path context; the target list is recorded in `version/manifest.json`.

Set venue class, anonymity, bibliography style and page limits explicitly in each entry's preamble. A name such as “camera ready” does not change template settings. **Build clean PDF**, then **Freeze snapshot**, to preserve the matching original PDF. Changed sources/settings make a snapshot source-only instead of silently pretending the older PDF matches.

**Build revision-marked PDF** compares a fixed baseline with captured current sources using the bundled revision helper. Markup is generated in an isolated build directory; it does not rewrite live source. Inspect complex mathematics, figures, bibliography changes and custom macros carefully. Builds retain an exact source ZIP and build instructions; failed builds preserve previous successful artifacts.

Freezing a manuscript version is distinct from freezing a remote dataset or Figure Studio asset. The former preserves a writing milestone; the latter pins inputs or outputs used by builds. A reproducible submission often needs both source history and preserved data provenance.

For an independent folder copy, use **Home → workspace menu → Make a copy**. This is useful when you explicitly want another workspace rather than another historical state in the same one.

## Storage and backups

History lives in `.versofold/history.git` inside the manuscript folder. Older app-managed history can be migrated from the personal history location on first use. This private history repository is independent of the project's own `.git` repository.

Copy hidden project files when backing up or transferring a workspace. Also back up the personal reference library if you need attached literature and verification records; those may live outside the manuscript folder.

> **Recovery limit:** missing historical Git objects cannot be recreated from a current file. VersoFold can offer the oldest available baseline, but that is not a reconstruction of lost versions.

## Choose the right recovery tool

| Situation | Appropriate action |
| --- | --- |
| Just made an editor mistake | Undo in the editor. |
| Need to reject a pending tracked change | **Reject** on its card or in the Review tab. |
| Need to undo an accepted or untracked change since sign-off | **Review → Compare with approved version**, using a current comparison. |
| Need an older file | Version history and guarded restore. |
| Need the whole paper as it was | **Restore this version…** in History. |
| Need to undo a layout adjustment | Its checked Undo action, or its named checkpoint if newer edits exist. |
| Need to send history to a collaborator | Use a complete workspace backup or an explicitly configured Git workflow. |

Related: [comments and review](comments-review.md), [Git and export](sharing-export.md), [troubleshooting](troubleshooting.md).


---

# Plan with the manuscript board

The manuscript board is a planning space linked to your paper. Open **Write → Manuscript board**. It stores purposes, working notes and next steps independently of assistant conversations.

## Start a board

Import detected manuscript headings, start with the six-section paper outline, or create individual cards. Cards can represent a section, figure, table or note. Give each card a clear purpose: what should the reader understand after this part?

Add an owner label, priority, word target, working notes and a checklist. Owners are plain labels; assigning a name does not notify someone or grant workspace access. A useful checklist contains observable tasks such as “Define the evaluation split” rather than only “Improve methods”.

## Use writing stages and paper order

**Writing stages** shows Planned, Drafting, In review and Ready. Drag a card or change its stage selector. Stage changes preserve narrative order and do not certify scientific readiness automatically.

**Paper order** arranges the planned narrative. Drag cards or use earlier/later controls. This changes the board's order, not LaTeX source blocks. If you decide to move a section in the manuscript, make the corresponding source edit separately and compile.

These views answer different questions: writing stages show progress, while paper order shows the argument's intended sequence.

## Connect cards to actual sections

Linked cards show a source excerpt, approximate word count and **Open in manuscript**. Detected headings follow common `\input` and `\include` structures. Each section's count estimates its own prose rather than counting subsection bodies twice.

Links use the file, heading kind and title, so ordinary line shifts can preserve them. Renamed or removed headings need reattachment. Repeated headings are marked ambiguous rather than silently picking one. Custom macros or conditional compilation may need manual cards because the board is not a TeX expansion engine.

The visible board refreshes periodically and on window focus. **Refresh** provides an explicit check. New headings appear as available sections but become cards only when you add/import them.

## Review source changes

A linked card can show **Text changed** when its source or included fragments change. Read the excerpt and use **Mark text reviewed** to acknowledge the displayed source state. If the source changes again before acknowledgement, refresh and inspect the newer version.

This acknowledgement does not complete checklist items or move the card to Ready. Keep those as deliberate author judgments. A paragraph may have changed without the underlying experiment or review request being complete.

## Save, archive and export

Save card details explicitly. Moving, archiving and restoring cards save immediately. Unsaved details are protected when switching cards or closing the board, and background refresh retains the active draft.

If another writer updates the same card, you can preserve your draft as a new card or discard it and reload. Archive is reversible. **Export** downloads a Markdown snapshot of active cards in their board order, useful for planning discussions outside VersoFold.

The board is stored in `.versofold.board.json` and participates in manuscript history. The current limits are 300 cards including archived cards, 30 checklist items and 6,000 characters of notes per card.

## Ask the agent for planning help

**Help me build the board** prepares a request to inspect the existing manuscript and board, import missing sections and improve purposes or next steps. **Improve this card with agent** targets a saved card. Review and send the prepared prompt with your configured model.

Board tools can update planning records in authorized Edit mode without changing manuscript source. The agent should preserve your decisions and should not mark work ready solely because text exists.

Related: [working with the agent](agent.md), [deadlines](deadlines-rebuttal.md), [versions](versions.md).


---

# References & citations

VersoFold separates the shared reference library from a manuscript's bibliography. The library is your research collection across workspaces. A `.bib` file is the portable bibliography source used by a particular LaTeX document.

## Collect a paper

Open **Reference library** on Home. Drag a paper in from your browser (the tab's address, or a link on a page) and it is saved straight away, or paste a DOI, publisher link, arXiv link, direct paper URL, BibTeX or RIS. **Add a paper** in the editor takes dragged links the same way. VersoFold creates an unchecked record and attempts registry metadata retrieval where supported. Metadata lookup needs connectivity; PDF access can depend on the publisher.

You can import exports from tools such as Zotero and EndNote. Local Zotero integration depends on Zotero running with its local API available. Inspect the imported title, authors, year, identifier and entry type rather than assuming an import proves accuracy.

**Scan workspaces** reads bibliography entries from saved workspaces without changing those files. Records retain their originating workspace, bibliography path and citation keys.

## Organize and reconcile

Use tags and named collections to gather papers by question, method or project. Add reading notes, attach PDFs and copy/download a selection as BibTeX. A collection can generate its own bibliography.

**Reconcile duplicates** groups records that appear to describe the same work. Identifier matches and supported title/author/year similarities help detect candidates. Preprints and published versions are shown for your decision instead of being silently merged.

Choose which record to keep; merging preserves associated keys, sources, links, tags, notes and attachments. It does not rewrite existing manuscript citation keys. **These are different papers** records a durable distinction. A duplicate group may temporarily mark records as **Needs review** until resolved.

## Cite while writing

In the source editor, begin a citation command and search the suggestions. **In this paper** shows existing workspace keys. Shared-library suggestions can match titles, authors, venues, years and identifiers.

Selecting a library paper inserts its citation key and appends its full BibTeX entry to the workspace bibliography. Existing identity matches are reused. If a desired key belongs to another work, the insertion coordinates the new bibliography key with the typed citation rather than silently overwriting the existing entry.

The suggestion list keeps **Browse the reference library** and **Add a paper by link or BibTeX** available. The full library opens with the typed query and offers **Cite this paper**. The Bibliography panel also has an Add a paper action.

Useful suggestion filters include:

| Filter | Purpose |
| --- | --- |
| `is:checked` | Restrict to checked library records. |
| `in:Related-work` | Search a named collection. |
| `from:NSERC` | Narrow by workspace/source name. |
| `tag:methods` | Narrow by tag. |
| `sort:year` | Order by publication year. |

The citation command must be supported by your template. `\citep`/`\citet` commonly require natbib; `\parencite`/`\autocite` belong to biblatex workflows. The editor can insert a command that still needs the right package. See [LaTeX bibliographies](latex-advanced.md#bibliographies).

## Inspect the bibliography and reference cards

**Bibliography** searches project entries, opens their `.bib` source and lets you copy citations or follow paper links. Notes/References orders reference cards by first citation; **This page** narrows the list to the current PDF page when citation locations are available.

Clicking a citation in the PDF highlights its record in References. In the LaTeX editor a click only places the cursor; in the Visual editor it edits the citation command. For imported PDFs, extracted references and Crossref matching are heuristic. Strong matches can populate metadata; uncertain matches need selection. **Find paper** opens the identified destination or a search. **Download PDF** attaches an available copy and becomes **Open PDF** when present.

## Review what an agent hands back

When an agent cannot settle a record, it marks it **Needs review** and says why. The References tab, the Bibliography panel and Home → Reference library each show **N references need your review**; **Review** goes through them one at a time, in the order they are listed. **Review now** on a card opens the same review at that record.

Each record fits on one screen:

- its fields, with a check mark on each one the agent verified. A field the agent changed says what it was. A field the agent only proposes shows the current value struck through beside the proposed one, with a box to leave it out.
- the `.bib` entry that holds it and where the paper cites it. If that entry disagrees with the library record, the differing values are shown too.
- the agent's open questions, limitations and corrections, and every source it consulted as a link.
- **Open paper** (the DOI, then arXiv, then the record's own link), **Open PDF** when one is attached, and searches on Google Scholar, Crossref, Semantic Scholar and arXiv built from the title and first author.

Decide with one click. A note is optional.

| Action | Result |
| --- | --- |
| **Confirm — it's correct** | The record becomes **Checked by you**. |
| **Apply correction & confirm** | Writes the proposed values you left ticked, then confirms. **Keep current & confirm** keeps what the record says. |
| **Needs work** | The record stays in Needs review as **Flagged by you**. Your note goes to the next agent check. |
| **Edit BibTeX** | Replace the record with your own entry, then **Save BibTeX & confirm**. |

Enter confirms (**⌘Enter** while editing BibTeX), ← and → move between records, and Esc closes. **Undo** appears after each decision, and **Reopen your review** in a record's verification report does the same later: the fields the decision changed are put back and the record returns to Needs review. **Review this check** on an agent-checked record lets you overrule it with **Needs work**.

If the record changed while you were looking at it, for example because a new agent report arrived, the review shows the latest version and asks again instead of overwriting it. If it may be the same paper as another record, the review shows both. Merge them if they are one paper, or mark them as different papers; the decision waits until that is settled.

Decisions change the shared library, never a workspace `.bib`. When a paper's `.bib` disagrees with the library record, **Copy library BibTeX** and paste it over the entry, open the entry, or keep the paper's values with **Use this paper's values & confirm**.

## Metadata checking is different from evidence

Records distinguish **Unchecked**, **Checked by an agent**, **Checked by you**, **Needs review** and **Flagged by you**. Verification briefs explain what to check and preserve evidence-backed reports. An agent can leave a correction it could not confirm as a proposal, which you accept or leave in the review. Metadata changes can require rechecking. A registry match alone does not set a checked status.

A correct title/DOI does not establish that a paper supports your claim. Use [Check the sources](evidence.md) to find the passages a citing sentence rests on, and judge support separately. Read the actual source before strengthening wording in the manuscript.

Library records live outside individual projects. Export or generate the bibliography you need when sharing source, and back up the shared library separately when preserving your research collection.


---

# PDF reader & reading desk

Use the PDF reader for a paper opened from disk, and the reading desk for a persistent literature-reading space. Both let you select passages, inspect references and ask focused questions while keeping the original PDF intact.

## Open a research PDF

On Home choose **Open PDF**, drop a PDF, or use the desktop file association. VersoFold keeps a reading copy, extracts text with page headings and attempts to identify bibliography entries and citation locations. It leaves the original file where it was.

Use the PDF toolbar to navigate pages, zoom, fit the page and search text. External links open their destinations; internal links move within the PDF. Imported PDFs do not have editable LaTeX source merely because they are open in VersoFold.

The reference panel shows compact cards in citation order. Inspect uncertain metadata matches and choose candidates when necessary. A downloaded/attached paper can be opened from its library record.

## Open the reading desk

Choose **Reading desk** on Home or in the research reader's header. Opening it from a PDF selects that paper. The desk places the library on the left, the paper in the center and notes or the agent on the right.

**My reading** is a personal collection that works without a manuscript. The **Reading space** selector also opens workspace collections. Choose deliberately: personal notes and a paper's project notes can be different collections.

Search the library or queue by title, author, year and tags. `#tag` queries and tag filters help narrow a topic. Mark papers To read, use reading status, and star papers you want to return to. A paper can join the reading queue before its PDF has been attached.

## Compare papers and save passages

Open a second paper for a side-by-side comparison. Search within either PDF independently. A useful comparison workflow is to read both methods sections, then compare evaluation data, assumptions and limitations rather than only abstracts.

Select text and choose **Save passage**. Add a Markdown note explaining why it matters. Notes retain page links so you can return to the passage. Keep exact quotations separate from your interpretation; an extracted phrase can lose context without the surrounding page.

**Export notes** downloads Markdown for use elsewhere. Removing a missing attachment does not erase saved notes. A paper with notes cannot be removed from the collection until those notes are removed.

## Use the reading companion

Select a passage or ask a question in the desk's agent panel. The request carries the current paper's reference identity, comparison paper and selected passage when supplied. Switching papers updates that context. The assistant can retrieve attached PDFs through its reading tools.

Starter questions prepare text for you to review and send. A model connection is required for responses. For a useful request, specify the page/passage and the question: “Explain the assumption in this paragraph, then compare it with the second paper's setup.”

The assistant should read extracted text first and use page images when equations, figures or poor extraction require visual inspection. It should distinguish what the source says from its own explanation.

## Know the extraction limits

PDF text order can be imperfect for columns, tables, ligatures and equations. Scanned pages may contain no searchable text. OCR is not included in the reading workflow; inspect the page image in those cases. Bibliography extraction and registry matching can miss or misidentify entries.

A failed search means no match was found in the available extracted text, not that a concept is absent from the paper. Check the PDF directly before making that claim.

## Preserve notes and positions

Personal notes live under `~/.versofold/reading-desk/`; workspace notes live in `.versofold.reading.json`. Saves use revision checks. If another writer changes the record, retain your draft and reload or reconcile instead of overwriting silently.

Workspace memory remembers PDF position, zoom, the comparison paper and panel arrangement on this device. Disabling position restoration does not delete saved notes. See [Home & workspaces](workspaces.md).

Related: [check the sources](evidence.md), [references](references.md), [agent](agent.md).


---

# Check the sources

Does the paper you cite say what your sentence claims? **Check the sources** shows you where to look. For each paper a sentence cites, it lists the passages of that paper's PDF that come closest to the sentence, with their page numbers. It runs on this device and takes a moment.

## Check a sentence

Select a sentence and choose **Check the sources**:

- **LaTeX editor:** the magnifier in the selection toolbar. A partial selection grows to the whole sentence, so its citations come along. Double-click a citation key to check the sentence that cites it.
- **Visual editor:** click in the paragraph, select the sentence on the page, then choose **Check the sources** in the toolbar. With nothing selected, the whole paragraph is checked.
- **PDF:** select the sentence, then choose **Check the sources**. VersoFold finds the sentence in the LaTeX through SyncTeX, so the citations are read from the source, not from the printed numbers. Recompile if it cannot find the sentence.
- **A citation:** click it in the PDF, then choose **Check the sources** on its card under References. Every reference card cited in the paper offers the same action. It checks the sentence that cites the reference on the PDF page you are viewing.

A small card opens beside the sentence. Press Escape or × to close it; nothing else on screen changes.

## Read what was found

Each cited paper is found through the paper's `.bib` files and your reference library. It lists up to three passages, best match first: a short quote and its page. **Open the page** shows that page of the PDF, with the passage highlighted.

Passages are matched by their words, not their meaning. A good match is a place to read, not a verdict. No match does not mean the paper disagrees: it may use other words, or the claim may rest on a table or a figure. Equations and tables often extract poorly. Scanned PDFs have no text to search, because OCR is not included.

When a cited paper has no PDF, the card says so and offers two ways to add one:

- **Find the PDF** looks for it through the paper's arXiv id, DOI or link, and attaches it to the library record.
- **Attach a PDF…** attaches a file you already have.

If the paper is in the `.bib` file but not yet in your reference library, it is added to the library first. The card then checks again. A citation key that is in no `.bib` file is listed as such: fix the key, or add the entry.

## A sentence that cites nothing

If the sentence has no citation, the card searches every paper in your library that has a PDF, and says that this is a search, not a check. Use it to find a paper the sentence could cite, then cite it as usual (see [references](references.md)).

## Ask the agent to judge it

**Ask the agent to judge it** opens the agent with a prepared request: the sentence, its file and line, the cited papers and the passages found. Nothing is sent until you send it. The request asks the agent to read the cited pages and give a short verdict for each paper (supported, partly supported, not supported, or can't tell) with the quote and page it rests on, and not to edit the paper.

Agents keep their evidence tools (`search_evidence`, `evidence_inspect`, `assess_claim_support` and `evidence_anchor`) without the card, for example when you ask one to check every claim in a section.

## Pin the check to the sentence

**Pin to the sentence** saves the check as a comment on the sentence, labelled **Source check**. It lists the cited papers, the passages and their pages. Reply with your own reading or the agent's verdict, and resolve the thread when the sentence is settled. There is no separate record to keep up: the thread follows the sentence like any other comment (see [comments and review](comments-review.md)).

## In the PDF reader

When you read a paper in the PDF reader, select a passage and choose **Check the sources**. The reader matches the passage's citation numbers, or author and year, to the paper's reference list. Cited papers that you have downloaded to your library are checked, and pins go to the reader's comments.

Evidence records saved with earlier versions stay on disk, and agents can still read them.

Related: [references](references.md), [reading](reading.md), [agent](agent.md), [workspace memory & procedures](memory-procedures.md).


---

# Working with the agent

The VersoFold agent is a research and writing assistant that works through app tools. It can read relevant source, explain a paper, check references, prepare research records, help design figures and make authorized edits. Opening a conversation does not itself contact a model; sending a request starts a run.

## Connect and choose a model

Open **Settings → AI & agent → Connections**. Choose a supported provider, a compatible endpoint or an available subscription connection, then follow its setup. Model choices and capabilities depend on the configured connection. Refresh/discover models when the account's catalog changes.

Custom endpoints are Discuss-only by default unless compatible tools have been verified. Connection tests should be distinguished from a real manuscript task. VersoFold does not silently switch to another account after authentication, quota or provider failure.

Browser-mode connection secrets remain in the server session. Desktop can remember supported credentials when explicitly selected: in the Keychain on a Mac, in the desktop keyring (GNOME Keyring or KWallet) on Linux. Without a keyring, Linux asks for the key again in each session rather than writing it to disk in the clear. Credentials do not belong in manuscript files or prompts.

## Give a concrete request and context

Select the relevant file or passage and add it to the composer. Source/Visual selections, PDF text, small text files, PDFs and compatible images can become explicit attachments. Review the context manifest to see supplied material and subsequent tool reads.

Buttons elsewhere in the app also write requests for you: **Draft with agent** in the Response view, **Ask the agent to judge it** when checking sources, **Tidy with the agent** when importing reviews. They open the agent with the request ready; with no model connected, it waits in the message box until you connect one and send it.

Specify the outcome and constraints. Examples:

- “Explain this equation using the notation in the methods section. Do not edit.”
- “Shorten this paragraph while preserving every number, qualification and citation.”
- “Inspect the CSV, plot mean and standard deviation across seeds, and render the figure. Ask if the grouping is unclear.”
- “Check whether the attached source supports this claim and quote the relevant passage.”

The **Prompts** library provides searchable starting points for reading, reviewing, reproducibility, citation checking and writing. Edit a prompt to fit the actual task before sending.

## Edit, Plan, Discuss and approval

The composer shows two controls next to the model: **Mode** and **Approval**.

**Edit** is the default for workspace conversations. The agent can change any text file in the paper — TeX and BibTeX, scripts, data, notes, style files — create new files, move or rename them and delete them, and run commands in the paper's folder. Its scope is the whole workspace unless a request was narrowed to specific files (an inline edit of a selection, say); reaching past that asks you instead of failing. Hidden files, VersoFold's own metadata (`.versofold*`, comment and task stores) and credential-named files are never available to it.

**Discuss** is for talking the work through first. The agent reads and answers, and the edit tools stay available: the first time it reaches for one, the conversation pauses with “The agent wants to edit main.tex — allow edits in this conversation?”. **Allow edits** switches the conversation to Edit and the run continues; **Keep discussing** leaves it in Discuss, and the agent describes the change instead. Read-only companions (the reading desk and research reader) are the one place edits are really unavailable.

**Plan** is read-only too: the agent works out a step-by-step plan for the change without making it. Switch to Edit to carry the plan out.

Every change goes through VersoFold's journal: exact replacements check the file hash (a replacement whose passage still matches exactly once is applied even if you edited elsewhere in the file meanwhile), whole-file writes need the hash they replace, deletions go to a private trash, and commands are snapshotted before and after. Each one has an **Undo** in the transcript. An edit to an existing file also arrives as a tracked change in the agent's name, in its own colour: accept or reject it in the editor or in the **Review** tab, one by one or all of the agent's at once (the workspace setting **Edits made by agents** at the bottom of Review turns this off). If you are typing in a file the agent edits, it waits a moment for the autosave and otherwise your editor merges the change into your unsaved text.

**Approval** decides when a permitted action pauses for you:

| Action | Manual | Accept edits (default) | Auto | Full access |
| --- | --- | --- | --- | --- |
| Reads of the paper, the library and the handbook | runs | runs | runs | runs |
| Edits to the paper, research records, reference-library verification and citations, public web reads | asks | runs | runs | runs |
| Reading a file outside the paper | asks | asks | runs, unless it looks like a key or credential | runs |
| Commands and scripts (workspace, sandboxed, remote) | asks | asks | a verifier clears it or asks you | runs |
| Saving preferences, git or Overleaf pushes, author decisions (resolving comments, restoring or freezing versions) | asks | asks | asks | runs |

**Allow for this conversation** answers for that tool until the conversation ends; **Conversation actions → Ask again before allowed tools** clears those answers. Approval never widens the workspace, the file scope, the library or web grants, or another conversation.

> **Live versus staged:** a successful live edit has already changed the working manuscript; as a tracked change it stays marked until you accept or reject it, and accepting does not apply it a second time. A staged proposal (`stage_source_proposal`) remains separate until you accept it, for when you want to review a larger change before it lands; once accepted, its edits are tracked changes too.

The agent sees the pending tracked changes (`read_tracked_changes`: who changed what, where) and, in Edit mode and when you ask for it, accepts or rejects them (`decide_tracked_changes`), for requests such as “accept my coauthor's changes in the method section” or “reject your edits to the abstract”. A checkpoint is taken first. See [tracked changes](comments-review.md#track-changes).

## What the agent can do

Besides reading, searching and editing, the agent can:

- **Run commands** in the paper's folder with `run_command` — the paper's own analysis or plotting scripts, `latexmk` on a supplement, data checks. Commands use your installed tools, run in a sandbox (the macOS sandbox on a Mac, bubblewrap on Linux: writes only inside the workspace, never its hidden VersoFold or git folders; no credential stores; no network unless the command asks for it and you or the verifier allow it) and report the files they changed. Longer research scripts can also run in the separate research sandbox.
- **Read a file elsewhere on your computer** that you name, such as a shared style file or a dataset.
- **Use the rest of VersoFold** through `find_capabilities` and `use_capability`: git, history and named versions, paper variants, tasks and comments, tables, page layout, rebuttal, submission rehearsal, the web edition, templates, the spelling dictionary, reference-library management, remote data, Overleaf and exports. These are the same capabilities external agents use, with the same approval and file-scope rules.

When the agent cannot do something, its message says what to do next: allow edits, allow another file, wait for your autosave, read the file again, or describe the change for you to make.

## Inspect results and stop when needed

The transcript shows responses, source links, tool activity and recorded outcomes. Only reported reasoning summaries are displayed. A claim that something compiled should have an actual build result. Open the PDF when layout matters.

Use **Stop** to cancel ongoing work. Cancellation does not undo a completed write. Use an edit's checked Undo control while its recorded state still matches, or review the source/history when newer edits exist.

Runs interrupted by restart remain visible as interrupted; they are not silently replayed. A failed or incomplete tool response should be checked against actual state before repeating a write.

## Notifications

When an agent needs your approval, asks a question, or finishes, VersoFold tells you. That covers the built-in agent, a connected Claude Code, Codex or ACP chat, and an external MCP client. While VersoFold is behind other windows you get a system notification; clicking it opens the conversation, or External agents for an MCP request. In front, a bell with a count sits in the header until every request is answered, and the Dock icon shows the same count. Switch them off under **Settings → General → Notifications**, where **Send a test notification** shows one and says whether the system displayed it. If nothing appears, allow VersoFold in your system's notification settings (on a Mac, **System Settings → Notifications**; macOS asks once, the first time) and check that Focus or Do Not Disturb is off. In a browser, choose **Allow notifications** there once.

## Conversations, branches and long context

Create, rename, reopen, export or delete conversations using their controls. Deleting a conversation removes its transcript/execution history, not manuscript edits. Workspace conversations are retained in the project's hidden agent area; personal library conversations and account settings are separate.

Conversation Undo/Redo moves the active conversation boundary without changing files. **Edit & retry** branches before a user message and returns its text for revision. A branch preserves the original conversation. Long conversations can compact into a continuation checkpoint while retaining the complete local transcript and execution evidence. **Compact** also provides an explicit action.

Usage indicators show available token/context measurements. Cost is an estimate when pricing is configured, not a subscription balance. Missing usage/cost information should remain unavailable rather than being treated as zero.

## Preferences, advanced tools and background work

Save personal or project writing preferences, reusable profiles and prompt shortcuts. Current requests take precedence over preferences. Notes the agent keeps about the paper are approved, edited and forgotten in **Workspace memory**; reusable procedures are written and versioned in **Settings → Procedures** and run from the composer's **+** menu with **Use a procedure**. See [workspace memory & procedures](memory-procedures.md).

Public web research is on unless you turn it off in Agent settings. Commands and research scripts follow the approval table above. Remote execution and registered MCP extensions are enabled per message from the composer's **+** menu and have their own prerequisites. A figure recipe is declarative data; it does not authorize arbitrary script execution. Remote commands require the configured connection, folder and executable restrictions.

Agent settings also manage persistent, budgeted read-only background questions and stopping/pausing controls. Background tasks remain bound to their declared workspace. Read-only work may run concurrently while each workspace keeps a single edit writer.

## Documentation is consulted on demand

The agent knows this handbook exists, but its contents are not automatically added to every conversation. It is instructed to search/read it only when you explicitly ask for documentation or how to use VersoFold, or when it is stuck on a specific VersoFold capability needed for your task.

Ask “Use the handbook to explain how to freeze a dataset” to request a lookup. The agent can search sections and read bounded Markdown excerpts. The handbook does not replace reading your actual manuscript and does not authorize actions. See [handbook access for agents](agent-reference.md).


---

# Workspace memory & procedures

Two things carry over from one agent conversation to the next: **notes about your paper** that every new conversation reads, and **procedures**, reusable methods you can ask the agent to follow. Notes live in **Workspace memory**, beside your saved layouts. Procedures live in **Settings → AI & agent → Procedures**. Both are saved with the paper, so they survive restarts and travel with the project folder.

The agent panel itself is just the conversation. Anything the agent saves along the way shows up as a card in the transcript.

## Notes the agent reads

Open **Workspace memory** from the **Workspace** gear menu, or search for it with **⌘K**. The section **What the agent knows about this paper** lists notes about terminology, notation, datasets, decisions, constraints and open questions. A note can apply to the whole paper or to one source file. A file-scoped note is offered to the agent only when that file is in play.

Each note keeps its source or reason: a lab-meeting decision, a passage in a project file or a page of a paper in your reference library. Open a note to read its full text, its source and when it was proposed.

Keep writing preferences and project facts apart. “Prefer concise captions” is a preference and belongs in **Settings → Writing preferences**. “Experiment B uses split X” is a fact about the paper, so it belongs here, with the evidence for it.

## Approve, edit and forget notes

The agent can propose a note while it works, but a proposal is not used until you approve it. Proposals sit at the top of the list marked **Awaiting your approval**. You can also approve one straight from its card in the conversation where it was proposed.

1. Open the proposal and read the wording and its source.
2. **Approve note** if it is right, or **Edit** it first. Saving your own wording approves it.
3. **Forget** a note you no longer want. Forgetting is reversible: **Forgotten notes** lists them, each with **Restore**.

**＋ Add a note** writes one yourself. Your own notes are approved as soon as you save them.

When the source behind a note changes, the note is marked **Needs recheck** and left out of new conversations until it is reassessed. Ask the agent to recheck it against the current source, or forget it. An early misunderstanding that becomes a durable note would be repeated in every later conversation, so read proposals before approving them.

## Build reusable procedures

A procedure describes a repeatable method: the inputs it needs, its steps, the outputs to expect, how to check the result and any resources to consult. Open **Settings → AI & agent → Procedures** in a paper. Start from a built-in procedure (a rebuttal, a camera-ready review, a statistics audit or a related-work synthesis), write your own with **New procedure** or **Import SKILL.md** to review a Markdown draft.

1. Name the task and list the inputs it should ask for. Mark the ones it cannot do without as required.
2. Write steps that say what evidence to inspect and how to handle missing information.
3. Define concrete outputs and completion checks.
4. Choose the tool scope. **Research only** procedures cannot edit manuscript files. **Guarded manuscript edits** keep the ordinary file scope and approval rules.
5. Save. A procedure the agent proposes must be approved here before it can run.

Resources are references for the agent to read. They are never run as scripts.

## Run a procedure in a conversation

In the agent composer, open **＋ → Use a procedure** and pick an approved procedure. If it asks for inputs, a short form opens above the composer; fill it in and choose **Use procedure**. A chip above the message box shows the procedure and its version. **Inputs** reopens the form, and **×** removes the procedure.

The procedure runs with your next message, pinned to the version you chose. Editing the procedure later saves a new version and does not change a run that already used the old one. If the procedure changed after you picked it, sending is refused until you pick it again.

## Versions, export and import

Every save keeps the previous version. **Version history** lists them; **Use as a new version** starts an edit from an older one. **Export SKILL.md** downloads the current version as Markdown that other tools can read, and **Import SKILL.md** brings one back as a draft to review. **Archive** hides a procedure without deleting it; **Archived** lists archived procedures with **Restore**.

## What the agent saves during a conversation

Besides notes and procedures, the agent can save evidence assessments for claims, literature comparison tables, revision plans and completion checklists. Each appears as a card under the reply that saved it. A saved claim's card opens its passage in the manuscript. The agent can read these records back in later conversations: ask it to summarize or update one.

To check a claim against its sources, see [evidence](evidence.md). For numbers that must stay connected to their data, see [Linked results](linked-results.md). For a plan of the paper's sections, see the [manuscript board](manuscript-board.md).

## Where it is stored

Notes, procedures and the other agent records live in `.versofold/research.json` inside the project folder. Layouts and reading positions in Workspace memory stay on this device. Writes are serialized and check each record's revision: if the agent changes a note while you edit it, saving is refused and the list reloads with the newer version, so you can reapply your change to it. These records are evidence and plans for the agent to read. They never grant it extra permissions.

Related: [working with the agent](agent.md), [home & workspaces](workspaces.md), [find your way around](navigation.md).


---

# External agents & connections

**Workspace → External agents** connects another assistant to one authorized VersoFold project. The Model Context Protocol (MCP) exposes app operations so source changes, compilation, research records and review can use the same guarded services as the built-in agent.

Open the same page from **Settings → AI & agent → External agents**, from **Connect an agent** at the bottom of the agent panel's model menu, or from **Conversation actions → Agent settings** in a connected-agent conversation. The page has **Agents & apps**, **Brief & scope**, and **Completion & evidence**.

## Chat with Claude Code, Codex or another installed agent

Agents installed on your computer appear in the agent panel's **Choose model** menu, under **Connected agents**, next to the VersoFold agent's models. Pick **Claude Code** (your Claude subscription) or **Codex** (your ChatGPT subscription) and the panel switches to that agent; pick a model again to switch back. Inside a connected chat the same menu lists that agent's models first, then the other agents and the VersoFold agent's models. One conversation history holds both kinds of chat.

The same agent panel is available in the editor, PDF reader, reading desk, and reference library. The selected document, passages, and suggested prompts provide the context; model selection, history, and approval controls work the same way. Library conversations use library tools without attaching a manuscript.

Claude conversations default to **Latest Claude Opus**, using the newest Opus reported by Claude Code. **Claude account default** is a separate choice and can point to an older model. Select an exact version to keep using it. **Choose visible models**, at the bottom of the model menu or under **Settings → External agents**, lets you show or hide choices, add a model ID, and **Refresh models**. These visibility choices apply across workspaces and readers. The selected model stays visible until you choose another. If a new model is missing, update Claude Code and refresh.

VersoFold asks Claude Code and Codex which models your account offers and shows their names. Each reply's header names the model that actually answered, and **Usage** shows the latest one.

The menu says when an agent's program is not on this computer. Choosing it then shows how to install it and sign in, with a **Check again** button. **Settings → External agents** lists the same agents with their status and a **Chat** button; **Add another agent** registers any Agent Client Protocol (ACP) program, such as Gemini CLI, by its executable and launch arguments.

The connected chat has the composer you know: the **+** menu attaches images and text files, the passage you selected, and prompts from the prompt library. Models, thinking, project mode, approval and writing style sit below the message. **Conversation actions → Conversation options** holds the reference-library and public-web switches for that chat.

## Use VersoFold from another app

Under **Use VersoFold from another app**, **Add** next to **Claude Code**, **Codex**, **Claude Desktop** or **Cursor** creates a connection to this paper and writes it into that app's MCP settings: there is no configuration to copy. Claude Code keeps it with this paper's folder, so running `claude` there finds VersoFold's tools. Codex, Claude Desktop and Cursor have one global list, so adding a second paper moves the entry to that paper. Claude Desktop needs a restart to load it. VersoFold keeps a backup of an app's original config file (`….versofold-backup`) the first time it edits it, and never overwrites a file it cannot read. **Remove** (or **Disconnect** in the connection list) revokes the key and takes VersoFold out of the app again.

For any other MCP client, **Another MCP app** creates a configuration with a private key to paste into its settings. A cloud client uses **Agents on the web**, the separate remote gateway with its own authorization; a reviewer share link is not an MCP connection.

Available models, effort controls and native modes depend on each runtime and account.

Avoid copying account credentials into a project. VersoFold's runtime adapters use their supported authentication paths and do not treat subscription credentials as API keys.

## Grant only the intended scope

New connections can read and edit the paper, use your reference library and search and read public websites. Every write is guarded, journaled and undoable, and follows the connection's approval mode. Narrow any of this when you create the connection, or later in the connection list: each existing connection has its own **Project access**, **Approval**, **Reference library** and **Public web** controls, and changing them keeps its key, so the client needs no new configuration. The connection stays bound to its original project even if you open another workspace.

In a connected chat, **Project mode** chooses Edit (the default), Plan or Discuss, and **Conversation options** holds the library and web switches. **New connections can** above the app list sets the access for the next app you add.

If an agent reaches for something its connection was not given — an edit in a read-only connection, the library, the web — the call becomes an **access request** instead of failing: “Claude Desktop asks for edit access to this project”. Allow it in one click in the External agents panel, or inline in a connected chat; the connection keeps that access from then on and the agent retries the same step. Declining is remembered, so the agent is not asked again; change the connection's controls to grant it later. A client that asked for read-only access when it connected keeps that ceiling.

Approval choices govern requests within those grants, with the same table as the built-in agent: Manual asks before anything that is not a read; Accept edits lets paper edits, library records and web reads run and asks before commands, files outside the paper, pushes, preference changes and author decisions; Full access asks for nothing. With Claude Code and Codex, Auto uses the runtime's own reviewer. None of them grants unrelated workspaces, account administration or proposal acceptance.

Some runtime capabilities are deliberately restricted to VersoFold tools. ACP programs are external executables and are not made into an operating-system sandbox by MCP permissions; choose a program you trust and review native requests separately.

## A productive first request

Ask the assistant to read the workspace context, inspect the relevant source and explain its intended change. It can discover tools by topic rather than guessing endpoint names. Large tool catalogs and results are paginated; a client needs to follow continuation information.

Example: “Read the current methods section and page budget. Propose a clearer organization, preserving every experimental setting. Stage a multi-file restructuring for my review.”

The documentation tools are available here too. They follow the same on-demand policy as the native agent: use the handbook when explicitly requested or when stuck on a specific app capability, not as routine startup reading.

## Review actions and proposals

Source reads return locations and current state. Guarded edits check hashes and unsaved buffers. Larger proposals can compile in an isolated copy before acceptance. Open the proposal's before/after source and PDF, then accept or reject it in VersoFold.

An `approval_required` or `input_required` response means the action has not happened. Review the exact request in the app — an access request, a tool approval or a question. Connected chat resumes after your answer; a standalone client retries the identical call. An `approval_denied` or `access_denied` response means you declined, and the agent must not repeat the action with changed arguments to avoid the decision.

Activity records identify completed operations. Source-edit Undo applies only while its recorded edited state still matches; other domain operations have their own revision/history controls.

## Stop, disconnect and resume

Stop ends the active runtime turn and revokes its current connection as implemented by the adapter. Disconnecting prevents future tool calls and requests cancellation. A write that already completed remains applied.

Runtime conversations have their own saved history and IDs. Supported clients resume their saved session; others may use a bounded recap. Interrupted turns are not automatically replayed. Deleting VersoFold's transcript does not necessarily delete a runtime's own external history.

Before retrying after a lost response, inspect the current source or domain record. This avoids creating duplicate work when the first action succeeded but its result was interrupted.

## What remains an author action

Account login, credential changes, granting/revoking access, sharing invitations, public hosting and external publication remain owner operations. Agents cannot manufacture approval or accept their own source proposals. Importing binary files and full Overleaf synchronization may require the app's dedicated interfaces.

For integration details and request formats, use the MCP configuration shown by your running app and the machine-readable handbook described in [agent reference](agent-reference.md). Treat the live tool catalog as authoritative for that connection.


---

# Figure Studio

Figure Studio turns recorded data and editable recipes into publication assets. Open **Figures → Figure Studio**. The gallery preserves designs and datasets, while Source, Design and Publish organize each item's workflow.

## Bring in data and inspect it

Choose New figure or New table. Import a workspace CSV/TSV/JSON file, drop a file, paste spreadsheet cells or type a small dataset. Inspect inferred column types, units, missing values and distinct counts before choosing a chart.

Original inputs remain intact. Editing values in a linked dataset creates an editable copy rather than silently rewriting the original file. Studio records source fingerprints, parsing rules, column mappings, preparation steps, theme version and generated outputs.

Use tidy repeated rows when you have seeds or folds:

```csv
method,seed,step,accuracy
Baseline,1,100,0.72
Baseline,2,100,0.74
Ours,1,100,0.78
Ours,2,100,0.80
```

Keeping repetitions lets the recipe summarize them explicitly. Do not discard repeated measurements and invent error bars from a final mean.

## Prepare data reproducibly

Preparation steps include filtering, sorting, derived columns, normalization, group summaries, spreading/gathering columns, smoothing, renaming and joins. Inspect the prepared rows after every analytical transformation.

Derived expressions can describe quantities such as `(ours - base) / base` or `log10(params)`. Group summaries include mean, median, standard deviation, standard error, count, first and last. Training curves can use an exponential moving average or moving average.

Choose grouping keys deliberately. Averaging across datasets can answer a different question than averaging repeated runs within each dataset. Record the analysis choice in the caption or method when needed. Smoothing is a presentation/analysis operation that should be disclosed rather than mistaken for raw measurements.

## Choose a chart and refine it

Available forms include line, scatter, grouped/stacked/horizontal bars, heatmap, box, violin, histogram and density. Suggestions can provide training curves, final-result bars, methods-by-dataset tables, confusion matrices or scaling plots.

Map columns, then check axis labels and units, series order, scales and ranges. Wide tables can plot several Y columns directly. Small multiples share axes/legend where configured; panels can combine different charts.

For repeated rows, choose the summary and uncertainty: mean with standard deviation, standard error or 95% interval, or median/range where supported. Supplied upper/lower bounds and plus/minus columns also work. Inspect whether error bars or a band communicate the intended quantity.

Click supported preview titles, axis labels and legend entries to edit. Set per-series labels, colors, markers, line styles and visibility. Legends can sit above, below, beside or inside a corner. Log axes require appropriate positive data; fixed ranges should not hide scientifically important observations.

## Use a paper theme

**Paper theme** controls the palette, typography, dimensions, line/marker weights, grids, backgrounds and stable category colors. Choose single- or double-column dimensions appropriate to the manuscript. Figure-specific overrides remain local to that design.

A theme update makes dependent figures stale so they can be regenerated consistently. Check grayscale/color-vision previews and printed label size. **Enlarge text** can help when labels would be too small at the estimated paper column width.

The preview is a useful design aid, but inspect the actual PDF at publication size. Typography can vary by export format; vector PDF uses the renderer's supported standard fonts.

## Generate tables from data

Studio tables offer booktabs, ruled or minimal styles, selected/reordered columns, numeric formatting, value ± error, spanning headers and grouping rules. Best/second-best emphasis can operate by row or column with explicit higher/lower-is-better choices.

Do not use automatic highlighting without checking the metric direction. A lower error rate and a higher accuracy score need different rules. For direct spreadsheet-style cell editing and formulas, use the separate [table editor](tables.md).

## Publish and insert

Publish/render the current recipe to produce SVG, vector PDF and PDF-rasterized PNG as selected. Figure outputs use stable paths under `figures/generated/`; table recipes produce standalone LaTeX under `tables/generated/`.

Insert with the available figure, full-width, wrap or input wrapper. A changed design must be published again before its new output is inserted. Booktabs insertion can add the needed package.

A manuscript build performs remote refresh, a consistent data snapshot, incremental asset generation and LaTeX compilation. Required generation failures preserve previous assets and stop the build. **Build with last assets** is an explicit stale fallback, not a fresh render. Externally modified generated files require a deliberate replace decision.

## Advanced reuse and agent help

Duplicate designs, group them by experiment/section, save reusable presets and copy a complete agent brief. Freeze assets when preserving a submission state; frozen items stay pinned.

The studio's agent composer can request a dataset or design change while leaving the studio visible. The assistant should inspect data, preserve the selected paper theme, preview the recipe, resolve warnings, then save and render. It should ask about analytical ambiguities such as which runs belong together rather than fabricate an answer.

Recipes use a deterministic local declarative renderer. They do not execute arbitrary imported plotting code. Keep raw data, transformation choices and provenance available so another author can reproduce the output.


---

# Spreadsheet table editor

Open **Write → Table editor** for a focused spreadsheet interface that publishes ordinary LaTeX. This is useful when you want to edit a presentation table directly rather than define a Figure Studio table recipe over a dataset.

## Create or import a sheet

Start blank, paste a rectangle from Excel/Sheets, import a workspace CSV/TSV, or copy a rendered Figure Studio table. Imports are independent editable copies. Editing them does not rewrite the original dataset or Studio recipe.

Choose the header row and enter descriptive column names. Keep units in headings where possible. A row labelled only “Ours” may need a caption explaining the model and evaluation setting.

## Edit and navigate cells

Click a cell and type to replace its value. Double-click, Enter or F2 edits the existing value. Arrow keys move, Shift extends a selection, and Tab advances. Drag across cells or select row/column headers for ranges. The formula bar edits the active cell.

Copy exports selected displayed values. Paste expands the grid as needed. Undo/redo keeps up to 50 edits in the current session. Add/remove rows or columns and use fill down for repeated formulas.

Sorting is supported for value-only tables. Formula tables cannot be sorted because moving dependent values without a complete spreadsheet dependency rewrite could change the result.

## Calculate with formulas

Supported expressions include arithmetic, parentheses, A1 references, absolute references, ranges, and `SUM`, `AVERAGE`, `MIN`, `MAX`, `COUNT`.

```text
=B2-C2
=(B2-C2)/C2
=AVERAGE(B2:B6)
=SUM(B2:D2)
=B2/$B$8
```

`$B$8` pins the row and column while relative references can adjust during fill. A leading apostrophe makes a leading equals sign literal text. Formulas never execute JavaScript.

Visible formula errors block publishing and export. Check referenced cells, division by zero and unsupported function names. This is not a full Excel engine; XLSX import and arbitrary spreadsheet functions are not supported.

## Format the publication table

Apply bold/italic to ranges, then set column alignment, decimal precision, percentages or best-value emphasis. **As entered** preserves leading zeros and trailing decimal places. Display precision does not round the underlying stored value.

Choose horizontal/minimal rules, caption and reference label. Inspect the publication preview and then compile the manuscript: final typography and width follow the paper. The editor does not automatically shrink a wide table to fit.

Use clear precision. Reporting six decimals from a noisy experiment rarely improves meaning, while an ID such as `0012` may need to remain text. Best-value highlighting is only appropriate when the comparison direction and experimental setup justify it.

## Save, publish and insert are separate

1. **Save table** stores the editable draft in `.versofold.tables.json`.
2. **Publish to paper** creates a named manuscript checkpoint and writes portable LaTeX under `tables/edited/table-<id>.tex`.
3. **Insert into manuscript** places a wrapper, caption, label and input reference at the current source cursor.
4. Recompile and inspect the PDF.

Later publications update the linked generated file. Merely saving a changed draft does not change the previously published manuscript output. External edits to the output, stale revisions or dirty buffers block overwriting until resolved.

## Export and limits

CSV/TSV downloads contain computed displayed values; TeX downloads contain escaped formatted source. Formulas remain in the editable draft, not the value export. Spreadsheet-looking literal strings are neutralized in CSV/TSV exports.

Current limits are 40 tables per paper, 300 rows and 26 columns per table, 2,000 characters per cell and 2 MB import text. Merged cells and arbitrary LaTeX-table parsing are not supported.

For reusable data-derived tables use [Figure Studio](figures.md). For manuscript values that need explicit update review use [Linked results](linked-results.md). For final fit use [Page layout](page-layout.md).


---

# Linked results

Linked results connects a manuscript number or statement to a named calculation over local data. When the data changes, you review what should change in the paper. It preserves ordinary LaTeX rather than inserting hidden result macros.

## Define a calculation

Open **Research → Linked results**. Choose a CSV, TSV or JSON-array dataset in the workspace and define a named result. Inspect the source columns and select any equality filters. Multiple filters are combined with AND.

Choose a single cell, mean, median, sum, minimum, maximum, sample standard deviation or row count. A single-cell calculation requires exactly one matching row. Missing or nonnumeric measurements cause visible errors rather than silently reducing the sample.

The preview shows matching rows, rounding, units and exact LaTeX output. Percentage formatting explicitly multiplies by 100: data stored as `0.87` becomes 87%, while data already stored as `87` should not use that conversion.

Example: select rows where `method` is `ours` and `dataset` is `test`, calculate the mean of `accuracy`, choose percentage display, and inspect the row count to confirm that the intended seeds were included.

## Connect a number or statement

Select the existing number in source or Visual, then choose **Link result**. A unique source passage can also be pasted into the workspace.

- A **numeric** connection can preview an exact old/new replacement.
- A **statement** connection creates a reminder to reconsider the interpretation when data changes.

Linking does not edit manuscript text. Keep the selection specific and verify the surrounding context. A number repeated many times needs a reliable anchor, not a guessed global replacement.

Generated tables are maintained through their figure/table workflow instead of arbitrary source replacement. Related Figure Studio items can be shown when they share datasets, including joins; shared input does not imply an identical calculation.

## Review changed data

The visible workspace checks sources and also offers **Refresh**. Changed connections are grouped by file and manuscript section. Inspect the changed input and resulting values before accepting.

Data changes still require acknowledgement when rounding leaves the printed value unchanged. An identical displayed mean can conceal changed sample size or variability. Statement connections require author review; the app does not rewrite a scientific conclusion automatically.

When the input of a statement changes, its card shows the linked value before and after. If the sentence compares values ("higher than", "lower than", "exceeds"…), the card says so, and when the sentence names another group from the same data (for example *Baseline* next to *Guided*) it computes that group with the same calculation and shows both numbers. If the sentence's direction no longer matches the numbers, the statement is marked **May no longer hold**: it is left out of **Select all**, and it can only be accepted after you tick **I checked this statement still holds**. The check reads plain comparative wording; it cannot judge claims such as "performs better", where the meaning depends on the metric, so read those yourself.

If the passage changed or became ambiguous, reconnect it from the editor. Do not force an update onto a different occurrence simply because it has the same number.

## Apply and verify updates

Select numeric changes to accept and statements to acknowledge. Acceptance requires a named manuscript checkpoint, rechecks source/data fingerprints and refuses dirty buffers or stale previews.

After successful updates, inspect related figures and tables separately. Refresh their assets if needed; frozen items stay pinned and externally edited outputs remain protected. Recompile explicitly to inspect the final PDF. Applying a result update and compiling the manuscript are separate operations.

History records the calculation, data fingerprint, row count, scope, displayed result and accepted passages. Its version link opens the checkpoint against the working draft. The latest 30 acceptance records remain in `.versofold.results.json` with definitions and anchors.

## Recovery and scope

If an operation is interrupted, reopening can recover from its saved journal. Recovery checks exact known states and refuses to overwrite newer external edits. Preserve the project and inspect the message rather than manually deleting the journal.

Current limits include 100 named results, 100 connections per result, 16 MB data sources and 2 MB manuscript files. Calculations use explicit equality scopes rather than arbitrary executable formulas. This feature does not infer scientific conclusions or scrape arbitrary PDF numbers.

Related: [Figure Studio](figures.md), [remote data](remote-data.md), [versions](versions.md).


---

# Remote data over SSH

Remote data brings reproducible inputs from a saved SSH host into a paper. Open **Remote connections** on Home to save a host, or **Research → Remote data** to browse and register inputs for the current workspace.

## Configure a connection

Save a descriptive name and SSH alias/host. VersoFold uses the system SSH client, including your SSH configuration, keys, agent and jump-host setup. Normal host verification remains enabled. It does not save SSH passwords or private keys.

Confirm the host works in your normal SSH environment. Bounded browsing/transfers require Python 3 on the remote host. If authentication or host verification fails, fix that connection before repeatedly requesting a build.

Connection profiles are personal, stored in `~/.versofold/remotes.json`. A manuscript keeps portable connection labels and provenance in `.versofold.remotes.json`; sharing a project does not share your private SSH identity.

## Browse and preview

Browse one remote directory at a time using breadcrumbs and filters. Text, CSV, TSV, JSON and log previews are bounded to 256 KB. A preview may show only the beginning of a larger file; do not infer the complete dataset from that excerpt.

Browsing is read-only on the host. Choose a stable output file or directory, ideally one that is not being written by an active experiment while you fetch it. Transfers compare fingerprints to detect changes during copying.

## Choose the right import mode

| Action | Meaning |
| --- | --- |
| Download snapshot | Keep a fixed local copy of the selected state. |
| Use in figure / Use in table | Register an input refreshed by the build dependency workflow. |
| Sync folder | Maintain a one-way local copy on demand or at a selected interval. |
| Freeze | Pin a registered source for a submission or reproducibility checkpoint. |

Use include/exclude patterns to narrow folder synchronization. Exclude large checkpoints when only final CSV metrics are needed. Do not assume a one-way sync is a bidirectional collaboration mechanism.

## Understand freshness and conflicts

Downloads are staged and published only after the remote fingerprint matches the pre-transfer state. Interrupted transfers preserve the last complete local copy. Local edits, remote deletions and changed remote content surface decisions instead of silently discarding your work.

A PDF build refreshes active fetch-on-build sources first. If the host cannot be checked, the build stops. **Build with cached data** explicitly uses the last complete copy and marks the result stale; it is unavailable without a complete cache.

Inspect the provenance and freshness indicator before interpreting the resulting plot. A successful LaTeX pass cannot prove that unreachable remote experiments were refreshed.

## Freeze and clean up

Freeze a source before a submission when you need the exact inputs retained. Frozen sources are pinned rather than refreshed opportunistically. Record which experiment/output they represent and preserve a manuscript version with the corresponding PDF.

Clearing cached files is disabled while frozen and refuses to remove locally modified data. Removing the registration leaves downloaded files in place. If you intend to remove both a dependency and a copy, inspect both actions rather than assuming deregistration deletes files.

## Work with figures and agents

Figure/table registrations provide stable local dependencies and provenance for Figure Studio. Recipes consume completed local copies rather than relying on unexplained machine-specific remote paths.

Remote execution is a separate capability from browsing and downloading. An agent needs the appropriate run grant, configured workspace-to-host binding, declared remote folder and executable allow-list to run a command. Asking it to plot a downloaded CSV does not imply permission to launch experiments on the server.

Related: [Figure Studio](figures.md), [linked results](linked-results.md), [compilation](builds-pdf.md).


---

# Page layout & budgets

Use word/page budgets to monitor length, then the Page layout workbench to inspect actual rendered pages and supported float adjustments. These are complementary tools: a shorter source is not necessarily a shorter PDF.

## Set a page budget

Click the word/page count in the status bar. Configure each applicable limit separately:

| Segment | What it measures |
| --- | --- |
| Before references | Content before the bibliography, often the venue's body limit. |
| References | The bibliography segment. |
| Appendix | Appendix/supplementary pages detected in the document. |
| Whole document | Every PDF page. |

An empty limit means unlimited. Segments sharing a boundary page both count that page. Headings and source structure help locate boundaries; if a segment cannot be identified, the app reports it as unverified/not found rather than declaring compliance.

Measurements come from the last compiled PDF. Compile after edits before trusting them. A selected submission venue can override corresponding budget segments for its selected document; clearing that target restores the original limits.

## Understand word estimates

The workspace word counter follows common includes and excludes the preamble, math, tables, verbatim and markup such as labels/citation keys. Per-section counts help decide where to cut or expand. Custom macros and unusual structures can affect estimates.

A venue may count abstract words differently. Use its actual instructions and inspect the submitted document; a local estimate is not an authoritative portal count.

When over budget, identify which segment exceeds its limit. Prefer targeted editorial changes. Do not disguise overflow by shrinking fonts, margins or bibliography style against the venue's requirements.

## Inspect rendered pages

Open **Write → Page layout** or the PDF toolbar's page-layout control. The PDF entry selects the page being read. **Compile & inspect** saves current edits and builds the selected main document.

Use the page map to select a preview. **Open space** highlights broad empty bands. Visual footprint measures coarse ink occupancy, including text and graphics; it is not an exact whitespace percentage or a font/margin compliance certificate. Intentional gaps can be highlighted too.

Read compiler warnings beside the preview. Overfull/underfull boxes and float messages can point to source locations. Unlabelled floats may require **Show all pages** because labelled output provides more reliable page mapping.

## Adjust a figure or table

1. Select a supported float in the workbench.
2. Choose a conventional placement preference. For a single normally sized graphic, adjust width where offered.
3. **Review adjustment** shows the exact source before and after.
4. **Apply & compare** creates a named version, changes the source, recompiles and displays original/current PDFs.
5. Inspect legibility, neighboring floats, page count and budget status.

Float placement is a request to LaTeX, not a guaranteed coordinate. Generic controls intentionally avoid rewriting complex multi-image layouts, explicit physical sizes, custom `H` positioning or height/scale combinations. Follow the source link for those cases.

The workbench preserves templates, margins, fonts and global spacing. Supported width changes range from 25–100% of the existing line/text/column width basis. A smaller figure can fit while becoming unreadable, so check axis labels and captions.

## Undo and compare accurately

**Undo adjustment** restores the latest changed file only if it still exactly matches the applied state, then recompiles. If newer changes exist, use the named checkpoint in Versions to inspect a safe recovery.

A failed compile retains the adjustment and its undo controls. The old PDF is marked as needing refresh. Side-by-side comparison pairs pages by number; reflow may move a paragraph to another page, so it is not a semantic or pixel-aligned diff.

Inspection is bounded to PDFs up to 20 MB and 80 pages, up to 100 source files under 1 MB each, and the first 300 supported floats. Session previews/quick-undo may disappear after restart, while named versions persist.

Related: [compilation](builds-pdf.md), [submission rehearsal](submission.md), [LaTeX floats](latex-advanced.md#figures-and-float-placement).


---

# Deadlines & rebuttals

**Review → Deadlines & reviews** tracks due dates, to-dos and reviewer points. The rebuttal itself is written in the **Response view**, beside the LaTeX, when the paper is in the Rebuttal phase (see [Paper phases](paper-phases.md)).

## Track exact deadlines

Create a deadline with a type such as abstract, submission, rebuttal, camera-ready, revision or internal. Add the date and, when known, time and zone. AoE means UTC−12. A zoned deadline without an explicit time uses the end of that date in the selected zone.

The countdown shows days, then more precise timing near the deadline; local time is displayed alongside the stated zone where available. Mark a deadline **Met** to remove it from active counting without deleting the record.

Always record the actual edition/track and deadline source when organizing a submission. An abstract registration date and full-paper date are different obligations. Unconfirmed venue dates should remain unconfirmed.

## Keep a small actionable task list

Create to-dos with optional due dates and file links. Click a file chip to open the relevant source. Done items can be folded away.

When the tracker contains work, a status-bar chip shows the nearest deadline or the open reviewer points. Click it to open the corner dock, which summarizes the nearest deadline, open/overdue tasks and reviewer progress; expand it to tick tasks or open the full tracker. Closing the dock returns the reminder to the chip; it does not delete the tasks. The venue you chose in Submission rehearsal appears among the deadlines with its own date and time zone.

Use the manuscript board for section-level planning and research plans for ordered dependencies. A short to-do list is better suited to discrete remaining actions.

## Import the reviews

**Import reviews** (in the Reviews tab of the side panel, or at the top of the Response view) takes the whole OpenReview page of your paper: select all (**⌘A**), copy, and paste. VersoFold finds each official review, the reviewer's rating and confidence, and splits it into labelled points: **W1** for weaknesses, **Q1** for questions, **L1** for limitations, **C1** for other comments. The preview shows what will be added; untick a point to leave it out, or switch its severity between major and minor. The reviewers' text is kept word for word.

Paste the page again later in the discussion: what is already imported is recognised and skipped, a changed rating is updated, and a reviewer's new comments become **follow-ups** of the current discussion round, threaded under the point they reply to. Your own replies on the page are left out.

A review that is not from OpenReview (an email, a journal's report) can be pasted on its own; it is split into points the same way. When a page is unusual, **Tidy with the agent** asks the agent to read the paste and import it in the same format, still quoting the reviewers exactly.

The paste is read on your computer. Nothing is sent anywhere unless you ask the agent to tidy it.

## Write the response

The Response view shows each reviewer comment as a card with your answer under it, in order:

- **General response**, the message to all reviewers (a summary of the main changes, for instance).
- For each reviewer: an optional **opening note**, then each point with your answer, then their follow-ups.

Click under a card and write. Answers are Markdown, `$…$` maths included. The response is the file `rebuttal/response.md` in the paper folder, so it behaves like the LaTeX: coauthors write in it at the same time and you see their cursors, tracked changes and history work, and an agent can write in it too. The cards themselves are read-only, so the reviewers' text cannot be edited by accident.

The formatting bar above the answers writes the Markdown OpenReview reads: bold (**⌘B**), italic (**⌘I**), inline code (**⌘E**), a link (**⇧⌘K**), bulleted and numbered lists (**⇧⌘8**, **⇧⌘7**), a quote (**⇧⌘.**), an inline equation `$…$` (**Control-M** on a Mac, **Ctrl+M** elsewhere) and a display equation, `$$` on lines of their own (**Control-Shift-M**, or **Ctrl+Shift+M**). Each wraps the selection or opens at the caret, and comes off when used again. The **α** menu inserts common LaTeX at the caret: fractions, sub- and superscripts, Greek letters, `\mathbb`, `\operatorname{argmax}`, `\mathcal{O}(\cdot)`. While the caret is in an equation, it is shown rendered just above it, or with the LaTeX error if it does not compile. Enter in a list item starts the next one.

Each card has:

- **Status** (Open, Drafted, Addressed, Declined) and **Decision** (Revise the paper, Clarify, Disagree, No change). Writing an answer marks the point Drafted.
- **Assign**, to give the point to a coauthor. **Mine** in the toolbar shows only the points assigned to you; **Unanswered** shows the ones still empty.
- **Draft with agent**: the agent reads the reviews and the paper and writes that one answer, without touching the others. With no model connected, the request waits in the agent's message box. Read and edit what the agent wrote; the answer is yours to send.
- **Link a passage**: tie the point to the manuscript passage that answers it, so Camera-ready can check that the promised change is there.

The reviewer's header counts the characters of the whole reply to that reviewer against the reply limit (5,000 by default, as on OpenReview). The count turns amber when a reply is over; nothing is cut. Set the limit and the discussion round in the phase menu (**Rebuttal or revision**).

The left sidebar's **Outline** tab lists the reviewers and their points with their state; click one to go to it.

The Response view can have a window of its own, like the PDF or the LaTeX: drag its **Response** button out of the toolbar, or use the pop-out button at the end of its toolbar. In that window, **Draft with agent** goes to the main window's agent, and the main window's Outline scrolls the Response window. See [Windows and layouts](navigation.md).

## Revise the paper, with the changes in colour

In Rebuttal, edits since the submitted version show in colour: insertions and deletions in the LaTeX, and the changed words highlighted on the PDF. The **Changes** chip in the PDF toolbar switches between **Off**, **Highlight**, and **Marked PDF**, which builds a latexdiff version of the paper with every insertion and deletion marked, ready to download for a journal. The submitted version is the one saved by **Mark as submitted**; choose another under **Changes are measured from** in the phase menu.

Make the manuscript change first when one is required, then describe what changed and where. A draft answer is not proof that the edit exists.

## Copy for OpenReview, or export the letter

**Copy for OpenReview** copies, as Markdown ready to paste:

- the **General response**;
- the **reply to each reviewer**: the opening note and every answer, each starting with the point's label;
- in later rounds, the **round reply** to a reviewer: only the answers to that round's follow-ups.

For a journal revision (choose **Journal revision** in the phase menu), the toolbar offers **Download letter** instead: the whole response letter as Markdown, LaTeX or HTML, with the reviewers' comments quoted.

## Rebuttal details

The gear in the Response view opens the rebuttal details: each point's request and rationale, linked passages and checks, overlaps between reviewers, and **Saved exports**, which freeze the response with a manuscript version so you can retrieve exactly what was sent after later edits. VersoFold never submits anything to a venue.

Related: [paper phases](paper-phases.md), [comments and review](comments-review.md), [versions](versions.md), [submission rehearsal](submission.md).


---

# Submission rehearsal & arXiv

Submission rehearsal checks a particular paper against a selected venue's recorded requirements. The arXiv tool builds and verifies a source package. Neither action submits the manuscript to an external service.

## Research and select a venue

Open **Publish → Submission rehearsal**. **Find venues with agent** prepares a research request; add field, timeline, location or publication preferences, choose a model and send it.

Venue cards record edition/track, fit, event details, deadlines and requirements. Compare up to three candidates and inspect linked sources. Agent-authored requirements retain quotations and retrieval provenance; a quotation does not establish that every condition was captured. Confirm the official instructions for the correct edition.

Choose the main document and select a target. VersoFold saves the current requirement set. Later edits to the candidate are flagged rather than silently changing the selected target; review and select again to adopt them.

Page requirements override the corresponding budget segments for that document. Other segments retain existing limits. Selecting a venue does not reformat your source or turn a draft into an anonymous submission automatically.

## Run a rehearsal

**Build & run rehearsal** saves edits, compiles the selected root and checks recorded output and source. It can inspect build/citation/reference warnings, measured page limits, a standard abstract's estimated length, TODOs, reviewer points and drafting placeholders.

Other requirements, including anonymity, figure quality, formatting and supplements, remain explicit review items. Automatic hints cannot establish scientific completeness or full venue compliance.

For each author-reviewed item, record what you inspected. An anonymity check should include visible author details, acknowledgments, links, supplementary content and PDF metadata as applicable to the venue's instructions.

## Keep the report current

Changing sources, PDF bytes, settings, target requirements or outstanding-work counts makes the report stale. Rerun the rehearsal before making current judgments or saving a final checkpoint. A new rehearsal preserves earlier judgments only when the inspected state remains unchanged.

Download the Markdown report or save a named manuscript checkpoint. Open its version in History to connect the readiness decision to the exact source state.

A green technical check means that check passed. It does not guarantee acceptance by a submission portal, satisfy unspecified venue rules or establish that the research is correct.

## Prepare an arXiv source package

Open **Publish → Package for arXiv**. The tool starts from the chosen document and walks its reachable sources, figures and local style/class files. Review the planned file list: unrelated notes, other roots and app metadata should not become submission contents accidentally.

When the paper has a preprint edition (see [Preprint & editions](editions.md)), the package is built from the preprint: the authors named, the appendix in, and every edition mark resolved in the copy, so text meant only for the submission or the supplementary material does not reach arXiv. The panel says which edition it packages; open it from the preprint's card in **Preprint & editions** to package that edition explicitly.

The available transformations operate on a copy:

- Carry or inline the compiled `.bbl`, or retain bibliography source when the selected packaging strategy calls for it.
- Remove supported review/draft options and line-numbering commands where selected.
- Convert SVG figures to PDF using an available supported converter.
- Add the selected PDF-output setup where appropriate.
- Optionally flatten standard includes into a single source.
- Optionally strip comments while preserving important paragraph/newline behavior.

Compile first if the package needs a `.bbl` that does not yet exist. A missing converter or missing referenced asset needs to be resolved before a valid package can be produced.

## Verify the actual bundle

Inspect the transformation plan, build the bundle and read its recorded verification result. The app can compile the prepared package with bibliography generation disabled to check the selected bundled-bibliography strategy.

Flattening is intentionally conservative around unresolved inputs, comments, literal environments and `\includeonly`. Comment removal and template-option changes can affect rendering, so inspect the resulting PDF as well as the source archive.

Use current arXiv/venue instructions for the final upload requirements. The local packaging tool verifies its own selected build strategy; it does not contact the submission portal or guarantee that the service accepts every dependency.

## Preserve a reproducible submission

Freeze necessary remote inputs and generated assets, compile, save the named version with its matching PDF, export the source package and retain the rehearsal report. Record the exact entry/root and engine. A label such as “camera ready” does not itself change anonymity or class options.

Related: [page budgets](page-layout.md), [remote data](remote-data.md), [versions](versions.md), [rebuttals](deadlines-rebuttal.md).


---

# Make a preprint

A preprint is your paper as you post it on arXiv: the authors named, the acknowledgements in, no page limit, the appendix included. In VersoFold it is not a copy of the paper. It is an **edition** built from the same LaTeX as the submission, so a typo fixed once is fixed in both, and only the few passages that differ are marked. You can make it at any phase; most people do around submission.

A preprint is not a phase. The phase says where the paper is in its life (Submission, Rebuttal, Camera-ready…) and there is one at a time; the preprint is one of the forms the paper takes, alongside the submission. See [Phases and editions](paper-phases.md#phases-and-editions).

Some venues limit preprints or publicity during review. Check your venue's policy before you post.

## 1. Create it

1. Click the button next to the phase, under the paper's title (it says **Paper ▾** or **Submission ▾**). With only the paper so far, it offers **Preprint** or **Supplementary material**: choose **Preprint**. (Also in **Publish → Preprint & editions**, and in the phase menu from Submission on.)
2. Set the options:
   - **The venue style's preprint mode** (on by default): the preprint loads the style as the venue asks for preprints, such as `\usepackage[preprint]{neurips_2026}`; the submission keeps the review mode.
   - **Authors**: when the paper's author block is anonymous, write the named one here. When the block already names you and the style hides it for review, nothing needs to change; with a style that prints it as it is, the submission gets "Anonymous" in its place.
   - **Acknowledgements**: printed only once the authors are named.
   - **Links**: anonymised links (such as `anonymous.4open.science`) are listed so you can give their real addresses.
3. **Preview the changes** shows every change to your LaTeX, before and after, with its file and line. Nothing is written yet. **Create** makes exactly that. A saved version is taken first, so you can go back.

VersoFold adds a short block of switches at the top of the main file and a two-line `main-preprint.tex` beside it. Your paper still builds on its own, on Overleaf too.

## 2. Look at it

Choose **Preprint** in the same button:

- **The PDF** shows the preprint, built for you; it is rebuilt after your edits while **Auto** is on.
- **The LaTeX** shows the preprint's text. It is the same file as before: what only the submission prints folds into a one-line placeholder (click to see it), and the markers step aside. Editing here edits the shared source, so your change reaches the submission too, unless the text is marked.

**Colour the differences** in the button's menu tints what the preprint adds: the names, the acknowledgements, the appendix. **Compare side by side** puts the submission's PDF and the preprint's next to each other, with what each one has that the other does not in colour. **Paper** takes you back.

## 3. Mark what differs

Select text in the LaTeX and choose **Edition** in the toolbar over the selection:

- **Only in the preprint**: a longer discussion, an extra experiment, the link to your code.
- **Not in the preprint**: text only the anonymous submission needs.
- **Anonymous wording…**: one phrase in two versions, such as "Anonymous et al. (2025)" in the submission and "Smith et al. (2025)" in the preprint.

The marks are plain LaTeX (`\ifpreprint … \fi`, `\anon{…}{…}`). Click a mark's label to remove it. See [How the source is marked](editions.md#how-the-source-is-marked).

## 4. Check it

**Run the checks** in **Preprint & editions** reads the PDFs as last built: the submission names no author (no names, affiliations, e-mail domains or links that only the preprint has), the preprint names its authors, and every mark is closed. Failed checks come first, with the page where a name was found.

## 5. Post it, then update it

- **arXiv package** on the preprint's card builds the source arXiv asks for, from the preprint: text marked for other editions is left out of the package, so nothing hidden becomes public. See [Prepare an arXiv source package](submission.md#prepare-an-arxiv-source-package).
- Once it is online, **Mark as posted on arXiv…** records the version (v1), with its arXiv identifier.
- After the reviews and your revisions, **What changed since v1** lists the sections that changed, and **Draft the arXiv comment with the agent** writes the comment for v2.
- In **Camera-ready**, the checklist names the authors in every edition in one click and reminds you to update the preprint with the final version.

For the supplementary material and a journal version, and every detail of the marks, see [Preprint & editions](editions.md).

Related: [paper phases](paper-phases.md), [submission rehearsal](submission.md), [rebuttals](deadlines-rebuttal.md).


---

# Preprint & editions

A paper often goes out in several forms: the anonymous submission, a named preprint on arXiv, the appendix as a separate supplementary PDF, and later perhaps a journal version. VersoFold builds them all from one LaTeX source. Nothing is copied, so the editions never drift apart: a typo fixed once is fixed in every PDF. For the common case, step by step, see [Make a preprint](preprint.md); for how editions differ from the paper's phase, see [Phases and editions](paper-phases.md#phases-and-editions).

Next to the paper's phase, under its title, the edition switcher says which edition you are looking at: **Paper ▾** at first. With only the paper so far, clicking it offers to make a **Preprint** or **Supplementary material**. The editions themselves are in **Publish → Preprint & editions**. You can also type **Editions** in **⌘K**, use **Preprint & editions…** in the phase menu (from Submission on) or in the switcher's menu, or start from the **Checklist** tab.

## The editions

| Edition | What it is |
| --- | --- |
| Submission | The paper itself, built from its main file. Its name follows the phase: Paper, Submission or Camera-ready. |
| Preprint | The same paper as you post it on arXiv: the authors named, no page limit, the appendix included, and the venue style in its preprint mode when the style has one. |
| Supplementary material | A separate PDF with the appendix only. It refers to the paper's figure and section numbers and keeps the submission's anonymity. |
| Copy as a new edition | A standalone copy, for a journal extension for instance. It is made once and then changes on its own; VersoFold lists how it differs from the conference version. |

Each card in the dialog shows the edition's entry file, when its PDF was last built, and **View**, **Build** and **Download**. **View** shows that edition, as the switcher does. The bin button deletes an edition: VersoFold stops building it and removes its small entry file. The marks in the paper stay, so the other editions are unchanged. A copy's own files always stay in the folder.

## Create an edition

Under **New edition**, choose **Preprint**, **Supplementary material** or **Copy as a new edition**, set its options, then **Preview the changes**. Nothing is written yet: the preview lists every change to the paper as a before and after, with the file and line it is in, the new files the edition adds, and anything to check yourself, each with a link to the place in the source. **Create** makes exactly what the preview showed. If the paper changed in the meantime, VersoFold shows the new preview instead and asks you to check it again.

The options:

- **Preprint.** Use the venue style's preprint mode; restore the real code and data links in place of anonymised ones (links VersoFold cannot match are listed in the preview); the named author block, when the paper's own is anonymous; acknowledgements that only the preprint prints.
- **Supplementary material.** Move the appendix out of the submitted paper; number its sections, figures and equations S1, S2… or continue the paper's numbering; refer to the paper's numbers; give it its own title and its own bibliography.
- **Copy as a new edition.** Its name, the edition it starts from (the submission, or the preprint when there is one) and where its main file goes.

## How the source is marked

The main file starts with a short block VersoFold writes. It defines one switch per edition, and each edition other than the submission has an entry file beside the main file (`paper-preprint.tex`, say) that names the edition and inputs the main file. Text that belongs to some editions only is wrapped in plain TeX conditionals, so the paper still builds anywhere, on Overleaf or on arXiv, and agents read it like any other source.

| In the source | Who prints it |
| --- | --- |
| `\ifpreprint … \fi` | The preprint only. |
| `\ifpreprint … \else … \fi` | The preprint prints the first part, the other editions the second. |
| `\ifsupplementary … \fi` | The supplementary material only. |
| `\ifsupplementary\else … \fi` | Everything but the supplementary material: the paper's body. |
| `\ifsubmission … \fi` | The submitted paper only. |
| `\ifanonymous … \else … \fi` | The anonymous editions, then the named ones. |
| `\anon{anonymous}{named}` | The same, inside a sentence. |

You can write these by hand; the editor helps with both reading and writing them.

Agents read the marks like any other LaTeX. Ask one to keep a sentence out of the preprint, to name the authors only once they are named, or to build an edition and run the checks: it marks the text the same way, and creating an edition follows the same approval setting as any other change to the paper.

## Marks in the editor

In the LaTeX editor, the lines of a marked passage get a coloured band, one colour per edition (faded for text an edition leaves out), and the markers themselves are dimmed. A small label after `\ifpreprint` and after `\else` says who reads what follows, such as **Preprint only** or **Not in the preprint**; hover it to see which editions print the text. A mark inside a sentence tints its words instead of the lines. `\anon{…}{…}` is underlined, and hovering it shows both wordings. A marker that is never closed with `\fi` is underlined as a warning, and the dialog lists it at the top with a link to its line.

To mark text, select it and choose the **Edition** button in the toolbar that appears over the selection:

- **Only in the preprint**, **Not in the preprint**, **Only in the supplementary material**, **Not in the supplementary material**, **Only in the submission**, **Only once the authors are named** or **Only while anonymous**. Whole lines get their markers on lines of their own; part of a line gets them inline, spaced so that no edition loses or doubles a space.
- **Anonymous wording…** keeps the selection as what the anonymous editions print and asks for what the named ones print instead.

To remove a mark, click its label in the editor, or select text inside it and open **Edition**. A mark with two versions offers to keep either one everywhere; a mark with one offers to keep the text everywhere or to delete it with its mark. Marking and removing are ordinary edits: **⌘Z** undoes them, co-authors see them live, and **Track changes** records them. Until the paper has the editions block, the menu offers **Set up the preprint…** instead.

These bands and labels are the **All editions** view (see below), where every edition's text is on screen with its marks. The Visual editor always shows every edition's text: the markers are small tags where they stand, and `\anon` shows the wording the paper prints now. Click a tag to edit the mark as LaTeX.

## Switch the view

The switcher next to the phase chooses what the PDF and the LaTeX below show. Its menu lists every edition with its build (when it was built, building, not built yet or failed), with **Build now** and **Download** beside each; **All editions** is at the bottom. Each window remembers its own view.

- **The PDF** shows the chosen edition's PDF, built first if it has none. While **Auto** is on, it is rebuilt once your edits pause, after the main PDF. When the view is not the paper, a small tag in the PDF toolbar names it; click the tag to open the switcher.
- **The LaTeX** shows the chosen edition's text. It is still the one source every edition shares, seen through that edition. Text the edition leaves out folds into a one-line placeholder, such as **Not in the preprint · 4 lines**; click it to show that text in place, and click **hide** on it to fold it again. The markers (`\ifpreprint`, `\else`, `\fi`) step aside, and of `\anon{…}{…}` you see the wording this edition prints, with a tiny chip for the other one. Line numbers skip the folded lines. The block of edition switches at the top of the main file folds into one line too. The **Paper** view does the same for the paper: what only the preprint or the supplement prints is folded.
- **Editing in a view** changes the shared source, so it reaches every edition unless the text is marked; when the view is not the paper, the tab bar says so with a small tag, such as **Preprint view**. Typing and deleting never touch folded text or hidden markers: a selection across them changes only what is shown, and Backspace next to them leaves them in place. A search hit, or a jump to a line, inside folded text shows it.
- **All editions** shows every edition's text with the bands and labels described above, for when you want to see and edit the marks themselves.

A copy has its own LaTeX: choosing it opens its main file.

## Colour the differences

**Colour the differences** in the switcher's menu colours what the edition on screen prints and the edition it is compared with does not: the paper's anonymous author block when you look at the paper, the named authors, acknowledgements and appendix when you look at the preprint. It colours the LaTeX (a tint in the edition's colour) and the PDF (the words the other PDF does not have, read from both PDFs, so text that only moved to another page is not coloured). The edition compared with is the paper, or the preprint when you look at the paper; choose another under **Compare side by side … with**. The switch is remembered with the view.

While it is on, these colours take the place of the changes since submission on that PDF; switch it off to see those again. Changes since submission (the highlights on the PDF and the marked PDF) always belong to the main edition.

## Compare side by side

**Compare side by side** in the switcher's menu shows the two PDFs next to each other, over the LaTeX and the PDF: the edition compared with on the left, the one on screen on the right. They scroll together. With the colours on, the right PDF shows what its edition adds and the left one what it leaves out, in a muted red (an "Anonymous" the preprint replaces, say). The bar above names both and lets you choose the edition on the left, swap the two, switch the colours, and leave (or press Escape). Your layout underneath stays as it was.

## Anonymity

The submission card says who is named. **Anonymous until camera-ready** hides the authors in the submission and the supplementary material while the preprint names them. **Named in every edition** names them everywhere, as the camera-ready version should. In the Camera-ready phase, the checklist checks this as **Name the authors in every edition** and fixes it in one click.

## Checks

**Run the checks** at the bottom of the dialog reads the editions' PDFs as last built: the submission and the supplementary material name no author, the preprint names them, and every mark is closed. Failed checks come first, with what was found and on which page.

## The preprint on arXiv

On the preprint's card, **arXiv package** opens the [arXiv tool](submission.md#prepare-an-arxiv-source-package) with the preprint: its marks are resolved in the package, so text meant for other editions does not reach arXiv. Once it is online, **Mark as posted on arXiv…** records the version, with its arXiv identifier if you give one. For the next version, **What changed since v1** lists the sections that changed and how many words were added or removed, and **Draft the arXiv comment with the agent** asks the agent for the comment that goes with the new version. In the Camera-ready phase, the checklist reminds you to update the preprint.

## A journal version

A copy changes on its own. On its card, **Differences from the conference version** lists the sections it added, removed or changed, and **Draft the list with the agent** asks the agent for the summary of differences journals ask for. See also [Paper phases](paper-phases.md).


---

# Sharing, Word, Git & Overleaf

Choose a collaboration method according to what the other person needs: a live workspace, an offline review copy, tracked Word edits, a source archive or repository synchronization. Check exactly what is included before sending an artifact.

## Share a live workspace

Open **Share** and choose permissions. Read-only, Comment, Suggest edits and Full editing grant progressively more capability. Source visibility, editable-file scope, creation, compilation and history can have additional controls; inspect the current invitation settings.

On a suggest link a collaborator edits the live files, but every edit they make is a tracked change: it is in the file, and shown to everyone in their colour, until someone with write access accepts or rejects it. Full editing writes authorized files directly (and tracks changes when that person switches **Track changes** on). Changing access or rotating/revoking a link affects future access; host/account administration remains private.

Local network sharing uses a separate review listener. Public-link sharing opens a Cloudflare tunnel from your computer to that review listener. The link works only while your computer is awake and VersoFold is running: closing the lid, letting the Mac sleep, shutting down or quitting VersoFold closes it for everyone, and opening it again gives a new address. Closing the link or stopping sharing shuts it at once. Treat it as a temporary link, not hosting; for a workspace that stays up, see hosted workspaces.

Share the generated invitation, not the owner's local editor address. A workspace invitation is different from a reference-library grant or an external-agent MCP connection.

## Edit together, live

Everyone with a file open is in the same document, as in Overleaf. Typing appears in the other editors as it happens, in the LaTeX and Visual views alike, and each collaborator's caret and selection show in their colour, labelled with their name while they type or when you point at it. Nobody's work waits for anyone else's save, and two people typing in one paragraph both keep what they wrote.

The header shows a chip for each person in the workspace. Point at one for their name and the file they are in; click it to go to their cursor, in the LaTeX or, during a rebuttal, in the Response view. Files others have open carry a small dot in their colour in the file tree and on the tab. Your own chip, on the right, sets the name and colour everyone sees on your cursor; so does **Settings → Your name & colour**, with a preview. A guest's name is also the one on their comments. Both are remembered on that device.

**Saving.** The status line reads **Saving…** while the host has not yet written your latest typing, and **All changes saved** once it has: saved means the host wrote it to the manuscript file, not that your browser has it. Typing is written a moment after it arrives, never once per keystroke. **⌘S** waits until everything you typed is on disk. Compiling first writes everybody's typing, so the PDF shows what the whole team sees.

**Offline.** If the connection drops, you keep typing; the status line says **Offline · edits kept here** and the work is also kept on the device. When the connection returns, your edits are sent and merged with what others did meanwhile. If the host restarted in between, your unsaved typing is added to its current version once, never twice.

**Undo** is per person: **⌘Z** undoes your own edits, never a collaborator's typing that landed in between. **⇧⌘Z** redoes.

**Agents and other programs.** An agent's edit, a save from another editor, a restore or a replace across files reaches every open editor straight away, merged with whatever is being typed. An agent's edit arrives as a tracked change in its name; other outside writes have their lines marked as written from outside.

**Tracked changes.** With **Track changes** on (**⌘ShiftE**), your edits are recorded in your colour for the others to accept or reject, and everyone sees the same markup live. The **Review** tab lists what is pending. See [tracked changes](comments-review.md#track-changes).

**Renames and deletes.** Renaming a file others have open moves their tab to the new name, with their typing. Deleting it closes the live document; whoever had it open keeps their text as an unsaved buffer, and **⌘S** writes it back.

## What each level can do

| Level | In a shared workspace |
|---|---|
| Read only | Follow the files live as others type, with their cursors; browse the file tree, outline and search; read the PDF and the threads; figures and bibliography; version history when it is shared. |
| Comment | All of that, and start, answer and resolve threads. |
| Suggest edits | All of that, and edit the files in scope live, as tracked changes only: everything they type or delete is recorded in their name for someone with write access to accept or reject. They can withdraw (reject) their own changes, not accept anything. Files out of scope stay a live read-only view. |
| Full editing | All of that, and type into the files in scope live with everyone else, tracking their changes when they choose, and accept or reject anyone's tracked changes in those files; create files where allowed; rename and delete files in scope (whole folders only with access to every file); compile and read the build log when compiling is allowed; replace across the files in scope; save named versions when history is shared. |

Whatever the level, the owner's settings, credentials, agent accounts, external agents, SSH connections, share and tunnel controls, and the workspace library stay with the owner. Files outside a link's scope open read-only, and hidden project records are never shared.

## Turn live editing off

Live co-editing is on for every workspace, a single local user included. To go back to whole-file saving with conflict checks for one workspace, add `"collaboration": { "liveEditing": false }` to its `.versofold.json`, then reopen the workspace or restart the service; for a whole service, start it with `VERSOFOLD_LIVE_EDITING=0`. Editors then save each file as a whole about half a second after typing stops and show a conflict when someone else changed it meanwhile. Files already open reload that way in place.

## Hosted and desktop collaboration

Hosted mode runs a service bound to one workspace with authenticated invitations. Desktop can open supported workspace links and preserve connection entries. Role and invitation grants govern what a collaborator can access, and live editing works the same way there: the service holds the shared documents, so collaborators keep editing together while the owner's laptop is closed. Each saved connection opens its window at the same local address every time, so that window keeps its layout.

An offline desktop/review copy is not a live connection to the host. Inspect whether work is local, connected, pending import or awaiting review before assuming others have received changes. Back up the host's complete workspace and data according to your deployment setup.

The repository's operator documentation covers service installation and hosting configuration. The user-facing workflow remains: create an invitation, inspect its scope, open it on the collaborator's device, and review proposed changes deliberately.

## Send an offline review file

**Share → Save review file** exports a self-contained HTML reader with the PDF, selected review content and permitted source where configured. The recipient opens it without a running VersoFold server.

The export follows its review level. Comment mode enables discussions; source-editing levels can include the document's relevant source files with locked files marked accordingly. The offline source editor supports ordinary navigation and editing, but it does not provide a full local TeX installation.

The reviewer uses **Save my work** to return a JSON response, or its copy option. Use **Read their comments back** to import it. Imported edits remain proposals for author review even if the file claims an editing permission; a returned file does not automatically overwrite the manuscript. They wait in **Review → Compare with approved version**. With live editing switched off, a suggest link works the same way: its edits are kept aside as a proposal instead of tracked changes.

## Exchange Word edits and PDF annotations

Open **Publish → Word round trip** to export a DOCX and inspect returned edits through the app's import workflow. Keep the original export and source baseline so returned changes can be interpreted. LaTeX and Word have different document models; inspect equations, tables, citations and complex formatting after any round trip.

**Equations** go out as real Word equations: fractions, scripts, roots, sums and integrals with their limits, Greek and the usual symbols, accents, `\mathbf`-style alphabets, `\text`, `\left…\right`, matrices, `cases`, `\operatorname` and functions such as `\sin`. The document's own `\newcommand` and `\DeclareMathOperator` macros are expanded first. An `align` keeps its lines lined up at `&`. A labelled equation carries the number the last build gave it, and `\tag` prints as written; a line with neither has no number, never a guessed one. An equation VersoFold cannot convert exactly, such as one using an unknown macro or `\intertext`, stays as its LaTeX text. An equation is generated from the source: an edit inside one, tracked or not, comes back as a note that points at its LaTeX, and is never written into the `.tex`.

**Numbers come from the last build.** Citation, figure, table and equation numbers, and the reference list, are what the last compile printed. Before exporting, the panel checks that build against the manuscript's sources. When something changed since, it names what and offers **Compile first, then export**, which builds and then writes the document, or **Export anyway**, whose numbers may be out of date. If the document has never been built, citations and cross-references show their keys.

Review tracked-change results before applying them and compile the resulting manuscript. Ask for **Track Changes** in Word. Tables come back cell by cell; an edit on generated text, such as a citation number or a caption's "Figure 2", is reported rather than written into a `\cite` key.

**Edits made with Track Changes off.** VersoFold compares that paragraph word by word with what it exported. Each changed word that sits on manuscript text is offered as **Propose this rewrite (made with Track Changes off)**, with a short before and after; tracked edits in the same paragraph are part of it. Nothing is applied until you tick it, and a ticked rewrite becomes a proposal in **Review changes** like any other. A change on generated text, across LaTeX markup or across files stays under **could not be placed**.

Use **Import an annotated PDF** when the input is PDF margin notes rather than Word source edits. Verify anchors and quoted text after import.

## Use Git intentionally

**Publish → Git** manages the manuscript folder's own repository with status/diff, commit, fetch, pull and push workflows. Inspect changed files before committing and confirm the selected remote/branch before pushing.

This repository is separate from VersoFold's automatic history under `.versofold/history.git`. An app checkpoint is not necessarily a commit pushed to collaborators. Likewise, restoring an app version does not explain every remote Git merge conflict.

Resolve repository conflicts carefully and recompile. Avoid committing credentials, private conversation exports or large generated data without considering what belongs in that repository.

## Export or synchronize with Overleaf

**Publish → Overleaf sync** can create a source ZIP for uploading as a new project. Use its file selection to inspect what travels; build intermediates, VersoFold's own files and the local compiled PDF never travel.

To keep an existing Overleaf project in sync, paste its Git URL (Overleaf → **Integrations → Git**) and a Git authentication token (Overleaf → **Account Settings**). The Git bridge is an Overleaf paid feature. Then switch on **Sync automatically**. The first sync shows what it will do before anything moves.

Automatic sync is two-way and safe while coauthors keep writing on Overleaf:

- It runs every few minutes (choose 1–30), shortly after you edit here, and whenever you press **Sync now**.
- A file changed on one side takes that side's version. A file changed on both sides is merged line by line against the version both last had, so edits to different paragraphs both survive.
- When you and a coauthor changed the same lines, the file is held back on both sides and listed under the sync switch (a leaf with a count appears in the header). **Show** displays the clashing lines; **Keep mine** or **Keep Overleaf's** decides those lines, and both sides' edits elsewhere in the file are kept. Every other file keeps syncing meanwhile.
- The first sync of a folder that began as an Overleaf download finds the Overleaf version it started from, so edits made on both sides since are merged rather than flagged.
- Changing the Git URL switches automatic sync off until you turn it on again and review the first sync with the new project. Files that only share a name with Overleaf's are listed for you to choose, never replaced.
- Nothing is force-pushed. A sync that would delete many files at once stops and asks (nothing syncs, in either direction, until you confirm or restore the files), and changes arriving from Overleaf are preceded by a history snapshot, so they can be undone from Versions.

**Push or pull by hand** remains available: Push makes Overleaf match this folder (replacing edits made there since), Pull does the reverse, and both preview added, changed and deleted files before confirming. The integration uses its own sync clone rather than the manuscript's Git repository.

## Pick the right output

A PDF shares the rendered paper. A source ZIP supports rebuilding. An offline review file supports anchored feedback. A Word round trip supports collaborators editing in Word. A [web edition](web-edition.md) presents a public research page. None should be assumed to contain a complete backup of personal references, credentials and device preferences.


---

# Create a web edition

The web edition is a separate publication draft for explaining your research online. Open **Publish → Web edition**. Its saved content lives in `.versofold.web.json` and does not rewrite the manuscript.

## Choose a presentation

Choose **Paper project** for a conventional visual project page, **Interactive article** for a longer explanation, or **Demo showcase** for a dark visual-results presentation.

Set the title, authors, affiliation, venue note, resource links and accent. Add a teaser image or animated GIF, Markdown abstract and citation. Use descriptive link labels such as Paper, Code or Data and verify their destinations.

An attractive page still needs accurate claims and attribution. Preserve qualifications from the paper and do not invent public links or author details to fill the layout.

## Import a starting draft

**Import manuscript** reads supported local LaTeX includes and ordinary prose. It can choose an available raster rendering of a referenced figure as the teaser. Inspect imported formatting, math, alternative text and section organization.

Figures/tables are not flattened indiscriminately into imported prose. Add visual components deliberately. Import replaces the unsaved website draft, with confirmation when existing content would be replaced; save or export what you want to keep first.

The web narrative can be shorter and more visual than the paper while remaining faithful to its results.

## Build useful sections

Available section formats include:

- Prose with Markdown headings, lists, links and emphasis.
- A large figure with caption and alternative text.
- A tabbed example gallery.
- An aligned before/after image comparison.
- Local MP4/WebM video.
- An interactive numeric results explorer.
- A link to a hosted demo opened in another tab.

A hosted-demo link is not a hosted inference runtime inside VersoFold. Ensure the destination actually exists and explain prerequisites to readers.

For the results explorer, use CSV/TSV with one increasing numeric x column and one to four numeric result columns, with 2–200 observations. It displays supplied observations, series controls and a data table; it does not invent or interpolate scientific results.

## Save and preview

Use **Save draft** to persist edits. **Preview site** and desktop/mobile previews help inspect the page at different widths. Try gallery tabs, comparison controls, chart series and keyboard navigation. Check that captions and alternative text explain the important visual result.

Animations respect reduced-motion preferences. Use motion when it helps reveal content without making reading dependent on it.

Raw HTML is escaped. Author-supplied scripts are not executed; interactivity comes from supported fixed components. This keeps the publication format constrained and reproducible.

## Export a standalone site

**Export website** produces one HTML file containing the selected supported assets, optional paper PDF and optional data downloads. Rename it `index.html` when using it as a site home page on your chosen host.

Export is local. No external hosting account is configured and nothing is published automatically. Remote resource links/demos need network access; embedded assets and controls can work offline.

Only selected publication assets and public fields should travel. Check that the downloadable PDF is the intended version and that images/videos may be shared. Current limits include 5 MB per supported image, 25 MB per video/PDF and 60 MB total assets.

## Work with the agent

**Write with agent** saves pending website edits and prepares an editable request. Per-section help narrows the request. Review and send it with your configured model.

The agent can inspect the saved website and manuscript, edit supported sections/settings and prepare a local export. It should preserve author choices and omitted fields, read current revisions and avoid claiming an external publication occurred.

Clean saved agent changes can refresh into the editor. If you have unsaved changes to the same draft, resolve the conflict before saving/exporting. Website assistance does not imply authorization to change manuscript source or publish to a host.

Related: [agent](agent.md), [Figure Studio](figures.md), [sharing and export](sharing-export.md).


---

# LaTeX from the beginning

LaTeX describes a document's meaning and structure in text. You write sections, equations, figures and citations; a compiler lays them out as a PDF according to the document class and packages.

## Anatomy of a document

```latex
\documentclass[11pt]{article}
\usepackage{amsmath}
\usepackage{graphicx}
\usepackage{hyperref}

\title{A clear title}
\author{Author name}
\date{}

\begin{document}
\maketitle
\section{Introduction}
The first paragraph.
\end{document}
```

The **document class** supplies the overall structure and style. A venue may provide its own `.cls` or `.sty`. The **preamble** is everything before `\begin{document}`: packages, settings, macros and metadata. The body holds the content.

Place `\usepackage` in the preamble, not inside a paragraph. `\maketitle` prints the title metadata. An empty `\date{}` suppresses a date for classes that use that field.

## Commands, arguments and environments

Commands begin with a backslash. Required arguments usually use braces, and optional arguments often use square brackets:

```latex
\textbf{bold text}
\emph{emphasized text}
\documentclass[11pt]{article}
```

Braces also group content so local settings do not leak farther than intended. Match every opening brace with its closing brace.

Environments delimit a region with matching names:

```latex
\begin{itemize}
  \item First point.
  \item Second point.
\end{itemize}
```

A mismatched `\end{...}` often causes an error reported after the original mistake. Indentation and one environment per logical block make source easier to inspect.

## Paragraphs, spaces and comments

A blank line starts a new paragraph. A single newline in ordinary source is usually just whitespace, so you can wrap long source lines for readability. Repeated ordinary spaces do not create an arbitrarily large gap.

Use `~` for a nonbreaking space, as in `Figure~\ref{fig:overview}`. `\\` forces a line break in environments where it is appropriate; do not use it as the general way to separate prose paragraphs.

`%` begins a comment and suppresses the remainder of that source line. This can also suppress the newline, which matters when editing macros or removing comments. A literal percent sign is `\%`.

## Special characters

Some characters have structural meanings and need commands when used literally:

| Character | Source for literal prose |
| --- | --- |
| Percent | `\%` |
| Ampersand | `\&` |
| Dollar | `\$` |
| Hash | `\#` |
| Underscore | `\_` |
| Braces | `\{` and `\}` |
| Backslash | `\textbackslash{}` |
| Tilde | `\textasciitilde{}` |
| Caret | `\textasciicircum{}` |

Underscores in ordinary prose often trigger a “Missing $ inserted” error because `_` means subscript in math. For web addresses, use a URL command from an appropriate package rather than manually escaping every punctuation mark.

## Structure and emphasis

Use `\section`, `\subsection` and `\subsubsection` to express hierarchy. The class decides numbering and typography. A starred form such as `\section*{Acknowledgments}` is generally unnumbered.

```latex
\section{Method}
\label{sec:method}
We introduce \emph{adaptive weighting}.
\subsection{Objective}
The objective combines two terms.
```

Use semantic emphasis sparingly. Avoid manually making bold lines to imitate section headings; proper headings support navigation and cross-references.

`itemize` creates bullets, `enumerate` numbered items, and `description` labelled items. Each item starts with `\item`.

## Inline and displayed mathematics

Use inline math for a short expression within a sentence and display math for an equation that needs its own line:

```latex
The sample has size \(n\), with mean \(\bar{x}\).
\[
  \bar{x} = \frac{1}{n}\sum_{i=1}^{n} x_i.
\]
```

Subscripts use `_`, superscripts use `^`, and braces group multiple characters: `x_{ij}`, `e^{i\theta}`. `\frac{a}{b}` creates a fraction; `\sqrt{x}` a square root. Greek letters include `\alpha`, `\beta` and `\lambda`.

Use `\text{...}` from amsmath for words inside math. Use operator commands such as `\log` and `\sin` instead of italic letter sequences. Math spacing differs from prose spacing.

## Number and align equations

```latex
\begin{equation}
  \mathcal{L}(\theta) = \frac{1}{n}\sum_{i=1}^{n}\ell_i(\theta)
  \label{eq:loss}
\end{equation}

\begin{align}
  a &= b + c \\
    &= d.
\end{align}

Equation~\eqref{eq:loss} defines the objective.
```

The `equation` environment numbers an equation. `align` from amsmath aligns at `&`; `\\` separates its rows. Starred variants omit numbering. Do not put an `align` environment inside another display-math delimiter.

## Labels and references

A `\label{...}` records a reference target. `\ref{...}` prints its number; `\eqref{...}` adds equation-style parentheses. Choose memorable unique keys instead of embedding fixed numbers in prose.

For figures and tables, put the label after the caption so it captures the correct counter. Rebuild after introducing labels. `??` generally indicates an unresolved reference or an incomplete build cycle.

## Build a learning loop

Use Split with source and Visual/PDF. Make one small edit, compile and inspect. When an error appears, fix the first error and check nearby braces or environments. Keep a working version so experiments with unfamiliar commands are easy to undo.

Continue with [practical LaTeX techniques](latex-advanced.md), [references](references.md) and [troubleshooting](troubleshooting.md).


---

# Practical LaTeX techniques

These examples use conventional LaTeX. Your venue template may impose different commands or package restrictions. Start from its supported setup and use the compiled PDF to verify every structural or layout change.

## Figures and float placement

```latex
% Preamble:
\usepackage{graphicx}

% Document body:
\begin{figure}[tbp]
  \centering
  \includegraphics[width=0.9\linewidth]{figures/overview.pdf}
  \caption{A description of the method and the important visual relationships.}
  \label{fig:overview}
\end{figure}

Figure~\ref{fig:overview} summarizes the method.
```

A figure is a **float**: LaTeX places it where its rules allow. `t`, `b`, `p` and `h` request top, bottom, float page and here. `!` relaxes some constraints; it does not guarantee the exact source position. Forcing every figure “here” can make layout worse.

`\linewidth` is the current line width, `\columnwidth` the column width and `\textwidth` the full text area. In two-column templates, `figure*` is commonly used for full-width figures. Its allowed positions can differ from ordinary figures.

Prefer vector PDF for plots when supported and use legible labels at the final size. SVG handling depends on conversion/packages and can require external tools; Figure Studio can export a PDF directly. Keep captions informative and label after caption.

## Publication tables

```latex
% Preamble:
\usepackage{booktabs}

% Document body:
\begin{table}[tb]
  \centering
  \caption{Accuracy on the held-out evaluation set.}
  \label{tab:accuracy}
  \begin{tabular}{lrr}
    \toprule
    Method & Accuracy (\%) & Runs \\
    \midrule
    Baseline & 81.2 & 5 \\
    Proposed & 84.7 & 5 \\
    \bottomrule
  \end{tabular}
\end{table}
```

`tabular` lays out cells; `table` provides a floating wrapper/caption. Column specifications `l`, `c`, `r` align cells, while `p{width}` creates a paragraph-width column. `&` separates columns and `\\` ends rows. A literal ampersand inside a cell is `\&`.

Use consistent precision and units. A wide table might need fewer columns, shorter headings, a landscape/supplementary placement or a template-approved full-width environment. Blindly scaling everything down can make it unreadable.

For editable cells and formulas, use the [table editor](tables.md). For data-driven aggregation/error formatting, use [Figure Studio](figures.md).

## Bibliographies

Choose the bibliography system expected by the template. Do not combine BibTeX/natbib and biblatex configurations arbitrarily.

A traditional BibTeX setup can look like:

```latex
% In the document body:
Prior work studies this problem~\cite{example2026}.
\bibliographystyle{plain}
\bibliography{refs}
```

The accompanying `refs.bib` entry might be:

```bibtex
@article{example2026,
  author = {Example, Alice and Sample, Bob},
  title = {A Clearly Identified Example Paper},
  journal = {Example Journal},
  year = {2026}
}
```

This is an illustrative record, not a real citation. Use the actual registry/source metadata for your paper. Braces can preserve intended capitalization in a title, and `and` separates BibTeX authors.

A biblatex workflow instead loads the package, adds a resource and prints the bibliography:

```latex
% Preamble:
\usepackage[backend=biber,style=numeric]{biblatex}
\addbibresource{refs.bib}

% Body:
An example citation~\autocite{example2026}.
\printbibliography
```

Its backend must be available and the build configured accordingly. Citation commands depend on the package: natbib commonly uses `\citet`/`\citep`; biblatex has `\textcite`/`\parencite`/`\autocite`. Consult the actual template before changing systems.

## Split a larger project

```latex
\begin{document}
\input{sections/introduction}
\input{sections/method}
\input{sections/results}
\bibliographystyle{plain}
\bibliography{refs}
\end{document}
```

`\input` inserts a source fragment. `\include` is useful for larger units and introduces page boundaries; it also interacts with `\includeonly`. Do not put a second `\documentclass`/`\begin{document}` inside an ordinary included fragment.

Keep the compilation root selected in VersoFold while editing included files. Paths must work from the actual build context. Use a coherent folder structure and test copied/exported source so dependencies do not secretly live outside the project.

## Define notation and theorem structures

```latex
% Preamble:
\usepackage{amsmath,amssymb,amsthm}
\newcommand{\R}{\mathbb{R}}
\newcommand{\vect}[1]{\boldsymbol{#1}}
\newtheorem{theorem}{Theorem}

% Body:
Let \(\vect{x}\in\R^d\).
\begin{theorem}
A precisely stated claim belongs here.
\end{theorem}
\begin{proof}
A complete justification belongs here.
\end{proof}
```

Macros keep notation consistent and make deliberate global changes easier. Use distinctive names to avoid collisions with packages. `\newcommand` reports an existing definition; do not switch to `\renewcommand` merely to suppress an error without understanding what you are replacing.

Static tools and Visual mode may not expand arbitrary macros or conditionals. Preserve simple structure when you want outline, word counts and source anchors to work reliably.

## Engines, fonts and packages

Use the engine your template requires. XeLaTeX/LuaLaTeX support `fontspec` workflows; pdfLaTeX uses a different font setup. An engine change can alter line breaks and pagination even when the prose is unchanged.

Load packages once with compatible options. Package order can matter, so follow the template's documented arrangement, particularly for hyperlink/cross-reference packages. Avoid enabling shell escape just to eliminate an unexplained error; first identify which external tool the document actually needs.

## Appendices and submission variants

`\appendix` changes subsequent section/chapter numbering according to the class. Label appendix sections and reference them normally. A supplementary file can also be a separate compilation root with its own preamble.

VersoFold's version/variant tools can preserve shared-body entries or independent versions. Set class options, anonymity, bibliography style and limits explicitly in the correct entry. Naming a variant “final” does not configure a final template.

Related: [LaTeX basics](latex-basics.md), [page layout](page-layout.md), [submission](submission.md).


---

# Troubleshooting

Start with the last confirmed good state and the first concrete failure. Preserve your current work before trying broad recovery steps. Most problems become easier to diagnose when you distinguish source, generated assets, compiled output and saved app records.

## A build fails or the PDF does not change

1. Check the selected root and engine in the Recompile dropdown.
2. Confirm the intended source was saved and resolve any disk conflict.
3. Open the build log and start with its first error.
4. Inspect that source location and the lines immediately before it.
5. Fix the specific issue and compile again.

A displayed old PDF is not a successful build of new source. Check build time/status. If remote refresh or Figure Studio generation failed, resolve that earlier pipeline step before changing LaTeX unrelated to the failure.

Use Clean build files when stale auxiliary state is plausible after a structural change. Cleaning does not repair missing files, unbalanced braces or unsupported commands.

## Common LaTeX messages

| Symptom | What to inspect |
| --- | --- |
| Undefined control sequence | Misspelling, missing package, wrong engine or a macro defined after its use. |
| File not found | Relative path, filename case, missing downloaded/copied asset or local style file. |
| Missing `$` inserted | An underscore/caret in prose or mismatched math delimiters. |
| Runaway argument / file ended while scanning | A missing closing brace, often before the reported line. |
| Environment undefined | Missing package or misspelled environment name. |
| Extra alignment tab | Too many `&` cells for a table/align structure, or an unescaped literal ampersand. |
| Undefined reference / `??` | Missing/duplicated label, mismatched key or incomplete compilation passes. |
| Undefined citation | Missing `.bib` key, bibliography setup/backend or a failed bibliography pass. |
| Overfull box | Unbreakable content, wide table/equation/image or long link extending beyond the line. |
| Font/package error after engine change | A template or font setup incompatible with the chosen engine. |

Compiler line numbers indicate where TeX noticed a problem, not always where it began. Inspect preceding groups and environments.

## A package or executable is missing

Check whether the app is using its packaged runtime or an external/local installation. Follow the offered package/runtime controls and read the exact missing dependency. Browser/source installations need their configured TeX environment available to the server process.

SVG conversion, bibliography backends, SSH data transfer and specialized builds may each have separate prerequisites. A package installed in a different shell environment may not be visible to the running app until configuration/restart is appropriate.

## Saved changes conflict with another writer

A dirty editor, external source change or newer domain-record revision can invalidate a preview. Keep your draft, inspect the current saved state, and refresh/rebase the proposed change. Copy important text before discarding any local draft.

Do not bypass the check by deleting `.versofold` files or blindly replacing the whole manuscript. Guarded workflows protect source, tables, board cards, research records and generated assets differently; follow the specific message.

## Visual differs from PDF

Visual approximates supported template behavior. It does not run TeX float placement, line breaking or every custom macro. Check exact pagination and numbering in a fresh PDF. Use LaTeX source for unsupported structures.

An equation can fail the local preview while compiling correctly, or preview successfully while the document lacks a required package. The actual build resolves which behavior applies to the manuscript.

## References, PDF search or evidence are incomplete

Check that the paper has an attached PDF and a usable text layer. Scanned pages need image inspection; OCR is not included. Try alternate terms, inspect the original page and read the coverage disclosure.

Registry metadata is not proof of claim support. An uncertain citation match needs a human choice. Missing search hits in a limited index do not prove no evidence exists.

Reopen evidence pages when an inspection record expires. Reattach manuscript anchors after wording changes or ambiguous duplicates. Recheck source fingerprints after replacing a PDF attachment.

## Data-driven content is stale

For remote sources, verify SSH access, the host's Python prerequisite and whether the file changed during transfer. A complete old cache can be used only through the explicit stale fallback.

For Figure Studio, inspect recipe warnings, mappings, missing inputs and whether assets were published after the latest design change. Externally edited generated files require an explicit replacement decision. Frozen sources/assets remain pinned.

For linked results, refresh calculations and inspect row counts, filters and percentage formatting. Reconnect changed anchors. For tables, correct formulas before publication and remember that saving a draft does not republish output.

## An agent cannot proceed

Check the current connection, model, mode, file scope and optional grants. A Discuss run cannot perform ordinary manuscript edits. A custom endpoint may not have verified tool support: its models can only discuss until you tick **Tools verified** on its card in **Settings → Connections** (only do this once you know the model handles tool calls). An external runtime may need login or a compatible installed version.

Read quota/authentication errors rather than repeatedly sending the same request. Review pending approval/question cards. Stop preserves completed changes; inspect activity before retrying an uncertain write.

Ask “Consult the handbook for this specific feature” when the obstacle is how to use VersoFold. If the problem is the manuscript's scientific content, the agent still needs to inspect that content.

## On Linux

VersoFold for Linux comes as a `.deb` for Ubuntu and Debian and as an AppImage for other distributions (x64).

- **The AppImage does not start.** AppImages need FUSE 2 (`libfuse2` on Ubuntu, which recent releases no longer install by default). Install it, or run the AppImage with `--appimage-extract-and-run`. The `.deb` needs neither.
- **Agent commands do not run.** Commands and research scripts run in a bubblewrap sandbox (`/usr/bin/bwrap`). The `.deb` installs it; with the AppImage, install the `bubblewrap` package. Without it, a command reports that the Linux sandbox is unavailable instead of running unconfined.
- **Keys are not remembered.** Remembered keys are sealed by the desktop keyring (GNOME Keyring or KWallet, through `libsecret`). Without one, VersoFold asks for the key again in each session and never writes it to disk in the clear.
- **Updates.** An AppImage updates itself in place. A `.deb` install downloads the new package and opens it in the system's software installer, which asks for your password.
- **Shortcuts.** The app and this handbook show **Ctrl** and **Alt** where a Mac shows ⌘ and ⌥.

## Recover or report a problem

Use editor Undo for immediate mistakes, Review changes for a current diff, and Versions for older source. Preserve hidden history in backups; lost Git objects cannot be recreated by the app.

Use **Help → Report a bug** with the action, expected result, actual result and relevant error. Settings/Home also expose feature requests. Include only material you intend to share; project prose and credentials are not automatically necessary to explain a UI error.


---

# Keyboard shortcuts & glossary

On a Mac the tables show Command and Option shortcuts. On Linux and Windows the app shows the same shortcuts with Ctrl and Alt. Some native desktop commands are unavailable in a browser window.

## Workspace shortcuts

| Shortcut | Action |
| --- | --- |
| `⌘K` | Search tools, views, actions and files in the command palette. |
| `⌘P` | Find a file. |
| `⌘Enter` | Compile the selected document root. |
| `⌘S` | Save immediately; source also autosaves. |
| `⌘F` | Search the active source editor. |
| `⌘ShiftF` | Search the project. |
| `⌘ShiftM` | Comment on the source selection. |
| `⌘ShiftR` | Review tracked changes (the Changes tab). |
| `⌘ShiftA` | Open or close the agent's column. |
| `⌘ShiftE` | Track changes on or off for your edits. |
| `⌘Option]` / `⌘Option[` | In the LaTeX editor: next / previous tracked change, with its card. |
| `⌘ShiftH` | Open versions/history. |
| `⌘ShiftT` | Deadlines, tasks and reviews. |
| `⌘ShiftI` | Snippets and wrappers. |
| `ControlSpace` | Expand a template shortcut in the editor. |
| `⌘J` | Build log/problems. |
| `⌘ShiftJ` | Show the cursor position in the PDF (Show in PDF). |
| `⌘B` | Toggle file-tree visibility. |
| `⌘Option O` | Open the view you are working in in its own window; in a view's own window, return it to the main window. |
| `⌘W` | Close the active tab where the editor handles it. |
| `⌘,` | Settings. |
| Double-click PDF text | Jump to source when SyncTeX is available. |
| Double-click source | Show the corresponding PDF location when the PDF is on screen. |
| Enter / `⌘Enter`, `←` `→`, Esc | In a reference review: confirm, move to the previous or next record, close the review. |

Use ordinary Undo/Redo for source edits. Conversation Undo/Redo changes the active conversation boundary and does not undo manuscript files.

## In the Response view

While you write an answer to a reviewer, the formatting bar's shortcuts belong to the answer (so **⌘B** makes text bold there instead of toggling the sidebar).

| Shortcut | Action |
| --- | --- |
| `⌘B` / `⌘I` | Bold / italic. |
| `⌘E` | Inline code. |
| `⌘ShiftK` | Link (`⌘K` stays the command palette). |
| `⌘Shift8` / `⌘Shift7` | Bulleted / numbered list. |
| `⌘Shift.` | Quote. |
| `Control-M` | Inline equation, `$…$` (Ctrl+M on Linux and Windows; ⌘M stays the Mac's Minimize). |
| `Control-Shift-M` | Display equation, `$$…$$` on lines of their own. |
| Enter | In a list item or quote, start the next one; in an empty item, end the list. |

## Documentation and accessibility

Desktop **Help → VersoFold Documentation** also uses F1. In the handbook, **⌘K** focuses search, Tab moves among controls, Enter activates the focused item, and Escape closes the handbook. Closing returns you to the underlying workspace.

The handbook provides category colors as an additional cue; headings and labels also identify every category. A contents rail appears in wide windows, while narrow layouts retain chapter navigation and search. Code examples have Copy controls, and tables scroll when necessary.

Focus a pane divider and use arrows to resize where supported. Split's divider also offers Home to reset its proportions. Reduced-motion preferences affect decorative effects and supported exported web-edition motion.

## Document and writing terms

| Term | Meaning |
| --- | --- |
| Workspace | A saved project pointing to a folder and its associated app records. |
| Source | The editable `.tex`, `.bib` and supporting files used to build a paper. |
| Root / entry | The complete LaTeX document selected for compilation. |
| Preamble | Commands before `\begin{document}`, including packages and definitions. |
| Package | A LaTeX extension loaded with `\usepackage`. |
| Environment | Content enclosed by matching `\begin` and `\end`. |
| Float | A figure/table whose placement is chosen by LaTeX within requested constraints. |
| Label | A unique key used to refer to a numbered object. |
| Citation key | An identifier connecting a citation command to a bibliography record. |
| SyncTeX | Build metadata mapping PDF locations to LaTeX source. |
| Build artifact | Output/intermediate files produced by compilation or generation. |

## Review and data terms

| Term | Meaning |
| --- | --- |
| Snapshot / checkpoint | A preserved source state used for comparison or recovery. |
| Named version | An intentional manuscript milestone, optionally with a matching PDF. |
| Baseline | The source state against which changes are compared. |
| Tracked change | An insertion or deletion recorded with its author, pending until someone accepts or rejects it; the file already holds it (insertions in, deletions out). |
| Live edit | A change already applied to working source. |
| Staged proposal | A proposed source state awaiting author acceptance. |
| Stale | A result/preview no longer known to match current inputs. |
| Fingerprint | A content identity used to detect changed source/data. |
| Provenance | Recorded origins, transformations and evidence behind an output. |
| Recipe | A declarative Figure Studio design and data-processing specification. |
| Publish table/figure | Generate manuscript assets from a saved draft/recipe. |
| Freeze | Pin a source, asset or version to preserve a chosen state. |
| Evidence assessment | A recorded interpretation of inspected sources, separate from metadata checking. |

## Agent and sharing terms

| Term | Meaning |
| --- | --- |
| Context | Material supplied to a conversation or read by its tools. |
| Discuss | A conversation mode primarily for reading and analysis. |
| Edit | A mode enabling authorized guarded changes. |
| Grant | Explicit access to a scope/capability; separate from per-action approval. |
| MCP | A protocol through which an external agent discovers and invokes app tools. |
| Compaction | A continuation summary for long context while local history is retained. |
| Review invitation | Access to a shared workspace under a role and grants. |
| Offline review file | A self-contained exported reader for feedback returned later. |

## Phases, rebuttals and editions

| Term | Meaning |
| --- | --- |
| Phase | Where the paper is in its life (Drafting to Published); it arranges the side panel and the tools in view, and locks nothing. |
| Submitted version | The version saved by **Mark as submitted**; changes since submission are measured against it. |
| Response view | The rebuttal as the reviewers' comments with your answers under them: the file `rebuttal/response.md`. |
| Follow-up | A reviewer's later comment in the discussion, answered under the point it replies to. |
| Marked PDF | A latexdiff build of the paper with every change since submission coloured. |
| Edition | One form of the paper built from the same source: the paper, the preprint, the supplementary material, or a copy. |
| Edition mark | `\ifpreprint … \fi` and its kin: text only some editions print. |
| Edition view | The LaTeX and PDF as one edition prints them; what it leaves out folds away. |

Related: [navigation](navigation.md), [agent](agent.md), [troubleshooting](troubleshooting.md).


---

# Handbook access for agents

The same Markdown sources power the human handbook, native-agent tools and external-agent lookups. They describe VersoFold's behavior and workflows. They are not project instructions, user authorization or evidence about a manuscript.

## When to consult the handbook

The agent receives a short notice that documentation exists, not the entire handbook. Consult it only when the user explicitly asks for documentation or how to use VersoFold or when stuck on a specific VersoFold capability required for the task.

Do not perform a documentation scan at the beginning of every conversation. Do not preload every guide. Search for the obstacle and read the relevant section. Continue to inspect actual project files before making claims or editing them.

Example triggers include “How do I use a shared-body variant?”, “Use the handbook to explain error bands”, or uncertainty about the app's required table publishing sequence. A normal request to improve prose does not require opening the handbook.

## Native and MCP tools

`search_documentation` accepts a literal multiword query and optional result limit. It searches guide metadata and body sections, returning guide/section IDs, headings, excerpts and line ranges.

```json
{"query":"table publish", "limit":5}
```

`read_documentation` without an ID returns the catalog. With an ID it returns bounded Markdown and a section outline. Specify a section ID from the search/outline when only that part is needed.

```json
{"id":"tables", "section":"save-publish-and-insert-are-separate"}
```

A read can also use `startLine` and `maxLines` (up to 160). Follow the returned continuation object when the selected material is longer than the bounded response. Continuations retain the selected section and advance source line numbers.

These read-only tools do not require a model call of their own, modify the manuscript or read private project files. They are available across applicable native reading/editing scopes and the external MCP catalog. Grants for other tools remain unchanged.

## HTTP and filesystem access

The running server exposes only bundled public guides at these relative URLs:

| Route | Result |
| --- | --- |
| `/documentation/index.json` | Guide IDs, titles, groups, summaries, source paths and Markdown URLs. |
| `/documentation/search?q=page%20budget` | Ranked section matches with excerpts and locations. |
| `/documentation/page-layout.md` | One complete canonical Markdown guide. |
| `/documentation/handbook.md` | All chapters for an explicitly requested full export. |

Use the running app's origin; do not assume the port is always 3055. These endpoints contain product documentation, not workspace state. They are available without exposing the owner's reference library, conversations or files.

In the source repository, begin with `docs/guide/README.md`, then read the relevant `docs/guide/<id>.md`. The packaged desktop build includes the same files. A paper workspace is not the application repository, so do not try to find these paths with manuscript-only file tools; use the dedicated documentation tools instead.

## Cite the answer precisely

Tell the user the workflow in ordinary language and link the relevant guide/section where useful. For example, a local app link can use `/?guide=tables&section=save-publish-and-insert-are-separate`.

Distinguish documented capability from an executed operation. Reading how to compile is not a build result; reading how to verify references is not evidence that a reference was checked. If the current tool catalog lacks a documented capability, explain the scope/availability rather than inventing a call.

Do not include review invitation tokens, account details or workspace secrets in help links. A copied local guide link works only where that VersoFold server is reachable.

## Maintain documentation alongside features

Each guide uses a level-one title, descriptive level-two/three headings, ordinary Markdown links, ordered procedures and fenced examples. Headings outside code fences become stable section IDs; duplicate headings receive suffixes. Search and agent reads share the same section parser.

When a feature changes, update its guide and the shared catalog if the title, category or keywords changed. Keep instructions grounded in the actual interface, state what saves/publishes/applies an edit, explain stale-data behavior and link related workflows. Preserve useful section IDs where possible so saved links remain meaningful.

Do not present planned features as available. Describe external submission/service requirements as things to check against their current official instructions; a local handbook cannot guarantee a remote policy is unchanged.