> ## Documentation Index
> Fetch the complete documentation index at: https://xerg.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Changelog

> Release notes for the Xerg CLI, schemas, skill, and hosted workspace.

The Xerg CLI (`@xerg/cli`), the `@xerg/schemas` wire contract, and the bundled Xerg skill ship together on one version. Hosted workspace features deploy continuously and are noted here when they land.

<Update label="v0.13.0" description="July 25, 2026" tags={["CLI", "Schemas", "Hosted", "Skill"]}>
  ## Signup-first activation

  * The primary Free journey now creates a workspace before guiding the user through source selection, secure CLI login, the exact audit command, and a live waiting state for the first push.
  * The onboarding state survives refreshes and sign-ins, records durable activation milestones without CLI telemetry, and includes deliberate snapshot-limit recovery.
  * Secure setup uses `xerg login --replace`, which verifies a new workspace key before atomically replacing any existing stored credential.
  * Activation reporting keeps historical workspace/revenue cohorts intact and excludes signups from 24-hour conversion denominators until their full observation window has elapsed.
  * The homepage now pairs its primary workspace CTA with one terminal-agent setup prompt and a separate no-agent CLI fallback.
  * Xerg's canonical skill supports cold fetches, and both current and legacy well-known discovery formats serve byte-identical skill content with generated integrity metadata.
</Update>

<Update label="v0.12.0" description="July 24, 2026" tags={["CLI", "Hermes", "Local"]}>
  ## Certified Hermes trace enrichment

  * New `xerg collect hermes` command receives traces-only OTLP/HTTP protobuf on loopback for the exact certified `briancaffey/hermes-otel` commit. Xerg prints configuration but never installs or modifies the plugin.
  * Hermes captures require `state.db` and use a persistent owner-only correlation key. Identifiers are HMACed before persistence; a moved capture without its key remains descriptive and cannot split economics.
  * The sanitizer drops prompts, responses, conversation content, invocation parameters, arguments/results, commands, paths, goals, summaries, approval text, skill paths, user IDs, and arbitrary attributes even if upstream privacy settings are wrong.
  * The first-party observer stays primary. Trace evidence can enrich ancestry, approvals, skills, tools, and delegation; observer/trace request conflicts restore the original state aggregate.
  * Certified plugin prompt totals are normalized into uncached input plus separate cache-read/write buckets before reconciliation. Optional observer and trace enrichment stay outside the audit comparison identity, so exact evidence does not change the authoritative audit ID.
  * The collector prints equivalent environment variables for non-default `HERMES_HOME` profiles, where the pinned plugin's fixed `~/.hermes` YAML lookup would otherwise miss profile-local configuration.
  * Audit Push Payload v3, hosted storage, dashboards, MCP, finding kinds, recommendations, and failure gates remain unchanged.
</Update>

<Update label="v0.11.0" description="July 24, 2026" tags={["CLI", "Hermes", "OpenClaw", "Local"]}>
  ## Common local analysis surface

  * Hermes and OpenClaw now share explicit `analysisCoverage`, neutral `toolActivity`, and `workloadEconomics` local blocks with deterministic lineage handling.
  * Complete first-party Hermes observer API evidence can split a `state.db` aggregate only when request count and input/output/cache buckets match exactly. Incomplete, dropped, ambiguous, or conflicting evidence stays aggregate.
  * Authoritative cost is allocated across exact requests without changing request totals, token buckets, spend, cost source, or audit ID. Only reconciled requests enter sequence-dependent detectors.
  * Content-free prompt-size counters, tool-result byte evidence, compression counts, state-only tool inventory, and branch/delegation lineage improve local context and orchestration coverage.
  * When no request sequence is eligible, reports say sequence-dependent monetary findings were not evaluated instead of implying no inefficiency.
</Update>

