wiq-cli 0.5.0 → 0.6.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: eb99112754a10af0b80b20d71425f95e864fb28a3db78a1c3d0e7d75340ebf8f
-  data.tar.gz: ee12d73a7e5053dd48540c73c35e4327bb3f4456998f3182725b2a1d40a99403
+  metadata.gz: ec283a11b87c6ba8e2f8db5bf5a56f5e02fbf092aa3fb93fab54d08660553aa3
+  data.tar.gz: 1afd0ade5f5de6770c74acdd5d3fb0f2c68721f1537b0344a2ab6a401f32a400
 SHA512:
-  metadata.gz: 92e5c6842312a60ad606f711b5c6893c2a2c761e181b0c999dcf0fcb6bb1e92f8cc3b25dadd6c365656b91f7b242666b43131e5680ec440036c67868f04eb794
-  data.tar.gz: a4e06d43acf373996c31593b6a736555ab9b5aa71a4d7c0baf606f8dc76fa090f3ae7519820ec04ed6ca1167375b977261d12312bca2fe07b70de86f902430e6
+  metadata.gz: 93172776f6f73aac7093aa64b04bade0de00cc633f6b8e17b6a4c3a7898c3b8148fc98b9ccb108ab22df639b2e56c26b167e6f85ed22013cadd444f4d1fac574
+  data.tar.gz: 075e0ab62fb1098c04a0a7714825eef7ea0b8ad450e1d21703cbf2fe6c60b8d58f8ca2d2616ba6b8ead65ec9237db681737408476692aab9b0443847637d2ebc

data/README.md

@@ -7,9 +7,10 @@
 > recommended for production-critical automation. Pin your gem version
 > if you build anything load-bearing on top of it.
 
