wxcli 1.4.2__tar.gz → 1.4.4__tar.gz

{wxcli-1.4.2/src/wxcli/_playbook → wxcli-1.4.4}/.claude/agents/wxc-calling-builder.md

@@ -28,16 +28,6 @@ Your job is to make the process structured, safe, and recoverable. You interview
 
 When invoked, run these checks silently:
 
-### 0. Register agent with wxcli gate (REQUIRED — run FIRST, before any other Bash)
-
-The PreToolUse hook denies all `wxcli` Bash calls unless this agent has registered itself in `/tmp/.wxcli-agent-active`. Run this once at startup, before `wxcli --help` or any other command:
-
-```bash
-echo $PPID >> /tmp/.wxcli-agent-active
-```
-
-This appends the parent Claude Code process PID to the gate file. Multiple concurrent wxc-calling-builder agents in the same Claude Code session will append the same PID multiple times — that is expected and correct (ref-counted). The `SubagentStop` hook automatically removes one entry on every subagent exit, so no explicit teardown is required — do not run a teardown block yourself (it will over-decrement and lock out sibling agents).
-
 ### 1. CLI Environment
 
 Check that wxcli is installed:
@@ -369,15 +359,14 @@ Read `docs/templates/deployment-plan.md` to get the template. Fill in every sect
 
 Execute commands in the order specified in the deployment plan. Use wxcli CLI commands for all standard operations.
 
-### Discovery-First Rule (applies to ALL phases, not just execution)
+### Discovery-First Rule
 
-When checking whether a capability, config key, API field, or setting exists — discover first, act second:
+Discover first, act second — one broad query, evaluate, stop within 3 commands; accept a
+negative result rather than hunting for workarounds. The rule and its false-negative guard
+live in CLAUDE.md (§ Discovery-First Rule), which you already have in context. It applies to
+reads and queries too, which is why it is no longer duplicated here.
 
-1. **One broad query** — enumerate what's available (e.g., `wxcli device-configurations show --device-id X --key "Lines.*"`)
-2. **Evaluate the result** — is the target in the response?
-3. **If yes** → proceed. **If no** → report what you found and **stop within 3 total commands**.
-
-**Anti-pattern: refusing a negative result.** If a broad query shows the target doesn't exist, accept it. Do not try alternate key names, narrower/broader filters, the same query on a different device, speculative writes, or workaround paths. Report the negative finding — that IS the answer. Three total commands max before reporting back.
+Example of a broad query in this domain: `wxcli device-configurations show --device-id X --key "Lines.*"`
 
 ### Progress Reporting
 
@@ -581,12 +570,9 @@ Each row names what the skill contains that is NOT in your training data. Do NOT
 
 ### Source of Truth Precedence
 
-When information conflicts between sources, trust them in this order:
-
-1. **`wxcli <command> --help`** — the running code; always current
-2. **Skills** — verified against live APIs; contain exact command examples
-3. **Reference docs** — comprehensive but can lag behind skill and CLI updates
-4. **Your training data** — least reliable; NEVER trust over the above three
+`--help` > skills > reference docs > training data. The full rule lives in CLAUDE.md
+(§ Source of Truth Precedence), which you already have in context; it applies to every
+caller of `wxcli`, not just this agent, so it is no longer duplicated here.
 
 Example: if a reference doc says `wxcli locations-api list` but the skill says `wxcli locations list`, run `wxcli locations list --help` to see which exists. If `--help` confirms `locations list` works, use that regardless of what the reference doc says.
 

{wxcli-1.4.2 → wxcli-1.4.4}/.claude/settings.json

@@ -12,5 +12,19 @@
       "Bash(python3.11:*)",
       "Bash(PYTHONPATH=.:*)"
     ]
+  },
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "sh /Users/ahobgood/Documents/webexCalling/.claude/hooks/wxcli-gate.sh",
+            "timeout": 5
+          }
+        ]
+      }
+    ]
   }
 }

{wxcli-1.4.2/src/wxcli/_playbook → wxcli-1.4.4}/.claude/skills/device-platform/SKILL.md

@@ -14,10 +14,12 @@ argument-hint: [device-platform-operation]
 # Device Platform Workflow
 
 **Checkpoint — do NOT proceed until you can answer these:**
