diff --git a/AGENT.md b/AGENT.md new file mode 100644 index 0000000..68dc754 --- /dev/null +++ b/AGENT.md @@ -0,0 +1,235 @@ +# 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. \ No newline at end of file