---
name: insat-pfe-report
description: Use this skill when the user wants to write, edit, or compile an INSAT end-of-studies (PFE) report using the ahmedsilinii/INSAT-PFE-Report-Template LaTeX template. Covers scaffolding a new report from the template, editing chapters/preliminary pages, regenerating the Word-based cover and last pages, and compiling to PDF locally (pdflatex + biber) without Overleaf. Trigger on mentions of "PFE report", "INSAT report template", "rapport de PFE", or a project directory containing this template's main.tex.
license: See upstream repo (github.com/ahmedsilinii/INSAT-PFE-Report-Template) for template license terms. Scripts in this skill are provided as-is.
---

# INSAT PFE Report — local build skill

Turns github.com/ahmedsilinii/INSAT-PFE-Report-Template into something you can write and compile
entirely on the command line — no Overleaf account needed.

## Overview

The template is a LaTeX `report`-class document (`main.tex`) that:
- pulls chapters from `chapters/*.tex` (general intro, chapter1–5, general conclusion)
- pulls front/back matter from `preliminary pages/*.tex` (dedication, acknowledgements, abstract,
  résumé, list of acronyms, appendices) and bibliography from `preliminary pages/bibliography.bib`
- uses **biblatex + biber** with `style=ieee` (set explicitly in `main.tex`: `\usepackage[style=ieee,
  backend=biber]{biblatex}`), **tikz**, **pdfpages**, **pdflscape** + **eso-pic** (rotated landscape
  headers), **listings**, **fancyhdr**, **titlesec**, **hyperref**, plus table support (**tabularx**,
  **longtable**, **booktabs**, `xcolor[table]`)
- includes pages that are NOT written in LaTeX — they're Word docs exported to PDF and pulled in
  with `\includepdf`: `PageDeGarde_English.pdf` (cover — **both pages** of it are included:
  `\includepdf{PageDeGarde_English.pdf}` then `\includepdf[pages=2]{PageDeGarde_English.pdf}` for
  an inner declaration page) and `LastPage.pdf` (back cover, single page), sourced from
  `PageDeGarde_English.docx` and `LastPage.docx` respectively

This has been verified end-to-end in a clean Ubuntu container: clone → install TeX Live + biber →
4-pass build (pdflatex → biber → pdflatex → pdflatex, or `latexmk -pdf` as a one-shot) → valid PDF.
docx→PDF conversion for the cover/last page was verified with headless LibreOffice.

## First-time setup (once per machine)

Run `scripts/install-deps.sh`. It installs, via `apt`:
- `texlive-latex-base texlive-latex-recommended texlive-latex-extra` (base LaTeX + biblatex, hyperref, etc.)
- `texlive-fonts-recommended texlive-pictures` (tikz)
- `texlive-bibtex-extra biber` (bibliography backend)
- `latexmk` (build driver)
- `libreoffice` (headless docx→PDF conversion for the cover/last page — optional, skip with `--no-libreoffice` if the user only edits chapters)

This is a ~1–2GB install the first time. If the user is on a machine without `apt` (macOS, etc.),
tell them to install **MacTeX** (or `basictex` + `tlmgr install biblatex biber tikz pdfpages pdflscape
listings fancyhdr titlesec enumitem csquotes`) and **LibreOffice** via `brew install --cask libreoffice`,
then skip straight to compiling.

## Getting the template into a project

Run `scripts/fetch-template.sh <target-dir>`. It `git clone --depth 1`s the upstream repo into
`<target-dir>` and strips `.git` so it becomes the user's own project, not a fork tracking upstream.
If the user already has the template cloned, skip this step and just `cd` into it.

## Compiling

Run `scripts/compile.sh <project-dir>` (defaults to `.`). It runs, inside that directory:

```
latexmk -pdf -interaction=nonstopmode -halt-on-error main.tex
```

`latexmk` auto-detects that biblatex needs biber (via `main.bcf`) and reruns pdflatex as many times
as needed to settle cross-references, the ToC, and citations — this replaces the manual
pdflatex → biber → pdflatex → pdflatex sequence. Output is `main.pdf` in the project root.

If `latexmk` isn't available for some reason, fall back to the manual sequence, run from the project
directory:
```
pdflatex -interaction=nonstopmode -halt-on-error main.tex
biber main
pdflatex -interaction=nonstopmode -halt-on-error main.tex
pdflatex -interaction=nonstopmode -halt-on-error main.tex
```
(Two pdflatex passes after biber are required — one pass alone can leave the bibliography or ToC
one revision stale.)

