# Beffroi Reports Create consistent technical PDF reports from readable, version-controlled YAML. Typst handles the layout, while each report remains easy to edit, review, and diff in Git. ## Quick overview ### Requirements - [Typst](https://typst.app/) available as `typst` - Bash and standard Unix command-line utilities No additional Typst packages are required. ### Create and render a report 1. Copy an existing file in `reports/`, or start with the [minimal boilerplate](docs/examples.md#minimal-report). 2. Edit the YAML content. 3. Render it: ```bash ./render.sh reports/my-report.yaml ``` The PDF is written to `build/my-report.pdf`. To render every report recursively: ```bash ./render.sh --all ``` Subfolders are preserved: `reports/customer/report.yaml` produces `build/customer/report.pdf`, including in ZIP exports. `build/diagnostics/` is reserved for diagnostic PDFs. Remove old PDFs before regenerating all reports: ```bash ./render.sh --clean --all ./render-diagnostics.sh --clean --all "Your Name" ``` Each command cleans only its own report category. With a single input, `--clean` removes only that input's PDF. Other files are retained. Set the report's purpose explicitly: ```yaml report_type: technical # Investigation, engineering review, or handoff # report_type: briefing # Concise findings for stakeholders ``` See [Report types](docs/writing-reports.md#report-types) for the distinction. Every report must include an author and date, and may select a theme: ```yaml theme: default # Also available: cic, eridani metadata: Date: "2026-09-05" Author: "Your Name" ``` Compilation stops with an actionable error if `metadata.Date` or `metadata.Author` is absent or empty. ### Generate a Windows diagnostics assessment Convert a WinDiagnostics schema 1 or 2 JSON capture into a concise, exception-focused PDF: ```bash ./render-diagnostics.sh diagnostics/windows_system_report_PC.json "Your Name" cic ``` The theme argument is optional and defaults to `default`. Render every `.json` dump under `diagnostics/` recursively with: ```bash ./render-diagnostics.sh --all "Your Name" ``` The result is written under `build/diagnostics/`. Its first page is a short health summary; later pages deduplicate errors, retain useful evidence, and record how every collected section was treated without reproducing large lists of healthy inventory. See [Diagnostics reports](docs/diagnostics.md), including the [safe finding-closure guide](docs/diagnostics.md#closing-findings-safely). You can also invoke Typst directly: ```bash typst compile \ --input report=reports/my-report.yaml \ report.typ \ build/my-report.pdf ``` ### Project layout ```text report.typ Typst entry point modules/ Shared Typst layouts and diagnostics normalization render.sh Convenience build script config/ Shared YAML themes, diagnostics rules, and watchlist assets/ Logos and other static assets reports/ Authoritative YAML report sources build/ Generated PDFs docs/ Detailed documentation and examples ``` ## Detailed guides - [Writing reports](docs/writing-reports.md) — field reference, content blocks, report types, status values, and authoring guidance. - [Examples and boilerplate](docs/examples.md) — complete minimal and full reports ready to copy and adapt. - [Advanced setup](docs/advanced-setup.md) — nested archives, customization, YAML themes, automation, and Git policy. - [Diagnostics reports](docs/diagnostics.md) — WinDiagnostics synthesis, filtering policy, usage, safe finding closure, and limitations. ## Core principle YAML files are the authoritative report sources. Keep content and report state in YAML, and keep visual presentation in `modules/model.typ`. For example, prefer `severity: high` over fields that specify colors or fonts. Generated PDFs are reproducible artifacts suitable for email, handoff, printing, tickets, and archival. Whether they are committed to Git is a project policy; see [Generated PDF policy](docs/advanced-setup.md#generated-pdf-policy). ## License See [LICENSE](LICENSE). ### Jenkins publication Jenkins renders YAML reports and JSON diagnostics, validates the PDFs, and publishes encrypted archives to the same `/mnt/books` mount used by the books: - `/mnt/books/Reports/Reports.zip`: YAML report PDFs, preserving subfolders. - `/mnt/books/Reports/Diagnostics.zip`: diagnostic PDFs, preserving subfolders. Only the ZIPs are archived as Jenkins artifacts. The agent needs `uv` and Python 3, access to PyPI, and write access to `/mnt/books/Reports`. `DIAGNOSTICS_AUTHOR` defaults to Beffroi. Jenkins installs pinned [pyzipper](https://pypi.org/project/pyzipper/) into `.ci-venv` and creates AES-256 ZIPs without a system `zip` executable. Extract with an AES-capable ZIP reader, such as 7-Zip. Jenkins binds the **Secret text** credential `typst-reporter-publish-password` to `REPORT_ZIP_PASSWORD` only during the packaging stage. The credential must be accessible to this job. The packaging script requires a nonempty password and reads it from the environment with shell tracing disabled; there is no fallback password. The next successful publication replaces both ZIPs using this secret. To package an existing local build: ```bash uv venv --allow-existing .ci-venv uv pip install --python .ci-venv/bin/python -r tools/packaging-requirements.txt # Prompt without echoing the password or storing it in shell history. set +x read -r -s -p 'Archive password: ' REPORT_ZIP_PASSWORD printf '\n' export REPORT_ZIP_PASSWORD PACKAGING_PYTHON=.ci-venv/bin/python ./tools/package-reports.sh unset REPORT_ZIP_PASSWORD ```