wiq-cli 0.1.0

data/share/skills/wiq/SKILL.md

@@ -0,0 +1,348 @@
+---
+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.
+---
+
+# WrestlingIQ CLI Skill
+
+`wiq` is a read-only Ruby CLI for WrestlingIQ data, designed to be driven
+by both humans and AI agents. It hits `/api/v1` using per-user personal
+access tokens (PATs). This skill orients you to its shape; the CLI itself
+is the source of truth for what's available right now.
+
+## Bootstrap (always do this first)
+
+Three calls give you the entire usable surface:
+
+```bash
+wiq doctor               # Confirms reach, identity, and which team you're scoped to
+wiq commands             # JSON dump of every command, option, enum (42 KB; cache this)
+wiq workflows list       # 14 curated multi-step recipes by category
+```
+
+Run these BEFORE inventing commands. The `wiq commands` output is
+authoritative — if it doesn't appear there, it doesn't exist in this
+build of the CLI.
+
+## Three core surfaces
+
+**`wiq commands`** — flat machine-readable JSON tree of the CLI. Use this
+when you need to know what commands exist, what options they take, what
+enums are valid. Cache the output in your context; it doesn't change
+within a session.
+
+**`wiq workflows`** — named recipes for common questions. Each workflow
+has a structured `parameters` list, a `recipe` of command strings with
+`<placeholder>` and `[--flag <name>]` substitutions, an `admin_only`
+flag, and notes. Map the user's natural-language question to a workflow
+when one fits; fall back to composing commands otherwise.
+
+**`wiq reports types`** — curated allowlist of WIQ's 36 report types with
+`recommended:` / `admin_only:` / `prefer:` / `notes:` / `example:`
+metadata. When a user asks for "an attendance report" or "a finance
+report", check this list first — the WIQ team has marked the right pick
+per situation.
+
+## Auth model (load-bearing)
+
+- **PATs are bound to a single profile at mint time.** A user with
+  CoachProfile + ParentProfile on different teams mints a separate token
+  per role. The CLI does not switch profiles at runtime.
+- **Everything is gated by the bound profile's permissions.** Parent or
+  wrestler PATs cannot run reports (`enforce_pat_restrictions` returns 403
+  with body `"Personal access tokens are read-only..."` — reports is the
+  one write currently on the PAT allowlist).
+- **The 9 finance reports require `admin?`.** They're flagged
+  `admin_only: true` in `wiq reports types`. Workflows that submit them
+  carry the same flag. Non-admin coach PATs 403 on these.
+- **`elite` and `payments_enabled` are NOT API gates.** They're team
+  attributes that affect UI tab rendering only. Ignore them when
+  reasoning about API access.
+
+## Multi-club (alias mechanic)
+
+A single user may have PATs for multiple clubs on the same host
+(`www.wrestlingiq.com`). The CLI stores them by `host → alias` in
+`~/.config/wiq/credentials.json`:
+
+```bash
+wiq auth list                          # See all stored credentials
+wiq auth status                        # Resolved alias + bound profile
+wiq --as westside rosters list         # Use a specific alias
+WIQ_ALIAS=westside wiq events list     # Same via env var
+```
+
+Resolution chain: `--as` flag → `WIQ_ALIAS` env → `.wiq/config.json` →
+sole alias for host → literal `"default"`. Ambiguous-alias errors
+include a list of available aliases in the `hint:` field.
+
+## Output modes
+
+| Mode | When it kicks in |
+| --- | --- |
+| `--json` | Full envelope: `{ok, data, summary, breadcrumbs, meta}`. Best for agents needing context. |
+| `--agent` | Bare `data` as JSON, no envelope, no prompts. Best for headless piping. |
+| (default) | Pretty JSON when stdout is a TTY; otherwise bare JSON (same as `--agent`). |
+
+The envelope's `breadcrumbs` array suggests obvious next-step commands —
+read it when deciding what to do after a response.
+
+## Error model
+
+All errors come back as a stable JSON envelope on stderr with a
+non-zero exit code:
+
+```json
+{ "ok": false, "error": "...", "code": "...", "hint": "...", "details": ... }
+```
+
+Common codes and the right response:
+
+| `code` | Meaning | What to do |
+| --- | --- | --- |
+| `host_unset` | No host configured (unusual; production is the default) | `wiq auth login` |
+| `not_authenticated` | No PAT stored for the resolved host | `wiq auth login` |
+| `ambiguous_alias` | Multiple aliases stored, none "default" | Pass `--as <alias>` (hint lists choices) |
+| `alias_not_found` | `--as` named a slot that doesn't exist | Check `wiq auth list` |
+| `unauthorized` (401) | Token rejected by server | Re-login; could be revoked |
+| `forbidden` (403) | Pundit denial (often admin gate on a finance report) | Check the report's `admin_only:` flag in `wiq reports types` |
+| `not_found` (404) | Resource doesn't exist for this profile | Confirm the id; cross-team enumeration returns 404 to avoid leaking existence |
+| `validation_failed` (422) | Server-side input rejection | Read `details` for per-field messages |
+| `rate_limited` (429) | 100 req / 3 sec per IP exceeded | Back off |
+| `season_not_found` | `--season <year>` matched zero paid sessions | `wiq paid_sessions list` to see configured periods |
+| `report_failed` | The report ran but errored server-side | Inspect `details` (the report's result jsonb) |
+| `report_timeout` | Polling exceeded `--timeout` | Re-run with longer `--timeout` or check later with `wiq reports show <id>` |
+
+## Rate-limit etiquette
+
+WIQ enforces **100 requests per 3 seconds per source IP** (≈ 33 req/sec).
+It's a per-IP throttle, not per-PAT — multi-club aliases on the same
+workstation share the budget.
+
+In practice the CLI rarely hits it because:
+
+- Pagination (`--all`) walks pages sequentially, naturally rate-limited
+  by request latency (100–500ms round-trip = 2–10 req/sec, well under).
+- Report polling backs off exponentially (2s → 30s cap).
+- Transient 429s are auto-retried by the Faraday middleware (3 attempts,
+  exponential backoff, `Retry-After` honored).
+
+**Agent guidance:** invoke `wiq` commands **sequentially** from scripts.
+Don't parallelize a fan-out (e.g. running three `wiq metrics show`
+calls at once) — the per-IP budget is shared across every concurrent
+process. If you see `code: "rate_limited"` after the auto-retries
+exhaust, treat it as backpressure: wait ~3 seconds, then continue
+sequentially. It's not a bug; you're just moving faster than the
+server wants you to.
+
+## Pagination
+
+Index endpoints (`wiq rosters list`, `wiq events list`, etc.) page at 30
+per page by default. The CLI surfaces this in two ways:
+
+- Without `--all`: returns page 1 only. The envelope `meta` block carries
+  `total` (server-side total record count).
+- With `--all`: follows `Link: rel=next` until exhausted. Required when
+  doing CLI-side filtering (`--season`, `--site` if it ever lands) since
+  filters apply *after* the fetch.
+
+The server's `TotalCount` header is non-standard capitalization (not
+`X-Total-Count`); the CLI handles this internally.
+
+## Reports — choosing the right type
+
+Use `wiq reports types` as the decision matrix. Three guidelines:
+
+1. **`recommended: true` entries are the WIQ-blessed picks.** When a
+   user's question matches multiple reports, prefer recommended ones
+   unless they specifically asked for a non-recommended variant.
+2. **`recommended: false` with `prefer:` lists alternatives.** Example:
+   `PracticeAttendanceReport` is deprecated → use `CheckInSummaryReport`
+   or `CheckInFeedReport` instead.
+3. **`admin_only: true` reports require `admin?` permission.** If the
+   PAT isn't admin, the submit returns 403. Check the bound profile's
+   permission level before suggesting an admin report.
+
+Key reports an agent should know by heart:
+
+- **`CheckInSummaryReport`** — "How many practices did each wrestler
+  attend?" (one row per wrestler, totals).
+- **`CheckInFeedReport`** — "Who came today?" (one row per check-in).
+- **`ChurnRiskReport`** — Active subscribers who haven't checked in
+  within N days (7, 14, 30, 60, 90). Requires `--days-threshold`.
+- **`RosterReport`** — Roster snapshot with optional custom columns via
+  `--append-properties <q_ids>`. Discover ids via `wiq registrations questions`.
+- **`LastPracticeAttendedReport`** — "Who hasn't been to practice in a
+  while?"
+- **`PaidSessionAccountingReport`** (admin_only) — Line-item charges for
+  a paid session.
+
+For anything else, `wiq reports types` is faster than guessing.
+
+## Reports — polling
+
+Submit + poll is the API's canonical async pattern:
+
+```bash
+wiq reports run <Type> --start <date> --end <date> [args]
+# Submits, then polls every 2s (backoff to 30s cap) until ready.
+# Default timeout 5 min; --timeout overrides.
+```
+
+`--no-wait` returns immediately after submit; poll later with
+`wiq reports show <id> --wait`. Status values: `requested → queued →
+processing → ready` (terminal) | `failed` (terminal). `result` is the
+type-specific jsonb payload.
+
+## Common gotchas
+
+- **`roster_id=0` = "all rosters"** in report args. UI convention; if
+  you want all rosters, pass `--roster 0` explicitly. Reports always
+  accept it.
+- **`paid_session_id=0` = "all sessions"** is accepted by ONE report
+  only: `UsawExportReport`. Anywhere else, `0` causes a 404 on
+  `PaidSession.find(0)`.
+- **`--season <year>` is CLI-side filtering, not a server param.** It
+  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.
+- **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.
+- **Custom registration columns are `RosterReport`-only.** The
+  `--append-properties` flag is accepted by other reports but only
+  RosterReport's model code reads it.
+- **`days_threshold` for `ChurnRiskReport`** accepts only `7, 14, 30,
+  60, 90`. Any other value silently falls back to 30 server-side.
+- **`wrestler_id` vs `wrestler_profile_id`.** The API uses both
+  interchangeably in different endpoints — the CLI normalizes, but if
+  you're constructing URLs yourself, expect the inconsistency.
+
+## Integer-backed enums (Ransack gotcha for future write paths)
+
+Some WIQ models back enums with integers (Rails default). Ransack 4.x
+does NOT translate enum strings to integers on those columns — sending
+`q[status_eq]=failed` against an integer column silently drops the
+predicate and returns every row, not zero rows.
+
+The CLI translates internally for the surfaces it exposes
+(`wiq charges list --status`, `wiq check_ins event --status`). If you
+construct ad-hoc `q[...]` filters via `curl` or a future surface, watch
+for this. Known integer-enum columns the CLI touches today:
+
+| Model | Field | Values |
+| --- | --- | --- |
+| Charge | status | successful (0), failed (1) |
+| CheckIn | status | unknown (0), present (1), absent (2), excused (3), unexcused (4), late (5), injured (6), other (7) |
+| WrestlerProfile | gender | male (0), female (1), other (2) |
+| PaidSession | usaw_override / aau_override | disabled (0), optional (1), require_id_and_expires (2), require_all (3) |
+
+String columns (Prospect.stage, WrestlerProfile.profile_type / academic_class)
+do NOT have this issue — Ransack matches the string directly.
+
+## Payment debugging
+
+For "did Johnny pay X?" / "what's failing right now?" / "is this family's
+subscription healthy?" — use the charges surface (admin coach PAT only):
+
+```bash
+wiq charges list --status failed --since 2026-04-01
+wiq charges list --billing-profile <id> --since 2026-04-01 --all
+wiq billing_profiles show <parent_profile_id> --profile-type ParentProfile
+```
+
+**Critical: a failed charge alone is NEVER actionable.** Stripe/Justifi
+retry subscriptions automatically and customers re-enter cards after
+declines, so most failures resolve themselves silently. Before
+flagging anything as needing follow-up, cross-check that no successful
+charge for the same `(billing_profile_id, chargeable_id,
+chargeable_type)` tuple exists AFTER the failure's `created_at`. The
+canonical pattern is in `wiq workflows show failed-payments-recent`.
+
+To go from a wrestler name to a billing_profile_id:
+
+```bash
+wiq wrestlers list --query "Johnny Smith"               # find wrestler_id
+wiq wrestlers show <wrestler_id>                        # find parent_profile_id
+wiq billing_profiles show <parent_id> --profile-type ParentProfile  # billing_profile_id
+wiq charges list --billing-profile <bp_id>              # their payment history
+```
+
+WrestlerProfile cannot have billing profiles directly — always walk
+through a parent.
+
+## ID discovery
+
+### Disambiguating "who is X?"
+
+WIQ tracks people in three states. When the user asks about a person by
+name (e.g., "show me Johnny"), decide which scope to search FIRST,
+based on context:
+
+| If recent context is about… | Search this |
+| --- | --- |
+| Leads / pipeline / trials / "potential new kid" | `wiq prospect_families list --query <name>` |
+| Active club members / attendance / rosters / subscriptions | `wiq wrestlers list --query <name>` |
+| Former members / graduates | `wiq wrestlers list --query <name> --profile-type alumnus` |
+| Truly ambiguous, no prior context | **Ask the user.** Don't fan out across both. |
+
+Don't default to wrestlers because it's listed first alphabetically —
+that wastes a call when the user is clearly asking about a lead.
+
+### How `--query` actually matches
+
+- **`wiq wrestlers list --query`** — name search (first/last) against
+  active WrestlerProfile rows on the team.
+- **`wiq prospect_families list --query`** — searches BOTH family
+  contact (name, email, phone — digits stripped for phone match) AND
+  child first/last names via a subquery. A "Johnny" search matches a
+  parent named Johnny OR a child named Johnny; check
+  `child_first_name` on the embedded prospects array to tell which.
+- **`wiq prospects list --query`** — same scope as families above, but
+  currently returns HTTP 500 due to a server-side ambiguous-column bug
+  (tracked in `docs/deferred.md`). Use `prospect_families list --query`
+  instead until the WIQ-app fix ships.
+
+### Wrestlers-specific filters
+
+```bash
+wiq wrestlers list --query "Jane Smith"
+wiq wrestlers list --last-name Smith
+wiq wrestlers list --roster 42 --weight-class 132
+```
+
+Narrow surface on purpose: default page size 20, no `--all` flag.
+For exhaustive exports go through `wiq reports run RosterReport`
+(with `--append-properties` for custom columns) or
+`wiq reports run FullExportWrestlerReport`. The list defaults to
+`profile_type=teammate` (matching the WIQ web UI default); pass
+`--profile-type alumnus|guest|all` to widen.
+
+## 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
+- Mint, list, or revoke PATs (use the web UI at
+  `<host>/settings/personal_access_tokens`)
+- Mark attendance, advance prospect stages, log contact notes
+- Trigger event-change notifications or roster re-sync jobs
+
+If the user asks for a write operation, tell them it's not yet exposed
+and point them at the WIQ web UI for now.
+
+## When to compose vs run a workflow
+
+- **Run a workflow** when the user's question matches one closely. They
+  encode WIQ's recommended patterns and reduce drift risk.
+- **Compose ad-hoc** when the user wants something workflow-shaped but
+  with twists (date range, roster scope, additional filtering).
+  Reference the workflow's recipe as a template, then adapt.
+- **Never** compose finance commands without first checking
+  `wiq auth status` to confirm `admin?` permission — saves the agent
+  from running into avoidable 403s mid-sequence.

