laporan-generator 2.6.1

package/.agents/skills/laporan-generator/resources/build-docx.sh

@@ -0,0 +1,122 @@
+#!/usr/bin/env bash
+set -e
+
+DIR="$(cd "$(dirname "$0")" && pwd)"
+if [ -n "$1" ]; then
+  OUTDIR="$1"
+elif [ -f "$(pwd)/metadata.yml" ] && [ -d "$(pwd)/chapters" ]; then
+  OUTDIR="$(pwd)"
+else
+  OUTDIR="$DIR"
+fi
+REPORT="$OUTDIR/Laporan.docx"
+
+# Resolve Python (handle WindowsApps stub redirector on Windows)
+PYTHON_BIN="python3"
+if ! command -v python3 >/dev/null 2>&1 || ! python3 -V >/dev/null 2>&1; then
+  if command -v python >/dev/null 2>&1 && python -V >/dev/null 2>&1; then
+    PYTHON_BIN="python"
+  fi
+fi
+
+if [ ! -d "$OUTDIR/chapters" ]; then
+  echo "ERROR: Direktori chapters/ tidak ditemukan."
+  exit 1
+fi
+
+TMPDIR=$(mktemp -d)
+trap 'rm -rf "$TMPDIR"' EXIT
+
+FALLBACK_DIRS=(
+  "$OUTDIR"
+  "$DIR"
+  "$HOME/.agents/skills/laporan-generator/resources"
+)
+
+copy_asset() {
+  local asset="$1"
+  local dest="$2"
+  for base in "${FALLBACK_DIRS[@]}"; do
+    if [ -e "$base/$asset" ]; then
+      cp -r "$base/$asset" "$dest/"
+      return 0
+    fi
+  done
+  return 1
+}
+
+copy_asset "cover.md" "$TMPDIR" || true
+copy_asset "logo.jpg" "$TMPDIR" || true
+copy_asset "reference.docx" "$TMPDIR" || true
+copy_asset "docx.lua" "$TMPDIR" || true
+copy_asset "metadata.yml" "$TMPDIR" || true
+copy_asset "references.bib" "$TMPDIR" || true
+copy_asset "apa.csl" "$TMPDIR" || true
+copy_asset "presets" "$TMPDIR" || true
+copy_asset "scripts" "$TMPDIR" || true
+
+if [ -d "$OUTDIR/gambar" ]; then
+  cp -r "$OUTDIR/gambar" "$TMPDIR/"
+elif [ -d "$DIR/gambar" ]; then
+  cp -r "$DIR/gambar" "$TMPDIR/"
+fi
+
+cp "$OUTDIR/chapters"/*.md "$TMPDIR/" 2>/dev/null || true
+CHAPTER_FILES=$(find "$TMPDIR" -maxdepth 1 -name "bab*.md" | sort -V)
+if [ -z "$CHAPTER_FILES" ]; then
+  echo "ERROR: Tidak ada berkas bab*.md di direktori chapters/."
+  exit 1
+fi
+INPUT_FILES=("$TMPDIR/cover.md")
+while IFS= read -r f; do
+  [ -n "$f" ] && INPUT_FILES+=("$f")
+done < <(find "$TMPDIR" -maxdepth 1 -name "bab*.md" | sort -V)
+
+cd "$TMPDIR"
+
+PRESET_NAME=$(grep -E '^[[:space:]]*(preset|margin_preset):' "$TMPDIR/metadata.yml" 2>/dev/null | head -n 1 | cut -d: -f2- | tr -d '"'\''\r\n ')
+PRESET_OPTS=()
+if [ -n "$PRESET_NAME" ] && [ -f "$TMPDIR/presets/${PRESET_NAME}.yml" ]; then
+  PRESET_OPTS=("--metadata-file=$TMPDIR/presets/${PRESET_NAME}.yml")
+elif [ -f "$TMPDIR/presets/standard.yml" ]; then
+  PRESET_OPTS=("--metadata-file=$TMPDIR/presets/standard.yml")
+fi
+
+pandoc \
+  "${INPUT_FILES[@]}" \
+  "${PRESET_OPTS[@]}" \
+  --metadata-file="metadata.yml" \
+  --citeproc \
+  --bibliography="references.bib" \
+  --csl="apa.csl" \
+  --metadata=reference-section-title="DAFTAR PUSTAKA" \
+  --top-level-division=chapter \
+  --reference-doc="reference.docx" \
+  --lua-filter="docx.lua" \
+  -o "$TMPDIR/Laporan-tmp.docx" 2>&1
+
+FINALIZE_SCRIPT="$TMPDIR/scripts/finalize-docx.py"
+PAGENUM_SCRIPT="$TMPDIR/scripts/docx-pagenum.py"
+if [ ! -f "$FINALIZE_SCRIPT" ]; then
+  for base in "${FALLBACK_DIRS[@]}"; do
+    if [ -f "$base/scripts/finalize-docx.py" ]; then
+      FINALIZE_SCRIPT="$base/scripts/finalize-docx.py"
+      break
+    fi
+  done
+fi
+if [ ! -f "$PAGENUM_SCRIPT" ]; then
+  for base in "${FALLBACK_DIRS[@]}"; do
+    if [ -f "$base/scripts/docx-pagenum.py" ]; then
+      PAGENUM_SCRIPT="$base/scripts/docx-pagenum.py"
+      break
+    fi
+  done
+fi
+
+export PYTHONUTF8=1
+"$PYTHON_BIN" "$FINALIZE_SCRIPT" "$TMPDIR/Laporan-tmp.docx" "$TMPDIR/Laporan-sect.docx"
+"$PYTHON_BIN" "$PAGENUM_SCRIPT" "$TMPDIR/Laporan-sect.docx" "$REPORT"
+
+echo "=== DOCX BERHASIL DIBUAT ==="
+echo "Lokasi: $REPORT"

package/.agents/skills/laporan-generator/resources/build.sh

@@ -0,0 +1,102 @@
+#!/usr/bin/env bash
+set -e
+
+DIR="$(cd "$(dirname "$0")" && pwd)"
+if [ -n "$1" ]; then
+  OUTDIR="$1"
+elif [ -f "$(pwd)/metadata.yml" ] && [ -d "$(pwd)/chapters" ]; then
+  OUTDIR="$(pwd)"
+else
+  OUTDIR="$DIR"
+fi
+REPORT="$OUTDIR/Laporan.pdf"
+
+TMPDIR=$(mktemp -d)
+trap 'rm -rf "$TMPDIR"' EXIT
+
+FALLBACK_DIRS=(
+  "$OUTDIR"
+  "$DIR"
+  "$HOME/.agents/skills/laporan-generator/resources"
+)
+
+copy_asset() {
+  local asset="$1"
+  local dest="$2"
+  for base in "${FALLBACK_DIRS[@]}"; do
+    if [ -e "$base/$asset" ]; then
+      cp -r "$base/$asset" "$dest/"
+      return 0
+    fi
+  done
+  return 1
+}
+
+copy_asset "cover.md" "$TMPDIR" || true
+copy_asset "template.typ" "$TMPDIR" || true
+copy_asset "logo.jpg" "$TMPDIR" || true
+copy_asset "metadata.yml" "$TMPDIR" || true
+copy_asset "references.bib" "$TMPDIR" || true
+copy_asset "apa.csl" "$TMPDIR" || true
+copy_asset "presets" "$TMPDIR" || true
+
+if [ -d "$OUTDIR/chapters" ]; then
+  cp "$OUTDIR/chapters"/*.md "$TMPDIR/" 2>/dev/null || true
+  CHAPTER_FILES=$(find "$TMPDIR" -maxdepth 1 -name "bab*.md" | sort -V)
+  if [ -z "$CHAPTER_FILES" ]; then
+    echo "ERROR: Tidak ada berkas bab*.md di direktori chapters/."
+    exit 1
+  fi
+  INPUT_FILES=("$TMPDIR/cover.md")
+  while IFS= read -r f; do
+    [ -n "$f" ] && INPUT_FILES+=("$f")
+  done < <(find "$TMPDIR" -maxdepth 1 -name "bab*.md" | sort -V)
+else
+  echo "ERROR: Direktori chapters/ tidak ditemukan."
+  echo "Buat folder chapters/ dengan file bab laporan (contoh: bab1-pendahuluan.md dst)."
+  exit 1
+fi
+
+if [ -d "$OUTDIR/gambar" ]; then
+  cp -r "$OUTDIR/gambar" "$TMPDIR/"
+  IM_CONV="convert"
+  command -v magick >/dev/null 2>&1 && IM_CONV="magick"
+  find "$TMPDIR/gambar" -type f \( -name "*.png" -o -name "*.PNG" \) -exec $IM_CONV {} -alpha off {} \; 2>/dev/null || true
+fi
+
+cd "$TMPDIR"
+
+PRESET_NAME=$(grep -E '^[[:space:]]*(preset|margin_preset):' "$TMPDIR/metadata.yml" 2>/dev/null | head -n 1 | cut -d: -f2- | tr -d '"'\''\r\n ')
+PRESET_OPTS=()
+if [ -n "$PRESET_NAME" ] && [ -f "$TMPDIR/presets/${PRESET_NAME}.yml" ]; then
+  PRESET_OPTS=("--metadata-file=$TMPDIR/presets/${PRESET_NAME}.yml")
+elif [ -f "$TMPDIR/presets/standard.yml" ]; then
+  PRESET_OPTS=("--metadata-file=$TMPDIR/presets/standard.yml")
+fi
+
+if ! pandoc \
+  "${INPUT_FILES[@]}" \
+  --template="template.typ" \
+  "${PRESET_OPTS[@]}" \
+  --metadata-file="metadata.yml" \
+  --citeproc \
+  --bibliography="references.bib" \
+  --csl="apa.csl" \
+  --metadata=reference-section-title="DAFTAR PUSTAKA" \
+  --top-level-division=chapter \
+  --pdf-engine=typst \
+  --syntax-highlighting=none \
+  -o "$REPORT" 2>&1; then
+  echo ""
+  echo "[ERROR] BUILD GAGAL: Terjadi kesalahan saat kompilasi Pandoc/Typst."
+  echo "Kemungkinan penyebab & solusi:"
+  echo "  1. Sintaks YAML di metadata.yml tidak valid -> Cek docs/metadata-schema.md"
+  echo "  2. Berkas gambar tidak ditemukan atau rusak -> Cek path gambar di chapters/"
+  echo "  3. Sintaks Markdown tidak didukung -> Cek docs/troubleshooting.md"
+  echo "  4. Gunakan Docker jika ada masalah dependensi lokal: docker compose run --rm laporan-generator"
+  exit 1
+fi
+
+echo ""
+echo "=== PDF BERHASIL DIBUAT ==="
+echo "Lokasi: $REPORT"

package/.agents/skills/laporan-generator/resources/chapters/bab1-pendahuluan.md

@@ -0,0 +1,60 @@
+# PENDAHULUAN
+
+## Latar Belakang
+
+Penulisan laporan akademik merupakan kegiatan fundamental dalam ekosistem pendidikan tinggi dan penelitian. Mahasiswa, dosen, dan peneliti secara berkala menyusun dokumen formal seperti laporan praktikum, laporan proyek rekayasa perangkat lunak, tugas akhir, skripsi, tesis, hingga makalah ilmiah [@apa2020manual]. Standarisasi laporan akademik menuntut tingkat konsistensi visual yang ketat, meliputi pengaturan geometri halaman (margin), tipografi, spasi baris, penomoran berjenjang, penataan tabel dan gambar, hingga keakuratan sitasi daftar pustaka.
+
+Metode konvensional dalam penyusunan laporan akademik di Indonesia umumnya masih mengandalkan pengolah kata berbasis Graphical User Interface (GUI) seperti Microsoft Word. Meskipun populer dan mudah diakses, pendekatan ini memiliki sejumlah tantangan teknis:
+
+1. **Inkonsistensi Pemformatan dan Pergeseran Tata Letak** --- Penataan gaya (styles), margin, dan spasi yang dilakukan secara manual sering kali menghasilkan dokumen yang tidak seragam. Perubahan kecil pada paragraf awal kerap mengakibatkan pergeseran posisi gambar dan tabel pada halaman-halaman berikutnya (*layout drift*).
+
+2. **Kompleksitas Penomoran Ganda** --- Pedoman penulisan karya ilmiah di perguruan tinggi Indonesia mewajibkan struktur penomoran halaman ganda (*dual pagination*), yaitu angka Romawi kecil (*i, ii, iii*) untuk bagian pengantar (*front matter*) dan angka Arab (*1, 2, 3*) yang dimulai ulang (*restart*) dari angka 1 pada BAB I (*main body*). Pengaturan *section break* manual pada pengolah kata konvensional sering membingungkan dan rentan rusak saat dokumen disunting berulang kali [@iso2021openxml].
+
+3. **Ketiadaan Dukungan Version Control yang Efektif** --- Berkas dokumen biner atau XML terkompresi tidak dapat di-*diff* dan di-*merge* secara bersih menggunakan sistem kontrol versi seperti Git. Hal ini menyulitkan pelacakan riwayat revisi dan kolaborasi tim secara terdistribusi.
+
+4. **Ketergantungan dan Bobot Sistem Typesetting Tradisional** --- Penggunaan sistem typesetting klasik seperti LaTeX [@lamport1994latex; @knuth1984texbook] memberikan kualitas tipografi tinggi, namun memiliki kurva belajar yang curam serta ukuran instalasi distribusi TeX Live yang sangat besar (mencapai 4--5 GB) sehingga lambat dalam lingkungan CI/CD container.
+
+Untuk mengatasi permasalahan tersebut, paradigma pemisahan konten dari penyajian (*separation of concerns*) diimplementasikan melalui pipeline otomatisasi dokumen modern. Konten ditulis menggunakan format teks ringan **Markdown** [@gruber2004markdown; @commonmark2021], kemudian dikonversi secara terpadu oleh **Pandoc** [@pandoc2024] ke dalam dua engine keluaran:
+
+1. **Typst Engine** [@typst2024] sebagai sistem typesetting mutakhir yang cepat dan ringan untuk menghasilkan dokumen PDF berkualitas percetakan.
+2. **Multi-Pass DOCX Engine** dengan filter Lua kustom [@krewinkel2020pandoc] untuk menghasilkan dokumen Microsoft Word resmi yang memenuhi aturan penomoran halaman akademik.
+
+Pipeline ini diorkestrasi secara otomatis melalui antarmuka CLI terpadu dan skrip otomatisasi Bash [@gnu2024bash], serta didukung oleh lingkungan terisolasi yang dapat direproduksi (*reproducible*) menggunakan Nix Flakes [@dolstra2004nix] dan Docker [@merkel2014docker].
+
+## Rumusan Masalah
+
+Berdasarkan latar belakang di atas, rumusan masalah dalam penelitian dan pengembangan pipeline ini adalah:
+
+1. Bagaimana merancang arsitektur pipeline otomatisasi konversi dokumen akademik dari format Markdown menjadi PDF dan Microsoft Word (DOCX)?
+2. Bagaimana mengintegrasikan engine typesetting Typst dan filter Pandoc Lua untuk menghasilkan format laporan yang mematuhi standar penomoran akademik Indonesia?
+3. Bagaimana mekanisme penanganan penomoran halaman ganda (Romawi kecil pada *front matter* dan Arab pada isi bab) secara otomatis pada berkas DOCX dan PDF?
+4. Bagaimana merancang sistem preset deklaratif yang fleksibel untuk memfasilitasi keberagaman aturan format di berbagai perguruan tinggi?
+5. Bagaimana membangun lingkungan pengembangan dan build yang sepenuhnya terisolasi dan *reproducible* menggunakan Nix Flakes dan Docker container?
+
+## Tujuan
+
+Tujuan dari penyusunan laporan dan pengembangan sistem ini adalah:
+
+1. Menganalisis dan mengimplementasikan pipeline otomatisasi dokumen berbasis teks menggunakan Markdown, Pandoc, Typst, dan Lua Filters.
+2. Membangun template visual Typst (`template.typ`) dan template gaya Word (`reference.docx`) yang mematuhi standar tipografi akademik Indonesia (A4, margin standar/skripsi, Times New Roman/Libertinus Serif, spasi 1.5).
+3. Mengembangkan sistem injeksi OpenXML dan skrip dua tahap (*two-pass page numbering*) untuk menyinkronkan penomoran halaman aktual pada Daftar Isi dokumen DOCX.
+4. Mengembangkan sistem preset format kampus deklaratif (`presets/*.yml`) beserta modul linter dan pemindai otomatis (*PDF Guideline Scanner*).
+5. Mengintegrasikan test suite otomatis berorientasi assertions untuk memverifikasi keandalan struktur dan konten dokumen yang dihasilkan.
+
+## Manfaat
+
+Manfaat yang diharapkan dari proyek dan laporan ini meliputi:
+
+1. **Efisiensi Waktu dan Produktivitas** --- Penulis dan mahasiswa dapat berfokus penuh pada substansi konten tanpa terbebani oleh pengaturan tata letak manual yang berulang.
+2. **Standardisasi dan Kualitas Dokumen** --- Menghasilkan keluaran dokumen PDF dan DOCX yang konsisten, rapi, dan mematuhi kaidah penulisan ilmiah serta gaya sitasi APA Edisi ke-7 [@apa2020manual].
+3. **Kemudahan Kolaborasi dan Version Control** --- Memungkinkan pelacakan perubahan baris per baris (*line-by-line diff*) pada repositori Git.
+4. **Portabilitas Tinggi** --- Dokumentasi dapat dibangun secara instan di berbagai sistem operasi (Linux, macOS, Windows) dengan dependensi ringan.
+
+## Batasan Masalah
+
+Batasan masalah dalam implementasi sistem ini adalah:
+
+1. Format dokumen masukan menggunakan varian Pandoc Markdown dengan metadata berbasis YAML.
+2. Format keluaran utama mencakup dokumen PDF (dikompilasi melalui Typst) dan dokumen Microsoft Word (.docx).
+3. Standar sitasi dan daftar pustaka default mengacu pada Citation Style Language (CSL) APA Style Edisi ke-7.
+4. Pengujian otomatis dijalankan pada lingkungan sistem operasi berbasis Linux dan Nix/Docker container.

package/.agents/skills/laporan-generator/resources/chapters/bab2-tinjauan-pustaka.md

@@ -0,0 +1,83 @@
+# TINJAUAN PUSTAKA
+
+## Markdown dan Standardisasi Dokumen Teks
+
+### Sejarah dan Filosofi Markdown
+
+Markdown pertama kali diciptakan oleh John Gruber pada tahun 2004 sebagai format penulisan berbasis teks polos (*plain text*) yang dirancang agar mudah dibaca dan ditulis oleh manusia tanpa perlu proses kompilasi visual [@gruber2004markdown]. Filosofi dasar Markdown menempatkan keterbacaan (*human-readability*) sebagai prioritas tertinggi, di mana markup struktural tidak boleh mengaburkan arti teks substantif.
+
+Seiring meluasnya penggunaan Markdown dalam ekosistem rekayasa perangkat lunak, inisiatif standardisasi melahirkan spesifikasi formal CommonMark [@commonmark2021]. Varian Pandoc Markdown memperluas spesifikasi ini dengan mendukung sintaks akademik tingkat lanjut seperti tabel bergaya *pipe*, blok kode beranotasi, catatan kaki (*footnotes*), persamaan matematika LaTeX inline maupun display, metadata berbasis YAML front matter, dan sitasi bibliografi terintegrasi [@pandoc2024].
+
+### Sintaks Penulisan Akademik dalam Markdown
+
+Tabel berikut merangkum pemetaan sintaks Markdown yang digunakan dalam pipeline penyusunan laporan akademik:
+
+| Elemen Struktur | Sintaks Markdown | Contoh Penulisan | Representasi Keluaran |
+|:---|:---|:---|:---|
+| Judul Bab (Level 1) | `# Judul` | `# PENDAHULUAN` | BAB I PENDAHULUAN |
+| Sub-Bab (Level 2) | `## Sub Judul` | `## Latar Belakang` | 1.1. Latar Belakang |
+| Sub-Sub-Bab (Level 3) | `### Rincian` | `### Identifikasi Masalah` | 1.1.1 Rincian Masalah |
+| Sitasi Bibliografi | `[@citekey]` | `[@typst2024]` | (Mädje & Haug, 2024) |
+| Tabel Akademik | Pipe & Header Syntax | `| Kolom 1 | Kolom 2 |` | Tabel formal bergaris 0.5pt |
+| Gambar / Diagram | `![Keterangan](path)` | `![Arsitektur](gambar/flow.png)` | Gambar terpusat ber-caption |
+| Persamaan Matematika | `$...$` / `$$...$$` | `$E = m c^2$` | Notasi rumus terformat presisi |
+
+## Sistem Typesetting Modern: Typst
+
+### Arsitektur dan Prinsip Kerja Typst
+
+Typst adalah sistem typesetting berbasis markup yang dapat diprogram (*programmable markup-based typesetting system*) yang dikembangkan oleh Laurenz Mädje dan Martin Haug [@typst2024]. Typst dirancang sebagai respons terhadap keterbatasan sistem typesetting klasik seperti TeX dan LaTeX [@knuth1984texbook; @lamport1994latex] yang memiliki waktu kompilasi lambat, pesan galat yang sulit diurai, serta sintaks makro yang kompleks.
+
+Typst mengadopsi model kompilasi inkremental modern berbasis bahasa pemrograman Rust. Karakteristik utama Typst mencakup:
+
+1. **Kecepatan Kompilasi Tinggi** --- Typst mampu mengompilasi puluhan halaman dokumen dalam hitungan milidetik, memungkinkan pengalaman pratinjau langsung (*live reload*) yang sangat responsif.
+2. **Binary Ringan dan Mandiri** --- Ukuran binary Typst hanya berkisar 25 MB dan tidak membutuhkan dependensi eksternal dari repositori paket yang besar.
+3. **Tipografi Bawaan yang Portabel** --- Typst menyertakan font berkualitas tinggi seperti Libertinus Serif dan DejaVu Sans Mono langsung di dalam binary, sehingga menjamin konsistensi render di semua platform tanpa isu font hilang (*missing fonts*).
+4. **Model Tata Letak Deklaratif** --- Pengaturan margin halaman, penomoran heading bertingkat, dan aturan jeda halaman (*pagebreak*) dikonfigurasi melalui fungsi bawaan yang elegan seperti `#set page()`, `#set heading()`, dan `#show heading()`.
+
+## Pandoc dan Pemrosesan Dokumen Abstrak
+
+### Universal Document Converter
+
+Pandoc adalah perangkat lunak konversi dokumen universal yang dikembangkan oleh John MacFarlane [@pandoc2024]. Pandoc bekerja dengan membaca format masukan (seperti Markdown), mengonversinya ke dalam struktur pohon sintaks abstrak internal yang disebut *Abstract Syntax Tree* (AST), lalu mengekspor AST tersebut ke berbagai format target, termasuk Typst, HTML, EPUB, dan Microsoft Word (DOCX).
+
+### Filter Lua dan Ekstensibilitas AST
+
+Sejak versi 2.0, Pandoc menyediakan mesin scripting tertanam berbasis bahasa pemrograman Lua yang memungkinkan manipulasi AST sebelum proses penulisan dokumen akhir dilakukan [@krewinkel2020pandoc]. Dalam proyek ini, berkas `docx.lua` berperan penting dalam:
+
+1. Mendeteksi elemen heading level 1, 2, dan 3 untuk menambahkan penomoran otomatis berformat Romawi (`BAB I`) dan Arab (`1.1.`, `1.1.1`).
+2. Menghasilkan struktur XML untuk halaman sampul formal dan Daftar Isi yang terhubung dengan tautan hiperteks internal (*hyperlink anchor*).
+3. Mencegah penomoran ganda pada bagian khusus seperti KATA PENGANTAR dan DAFTAR PUSTAKA.
+
+## Arsitektur Dokumen Office Open XML (DOCX)
+
+Standar internasional ISO/IEC 29500 mendefinisikan Office Open XML (OpenXML) sebagai representasi berkas dokumen teks berbasis arsip ZIP yang berisi serangkaian berkas XML dan relasi strukturalnya [@iso2021openxml]. Berkas utama `word/document.xml` menyimpan seluruh elemen paragraf (`<w:p>`), teks (`<w:t>`), dan properti seksi (`<w:sectPr>`).
+
+Pengaturan *section break* (`<w:sectPr>`) menentukan perilaku penomoran halaman pada setiap bagian dokumen. Agar mematuhi kaidah akademik Indonesia, dokumen DOCX dibagi menjadi tiga seksi:
+1. **Seksi Sampul**: Referensi footer dihapus sehingga halaman pertama bersih tanpa nomor.
+2. **Seksi Front Matter**: Properti penomoran diset ke format Romawi kecil (`w:fmt="lowerRoman"` dan `w:start="1"`).
+3. **Seksi Main Body (BAB I)**: Properti penomoran di-reset menjadi format angka Arab (`w:fmt="decimal"` dan `w:start="1"`).
+
+## Pemrosesan Citra Digital dengan ImageMagick
+
+ImageMagick adalah rangkaian perangkat lunak untuk manipulasi citra digital via baris perintah [@imagemagick2024]. Pada pipeline dokumen ilmiah, diagram dan tangkapan layar sering kali berformat PNG dengan saluran transparansi (*alpha channel*). Saluran alfa yang tidak diatur dapat menimbulkan artefak visual seperti latar belakang hitam atau distorsi warna pada saat citra dirender ke dalam dokumen PDF. Pipeline menggunakan perintah normalisasi:
+
+```bash
+convert input.png -alpha off output.png
+```
+
+Perintah ini secara rekursif menonaktifkan transparansi dan menggantinya dengan latar belakang putih pekat, menjamin gambar tampil bersih pada media cetak.
+
+## Reproducibility dan Lingkungan Terisolasi
+
+### Manajemen Dependensi Berbasis Nix Flakes
+
+Nix adalah manajer paket murni fungsional yang menjamin *reproducible builds* dengan menyimpan setiap dependensi dalam direktori unik berbasis *cryptographic hash* di `/nix/store` [@dolstra2004nix]. Melalui berkas konfigurasi `flake.nix` dan berkas pengunci `flake.lock`, seluruh dependensi toolchain (Pandoc, Typst, ImageMagick, poppler-utils, dan LibreOffice) dapat diinisialisasi secara deterministik di berbagai mesin pengembang tanpa konflik dependensi sistem operasi.
+
+### Kontainerisasi Menggunakan Docker
+
+Docker menyediakan isolasi tingkat sistem operasi menggunakan teknologi Linux *cgroups* dan *namespaces* [@merkel2014docker; @love2010kernel]. Melalui `Dockerfile` multi-arsitektur (amd64 dan arm64), lingkungan kompilasi dokumen dapat dijalankan langsung pada platform apapun yang mendukung runtime container tanpa perlu instalasi perangkat lunak lokal.
+
+## Standar Sitasi Akademik APA Edisi ke-7
+
+Karya ilmiah dan laporan akademik mengadopsi standar pengutipan dan penulisan daftar pustaka berdasarkan *Publication Manual of the American Psychological Association* (APA) Edisi ke-7 [@apa2020manual]. Standar APA menerapkan sistem pengutipan Nama Penulis dan Tahun Penerbitan (*Author-Date System*), misalnya `(MacFarlane, 2024)` untuk sitasi dalam kurung (*parenthetical*) atau `MacFarlane (2024)` untuk sitasi naratif. Pemrosesan sitasi pada pipeline dijalankan secara otomatis oleh mesin `pandoc-citeproc` menggunakan berkas definisi gaya `apa.csl` dan basis data pustaka BibTeX `references.bib`.

package/.agents/skills/laporan-generator/resources/chapters/bab3-metodologi.md

@@ -0,0 +1,116 @@
+# METODOLOGI
+
+## Arsitektur Sistem dan Alur Kerja Pipeline
+
+Pengembangan sistem **Laporan Generator** dirancang dengan prinsip modularitas tinggi dan pemisahan lapisan tugas (*separation of concerns*). Arsitektur sistem dibagi menjadi tiga lapisan utama: Lapisan Masukan (*Input Layer*), Lapisan Pemrosesan (*Processing Layer*), dan Lapisan Keluaran (*Output Layer*).
+
+```
++-------------------------------------------------------------------------+
+|                              INPUT LAYER                                |
+|  chapters/bab*.md  |  cover.md  |  metadata.yml  |  presets/*.yml       |
+|  references.bib    |  apa.csl   |  logo.jpg      |  gambar/*            |
++-------------------------------------------------------------------------+
+                                    |
+            +-----------------------+-----------------------+
+            |                                               |
+            v                                               v
++---------------------------------------+ +-------------------------------+
+|       PIPELINE 1: TYPST (PDF)         | |   PIPELINE 2: DOCX MULTI-PASS |
+|                                       | |                               |
+| 1. ImageMagick Alpha Normalization    | | 1. Pandoc + docx.lua Filter   |
+| 2. Preset Metadata Extraction         | | 2. Base reference.docx Styling|
+| 3. Pandoc AST + Citeproc Processing   | | 3. finalize-docx.py (3 Sect)  |
+| 4. Typst Typesetting Engine Render    | | 4. docx-pagenum.py (Page Inj) |
++---------------------------------------+ +-------------------------------+
+            |                                               |
+            v                                               v
++---------------------------------------+ +-------------------------------+
+|             Laporan.pdf               | |          Laporan.docx         |
+| (Clean Vector, APA Style, Typst)      | | (Roman Front, Arabic Body)    |
++---------------------------------------+ +-------------------------------+
+```
+
+## Perancangan Template Visual Typst (`template.typ`)
+
+Template visual Typst berfungsi sebagai pengatur tata letak halaman, tipografi, dan penomoran dokumen PDF. Template dirancang fleksibel untuk mendukung preset margin dinamis dan penomoran otomatis.
+
+### Pengaturan Geometri Halaman dan Margin
+
+Geometri halaman diatur secara adaptif melalui blok evaluasi kondisi Typst:
+
+```typst
+#set page(
+  paper: "a4",
+  margin: doc-margin,
+  numbering: none,
+)
+```
+
+Variabel `doc-margin` dievaluasi dari berkas konfigurasi preset (`margin_top`, `margin_bottom`, `margin_left`, `margin_right`) yang diinjeksikan oleh Pandoc pada saat kompilasi.
+
+### Penomoran Heading Bertingkat
+
+Penomoran judul bab dan sub-bab ditangani melalui fungsi callback `#set heading()`:
+
+```typst
+#set heading(numbering: (..ns) => {
+  if ns.len() == 1 {
+    "BAB " + numbering("I", ns.at(0))
+  } else if ns.len() == 2 {
+    numbering("1.1.", ..ns)
+  } else {
+    numbering("1.1.1", ..ns)
+  }
+})
+```
+
+Penanganan khusus diimplementasikan pada `#show heading.where(level: 1)` untuk menghasilkan jeda halaman otomatis (*pagebreak*) dan meletakkan nomor bab ("BAB I") di atas judul bab dengan gaya huruf kapital tebal 14pt di tengah halaman.
+
+### Algoritma Keseimbangan Judul Sampul (*Balanced Title Splitting*)
+
+Untuk mencegah terjadinya fenomena kata menggantung sendirian di baris bawah (*orphan words*), template mengintegrasikan fungsi pembagi judul berbasis Dynamic Programming (`balance-split`). Algoritma ini mengevaluasi jumlah karakter per baris dan meminimalisir fungsi biaya (*cost function*) agar panjang tiap baris judul sampul depan simetris menyerupai bentuk piramida terbalik.
+
+## Perancangan Pipeline Dokumen Microsoft Word (DOCX)
+
+Penyusunan dokumen DOCX resmi memerlukan integrasi tiga komponen pemrosesan berurutan:
+
+### Filter Lua docx.lua
+Filter Lua mengintersepsi pohon sintaks abstrak (AST) Pandoc. Fungsi `Header(el)` menghitung indeks bab dan sub-bab serta menyusun entri Daftar Isi ber-hyperlink. Fungsi `Pandoc(doc)` membangun halaman sampul formal menggantikan title block bawaan Pandoc.
+
+### Partisi Tiga Seksi Dokumen finalize-docx.py
+Skrip Python memanipulasi struktur OpenXML berkas `word/document.xml` dengan membagi dokumen ke dalam tiga penanda seksi (`w:sectPr`):
+- **Seksi 1 (Sampul)**: Menghapus elemen `<w:footerReference>` sehingga nomor halaman tidak tampil pada sampul luar.
+- **Seksi 2 (Front Matter)**: Menginjeksikan `<w:pgNumType w:fmt="lowerRoman" w:start="1"/>` agar halaman KATA PENGANTAR dan DAFTAR ISI diberi nomor *i, ii, iii*.
+- **Seksi 3 (Main Body)**: Menginjeksikan `<w:pgNumType w:fmt="decimal" w:start="1"/>` sebelum judul BAB I agar penomoran dimulai ulang dari angka 1, 2, 3.
+
+### Sinkronisasi Nomor Halaman Aktual docx-pagenum.py
+Untuk memastikan Daftar Isi pada dokumen DOCX menampilkan nomor halaman yang akurat di seluruh aplikasi pengolah kata, skrip `docx-pagenum.py` melakukan:
+1. Render headless berkas DOCX menjadi PDF temporer menggunakan LibreOffice (`soffice --headless`).
+2. Ekstraksi teks per halaman menggunakan utilitas `pdftotext`.
+3. Pencocokan teks heading dengan footer halaman aktual.
+4. Pengisian nilai cache pada field OpenXML `<w:instrText>PAGEREF</w:instrText>`.
+
+## Sistem Preset Kampus Deklaratif
+
+Untuk memfasilitasi keberagaman pedoman penulisan skripsi di berbagai perguruan tinggi di Indonesia, arsitektur preset deklaratif (`presets/*.yml`) dibangun dengan skema standar:
+
+| Kategori Parameter | Kunci Konfigurasi | Contoh Nilai | Keterangan |
+|:---|:---|:---|:---|
+| **Identitas** | `preset_id`, `name` | `ui-skripsi`, `itb-ta` | Identifikasi unik dan nama institusi |
+| **Geometri Margin** | `margin_top`, `margin_left` | `4cm`, `3cm`, `2.5cm` | Batas tepi kertas A4 |
+| **Tipografi** | `font_family`, `font_size` | `Libertinus Serif`, `12pt` | Jenis font dan ukuran teks isi |
+| **Spasi & Indentasi** | `line_spacing`, `first_line_indent` | `0.75em`, `1.25cm` | Spasi 1.5 dan indent alinea |
+| **Sampul (Cover)** | `cover_show_lecturer` | `true` / `false` | Pengaturan tampilan dosen pembimbing |
+
+Sistem ini didukung oleh dua utilitas otomatis:
+1. **`scripts/scan-preset.py`**: Mengekstraksi aturan margin, spasi, dan font secara otomatis dari berkas PDF Buku Pedoman Skripsi kampus baru menggunakan regex heuristik.
+2. **`scripts/validate-preset.py`**: Melakukan validasi sintaks dan verifikasi skema pada seluruh berkas preset YAML sebelum digunakan pada proses kompilasi.
+
+## Metodologi Pengujian dan Verifikasi
+
+Keandalan seluruh komponen pipeline diuji menggunakan test suite otomatis (`test.sh`) yang mencakup 20 kategori pengujian dan 78 *test assertions*. Pengujian memverifikasi:
+1. Ketersediaan dependensi dan kelengkapan struktur direktori proyek.
+2. Validitas metadata YAML dan integritas basis data sitasi BibTeX.
+3. Keterbacaan teks berkas PDF dan kelayakan ukuran berkas keluaran.
+4. Validitas struktur OpenXML dokumen DOCX (pemeriksaan 3 seksi, format nomor Romawi/Arab, gaya font Times New Roman, dan field TOC).
+5. Integritas sistem preset kampus, fungsionalitas scanner PDF, dan CLI helper.

package/.agents/skills/laporan-generator/resources/chapters/bab4-hasil-dan-pembahasan.md

@@ -0,0 +1,93 @@
+# HASIL DAN PEMBAHASAN
+
+## Struktur Berkas dan Implementasi Sistem
+
+Implementasi pipeline **Laporan Generator** menghasilkan struktur direktori yang modular dan terorganisasi secara sistematis:
+
+```
+laporan-generator/
+|-- laporan                  # CLI Helper terpadu (build, init, preset, check, test)
+|-- build.sh                 # Skrip build utama PDF (Typst engine)
+|-- Makefile                 # Target otomasi (build, docx, html, watch, view, clean)
+|-- template.typ             # Template visual Typst (font, margin, heading)
+|-- docx.lua                 # Filter Lua penomoran bab & sampul DOCX
+|-- reference.docx           # Template gaya Microsoft Word (A4, TNR 12pt)
+|-- metadata.yml             # Konfigurasi judul, penulis, dosen, institusi, preset
+|-- references.bib           # Basis data daftar pustaka (format BibTeX)
+|-- apa.csl                  # Aturan sitasi standar APA Edisi ke-7
+|-- cover.md                 # Kata pengantar & outline front matter
+|-- chapters/                # Konten laporan modular (BAB I s/d BAB V)
+|-- presets/                 # Konfigurasi format kampus (UI, ITB, UGM, ITS, Standard)
+|-- scripts/                 # Utilitas Python (scan-preset, validate, docx-pagenum)
+|-- flake.nix / flake.lock   # Lingkungan hermetik Nix Flake
+|-- Dockerfile               # Kontainer build multi-arsitektur (amd64 / arm64)
+|-- docker-compose.yml       # Orkestrasi kontainer Docker dengan pemetaan user
+|-- prompt.md                # Panduan instruksi agen AI (OpenCode, Claude, Antigravity)
+\-- test.sh                  # Suite pengujian otomatis (78 assertions)
+```
+
+## Evaluasi Hasil Keluaran Dokumen PDF (Typst Engine)
+
+Kompilasi dokumen PDF menggunakan Typst menghasilkan dokumen akademik dengan kualitas tipografi tingkat tinggi. Beberapa pencapaian visual utama meliputi:
+
+1. **Struktur Penomoran Bab Dua Baris** --- Sesuai dengan pedoman penulisan karya ilmiah di Indonesia, judul bab level 1 dirender dalam dua baris simetris: baris pertama berisi prefix angka Romawi tebal (contoh: `BAB I`), dan baris kedua berisi nama judul bab dalam huruf kapital tebal 14pt (contoh: `PENDAHULUAN`).
+2. **Kerapian Spasi dan Indentasi Paragraf** --- Teks isi menggunakan font Libertinus Serif 12pt dengan spasi baris 1.5 (`leading: 0.75em`) dan perataan rata kanan-kiri (*justified*). Baris pertama setiap alinea diindentasi secara presisi sebesar 1.25 cm.
+3. **Penyusunan Tabel dan Gambar yang Bersih** --- Seluruh gambar diposisikan di tengah halaman dengan keterangan caption di bagian bawah. Tabel akademik bergaris tipis 0.5pt abu-abu tanpa border vertikal berlebih.
+4. **Sitasi Otomatis Format APA** --- Seluruh pengutipan dalam teks seperti `(Mädje & Haug, 2024)` secara otomatis ditautkan ke bagian DAFTAR PUSTAKA di akhir dokumen dengan penataan *hanging indent* 1.25 cm.
+
+## Evaluasi Hasil Keluaran Dokumen Word (DOCX Multi-Pass)
+
+Dokumen Microsoft Word (`Laporan.docx`) yang dihasilkan melalui proses multi-pass berhasil memenuhi persyaratan format formal:
+
+1. **Pemisahan Seksi dan Penomoran Halaman** --- Sampul depan tampil bersih tanpa nomor halaman. Bagian KATA PENGANTAR dan DAFTAR ISI memiliki penomoran angka Romawi kecil (*i, ii*). Pada awal BAB I, penomoran halaman berhasil dimulai ulang (*restart*) dari angka Arab 1 (*1, 2, 3...*).
+2. **Daftar Isi Otomatis Terhubung (Hyperlinked TOC)** --- Entri Daftar Isi dihubungkan dengan *hyperlink internal* dan menampilkan nomor halaman aktual secara presisi berkat proses injeksi nilai cache oleh `docx-pagenum.py`.
+3. **Konsistensi Gaya dan Font** --- Dokumen Word menggunakan font Times New Roman berukuran 12pt pada teks normal dan 14pt tebal pada Heading 1, memastikan paritas visual yang identik dengan dokumen PDF.
+
+## Analisis Komparasi Kinerja dan Efisiensi
+
+Tabel berikut menyajikan perbandingan komprehensif antara pipeline **Laporan Generator (Typst Engine)**, pipeline berbasis **LaTeX Tradisional**, dan penyusunan manual menggunakan **Microsoft Word**:
+
+| Parameter Evaluasi | Laporan Generator (Typst) | LaTeX Tradisional | Microsoft Word Manual |
+|:---|:---|:---|:---|
+| **Waktu Kompilasi Dokumen** | **< 1.0 detik** | 10 -- 30 detik | Tidak ada (Manual) |
+| **Ukuran Toolchain / Instalasi** | **~25 MB** (Binary Typst) | ~4.5 GB (TeX Live) | ~2.5 GB (MS Office) |
+| **Dukungan Version Control (Git)** | **Sangat Baik** (Plain Text) | Sangat Baik (Plain Text)| Sangat Buruk (Binary DOCX)|
+| **Keluaran Format Ganda** | **PDF & DOCX Sinkron** | Hanya PDF | Hanya DOCX |
+| **Penanganan Layout Drift** | **Deterministik & Otomatis** | Deterministik | Sering Bergeser Manual |
+| **Konfigurasi Format Kampus** | **1 Baris YAML Preset** | Modifikasi .cls/macro | Setting Style GUI Manual |
+| **Integrasi AI Agent** | **Terpadu (`prompt.md`)** | Kustom / Manual | Terbatas |
+
+## Hasil Pengujian Otomatis (Automated Test Suite)
+
+Pengujian menyeluruh menggunakan skrip `test.sh` dilakukan untuk memverifikasi fungsionalitas seluruh komponen. Hasil eksekusi pengujian pada lingkungan terisolasi menghasilkan status lulus 100%:
+
+```
+=== Test Suite: Laporan Generator ===
+
+[T1] Dependency check                               [OK] 3/3 tools
+[T2] File structure check                           [OK] 8/8 files
+[T3] Metadata check                                 [OK] 2/2 checks
+[T4] Template check                                 [OK] 3/3 checks
+[T5] .gitignore check                               [OK] 2/2 checks
+[T6] Docker check                                   [OK] 2/2 checks
+[T7] Build PDF (Typst Engine)                       [OK] PDF Valid (458 KB)
+[T8] No box-drawing characters                      [OK] Clean text
+[T9] No manual numbering in headings                [OK] Valid AST
+[T10] Metadata fields check                         [OK] 2/2 fields
+[T11] References check (BibTeX structure)           [OK] Valid BibTeX
+[T12] Makefile targets check                        [OK] Valid targets
+[T13] Recursive image processing check              [OK] Recursive find
+[T14] PDF content readability check                 [OK] Readable text
+[T15] Typst engine check                            [OK] Verified
+[T16] DOCX export check (Styles, XML, Sect, Pages)  [OK] 21/21 assertions
+[T17] CLI Helper and Preset Guide check             [OK] 4/4 checks
+[T18] Preset Architecture & University Presets      [OK] 10/10 checks
+[T19] PDF Preset Scanner & Extractor check          [OK] 5/5 checks
+[T20] Preset Linter, Validator & Diff CLI check     [OK] 4/4 checks
+
+========================================================================
+Hasil Akhir: 78 assertions passed, 0 failed (100% Success Rate)
+========================================================================
+```
+
+Seluruh 78 pengujian terotomatisasi berhasil dieksekusi tanpa galat, membuktikan bahwa pipeline memiliki stabilitas tinggi, kompatibilitas lintas platform yang solid, dan siap digunakan dalam produksi.

package/.agents/skills/laporan-generator/resources/chapters/bab5-penutup.md

@@ -0,0 +1,27 @@
+# PENUTUP
+
+## Kesimpulan
+
+Berdasarkan perancangan, implementasi, dan serangkaian pengujian yang telah dilakukan pada proyek **Laporan Generator**, dapat ditarik beberapa kesimpulan utama:
+
+1. **Efektivitas Paradigma Pemisahan Konten dan Penyajian** --- Penerapan format teks ringan Markdown sebagai lapisan penulisan konten yang dipisahkan dari lapisan tata letak (*layout*) terbukti secara signifikan meningkatkan fokus penulis, mengeliminasi masalah pergeseran tata letak (*layout drift*), serta memudahkan kolaborasi tim melalui sistem kontrol versi Git.
+
+2. **Keunggulan Engine Typesetting Typst** --- Penggunaan Typst sebagai mesin kompilasi PDF utama berhasil memangkas ukuran dependensi sistem dari ~4.5 GB (distribusi TeX Live) menjadi hanya ~25 MB (binary mandiri Typst) dengan kecepatan kompilasi sub-detik, sembari tetap mempertahankan standar tipografi akademik profesional dan tata letak yang presisi.
+
+3. **Keberhasilan Solusi Multi-Pass DOCX** --- Pendekatan multi-pass yang menggabungkan filter Pandoc Lua (`docx.lua`), manipulasi struktur OpenXML (`finalize-docx.py`), dan sinkronisasi nomor halaman via LibreOffice headless (`docx-pagenum.py`) berhasil mewujudkan dokumen Microsoft Word resmi dengan pemisahan seksi yang tepat (sampul tanpa nomor, *front matter* bernomor Romawi *i, ii*, dan isi bab yang dimulai ulang dari angka Arab 1).
+
+4. **Fleksibilitas Sistem Preset Kampus dan Alat Bantu Otomasi** --- Kehadiran sistem preset deklaratif (`presets/*.yml`), didukung oleh pemindai pedoman PDF otomatis (`scan-preset.py`), linter validasi skema (`validate-preset.py`), serta antarmuka baris perintah terpadu (`./laporan`), memberikan kemudahan bagi sivitas akademika di berbagai universitas di Indonesia untuk menyesuaikan format laporan secara instan.
+
+5. **Keandalan dan Keterulangan Sistem (*Reproducibility*)** --- Dukungan konfigurasi Nix Flakes (`flake.nix`) dan kontainer Docker menjamin bahwa pipeline dapat dijalankan secara identik di seluruh sistem operasi pengembang (Linux, macOS, Windows) dengan tingkat kelulusan pengujian 100% pada 78 *test assertions*.
+
+## Saran
+
+Beberapa peluang pengembangan lanjutan yang direkomendasikan untuk meningkatkan fungsionalitas dan adopsi proyek ini di masa depan antara lain:
+
+1. **Pengembangan Antarmuka Web (Web-Based Interactive Generator)** --- Membangun antarmuka berbasis web atau aplikasi WebAssembly (Wasm) agar pengguna tanpa akses terminal atau baris perintah dapat menyunting dan mengunduh laporan langsung melalui peramban.
+
+2. **Ekspansi Basis Data Preset Perguruan Tinggi** --- Menambahkan koleksi preset resmi untuk universitas-universitas besar lainnya di Indonesia, seperti Universitas Diponegoro (UNDIP), Universitas Airlangga (UNAIR), Universitas Brawijaya (UB), Universitas Telkom (Tel-U), dan BINUS University.
+
+3. **Penyediaan Wrapper Baris Perintah PowerShell (`laporan.ps1`)** --- Mengembangkan skrip pembungkus PowerShell native guna menyempurnakan pengalaman pengembang (*developer experience*) bagi pengguna sistem operasi Windows murni tanpa ketergantungan pada WSL atau Git Bash.
+
+4. **Integrasi Ekstensi Editor (VS Code / Antigravity IDE Plugin)** --- Menyediakan plugin editor yang menyertakan fitur cuplikan kode (*snippets*), validasi sitasi BibTeX otomatis, dan pratinjau dokumen (*live preview*) langsung di dalam lingkungan pengembangan terintegrasi.