Correct failure alert and digest details

[lmac-1]

Short Description

Corrects the failure alert and digest page against current Lightning: alert emails link to the logs rather than including them, and digests count work orders.

Details

Checked against OpenFn/lightning main at 3b9f4a2f9b.

Changed in docs/manage-projects/notifications.md:

• Failure alerts fire when a run fails, not a job (lib/lightning/pipeline/failure_alerter.ex).
• The alert email links to the work order, the run and its logs, and the workflow health page. It doesn't include the logs (failure_alert.html.heex).
• Added the rate limit of 3 alerts per workflow every 5 minutes (config/config.exs).
• Failure alerts are off and the digest is set to Never by default (project_user.ex), and you can only change your own settings (policies/project_users.ex).
• Digests count work orders, not runs, and go out at 10:00 UTC: daily, weekly on Mondays, monthly on the 1st (config/bootstrap.ex). They link to History and, if there were failures, to workflow health.

Left for later:

• Screenshots need retaking. lightning_failure_email.webp shows logs inside the email and old wording, so it now contradicts the text. lightning_weekly_digest.webp shows old digest wording. We don't retake screenshots with AI.
• Workflow health has no page. It shipped in lightning #5189 and #5229 and both emails link to it, but nothing in docs/ covers it. It needs its own page under Monitor & History.
• Style fixes not made: headings start at ###, the intro is two paragraphs that say the same thing, and the alt text doesn't describe the images. These were Could changes in the report.
• Question for the product team: the Failure Alert column can show "Unavailable", which the usage limiter decides per project. If this depends on the plan on app.openfn.org, which plans include alerts?
• The Spanish page (machine status) needs retranslating after this merges.

identify-gaps report

Covered docs/manage-projects/notifications.md against OpenFn/lightning origin/main 3b9f4a2f9b. 1 Must, 4 Should, 4 Could, 1 Question.

Must

• [must] notifications.md:21 — says the email "includes the logs"; failure_alert.html.heex only links to the run and its logs — say it links to the work order, run and logs, and workflow health.

Should

• [should] notifications.md:16 — "when a job fails"; alerts fire per failed run (failure_alerter.ex:17) — change to run.
• [should] Failure Alerts — missing the rate limit (3 per workflow per 5 min, config/config.exs:193), defaults (off / Never, project_user.ex:37-39), and that you can only change your own settings (policies/project_users.ex:51).
• [should] notifications.md:31 — digests count work orders, not runs (digest_email_worker.ex:159); add send times (10:00 UTC daily / Monday / 1st, bootstrap.ex:294-299) and the History and health links.
• [should] lightning_failure_email.webp and lightning_weekly_digest.webp are out of date — a human needs to retake them.

Could

• [could] Headings start at ###; STYLE.md says ##.
• [could] Intro repeats itself and puts Notifications and Digests in code formatting.
• [could] Alt text doesn't describe the images; lightning_failed_run.webp adds little.
• [could] Workflow health (lightning #5189, #5229) has no docs page; it belongs under Monitor & History.

Questions

• When does the Failure Alert column show "Unavailable" (project_limiter.ex:11)? Is it plan-dependent on app.openfn.org?

AI Usage

Please disclose how you've used AI in this work (it's cool, we just want to know!):

• I have used Claude Code
• I have used another model
• I have not used AI

You can read more details in our Responsible AI Policy