docs: update CI visibility refarch to content-only approach

[chaodu-agent]

Summary

Update the CI visibility reference architecture doc to reflect the final working implementation.

Changes

• No more embeds — all info goes in content field so bots can read it
• File + jq --rawfile — guarantees real newlines in JSON payload
• allowed_mentions — required for webhook mentions to actually ping
• Updated architecture diagram, design decisions table, and gotchas

Why

We discovered through testing that:

1. Discord embeds are invisible to most bot frameworks
2. jq --arg with shell variables loses newlines
3. Webhook mentions need explicit allowed_mentions to ping
4. Mention-only content doesn't trigger bot message handlers

[github-actions]

⚠️ This PR is missing a Discord Discussion URL in the body.

All PRs must reference a prior Discord discussion to ensure community alignment before implementation.

Please edit the PR description to include a link like:

Discord Discussion URL: https://discord.com/channels/...

This PR will be automatically closed in 3 days if the link is not added.

[shaun-agent]

OpenAB PR Screening

This is auto-generated by the OpenAB project-screening flow for context collection and reviewer handoff.
Click 👍 if you find this useful. Human review will be done within 24 hours. We appreciate your support and contribution 🙏

• Title: docs: update CI visibility refarch to content-only approach
• Source: docs: update CI visibility refarch to content-only approach #840
• Status: moved to PR-Screening
• Generated at: 2026-05-18T01:20:32.480Z
• Discord thread: not available

Screening report

screening complete.

GitHub comment: #840 (comment)
Project action: moved PVTI_lADOEFbZWM4BUUALzgtAM40 from Incoming to PR-Screening in https://github.com/orgs/openabdev/projects/1

Intent

PR #840 updates the CI observability Discord reference architecture to match the implementation that actually worked in testing. The operator-visible problem is that CI notifications must be readable by Discord bots, preserve multiline formatting, route to the right thread, and reliably ping the intended user or bot.

Feat

Docs work. The PR changes docs/refarch/ci-observability-discord.md from an embed-first Discord webhook design to a content-only payload design using a temp file plus jq --rawfile, bare URLs, and allowed_mentions.

Who It Serves

Maintainers and deployers. It also helps agent runtime operators who rely on Discord notifications being visible to bot frameworks rather than hidden inside embeds.

Rewritten Prompt

Update the CI observability Discord reference architecture doc so it describes the verified content-only webhook approach. Remove guidance that depends on Discord embeds for CI metadata. Show a reusable GitHub Actions notification workflow that builds the Discord message as real multiline text, reads it into JSON with jq --rawfile, includes the run URL as a bare URL, and sets allowed_mentions so <@USER_ID> pings.

Merge Pitch

This should move forward as a low-risk documentation correction. Main reviewer concern: the sample must be copy-paste accurate, especially around whether mentions support users only or roles too.

Best-Practice Comparison

OpenClaw and Hermes Agent mostly do not apply here because this is documentation for CI-to-Discord webhook notifications, not scheduling, persisted execution, or gateway runtime architecture.

Recommendation

Use the balanced path: merge the doc correction after quick technical review, then follow up with a tested reusable workflow/template so the reference architecture does not drift again.