4.4 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. 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.