# AGENT.md — Reportist ## Mission Reportist is a generic structured report renderer. Its responsibility is strictly: YAML / JSON ↓ Reportist ↓ Typst ↓ PDF Reportist must remain independent from any specific diagnostic system, organisation, incident database, or reporting workflow. The existing `typst_reporter` repository may be used as a migration source, but this repository is a clean implementation with intentionally defined boundaries. --- ## Primary goals 1. Provide a stable structured report format. 2. Validate report input. 3. Render professional PDF reports using Typst. 4. Support configurable branding and presentation. 5. Remain usable as a standalone tool. 6. Preserve the sober corporate visual style of the original `typst_reporter`. --- ## Non-goals Reportist is NOT responsible for: - collecting diagnostic information; - interpreting Windows events; - generating diagnostic conclusions; - storing historical reports; - managing incidents; - knowing what Beffroi is; - knowing what WinDiagnostics is. Do not introduce dependencies on these concepts. --- ## Migration source The existing `typst_reporter` project contains useful existing work. When migrating from it, classify files before copying them. Migrate: - generic Typst templates; - generic components; - generic rendering scripts; - generic styling; - reusable validation logic. Do NOT migrate: - actual Beffroi reports; - investigation history; - diagnostic output; - machine-specific information; - hard-coded Beffroi branding. Historical reports will eventually live in `beffroi-reports`. --- ## Input format Reportist should define and document its input format. Prefer: schema/report.schema.json Reports should carry an explicit schema version. Conceptually: schema_version metadata branding title summary findings recommendations actions appendices Do not blindly implement this structure if the existing report format already provides a better representation. Preserve useful compatibility with existing reports where practical. --- ## Branding Organisation-specific branding must be supplied as data/assets. Do not hard-code: - organisation name; - logo; - author; - department; - machine name; - incident terminology. A Beffroi report should be possible, but Reportist should work equally well for an unrelated personal project. --- ## CLI Aim for a simple interface. For example: reportist report.yaml and: reportist report.yaml --output report.pdf During early development, a wrapper such as: ./render.sh report.yaml is acceptable. Do not make the CLI unnecessarily complex. --- ## Project structure Prefer a structure approximately like: src/ templates/ components/ schema/ examples/ tests/ assets/ Adapt this structure when there is a good reason. Do not create empty architecture merely to satisfy this example. --- ## Examples Maintain at least one synthetic example: examples/example-report.yaml It should exercise the important renderer functionality without containing private or machine-specific information. The example should render successfully as part of testing. --- ## Compatibility Treat the report schema as a public interface. Once versions are used by external report repositories, avoid breaking them without: - incrementing the schema version; - documenting the change; - providing a migration path when reasonable. --- ## Testing At minimum test: 1. valid example report renders; 2. invalid input is rejected; 3. missing optional fields do not break rendering; 4. branding can be replaced; 5. output does not require external Beffroi repositories. --- ## Development principles Prefer: - explicit schemas; - simple tooling; - deterministic output; - readable Typst; - clear error messages; - few dependencies. Avoid: - hidden coupling; - absolute paths; - report-specific hacks; - duplicated rendering logic. --- ## Definition of success A fresh clone of Reportist can render its example PDF without: - WinDiagnostics; - win-diagnostics; - beffroi-reports; - beffroi-reporting. If another project needs to know Reportist internals in order to produce a report, improve the input contract instead.