metadata

@@ -0,0 +1,141 @@
+--- !ruby/object:Gem::Specification
+name: wiq-cli
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- WrestlingIQ
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2026-05-22 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: thor
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.3'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.3'
+- !ruby/object:Gem::Dependency
+  name: faraday
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.9'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.9'
+- !ruby/object:Gem::Dependency
+  name: faraday-retry
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.2'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.2'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.13'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.13'
+description: Agent-native CLI for reading WrestlingIQ data via /api/v1 personal access
+  tokens.
+email:
+- support@wrestlingiq.com
+executables:
+- wiq
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- bin/wiq
+- docs/deferred.md
+- docs/wiq_api_notes.md
+- lib/wiq.rb
+- lib/wiq/cli.rb
+- lib/wiq/client.rb
+- lib/wiq/commands/auth.rb
+- lib/wiq/commands/base.rb
+- lib/wiq/commands/billing_profiles.rb
+- lib/wiq/commands/charges.rb
+- lib/wiq/commands/check_ins.rb
+- lib/wiq/commands/doctor.rb
+- lib/wiq/commands/events.rb
+- lib/wiq/commands/metrics.rb
+- lib/wiq/commands/paid_sessions.rb
+- lib/wiq/commands/prospect_families.rb
+- lib/wiq/commands/prospects.rb
+- lib/wiq/commands/registrations.rb
+- lib/wiq/commands/reports.rb
+- lib/wiq/commands/rosters.rb
+- lib/wiq/commands/setup.rb
+- lib/wiq/commands/workflows.rb
+- lib/wiq/commands/wrestlers.rb
+- lib/wiq/config.rb
+- lib/wiq/credentials.rb
+- lib/wiq/errors.rb
+- lib/wiq/introspection.rb
+- lib/wiq/output.rb
+- lib/wiq/pagination.rb
+- lib/wiq/season_resolver.rb
+- lib/wiq/version.rb
+- lib/wiq/workflows.rb
+- share/skills/wiq/SKILL.md
+homepage: https://github.com/wrestlingiq/wiq-cli
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/wrestlingiq/wiq-cli
+  source_code_uri: https://github.com/wrestlingiq/wiq-cli
+  bug_tracker_uri: https://github.com/wrestlingiq/wiq-cli/issues
+  documentation_uri: https://github.com/wrestlingiq/wiq-cli#readme
+  rubygems_mfa_required: 'true'
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.1.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.3.27
+signing_key:
+specification_version: 4
+summary: Command-line interface for the WrestlingIQ API
+test_files: []