Compilation Requirements for CVs and Cover Letters in the AI Job Search Repository

The AI Job Search framework generates application materials as LaTeX PDFs using LuaLaTeX for CVs and XeLaTeX for cover letters, with strict page-count constraints and font dependencies enforced by the /apply workflow.

The MadsLorentzen/ai-job-search repository automates job applications by compiling specialized LaTeX templates into ATS-readable PDFs. Understanding the specific compilation requirements for CVs and cover letters ensures your local TeX distribution can execute the full /apply pipeline without engine mismatches or missing font errors.

LaTeX Engine Requirements by Document Type

The repository enforces distinct compilation engines for each document type based on their underlying LaTeX classes and font requirements.

CV Compilation with LuaLaTeX

The stock CV template located at cv/main_example.tex utilizes the moderncv document class and must be compiled with lualatex. This engine handles dynamic font loading and modern Unicode features required by moderncv's internal dependencies. The output is strictly constrained to exactly 2 pages; if compilation produces a longer document, the framework automatically truncates low-relevance content and recompiles until the constraint is met.

Required packages include moderncv, fontawesome5, geometry, and hyperref. These are typically bundled with full TeX distributions but must be manually installed on minimal setups.

Cover Letter Compilation with XeLaTeX

Cover letters use a custom class defined in cover_letters/cover.cls and the example template cover_letters/cover_example.tex. This workflow requires xelatex specifically because the class relies on the fontspec package to load system fonts. The template references the Raleway font family stored in cover_letters/OpenFonts/fonts/raleway/.

The final cover letter must be exactly 1 page with the signature block fully visible. The xelatex engine is mandatory here; using lualatex will fail due to fontspec integration differences.

Required Packages and Font Dependencies

A full LaTeX distribution capable of running both lualatex and xelatex is required. Recommended distributions include TeX Live, MacTeX, MiKTeX, or TinyTeX.

When using minimal installations like TinyTeX or BasicTeX, you must install additional packages documented in SETUP.md. These include:

• moderncv
• fontawesome5
• fontspec
• Any dependencies required by the custom cover.cls class

The CV template automatically loads fontawesome5 for social media icons, while the cover letter class requires fontspec for custom typography. The Raleway fonts are bundled within the repository at cover_letters/OpenFonts/fonts/raleway/, eliminating external font installation for the cover letter workflow.

The /apply Compilation Workflow

When you execute /apply https://example.com/job/123, the system orchestrates a three-step compilation and verification process defined in the repository's core workflow.

CV Generation and Automatic Truncation

The system executes lualatex on cv/main_example.tex with non-stop interaction mode. If the resulting PDF exceeds two pages, the framework analyzes content relevance, removes the lowest-priority lines, and recompiles iteratively until the strict two-page limit is satisfied.

Cover Letter Generation with Font Specifications

The workflow runs xelatex on cover_letters/cover_example.tex, leveraging fontspec to load the local Raleway typefaces. The compiler enforces a single-page constraint and verifies that the signature image renders within the page boundaries.

PDF Verification via verify_pdf.py

After each compilation, the tools/verify_pdf.py script performs automated quality checks. It verifies page counts against expected values (2 for CVs, 1 for cover letters) and extracts the text layer using pdftotext or pypdf to confirm ATS readability before final submission.

Manual Compilation Commands

You can manually compile documents for debugging or custom template development using these deterministic commands from the repository root.

Compile the CV manually:

cd cv
lualatex -interaction=nonstopmode -halt-on-error main_example.tex

Compile the cover letter manually:

cd cover_letters
xelatex -interaction=nonstopmode -halt-on-error cover_example.tex

Run the verification script directly to check page counts:

python3 tools/verify_pdf.py \
    --pdf_path=cv/main_example.pdf \
    --expected_pages=2

python3 tools/verify_pdf.py \
    --pdf_path=cover_letters/cover_example.pdf \
    --expected_pages=1

Installing Minimal LaTeX Distributions

For users with limited disk space, TinyTeX or BasicTeX provide lightweight alternatives to full TeX Live installations. However, these minimal distributions require manual package installation to meet the compilation requirements for CVs and cover letters.

Refer to SETUP.md for the complete list of packages to install via tlmgr (TeX Live Manager) or the MiKTeX console. The document specifies exact commands to acquire moderncv, fontawesome5, and fontspec along with their transitive dependencies.

Summary

• CVs require LuaLaTeX: The cv/main_example.tex template uses moderncv and must compile to exactly 2 pages using lualatex.
• Cover letters require XeLaTeX: The cover_letters/cover_example.tex template uses a custom class with fontspec and Raleway fonts, requiring xelatex for exactly 1 page.
• Verification is automated: The tools/verify_pdf.py script validates page counts and ATS readability after compilation.
• Minimal distributions need setup: TinyTeX and BasicTeX users must install additional packages listed in SETUP.md to satisfy both engine requirements.

Frequently Asked Questions

Why does the CV use LuaLaTeX while the cover letter uses XeLaTeX?

The CV relies on the moderncv class, which performs optimally with LuaLaTeX's modern font handling and microtype features. The cover letter uses a custom class (cover_letters/cover.cls) that depends on the fontspec package to load the Raleway font family from the local cover_letters/OpenFonts/fonts/raleway/ directory. While fontspec technically works with both engines, the repository specifically targets XeLaTeX for the cover letter workflow to ensure consistent cross-platform font rendering.

How do I install the required packages on a minimal TeX distribution?

If using TinyTeX or BasicTeX, consult the SETUP.md file for the exact tlmgr install commands. You must install moderncv, fontawesome5, fontspec, and their dependencies before running the /apply command. The repository maintainers test primarily against TeX Live full installations, so minimal distribution users should verify all packages are present by running the manual compilation commands before attempting automated application generation.

What happens if my CV exceeds the 2-page limit?

The /apply workflow automatically truncates content by removing the lowest-relevance entries (typically older or less relevant job experiences) and recompiles the document. This iterative process continues until the PDF satisfies the two-page constraint enforced by tools/verify_pdf.py. If you manually compile and exceed the limit, the verification script will return an error when checking --expected_pages=2.

Can I use custom templates with different compilation requirements?

Yes. When adding templates via /add-template, you must specify the custom compile command and required packages in the template configuration. The built-in CV and cover-letter templates follow strict requirements, but custom additions can target alternative engines like pdfLaTeX or ConTeXt provided you document the dependencies and adjust the verification parameters in tools/verify_pdf.py accordingly.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}