4.5 KiB
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
- Provide a stable structured report format.
- Validate report input.
- Render professional PDF reports using Typst.
- Support configurable branding and presentation.
- Remain usable as a standalone tool.
- 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:
- valid example report renders;
- invalid input is rejected;
- missing optional fields do not break rendering;
- branding can be replaced;
- output does not require external Beffroi repositories.
Development principles
Reportist's production interface must be Make, shell, and Typst, with jq only
where shell needs structured JSON handling. Python may exist only in tests/,
must run through a uv-managed virtual environment, and must not be called by
production validation or rendering.
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.