Harden AGENTS.md claims with explicit validation boundaries

[Copilot]

This issue asked for an audit of AGENTS.md to identify under-documented, over-claimed, or risky statements unless backed by tests/examples. This PR narrows documentation claims to what is explicitly validated and adds guardrails to keep those claims accurate over time.

• Documentation claim tightening (AGENTS.md)

  • Replaced broad onboarding claim (“covers 80% of use cases”) with non-absolute wording.
  • Added explicit Validation status notes in high-risk sections:
    • .hint() ergonomics behavior vs. unstable output formatting
    • warning system behavior (suppress_warnings tested) vs. non-contractual warning text/thresholds
    • Golden Paths coverage split (Path 1/2 test-backed; Path 3/4/5 marked as advanced/environment-dependent)
  • Updated guidance language to require environment-specific validation before relying on examples as canonical.

• Regression guardrails for documentation accuracy

  • Added a focused test module: tests/test_agents_documentation_claims.py
  • Enforces presence of the new “Validation status” language so future edits do not reintroduce over-claims.

• Example of enforced claim boundary

  # tests/test_agents_documentation_claims.py
  assert "Path 1 and Path 2 are exercised in `tests/test_agents_golden_paths.py`" in text
  assert "Path 3, Path 4, and Path 5 are advanced workflows and may require optional modules or setup in the current environment" in text

---

📍 Connect Copilot coding agent with Jira, Azure Boards or Linear to delegate work to Copilot in one click without leaving your project management tool.