<Update label="v0.10.0" description="July 22, 2026" tags={["CLI", "OpenClaw", "Local"]}>
  ## Current OpenClaw evidence and isolated trace collection

  * Modern OpenClaw session transcripts now retain ordered tool names, exact execution counts, serialized input/result byte sizes without content, compaction evidence, and root/child lineage with deterministic cycle handling.
  * OpenClaw reports add separate local Tool activity and Workload economics sections. These neutral blocks do not create findings, recommendations, savings claims, waste totals, or CI failures.
  * New `xerg collect openclaw` command receives traces-only OTLP/HTTP protobuf on loopback, sanitizes each request before persistence, and audits the bounded owner-only capture after shutdown. It never changes OpenClaw configuration or pushes automatically.
  * Existing captures can be audited with `--otlp-file`. This source is isolated from transcripts, logs, other runtimes, and remote modes so economics cannot be double counted.
  * The collector enforces 16 MiB request, 256 MiB capture, and 100,000 span limits; hashes correlation IDs before persistence; rejects content attributes; preserves interrupted captures; and never overwrites an output file.
  * Xerg Event Payload v2 adds optional `modelCallId` and `toolCallId` correlation with strict same-payload and same-run validation. Version 1 remains accepted. Audit Push Payload v3 and all hosted schemas remain unchanged.
</Update>

<Update label="v0.9.0" description="July 21, 2026" tags={["CLI", "Hermes", "Local"]}>
  ## Hermes state database and local mechanical analysis

  * Xerg now reads Hermes v0.17 through v0.19 `state.db` directly in query-only mode, including schema 16 session aggregates, schema 20 model usage, and schema 22 task usage. Unknown compatible future columns are ignored.
  * Aggregate request counts now reconcile with Hermes without multiplying aggregate token or cost values, and sequence-dependent monetary detectors ignore observations that cannot support sequence claims.
  * Compression continuations become one logical run while branches and delegated sessions remain separate. Positive actual cost is observed; positive estimated cost is estimated; missing or zero cost is repriced where token data permits.
  * The optional `xergai/hermes-observer` plugin records content-free local tool, terminal, API-error, delegation, and lifecycle mechanics. It never adds economic calls or sends data to Xerg Cloud.
  * Hermes reports can include a separate local Mechanical efficiency section. Only directly observed repeated identical tool inputs and discarded terminal output can become findings; other shapes remain neutral metrics.
  * Mechanical data is excluded from recommendations, audit gates, audit IDs, pushed payloads, hosted storage, and MCP. The public wire contracts remain unchanged.
  * The minimum runtime is Node 22.13.0, the first Node 22 release where `node:sqlite` no longer needs a startup flag.
</Update>

<Update label="v0.8.0" description="July 13, 2026" tags={["CLI", "Schemas", "Hosted"]}>
  ## Free hosted workspaces

  * Xerg now has a Free plan: a hosted workspace for up to 2 members with the last 30 days of pushed audit history, up to 100 stored audit snapshots per month, and workspace API keys. Local audits stay unlimited and account-free.
  * Pro (\$29 per member per month) adds full pushed audit history, unlimited audit pushes, unlimited workspace members, Ask Xerg, hosted MCP, Slack, and optimization policy drafts. Enterprise remains available for SSO/SAML, self-hosted deployment, and custom contracts.
  * The dashboard shows your plan, monthly snapshot usage, and history window, and paid features display an in-place upgrade path instead of redirecting away.
  * After a successful local audit, the CLI occasionally suggests saving audits in a free workspace (at most once per week, never in CI or machine-readable output, and never with telemetry). Successful pushes print a direct dashboard link to the pushed audit.
  * `xerg login` now accepts Free workspace keys, and push errors explain member-limit or snapshot-quota issues precisely.
  * `@xerg/schemas` gains the `WorkspaceEntitlements` wire contract backing the new `GET /v1/entitlements` endpoint.
  * The design partner program has closed; see the pricing page for current plans.
</Update>

