wiq-cli 0.4.0 → 0.6.1

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.4.0"
+  VERSION = "0.6.1"
 end

data/lib/wiq.rb

@@ -29,4 +29,5 @@ require "wiq/commands/wrestlers"
 require "wiq/commands/parents"
 require "wiq/commands/charges"
 require "wiq/commands/billing_profiles"
+require "wiq/commands/payouts"
 require "wiq/cli"