-1. Do 9800-series phones (9811/9821/9841/9851/9861/9871) use telephony device settings or RoomOS config keys? (Answer: RoomOS config keys — they are NOT configured via `wxcli device-settings` or telephony settings APIs.)
-2. What CLI group handles xAPI commands for device control? (Answer: `wxcli xapi` — covers both command execution and status queries on devices.)
+1. Do 9800-series phones (9811/9821/9841/9851/9861/9871) use telephony device settings or PhoneOS config keys? (Answer: PhoneOS config keys via the Device Configurations API (`wxcli device-configurations`) — they are NOT configured via `wxcli device-settings` or telephony settings APIs.)
+2. What CLI group handles xAPI commands for device control? (Answer: `wxcli xapi` — covers schema discovery (`list`), status queries (`show`), and command execution (`create`).)
+3. You need a key name (command, status, or config) and don't know it. What do you do FIRST? (Answer: dump the device's full namespace to disk with `"*"` and grep it — see 6c. Do NOT guess a namespace, do NOT use training data, do NOT send the user to a website.)
+4. You grep all three dumps and the key isn't there. What do you report? (Answer: "this device does not expose it" — NOT "the feature doesn't exist." Coverage varies by model and firmware.)
 
-If you cannot answer both, you skipped reading this skill. Go back and read it.
+If you cannot answer all four, you skipped reading this skill. Go back and read it.
 
 ## Step 1: Load references
 
@@ -202,7 +204,68 @@ wxcli workspace-personalization show WORKSPACE_ID
 - Common error: "Device is offline" -- the workspace device must be online and registered
 - **Do not tell the user it is done until `show` returns `success: true`**
 
