Feat/graphql versioning and cli migration notes

.github/pull_request_template.md

@@ -51,6 +51,24 @@ Describe what scenarios have been tested:
 
 If checked, describe the breaking changes and migration path:
 
+### GraphQL Breaking-Change Checklist
+
+<!-- Complete this section for ANY PR that touches src/graphql/ — leave unchecked items as-is if not applicable -->
+
+- [ ] **No non-deprecated field is removed** — if a field is removed, confirm
+      it carried `#[graphql(deprecation)]` for ≥ 90 days (see `GRAPHQL_SCHEMA_VERSIONING.md`).
+- [ ] **Deprecation registered** — new deprecations are recorded in
+      `src/graphql/schema_deprecations.rs` with correct `deprecated_since`
+      and `earliest_removal` dates (≥ deprecated_since + 90 days).
+- [ ] **Replacement documented** — the `#[graphql(deprecation = "...")]` reason string
+      names the replacement field/type.
+- [ ] **Schema version bumped** — `SCHEMA_VERSION` in `src/graphql/schema.rs`
+      updated if a field/type is removed or a type signature changed.
+- [ ] **CHANGELOG updated** — entry added under `### Deprecated` or `### Removed` as appropriate.
+- [ ] **CI lint passes** — `bash scripts/check-graphql-deprecations.sh` exits 0.
+- [ ] **Consumer impact assessed** — first-party client libraries
+      (`client.go`, `client.py`, `client.rs`, `client.ts`) checked or updated.
+
 ## Documentation
 
 - [ ] README.md updated

.github/workflows/graphql-schema-lint.yml

@@ -0,0 +1,40 @@
+name: GraphQL Schema Lint
+
+# Enforces the 90-day deprecation SLA from GRAPHQL_SCHEMA_VERSIONING.md.
+# Runs on every push/PR that touches GraphQL source or schema docs.
+
+on:
+  push:
+    paths:
+      - "src/graphql/**"
+      - "GRAPHQL_*.md"
+      - "scripts/check-graphql-deprecations.sh"
+  pull_request:
+    paths:
+      - "src/graphql/**"
+      - "GRAPHQL_*.md"
+      - "scripts/check-graphql-deprecations.sh"
+
+jobs:
+  graphql-schema-lint:
+    name: GraphQL Schema Lint
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Make lint script executable
+        run: chmod +x scripts/check-graphql-deprecations.sh
+
+      - name: Check GraphQL deprecation windows
+        run: bash scripts/check-graphql-deprecations.sh
+
+      - name: Verify schema_deprecations.rs compiles
+        # Compile only the graphql module to catch any Rust errors in the
+        # deprecation registry before they reach the main CI build job.
+        uses: dtolnay/rust-toolchain@stable
+
+      - name: Install system dependencies
+        run: sudo apt-get update && sudo apt-get install -y libudev-dev
+
+      - name: Compile graphql module (deprecation registry check)
+        run: cargo check --locked 2>&1 | grep -E "^error" && exit 1 || true