Export header metadata for Reports Hub (defaults + configurable fields)

Objective

• Add a contextual header block to Reports Hub CSV/XLSX exports — metadata rows above the column header row, not just in the filename.
• Let users choose which header fields appear when creating or editing a saved report (Phase 2).
• Let users turn the header off entirely for a saved report and export raw data only (column headers + rows, today's behavior).
• Close the immediate gap from product feedback: instance name and run date must appear inside the exported file body when the header is enabled (Phase 1 default set).

Background

• Product feedback reported that exported files omit contextual information. The export should show the instance name above the data and the report run date in the header or footer.
• That request is the confirmed example of a broader gap: exports today contain only column headers and data rows. Run date may appear in the generated filename ({reportName}_export_{YYYY-MM-DD}) but not in the file body.
• Not every export needs contextual headers — some teams want data-only files for re-import, downstream tools, or minimal spreadsheets. Opting out must be a first-class saved report setting, not a workaround.
• This is a feature gap, not a bug or permissions issue. Export writers accept data and headers only; there is no saved report setting or job payload field for export header metadata.
• Some header values are resolved at export time (run date/time, applied filter date range); others come from the saved report or company (instance name, report name). Toggles are saved on the report definition; values are computed when the export runs.

Confirmed example (instance name + run date):

Current:

Desired:

Scope

Phase 1 — Default export header block

Ship metadata rows in CSV/XLSX when the header is enabled, using a sensible default set (no create/edit UI required yet). Phase 1 closes the confirmed example above for reports that use defaults.

Default header fields (when enabled):

• Instance / company name (Company.name)
• Report name (saved report name)
• Run date/time (export execution time, formatted with company/export timezone)
• Applied filter date range (when the run includes a date filter)

Done when Phase 1 is complete:

• CSV and XLSX support optional metadata rows above the column header row.
• When header is enabled (default until Phase 2 opt-out exists), default set includes instance name, report name, and run date/time at minimum.
• Confirmed example exports show instance name and run date inside the file body.
• Background job exports (runDataExportJob.ts) and interactive downloads (dataExport.ts) behave the same.
• Writers can skip metadata entirely when header is disabled (backend path ready for Phase 2).

Phase 2 — Configurable header fields on saved reports

Let users control the export header when creating or editing a report in Reports Hub.

Header control (required):

• Include export header — master on/off for the saved report. When off, export is data-only (column headers + rows), matching today's output.
• Header field selection — when on, choose which curated fields appear (see below).

Curated field options (not free-text):

• Instance name
• Report name
• Run date/time
• Applied filter date range
• Exported by (optional, lower priority)
• Report description (optional, lower priority)

Done when Phase 2 is complete:

• Create/edit report UI exposes Include export header and header field selection.
• Settings persist on the saved report and flow through export job payload.
• New reports default to header on, with instance name + report name + run date/time selected.
• Turning header off produces exports with no metadata rows (same as pre-feature behavior).
• With header on, deselecting individual fields removes only those lines from output.
• Existing reports without a saved preference use Phase 1 defaults (header on) until edited; users can then opt out per report.

Backend (attik-backend)

• Export writers in src/util/functions/exports/generateCSV.ts and src/util/functions/exports/generateXLSX.ts today output header row + data rows only; they need optional metadata support and a path to emit no metadata rows when header is disabled.
• Background exports run through src/util/functions/dataExports/runDataExportJob.ts (DataExportJobPayload, executeDataExportJob), which calls those writers directly. Filename date is set in runDataExportJob.ts; company is loaded for timezone only today — instance name would come from Company.name in src/models/companySchema.ts.
• Streaming CSV: joined and cursor exports write a full header on batch 0 via generateCSVExport, then generateCSVDataRowsOnly for later batches. Metadata must appear only in the first segment when header is enabled, with a blank row before the column header row; when disabled, first segment matches today's behavior.
• Interactive download path in src/routes/dataExport.ts uses the same writers and {name}_export_{YYYY-MM-DD} filename pattern — should match background export header behavior.
• Phase 2: persist header enabled flag and field selection on DataExport in src/models/dataExportSchema.ts and pass through save/run API + DataExportJobPayload.
• Decision needed: Master Include export header toggle vs inferring "off" when zero fields are selected (toggle is clearer for users who want data-only exports).
• Decision needed: Header-only vs footer for run date when header is on (header above data is simpler for CSV streaming; footer can follow later).
• Out of scope for v1 unless trivial: Custom header labels, arbitrary key/value rows, preview header in report preview UI, platform catalog clone behavior (defaults should still work).

Frontend (attik-frontend)

• Phase 1: no UI change required if defaults apply to all exports until Phase 2 ships.
• Phase 2: Include export header toggle plus header field picker in src/app/tools/data-exports/CreateReportForm.tsx, wired through formReducer.ts, utils/formStateToPayload.ts, and RunReportConfig in types.ts. Field picker should be disabled or hidden when header is off.
• Per-run date range is already chosen at export time in runs/[id]/RunReportClient.tsx — "applied filter date range" is a run-time value, not a static saved string.

References

• src/util/functions/exports/generateCSV.ts — generateCSVExport, generateCSVDataRowsOnly
• src/util/functions/exports/generateXLSX.ts — generateXLSXExport
• src/util/functions/dataExports/runDataExportJob.ts — executeDataExportJob, DataExportJobPayload
• src/routes/dataExport.ts — interactive CSV/XLSX download
• src/models/dataExportSchema.ts — saved report definition (Phase 2 persistence)
• src/app/tools/data-exports/CreateReportForm.tsx — create/edit report (Phase 2 UI)