@xerg/cli 0.5.1 → 0.5.3

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.3",
+  "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": {
@@ -36,8 +37,11 @@
   },
   "files": ["dist", "README.md", "LICENSE", "skills"],
   "main": "./dist/index.js",
+  "browser": "./dist/browser.js",
   "exports": {
     ".": {
+      "browser": "./dist/browser.js",
+      "node": "./dist/index.js",
       "default": "./dist/index.js"
     }
   },
@@ -52,8 +56,8 @@
     "typecheck": "tsc --noEmit -p tsconfig.json"
   },
   "dependencies": {
-    "@inquirer/prompts": "^8.4.1",
-    "better-sqlite3": "^11.10.0"
+    "@inquirer/confirm": "^6.1.1",
+    "@inquirer/select": "^5.2.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,16 +91,19 @@ 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
 
 ## Security And Data Flow
 
-Default `doctor`, `init`, `audit`, `--compare`, `--json`, and `--markdown` commands analyze data on the local machine. They read OpenClaw, Hermes, or Cursor usage files, compute economic summaries, print reports, and may write local SQLite snapshots for future comparison.
+Default `doctor`, `init`, `audit`, `--compare`, `--json`, and `--markdown` commands analyze data on the local machine. They read OpenClaw, Hermes, or Cursor usage files, compute economic summaries, print reports, and may write local JSON snapshots for future comparison.
 
 Remote OpenClaw audits over SSH, Railway, or `--remote-config` pull selected gateway logs and session files to local temporary storage, then run the same local audit engine. These flows require the corresponding remote transport credentials already configured on the machine.
 
-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.
+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 snapshot store 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
 
@@ -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)