Harden AGENTS.md claims with explicit validation boundaries

AGENTS.md

@@ -12,7 +12,7 @@
 
 ** New to py3plex?** 
 - **5 minutes**: See [dsl_patterns_quick_reference.py](examples/getting_started/dsl_patterns_quick_reference.py) for 7 copy-paste patterns
-- **15 minutes**: Jump to [Quick Start: Golden Paths](#quick-start-golden-paths) for 5 essential patterns that cover 80% of use cases
+- **15 minutes**: Jump to [Quick Start: Golden Paths](#quick-start-golden-paths) for 5 high-value patterns that cover common workflows
 - **Deep dive**: Continue reading this comprehensive guide
 
 ---
@@ -98,6 +98,10 @@ q = q.compute("degree").hint()  # Get new suggestions
 - Learning new DSL features
 - Debugging query construction issues
 
+**Validation status**:
+- Execution and chaining behavior are covered by `tests/test_agents_ergonomics_features.py`
+- Exact hint text and formatting may evolve between versions; rely on API behavior, not exact output text
+
 ### Enhanced QueryResult Introspection
 
 **What it does**: QueryResult objects now have rich `__repr__` showing full context.
@@ -247,6 +251,10 @@ with suppress_warnings("degree_ambiguity", "node_replica_confusion"):
 - **React to warnings**: Warnings are actionable — apply suggested alternatives when applicable
 - **Don't ignore**: Warnings indicate potential correctness or performance issues
 
+**Validation status**:
+- Warning suppression behavior (`suppress_warnings`) is tested in `tests/test_agents_ergonomics_features.py`
+- Warning triggering thresholds and exact warning text are implementation details and may vary across releases
+
 ### Multilayer Semantics Mental Model
 
 **Core concepts LLM agents must understand**:
@@ -336,12 +344,16 @@ result = (
 result.export_bundle("analysis.bundle.json.gz", compress=True)
 ```
 
-**LLM agent guidance**: When user asks "how do I...", search these recipes first. They represent tested, best-practice patterns.
+**LLM agent guidance**: When user asks "how do I...", search these recipes first and then validate in the current environment.
 
 ---
 
 ## Quick Start: Golden Paths
 
+**Validation status**:
+- Path 1 and Path 2 are exercised in `tests/test_agents_golden_paths.py`
+- Path 3, Path 4, and Path 5 are advanced workflows and may require optional modules or setup in the current environment
+
 ### Path 1: Network Analysis from CSV
 
 ```python

tests/test_agents_documentation_claims.py

@@ -0,0 +1,42 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""
+Guardrails for AGENTS.md claim language.
+
+These tests ensure AGENTS.md keeps conservative wording around validation
+coverage and warning behavior so documentation does not over-claim support.
+"""
+
+from pathlib import Path
+
+
+def _read_agents_md() -> str:
+    repo_root = Path(__file__).parent.parent
+    return (repo_root / "AGENTS.md").read_text(encoding="utf-8")
+
+
+def test_quickstart_validation_status_is_explicit():
+    """Golden Paths section should clearly state tested vs advanced paths."""
+    text = _read_agents_md()
+
+    assert "**Validation status**:" in text
+    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
+    )
+
+
+def test_warning_behavior_claims_are_conservative():
+    """Ergonomics warning docs should avoid implying stable warning text contracts."""
+    text = _read_agents_md()
+
+    assert (
+        "Warning suppression behavior (`suppress_warnings`) is tested in `tests/test_agents_ergonomics_features.py`"
+        in text
+    )
+    assert (
+        "Warning triggering thresholds and exact warning text are implementation details and may vary across releases"
+        in text
+    )
+