reportist/AGENT.md

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

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