<Update label="v0.7.0" description="July 11, 2026" tags={["CLI", "Schemas", "Hosted"]}>
  ## Silent-source visibility and a canonical finding-kind registry

  * Audits now tell you when a detected source file contributes nothing: a count-only note appears whenever OpenClaw, Hermes, or Claude Code files produce no included calls in the audit window, instead of those files silently vanishing from the report.
  * `xerg doctor --verbose` lists those zero-call files with their full local paths so you can inspect them. Paths stay local and never cross the push wire.
  * Markdown reports from `xerg audit --markdown` now include the Notes section that was previously terminal-only.
  * `@xerg/schemas` gains a canonical finding-kind registry (`FINDING_KINDS`, `FINDING_KIND_META`, and lookup helpers) as the single source for finding labels, categories, and implementation surfaces.
  * Terminal and markdown taxonomy output now labels cache carryover and max mode concentration findings instead of showing raw kind identifiers.
  * Hosted workspace: pushes create and recur Optimization backlog items again (wire v3 payloads were stored but skipped backlog upserts between July 6 and July 11), and provisional backlog items now persist real category and surface data for every finding kind.
</Update>

<Update label="v0.6.0" description="July 7, 2026" tags={["CLI", "Schemas"]}>
  ## Cost per outcome and richer call economics

  * New `xerg outcome` command: declare a success or failure outcome for a run or workflow. Declarations are stored locally, apply to future audits, override derived outcomes, and unlock cost-per-outcome reporting.
  * Every normalized call now carries first-class economics fields across all sources: cache and reasoning tokens, stop reasons, tool names, and outcomes.
  * Unified date-aware pricing engine with a much larger model catalog, replacing per-source pricing tables.
  * Session-native waste detection: transcript-inferred retries, tool loops, context growth, cache thrash, and cadence-based idle spend.
  * Push wire payload v3 adds token-economics and outcome rollups. Framework event payload v2 for `xerg ingest`.
  * `xerg doctor --verbose` now reports field-extraction coverage per source, so you can see how much economic detail each source provides.
</Update>

<Update label="v0.5.8" description="July 6, 2026" tags={["CLI"]}>
  ## OpenClaw transcript parsing fixes

  * Parse the modern OpenClaw session transcript format, including normalized `message.usage` token fields.
  * Calls that report a cost of zero (common on subscription or OAuth billing) are now treated as unobserved and priced by estimation instead of being counted as free.
  * Added newer Anthropic models to the pricing catalog.
  * Trajectory support bundles are excluded from detection to avoid double counting.
  * `xerg init` reports cloud-setup failures as cloud-setup failures, noting that the local audit succeeded and is cached.
</Update>

<Update label="v0.5.7" description="July 6, 2026" tags={["CLI", "Skill", "Hosted"]}>
  ## Claude Code, ingest for any framework, and per-agent spend

  * Claude Code is now a first-class local source: Xerg audits session transcripts from `~/.claude/projects/`, with `init` and `doctor` support.
  * New `xerg ingest --file <payload.json>` command audits any framework through a versioned JSON event payload.
  * Per-agent spend attribution, including delegated sub-agent spend, in the CLI audit output, the hosted dashboard, and Ask Xerg.
  * Content-addressed audit IDs make pushes idempotent; re-pushing the same audit no longer creates duplicates.
  * The Xerg skill is now installable with `npx skills add xergai/skills`.
  * Turnkey first run: a friendly Node version guard at startup, a non-blocking update notice when a newer CLI is published, Node 26 support, and `@latest`-pinned install commands everywhere.
</Update>

<Update label="Hosted workspace" description="June 29, 2026" tags={["Hosted"]}>
  ## Slack integration

  Pro workspaces can connect Slack from dashboard Settings: pick a channel, receive Optimizations and audit notifications, send a test message, and mute or disconnect at any time.
</Update>

<Update label="v0.5.5 and v0.5.6" description="June 21 and 26, 2026" tags={["CLI"]}>
  ## Synced release train

  * The CLI, schemas, and skill now publish on one synced version with automated drift checks.
  * Refreshed npm, docs, and skill listing content.
