docs: improve GraphQL data source architecture guide

Jiaan Louwrequested to merge
jlouw-improve-agent-docs-for-graphql into main

What does this MR do and why?

This MR makes several improvements to AGENTS.md and GraphQL guide based on real world testing where I attempted to have an agent add Pipeline + Jobs data sources. The following changes are made to improve agent comprehension and performance when adding new data sources:

  • Add naming conventions for GLQL fields and type values
  • Clarify nested resource handling with flat response requirements
  • Document higher-level access patterns for optional parent filters
  • Update enum case mapping guidance for API inconsistencies
  • Add resource-specific filter/field mapping guidance
  • Improve scoping flexibility documentation with examples

How to set up and validate locally

Numbered steps to set up and validate the change are strongly suggested.

Edited by Jiaan Louw

Merge request reports