@xerg/cli 0.5.3 → 0.5.5

package/README.md

@@ -1,6 +1,8 @@
 # xerg
 
-Audit OpenClaw, Hermes, and Cursor spend in dollars, surface provenance-aware waste findings, compare fixes, and optionally connect hosted follow-up after the first local result.
+Find wasted AI spend in OpenClaw, Hermes, and Cursor.
+
+Xerg audits AI spend in dollars, surfaces provenance-aware waste findings, compares fixes, and optionally connects hosted follow-up after the first local result.
 
 Xerg runs locally by default. Local audits and `--compare` are free. No account is required for local value, and no data leaves your machine unless you explicitly push results to Xerg Cloud.
 
@@ -57,7 +59,7 @@ node_modules/@xerg/cli/skills/xerg/SKILL.md
 
 For a global install, the same file lives inside the global npm package directory instead. That file is a packaged copy of the canonical repo skill at [`skills/xerg/SKILL.md`](../../skills/xerg/SKILL.md). Use it if your agent platform imports skills from disk; installing the npm package does not automatically register the skill with every agent product.
 
-The bundled skill frontmatter declares the CLI/package surface plus optional Xerg Cloud, SSH, rsync, and Railway requirements so registries can distinguish the default local audit workflow from opt-in hosted sync and remote audit workflows.
+The bundled skill frontmatter declares the CLI/package surface plus optional Xerg Cloud and remote audit requirements so registries can distinguish the default local audit workflow from opt-in hosted sync and remote audit workflows.
 
 ## Supported runtime
 
@@ -118,7 +120,7 @@ xerg push
 Remote prerequisites:
 
 - SSH audits require `ssh` and `rsync` on your `PATH`
-- Railway audits require the `railway` CLI on your `PATH`
+- Optional legacy Railway audits require the `railway` CLI on your `PATH`
 
 ## Default paths
 
@@ -145,7 +147,6 @@ If local defaults are empty, `xerg init` prints next-step commands for explicit
 
 ```bash
 xerg audit --remote user@host
-xerg audit --railway
 ```
 
 ## Hosted follow-up
@@ -218,7 +219,7 @@ Xerg v0 stores economic metadata and audit summaries locally. It does not store
 - `xerg init` is interactive in v1. Use direct `doctor` / `audit` commands when you need non-interactive control.
 - `--verbose` prints progress updates to stderr for `xerg doctor` and `xerg audit`, which helps distinguish package install time from CLI runtime.
 - If `xerg audit --remote ...` fails before pulling files, verify that both `ssh` and `rsync` are installed and reachable on your `PATH`.
