@xerg/cli 0.4.0 → 0.5.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xerg/cli",
-  "version": "0.4.0",
+  "version": "0.5.1",
   "description": "Audit OpenClaw and Hermes workflows in dollars, compare fixes, and export daily spend and waste trends.",
   "keywords": [
     "xerg",

package/skills/xerg/SKILL.md

@@ -1,6 +1,47 @@
 ---
 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.
+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
@@ -11,6 +52,8 @@ Xerg audits OpenClaw and Hermes workflows in dollars, not tokens. It reads gatew
 
 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
@@ -49,6 +92,14 @@ Additional requirements:
 - 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.
+
 ## Default Flow
 
 1. Start with the default first-run path when you want the fastest local result:
@@ -112,7 +163,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
@@ -206,18 +257,22 @@ Automation can branch on those codes instead of scraping terminal output.
 
 ## Recommendations
 
-When using `--json`, expect a `recommendations` array alongside the audit summary. Recommendation items include:
+When using `--json`, expect a `recommendations` array alongside the audit summary. Each recommendation item includes:
 
-- `id`, `findingId`, `kind`, `title`, `description`
-- `estimatedSavingsUsd`, `confidence`, `actionType`
-- optional `suggestedChange`
+- `id`, `findingId`, `kind`, `title`, `summary`
+- `priorityBucket`, `recommendedOrder`, `implementationSurface`, `category`
+- `severity`, `confidence`, `effort`
+- `estimatedSavingsUsd`, `estimatedSavingsPct`
+- `scope`, `scopeId`, `scopeLabel`
+- `whereToChange`, `validationPlan`, `actions`
 
-Current recommendation kinds fall into two buckets:
+Current recommendation kinds map into the Action queue buckets:
 
-- Confirmed waste: `retry-waste`, `loop-waste`
-- Savings opportunities or directional findings: `context-outlier`, `idle-spend`, `candidate-downgrade`
+- `fix_now`: `retry-waste`, `loop-waste`
+- `test_next`: `context-outlier`, `idle-spend`, `candidate-downgrade`, `cache-carryover`, `max-mode-concentration`
+- `watch`: unknown or uncategorized findings
 
-Prefer reversible or high-confidence fixes first. Treat model downgrades and context reductions as A/B-test candidates, not guaranteed savings.
+Prefer high-confidence or reversible fixes first. Treat model downgrades, context changes, and Cursor behavior changes as compare-friendly experiments, not guaranteed savings.
 
 ## Checks