docs(gql): validate group discovery queries and fix stale templates

- Fix self query to use memberEvents/totalCount (was deprecated upcomingEvents/count)
- Fix groupByUrlname query to use events/totalCount (same migration)
- Add group(id:) query template (verified working via live API)
- Document that node(id:) does not exist in Meetup schema
- Document ID consistency between groupSearch and groupByUrlname
- Complete task-017 and task-018

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: pythoninthegrass

app/meetup_queries.gql

@@ -11,15 +11,15 @@ query {
 	}
 }
 
-# join first party events then filter group info
+# first-party events (techlahoma member events)
 query {
 	self {
 		id
 		name
 		username
 		memberUrl
-		upcomingEvents {
-			count
+		memberEvents(first: 10) {
+			totalCount
 			pageInfo {
 				endCursor
 			}
@@ -43,7 +43,7 @@ query {
 	}
 }
 
-#  events by query var
+# events by query var
 # {"eventId":"285533748"}
 query($eventId: ID) {
 	event(id: $eventId) {
@@ -84,8 +84,8 @@ query($id: ID!) {
 	}
 }
 
-# search for non pro network group by urlname
-{"urlname":"pythonistas"}
+# group by urlname (third-party / unaffiliated groups)
+# {"urlname":"pythonistas"}
 query($urlname: String!) {
 	groupByUrlname(urlname: $urlname) {
 		id
@@ -94,8 +94,8 @@ query($urlname: String!) {
 		urlname
 		city
 		link
-		upcomingEvents(input: { first: 3 }) {
-			count
+		events(first: 3) {
+			totalCount
 			pageInfo {
 				endCursor
 			}
@@ -119,8 +119,45 @@ query($urlname: String!) {
 	}
 }
 
-# query OKC area for programming groups' IDs
+# group by ID (validated: IDs match between groupByUrlname and groupSearch)
+# {"id":"35460866"}
+query($id: ID!) {
+	group(id: $id) {
+		id
+		description
+		name
+		urlname
+		city
+		link
+		events(first: 3) {
+			totalCount
+			pageInfo {
+				endCursor
+			}
+			edges {
+				node {
+					id
+					title
+					description
+					dateTime
+					eventUrl
+					group {
+						id
+						name
+						urlname
+						link
+						city
+					}
+				}
+			}
+		}
+	}
+}
+
+# keyword search for programming groups in OKC area
 # topicCategoryId 546 = Technology (from topicCategories query)
+# IDs returned here match groupByUrlname IDs (verified for pythonistas, okcwebdevs, okccoffeeandcode)
+# node(id:) does NOT exist in Meetup's schema; use group(id:) or groupByUrlname(urlname:) instead
 {"query": "programming", "topicCategoryId": "546"}
 query ($query: String!, $topicCategoryId: ID) {
 	groupSearch(
@@ -145,4 +182,3 @@ query ($query: String!, $topicCategoryId: ID) {
 		}
 	}
 }
-

backlog/completed/task-017 - Handle-missing-events-and-imprecise-date-parsing.md

@@ -0,0 +1,40 @@
+---
+id: TASK-017
+title: Handle missing events and imprecise date parsing
+status: Done
+assignee: []
+created_date: '2026-02-27 00:54'
+updated_date: '2026-03-21 00:35'
+labels:
+  - bug
+dependencies: []
+references:
+  - app/meetup_query.py
+priority: medium
+ordinal: 8000
+---
+
+## Description
+
+<!-- SECTION:DESCRIPTION:BEGIN -->
+Two related data quality issues in meetup_query.py: (1) When a group has no upcoming events, format_response falls through to city comparison on a None/empty response instead of gracefully returning empty. (2) sort_json uses heuristics to determine the year when dates are in 'ddd M/D h:mm a' format (no year), which can produce incorrect years near year boundaries.
+<!-- SECTION:DESCRIPTION:END -->
+
+## Acceptance Criteria
+<!-- AC:BEGIN -->
+- [x] #1 format_response returns empty DataFrame when group has no upcoming events without errors
+- [x] #2 sort_json derives year from the original ISO 8601 dateTime field instead of guessing
+- [x] #3 Tests cover empty event lists and year-boundary date parsing
+<!-- AC:END -->
+
+## Final Summary
+
+<!-- SECTION:FINAL_SUMMARY:BEGIN -->
+Commit b1ffb41 fixes both issues in meetup_query.py:
+
+1. **format_response** now catches `TypeError` alongside `KeyError` and uses `.get()` for safer navigation of `memberEvents`, `groupByUrlname`, and `events` fields. Null intermediate API fields return an empty DataFrame instead of crashing.
+
+2. **sort_json** and **prepare_events** year-derivation logic improved: when parsing year-less `'ddd M/D h:mm a'` dates, if assigning the current year produces a date more than 6 months in the past, it bumps to the next year. This correctly handles Dec/Jan year boundaries.
+
+7 new unit tests cover empty event lists, null API fields, and year-boundary date parsing for both ISO 8601 and human-readable formats.
+<!-- SECTION:FINAL_SUMMARY:END -->

backlog/completed/task-018 - Validate-GraphQL-group-discovery-queries.md

@@ -0,0 +1,56 @@
+---
+id: TASK-018
+title: Validate GraphQL group discovery queries
+status: Done
+assignee: []
+created_date: '2026-02-27 00:54'
+updated_date: '2026-03-21 01:06'
+labels:
+  - qa
+dependencies: []
+references:
+  - app/meetup_queries.gql
+  - app/meetup_query.py
+priority: low
+ordinal: 3000
+---
+
+## Description
+
+<!-- SECTION:DESCRIPTION:BEGIN -->
+meetup_queries.gql contains two unused query templates that need QA: (1) a keywordSearch query that returns node IDs for groups — need to verify these match the group IDs used elsewhere, and (2) a workflow to look up a group by ID and fall back to parsing urlname from URL if not found. These queries support the capture_groups GQL migration.
+<!-- SECTION:DESCRIPTION:END -->
+
+## Acceptance Criteria
+<!-- AC:BEGIN -->
+- [x] #1 Confirm keywordSearch node IDs match groupByUrlname IDs for the same groups
+- [x] #2 Document whether group lookup by ID is possible or if urlname is the only key
+- [x] #3 Update or remove meetup_queries.gql templates based on findings
+<!-- AC:END -->
+
+## Final Summary
+
+<!-- SECTION:FINAL_SUMMARY:BEGIN -->
+## Findings
+
+### AC#1: keywordSearch IDs match groupByUrlname IDs
+Verified for three overlapping groups:
+- `pythonistas`: `35460866` (match)
+- `okcwebdevs`: `33258520` (match)
+- `okccoffeeandcode`: `24875064` (match)
+
+The `groupSearch` query returns 37 results for "programming" in the OKC area (topicCategoryId 546). IDs are consistent across query types.
+
+### AC#2: Group lookup by ID
+- `group(id: $id)` — works, returns full group data
+- `node(id: $id)` — does NOT exist in Meetup's GraphQL schema (ValidationError)
+- `groupByUrlname(urlname: $urlname)` — works (already in use)
+
+Both `group(id:)` and `groupByUrlname(urlname:)` are valid lookup keys.
+
+### AC#3: meetup_queries.gql updates
+- Fixed stale `self` query to use `memberEvents(first: 10)` with `totalCount` (was using deprecated `upcomingEvents`/`count`)
+- Fixed `groupByUrlname` query to use `events(first: 3)` with `totalCount` (was using deprecated `upcomingEvents`/`count`)
+- Added `group(id:)` query template with documentation
+- Added comments to `groupSearch` noting ID consistency and that `node(id:)` is not available
+<!-- SECTION:FINAL_SUMMARY:END -->