# Editing, building, and publishing ## Setup and editing Run `./beffroi.sh bootstrap` after cloning to initialize the pinned Reports and Reportist submodules. `./beffroi.sh doctor` checks the core tools. Edit source files in `reports/reports/` or add a raw capture to `reports/diagnostics/`; implementation changes belong in Reportist. Consult [the report input contract](../reporter/docs/report-contract.md) for authored YAML/JSON and [the diagnostic plugin](../reporter/plugins/diagnostics/README.md) for raw capture behavior. Render one source while editing: ```bash ./beffroi.sh report reports/reports/2026-09-04-clevo-handoff.yaml /tmp/report.pdf ./beffroi.sh diagnostic-pdf reports/diagnostics/windows_system_report_DESKTOP-SAU019H_20260915_121057.json /tmp/diagnostic.pdf ``` `capture-pdf` is a compatibility alias for `diagnostic-pdf`. For evidence processing, `./beffroi.sh diagnostic CAPTURE EVIDENCE_ROOT NEW_OUTPUT_DIR REFERENCE_TIME [AUTHOR] [THEME]` writes both `diagnostic.json` and `report.pdf`. The PDF renderer reads the raw capture directly. ## Local verification Run `./beffroi.sh test` before publishing. It executes Reportist's report and diagnostic suites, checks the stored source set, builds all PDFs, and compares all seven reports and ten diagnostics to the recorded legacy baseline. The original renderer in `legacy/typst_reporter` is retained as a read-only local reference. Its ignored `build/` PDFs enable raster comparison when available; CI can still check recorded page counts and text hashes without them. Build the complete publication with: ```bash ./beffroi.sh all build/publication --replace ./beffroi.sh all build/publication --replace --include-json ``` `--replace` builds beside the existing directory, then swaps it after success. `--include-json` adds authored report JSON exports and copies raw capture JSON beside the PDFs. Single-document rendering refuses an existing PDF unless `--force` is supplied. ## CI and delivery On `main`, the macro Jenkinsfile checks out pinned submodules, runs tests, builds the publication, creates password-protected AES ZIP archives, archives them as CI artifacts, and copies `Reports.zip` and `Diagnostics.zip` to its configured deployment directory. Jenkins supplies `REPORT_ZIP_PASSWORD` from credentials. The password must not be committed or printed. The standalone Reportist Jenkinsfile runs plugin tests. Reports Jenkinsfile checks YAML and JSON syntax only. `./beffroi.sh package BUILD_DIR ARTIFACT_DIR` runs the same packaging locally when `REPORT_ZIP_PASSWORD` is set. It requires `uv` and pinned `pyzipper`. Package output is checked by reopening the archives. Publication and deployment are external actions; review generated sources and artifacts before pushing a change that triggers the main-branch pipeline.