spec: roll up to Agent CLI Guidelines v0.4.0

CHANGELOG.md

@@ -7,6 +7,15 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Added
+- Machine-readable **conformance block** in `gfly schema --json`:
+  `{"spec": "agent-cli-guidelines", "version": "0.4.0", "level": "Full"}` (sourced from the
+  package `SPEC` constant), so an agent can verify the contract version from the binary.
+
+### Changed
+- Pinned the conformance statement to **Agent CLI Guidelines v0.4.0, Full** (was an imprecise
+  "v0.3") across the README and the for-agents reference.
+
 ## [0.2.0] - 2026-06-25
 
 Reaches **Agent CLI Guidelines v0.3, Full**.

README.md

@@ -176,7 +176,7 @@ throttle/block), so an agent can back off, switch backend, or report instead of
 
 ## For agents
 
-> Follows the [Agent CLI Guidelines](https://aclig.dev) (v0.3, **Full**) — read-only by default,
+> Follows the [Agent CLI Guidelines](https://aclig.dev) (**v0.4.0, Full**) — read-only by default,
 > structured, self-describing, stable exit codes.
 
 ```bash

docs/src/content/docs/reference/for-agents.md

@@ -256,11 +256,11 @@ gfly search JFK LHR \
 
 ## Conformance
 
-gfly follows the [Agent CLI Guidelines](https://aclig.dev) at **v0.3, Full** — every Core invariant
+gfly follows the [Agent CLI Guidelines](https://aclig.dev) at **v0.4.0, Full** — every Core invariant
 (read-only by default, stdout/stderr discipline, stable `--json` schema, documented exit codes,
-`--no-input` hard-fail, machine-readable `schema`, structured errors, bounded output, untrusted-text
-fencing, append-only fields) plus the Full SHOULDs, including the ones the v0.2/v0.3 revisions added
-for scraped-backend tools:
+`--no-input` hard-fail, machine-readable `schema` with a `conformance` block, structured errors,
+bounded output, untrusted-text fencing, append-only fields) plus the Full SHOULDs, including the ones
+the v0.2/v0.3/v0.4 revisions added for scraped-backend tools:
 
 - **Backpressure** — a persistent, cross-process throttle with a circuit breaker; fail-fast by
   default (see [rate limits](/guides/rate-limits/)).

src/gfly/__init__.py

@@ -17,3 +17,6 @@ def _version() -> str:
 
 
 __version__ = _version()
+
+# Agent CLI Guidelines version this tool conforms to (declared in `schema`).
+SPEC = "0.4.0"

src/gfly/cli.py

@@ -23,7 +23,7 @@
 
 import click
 
-from . import __version__
+from . import SPEC, __version__
 from . import auth as authmod
 from . import backend as be
 from . import throttle
@@ -570,6 +570,7 @@ def schema(ctx, **_):
         "tool": "gfly",
         "version": __version__,
         "schemaVersion": SCHEMA_VERSION,
+        "conformance": {"spec": "agent-cli-guidelines", "version": SPEC, "level": "Full"},
         "commands": info,
         "exit_codes": exit_table(),
         "safety": {"allow_mutations": rt.allow_mutations, "dry_run": rt.dry_run,