# 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 ``` 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 Full WinDiagnostics text dump into a concise, exception-focused PDF: ```bash ./render-diagnostics.sh diagnostics/windows_system_report_PC.txt "Your Name" cic ``` The theme argument is optional and defaults to `default`. Render every `.txt` 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 model.typ Shared layout and YAML renderer render.sh Convenience build script 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 `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).