reportist/AGENT.md

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

  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

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.