README

18 — Workbooks

The audit-engine uses workbooks — AI-generated specifications stored in the audit.workbooks Supabase table — to define what each audit run checks, what data it collects, and what it delivers. One active workbook exists per audit.actions row.

How the Workbook System Works

1. A row in audit.actions has a schedule (cron string), action_type, and status
2. When status = 'new', the audit-engine designer.py calls Claude to auto-generate a WorkbookSpec JSON
3. The spec defines: sections, data connectors to use, thresholds, delivery (email + Drive)
4. On each scheduled run, scheduler.py dispatches to the appropriate action handler
5. Results are written to audit.runs; PDF reports go via Mailgun to radieu@gmail.com

Key Documents

Document	Description
audit-engine.md	Full specification — WorkbookSpec model, connectors, scheduler, delivery
audit-engine-operations.md	Deployment, health check, manual trigger, log access
workbook-template.md	Template for creating new workbook specs manually

Action Types

action_type	Description
ai_workbook	AI-generated multi-section audit report; uses all connectors
ping_check	Simple availability ping to registered service URLs
infra_docs_check	Checks dev_r_services for compliance_workbook != 'yes'; fails if gaps found
eu_ai_act_check	Checks dev_r_ai_systems for compliance gaps; runs weekly Monday 08:00 UTC

Connector Inventory

Connector	Module	What it fetches
GitHub	connectors/github_conn	Open issues, PR status, CI run results
Prometheus	connectors/prometheus_conn	PromQL queries against Thanos Query
Wasabi S3	connectors/wasabi_conn	Backup status JSON, bucket size
Google Drive	connectors/gdrive_conn	Report upload destination
HTTP	connectors/http_conn	Generic HTTP health checks
n8n	connectors/n8n_conn	n8n workflow execution status

Workbook Perspective Map

Each of the 18 perspectives in this documentation hub has a corresponding audit focus:

Perspective	Audit coverage
04 — Monitoring	Prometheus target up, Alertmanager firing, exporter health
05 — Backups DR	Wasabi backup status JSON freshness, restore drill flag
06 — Secrets	Credential age via credential-exporter metrics
11 — Automations	n8n workflow last-run status, audit-engine run history
14 — Compliance	infra_docs_check (daily), eu_ai_act_check (weekly)
12 — Costs	cost-exporter Prometheus metrics vs budget thresholds

Cross-references

• README — audit-engine service operations
• README — compliance checks driven by infra_docs_check and eu_ai_act_check
• README — workbook template for new workbook creation