@xerg/cli 0.5.0 → 0.5.2

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@xerg/cli",
-  "version": "0.5.0",
-  "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,16 +1,59 @@
 ---
 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:
+    homepage: https://xerg.ai
+    links:
+      repository: https://github.com/xergai/xerg
+      documentation: https://xerg.ai/docs
+    primaryEnv: XERG_API_KEY
+    requires:
+      anyBins:
+        - xerg
+        - npx
+      config:
+        - ~/.xerg/config.json
+        - ~/.config/xerg/credentials.json
+        - ~/.xerg/remotes.json
+    install:
+      - kind: node
+        package: "@xerg/cli"
+        bins:
+          - xerg
+    envVars:
+      - name: XERG_API_KEY
+        required: false
+        description: Optional Xerg Cloud workspace API key for explicit push, connect, and hosted MCP setup.
+      - name: XERG_API_URL
+        required: false
+        description: Optional override for the Xerg API endpoint; defaults to https://api.xerg.ai.
+    dependencies:
+      - name: "@xerg/cli"
+        type: npm
+        repository: https://github.com/xergai/xerg
+      - name: ssh
+        type: other
+        url: https://www.openssh.com/
+      - name: rsync
+        type: other
+        url: https://rsync.samba.org/
+      - name: railway
+        type: npm
+        repository: https://github.com/railwayapp/cli
 ---
 
 # Xerg
 
 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.
 
+The initial `npx @xerg/cli` path fetches and executes the published npm package. To avoid that runtime fetch, install and review the CLI first with `npm install -g @xerg/cli`, or use a locally built `xerg` binary.
+
 ## Quick Start
 
 ```bash
@@ -23,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
 ```
@@ -37,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`
@@ -46,9 +91,20 @@ 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.
+
+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.
+
+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:
@@ -80,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:
@@ -112,7 +169,7 @@ xerg push
 ```
 
 - `connect` is the guided hosted path: it reuses existing auth, prompts before browser login when needed, and offers to push the latest audit
-- `mcp-setup` prints or writes hosted MCP config for Cursor, Claude Code, or another client
+- `mcp-setup` prints or writes hosted MCP config for Cursor, Claude Code, Codex, or another client
 - local audits and compare remain available if you skip hosted setup
 
 ## Source Selection
@@ -132,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:
@@ -223,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:
@@ -233,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)