-Read-only command-line interface for [WrestlingIQ](https://www.wrestlingiq.com).
+Command-line interface for [WrestlingIQ](https://www.wrestlingiq.com).
 Designed to be driven by both humans and AI agents (Claude Code, Cursor,
-etc.) via per-user personal access tokens (PATs).
+etc.) via per-user personal access tokens (PATs). Every token can read;
+tokens minted with a write scope can also work the leads pipeline.
 
 ## Getting started
 
@@ -39,6 +40,13 @@ coach, your CLI will be able to run admin reports; if you're not, it
 won't. Either way, the token can be revoked anytime from the same
 page.
 
+Tokens are read-only unless you tick a write permission when minting
+one. Today that's **Create and edit leads** (`prospects:write`) and
+**Create reports** (`reports:write`). A team admin has to enable each
+capability for the club first under **Settings → API Access**; the
+token picker only offers what the team allows. Scopes are fixed for the
+life of a token — to change them, revoke it and mint a new one.
+
 ### 3. Log in
 
 ```bash
@@ -81,6 +89,7 @@ Now you can ask Claude things like:
 ```bash
 wiq rosters list                                            # Browse rosters
 wiq prospects summary                                       # Pipeline dashboard
+wiq prospects advance 123 trial_scheduled                   # Move a lead forward (needs prospects:write)
 wiq events list --start 2026-05-01 --end 2026-05-31         # Calendar
 wiq workflows list                                          # Curated multi-step recipes
 wiq reports types                                           # 36 report types w/ recommendations
@@ -135,9 +144,11 @@ output (the CLI never logs your token — paste the full JSON safely).
 
 ## Status
 
-v0.1.0 — 29 commands across 16 groups, 117 RSpec smoke examples.
-Reads-only except for report submission (the API's canonical async
-pattern). Write commands deferred — see `docs/deferred.md`.
+v0.6.1 — reads across every group, plus report submission and a
+scoped write surface for the prospects pipeline (`prospect_families
+create/update/note`, `prospects create/update/advance`) gated by the
+`prospects:write` token scope. Other write commands deferred — see
+`docs/deferred.md`.
 
 ## License
 

data/docs/deferred.md

@@ -81,17 +81,14 @@ Last updated: 2026-05-12 (after L1 ships).
 - **`wiq url parse <url>`** — extract team/roster/event IDs from WIQ web
   URLs. Initial-plan item; useful for agents pasted URLs by humans.
 - **`wiq paid_sessions create/update`**, **`wiq rosters create/update`**,
-  etc. — every write path on every resource. v1 is reads-only except
-  report submission. Cherry-pick as customers ask.
-- **Prospect write commands.** API supports `POST /prospect_families`,
-  `PATCH /prospect_families/:id` (incl. assigned_coach), `DELETE`,
-  `POST /prospect_families/:id/prospects`, `PATCH /prospects/:id`
-  (incl. stage transitions via `advance_to!`), and
-  `POST /prospect_families/:id/notes` (with `clear_follow_up_for[]` /
-  `add_follow_up_for[]` side-effect params). Reads-only in v1 — most
-  pipeline edits happen in the drawer UI today, and exposing
-  stage-transition writes without first watching agents use them is
-  asking for trouble.
+  etc. — every other write path. Each needs a server-side capability in
+  `ApiCapability::REGISTRY` first (writes fail closed without one), then
+  a CLI command. Cherry-pick as customers ask.
+- **Prospect deletes.** Shipped in v0.6.0: `prospect_families
+  create/update/note` and `prospects create/update/advance` behind the
+  `prospects:write` scope. `DELETE /prospect_families/:id` and
+  `DELETE /prospects/:id` remain out of reach — destroy actions are in
+  no API capability server-side, by design.
 
 ## Packaging / distribution
 
@@ -133,16 +130,10 @@ Last updated: 2026-05-12 (after L1 ships).
 
 ## Backend asks (push back to WIQ app team)
 
-- **`GET /api/v1/prospects?query=<str>` 500s on ambiguous ORDER BY.**
-  Found during the Phase 5 agent telemetry pass. The controller does
-  `Prospect.joins(:prospect_family).merge(ProspectFamily.search(query))
-  .order(created_at: :desc)` — both `prospects` and `prospect_families`
-  have `created_at`, so the join makes the order ambiguous. One-line
-  fix on the WIQ-app side: change to
-  `.order("prospects.created_at DESC")` (or
-  `.order(Prospect.arel_table[:created_at].desc)`). The CLI documents
-  the workaround (use `wiq prospect_families list --query` — same
-  matches, returns families with prospects embedded) until this ships.
+- ~~**`GET /api/v1/prospects?query=<str>` 500s on ambiguous ORDER BY.**~~ —
+  SHIPPED (WIQ-app commit 7ac9d90a5, 2026-05-21, qualifies the ORDER BY
+  as `prospects.created_at`). `wiq prospects list --query` works; the
+  KNOWN BUG note was removed from its long_desc in v0.6.0.
 
 
 - ~~**`days_threshold` permit fix on `Api::V1::ReportsController`**~~ —

data/docs/wiq_api_notes.md

@@ -288,13 +288,49 @@ file with the WIQ team.
     permit list as of the May 2026 WIQ-app fix. The CLI's
     `--days-threshold` flag lands unchanged on the model.
 
+**PAT write capabilities (`Api::V1::BaseController#enforce_pat_restrictions`):**
+
+PAT traffic is read-only by default. A non-GET request succeeds only when
+`ApiCapability.for(controller, action)` resolves to a capability that
+(a) the team has enabled (`Team#api_write_capabilities`, editable by an
+admin at `/settings/team/api_access`) and (b) the token carries
+(`PersonalAccessToken#scopes`, immutable after mint, coach tokens only).
+Registry today:
+
+| Capability | Actions |
+| --- | --- |
+| `prospects:write` | `prospect_families#create/#update`, `prospects#create/#update`, `prospect_family_notes#create` |
+| `reports:write` | `reports#create` |
+
+Unregistered writes (every `destroy`, everything else) fail closed with
+`"This endpoint is not writable with a personal access token."` The other
+two denials name the capability verbatim — the CLI regexes on them:
+
+| Body | CLI `code` |
+| --- | --- |
+| `This endpoint is not writable with a personal access token.` | `pat_write_unsupported` |
+| `This team has not enabled <cap> for API access. …` | `capability_disabled_for_team` |
+| `This token lacks the <cap> scope. Revoke it and mint a new token …` | `token_missing_scope` |
+
+Team policy is re-checked per request, so an admin turning a capability
+off disables every token holding it immediately. Every PAT call writes an
+audit row (`PersonalAccessTokenAuditJob`) carrying the capability + scopes.
+`GET /api/v1/personal_access_tokens` now includes `scopes: [...]` per
+token; the CLI stores it at login and shows it in `auth status` / `doctor`.
+
+Prospect-specific PAT rule (`ProspectsController#update`): stage changes
+are not forced for token callers, so `advance_to!` refuses downgrades and
+moves out of a terminal stage. The controller turns that silent no-op
+into a 422 `"Stage cannot move from <a> to <b> with a personal access
+token …"` → CLI code `stage_transition_refused`.
+
 **Auth model (POST /api/v1/reports):**
 
 - Every report POST requires a `CoachProfile`-bound PAT on the same team
-  (`coach_belongs_to_team?` in `ReportPolicy#create?`). Parent/wrestler
-  PATs return 403 with body `"Personal access tokens are read-only..."`
-  via `enforce_pat_restrictions` — reports is the one write currently on
-  the PAT allowlist.
+  (`coach_belongs_to_team?` in `ReportPolicy#create?`) AND the
+  `reports:write` capability (backfilled onto every existing team and
+  token when per-token scopes shipped, so nothing changed for existing
+  scripts). See "PAT write capabilities" below.
 - A subset of report types — the 9 listed in `Report.finance_types`
   (Membership, PaidSessionAccounting, RecurringDonor, DonationTransaction,
   FundraiserSummary, FundraiserAccounting, InProgressRegistration,
@@ -343,7 +379,7 @@ DiscountedSubscriptionsReport, **DonationTransactionReport**,
 PaidSessionAddOnDetailReport, PaidSessionAddOnSummaryReport,
 **PracticeAttendanceReport**, **RecurringDonorReport**, RegistrationAnswerReport,
 **RegistrationFinanceSummaryReport**, **RosterReport**, **RosterStatsReport**,
-**ScholarshipAuditReport**, SessionRegistrationAnswerReport,
+**ScholarshipAuditReport**, **SessionRegistrationAnswerReport**,
 TeamRegistrationRosterReport, UsawExpiredReport, UsawExportReport, UsawReport,
 **WinLossReport**, **WrestlersWithoutSubscriptionsReport**`
 

data/lib/wiq/cli.rb

@@ -68,10 +68,10 @@ module Wiq
     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)"
+    desc "prospects SUBCOMMAND", "Prospect pipeline — individual kids (list, show, summary; create, update, advance need prospects:write)"
     subcommand "prospects", Wiq::Commands::Prospects
 
-    desc "prospect_families SUBCOMMAND", "Prospect pipeline — households (list, show, notes)"
+    desc "prospect_families SUBCOMMAND", "Prospect pipeline — households (list, show, notes, stage_changes, linked_answers; create, update, note need prospects:write)"
     subcommand "prospect_families", Wiq::Commands::ProspectFamilies
 
     desc "workflows SUBCOMMAND", "Named multi-step recipes for common club-admin questions (list, show)"

data/lib/wiq/client.rb

@@ -9,7 +9,8 @@ module Wiq
   # Thin wrapper around Faraday that:
   #   - Adds Authorization: Bearer <pat>
   #   - Parses JSON requests and responses
-  #   - Retries on 429 and 5xx (Retry-After honored)
+  #   - Retries on 429 and 5xx (Retry-After honored) — GET/HEAD only, so a
+  #     write is never replayed
   #   - Translates non-2xx responses into Wiq::APIError
   #   - Exposes paginate(path, params) that walks the Link: rel=next chain
   class Client
@@ -36,6 +37,10 @@ module Wiq
       request(:put, path, body: body)
     end
 
+    def patch(path, body = {})
+      request(:patch, path, body: body)
+    end
+
     def delete(path, params = {})
       request(:delete, path, params: params)
     end

data/lib/wiq/commands/auth.rb

@@ -21,8 +21,14 @@ module Wiq
 
         Verification: the CLI hits `GET /api/v1/personal_access_tokens` to
         confirm the token works AND fetch the bound profile (display_name,
-        team_name, type) in one round trip. That metadata is shown after
-        login and stored alongside the token.
+        team_name, type) plus the token's write `scopes` in one round trip.
+        That metadata is shown after login and stored alongside the token.
+
+        Scopes: every PAT can read. Writes need a capability (currently
+        prospects:write, reports:write) that the team admin has enabled
+        under Settings → API Access AND that the token was minted with.
+        Scopes are immutable — to change them, revoke and mint a new
+        token, then re-run this command with --force.
       DESC
       method_option :token, type: :string, desc: "PAT value (otherwise prompted interactively)"
       method_option :force, type: :boolean, default: false,
@@ -64,7 +70,8 @@ module Wiq
           token: token,
           token_prefix: metadata[:token_prefix],
           name: metadata[:name],
-          profile: metadata[:profile]
+          profile: metadata[:profile],
+          scopes: metadata[:scopes]
         )
 
         render(
@@ -74,10 +81,11 @@ module Wiq
             "token_prefix" => metadata[:token_prefix],
             "name" => metadata[:name],
             "profile" => metadata[:profile],
+            "scopes" => metadata[:scopes],
             "stored_at" => Wiq::Credentials.for_host(host, alias_name)["stored_at"]
           }.compact,
           summary: profile_summary("Stored PAT for #{host} as #{alias_name.inspect}",
-                                   metadata[:profile]),
+                                   metadata[:profile], metadata[:scopes]),
           breadcrumbs: [
             { "cmd" => "wiq auth status --as #{alias_name}",
               "description" => "Verify the stored token works" },
@@ -93,7 +101,9 @@ module Wiq
 
         Performs a best-effort live probe against
         `/api/v1/personal_access_tokens` to confirm the token still works
-        and surface the live last_used_at. If the probe fails (network,
+        and surface the live last_used_at and write `scopes` (empty =
+        read-only). Check `live_scopes` before attempting a write command
+        such as `wiq prospects advance`. If the probe fails (network,
         revoked token, host unreachable), the error appears in `live_error`
         rather than aborting the command — local state is always shown.
 
@@ -126,9 +136,11 @@ module Wiq
           "token_prefix" => store_entry["token_prefix"],
           "stored_name" => store_entry["name"],
           "stored_profile" => store_entry["profile"],
+          "stored_scopes" => store_entry["scopes"],
           "live_name" => live_metadata&.dig(:name),
           "live_last_used_at" => live_metadata&.dig(:last_used_at),
           "live_profile" => live_metadata&.dig(:profile),
+          "live_scopes" => live_metadata&.dig(:scopes),
           "live_error" => live_error
         }.compact
 
@@ -138,7 +150,8 @@ module Wiq
                           : "No alias resolvable for this host."
           else
             profile_summary("Token reachable (alias=#{cfg.alias_name})",
-                            live_metadata&.dig(:profile) || store_entry["profile"])
+                            live_metadata&.dig(:profile) || store_entry["profile"],
+                            live_metadata ? live_metadata[:scopes] : store_entry["scopes"])
           end
 
         render(data, summary: summary)
@@ -231,25 +244,36 @@ module Wiq
             key: "personal_access_tokens"
           )
           match = rows.find { |r| r["token_prefix"] == prefix }
-          return { token_prefix: prefix, name: nil, last_used_at: nil, profile: nil } unless match
+          return { token_prefix: prefix, name: nil, last_used_at: nil, profile: nil, scopes: nil } unless match
 
           {
             token_prefix: match["token_prefix"],
             name: match["name"],
             last_used_at: match["last_used_at"],
-            profile: match["profile"]
+            profile: match["profile"],
+            # Servers predating per-token scopes omit the key; treat as read-only.
+            scopes: Array(match["scopes"])
           }
         end
 
-        def profile_summary(prefix, profile)
-          return "#{prefix}." unless profile
+        def profile_summary(prefix, profile, scopes = nil)
+          scope_note =
+            if scopes.nil?
+              nil
+            elsif scopes.empty?
+              "scopes: read-only"
+            else
+              "scopes: #{scopes.join(", ")}"
+            end
+          return [prefix, scope_note].compact.join("; ") + "." unless profile
 
           who = profile["display_name"]
           where = profile["team_name"]
           kind = profile["type"]
           tail = [who, where].compact.reject(&:empty?).join(" @ ")
           tail += " (#{kind})" if kind && !kind.empty?
-          tail.empty? ? "#{prefix}." : "#{prefix} — #{tail}."
+          head = tail.empty? ? prefix : "#{prefix} — #{tail}"
+          [head, scope_note].compact.join("; ") + "."
         end
       end
     end

data/lib/wiq/commands/doctor.rb

@@ -15,6 +15,9 @@ module Wiq
           6. Live reachability + auth probe via
              `GET /api/v1/personal_access_tokens`
           7. Bound profile (display_name, type, team) for the calling token
+          8. Write scopes on the token (empty = read-only; writes such as
+             `wiq prospects advance` need the matching capability enabled
+             by the team AND present on the token)
 
         Exits non-zero if any check fails. Agents should run this first
         when handed an unfamiliar shell to confirm they can actually call
@@ -59,6 +62,12 @@ module Wiq
               checks << check("Bound profile",
                               "#{profile["display_name"]} (#{profile["type"]}) @ #{profile["team_name"]}",
                               ok: !profile["display_name"].nil?)
+              scopes = Array(match["scopes"])
+              checks << check("Write scopes",
+                              scopes.empty? ? "none (read-only)" : scopes.join(", "),
+                              ok: true,
+                              hint: scopes.empty? ? "Reads only. Mint a token with prospects:write to use " \
+                                                    "prospect write commands." : nil)
             else
               checks << check("Reachability + auth", "200 OK", ok: true)
               checks << check("Bound profile", "(token not in own user's PAT list?)",

data/lib/wiq/commands/prospect_families.rb

@@ -4,6 +4,7 @@ module Wiq
   module Commands
     class ProspectFamilies < Base
       SORT_OPTIONS = %w[newest oldest_followup oldest_contact next_trial].freeze
+      ACTIVITY_TYPES = %w[phone_call sms email in_person other].freeze
 
       desc "list", "List prospect families (one row per household)"
       long_desc <<~DESC
@@ -124,6 +125,231 @@ module Wiq
           ]
         )
       end
+
+      desc "stage_changes FAMILY_ID", "Stage-transition audit log for every prospect in a family"
+      long_desc <<~DESC
+        Append-only history of every stage move for every prospect (kid)
+        in the family, newest first. Each row: prospect_id + child_name,
+        from_stage (null on the initial create), to_stage, changed_at,
+        changed_via, and changed_by (profile, or null for system moves).
+
+        changed_via values:
+          manual              A person moved it (drawer, note shortcut, or a
+                              PAT write — changed_by names the coach)
+          trial_registration  Family bought a trial session
+          check_in            Kid checked in to a trial practice
+          trial_expired       Trial passes ran out
+          paid_registration   Registered for a paid session (→ converted)
+          subscription        Started a recurring membership (→ converted)
+          backfill            Historical import
+          bulk_archive        The stale-lead archive task
+
+        Use this to answer "did this lead actually trial or skip straight
+        to converted?" — the prospect row only carries its CURRENT stage —
+        and to review what an agent or coach did before attempting another
+        `wiq prospects advance` (moves are forward-only via PAT).
+      DESC
+      method_option :all, type: :boolean, default: false
+      def stage_changes(family_id)
+        records, total = fetch_index("/api/v1/prospect_families/#{family_id}/stage_changes",
+                                     { "per_page" => 50 },
+                                     key: "stage_changes")
+        render_index(
+          records, total: total,
+          summary: "Listed #{records.size} stage changes for family #{family_id}.",
+          breadcrumbs: [
+            { "cmd" => "wiq prospect_families show #{family_id}", "description" => "Back to the family" },
+            { "cmd" => "wiq prospect_families notes #{family_id}", "description" => "Contact log alongside the stage history" }
+          ]
+        )
+      end
+
+      desc "linked_answers FAMILY_ID", "Registration answers on the member profiles linked to a family"
+      long_desc <<~DESC
+        Trial-purchase leads skip the interest form, so their phone number
+        and other intake details usually exist only as registration answers
+        on the profiles the family is linked to: the guardian (parent or
+        coach) and each prospect's wrestler_profile. This returns one entry
+        per linked profile (profile_id, profile_type, full_name, relation =
+        guardian | wrestler) with its registration_answers, deduped to the
+        most recent answer per question and ordered by the question's
+        display order.
+
+        Not paginated. Coach visibility is enforced server-side, so
+        admin-only questions are omitted for non-admin tokens. A family
+        with no linked profiles returns an empty list.
+
+        Cheaper first stop: `wiq prospect_families show` already surfaces
+        `phone_suggestions` for blank-phone families. Use this when you
+        need everything known about the household before a call.
+      DESC
+      def linked_answers(family_id)
+        data = client.get("/api/v1/prospect_families/#{family_id}/linked_answers")
+        profiles = Array(data["linked_profiles"])
+        answer_count = profiles.sum { |p| Array(p["registration_answers"]).size }
+        render_index(
+          profiles,
+          summary: "#{profiles.size} linked profiles with #{answer_count} visible registration answers for family #{family_id}.",
+          breadcrumbs: [
+            { "cmd" => "wiq prospect_families show #{family_id}", "description" => "Back to the family" },
+            { "cmd" => "wiq prospect_families update #{family_id} --phone <number>",
+              "description" => "Copy a found phone onto the family record" }
+          ]
+        )
+      end
+
+      desc "create", "Create a prospect family (household) [prospects:write]"
+      long_desc <<~DESC
+        POSTs to /api/v1/prospect_families. Requires a coach PAT minted
+        with the prospects:write scope on a team that has enabled it
+        (Settings → API Access). Only --first-name is required; --email
+        must be a valid address when given.
+
+        A family is the household record — add the kid(s) afterwards with
+        `wiq prospects create <family_id> --first-name ...`. Check for an
+        existing household first with `wiq prospect_families list --query
+        <name or email or phone>` to avoid duplicates.
+
+        --source is the machine-readable origin (e.g. web_form, walk_in,
+        referral); --hear-about-us is the family's free-text answer to
+        "How did you hear about us?". --assigned-coach takes a
+        coach_profile id. --guardian-id/--guardian-type link an existing
+        ParentProfile or CoachProfile as the guardian.
+      DESC
+      method_option :first_name, type: :string, required: true, desc: "contact_first_name (required)"
+      method_option :last_name, type: :string, desc: "contact_last_name"
+      method_option :email, type: :string, desc: "contact_email"
+      method_option :phone, type: :string, desc: "contact_phone"
+      method_option :hear_about_us, type: :string, desc: "Free-text 'How did you hear about us?'"
+      method_option :source, type: :string, desc: "Lead source tag (free text)"
+      method_option :assigned_coach, type: :numeric, desc: "assigned_coach_id (coach_profile id)"
+      method_option :guardian_id, type: :numeric, desc: "Existing profile id to link as guardian"
+      method_option :guardian_type, type: :string, enum: %w[ParentProfile CoachProfile],
+                                    desc: "Profile type for --guardian-id"
+      def create
+        family = client.post("/api/v1/prospect_families", { "prospect_family" => build_family_attrs })
+        render(family,
+               summary: "Created prospect family #{family["id"]} — #{family["contact_name"]}.",
+               breadcrumbs: [
+                 { "cmd" => "wiq prospects create #{family["id"]} --first-name <child>",
+                   "description" => "Add the kid(s) to this household" },
+                 { "cmd" => "wiq prospect_families note #{family["id"]} --activity-type phone_call --content \"...\"",
+                   "description" => "Log the first contact" }
+               ])
+      end
+
+      desc "update ID", "Edit a prospect family's contact info or assignment [prospects:write]"
+      long_desc <<~DESC
+        PATCHes /api/v1/prospect_families/:id with only the flags you
+        pass. Requires the prospects:write scope (team-enabled + on the
+        token). Typical uses: fill in a missing phone (see
+        `phone_suggestions` on `wiq prospect_families show`), reassign a
+        coach, or correct a misspelled name.
+      DESC
+      method_option :first_name, type: :string, desc: "contact_first_name"
+      method_option :last_name, type: :string, desc: "contact_last_name"
+      method_option :email, type: :string, desc: "contact_email"
+      method_option :phone, type: :string, desc: "contact_phone"
+      method_option :hear_about_us, type: :string, desc: "Free-text 'How did you hear about us?'"
+      method_option :source, type: :string, desc: "Lead source tag (free text)"
+      method_option :assigned_coach, type: :numeric, desc: "assigned_coach_id (coach_profile id)"
+      method_option :guardian_id, type: :numeric, desc: "Existing profile id to link as guardian"
+      method_option :guardian_type, type: :string, enum: %w[ParentProfile CoachProfile],
+                                    desc: "Profile type for --guardian-id"
+      def update(id)
+        attrs = build_family_attrs
+        if attrs.empty?
+          raise Wiq::Error.new("Nothing to update — pass at least one field flag.",
+                               code: "no_fields",
+                               hint: "See `wiq prospect_families update --help` for the editable fields.")
+        end
+
+        family = client.patch("/api/v1/prospect_families/#{id}", { "prospect_family" => attrs })
+        render(family,
+               summary: "Updated prospect family #{family["id"]} — #{family["contact_name"]}.",
+               breadcrumbs: [
+                 { "cmd" => "wiq prospect_families show #{family["id"]}", "description" => "Refetch the family" }
+               ])
+      end
+
+      desc "note FAMILY_ID", "Log a contact / add a note to a prospect family [prospects:write]"
+      long_desc <<~DESC
+        POSTs to /api/v1/prospect_families/:family_id/notes. Requires the
+        prospects:write scope (team-enabled + on the token). The note is
+        authored by the coach who minted the token.
+
+        --activity-type marks the note as a logged contact: the server
+        bumps last_contacted_at on every ACTIVE prospect in the family,
+        which is what clears "stale contact" follow-up flags. Omit it for
+        an internal note that shouldn't count as contact.
+
+        Side effects in the same call (prospect ids, comma-separated):
+          --clear-follow-up 12,34   Clear the needs_follow_up flag
+          --add-follow-up 56        Flag for follow-up (reason=manual)
+        Ids outside this family are ignored server-side.
+
+        Content is sent as plain text; @mentions are processed server-side.
+      DESC
+      method_option :content, type: :string, required: true, desc: "Note body (plain text)"
+      method_option :activity_type, type: :string, enum: ACTIVITY_TYPES,
+                                    desc: "phone_call | sms | email | in_person | other (omit for a plain note)"
+      method_option :clear_follow_up, type: :string,
+                                      desc: "Comma-separated prospect ids to un-flag for follow-up"
+      method_option :add_follow_up, type: :string,
+                                    desc: "Comma-separated prospect ids to flag for follow-up"
+      def note(family_id)
+        body = {
+          "note" => {
+            "content" => options[:content],
+            "plain_content" => options[:content]
+          }
+        }
+        body["note"]["activity_type"] = options[:activity_type] if options[:activity_type]
+        clear_ids = parse_id_list(options[:clear_follow_up])
+        add_ids = parse_id_list(options[:add_follow_up])
+        body["clear_follow_up_for"] = clear_ids unless clear_ids.empty?
+        body["add_follow_up_for"] = add_ids unless add_ids.empty?
+
+        note = client.post("/api/v1/prospect_families/#{family_id}/notes", body)
+        kind = options[:activity_type] ? "Logged #{options[:activity_type]} contact" : "Added note"
+        render(note,
+               summary: "#{kind} ##{note["id"]} on family #{family_id}.",
+               breadcrumbs: [
+                 { "cmd" => "wiq prospect_families notes #{family_id}", "description" => "Full contact log" },
+                 { "cmd" => "wiq prospect_families show #{family_id}", "description" => "Back to the family" }
+               ])
+      end
+
+      no_commands do
+        # Maps CLI flags → the `prospect_family` permit list on
+        # Api::V1::ProspectFamiliesController.
+        FAMILY_FIELD_MAP = {
+          first_name: "contact_first_name",
+          last_name: "contact_last_name",
+          email: "contact_email",
+          phone: "contact_phone",
+          hear_about_us: "hear_about_us",
+          source: "source",
+          assigned_coach: "assigned_coach_id",
+          guardian_id: "guardian_id",
+          guardian_type: "guardian_type"
+        }.freeze
+
+        def build_family_attrs
+          attrs = {}
+          FAMILY_FIELD_MAP.each do |flag, param|
+            value = options[flag]
+            attrs[param] = value unless value.nil?
+          end
+          attrs
+        end
+
+        def parse_id_list(raw)
+          return [] if raw.nil? || raw.to_s.strip.empty?
+
+          raw.to_s.split(",").map(&:strip).reject(&:empty?).map(&:to_i).reject(&:zero?)
+        end
+      end
     end
   end
 end

data/lib/wiq/commands/prospects.rb

@@ -4,8 +4,14 @@ module Wiq
   module Commands
     class Prospects < Base
       STAGES = %w[inquiry trial_scheduled trialing trial_complete converted didnt_join archived].freeze
+      TERMINAL_STAGES = %w[converted didnt_join archived].freeze
       ATTENTION_MODES = %w[needs_attention handled].freeze
 
+      # Write capability every create/update/advance below needs. The server
+      # checks it per request: the team must have it enabled AND the token
+      # must have been minted with it. See `wiq auth status` for scopes.
+      WRITE_CAPABILITY = "prospects:write"
+
       desc "list", "List individual prospects (one row per kid)"
       long_desc <<~DESC
         Returns one row per prospect (kid), sorted newest-first.
@@ -21,15 +27,6 @@ module Wiq
                                scope which unions both via a subquery.
                                When set, ALL other filters are bypassed
                                server-side.
-
-                               KNOWN BUG: `wiq prospects list --query …`
-                               currently returns HTTP 500 due to an
-                               ambiguous-column ORDER BY on the
-                               prospect↔prospect_family join. Workaround:
-                               use `wiq prospect_families list --query …`
-                               instead (same search scope, same matches,
-                               returns the family with its prospects
-                               nested inline).
           --attention          needs_attention | handled
           --stage              One funnel stage
           --assigned-to-me     Only families assigned to the calling coach
@@ -92,6 +89,138 @@ module Wiq
                ])
       end
 
+      desc "create FAMILY_ID", "Add a prospect (kid) to an existing prospect family [prospects:write]"
+      long_desc <<~DESC
+        POSTs to /api/v1/prospect_families/:family_id/prospects. Requires a
+        coach PAT minted with the prospects:write scope on a team that has
+        enabled it (Settings → API Access). Only --first-name is required.
+
+        New prospects start at stage `inquiry` unless --stage is given.
+        The stage audit row is attributed to the coach who minted the token.
+
+        Create the household first with `wiq prospect_families create` if
+        the family doesn't exist yet; use `wiq prospect_families list
+        --query <name>` to check.
+
+        Errors you may see:
+          capability_disabled_for_team   Team hasn't enabled prospects:write
+          token_missing_scope            Token wasn't minted with it — mint a new one
+          validation_failed              Server rejected a field (see details)
+      DESC
+      method_option :first_name, type: :string, required: true, desc: "child_first_name (required)"
+      method_option :last_name, type: :string, desc: "child_last_name"
+      method_option :dob, type: :string, desc: "child_date_of_birth (YYYY-MM-DD)"
+      method_option :academic_class, type: :string, desc: "child_academic_class (free text, e.g. 5th)"
+      method_option :experience_level, type: :string, desc: "experience_level (free text, e.g. none / 1 season)"
+      method_option :stage, type: :string, enum: STAGES, desc: "Initial stage (default: inquiry)"
+      method_option :paid_session, type: :numeric, desc: "paid_session_id of the trial session"
+      method_option :trial_event, type: :numeric, desc: "trial_event_id — the practice/event they'll try"
+      method_option :trial_scheduled_at, type: :string, desc: "ISO-8601 timestamp"
+      method_option :needs_follow_up, type: :boolean, desc: "Flag (or --no-needs-follow-up to clear) for follow-up"
+      def create(family_id)
+        body = { "prospect" => build_prospect_attrs }
+        prospect = client.post("/api/v1/prospect_families/#{family_id}/prospects", body)
+        render(prospect,
+               summary: "Created prospect #{prospect["id"]} — #{prospect["child_first_name"]} " \
+                        "#{prospect["child_last_name"]} (stage=#{prospect["stage"]}) on family #{family_id}.",
+               breadcrumbs: [
+                 { "cmd" => "wiq prospects show #{prospect["id"]}", "description" => "Refetch the prospect" },
+                 { "cmd" => "wiq prospect_families note #{family_id} --activity-type phone_call --content \"...\"",
+                   "description" => "Log the first contact" }
+               ])
+      end
+
+      desc "update ID", "Edit a prospect's details and/or move its stage [prospects:write]"
+      long_desc <<~DESC
+        PATCHes /api/v1/prospects/:id with only the flags you pass. Requires
+        the prospects:write scope (team-enabled + on the token).
+
+        Stage changes via a PAT are FORWARD-ONLY and cannot leave a terminal
+        stage (converted, didnt_join, archived). The server answers 422
+        (`stage_transition_refused`) rather than silently no-op'ing; a coach
+        can force the move in the web app. `wiq prospects advance` is the
+        same call with a clearer signature for stage-only moves.
+
+        --needs-follow-up / --no-needs-follow-up also syncs follow_up_set_at
+        and follow_up_reason (=manual) server-side so the flag stays
+        internally consistent.
+
+        Funnel timestamps (--trial-scheduled-at, --trial-completed-at,
+        --converted-at, --archived-at, --last-contacted-at) accept ISO-8601
+        and are normally stamped by the stage change itself — pass them
+        only to backfill history.
+      DESC
+      method_option :first_name, type: :string, desc: "child_first_name"
+      method_option :last_name, type: :string, desc: "child_last_name"
+      method_option :dob, type: :string, desc: "child_date_of_birth (YYYY-MM-DD)"
+      method_option :academic_class, type: :string, desc: "child_academic_class"
+      method_option :experience_level, type: :string, desc: "experience_level"
+      method_option :stage, type: :string, enum: STAGES, desc: "Move to this stage (forward-only via PAT)"
+      method_option :lost_reason, type: :string, desc: "Why they didn't join (pairs with --stage didnt_join)"
+      method_option :paid_session, type: :numeric, desc: "paid_session_id of the trial session"
+      method_option :trial_event, type: :numeric, desc: "trial_event_id"
+      method_option :wrestler_profile, type: :numeric, desc: "wrestler_profile_id to link (on conversion)"
+      method_option :needs_follow_up, type: :boolean, desc: "Flag (or --no-needs-follow-up to clear) for follow-up"
+      method_option :trial_scheduled_at, type: :string, desc: "ISO-8601 timestamp"
+      method_option :trial_completed_at, type: :string, desc: "ISO-8601 timestamp"
+      method_option :converted_at, type: :string, desc: "ISO-8601 timestamp"
+      method_option :archived_at, type: :string, desc: "ISO-8601 timestamp"
+      method_option :last_contacted_at, type: :string, desc: "ISO-8601 timestamp"
+      def update(id)
+        attrs = build_prospect_attrs
+        if attrs.empty?
+          raise Wiq::Error.new("Nothing to update — pass at least one field flag.",
+                               code: "no_fields",
+                               hint: "See `wiq prospects update --help` for the editable fields.")
+        end
+
+        prospect = client.patch("/api/v1/prospects/#{id}", { "prospect" => attrs })
+        render(prospect,
+               summary: "Updated prospect #{prospect["id"]} — #{prospect["child_first_name"]} " \
+                        "#{prospect["child_last_name"]} (stage=#{prospect["stage"]}).",
+               breadcrumbs: [
+                 { "cmd" => "wiq prospects show #{prospect["id"]}", "description" => "Refetch the prospect" },
+                 { "cmd" => "wiq prospect_families show #{prospect["prospect_family_id"]}",
+                   "description" => "Family this prospect belongs to" }
+               ])
+      end
+
+      desc "advance ID STAGE", "Move a prospect forward to STAGE [prospects:write]"
+      long_desc <<~DESC
+        Shorthand for `wiq prospects update ID --stage STAGE`. Stage order:
+
+          inquiry → trial_scheduled → trialing → trial_complete
+                  → converted | didnt_join | archived   (terminal)
+
+        Via a personal access token the move must go FORWARD in that order
+        and cannot start from a terminal stage. Skipping ahead is fine
+        (inquiry → converted). Anything else returns 422 with code
+        `stage_transition_refused`; a coach can override in the web app.
+
+        --lost-reason is stored alongside a move to didnt_join.
+      DESC
+      method_option :lost_reason, type: :string, desc: "Why they didn't join (with didnt_join)"
+      def advance(id, stage)
+        unless STAGES.include?(stage)
+          raise Wiq::Error.new("Unknown stage #{stage.inspect}.",
+                               code: "invalid_stage",
+                               hint: "Valid stages: #{STAGES.join(", ")}")
+        end
+
+        attrs = { "stage" => stage }
+        attrs["lost_reason"] = options[:lost_reason] if options[:lost_reason]
+        prospect = client.patch("/api/v1/prospects/#{id}", { "prospect" => attrs })
+        render(prospect,
+               summary: "Prospect #{prospect["id"]} — #{prospect["child_first_name"]} " \
+                        "#{prospect["child_last_name"]} is now #{prospect["stage"]}.",
+               breadcrumbs: [
+                 { "cmd" => "wiq prospect_families note #{prospect["prospect_family_id"]} " \
+                            "--activity-type other --content \"...\"",
+                   "description" => "Log why, so the contact history matches the stage" },
+                 { "cmd" => "wiq prospects show #{prospect["id"]}", "description" => "Refetch the prospect" }
+               ])
+      end
+
       desc "summary", "Pipeline dashboard: counts per stage + conversion rate"
       long_desc <<~DESC
         Single-call dashboard. Returns an unwrapped object (not paginated)
@@ -147,6 +276,40 @@ module Wiq
             { "cmd" => "wiq prospect_families list", "description" => "List by family instead of by kid" }
           ]
         end
+
+        # Maps CLI flags → the `prospect` param permit list on
+        # Api::V1::ProspectsController. Only flags actually passed land in
+        # the body so PATCH stays a partial update.
+        FIELD_MAP = {
+          first_name: "child_first_name",
+          last_name: "child_last_name",
+          dob: "child_date_of_birth",
+          academic_class: "child_academic_class",
+          experience_level: "experience_level",
+          stage: "stage",
+          lost_reason: "lost_reason",
+          paid_session: "paid_session_id",
+          trial_event: "trial_event_id",
+          wrestler_profile: "wrestler_profile_id",
+          trial_scheduled_at: "trial_scheduled_at",
+          trial_completed_at: "trial_completed_at",
+          converted_at: "converted_at",
+          archived_at: "archived_at",
+          last_contacted_at: "last_contacted_at"
+        }.freeze
+
+        def build_prospect_attrs
+          attrs = {}
+          FIELD_MAP.each do |flag, param|
+            value = options[flag]
+            attrs[param] = value unless value.nil?
+          end
+          # Boolean: Thor sets nil when the flag isn't passed, true/false otherwise.
+          unless options[:needs_follow_up].nil?
+            attrs["needs_follow_up"] = options[:needs_follow_up]
+          end
+          attrs
+        end
       end
     end
   end

data/lib/wiq/commands/reports.rb

@@ -234,9 +234,29 @@ module Wiq
         "SessionRegistrationAnswerReport" => {
           args: %w[paid_session_id],
           dates: :optional,
-          desc: "Full Q&A export of info submitted by parents at signup",
+          desc: "Full Q&A export of info submitted by parents at signup, one row per wrestler " \
+                "with stable ids + registration status",
           recommended: true,
-          notes: "Pass --paid-session <id> — required."
+          notes: "Pass --paid-session <id> — required. The default (vrow) row shape " \
+                 "leads with seven registration columns: \"WIQ ID #\" (wrestler_profile " \
+                 "id — same header/value as RosterReport column A, so the two reports " \
+                 "join on it), \"Registration ID\" (the stable key for external syncs), " \
+                 "\"Registration status\" (paid | partially_paid | pending | overdue | " \
+                 "canceled | awaiting_approval), \"Good standing\" (true/false: status in " \
+                 "paid/partially_paid/pending), \"Registered at\", \"Registration updated " \
+                 "at\", \"Registration canceled at\" (timestamps in the team's zone; blank " \
+                 "unless canceled). Then Last/First name, Email, Account type, Academic " \
+                 "class, Weight class, DOB, Age, created-at, USAW/AAU membership columns " \
+                 "(unless disabled for the team), each wrestler registration question, " \
+                 "and per-guardian name/email/type + guardian questions. One row per " \
+                 "wrestler: when a wrestler has several registrations for the session " \
+                 "(canceled then re-registered) the latest non-canceled one is " \
+                 "reported, else the latest canceled one; blank registration columns " \
+                 "mean no registration row exists. Anonymous sessions emit only " \
+                 "Last name / First name / Email. --v1 returns structured JSON " \
+                 "(wrestler_profiles + questions + answers) without the " \
+                 "registration columns.",
+          example: "wiq reports run SessionRegistrationAnswerReport --paid-session 42"
         },
         "PaidSessionAccountingReport" => {
           args: %w[paid_session_id],

data/lib/wiq/commands/rosters.rb

@@ -5,7 +5,9 @@ module Wiq
     class Rosters < Base
       desc "list", "List rosters"
       long_desc <<~DESC
-        Returns every roster on the calling profile's team, paginated.
+        Returns the team's active rosters by default, paginated. Archived
+        rosters are hidden unless you pass --include-archived (returns both)
+        or --archived true (returns only archived).
 
         Season filtering is a CLI-side projection (WIQ has no first-class
         Season entity):
@@ -31,9 +33,12 @@ module Wiq
       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 :include_archived, type: :boolean, default: false,
+                                       desc: "Include archived rosters alongside active ones"
       method_option :all, type: :boolean, default: false
       def list
         params = { "per_page" => 100 }
+        params["include_archived"] = true if options[:include_archived]
         unless options[:archived].nil?
           params["q[archived_eq]"] = options[:archived]
         end

data/lib/wiq/commands/setup.rb

@@ -23,8 +23,9 @@ module Wiq
         restart needed. Re-run with --force to overwrite an existing
         install (useful when upgrading the gem).
 
-        The skill is read-only on the WIQ side: it teaches Claude how to
-        drive `wiq`, but doesn't touch any WIQ data.
+        Installing the skill doesn't touch any WIQ data: it only teaches
+        Claude how to drive `wiq`. What Claude can then change is bounded
+        by the token's write scopes (see `wiq auth status`).
       DESC
       method_option :project, type: :boolean, default: false,
                               desc: "Install per-project (./.claude/skills/) instead of user-global"

data/lib/wiq/credentials.rb

@@ -10,7 +10,8 @@ module Wiq
   #   {
   #     "<host>": {
   #       "<alias>": { "token": "...", "token_prefix": "...", "name": "...",
-  #                    "profile": {...}, "stored_at": "..." },
+  #                    "profile": {...}, "scopes": ["prospects:write"],
+  #                    "stored_at": "..." },
   #       "<alias>": { ... }
   #     }
   #   }
@@ -55,13 +56,14 @@ module Wiq
             "token_prefix" => entry["token_prefix"],
             "name" => entry["name"],
             "profile" => entry["profile"],
+            "scopes" => entry["scopes"],
             "stored_at" => entry["stored_at"]
           }
         end
       end
     end
 
-    def store(host:, alias_name:, token:, token_prefix: nil, name: nil, profile: nil)
+    def store(host:, alias_name:, token:, token_prefix: nil, name: nil, profile: nil, scopes: nil)
       data = load_all
       data[host] ||= {}
       data[host][alias_name] = {
@@ -69,6 +71,7 @@ module Wiq
         "token_prefix" => token_prefix,
         "name" => name,
         "profile" => profile,
+        "scopes" => scopes,
         "stored_at" => Time.now.utc.iso8601
       }.compact
       write(data)

data/lib/wiq/errors.rb

@@ -76,13 +76,28 @@ module Wiq
   end
 
   # Mirror of the HTTP error envelope from /api/v1.
+  #
+  # PAT write policy (Api::V1::BaseController#enforce_pat_restrictions):
+  # a write goes through only when it maps to a capability in the server's
+  # ApiCapability registry that the team has enabled AND the token carries.
+  # The server emits three distinct 403 bodies for the three failure modes,
+  # naming the capability verbatim; we key off that wording to give each
+  # its own `code` + fix-it hint. Keep the regexes in sync with
+  # `pat_denial_message` in the Rails app.
   class APIError < Error
-    attr_reader :status, :response_body, :request_id
+    attr_reader :status, :response_body, :request_id, :capability
+
+    PAT_NOT_WRITABLE = /not writable with a personal access token/i
+    PAT_TEAM_DISABLED = /team has not enabled (\S+) for API access/i
+    PAT_TOKEN_MISSING_SCOPE = /token lacks the (\S+) scope/i
+    PAT_LEGACY_READ_ONLY = /personal access tokens are read-only/i
+    PAT_STAGE_REFUSED = /stage cannot move from (\S+) to (\S+) with a personal access token/i
 
     def initialize(status:, body:, request_id: nil)
       @status = status
       @response_body = body
       @request_id = request_id
+      @capability = nil
 
       code, message, hint = derive(status, body)
       super(message, code: code, hint: hint, exit_code: 1, details: body)
@@ -97,12 +112,11 @@ module Wiq
         ["unauthorized", "Token rejected by server (401).",
          "Run `wiq auth status` to inspect the active token; `wiq auth login` to replace it."]
       when 403
-        ["forbidden", "Server denied access (403): #{msgs}",
-         "PATs inherit the user's permissions. Confirm the minting user can see this resource in the web app."]
+        derive_forbidden(msgs)
       when 404
         ["not_found", "Resource not found (404).", nil]
       when 422
-        ["validation_failed", "Validation error (422): #{msgs}", nil]
+        derive_unprocessable(msgs)
       when 429
         ["rate_limited", "Rate limited (429): #{msgs}",
          "WIQ enforces 100 req/3s per IP. Back off and retry."]
@@ -111,6 +125,38 @@ module Wiq
       end
     end
 
+    def derive_forbidden(msgs)
+      if msgs =~ PAT_NOT_WRITABLE || msgs =~ PAT_LEGACY_READ_ONLY
+        ["pat_write_unsupported", "Server denied access (403): #{msgs}",
+         "This endpoint has no API write capability, so no personal access token can call it. " \
+         "Make the change in the WIQ web app."]
+      elsif (m = msgs.match(PAT_TEAM_DISABLED))
+        @capability = m[1]
+        ["capability_disabled_for_team", "Server denied access (403): #{msgs}",
+         "A team admin must enable #{@capability} under Settings → API Access " \
+         "(<host>/settings/team/api_access). Existing tokens minted with that scope start working immediately."]
+      elsif (m = msgs.match(PAT_TOKEN_MISSING_SCOPE))
+        @capability = m[1]
+        ["token_missing_scope", "Server denied access (403): #{msgs}",
+         "Token scopes are immutable. Mint a new token that includes #{@capability} at " \
+         "<host>/settings/personal_access_tokens, then `wiq auth login --force` to replace the stored one. " \
+         "Run `wiq auth status` to see the scopes on the current token."]
+      else
+        ["forbidden", "Server denied access (403): #{msgs}",
+         "PATs inherit the user's permissions. Confirm the minting user can see this resource in the web app."]
+      end
+    end
+
+    def derive_unprocessable(msgs)
+      if msgs =~ PAT_STAGE_REFUSED
+        ["stage_transition_refused", "Validation error (422): #{msgs}",
+         "Stage changes via a personal access token are forward-only and cannot leave a terminal stage " \
+         "(converted, didnt_join, archived). A coach can force the move in the WIQ web app."]
+      else
+        ["validation_failed", "Validation error (422): #{msgs}", nil]
+      end
+    end
+
     # /api/v1 always returns { "errors": <array|hash> }. Flatten to a human string.
     def extract_messages(body)
       return body.to_s unless body.is_a?(Hash)

data/lib/wiq/version.rb

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

data/share/skills/wiq/SKILL.md

@@ -1,14 +1,16 @@
 ---
 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, payouts/bank deposits, 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.
+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, payouts/bank deposits, reports, USAW/AAU memberships, fundraising, online store orders, or per-location/site breakdowns for multi-gym clubs. The `wiq` CLI reads /api/v1 via personal access tokens and, when the token carries the prospects:write scope, can also create/edit leads, log contact notes, and advance prospects through the pipeline. 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
 
-`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.
+`wiq` is a 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). Every token can read; a token additionally minted with a
+write scope (see "Writes" below) can create and edit leads. 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)
 