-- If `xerg audit --railway` fails immediately, verify that the `railway` CLI is installed, authenticated, and can access the target project.
+- If a legacy Railway audit fails immediately, verify that the `railway` CLI is installed, authenticated, and can access the target project.
 
 ## Pilot and support
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@xerg/cli",
-  "version": "0.5.3",
-  "description": "Audit OpenClaw, Hermes, and Cursor spend in dollars with provenance-aware waste findings and compare output.",
+  "version": "0.5.5",
+  "description": "Find wasted AI spend in OpenClaw, Hermes, and Cursor.",
   "keywords": [
     "xerg",
     "ai",

package/skills/xerg/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: xerg
-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.
+description: Find wasted AI spend in OpenClaw, Hermes, and Cursor.
 homepage: https://xerg.ai
 metadata:
   openclaw:
@@ -46,13 +46,7 @@ metadata:
 
 # Xerg
 
-Use `xerg` if it is already installed. If not, use `npx @xerg/cli` with the same arguments.
-
-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.
+Xerg is a local-first CLI for finding wasted AI spend in OpenClaw, Hermes, and Cursor. It audits dollars instead of raw token counts, separates confirmed waste from savings opportunities, and uses `--compare` to measure whether a workflow or model change actually helped.
 
 ## Quick Start
 
@@ -61,246 +55,29 @@ xerg init
 xerg audit --compare
 ```
 
-Use direct commands when you need explicit control, non-interactive behavior, JSON output, or CI gates:
-
-```bash
-xerg doctor
-xerg audit
-xerg audit --cursor-usage-csv ./cursor-usage.csv
-xerg audit --json
-xerg audit --fail-above-waste-rate 0.30
-```
-
-## Inputs
-
-Xerg needs one of these source inputs:
-
-- Local OpenClaw data at the default paths:
-  - `/tmp/openclaw/openclaw-*.log`
-  - `~/.openclaw/agents/*/sessions/*.jsonl`
-- 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`
-- A multi-source config via `--remote-config`
-
-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 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 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
-
-1. Start with the default first-run path when you want the fastest local result:
-
-```bash
-xerg init
-```
-
-- `init` detects local OpenClaw or Hermes data
-- it runs a first audit with local snapshot persistence enabled
-- it offers optional hosted follow-up after the audit completes
-- if no local data is found, it prints explicit local-path commands plus remote OpenClaw-only guidance
-
-2. Detect sources directly when paths or connectivity are uncertain:
-
-```bash
-xerg doctor
-xerg doctor --verbose
-xerg doctor --remote user@host
-xerg doctor --railway
-```
-
-- `xerg doctor --verbose` shows progress on stderr while Xerg checks local paths or remote transports
-- If local defaults are empty, prefer `xerg doctor --remote ...` or `xerg doctor --railway` instead of guessing paths
-
-3. Run a baseline audit explicitly when you want direct control:
-
-```bash
-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:
-
-```bash
-xerg audit
-xerg audit --json
-xerg audit --markdown
-```
-
-- Plain `xerg audit` is best for a human-readable summary
-- `xerg audit --json` is best for automation and agents
-- `xerg audit --markdown` is best for a shareable report
-
-5. After a workflow or model change, measure the delta:
-
-```bash
-xerg audit --compare
-xerg audit --compare --json
-```
-
-6. Export, push, or hosted-setup only when needed:
-
-```bash
-xerg audit --markdown > xerg-audit.md
-xerg connect
-xerg mcp-setup
-xerg audit --push
-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, Codex, or another client
-- local audits and compare remain available if you skip hosted setup
-
-## Source Selection
-
-Local defaults:
-
-```bash
-xerg audit
-```
-
-If both OpenClaw and Hermes are present locally, pass `--runtime openclaw` or `--runtime hermes` explicitly.
-
-Explicit local paths:
-
-```bash
-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:
-
-```bash
-xerg audit --remote user@vps.example.com
-xerg audit --remote user@vps.example.com \
-  --remote-log-file /opt/openclaw/logs/openclaw.log \
-  --remote-sessions-dir /opt/openclaw/sessions
-```
-
-Railway:
-
-```bash
-xerg audit --railway
-xerg audit --railway --project <id> --environment <id> --service <id>
-```
-
-Multiple remote sources:
-
-```bash
-xerg audit --remote-config ~/.xerg/remotes.json
-```
-
-Remote config files use this shape:
-
-```json
-{
-  "remotes": [
-    {
-      "name": "prod",
-      "transport": "ssh",
-      "host": "deploy@prod.example.com"
-    },
-    {
-      "name": "railway-prod",
-      "transport": "railway",
-      "railway": {
-        "projectId": "...",
-        "environmentId": "...",
-        "serviceId": "..."
-      }
-    }
-  ]
-}
-```
-
-## CI And Automation
-
-For CI gates, prefer a single command so the audit can still be pushed before threshold failure:
-
-```bash
-xerg audit --push --fail-above-waste-rate 0.25 --fail-above-waste-usd 100
-```
-
-Common variants:
-
-```bash
-xerg audit --fail-above-waste-rate 0.30
-xerg audit --fail-above-waste-usd 50
-xerg audit --since 24h --fail-above-waste-rate 0.30
-```
-
-Documented exit codes:
-
-- `0` success
-- `1` runtime error
-- `2` no supported local runtime data found
-- `3` threshold exceeded
-
-Automation can branch on those codes instead of scraping terminal output.
-
-## Recommendations
-
-When using `--json`, expect a `recommendations` array alongside the audit summary. Each recommendation item includes:
-
-- `id`, `findingId`, `kind`, `title`, `summary`
-- `priorityBucket`, `recommendedOrder`, `implementationSurface`, `category`
-- `severity`, `confidence`, `effort`
-- `estimatedSavingsUsd`, `estimatedSavingsPct`
-- `scope`, `scopeId`, `scopeLabel`
-- `whereToChange`, `validationPlan`, `actions`
-
-Current recommendation kinds map into the Action queue buckets:
+If `xerg` is not installed, use `npx @xerg/cli` with the same arguments.
 
-- `fix_now`: `retry-waste`, `loop-waste`
-- `test_next`: `context-outlier`, `idle-spend`, `candidate-downgrade`, `cache-carryover`, `max-mode-concentration`
-- `watch`: unknown or uncategorized findings
+## What It Audits
 
-Prefer high-confidence or reversible fixes first. Treat model downgrades, context changes, and Cursor behavior changes as compare-friendly experiments, not guaranteed savings.
+- OpenClaw gateway logs and session transcripts
+- Hermes logs and session transcripts
+- Cursor usage CSV exports via `xerg audit --cursor-usage-csv ./cursor-usage.csv`
 
-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.
+## What It Finds
 
-## Checks
+- Retry waste from failed calls before a later success
+- Loop waste from runs that exceed efficient iteration bounds
+- Context bloat from unusually large inputs
+- Downgrade candidates where cheaper models may be enough
+- Idle spend from recurring heartbeat or monitoring loops
 
-Before finalizing work that used Xerg:
+## Optional Cloud
 
-- Say whether the audit was local, SSH, Railway, or multi-source
-- Say whether the output was plain terminal text, JSON, or Markdown
-- If `--compare` was used, confirm that it compared against a compatible stored snapshot
-- 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
+Local audits need no account. Hosted sync and hosted MCP are optional workspace features and only run when you explicitly use `xerg connect`, `xerg audit --push`, `xerg push`, or `xerg mcp-setup`.
 
-## Notes
+## Links
 
-- `--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)
+- Docs: [xerg.ai/docs](https://xerg.ai/docs)
+- GitHub: [xergai/xerg](https://github.com/xergai/xerg)
+- npm: [@xerg/cli](https://www.npmjs.com/package/@xerg/cli)
 - Support: `query@xerg.ai`