wiq-cli 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b8732206776c88ba1c9d5630407e3a7a4ba6386e528cb5a7a36b2b7c8bcda3dc
-  data.tar.gz: 499116e3d7977c22e0f44759ea59406c49265e865def76300353de0052dbf5b0
+  metadata.gz: bffdea54163c5b95a5cab8b219d3e5cb3a898a059d7edce13afa8ae02928b27a
+  data.tar.gz: 0f9e49529c6bc9fb37b75761e581d1de90a186107242a6c3092fcca55687f9ba
 SHA512:
-  metadata.gz: 34f253c3bfcf4a7702348287da3a3e8c2458dbc818d20a73849e1b14574b9d7b38767113dd099ea065142d80e1415669813ca54199e9d61326452a6daf6f6b04
-  data.tar.gz: 80df40a51028efe1926961e2c556a8fab8a46d28757f28360ef12d258003fbdaea031ea2933690e07a33f7729f6e165cea4db33a5491722d44eaa8e7d323498e
+  metadata.gz: 57f4ccba1f18ca17207739d051e94fcfb1b52b712c2d87e97fc64951acd4041d37a69f6d89d262dfde73cc44d278549d6ac9af02b67a572e3dd549dd2c58cd95
+  data.tar.gz: a317f13e135ab5b7a20f24b7f0c8a6640cbf84afc6a0a3e8d38d9d6483a537c302289f479b1cac0d454ca9c10485ebbcf453804decf4cdf02dbd73b822b0b933

data/docs/deferred.md

@@ -144,10 +144,14 @@ Last updated: 2026-05-12 (after L1 ships).
 - **Echo `request_id`** in the response body or `X-Request-ID` header,
   for support correlation. Today the CLI can't give a customer a request
   ID to ship to support.
-- **Real location/site filter on events.** `Event.location` is free-text
-  and not in `ransackable_attributes`. WIQ team has flagged a structured
-  location concept as roadmap. Until then the CLI deliberately exposes
-  no `--site` flag.
+- ~~**Real location/site filter on events.**~~ — SHIPPED (June 2026,
+  wre-506). The backend grew a structured Location model. The CLI now
+  exposes `wiq locations list|show` plus `--location` flags on
+  `events list` (repeatable → `location_ids[]`), `rosters list`
+  (`q[location_id_eq]`), `paid_sessions list`, `wrestlers list`,
+  `metrics show`, and `reports run` (args.location_id, honored by 13
+  report types). The legacy free-text `Event.location` remains for old
+  rows; serialized `location` is the display form.
 - **Subdomain discovery flow for `wiq auth login`.** PAT settings URL
   lives at `<team-subdomain>.wrestlingiq.com/settings/personal_access_tokens`.
   If a customer doesn't know their subdomain, the CLI can't deep-link

data/docs/wiq_api_notes.md

@@ -468,13 +468,16 @@ Other registration surface:
 - `expand=event_invites,event_bookings,private_lessons` — comma-separated
   CSV; pulls in nested data on the events index/show.
 - `Event.ransackable_attributes` allows
-  `id, name, start_at, end_at, event_type, paid_session_id`. **`location`
-  is not ransackable today.** A real location filter is on the WIQ
-  backend roadmap (it will replace the free-text `location` column with a
-  structured concept); until that ships the CLI doesn't expose a
-  location/site flag. Users who need it can fetch the date range, write
-  the results to a file, and post-process — that's not the CLI's problem
-  to solve in v1.
+  `id, name, start_at, end_at, event_type, paid_session_id`. The
+  free-text `location` column is still not ransackable, but the
+  structured location filter shipped (June 2026): pass `location_ids[]`
+  (repeatable, dedicated param handled in `apply_event_filters`, not
+  Ransack) to filter on the event's `location_id`. Events with no
+  `location_id` are excluded from a filtered listing. The serialized
+  `location` field is now `Event#display_location` — the structured
+  Location's name when set, else the legacy free text — and `location_id`
+  is serialized alongside it. The CLI exposes this as
+  `wiq events list --location <id> [<id>...]`.
 - Soft deletes: events use `acts_as_paranoid`; the index calls
   `.without_deleted`. No "include deleted" param exposed.
 - `POST /api/v1/events` — recurring practice creation:
@@ -642,9 +645,12 @@ PaidSession-overlap convention proves load-bearing for many customers.
    demand. Until then, jbuilders are the source of truth.
 2. `request_id` echoed in response body and/or `X-Request-ID` header for
    support correlation.
-3. Real location/site filter on `GET /api/v1/events` (when the backend
-   gets a structured location concept). Until then the CLI doesn't expose
-   a flag.
+3. ~~Real location/site filter on `GET /api/v1/events`~~ — SHIPPED
+   (June 2026, wre-506). Structured Location model + `location_ids[]` on
+   events, `location_id` on paid_sessions/wrestlers/metrics/reports,
+   `q[location_id_eq]` on rosters, and a `GET /api/v1/locations`
+   resource. All exposed in the CLI via `wiq locations` and `--location`
+   flags.
 4. Subdomain discovery for `wiq auth login`. The PAT settings URL lives at
    `<team-subdomain>.wrestlingiq.com/settings/personal_access_tokens`; if
    the customer doesn't know their subdomain, the CLI can't deep-link

data/lib/wiq/cli.rb

@@ -65,6 +65,9 @@ module Wiq
     desc "rosters SUBCOMMAND", "Rosters (list, show)"
     subcommand "rosters", Wiq::Commands::Rosters
 
+    desc "locations SUBCOMMAND", "Team locations / sites — ID discovery for --location flags (list, show)"
+    subcommand "locations", Wiq::Commands::Locations
+
     desc "prospects SUBCOMMAND", "Prospect pipeline — individual kids (list, show, summary)"
     subcommand "prospects", Wiq::Commands::Prospects
 

data/lib/wiq/commands/events.rb

@@ -25,18 +25,25 @@ module Wiq
           --event-type     One of `wiq events types` (practice, dual_meet, ...)
           --roster         One or more roster ids (the API joins through
                            roster_events)
+          --location       One or more location ids (structured Location
+                           records; discover via `wiq locations list`)
           --expand         CSV of event_invites,event_bookings,private_lessons.
                            Drops nested data into each event row.
 
-        There is no server-side location/site filter today — `Event.location`
-        is free-text and not in `ransackable_attributes`. A location-aware
-        backend is on the WIQ roadmap; until then post-process client-side.
+        Location caveat: --location matches the event's own structured
+        location_id. Events with NO location set are excluded from a
+        filtered listing — they only appear when you don't filter. The
+        legacy free-text `location` field still exists on old events; the
+        serialized `location` value is the display form (structured record
+        when set, else the free text).
 
         Use --all to walk every page; default is page 1, per_page=100.
       DESC
       method_option :start, type: :string, required: true, desc: "YYYY-MM-DD (team timezone)"
       method_option :end, type: :string, required: true, desc: "YYYY-MM-DD (team timezone)"
       method_option :roster, type: :array, desc: "One or more roster ids"
+      method_option :location, type: :array,
+                               desc: "One or more location ids (events with no location are excluded)"
       method_option :event_type, type: :string, enum: %w[practice dual_meet tournament scramble private_lesson other],
                                  desc: "Filter to one event_type (see `wiq events types`)"
       method_option :expand, type: :string,
@@ -53,6 +60,9 @@ module Wiq
         if options[:roster]
           options[:roster].each { |rid| (params["roster_ids[]"] ||= []) << rid }
         end