@@ -49,9 +51,17 @@ per situation.
   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).
+  wrestler PATs cannot run reports or touch prospects (Pundit requires a
+  CoachProfile on the team).
+- **Writes need a capability on BOTH the team and the token.** Reads are
+  implicit for every token. A write (`POST`/`PATCH`) succeeds only when it
+  maps to a capability in the server's registry (`prospects:write`,
+  `reports:write`) that a team admin has enabled under Settings → API
+  Access AND that the token was minted with. Token scopes are immutable:
+  to add one, revoke + mint a new token, then `wiq auth login --force`.
+  `wiq auth status` / `wiq doctor` show the live scopes — check them
+  before attempting a write. `reports:write` was backfilled onto every
+  existing team and token, so report submission keeps working.
 - **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.
@@ -106,8 +116,12 @@ Common codes and the right response:
 | `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` |
+| `capability_disabled_for_team` (403) | Team hasn't enabled the write capability named in the message | Ask a team admin to enable it at `<host>/settings/team/api_access`; nothing to change on the token |
+| `token_missing_scope` (403) | Team allows the write, but this token was minted without the scope | Mint a new token WITH the scope, `wiq auth login --force`; scopes can't be edited in place |
+| `pat_write_unsupported` (403) | Endpoint has no API write capability at all | Use the WIQ web app; not a permissions problem |
 | `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 |
+| `stage_transition_refused` (422) | PAT tried to move a prospect backwards or out of a terminal stage | Don't retry; tell the user a coach must make that move in the web app |
 | `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) |
@@ -181,6 +195,14 @@ Key reports an agent should know by heart:
   while?"
 - **`PaidSessionAccountingReport`** (admin_only) — Line-item charges for
   a paid session.
+- **`SessionRegistrationAnswerReport`** — Signup Q&A for one
+  `--paid-session <id>`, one row per wrestler. Rows lead with **"WIQ ID
+  #"** (wrestler_profile id, identical to RosterReport's first column, so
+  the two join on it), **"Registration ID"** (the stable key to hand an
+  external sync), "Registration status", "Good standing", "Registered
+  at", "Registration updated at", "Registration canceled at" — then the
+  name/DOB/USAW/AAU columns and every registration question. Use this,
+  not name+DOB matching, when a customer syncs registrations elsewhere.
 
 For anything else, `wiq reports types` is faster than guessing.
 
@@ -426,20 +448,66 @@ Three gotchas an agent must know:
    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)
+## Writes — the prospects pipeline (`prospects:write`)
 
-The CLI is read-only by design except for report submission. You
-cannot via this CLI:
+The only writable surface besides report submission is the leads
+pipeline. Six commands, all requiring the `prospects:write` scope:
 
-- Create/edit prospects, families, notes, check-ins, events, paid
-  sessions, rosters, locations, or any other resource
+```bash
+wiq prospect_families create --first-name Dana --last-name Lee --email dana@x.com --phone 5551234
+wiq prospect_families update <family_id> --phone 5551234 --assigned-coach <coach_id>
+wiq prospect_families note <family_id> --activity-type phone_call --content "Left voicemail" \
+    [--clear-follow-up <prospect_ids>] [--add-follow-up <prospect_ids>]
+wiq prospects create <family_id> --first-name Sam --dob 2016-03-04 --academic-class 4th
+wiq prospects update <prospect_id> --stage trial_scheduled --trial-event <event_id>
+wiq prospects advance <prospect_id> trialing
+```
+
+Rules the server enforces on PAT callers (and you should respect up
+front rather than discover via errors):
+
+1. **Check scopes first.** `wiq auth status` → `live_scopes` must include
+   `prospects:write`. If it doesn't, stop and tell the user: either the
+   team admin needs to enable it (Settings → API Access) or they need a
+   new token minted with it. Don't loop on 403s.
+2. **Stage moves are forward-only and never leave a terminal stage.**
+   Order: inquiry → trial_scheduled → trialing → trial_complete →
+   converted | didnt_join | archived. Skipping ahead is fine; going back
+   or moving a converted/archived lead returns `stage_transition_refused`
+   (422). A coach can force it in the web app. Deletes are never allowed
+   through the API.
+3. **Search before you create.** `wiq prospect_families list --query
+   <name|email|phone>` finds existing households so you don't duplicate
+   a family that came in through the web interest form.
+4. **Log contact when you act.** A note WITH `--activity-type` counts as
+   contact: it stamps `last_contacted_at` on every active prospect in
+   the family and is what clears stale-contact follow-up flags. A note
+   without it is an internal comment only.
+5. **Attribution.** Every write is audited against the token; stage
+   changes and notes are attributed to the coach who minted it.
+   `wiq prospect_families stage_changes <family_id>` is the audit log
+   (from/to stage, changed_at, changed_via, changed_by) — use it to
+   answer "who moved this lead?" and to check history before advancing.
+6. **Trial-purchase leads have thin family records.** They skipped the
+   interest form, so contact details often live only as registration
+   answers on the linked wrestler/guardian profiles. `wiq
+   prospect_families linked_answers <family_id>` returns them; copy a
+   phone back with `wiq prospect_families update --phone`.
+
+## What's NOT available
+
+You cannot via this CLI:
+
+- Create/edit check-ins, events, paid sessions, rosters, locations, or
+  any resource other than prospects/families/notes and reports
+- Delete anything (destroy actions are outside every capability)
 - 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
+- Mark attendance or trigger event-change notifications / 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.
+If the user asks for one of these, say it's not exposed and point them
+at the WIQ web UI.
 
 ## When to compose vs run a workflow
 

metadata

@@ -1,14 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: wiq-cli
 version: !ruby/object:Gem::Version
-  version: 0.5.0
+  version: 0.6.1
 platform: ruby
 authors:
 - WrestlingIQ
-autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-08-19 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: thor
@@ -122,7 +121,6 @@ metadata:
   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
@@ -137,8 +135,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.3.27
-signing_key:
+rubygems_version: 4.0.16
 specification_version: 4
 summary: Command-line interface for the WrestlingIQ API
 test_files: []