Fix Xerg ClawHub metadata

docs/how-it-works.mdx

@@ -59,7 +59,7 @@ This wire payload is intentionally narrower than the local summary:
 - it omits local file paths
 - it omits local database path details
 - it omits internal finding `details`
-- it does not include the recommendation array
+- it includes ranked recommendations without raw prompt or response content
 
 ## Privacy boundaries
 
@@ -70,5 +70,6 @@ The docs and codebase currently support these claims:
 - Xerg stores local economic metadata and audit summaries
 - the push payload excludes local file paths and internal debug-style fields
 - prompt and response content are not part of the push wire schema
+- hosted sync only happens through explicit `connect`, `audit --push`, `push`, or `mcp-setup` commands
 
 For the exact local summary and wire payload shapes, see [json output](/json-output).

docs/skill-bundle.mdx

@@ -38,6 +38,17 @@ The skill describes how an agent should use Xerg well:
 - how to interpret confirmed waste versus directional opportunities
 - what to verify before finishing an audit task
 
+## Registry metadata
+
+The skill frontmatter declares the runtime surface that ClawHub and agent registries need to understand:
+
+- `xerg` or `npx` as the CLI entry point
+- `@xerg/cli` as the npm package source
+- optional Xerg Cloud credentials and config paths for explicit hosted commands
+- optional SSH, rsync, and Railway dependencies for remote OpenClaw audits
+
+These declarations are intentionally broader than the default local audit path because the same skill also documents opt-in hosted sync and remote audit workflows.
+
 ## Important caveat
 
 Installing `@xerg/cli` does not automatically register the bundled skill with every agent product. Some tools can import skills from disk directly. Others need you to copy or link the skill into that product's own skill directory or use its import flow.

packages/cli/CHANGELOG.md

@@ -1,5 +1,11 @@
 # @xerg/cli
 
+## 0.5.1
+
+### Patch Changes
+
+- Declare the Xerg skill runtime metadata for ClawHub security scans and document the local, remote, and hosted data-flow boundaries.
+
 ## 0.5.0
 
 ### Minor Changes

packages/cli/README.md

@@ -4,6 +4,8 @@ Audit OpenClaw and Hermes workflows in dollars, compare fixes, and optionally co
 
 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.
 
+The `npx @xerg/cli` path fetches and executes the published npm package before running Xerg. If you want to avoid a runtime fetch, install once with `npm install -g @xerg/cli` or run a local build from source.
+
 ## Fastest first run
 
 ```bash
@@ -54,6 +56,8 @@ 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.
+
 ## Supported runtime
 
 `@xerg/cli` supports Node `22` and `24`.

packages/cli/package.json

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

packages/core/tests/wire.test.ts

@@ -73,6 +73,28 @@ describe('toWirePayload', () => {
     expect(summaryObj).not.toHaveProperty('since');
   });
 
+  it('keeps raw prompts, responses, and local-only details out of the push payload', async () => {
+    const summary = await auditOpenClaw({ logFile: gatewayLog, noDb: true });
+    const rawPrompt = 'customer-secret-prompt-do-not-push';
+    const rawResponse = 'customer-secret-response-do-not-push';
+    const localDbPath = '/tmp/xerg-private.sqlite';
+
+    expect(summary.findings.length).toBeGreaterThan(0);
+    summary.dbPath = localDbPath;
+    summary.findings[0].details = {
+      prompt: rawPrompt,
+      response: rawResponse,
+      sourceFile: gatewayLog,
+    };
+
+    const payloadJson = JSON.stringify(toWirePayload(summary, testMeta));
+
+    expect(payloadJson).not.toContain(rawPrompt);
+    expect(payloadJson).not.toContain(rawResponse);
+    expect(payloadJson).not.toContain(gatewayLog);
+    expect(payloadJson).not.toContain(localDbPath);
+  });
+
   it('keeps cursor-only local fields out of the push payload', async () => {
     const summary = await auditCursorUsageCsv({ cursorUsageCsv, noDb: true });
     const payload = toWirePayload(summary, testMeta);

scripts/smoke-cli-package.mjs

@@ -114,6 +114,39 @@ try {
     throw new Error('Bundled Xerg skill did not contain expected frontmatter.');
   }
 
+  const expectedSkillMetadata = [
+    'metadata:',
+    'openclaw:',
+    'primaryEnv: XERG_API_KEY',
+    'anyBins:',
+    '- xerg',
+    '- npx',
+    'package: "@xerg/cli"',
+    '- ~/.xerg/config.json',
+    '- ~/.config/xerg/credentials.json',
+    'name: XERG_API_KEY',
+    'required: false',
+  ];
+
+  for (const snippet of expectedSkillMetadata) {
+    if (!bundledSkill.includes(snippet)) {
+      throw new Error(`Bundled Xerg skill is missing expected ClawHub metadata: ${snippet}`);
+    }
+  }
+
+  const installedPackageJson = JSON.parse(
+    readFileSync(join(installDir, 'node_modules', '@xerg', 'cli', 'package.json'), 'utf8'),
+  );
+  const installLifecycleScripts = ['preinstall', 'install', 'postinstall'].filter(
+    (scriptName) => installedPackageJson?.scripts?.[scriptName],
+  );
+
+  if (installLifecycleScripts.length > 0) {
+    throw new Error(
+      `Installed package unexpectedly declares install lifecycle scripts: ${installLifecycleScripts.join(', ')}`,
+    );
+  }
+
   process.stdout.write('CLI package smoke test passed.\n');
 } finally {
   rmSync(tempRoot, { recursive: true, force: true });

skills/xerg/README.md

@@ -4,6 +4,8 @@ Xerg audits OpenClaw and Hermes workflows in dollars, not tokens. It reads gatew
 
 Everything runs locally by default. The CLI is open source (MIT), published on npm as `@xerg/cli`, and the full source is at [github.com/xergai/xerg](https://github.com/xergai/xerg). No account is required for local audits. Hosted sync and hosted MCP are optional paid workspace features.
 
+The `npx @xerg/cli` path fetches and executes the published npm package before running Xerg. If you want to review the code first and avoid that fetch on each use, install the CLI globally with `npm install -g @xerg/cli` or run a local build.
+
 ## Install
 
 ```bash
@@ -59,6 +61,13 @@ xerg mcp-setup
 - `mcp-setup` prints or writes hosted MCP config for supported clients
 - local audits and compare remain available if you skip hosted setup
 
+## Security And Data Flow
+
+- Local audits read OpenClaw, Hermes, or Cursor usage files and may write local SQLite snapshots for `--compare`.
+- SSH, Railway, and `--remote-config` audits pull selected OpenClaw files to local temporary storage before analysis.
+- Xerg Cloud sync only happens when you run `connect`, `audit --push`, `push`, or `mcp-setup`.
+- Push payloads include audit totals, rollups, findings, recommendations, comparison deltas, and source metadata. They exclude raw prompt and response content, local source file paths, local database paths, and internal finding details.
+
 ## CI And Automation
 
 ```bash

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: