wxcli 1.2.0__py3-none-any.whl

wxcli/_playbook/.claude/skills/provision-calling/SKILL.md

@@ -0,0 +1,421 @@
+---
+name: provision-calling
+description: |
+  Provision Webex Calling users, locations, and licenses via the wxcli CLI.
+  Also covers People API profile updates (alternate phone numbers, display name,
+  phoneNumbers array including alternate1/alternate2), number inventory management,
+  and bulk CSV import. Guides through auth verification, prerequisite checks,
+  deployment planning, execution, and result verification for any provisioning operation.
+  Use for: create, enable, assign, bulk provision, update user profile fields.
+  For teardown/delete/cleanup operations, use the teardown skill instead.
+allowed-tools: Read, Grep, Glob, Bash
+argument-hint: [operation — e.g. "create location", "enable user", "assign license", "bulk provision"]
+---
+
+<!-- Updated by playbook session 2026-03-18 -->
+
+# Provision Calling Workflow
+
+**Checkpoint — do NOT proceed until you can answer these:**
+1. Can `location_id` be changed after a calling license is assigned? (Answer: No — it is write-once. Wrong location = must remove and re-add calling license.)
+2. What case must `announcement_language` use? (Answer: lowercase only — `en_us` not `en_US`. Mixed case causes "Invalid Language Code" error.)
+
+If you cannot answer both, you skipped reading this skill. Go back and read it.
+
+## Step 1: Load references
+
+1. Read `docs/reference/provisioning.md` for People, Licenses, and Locations API patterns
+
+**Mandatory --help verification:** Before constructing any wxcli command, run `wxcli <group> --help` to verify the subcommand exists, then `wxcli <group> <subcommand> --help` to verify the exact flags. Do NOT rely on examples in this skill or reference docs — the CLI is auto-generated and flag names may differ from what documentation suggests.
+
+## Step 2: Verify auth token is working
+
+Before any provisioning operation, confirm the token is valid and has admin scopes.
+
+```bash
+wxcli whoami
+```
+
+If this fails with 401/403, stop and troubleshoot auth before proceeding. Common causes:
+- Token expired (personal access tokens last 12 hours)
+- Token not configured — run `wxcli configure` or check `~/.wxcli/config.json`
+- Token lacks admin scopes (`spark-admin:people_write`, `spark-admin:licenses_read`, etc.)
+
+## Step 3: Determine the operation
+
+Ask the user which provisioning operation they need. The six supported operations are:
+
+| Operation | What It Does | Prerequisites |
+|-----------|-------------|---------------|
+| **Create location** | Add a new physical location | Admin token with `spark-admin:locations_write` |
+| **Enable location for calling** | Turn on Webex Calling for an existing location | Location must exist; `spark-admin:telephony_config_write` |
+| **Create user** | Add a new person to the org | Admin token with `spark-admin:people_write` |
+| **Enable user for calling** | Assign calling license + location + extension to existing user | Location must exist; calling license available |
+| **Assign/change licenses** | Add or remove licenses on a user | License with available capacity |
+| **Bulk provision** | Provision multiple users in one run | All of the above |
+
+Confirm with the user before proceeding:
+- **Which operation** from the table above
+- **Target details** (location name/address, user email, license type, etc.)
+- **For bulk**: CSV or list of users to provision
+
+## Step 4: Check prerequisites
+
+Run these checks based on the operation. **Stop and report** if any prerequisite fails.
+
+### For location creation:
+```bash
+# Check if location name already exists
+wxcli locations list --name "target name"
+# Look for a match in the output. If the target name appears:
+wxcli locations show LOCATION_ID
+# Ask user: update existing or abort?
+```
+
+### For user provisioning:
+```bash
+# 1. Verify location exists and is calling-enabled
+wxcli location-settings list-1
+# Confirm target location appears (only calling-enabled locations are returned)
+
+# 2. Find an available calling license with capacity
+wxcli licenses list
+# Look for "Webex Calling - Professional" with consumed < total
+
+# 3. Check if user already exists
+wxcli users list --email target@example.com --output json
+# If user exists, check if already calling-enabled:
+wxcli users show PERSON_ID --output json
+# If location_id is set, user is already calling-enabled.
+# Ask user: update or abort?
+
+# 4. Verify email domain is provisioned in this org
+# No CLI command lists currently-claimed org domains — the `domains` group only
+# supports get-domain-verification / verify-domain / claim-domain / unverify-domain /
+# unclaim-domain (see manage-identity skill for the verification flow). If domain
+# status is unknown, check Control Hub, or attempt user creation and watch for a
+# domain authorization error; resolve via manage-identity's domain verification
+# flow before retrying.
+```
+
+### For phone number assignment:
+```bash
+# Verify number is in location inventory before assigning to a user
+# Numbers must be added to location first via numbers-manage commands
+wxcli numbers create LOCATION_ID --json-body '{"phoneNumbers": ["+15551234567"], "numberType": "DID"}'
+```
+
+## Step 5: Build deployment plan — [SHOW BEFORE EXECUTING]
+
+**Present the plan to the user and wait for approval.** Never execute without confirmation.
+
+Format the plan as:
+
+```
+=== Provisioning Plan ===
+
+Operation: [Create Location / Enable User / etc.]
+
+Target:
+  - [specific details]
+
+Steps:
+  1. [First CLI command — what it does]
+  2. [Second CLI command — what it does]
+  3. Verify: [what we'll check after]
+
+Prerequisites verified:
+  ✓ Auth token valid (authenticated as [name])
+  ✓ Location exists: [name] ([id])
+  ✓ License available: [name] ([consumed]/[total])
+  ✓ [any other checks]
+
+Proceed? [wait for user confirmation]
+```
+
+## Step 6: Execute the provisioning operation
+
+### Operation A: Create a Location
+
+Required flags: `--name`, `--time-zone`, `--preferred-language`, `--announcement-language`. Address must go in `--json-body`.
+
+```bash
+wxcli locations create \
+  --name "San Jose Office" \
+  --time-zone "America/Los_Angeles" \
+  --preferred-language en_US \
+  --announcement-language en_us \
+  --json-body '{"address": {"address1": "123 Main St", "city": "San Jose", "state": "CA", "postalCode": "95113", "country": "US"}}'
+```
+
+### Operation B: Enable Location for Calling
+
+Creating a location does NOT automatically enable calling. Separate command required.
+
+First, fetch the location details you'll need:
+```bash
+wxcli locations show LOCATION_ID
+```
+
+Then enable calling using those details:
+```bash
+wxcli location-settings create \
+  --id LOCATION_ID \
+  --name "San Jose Office" \
+  --time-zone "America/Los_Angeles" \
+  --preferred-language en_US \
+  --announcement-language en_us
+```
+
+**Important:** `announcement_language` must be lowercase (`en_us` not `en_US`) or the API rejects with "Invalid Language Code".
+
+**Warning:** Do not promise an API-based "disable calling" step during teardown. Use CLI/API to clear visible blockers first, but final delete of a calling-enabled location may still require Control Hub if the backend continues to hold the telephony reference.
+
+### Operation C: Create a New User
+
+**Before creating:** confirm the user's `firstName`, `lastName`, and `displayName` with the requester. Do not use email-derived placeholders (e.g., `jsmith`/`example`) — they produce incorrect directory entries and cannot be changed without a separate update call.
+
+```bash
+wxcli users create \
+  --json-body '{"emails":["jsmith@example.com"],"firstName":"John","lastName":"Smith","displayName":"John Smith"}'
+```
+
+**Gotcha:** A POST that returns 400 may **still have created the person**. Always check with a GET before retrying:
+```bash
+wxcli users list --email jsmith@example.com --output json
+```
+
+### Operation D: Enable Existing User for Calling
+
+Assign a calling license, location, and extension to an existing user.
+
+```bash
+# Look up current user state
+wxcli users show PERSON_ID --output json
+
+# Look up the calling license ID
+wxcli licenses list --output json
+# Find the license where name contains "Calling - Professional"
+
+# Assign the calling license with location and extension
+wxcli licenses update --person-id PERSON_ID --json-body '{
+  "email": "jsmith@example.com",
+  "licenses": [{
+    "id": "CALLING_LICENSE_ID",
+    "properties": {
+      "locationId": "LOCATION_ID",
+      "extension": "1001"
+    }
+  }]
+}'
+```
+
+**Key constraints:**
+- `location_id` is **write-once** — can only be set on initial calling license assignment, cannot be changed after
+- `extension` value must NOT include the location routing prefix
+- Either `phone_number` or `extension` is mandatory for calling licenses
+- To move a user, remove calling license and re-add with new location
+
+### Operation E: Bulk Provision
+
+**Before running:** confirm `firstName`, `lastName`, and `displayName` for each user with the requester. Do not derive names from email aliases.
+
+For small batches (< 20 users), pair each create with an immediate license assignment in a single loop:
+
+```bash
+LOCATION_ID="<location_id>"
+LICENSE_ID="<calling_license_id>"
+EXT=1001
+
+for email in user1@example.com user2@example.com user3@example.com; do
+  echo "=== Provisioning $email ==="
+
+  # Step 1: Create the user — capture the returned person ID
+  PERSON_ID=$(wxcli people create -o json \
+    --json-body "{\"emails\":[\"$email\"],\"firstName\":\"First\",\"lastName\":\"Last\",\"displayName\":\"First Last\"}" \
+    | python3 -c "import sys,json; print(json.load(sys.stdin)['id'])")
+  echo "Created: $email → $PERSON_ID"
+
+  # Step 2: Assign calling license with location and extension
+  wxcli licenses update --person-id "$PERSON_ID" --json-body "{
+    \"email\": \"$email\",
+    \"licenses\": [{
+      \"id\": \"$LICENSE_ID\",
+      \"operation\": \"add\",
+      \"properties\": {
+        \"locationId\": \"$LOCATION_ID\",
+        \"extension\": \"$EXT\"
+      }
+    }]
+  }"
+  echo "Enabled for calling: ext $EXT"
+
+  EXT=$((EXT + 1))
+done
+```
+
+**Note:** If `people create` returns 400, the user may still have been created. Check with `wxcli people list --email <email>` before retrying. If the user exists, skip the create and run only the `licenses update` step with the existing person ID.
+
+> **Bulk operations (50+ users):** Shell loops with `sleep 1` work for small batches. For large batches, use the migration engine's async pattern, which handles concurrency, rate limiting, and retry automatically.
+
+### Operation F: Teardown / Delete Location
+
+**For teardown operations, load the `teardown` skill.** It covers single-location teardown, multi-location bulk cleanup, and org reset with the full dependency-safe deletion order and `wxcli cleanup` automation.
+
+Delete-related critical rules (13-15) below still apply.
+
+## Step 7: Verify results
+
+Always read back the created/updated resources to confirm.
+
+### Verify a user:
+```bash
+wxcli users show PERSON_ID --output json
+# Confirm: location_id is set, calling license appears in licenses list, extension is correct
+```
+
+### Verify a location:
+```bash
+wxcli locations show LOCATION_ID --output json
+# Confirm: name, address, timezone are correct
+```
+
+### Verify bulk:
+```bash
+# List all users at a location
+wxcli users list --location-id LOCATION_ID --output json
+# Count results to confirm expected number of users provisioned
+```
+
+## Step 8: Report results
+
+Summarize what was done:
+
+```
+=== Provisioning Complete ===
+
+Operation: [what was done]
+Results:
+  - [resource]: [status] ([id])
+  - [resource]: [status] ([id])
+
+Verification:
+  ✓ [what was confirmed]
+
+Next steps:
+  - [any follow-up actions needed]
+```
+
+---
+
+## Critical Rules
+
+1. **ALWAYS test auth first** — Run `wxcli whoami` before any provisioning call. Do not proceed on auth failure.
+
+2. **ALWAYS show plan before executing** — Present the deployment plan and wait for user confirmation. Never provision without approval.
+
+3. **`location_id` is write-once** — Can only be set when first assigning a calling license. Cannot be changed after. To move a user, remove calling license and re-add with new location.
+
+4. **`announcement_language` must be lowercase** — `en_us` not `en_US`. The telephony `enable_for_calling` API rejects mixed case with "Invalid Language Code".
+
+5. **`announcement_language` returns None from details** — Always set it explicitly before calling `enable_for_calling`, even if it was set during creation.
+
+6. **Do not promise API disable-calling on locations** — the older `wxcli location-settings update-location-calling ...` guidance is stale in this repo. For teardown, use CLI/API to remove visible blockers, run `wxcli location-settings safe-delete-check LOCATION_ID`, retry delete, and warn that final removal of a calling-enabled location may still require Control Hub.
+
+7. **Phone numbers must be in location inventory first** — Before assigning a DID to a user, add it via `wxcli numbers create LOCATION_ID`.
+
+8. **POST/PUT may partially succeed** — A 400 response on user create/update may have still created/modified the resource. Always verify with a subsequent GET before retrying.
+
+9. **License IDs are org-specific base64 strings** — Never hardcode them. Always retrieve via `wxcli licenses list`.
+
+10. **Extension values must NOT include the routing prefix** — Set extension to `1001`. The work_extension in the response will include the prefix (e.g., `8001001`), but when writing, omit it. To check for extension conflicts before assigning, run `wxcli numbers list --location-id LOCATION_ID` and scan the extension column.
+
+11. **Log all operations** — Print what you're about to do before each CLI command, and print the result after. This creates an audit trail for troubleshooting.
+
+12. **For bulk operations (50+ users), use the migration engine's async pattern** — wxcli runs one command at a time. For large batches, the proven async pattern handles concurrency, rate limiting, and retry. For smaller batches (<50), shell loops with `sleep 1` suffice.
+
+13. **Location-scoped feature deletes require LOCATION_ID as FIRST argument** — `wxcli hunt-group delete --force LOCATION_ID HG_ID`, not `wxcli hunt-group delete --force HG_ID`. The LOCATION_ID comes before the feature ID.
+
+14. **Always use `--force` for programmatic deletes** — Without `--force`, delete commands prompt `[y/N]` which blocks non-interactive execution.
+
+15. **Routing delete commands use PLURAL names** — `delete-route-groups`, `delete-trunks`, `delete-route-lists`. The singular form (`delete-route-group`) does not exist.
+
+---
+
+## Error Handling
+
+When a wxcli command fails:
+
+**A. Fix and retry** — Missing required field, wrong ID, format issue:
+1. Read the full error message
+2. Run `wxcli <group> <command> --help` to check required flags
+3. Fix the command and retry
+
+**B. Skip and continue** — Resource already exists or already configured:
+1. Verify current state: `wxcli users show PERSON_ID` or `wxcli locations show LOCATION_ID`
+2. If state is correct, skip to next operation
+
+**C. Escalate** — Unclear or persistent error:
+1. Run with `--debug` for raw HTTP details
+2. Invoke `/wxc-calling-debug` for systematic diagnosis
+
+**D. 409 Conflict (50003 "Location is being referenced")**
+
+The location still has dependent resources. Load the `teardown` skill and follow its enumeration procedure. If all resources are deleted and the 409 persists, calling is still enabled — disable it and wait 90+ seconds.
+
+Provisioning-specific errors:
+- 400 on `users create`: Check email format, verify no existing user with same email
+- 400 on `numbers create`: Check E.164 format (+1XXXXXXXXXX), verify number not already assigned
+- 403: Check token has `spark-admin:people_write` and `spark-admin:telephony_config_write` scopes
+- 409: User/location already exists — GET current state first
+
+---
+
+## Required Scopes Reference
+
+| Operation | Scope(s) |
+|-----------|----------|
+| List/view people | `spark-admin:people_read` |
+| Create/update/delete people | `spark-admin:people_write` + `spark-admin:people_read` |
+| List licenses | `spark-admin:licenses_read` |
+| Assign licenses (PATCH) | `spark-admin:people_write` |
+| List/view locations | `spark-admin:locations_read` |
+| Create/update/delete locations | `spark-admin:locations_write` |
+| Enable location for calling | `spark-admin:telephony_config_write` |
+
+---
+
+## License Lookup Quick Reference
+
+> For bulk license assignment, usage auditing, and reclamation workflows, see the `manage-licensing` skill. The `licenses update` command provides CLI-native license assignment (`licenses-api` remains a deprecated alias for one release).
+
+```bash
+# List all licenses — look for "Webex Calling - Professional" with available capacity
+wxcli licenses list
+
+# Key license types to look for in the output:
+#   "Webex Calling - Professional"   — full calling license
+#   "Webex Calling - Basic"          — basic calling (limited features)
+#   "Webex Calling - Workspaces"     — for workspace devices
+# Check that consumed < total for the license you need
+```
+
+---
+
+## Two License Assignment Methods
+
+| | Method A: People API PUT | Method B: Licenses PATCH API |
+|---|---|---|
+| **CLI equivalent** | `wxcli users update` (modify user fields) | Raw HTTP PATCH `/licenses/users` (license assignment not in CLI yet) |
+| **Best for** | Migrating existing users, changing multiple Person fields | Net-new provisioning, SCIM users, atomic license+location+extension |
+| **Gotcha** | Must GET full person first, include ALL fields in PUT | Requires extension or phone_number for calling licenses |
+| **Can combine add+remove** | Manually modify the licenses list | Yes, add + remove operations in same call |
+
+---
+
+## Context Compaction Recovery
+
+If context compacts mid-execution, recover by:
+1. Read the deployment plan from `docs/plans/` to recover what was planned
+2. Check what's already been created: run the relevant `list` commands
+3. Resume from the first incomplete step