-### 6c. xAPI -- Status Queries
+### 6c. Discover the Namespace -- Dump, Then Grep
+
+**Do this FIRST whenever you do not already know the exact key name. Do NOT guess a namespace, and do NOT rely on your training data for xAPI key names.**
+
+The device reports its own complete namespace. Dump all three surfaces to disk, then grep locally:
+
+**One device per dump. Always namespace the filenames by device.** Namespaces differ by model and firmware — a key on one device may be absent on the next.
+
+```bash
+# Pick a short unique tag per device (e.g. its displayName, slugified). ONE device per file.
+TAG=roombarpro   # <- change per device; never reuse across devices
+
+wxcli xapi list --device-id DEVICE_ID --status  "*" -o json > /tmp/${TAG}_status.json
+wxcli xapi list --device-id DEVICE_ID --command "*" -o json > /tmp/${TAG}_commands.json
+
+# Configurations -- DIFFERENT API, see the surface table below
+wxcli device-configurations show --device-id DEVICE_ID -o json > /tmp/${TAG}_configs.json
+
+# Search ONE device's dumps at a time -- never glob across devices
+grep -io '"[A-Za-z][A-Za-z0-9._[]]*Background[A-Za-z0-9._[]]*"' /tmp/${TAG}_*.json | sort -u
+```
+
+**NEVER `Read` these dumps.** Verified live on a Room Bar Pro: 535 statuses + 453 commands + 1,218 configs, ~1.4 MB combined (~350k tokens). Grep them; never open them.
+
+**Multi-device rules — violating these is how you execute against the wrong box:**
+
+- **Never grep across devices** (no `/tmp/*_status.json` globs). A hit tells you a key exists *somewhere*, not on the device you're about to call. Re-grep that device's own dump before executing.
+- `--device-id` accepts up to **5 device IDs** per request, and the response is an array where each item carries its own `deviceId`. If you ever query more than one at a time, you **must** parse per `deviceId` — a flat grep destroys the attribution the API gave you.
+- **Fleet-wide work:** dump each device separately, grep each separately, and treat "device A has it" as zero evidence about device B. Report per-device results, not a single fleet-wide answer.
+- **Mixed fleets: xAPI is RoomOS-only.** Room/Board/Desk series support xAPI; PhoneOS 9800-series and MPP phones do not. On a 9800-series phone, skip the `xapi` dumps entirely and use `device-configurations` (6a) — that API serves both RoomOS and PhoneOS. A failed xAPI call on a phone is expected, not a bug; do not report it as the device being broken, and do not retry it.
+
+**Why dump instead of filter:** filtering requires guessing the first word, and that guess is a coin flip. `Camera.*` and `Cameras.*` are BOTH real, distinct namespaces on the same device — a filtered query on the wrong one returns a confident, complete-looking, wrong answer. Dumping has no such failure mode. Once you know the namespace, filtering (`--command "Camera.*"`) is a fine optimization.
+
+**Three surfaces, two APIs — a key lives in exactly one:**
+
+| Surface | API | Command | Example |
+|---------|-----|---------|---------|
+| Command (do a thing) | xAPI | `wxcli xapi list --command`, `xapi create` | `Camera.PositionReset` |
+| Status (read a live value) | xAPI | `wxcli xapi list --status`, `xapi show` | `SystemUnit.ProductPlatform` |
+| Configuration (persistent setting) | Device Configurations | `wxcli device-configurations show/update` (6a) | `Video.Input.CameraConfigMode` |
+
+`xapi list` **cannot see configurations** — `/xapi/schema` accepts only `--status` and `--command`. If you search only xAPI for a setting, you will wrongly conclude it does not exist. Search all three dumps.
+
+**Verified behaviors — do not re-derive these:**
+
+- **`-o json` is mandatory.** The default table output renders a single `Device Id` column and silently drops every command, argument, and schema. It does not error — it just looks like the device has nothing.
+- **The dumps contain NO descriptions.** Checked across all 2,206 keys on a live device: zero `description`/`help`/`summary`/`doc` fields. A command returns only `arguments` (each with `required` + a JSON Schema) and a `resultSchema`; a config returns only `value`, `source`, `sources`, `valueSpace`, `appliedConfigurationValue`. **The device tells you a key's shape, never its meaning.** Do not tell the user what a key does based on a dump alone — say you have the name and shape but not the semantics.
+- `--device-id` is required (max 5 per request). Discovery needs a live, online, cloud-registered device.
+- Scopes differ: `spark:xapi_commands` for `--command`, `spark:xapi_statuses` for `--status`. Configurations use `spark-admin:devices_read/write`.
+
+**Absence in a dump means "not on THIS device" — never "does not exist."**
+Coverage varies sharply by model and firmware. A real example: the virtual-background keys (`Cameras.Background.*`) exist on Cisco hardware but are absent from a Room Bar Pro's dump entirely. If you grep and find nothing, report *"this device does not expose it"* and name the device — do NOT tell the user the feature does not exist. A confident false negative is worse than no answer.
+
+**Worked example -- "reset the camera position on device XYZ":**
+
+1. Dump + grep: `grep -io '"Camera[^"]*"' /tmp/dev_commands.json | sort -u` -> finds `Camera.PositionReset`
+2. Read that key's object: `CameraId` (required, integer 1-15) and `Axis` (optional enum `All`/`Focus`/`PanTilt`/`Zoom`, default `All`). *(Verified live.)*
+3. Execute: `wxcli xapi create Camera.PositionReset --device-id XYZ --json-body '{"deviceId": "XYZ", "arguments": {"CameraId": 1}}'`
+
+Argument names and value ranges vary by model and firmware. Trust the dump for the device in front of you over any example in this skill.
+
+### 6d. xAPI -- Status Queries
 
 ```bash
 # Query a single status value
@@ -227,7 +290,7 @@ wxcli xapi show --device-id DEVICE_ID --name "Audio.Volume,SystemUnit.State.Numb
 | `Peripherals.ConnectedDevice[*].Name` | Connected peripherals |
 | `Standby.State` | Standby/active state |
 
-### 6d. xAPI -- Command Execution
+### 6e. xAPI -- Command Execution
 
 ```bash
 # Simple command with no arguments (deviceId auto-populated from --device-id)
@@ -260,7 +323,7 @@ wxcli xapi create UserInterface.Message.Alert.Display --device-id DEVICE_ID --js
 | `Message.Send` | `Text` | Display on-screen message |
 | `UserInterface.Message.Alert.Display` | `Title`, `Text`, `Duration` | Show alert popup |
 