On a clean compile you'll see a handful of harmless `pdfTeX warning ... PDF inclusion` lines from
the `\includepdf` calls and possibly a `destination with the same identifier` warning — these are
not errors. Treat anything under `! LaTeX Error` or `! Undefined control sequence` in the log as
the thing to actually fix.

If the user only changed a `.tex` file (no new citations, no cover page swap), a single
`pdflatex -interaction=nonstopmode main.tex` is enough for a quick preview — just remember to do
the full 4-step (or `latexmk`) pass before calling it done, or citations/toc will be stale.

## Editing content

- Chapters: edit `chapters/chapter1.tex` … `chapter5.tex`, `general_introduction.tex`,
  `general_conclusion.tex`. To add/remove a chapter, edit the `\input{chapters/...}` lines in
  `main.tex` directly — mirror the existing pattern.
- Front/back matter: `preliminary pages/dedication.tex`, `acknowledgements.tex`, `abstract.tex`,
  `resume.tex`, `list_of_acronyms.tex`, `appendices.tex`.
- References: add BibTeX entries to `preliminary pages/bibliography.bib`, cite with `\cite{key}`.
  Style is IEEE via biblatex — no manual formatting needed.
- Images: put files under `assets/` (e.g. `assets/Logos/`) and `\includegraphics` them.
- Code listings: use the `lstlisting` environment (already configured with line numbers, a light
  gray background, and syntax highlighting via the `listings` package).

## Editing the cover and last page (no Word needed)

These two source files are DOCX documents exported to PDF; `main.tex` includes the PDFs, not the
DOCX. `PageDeGarde_English.docx` must stay a 2-page document (cover + inner declaration page) since
`main.tex` pulls both pages in separately — deleting a page or adding one shifts what
`\includepdf[pages=2]{...}` grabs. `LastPage.docx` is a single page. Two ways to edit them without
opening Word/Overleaf:

1. **Text edits only, keep the Word layout**: edit `PageDeGarde_English.docx` / `LastPage.docx` with
   any tool the user has (LibreOffice Writer GUI, or programmatically with `python-docx` if it's a
   simple find-and-replace like a name or project title), then run
   `scripts/convert-cover-pages.sh <project-dir>` to headless-convert both docx files back to PDF
   **with the exact same filenames** (`PageDeGarde_English.pdf`, `LastPage.pdf`) that `main.tex`
   expects. Re-run the compile after.
2. **Full redesign**: if the user wants a different look, they can design a new PDF (Canva, LaTeX,
   whatever) and drop it in under the same filename — `main.tex` doesn't care how the PDF was made.

Never hand-edit the `.pdf` cover files directly; always regenerate from source and keep filenames
identical, since `\includepdf{PageDeGarde_English.pdf}` and `\includepdf{LastPage.pdf}` are literal
filename references in `main.tex`.

## Common failure modes

- **`! LaTeX Error: File 'preliminary pages/bibliography.bib' not found`**: run from the project
  root, not from inside `chapters/` or `preliminary pages/` — all paths in `main.tex` are relative
  to the root.
- **Citations show as `[?]` or bibliography is empty**: biber didn't run, or ran before a `.bcf` was
  generated. Always do a pdflatex pass *before* biber, or just use `latexmk -pdf` which sequences
  this correctly on its own.
- **`biber: command not found`**: rerun `scripts/install-deps.sh`, or `apt install biber` /
  `tlmgr install biber` depending on the TeX distribution.
- **Cover/last page missing or stale after a docx edit**: the PDF wasn't regenerated, or was saved
  under a different filename — rerun `scripts/convert-cover-pages.sh` and check the two PDF
  filenames match exactly (case-sensitive).
- **Space in `preliminary pages/` trips up a shell one-liner**: always quote the path, e.g.
  `"preliminary pages/bibliography.bib"`.

## Files in this skill

- `scripts/install-deps.sh` — one-time TeX Live + biber + latexmk + LibreOffice install (apt-based)
- `scripts/fetch-template.sh` — clone the upstream template into a fresh project directory
- `scripts/compile.sh` — full local build (latexmk, with manual-sequence fallback)
- `scripts/convert-cover-pages.sh` — headless docx→pdf for the cover/last page
- `INSTALL.md` — how to install this skill into Claude Code, opencode, and Codex CLI