wxcli/_playbook/.claude/skills/query-live/SKILL.md

@@ -0,0 +1,183 @@
+---
+name: query-live
+description: |
+  Answer natural-language questions about a Webex Calling environment using live API data.
+  Read-only queries against people, call features, routing, numbers, call history, and call flow tracing.
+  Use when the user asks "who", "what", "which", "how many", "does", "is", "show me", or "check" questions
+  about their current Webex Calling configuration. Invoked by the wxc-calling-builder agent on query intent,
+  or directly via /query-live.
+  NOT for: making changes (use the appropriate config skill), historical CDR analysis
+  (use reporting skill), or Contact Center queries (use reporting-cc skill).
+allowed-tools: Read, Grep, Glob, Bash, Skill
+argument-hint: [question]
+---
+
+# Query Live State
+
+Answer plain-English questions about a Webex Calling environment using live API data. **Read-only only.**
+
+## Checkpoint — verify before proceeding
+
+1. Has `wxcli whoami` succeeded in this session? If not, run it now. Do not proceed without a valid token.
+2. Do you know which domain(s) this question touches? (people, features, routing, numbers, call-history, call-flow). If unsure, read the Domain Routing table below.
+
+## Step 1: Classify the question
+
+**Query signals** — this skill handles these:
+- Interrogative form: "Who...?", "What...?", "Which...?", "How many...?", "Does...?", "Is...?"
+- Inspection verbs: "show me", "list", "check", "look up", "find", "tell me about"
+- State references: "current", "right now", "configured", "enabled", "assigned"
+- Comparison/audit: "which users don't have...", "compare", "differences between"
+
+**Not a query** — hand back to the builder's normal workflow:
+- Action verbs: "create", "set up", "enable", "add", "configure", "change", "move", "delete"
+- Future intent: "I want to...", "we need to...", "can you make..."
+
+**Edge case:** "Can you check if voicemail is enabled and turn it on if not?"
+→ Classify as query first. Answer the check. Then say: "I can look things up but can't make changes. To enable voicemail, you'd go to Control Hub → Calling → User Settings → Voicemail, or I can help configure it if you'd like to switch to build mode."
+
+## Step 2: Route to domain module(s)
+
+Read the domain module(s) that match the question. Cross-domain queries load multiple modules.
+
+### Domain Routing Table
+
+| Question about... | Domain module | Load with |
+|-------------------|--------------|-----------|
+| Users, person settings (voicemail, forwarding, DND, recording, caller ID, permissions) | people-and-settings | `Read .claude/skills/query-live/domains/people-and-settings.md` |
+| Hunt groups, call queues, auto attendants, paging, call park, pickup, voicemail groups | features | `Read .claude/skills/query-live/domains/features.md` |
+| Trunks, route groups, route lists, dial plans, translation patterns, PSTN | routing | `Read .claude/skills/query-live/domains/routing.md` |
+| Phone numbers, number inventory, assignment status, available numbers | numbers | `Read .claude/skills/query-live/domains/numbers.md` |
+| Call history, CDR, call volume, missed calls, busiest hours | call-history | `Read .claude/skills/query-live/domains/call-history.md` |
+| "What happens when someone calls...", call path tracing, schedule evaluation | call-flow-trace | `Read .claude/skills/query-live/domains/call-flow-trace.md` |
+
+**Cross-domain examples:**
+- "Show me all users at Austin with their devices and voicemail status" → people-and-settings (primary)
+- "What number is assigned to the Main auto attendant?" → features + numbers
+
+**Cross-domain anti-pattern — do NOT combine these:**
+- "Who's in the Sales hunt group and what are their forwarding settings?" — member personal forwarding settings are irrelevant to HG routing. Hunt groups route directly to agent devices and ignore personal call forwarding entirely. Ask about the HG's own no-answer/forwarding settings instead (features domain only).
+
+## Step 3: Execute the domain module's recipes
+
+Follow the loaded domain module's command recipes, resolution rules, and join patterns exactly. Use `-o json` on all commands for programmatic parsing.
+
+**Mandatory --help verification:** Before constructing any wxcli command, run `wxcli <group> --help` to verify the subcommand exists, then `wxcli <group> <subcommand> --help` to verify the exact flags (e.g. `wxcli people list --help`). Even read-only commands differ by name (`show` vs `list`, singular vs plural — known issue #5), so confirm before running. Do NOT rely on examples in this skill, the domain modules, or reference docs — the CLI is auto-generated and flag names may differ from what documentation suggests.
+
+### Resource Resolution Protocol
+
+When the user references a resource by name (not ID):
+
+1. **List** the resource type with `-o json`
+2. **Search** the response for name matches (case-insensitive substring)
+3. **Exact match** → use it immediately
+4. **Multiple partial matches** → disambiguate:
+   ```
+   I found 2 hunt groups matching "Sales":
+     1. Sales - East (Austin, 5 members)
+     2. Sales - West (Denver, 3 members)
+   Which one?
+   ```
+5. **No match** → report with suggestion:
+   ```
+   I couldn't find a hunt group named "Sales". The hunt groups at your org are:
+     - Support (Austin)
+     - Engineering (Denver)
+     - Front Desk (Austin)
+   Did you mean one of these?
+   ```
+
+### Batch Query Protocol
+
+For audit queries checking a setting across many users (e.g., "which users don't have voicemail?"):
+
+1. **Count first:** `wxcli people list -o json` → count results
+2. **If ≤ 50 users:** Fetch settings for each user sequentially
+3. **If > 50 users:** Note upfront: "Checking [N] users — this will take a moment." Batch in groups of 20 with brief progress updates every 20 users.
+4. **Report:** "Checked all [N] users at [location]. [X] of [N] don't have voicemail enabled."
+
+## Step 4: Format the response
+
+### Formatting Principles
+
+- **Lead with the direct answer**, then supporting details
+- **Use the admin's language**: "voicemail" not "voicemailEnabled", "forwarding" not "callForwarding"
+- **Include counts and context**: "3 of 12 users" not just "3 users"
+- **Be specific about what was checked**: "I checked all 45 users at the Austin location"
+
+### Format by Query Type
+
+**Membership queries** ("Who's in the Sales hunt group?"):
+```
+Sales Hunt Group has 4 members:
+  - Jane Smith (ext 2001, Austin)
+  - Bob Lee (ext 2002, Austin)
+  - Maria Garcia (ext 2003, Denver)
+  - Tom Chen (ext 2004, Denver)
+
+Ring pattern: Simultaneous
+No-answer action: Forward to Sales voicemail after 20 seconds
+```
+
+**Yes/no queries** ("Does John have voicemail enabled?"):
+```
+Yes, John Smith has voicemail enabled.
+  - Messages sent to: john.smith@acme.com
+  - PIN required: Yes
+  - Greeting: Custom greeting uploaded
+```
+
+**Inventory/audit queries** ("Which users at Austin don't have voicemail?"):
+```
+12 of 45 users at Austin don't have voicemail enabled:
+  - Alice Johnson (ext 3001)
+  - Brian Kim (ext 3002)
+  - Carol Davis (ext 3003)
+  ... and 9 more
+
+Note: I checked all 45 Webex Calling-licensed users at the Austin location.
+```
+
+**Large result sets (> 10 items):**
+- Show first 10 with "...and N more" note
+- Include summary count at top
+- Offer to show full list if needed
+
+### Disambiguation format:
+```
+I found 2 queues matching "Sales":
+  1. Sales - East (Austin, 5 agents)
+  2. Sales - West (Denver, 3 agents)
+
+Which one?
+```
+
+## Safety Guardrails
+
+### Read-Only Enforcement
+
+**Only use these command verbs:** `list`, `show`, `test`
+
+**Blocklisted verbs — NEVER use these in query mode:**
+`create`, `add`, `update`, `modify`, `delete`, `remove`, `assign`, `enable`, `disable`, `configure`
+
+If the user requests a change, respond with:
+1. The current state (the query result)
+2. "I can look things up but can't make changes in query mode."
+3. Where in Control Hub they'd make the change, OR offer to switch to build mode
+
+### Scope Limiting
+
+- Operate within the org authenticated via `wxcli configure`
+- If a partner/multi-org token is active, query the currently-selected org only
+- No cross-org queries or comparisons
+
+### Error Handling
+
+| Error | Response |
+|-------|----------|
+| 401 Unauthorized | "Your session may have expired. Run `wxcli configure` to re-authenticate." |
+| 403 Forbidden | "Your account doesn't have permission to view [resource]. Contact your org admin." |
+| 404 Not Found | "I couldn't find [resource]. It may have been deleted or the name might be different." |
+| 429 Rate Limited | "The API is rate-limiting requests. Try again in a minute." |
+| Timeout | "The request timed out. The org may have a large number of [resources]. Try narrowing your query to a specific location." |