+        if options[:location]
+          options[:location].each { |lid| (params["location_ids[]"] ||= []) << lid }
+        end
 
         records, total = fetch_index("/api/v1/events", params, key: "events")
         render_index(

data/lib/wiq/commands/locations.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+module Wiq
+  module Commands
+    class Locations < Base
+      desc "list", "List the team's structured locations (sites/gyms)"
+      long_desc <<~DESC
+        Locations are WIQ's structured multi-site concept — a named place
+        (with optional street address) that rosters, events, paid sessions,
+        wrestlers, metrics, and reports can be scoped to. Single-site clubs
+        typically have zero or one; multi-site clubs use them to slice
+        everything per gym.
+
+        Archived locations are hidden by default; pass --include-archived
+        to see them. Ordered by name server-side.
+
+        This is the ID-discovery surface for every --location flag in the
+        CLI:
+          wiq rosters list --location <id>
+          wiq events list --location <id> [...more ids]
+          wiq wrestlers list --location <id>
+          wiq paid_sessions list --location <id>
+          wiq metrics show <name> --location <id>
+          wiq reports run <Type> --location <id>
+      DESC
+      method_option :include_archived, type: :boolean, default: false,
+                                       desc: "Include archived locations"
+      method_option :all, type: :boolean, default: false
+      def list
+        params = { "per_page" => 100 }
+        params["include_archived"] = true if options[:include_archived]
+
+        records, total = fetch_index("/api/v1/locations", params, key: "locations")
+        render_index(
+          records, total: total,
+          summary: "Listed #{records.size} locations#{options[:include_archived] ? " (including archived)" : ""}.",
+          breadcrumbs: [
+            { "cmd" => "wiq locations show <id>", "description" => "Inspect a single location" },
+            { "cmd" => "wiq rosters list --location <id>", "description" => "Rosters at a location" },
+            { "cmd" => "wiq metrics show mrr --location <id>",
+              "description" => "Finance metrics scoped to a location (admin only)" }
+          ]
+        )
+      end
+
+      desc "show ID", "Fetch a single location"
+      long_desc <<~DESC
+        Full location payload: id, name, address_line1, address_line2,
+        city, state, postal_code, country, archived.
+      DESC
+      def show(id)
+        location = client.get("/api/v1/locations/#{id}")
+        render(location,
+               summary: "Location #{location["id"]} — #{location["name"]}",
+               breadcrumbs: [
+                 { "cmd" => "wiq rosters list --location #{location["id"]}",
+                   "description" => "Rosters at this location" },
+                 { "cmd" => "wiq wrestlers list --location #{location["id"]}",
+                   "description" => "Wrestlers on any roster at this location" }
+               ])
+      end
+    end
+  end
+end

data/lib/wiq/commands/metrics.rb

@@ -62,6 +62,13 @@ module Wiq
         Intervals: hourly, daily, weekly, monthly. Invalid values are
         silently coerced to `daily` server-side.
 
+        --location <id> scopes every metric to one structured location
+        (discover ids via `wiq locations list`). CAUTION: the server
+        validates the id against the team's own locations and silently
+        falls back to ALL locations when it doesn't match — a typo'd or
+        foreign id returns team-wide numbers, not an error. The CLI echoes
+        the requested location in `meta` so you can sanity-check.
+
         Currency metrics return integer cents (divide by 100 for dollars).
         Non-currency metrics return raw counts.
       DESC
@@ -70,6 +77,8 @@ module Wiq
                                enum: VALID_INTERVALS, desc: "interval_group"
       method_option :start_date, type: :string, desc: "Required if --range=custom"
       method_option :end_date, type: :string, desc: "Required if --range=custom"
+      method_option :location, type: :numeric,
+                               desc: "Scope to one location id (unknown ids silently mean ALL locations)"
       method_option :no_comparison, type: :boolean, default: false,
                                     desc: "Drop comparison_series/comparison_total from output"
       def show(name)
@@ -91,6 +100,7 @@ module Wiq
           params["start_date"] = options[:start_date]
           params["end_date"] = options[:end_date]
         end
+        params["location_id"] = options[:location] if options[:location]
 
         payload = client.get("/api/v1/metrics/#{name}", params)
         metrics = payload["metrics"] || {}
@@ -106,9 +116,13 @@ module Wiq
           data["comparison_total"] = metrics["comparison_total"]
         end
 
+        meta = { "currency_unit" => CURRENCY_METRICS.include?(name) ? "cents" : "count" }
+        meta["location_id"] = options[:location] if options[:location]
+
         render(data,
-               summary: "metric=#{name} range=#{options[:range]} interval=#{options[:interval]}",
-               meta: { "currency_unit" => CURRENCY_METRICS.include?(name) ? "cents" : "count" },
+               summary: "metric=#{name} range=#{options[:range]} interval=#{options[:interval]}" \
+                        "#{options[:location] ? " location=#{options[:location]}" : ""}",
+               meta: meta,
                breadcrumbs: [
                  { "cmd" => "wiq metrics list", "description" => "See all supported metrics" }
                ])

data/lib/wiq/commands/paid_sessions.rb

@@ -20,6 +20,10 @@ module Wiq
           recurring_registerable, not_recurring, not_recurring_with_archived,
           not_archived, dropin, trial, trial_or_dropin
 
+        --location <id> filters server-side to sessions stamped with that
+        structured location (discover ids via `wiq locations list`).
+        Sessions with no location are excluded when the filter is on.
+
         --season filters CLI-side to sessions whose [start_at, end_at] window
         overlaps the given calendar year. Pair with --all to get an exhaustive
         list.
@@ -30,11 +34,13 @@ module Wiq
         you usually don't need a follow-up call.
       DESC
       method_option :type, type: :string, enum: PRESET_TYPES, desc: "Preset scope filter"
+      method_option :location, type: :numeric, desc: "Filter to sessions at one location id"
       method_option :season, type: :numeric, desc: "Filter to sessions overlapping calendar year"
       method_option :all, type: :boolean, default: false
       def list
         params = { "per_page" => 50 }
         params[:type] = options[:type] if options[:type]
+        params["location_id"] = options[:location] if options[:location]
 
         records, total = fetch_index("/api/v1/paid_sessions", params, key: "paid_sessions")
 

data/lib/wiq/commands/reports.rb

@@ -26,7 +26,7 @@ module Wiq
       TYPES = {
         # ── Roster tab ───────────────────────────────────────────────
         "RosterReport" => {
-          args: %w[roster_id append_property_ids include_archived_roster_tags],
+          args: %w[roster_id location_id append_property_ids include_archived_roster_tags],
           dates: :optional,
           desc: "Roster snapshot — name, weight class, academic class, age",
           recommended: true,
@@ -41,8 +41,11 @@ module Wiq
                  "to roster at\" column (roster_memberships.created_at — when the " \
                  "wrestler landed on the roster, NOT their registration date), " \
                  "populated only for a specific --roster <id> (id > 0), not " \
-                 "--roster 0. --v1 returns fuller per-wrestler objects but drops " \
-                 "that column.",
+                 "--roster 0. With --location <id> instead, the report scopes to " \
+                 "wrestlers on any roster at that location (one row each) and " \
+                 "\"Added to roster at\" becomes their EARLIEST membership across " \
+                 "that location's rosters. --v1 returns fuller per-wrestler " \
+                 "objects but drops that column.",
           example: "wiq reports run RosterReport --roster 42"
         },
         "FullExportWrestlerReport" => {
@@ -67,52 +70,52 @@ module Wiq
 
         # ── USAW / AAU tab ───────────────────────────────────────────
         "UsawReport" => {
-          args: %w[roster_id],
+          args: %w[roster_id location_id],
           dates: :optional,
           desc: "All USA Wrestling card info on file, one row per wrestler",
           recommended: true,
           notes: "UI hides this tab when USAW collection is off (team setting)."
         },
         "UsawExpiredReport" => {
-          args: %w[roster_id],
+          args: %w[roster_id location_id],
           dates: :optional,
           desc: "Wrestlers missing or with expired USAW memberships",
           notes: "Output is also a bulk-purchase upload format for USAW's system."
         },
         "UsawExportReport" => {
-          args: %w[roster_id paid_session_id],
+          args: %w[roster_id location_id paid_session_id],
           dates: :optional,
           desc: "USAW bulk-purchase upload format",
           notes: "Only report that accepts paid_session_id=0 to mean " \
                  "\"all sessions\"."
         },
         "AauReport" => {
-          args: %w[roster_id],
+          args: %w[roster_id location_id],
           dates: :optional,
           desc: "All AAU card info on file, one row per wrestler",
           recommended: true,
           notes: "UI hides this tab when AAU collection is off (team setting)."
         },
         "AauExpiredReport" => {
-          args: %w[roster_id],
+          args: %w[roster_id location_id],
           dates: :optional,
           desc: "Wrestlers missing or with expired AAU memberships"
         },
         "AauExportReport" => {
-          args: %w[roster_id],
+          args: %w[roster_id location_id],
           dates: :optional,
           desc: "AAU bulk-purchase upload format"
         },
 
         # ── Stats tab ────────────────────────────────────────────────
         "WinLossReport" => {
-          args: %w[roster_id],
+          args: %w[roster_id location_id],
           dates: :required,
           desc: "Wins and losses per wrestler",
           recommended: true
         },
         "RosterStatsReport" => {
-          args: %w[roster_id],
+          args: %w[roster_id location_id],
           dates: :required,
           desc: "Wrestling stats per wrestler (takedowns, nearfall, etc.)",
           recommended: true
@@ -133,8 +136,10 @@ module Wiq
           recommended: true,
           notes: "One row per wrestler over the date range — totals across all " \
                  "their check-ins in the window. If you want one row per " \
-                 "check-in event use CheckInFeedReport. The UI doesn't expose " \
-                 "a roster picker; counts span the whole team.",
+                 "check-in event use CheckInFeedReport. Always team-wide: the " \
+                 "model ignores roster_id AND location_id args. For a " \
+                 "location-scoped attendance report use CheckInReport " \
+                 "--location <id> instead.",
           example: "wiq reports run CheckInSummaryReport --start 2026-05-01 --end 2026-05-31"
         },
         "CheckInFeedReport" => {
@@ -144,11 +149,12 @@ module Wiq
           recommended: true,
           notes: "Useful for \"who came to the club today and what registrations " \
                  "did they have at check-in time.\" Larger payload than the " \
-                 "summary.",
+                 "summary. Always team-wide: the model ignores roster_id AND " \
+                 "location_id args.",
           example: "wiq reports run CheckInFeedReport --start 2026-05-01 --end 2026-05-31"
         },
         "PracticeAttendanceReport" => {
-          args: %w[roster_id],
+          args: %w[roster_id location_id],
           dates: :required,
           desc: "Practice-event attendance roll-up across a date range",
           recommended: false,
@@ -159,7 +165,7 @@ module Wiq
                  "use CheckInSummaryReport or CheckInFeedReport instead."
         },
         "LastPracticeAttendedReport" => {
-          args: %w[roster_id],
+          args: %w[roster_id location_id],
           dates: :optional,
           desc: "Days since last practice attended, per wrestler",
           recommended: true,
@@ -167,7 +173,7 @@ module Wiq
                  "practice in a while — particularly for seasonal clubs."
         },
         "ChurnRiskReport" => {
-          args: %w[roster_id days_threshold],
+          args: %w[roster_id location_id days_threshold],
           dates: :optional,
           desc: "Active recurring subscribers who haven't checked in within a window",
           recommended: true,
@@ -178,7 +184,7 @@ module Wiq
           example: "wiq reports run ChurnRiskReport --roster 0 --days-threshold 30"
         },
         "CheckInReport" => {
-          args: %w[roster_id],
+          args: %w[roster_id location_id],
           dates: :required,
           desc: "Extended attendance — one row per check-in INCLUDING Q&A responses",
           notes: "UI labels this \"Attendance Extended (with questions).\" Same " \
@@ -333,6 +339,14 @@ module Wiq
         Common args (only those documented in TYPES are honored
         server-side):
           --roster <id>            roster_id (0 = all rosters)
+          --location <id>          location_id — scope the wrestler set to
+                                   one location (wrestlers on ANY roster at
+                                   that location, deduped to one row each).
+                                   Precedence: a specific --roster <id> (> 0)
+                                   WINS over --location; pass --location
+                                   alone (or with --roster 0) to get
+                                   location scoping. Discover ids via
+                                   `wiq locations list`.
           --paid-session <id>      paid_session_id (0 = all, UsawExport only)
           --event <id>             event_id (EventStatsReport)
           --fundraiser <id>        fundraiser_id (Fundraiser* reports)
@@ -369,6 +383,9 @@ module Wiq
       method_option :start, type: :string, desc: "YYYY-MM-DD"
       method_option :end, type: :string, desc: "YYYY-MM-DD"
       method_option :roster, type: :numeric, desc: "args.roster_id (0 = all rosters)"
+      method_option :location, type: :numeric,
+                               desc: "args.location_id — scope wrestlers to one location " \
+                                     "(a specific --roster <id> > 0 takes precedence)"
       method_option :paid_session, type: :numeric, desc: "args.paid_session_id"
       method_option :event, type: :numeric, desc: "args.event_id"
       method_option :fundraiser, type: :numeric, desc: "args.fundraiser_id"
@@ -529,6 +546,7 @@ module Wiq
 
           args = {}
           args["roster_id"] = options[:roster] if options[:roster] || options[:roster] == 0
+          args["location_id"] = options[:location] if options[:location]
           args["paid_session_id"] = options[:paid_session] if options[:paid_session] || options[:paid_session] == 0
           args["event_id"] = options[:event] if options[:event]
           args["fundraiser_id"] = options[:fundraiser] if options[:fundraiser]

data/lib/wiq/commands/rosters.rb

@@ -17,12 +17,19 @@ module Wiq
                                 exact name. Some teams tag rosters with
                                 conventions like "2025-26".
 
+        --location <id> filters server-side (Ransack q[location_id_eq]) to
+        rosters stamped with that structured location. Discover ids via
+        `wiq locations list`. Rosters with no location are excluded when
+        the filter is on. Each roster row embeds its location object (or
+        null) so you can also group client-side without the filter.
+
         Each roster row embeds roster_syncers and taggings, which is what
         --season uses to filter without needing extra calls.
       DESC
       method_option :season, type: :numeric,
                              desc: "Filter to rosters whose syncers point at paid sessions overlapping this year"
       method_option :season_tag, type: :string, desc: "Filter to rosters carrying this tag"
+      method_option :location, type: :numeric, desc: "Filter to rosters at one location id"
       method_option :archived, type: :boolean, desc: "Show only archived (true) or active (false)"
       method_option :all, type: :boolean, default: false
       def list
@@ -30,6 +37,7 @@ module Wiq
         unless options[:archived].nil?
           params["q[archived_eq]"] = options[:archived]
         end
+        params["q[location_id_eq]"] = options[:location] if options[:location]
 
         records, total = fetch_index("/api/v1/rosters", params, key: "rosters")
 

data/lib/wiq/commands/wrestlers.rb

@@ -20,6 +20,10 @@ module Wiq
           --first-name         q[first_name_cont]
           --last-name          q[last_name_cont]
           --roster <id>        q[rosters_id_eq] — filter to one roster
+          --location <id>      location_id (dedicated param, not Ransack) —
+                               wrestlers on ANY roster at that location.
+                               Composes with the other filters. Discover
+                               ids via `wiq locations list`.
           --weight-class       q[weight_class_numeric_eq] — exact numeric
           --academic-class     q[academic_class_eq] (senior, junior, …)
           --age                q[age_eq]
@@ -43,6 +47,8 @@ module Wiq
       method_option :first_name, type: :string, desc: "First name (contains)"
       method_option :last_name, type: :string, desc: "Last name (contains)"
       method_option :roster, type: :numeric, desc: "Filter to a single roster id"
+      method_option :location, type: :numeric,
+                               desc: "Filter to wrestlers on any roster at this location id"
       method_option :weight_class, type: :string,
                                    desc: "Weight class (exact numeric, e.g. 132)"
       method_option :academic_class, type: :string,
@@ -107,6 +113,7 @@ module Wiq
           params["q[first_name_cont]"] = options[:first_name] if options[:first_name]
           params["q[last_name_cont]"] = options[:last_name] if options[:last_name]
           params["q[rosters_id_eq]"] = options[:roster] if options[:roster]
+          params["location_id"] = options[:location] if options[:location]
           params["q[weight_class_numeric_eq]"] = options[:weight_class] if options[:weight_class]
           params["q[academic_class_eq]"] = options[:academic_class] if options[:academic_class]
           params["q[age_eq]"] = options[:age] if options[:age]
@@ -130,6 +137,7 @@ module Wiq
           bits = []
           bits << "matching #{options[:query].inspect}" if options[:query]
           bits << "in roster #{options[:roster]}" if options[:roster]
+          bits << "at location #{options[:location]}" if options[:location]
           bits << "weight class #{options[:weight_class]}" if options[:weight_class]
           bits << "profile_type=#{options[:profile_type]}" if profile_type_filter? && options[:profile_type] != "teammate"
           bits.empty? ? "" : " (#{bits.join(", ")})"

data/lib/wiq/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Wiq
-  VERSION = "0.2.0"
+  VERSION = "0.3.0"
 end

data/lib/wiq.rb

@@ -20,6 +20,7 @@ require "wiq/commands/registrations"
 require "wiq/commands/metrics"
 require "wiq/commands/events"
 require "wiq/commands/rosters"
+require "wiq/commands/locations"
 require "wiq/commands/prospects"
 require "wiq/commands/prospect_families"
 require "wiq/commands/workflows"

data/share/skills/wiq/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: wiq
-description: Use this skill when the user asks about their WrestlingIQ data — rosters, attendance, check-ins, paid sessions and registrations, the prospects/leads pipeline, financial metrics, reports, USAW/AAU memberships, fundraising, or online store orders. The `wiq` CLI provides read-only access to /api/v1 via personal access tokens. Recognize phrasings like "how is our pipeline?", "who came to practice this week?", "show me the roster", "what's our MRR?", "which kids need USAW renewal?", or anything that maps to a wrestling club's admin workflows.
+description: Use this skill when the user asks about their WrestlingIQ data — rosters, attendance, check-ins, paid sessions and registrations, the prospects/leads pipeline, financial metrics, reports, USAW/AAU memberships, fundraising, online store orders, or per-location/site breakdowns for multi-gym clubs. The `wiq` CLI provides read-only access to /api/v1 via personal access tokens. Recognize phrasings like "how is our pipeline?", "who came to practice this week?", "show me the roster", "what's our MRR?", "which kids need USAW renewal?", "how is the Eastside gym doing?", or anything that maps to a wrestling club's admin workflows.
 ---
 
 # WrestlingIQ CLI Skill
@@ -223,9 +223,14 @@ join date is in the default output.
   resolves to paid_session ids whose date range overlaps the calendar
   year, then filters client-side. There's no first-class Season entity
   in WIQ.
-- **`Event.location` is free-text and not filterable.** No `--site` or
-  `--location` flag exists yet. A structured location concept is on the
-  WIQ roadmap.
+- **Legacy free-text `Event.location` vs structured locations.** Old
+  events carry a free-text `location` string; the serialized `location`
+  field is the display form (structured Location name/address when
+  `location_id` is set, else the legacy text). `--location` filters only
+  match the structured `location_id` — events, rosters, and paid sessions
+  with NO location set are excluded from filtered listings, so an empty
+  filtered result doesn't mean "nothing happened", it may mean "nothing
+  is stamped with that location yet."
 - **Index responses are wrapped.** Every `/api/v1` index returns
   `{"<resource>": [...]}` — the CLI unwraps internally, but if you ever
   hit the API directly remember to unwrap.
@@ -338,13 +343,58 @@ For exhaustive exports go through `wiq reports run RosterReport`
 `profile_type=teammate` (matching the WIQ web UI default); pass
 `--profile-type alumnus|guest|all` to widen.
 
+## Locations (multi-site clubs)
+
+WIQ has a structured Location model (name + street address, per team).
+Multi-gym clubs stamp rosters, events, and paid sessions with a
+location; single-site clubs usually have none, and every `--location`
+flag is simply irrelevant for them.
+
+Discover ids first — this is the anchor for everything below:
+
+```bash
+wiq locations list                     # id, name, address, archived
+wiq locations list --include-archived
+```
+
+Then scope any of these surfaces:
+
+| Command | Flag | Semantics |
+| --- | --- | --- |
+| `wiq rosters list` | `--location <id>` | Rosters stamped with that location (`q[location_id_eq]`) |
+| `wiq events list` | `--location <id> [<id>...]` | Events at those locations (repeatable; unset-location events excluded) |
+| `wiq paid_sessions list` | `--location <id>` | Sessions stamped with that location |
+| `wiq wrestlers list` | `--location <id>` | Wrestlers on ANY roster at that location; composes with other filters |
+| `wiq metrics show <name>` | `--location <id>` | Per-location finance metrics (the payment-dashboard filter) |
+| `wiq reports run <Type>` | `--location <id>` | Scopes the wrestler set for the 13 location-aware report types |
+
+Three gotchas an agent must know:
+
+1. **Reports precedence:** a specific `--roster <id>` (> 0) WINS over
+   `--location` in report args. Pass `--location` alone (or with
+   `--roster 0`) to get location scoping. A wrestler on multiple rosters
+   at the location collapses to one row; RosterReport's "Added to roster
+   at" becomes their EARLIEST membership across that location's rosters.
+   `CheckInSummaryReport` / `CheckInFeedReport` ignore both args
+   entirely (always team-wide) — use `CheckInReport --location <id>` for
+   location-scoped attendance.
+2. **Metrics fail silent, not loud:** an unknown or foreign `--location`
+   id on `wiq metrics show` silently falls back to ALL locations —
+   team-wide numbers, no error. Verify the id against
+   `wiq locations list` before quoting per-site revenue to the user.
+3. **Nothing is auto-stamped retroactively.** Filters only match records
+   whose `location_id` is set. Empty filtered results on a club that
+   just adopted locations usually mean unstamped data, not zero
+   activity. Rosters/events/paid_sessions embed their `location` object
+   (or null) in list payloads, so you can check coverage cheaply.
+
 ## What's NOT available (yet)
 
 The CLI is read-only by design except for report submission. You
 cannot via this CLI:
 
 - Create/edit prospects, families, notes, check-ins, events, paid
-  sessions, rosters, or any other resource
+  sessions, rosters, locations, or any other resource
 - Mint, list, or revoke PATs (use the web UI at
   `<host>/settings/personal_access_tokens`)
 - Mark attendance, advance prospect stages, log contact notes

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: wiq-cli
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.0
 platform: ruby
 authors:
 - WrestlingIQ
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-05-29 00:00:00.000000000 Z
+date: 2026-07-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: thor
@@ -90,6 +90,7 @@ files:
 - lib/wiq/commands/check_ins.rb
 - lib/wiq/commands/doctor.rb
 - lib/wiq/commands/events.rb
+- lib/wiq/commands/locations.rb
 - lib/wiq/commands/metrics.rb
 - lib/wiq/commands/paid_sessions.rb
 - lib/wiq/commands/prospect_families.rb