-**Do not enumerate the full xAPI namespace.** The namespace is huge. Ask the user what they want to DO, then look up the specific command name. Point them to https://roomos.cisco.com/xapi for the full reference.
+**Do not paste the namespace into context — but do dump it.** An unfiltered `xapi list` returns hundreds of keys (~350k tokens across all three surfaces). Redirect it to a file and grep (6c); never `Read` it. https://roomos.cisco.com/xapi documents the namespace for humans and is the only source of *prose* for what a key means, but it is not a substitute for 6c — only the device knows what it actually exposes.
 
 ### Error handling
 
@@ -268,7 +331,7 @@ wxcli xapi create UserInterface.Message.Alert.Display --device-id DEVICE_ID --js
 |-------|-------|-----|
 | 401/403 | Token expired or insufficient scopes | Run `wxcli configure` to re-authenticate |
 | 400 "device not found" | Invalid device ID or device not cloud-registered | Verify with `wxcli devices list` |
-| 400 on xAPI command | Device offline, wrong command name, or missing arguments | Check device is online, verify command name at roomos.cisco.com/xapi |
+| 400 on xAPI command | Device offline, wrong command name, or missing arguments | Check device is online, then confirm the command name and its required arguments against the device with a filtered `wxcli xapi list` (6c) |
 | 400 on device-configurations update | Invalid path, bad JSON Patch format, or non-editable key | Verify path ends in `/sources/configured/value`, check key is editable |
 | Personalization "Device is offline" | Workspace device not online | Device must be powered on and cloud-registered |
 
@@ -355,7 +418,7 @@ Next steps:
 
 6. **Configuration update PATCH content type.** The API uses `application/json-patch+json`, not `application/json`. The CLI handles this automatically. If the user falls back to raw HTTP (curl), they must set the `Content-Type` header correctly.
 
-7. **Do not enumerate xAPI commands.** The xAPI namespace is huge. Ask the user what they want to DO, then look up the specific command name. Point them to https://roomos.cisco.com/xapi for the full command reference.
+7. **Never guess a key name — dump the device's namespace and grep it (6c).** Filtering on a guessed namespace is a coin flip: `Camera.*` and `Cameras.*` are both real and distinct, so a wrong guess returns a confident, complete-looking, wrong answer. Dump all three surfaces with `"*"` to disk and grep. Never `Read` the dumps (~350k tokens). Do not substitute training data or a link to roomos.cisco.com for the lookup. The device is authoritative for its own model and firmware — but only about itself: absence means "not on this device," not "does not exist."
 
 8. **Scope mismatch between device-configurations and xAPI.** Device configurations use admin scopes (`spark-admin:devices_read`/`spark-admin:devices_write`). xAPI uses user-level scopes (`spark:xapi_statuses`/`spark:xapi_commands`). A token may have one set but not the other. Diagnose scope issues early in Step 2.
 

{wxcli-1.4.2/src/wxcli/_playbook/.codex → wxcli-1.4.4/.claude}/skills/query-live/domains/people-and-settings.md

@@ -16,17 +16,25 @@
 ## Command Recipes
 
 ### List users (org-wide or filtered)
+
+**Always pass `--calling-data true` when the question touches extension, location, or
+any calling attribute.** Without it the API omits those fields entirely — the command
+still exits 0 and returns every person, so a count built from it silently reports zero.
+
 ```bash
-wxcli people list -o json
-wxcli people list --location-id LOCATION_ID -o json
-wxcli people list --display-name "John Smith" -o json
-wxcli people list --email "john@example.com" -o json
+wxcli people list --calling-data true -o json
+wxcli people list --calling-data true --location-id LOCATION_ID -o json
+wxcli people list --calling-data true --display-name "John Smith" -o json
+wxcli people list --calling-data true --email "john@example.com" -o json
 ```
 
+Omit `--calling-data` only for pure directory questions (name, email, roles, licenses).
+
 ### Show a specific user
 ```bash
-wxcli people show PERSON_ID -o json
+wxcli people show PERSON_ID --calling-data true -o json
 ```
