# Writing reports Reports are YAML files stored under `reports/`. The filename determines the PDF filename, while the YAML determines its content. ## Top-level fields | Field | Purpose | Required | | --- | --- | --- | | `title` | Main report heading | Recommended | | `id` | Report or ticket identifier | No | | `organization` | Name displayed in the header | No | | `subtitle` | Context below the title | No | | `report_type` | Report purpose: `technical` or `briefing` | Recommended | | `theme` | Visual theme: `default`, `cic`, or `eridani` | No; defaults to `default` | | `status` | Overall workflow state | No | | `severity` | Overall urgency | No | | `metadata` | Key/value facts; must contain `Date` and `Author` | **Yes** | | `summary` | Executive summary callout | No | | `timeline` | Chronological event table | No | | `findings` | Evidence and assessments | No | | `sections` | Free-form structured content | No | | `actions_title` | Custom heading for the action plan | No | | `actions` | Ordered work items and commands | No | | `closing` | Current state or handoff point | No | Missing optional fields are simply omitted from the PDF. Compilation fails when the required `metadata.Date` or `metadata.Author` value is missing or empty and prints the YAML needed to fix it. ## Theme Select one of the built-in visual themes at the top level: ```yaml theme: cic ``` - `default` — neutral, understated corporate styling. - `cic` — a sharper corporate space-operations/cyberpunk palette. - `eridani` — a rugged, grass-and-earth palette. The default is used when `theme` is omitted. An unknown name stops compilation and lists the available themes. See [Advanced setup](advanced-setup.md#themes) to customize or add themes. ## Report types Classify reports by their purpose, not merely whether they are internal or external: | Type | Use it for | Typical content | | --- | --- | --- | | `technical` | Investigation, engineering review, and shift handoff | Detailed evidence, commands, timelines, hypotheses, and operational precautions | | `briefing` | Sharing verified findings with customers, managers, or other stakeholders | Concise impact, confirmed findings, decisions, ownership, and next steps | ```yaml report_type: technical ``` A technical report may still be shared when appropriate, and a briefing may be internal. The distinction describes depth and purpose rather than access control. The renderer displays `Technical report` or `Stakeholder briefing` as a badge near the title. Avoid putting secrets, credentials, personal data, or unnecessarily sensitive infrastructure details in either type. Classification does not provide security or redact content. ## Status and severity Typical workflow states are `open`, `pending`, `confirmed`, and `resolved`. Typical severity values are `info`, `medium`, `high`, and `critical`. The renderer also recognizes `warning`, `ok`, and `success` when choosing badge and callout colors. Values are case-insensitive, but lowercase keeps YAML files consistent. ## Metadata Metadata accepts arbitrary labels and values: ```yaml metadata: Date: "2026-09-05" Author: "Your Name" Device: "DESKTOP-EXAMPLE" Owner: "Operations" Ticket: "INC-1234" ``` Quote dates and identifier-like values so YAML does not reinterpret them. `Date` and `Author` are required with exactly this capitalization. ## Timeline and findings ```yaml timeline: - time: "09:15" event: "Alert received" notes: "Monitoring detected repeated storage timeouts." findings: - title: "Storage controller timeout" severity: high status: confirmed evidence: > The system log contains three controller resets within ten minutes. assessment: > The storage path is the leading cause and needs focused testing. ``` Use `evidence` for observations and `assessment` for interpretation. Keeping them separate makes technical conclusions easier to review. ## Free-form sections Each item in `sections` has a title and a list of content blocks: ```yaml sections: - title: "Investigation notes" content: - type: text text: "A short paragraph." - type: bullets items: - "First observation" - "Second observation" - type: steps items: - "Collect logs" - "Reproduce the failure" - type: callout title: "Caution" kind: warning text: "Back up important data before destructive testing." - type: code text: "journalctl --since '30 minutes ago'" - type: subsection title: "Nested detail" content: - type: text text: "Subsections can contain the same block types." ``` Supported block types are `text`, `bullets`, `steps`, `callout`, `code`, and `subsection`. Unknown types render a warning instead of being silently discarded. ## Actions ```yaml actions_title: "Next steps" actions: - title: "Collect system logs" status: pending text: "Export the relevant events and attach them to the ticket." commands: - "journalctl --since today > system.log" - "dmesg > kernel.log" ``` `commands` is a list, so an action can contain zero, one, or several commands. ## Authoring tips - Use `>` for prose that should wrap into one paragraph. - Quote Windows paths and values containing YAML punctuation. - Keep evidence factual and put conclusions in `assessment`. - Use metadata for short facts, not long explanations. - Render after editing to catch malformed YAML and layout problems early. For complete files, continue to [Examples and boilerplate](examples.md).