@xerg/cli 0.5.1 → 0.5.2

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@xerg/cli",
-  "version": "0.5.1",
-  "description": "Audit OpenClaw and Hermes workflows in dollars, compare fixes, and export daily spend and waste trends.",
+  "version": "0.5.2",
+  "description": "Audit OpenClaw, Hermes, and Cursor spend in dollars with provenance-aware waste findings and compare output.",
   "keywords": [
     "xerg",
     "ai",
@@ -13,7 +13,8 @@
     "cost",
     "cli",
     "cursor",
-    "analytics"
+    "analytics",
+    "provenance"
   ],
   "homepage": "https://xerg.ai",
   "repository": {
@@ -53,7 +54,7 @@
   },
   "dependencies": {
     "@inquirer/prompts": "^8.4.1",
-    "better-sqlite3": "^11.10.0"
+    "better-sqlite3": "^12.11.1"
   },
   "devDependencies": {
     "@xerg/schemas": "workspace:*",

package/skills/xerg/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: xerg
-description: Audit OpenClaw and Hermes workflows in dollars. Local-first audits with init, compare mode, OpenClaw remote support, CI gates, and optional hosted follow-up.
+description: Audit OpenClaw, Hermes, and Cursor spend in dollars. Local-first audits with provenance-aware findings, compare mode, OpenClaw remote support, CI gates, and optional hosted follow-up.
 homepage: https://xerg.ai
 metadata:
   openclaw:
@@ -48,7 +48,7 @@ metadata:
 
 Use `xerg` if it is already installed. If not, use `npx @xerg/cli` with the same arguments.
 
-Xerg audits OpenClaw and Hermes workflows in dollars, not tokens. It reads gateway logs and session transcripts, surfaces confirmed waste plus savings opportunities, and helps you measure fixes with `--compare`.
+Xerg audits OpenClaw, Hermes, and Cursor spend in dollars, not tokens. It reads gateway logs, session transcripts, and Cursor usage exports, surfaces provenance-aware confirmed waste plus savings opportunities, and helps you measure fixes with `--compare`.
 
 Local audits need no account. Hosted sync and hosted MCP are optional paid workspace features. No data leaves your machine unless you explicitly push results to Xerg Cloud.
 
@@ -66,6 +66,7 @@ Use direct commands when you need explicit control, non-interactive behavior, JS
 ```bash
 xerg doctor
 xerg audit
+xerg audit --cursor-usage-csv ./cursor-usage.csv
 xerg audit --json
 xerg audit --fail-above-waste-rate 0.30
 ```
@@ -80,6 +81,7 @@ Xerg needs one of these source inputs:
 - Local Hermes data at the default paths:
   - `~/.hermes/logs/agent.log*` with `gateway.log*` fallback
   - `~/.hermes/sessions/`
+- An exported Cursor usage CSV via `--cursor-usage-csv`
 - Explicit paths via `--log-file` and/or `--sessions-dir`
 - An SSH target via `--remote`
 - A Railway target via `--railway`
@@ -89,6 +91,7 @@ Additional requirements:
 
 - `--compare` needs at least one previously stored compatible local snapshot
 - Pushing needs auth via `XERG_API_KEY`, `~/.xerg/config.json`, or browser credentials from `xerg login`
+- Cursor audits require an explicit exported usage CSV path
 - SSH audits require `ssh` and `rsync` on your local `PATH` and are OpenClaw-only in this phase
 - Railway audits require the `railway` CLI on your local `PATH` and are OpenClaw-only in this phase
 
@@ -100,6 +103,8 @@ Remote OpenClaw audits over SSH, Railway, or `--remote-config` pull selected gat
 
 Hosted sync is opt-in. `connect`, `audit --push`, `push`, and `mcp-setup` use `XERG_API_KEY`, `~/.xerg/config.json`, or browser login credentials only for Xerg Cloud actions. The push payload contains audit totals, daily rollups, findings, recommendations, comparison deltas, and source metadata; it does not include raw prompt or response content, local source file paths, local database paths, or internal finding details.
 
+Local JSON findings may include `signalSource`, `ruleId`, and evidence references. Use those fields to distinguish observed signals from inferred or legacy unknown provenance. These provenance fields are local-only in this release and are not part of the pushed v2 wire payload.
+
 ## Default Flow
 
 1. Start with the default first-run path when you want the fastest local result:
@@ -131,6 +136,7 @@ xerg doctor --railway
 xerg audit
 xerg audit --runtime openclaw
 xerg audit --runtime hermes
+xerg audit --cursor-usage-csv ./cursor-usage.csv
 ```
 
 4. Choose the right output mode for the task:
@@ -183,6 +189,7 @@ xerg audit --runtime openclaw --log-file /path/to/openclaw.log
 xerg audit --runtime openclaw --sessions-dir /path/to/sessions
 xerg audit --runtime hermes --log-file ~/.hermes/logs/agent.log
 xerg audit --runtime hermes --sessions-dir ~/.hermes/sessions
+xerg audit --cursor-usage-csv ./cursor-usage.csv
 ```
 
 SSH remote:
@@ -274,6 +281,8 @@ Current recommendation kinds map into the Action queue buckets:
 
 Prefer high-confidence or reversible fixes first. Treat model downgrades, context changes, and Cursor behavior changes as compare-friendly experiments, not guaranteed savings.
 
+For `--compare`, prefer the normalized rows first: waste rate, waste per run, waste per 1k calls, and inferred waste share when available. Absolute spend and waste deltas are still useful, but they are workload-dependent when run or call volume changed.
+
 ## Checks
 
 Before finalizing work that used Xerg:
@@ -284,11 +293,13 @@ Before finalizing work that used Xerg:
 - If no data was found, run `xerg doctor` or use explicit source flags rather than guessing
 - Say whether results were pushed to the Xerg API
 - Distinguish confirmed waste (`retry-waste`, `loop-waste`) from directional opportunities (`context-outlier`, `idle-spend`, `candidate-downgrade`)
+- Mention inferred or unknown provenance when it materially affects confidence in the finding or compare result
 
 ## Notes
 
 - `--compare` and `--no-db` cannot be used together
 - Xerg is local-first: it stores economic metadata and audit snapshots locally, not prompt or response content
+- Local provenance fields are intentionally not part of the pushed v2 payload yet
 - `XERG_API_KEY` is recommended for CI and non-interactive automation
 - If browser auth is needed without the hosted setup flow, use `xerg login`; remove stored credentials with `xerg logout`
 - Pilot: [xerg.ai/pilot](https://xerg.ai/pilot)