cc @elastic/observablt-ci

Recent direct documentation audit found concrete documentation drift that can mislead contributors and operators.

Changes Requiring Documentation Updates

1. Security architecture doc claims full detector coverage that current docs and implementation do not provide

Commit(s): N/A (direct audit of current main state)

What changed:

• docs/architecture/security-agent-architecture.md states that the detector implements the full ruleset, including SEC-001–SEC-003 and SEC-040–SEC-044 (docs/architecture/security-agent-architecture.md:9, :57, :73, :78).
• docs/workflows/security-scanning-ruleset.md documents current emitted coverage as a subset and explicitly marks multiple rules as not emitted (docs/workflows/security-scanning-ruleset.md:9, :42, :44, :55, :58, :61).

Documentation impact:

• The architecture document currently overstates detector behavior and contradicts the ruleset page users rely on for actual coverage.

2. Dashboard sync workflow doc omits required gh CLI prerequisite for local execution

Commit(s): N/A (direct audit of current main state)

What changed:

• Local invocation is documented (docs/workflows/sync-control-plane-dashboard.md:40-45), but prerequisites list does not include gh (docs/workflows/sync-control-plane-dashboard.md:9-14).
• The script uses GitHub CLI commands (scripts/sync_control_plane_dashboard.py:211 for gh api, :280 for gh issue pin).

Documentation impact:

• Users can follow the documented local run steps and still fail immediately when gh is not installed.

3. Contributor guide lists direct lint/type commands without documenting how those tools are installed

Commit(s): N/A (direct audit of current main state)

What changed:

• Setup only installs pytest and Node dependencies (docs/development/contributing.md:30-40).
• The same page later instructs direct use of yamllint, shellcheck, actionlint, ruff, and mypy (docs/development/contributing.md:84-92).

Documentation impact:

• New contributors can hit command not found for the “Individual tools” section unless they infer extra global installs or know to run equivalent pre-commit hooks.

Suggested Actions

• Update docs/architecture/security-agent-architecture.md to align detector coverage statements with docs/workflows/security-scanning-ruleset.md (or explicitly separate “target ruleset” vs “currently emitted rules”).
• Add gh as an explicit prerequisite in docs/workflows/sync-control-plane-dashboard.md for local/script usage.
• In docs/development/contributing.md, either document explicit installation commands for yamllint, shellcheck, actionlint, ruff, and mypy, or replace direct CLI examples with equivalent pre-commit run <hook-id> --all-files guidance.

What is this? | From workflow: Observability Agentic Workflow Entrypoint

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

• expires on May 11, 2026, 7:27 AM UTC