[oblt-aw][autodoc] Fix stale workflow references and multi-org architecture docs #1428

cc @elastic/observablt-ci

Recent documentation audit found concrete documentation drift that can mislead maintainers and consumers.

Changes Requiring Documentation Updates

1. ESTC Buildkite Detective docs reference a nonexistent client template

What changed / evidence: docs/workflows/oblt-aw-estc-pr-buildkite-detective.md:7 and docs/workflows/oblt-aw-estc-pr-buildkite-detective.md:11 say the workflow is called from trigger-oblt-aw-estc-pr-buildkite-detective.yml, but that file does not exist in the repository. The actual distributed status template is .github/remote-workflow-template/obs/.github/workflows/trigger-oblt-aw-status.yml:1, which calls .github/workflows/oblt-aw-event-status.yml:20 and then .github/workflows/oblt-aw-estc-pr-buildkite-detective.yml:37.

Documentation impact: Consumers looking for or configuring the documented client template will search for a file that is not shipped.

2. Multi-org architecture docs document an unsupported registry display field

What changed / evidence: docs/architecture/multi-org-agentic-workflows.md:133 says workflow entries can include optional display_name. The dashboard renderer reads name instead: scripts/sync_control_plane_dashboard.py:168-174 and scripts/sync_control_plane_dashboard.py:184-192 use wf.get("name", wf_id). Current registries also use name, for example config/obs/workflow-registry.json:5-7.

Documentation impact: Maintainers adding display_name based on the architecture docs would not see it rendered in the dashboard.

3. Multi-org architecture docs omit workflow-token-policy from the repos matrix shape

What changed / evidence: docs/architecture/multi-org-agentic-workflows.md:122-125 documents build_repos_matrix.py output repos as [{"repository":"owner/repo"}, ...]. The script emits workflow-token-policy for every matrix row: scripts/build_repos_matrix.py:23-24 documents {"repository": "owner/repo", "workflow-token-policy": "..."}, and scripts/build_repos_matrix.py:50-54 builds that shape.

Documentation impact: Operators debugging dashboard sync matrix output or token policy propagation see an incomplete documented contract.

Suggested Actions

• Update docs/workflows/oblt-aw-estc-pr-buildkite-detective.md to describe the actual route: trigger-oblt-aw-status.yml -> oblt-aw-event-status.yml -> oblt-aw-estc-pr-buildkite-detective.yml.
• Update docs/architecture/multi-org-agentic-workflows.md to replace display_name with the supported workflow entry field name, and note that section_title is the optional top-level registry display label.
• Update docs/architecture/multi-org-agentic-workflows.md to document build_repos_matrix.py repos rows as including both repository and workflow-token-policy, with workflow-token-policy set to an empty string when unset.

What is this? | From workflow: Observability Agentic Workflow — Schedule

Give us feedback! React with 🚀 if perfect, 👍 if helpful, 👎 if not.

• expires on Jul 16, 2026, 7:33 AM UTC