+Same rule as `list`: without `--calling-data true`, `extension` and `locationId` are absent.
 
 ### Voicemail settings
 ```bash
@@ -92,13 +100,14 @@ wxcli user-settings show-hoteling PERSON_ID -o json
 
 **Finding users at a location by name:**
 1. `wxcli locations list -o json` → search for location name → get ID
-2. `wxcli people list --location-id <locationId> -o json`
+2. `wxcli people list --calling-data true --location-id <locationId> -o json`
 
 ## Join Patterns
 
 **Audit query** ("Which users at Austin don't have voicemail?"):
 1. Resolve location name → ID: `wxcli locations list -o json`
-2. List users at location: `wxcli people list --location-id <locationId> -o json`
+2. List users at location: `wxcli people list --calling-data true --location-id <locationId> -o json`
+   (`--calling-data true` is required — the audit report prints each user's extension)
 3. For each user, fetch setting: `wxcli user-settings show-voicemail <personId> -o json`
 4. Filter to matches (enabled=false or missing)
 5. Format as audit table

{wxcli-1.4.2 → wxcli-1.4.4}/.gitignore

@@ -46,12 +46,21 @@ docs/arch/
 docs/webex-api-feedback.html
 docs/webex-api-feedback-for-cisco-collab-bu.md
 
-# Tests (dev-only, except the actively-maintained migration/org-health suites)
+# Tests (dev-only, except the actively-maintained migration/org-health suites
+# and the artifact guards below)
 tests/*
 !tests/migration/
 !tests/migration/**
 !tests/org_health/
 !tests/org_health/**
+# Artifact guards: these assert on files that ship (settings.bundled.json,
+# field_overrides.yaml, README.md, ci.yml). They caught real drift while CI
+# could not see them, so they are tracked and run on every PR. They import only
+# stdlib/pytest/yaml plus in-repo modules — no network, no live API, and no
+# dependency on the untracked tests/conftest.py.
+!tests/test_assemble.py
+!tests/test_field_overrides.py
+!tests/test_readme_distribution.py
 !tests/test_release_integrity.py
 tests/migration/**/__pycache__/
 tests/org_health/**/__pycache__/
@@ -89,6 +98,9 @@ tools/reassign_dids_to_cc.py
 README.md.bak
 src/wxcli/_version.py
 
+# Org-health scan output (contains live org data — person IDs, numbers, devices)
+org-health-output/
+
 # Remotion video production (local build artifact)
 remotion-video/
 

{wxcli-1.4.2/src/wxcli/_playbook → wxcli-1.4.4}/CLAUDE.md

@@ -15,6 +15,47 @@ For every question — capability, configuration, behavior, limits, or anything
 
 The reference docs and skills are the authoritative source for this project. Training data about Cisco/Webex products is unreliable — product tiers get conflated, feature names change, and capabilities vary by license. If the answer isn't in the docs or skills, say so explicitly rather than filling the gap from training data.
 
+## Source of Truth Precedence
+
+Applies to everyone touching `wxcli` — main session, skills, and agents alike. When
+sources conflict, trust them in this order:
+
+1. **`wxcli <command> --help`** — the running code; always current
+2. **Skills** — verified against live APIs; contain exact command examples
+3. **Reference docs** — comprehensive but can lag behind skill and CLI updates
+4. **Your training data** — least reliable; NEVER trust over the above three
+
+This refines the grounding rule above: skills and docs outrank your training, but
+`--help` outranks *them*. A skill's recipe is a starting point, not a guarantee — recipes
+are hand-written and drift as the CLI regenerates. When a recipe and `--help` disagree,
+`--help` wins, and the stale recipe should be fixed, not worked around.
+
+**A read-only command can be silently wrong.** Real case: the query-live recipe said
+`wxcli people list -o json`, but Webex omits `extension` and `locationId` unless
+`--calling-data true` is passed. The command exits 0 and returns every user, so
+"how many users have extensions?" answers **0** instead of the true count. No error, no
+warning. Before trusting a read, confirm via `--help` that the command was actually
+capable of returning the field you are about to draw a conclusion from.
+
+## Discovery-First Rule
+
+Applies to ALL work — reads, queries, and builds — not just execution. When checking
+whether a capability, config key, API field, or setting exists, discover first, act second:
+
+1. **One broad query** — enumerate what's available
+2. **Evaluate the result** — is the target in the response?
+3. **If yes** → proceed. **If no** → report what you found and **stop within 3 total commands**.
+
+**Anti-pattern: refusing a negative result.** If a broad query shows the target doesn't
+exist, accept it. Do not try alternate key names, narrower/broader filters, the same query
+on a different resource, speculative writes, or workaround paths. Report the negative
+finding — that IS the answer. Three total commands max before reporting back.
+
+**Guard on that rule: only accept a negative once the query could have returned a positive.**
+An absent field may mean "not configured" or may mean "you didn't ask for it" (see the
+`--calling-data` case above). Confirm the command surfaces the field before reporting
+"none found" — a false negative delivered confidently is worse than no answer.
+
 ## Plain-English Communication Rule
 
 The target user has ZERO platform experience. When explaining findings, trade-offs, or decisions — or asking the user to choose between options — do NOT lead with jargon, acronyms, or internal feature-names. Instead:

{wxcli-1.4.2/src/wxcli.egg-info → wxcli-1.4.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: wxcli
-Version: 1.4.2
+Version: 1.4.4
 Summary: Webex Calling CLI — terminal-based provisioning for Webex APIs
 Author: Adam Hobgood
 License: Apache-2.0
@@ -41,6 +41,13 @@ A command-line tool and AI-assisted playbook for provisioning, managing, migrati
 
 > **Unofficial community CLI — not affiliated with or endorsed by Cisco.**
 
+> **Use at your own risk.** This software is provided "AS IS", without warranty
+> of any kind, and the authors accept no liability for any damage, data loss, or
+> service disruption arising from its use (see [LICENSE](LICENSE), Apache 2.0
+> §7–8). It performs **write and delete operations against live production
+> Webex Calling and CUCM environments**, driven in part by non-deterministic AI.
+> You are responsible for reviewing every action before it runs.
+
 ## What It Does
 
 - **176 CLI command groups** — provision locations, users, call features, devices, routing, PSTN, messaging, meetings, and contact center resources from the terminal
@@ -493,6 +500,46 @@ The CLI covers 176 command groups across calling, admin, device, messaging, meet
 
 See [`docs/reference/authentication.md`](docs/reference/authentication.md) for full details on token types, OAuth flows, and scope requirements per endpoint.
 
+## Disclaimer & Safe Use
+
+wxcli is an unofficial, community-maintained tool. It is **not affiliated with,
+endorsed by, or supported by Cisco.** "Webex", "Webex Calling", and "CUCM" are
+Cisco trademarks, used here only to describe interoperability.
+
+**This tool changes and deletes real telephony configuration.** The AI playbook
+reasons and orchestrates using a large language model, which is non-deterministic:
+the same prompt can produce different actions, and the agent can select the wrong
+resource. The layered design (docs → skills → tested CLI, with read-back
+verification) is built to reduce this, but **cannot eliminate it.**
+
+Before running anything against a production org:
+
+- **Preview first.** Use `--dry-run` (cleanup, migration) and review the plan.
+- **Verify emergency services.** E911 / emergency-callback misconfiguration is a
+  life-safety risk. Independently confirm every emergency address and ECBN after
+  any change — do not rely on the tool's read-back alone.
+- **`cleanup run --all` is irreversible** and deletes an entire org's calling
+  config. There is no undo.
+- **Test in a lab or sandbox org first**, especially for CUCM migrations.
+- **You are the operator of record.** You are responsible for reviewing and
+  authorizing every action, and for compliance with your own change-control,
+  regulatory (e.g. Kari's Law / RAY BAUM's Act), and data-handling obligations.
+
+By using this tool you accept these risks and the terms of the Apache 2.0 License.
+
+### Credentials, secrets, and API usage
+
+- **Tokens are stored locally in plaintext** in your wxcli config file. Treat that
+  file like a password — it grants full admin access to your Webex org. Personal
+  access tokens expire after 12 hours; OAuth/service-app tokens live longer, so
+  guard them accordingly.
+- **CUCM AXL credentials** passed inline to `wxcli cucm discover --username/--password`
+  land in your shell history. Prefer a prompt-based flow or a throwaway shell, and
+  clear the history afterward.
+- **The AI playbook can generate many API calls in a loop.** Long agent runs and
+  large migrations may hit Webex API rate limits; the tool retries, but you own the
+  API-usage footprint against your org.
+
 ## License
 
 Apache 2.0 — see LICENSE.

{wxcli-1.4.2 → wxcli-1.4.4}/README.md

@@ -4,6 +4,13 @@ A command-line tool and AI-assisted playbook for provisioning, managing, migrati
 
 > **Unofficial community CLI — not affiliated with or endorsed by Cisco.**
 
+> **Use at your own risk.** This software is provided "AS IS", without warranty
+> of any kind, and the authors accept no liability for any damage, data loss, or
+> service disruption arising from its use (see [LICENSE](LICENSE), Apache 2.0
+> §7–8). It performs **write and delete operations against live production
+> Webex Calling and CUCM environments**, driven in part by non-deterministic AI.
+> You are responsible for reviewing every action before it runs.
+
 ## What It Does
 
 - **176 CLI command groups** — provision locations, users, call features, devices, routing, PSTN, messaging, meetings, and contact center resources from the terminal
@@ -456,6 +463,46 @@ The CLI covers 176 command groups across calling, admin, device, messaging, meet
 
 See [`docs/reference/authentication.md`](docs/reference/authentication.md) for full details on token types, OAuth flows, and scope requirements per endpoint.
 
+## Disclaimer & Safe Use
+
+wxcli is an unofficial, community-maintained tool. It is **not affiliated with,
+endorsed by, or supported by Cisco.** "Webex", "Webex Calling", and "CUCM" are
+Cisco trademarks, used here only to describe interoperability.
+
+**This tool changes and deletes real telephony configuration.** The AI playbook
+reasons and orchestrates using a large language model, which is non-deterministic:
+the same prompt can produce different actions, and the agent can select the wrong
+resource. The layered design (docs → skills → tested CLI, with read-back
+verification) is built to reduce this, but **cannot eliminate it.**
+
+Before running anything against a production org:
+
+- **Preview first.** Use `--dry-run` (cleanup, migration) and review the plan.
+- **Verify emergency services.** E911 / emergency-callback misconfiguration is a
+  life-safety risk. Independently confirm every emergency address and ECBN after
+  any change — do not rely on the tool's read-back alone.
+- **`cleanup run --all` is irreversible** and deletes an entire org's calling
+  config. There is no undo.
+- **Test in a lab or sandbox org first**, especially for CUCM migrations.
+- **You are the operator of record.** You are responsible for reviewing and
+  authorizing every action, and for compliance with your own change-control,
+  regulatory (e.g. Kari's Law / RAY BAUM's Act), and data-handling obligations.
+
+By using this tool you accept these risks and the terms of the Apache 2.0 License.
+
+### Credentials, secrets, and API usage
+
+- **Tokens are stored locally in plaintext** in your wxcli config file. Treat that
+  file like a password — it grants full admin access to your Webex org. Personal
+  access tokens expire after 12 hours; OAuth/service-app tokens live longer, so
+  guard them accordingly.
+- **CUCM AXL credentials** passed inline to `wxcli cucm discover --username/--password`
+  land in your shell history. Prefer a prompt-based flow or a throwaway shell, and
+  clear the history afterward.
+- **The AI playbook can generate many API calls in a loop.** Long agent runs and
+  large migrations may hit Webex API rate limits; the tool retries, but you own the
+  API-usage footprint against your org.
+
 ## License
 
 Apache 2.0 — see LICENSE.

{wxcli-1.4.2 → wxcli-1.4.4}/docs/reference/devices-platform.md

@@ -24,7 +24,7 @@ Before using any of the three APIs documented here, you need:
 
 1. **A working auth token.** Verify with `wxcli whoami`. Token type (admin, user, service app) affects which scopes are available — see the Scopes section below.
 
-2. **At least one cloud-registered RoomOS device** (for device-configurations and xAPI). This means a Cisco Room, Board, or Desk series device registered to Webex cloud. MPP phones do not support device-configurations key management or xAPI.
+2. **At least one cloud-registered RoomOS device or PhoneOS 9800-series phone.** Device-configurations works on either: a Cisco Room, Board, or Desk series device (RoomOS) or a 9800-series phone (9811/9821/9841/9851/9861/9871, PhoneOS) registered to Webex cloud. xAPI requires a RoomOS device specifically. MPP phones (68xx/78xx/88xx) support neither — they use the telephony device settings API instead (see [devices-core.md](devices-core.md)).
 
 3. **At least one workspace with a device** (for workspace-personalization). The workspace must already exist and have a device assigned to it.
 
@@ -61,7 +61,7 @@ The Device Configurations API reads and writes RoomOS configuration keys on a sp
 
 Changes are applied via JSON Patch operations (`replace` to set a value, `remove` to revert to the schema default). The API supports filtering by key name, wildcard patterns, and index ranges.
 
-This API targets RoomOS devices only (Room, Board, Desk series). MPP phones do not expose configuration keys through this interface.
+This API targets RoomOS devices (Room, Board, Desk series) and PhoneOS 9800-series phones. The API surface is shared between the two platforms, but the reported config-key schemas differ by platform and firmware (see gotcha #11). MPP phones do not expose configuration keys through this interface.
 
 ### CLI Commands
 

{wxcli-1.4.2 → wxcli-1.4.4/src/wxcli/_playbook}/.claude/agents/wxc-calling-builder.md

@@ -28,16 +28,6 @@ Your job is to make the process structured, safe, and recoverable. You interview
 
 When invoked, run these checks silently:
 
-### 0. Register agent with wxcli gate (REQUIRED — run FIRST, before any other Bash)
-
-The PreToolUse hook denies all `wxcli` Bash calls unless this agent has registered itself in `/tmp/.wxcli-agent-active`. Run this once at startup, before `wxcli --help` or any other command:
-
-```bash
-echo $PPID >> /tmp/.wxcli-agent-active
-```
-
-This appends the parent Claude Code process PID to the gate file. Multiple concurrent wxc-calling-builder agents in the same Claude Code session will append the same PID multiple times — that is expected and correct (ref-counted). The `SubagentStop` hook automatically removes one entry on every subagent exit, so no explicit teardown is required — do not run a teardown block yourself (it will over-decrement and lock out sibling agents).
-
 ### 1. CLI Environment
 
 Check that wxcli is installed:
@@ -369,15 +359,14 @@ Read `docs/templates/deployment-plan.md` to get the template. Fill in every sect
 
 Execute commands in the order specified in the deployment plan. Use wxcli CLI commands for all standard operations.
 
-### Discovery-First Rule (applies to ALL phases, not just execution)
+### Discovery-First Rule
 
-When checking whether a capability, config key, API field, or setting exists — discover first, act second:
+Discover first, act second — one broad query, evaluate, stop within 3 commands; accept a
+negative result rather than hunting for workarounds. The rule and its false-negative guard
+live in CLAUDE.md (§ Discovery-First Rule), which you already have in context. It applies to
+reads and queries too, which is why it is no longer duplicated here.
 
-1. **One broad query** — enumerate what's available (e.g., `wxcli device-configurations show --device-id X --key "Lines.*"`)
-2. **Evaluate the result** — is the target in the response?
-3. **If yes** → proceed. **If no** → report what you found and **stop within 3 total commands**.
-
-**Anti-pattern: refusing a negative result.** If a broad query shows the target doesn't exist, accept it. Do not try alternate key names, narrower/broader filters, the same query on a different device, speculative writes, or workaround paths. Report the negative finding — that IS the answer. Three total commands max before reporting back.
+Example of a broad query in this domain: `wxcli device-configurations show --device-id X --key "Lines.*"`
 
 ### Progress Reporting
 
@@ -581,12 +570,9 @@ Each row names what the skill contains that is NOT in your training data. Do NOT
 
 ### Source of Truth Precedence
 
-When information conflicts between sources, trust them in this order:
-
-1. **`wxcli <command> --help`** — the running code; always current
-2. **Skills** — verified against live APIs; contain exact command examples
-3. **Reference docs** — comprehensive but can lag behind skill and CLI updates
-4. **Your training data** — least reliable; NEVER trust over the above three
+`--help` > skills > reference docs > training data. The full rule lives in CLAUDE.md
+(§ Source of Truth Precedence), which you already have in context; it applies to every
+caller of `wxcli`, not just this agent, so it is no longer duplicated here.
 
 Example: if a reference doc says `wxcli locations-api list` but the skill says `wxcli locations list`, run `wxcli locations list --help` to see which exists. If `--help` confirms `locations list` works, use that regardless of what the reference doc says.