</Update>

<Update label="v0.5.2 and v0.5.3" description="June 20, 2026" tags={["CLI"]}>
  ## Accuracy hardening and a lighter install

  * Provenance-aware findings, more conservative retry and loop waste detection, and normalized compare output.
  * Removed the native SQLite dependency: local compare snapshots are stored as JSON, installs no longer need a native build step, and prompt dependencies were narrowed to what Xerg actually uses.
  * Clearer Cursor and runtime waste taxonomy documentation.
</Update>

<Update label="v0.5.1" description="April 28, 2026" tags={["Skill"]}>
  ## Skill runtime metadata

  * Declared the Xerg skill runtime metadata used by registry security scans.
  * Documented the local, remote, and hosted data-flow boundaries.
</Update>

<Update label="v0.5.0" description="April 18, 2026" tags={["CLI", "Schemas", "Hosted"]}>
  ## Action queue and recommendation contract v2

  * Recommendation payload upgraded to v2: ranked recommendations with stable IDs and structured scope labels, included on the push wire format.
  * The terminal audit output now ends with an Action queue summary of top `fix_now`, `test_next`, and `watch` items.
  * The same v2 recommendations power the hosted Optimizations backlog.
</Update>

<Update label="v0.4.0" description="April 13, 2026" tags={["CLI"]}>
  ## Init-first onboarding

  * New `xerg init` interactive first run: detects local sources, runs the first audit, caches a snapshot, and offers hosted follow-up.
  * New `xerg connect` and `xerg mcp-setup` commands with shared auth resolution across local and hosted flows.
  * Refreshed docs and skill messaging around free local audits with optional hosted setup.
</Update>

<Update label="v0.3.0" description="April 11, 2026" tags={["CLI"]}>
  ## Hermes support

  * Hermes is now a first-class local runtime alongside OpenClaw, with `--runtime` selection and local auto-detection.
  * Runtime-aware compare and push labels, updated skill content, and refreshed docs.
</Update>

<Update label="v0.2.0" description="April 9, 2026" tags={["CLI", "Schemas"]}>
  ## Daily spend and waste series

  Audit output and pushed payloads now include daily spend and waste series, expanding the dashboard-ready rollups without changing the hosted API contract version.
</Update>

<Update label="v0.1.9 and v0.1.10" description="April 2026" tags={["CLI"]}>
  ## Diagnostics improvements

  * `--verbose` progress output for `doctor` and `audit`.
  * No-data guidance now points to explicit local paths plus SSH and Railway inspection flows.
  * Better Railway diagnostics and package-runner hints, so `npx` and `pnpm dlx` installs see the right follow-up commands.
</Update>

<Update label="v0.1.6 to v0.1.8" description="March 30 to 31, 2026" tags={["CLI", "Skill"]}>
  ## Bundled agent skill

  * The Xerg agent skill ships inside the npm package and is published to ClawHub with each CLI release.
  * Supported Node runtime is 22 or newer.
</Update>

<Update label="v0.1.5" description="March 28, 2026" tags={["CLI", "Schemas"]}>
  ## Remote audits, push, and CI gates

  * Remote OpenClaw audits over SSH and Railway: telemetry is pulled to your machine and analyzed locally.
  * Public `@xerg/schemas` package: the MIT-licensed wire contract for pushed payloads.
  * `xerg login`, `xerg logout`, and standalone `xerg push` for explicit hosted sync.
  * Ranked recommendations in audit output.
  * CI threshold flags with dedicated exit codes, including exit code 2 for no-data errors.
</Update>

<Update label="v0.1.0 to v0.1.4" description="March 2026" tags={["CLI"]}>
  ## Initial public beta

  * Local OpenClaw audits in dollars: spend rollups and waste findings from gateway logs and session transcripts.
  * `xerg audit --compare` for before and after reporting against the previous snapshot.
  * `xerg doctor` source diagnostics.
  * Supply-chain hardening for the published package.
</Update>