Build and fix

A compile failure is a lookup, not a puzzle. Read the first error, name its class, apply the smallest edit that fixes that class, compile again. Repeat until compile returns success: true with an empty errors list.

1. Know the engine before touching anything

read_file on project.json. The engine value decides almost everything below. In a Typst project, typst.version in the same file is the Typst version the project pins.

The assistant cannot switch engines. set_main_doc changes the engine as a side effect of the file extension, and that is the only lever it has. Anything else is a Settings change the user makes.

Never write pdflatex as an engine name. Oleafly does not accept it, and a project or template that declares it disappears from the app.

2. Compile and read the result

1. compile. The envelope carries success, errors, has_pdf, and log_tail.
2. get_log for the last 20k characters when log_tail is not enough.
3. Read the first error, not the last. LaTeX errors cascade, so the tail is usually noise from the first one.
4. Note whether has_pdf is true. A PDF plus errors means a recoverable error was stepped over and the output is probably wrong even though a file exists.

3. Classify before editing

read_skill_file this skill's references/error-catalog.md and match the log line to a row. It gives the cause, the fix, and the tool call for each pattern, across LaTeX, BibTeX and Biber, fonts, Typst, and Pandoc.

If nothing matches, say so rather than guessing, and fall back to the bisect procedure at the end of the catalog.

4. Fix with the smallest edit

Use replace_in_file with enough surrounding text to be unambiguous. Prefer one class of error per round so the next compile tells you whether that fix worked.

Rules that keep the loop honest:

• Never delete content to make a compile pass. Comment nothing out permanently without saying so.
• Never add a package you have not confirmed the engine can resolve.
• Never change the engine, the class, or the bibliography backend to dodge a single error.
• If the fix would change what the document says, stop and ask.

5. Recompile until it is actually clean

Clean means success: true and errors: []. A build that produces a PDF while errors remain is not done.

Then check what came out:

• get_pdf_text to confirm the sections, the title, and the references list are present.
• verify_pdf_pages when layout matters (column breaks, a table that overflows, a figure that landed on the wrong page). It only exists when the user has enabled PDF page capture in Settings; if it is unavailable, say what you could not check.
• project_map for unresolvedRefs and unresolvedCites after any citation or reference work.

6. Sweep for the failures that do not error

read_skill_file this skill's references/engine-notes.md when any of these apply. They compile successfully and are still wrong:

• the log mentions an absolute path under /System/Library, /Library/Fonts, or C:/Windows/Fonts, which means the build is bound to this machine's fonts;
• the document is CJK and uses ctex;
• a font was requested and silently fell back;
• two machines produce visibly different PDFs from the same source;
• the same source compiles here and fails on a coauthor's machine.

Decision points

Failure handling

Artifacts

A compiled PDF, a clean compile log, and a short written list of what was wrong and what changed. Leave the source in a state where every edit is explainable.

Done when

• compile returns success: true with an empty errors list
• No content was removed to achieve that
• project_map reports no unresolved references or citations, or the remaining ones are listed for the user
• The output was checked with get_pdf_text, and with verify_pdf_pages when it was available
• No absolute host font path appears in the log
• Every change is named in one line, with the error it fixed

From a terminal

Outside the app (a terminal, or a coding agent with a shell), the oleafly command does the same work. Always pass --json and check ok.