feat: publish versioned capability contract

README.md

@@ -9,7 +9,7 @@
 
 ClawFix scans locally, redacts recognized secrets, and matches failures against deterministic rules. Optional AI analysis can explain unmatched problems when it is configured on the selected server. Model output never becomes executable shell.
 
-[Quick start](#quick-start) · [How it works](#how-it-works) · [Security](#security--transparency) · [Self-hosting](#self-hosting) · [Contributing](#contributing)
+[Quick start](#quick-start) · [How it works](#how-it-works) · [Security](#security--transparency) · [Versioned capability contract](docs/capabilities/v0.11.2.md) · [Self-hosting](#self-hosting) · [Contributing](#contributing)
 
 ## Quick Start
 

docs/capabilities/evidence.json

@@ -0,0 +1,43 @@
+{
+  "asOf": "2026-07-27",
+  "release": {
+    "tag": "v0.11.2",
+    "publishedAt": "2026-07-24T06:22:17Z",
+    "source": "https://api.github.com/repos/arcabotai/clawfix/releases/tags/v0.11.2",
+    "assets": [
+      "clawfix-tui-linux-x64-baseline.tar.gz",
+      "clawfix-tui-linux-x64.tar.gz",
+      "TUI-SHA256SUMS"
+    ]
+  },
+  "platforms": {
+    "portableCli": [
+      "macOS",
+      "Linux",
+      "WSL"
+    ],
+    "standaloneTui": [
+      "Linux x64",
+      "Linux x64 baseline"
+    ]
+  },
+  "validation": {
+    "supportedOpenClawVersions": [],
+    "supportStatement": "No broad OpenClaw compatibility range has been validated or asserted.",
+    "testedOpenClawVersions": [
+      {
+        "version": "2026.6.11",
+        "scope": "Real-machine diagnostic and guarded-repair scenarios in the Blaxel lab.",
+        "source": "REVIEW.md"
+      }
+    ]
+  },
+  "outcomes": {
+    "source": "https://clawfix.dev/api/stats",
+    "observedAt": "2026-07-27",
+    "totalDiagnoses": 205,
+    "recordedSuccesses": 5,
+    "unknown": 200,
+    "interpretation": "Unknown outcomes are missing follow-up, not failures. This snapshot does not establish a repair success rate."
+  }
+}

docs/capabilities/v0.11.2.json

@@ -0,0 +1,175 @@
+{
+  "schemaVersion": 1,
+  "generatedFrom": {
+    "packageMetadata": [
+      "package.json",
+      "cli/package.json"
+    ],
+    "detectorCatalog": "src/known-issues.js",
+    "repairCatalog": "cli/core/repair-catalog.js",
+    "evidenceSnapshot": "docs/capabilities/evidence.json"
+  },
+  "evidenceAsOf": "2026-07-27",
+  "release": {
+    "version": "0.11.2",
+    "tag": "v0.11.2",
+    "publishedAt": "2026-07-24T06:22:17Z",
+    "package": "clawfix",
+    "nodeEngine": ">=22.0.0",
+    "releaseMetadataSource": "https://api.github.com/repos/arcabotai/clawfix/releases/tags/v0.11.2",
+    "releaseAssets": [
+      "clawfix-tui-linux-x64-baseline.tar.gz",
+      "clawfix-tui-linux-x64.tar.gz",
+      "TUI-SHA256SUMS"
+    ]
+  },
+  "interfaces": {
+    "installer": {
+      "preparation": [
+        "Download https://clawfix.dev/install to install-clawfix.sh.",
+        "Inspect the script and compare its SHA-256 with https://clawfix.dev/install/sha256.",
+        "Run bash install-clawfix.sh."
+      ],
+      "run": "clawfix",
+      "delivers": "Portable plain readline CLI installed under ~/.clawfix with a ~/.local/bin/clawfix launcher.",
+      "platforms": [
+        "macOS",
+        "Linux",
+        "WSL"
+      ]
+    },
+    "npx": {
+      "run": "npx clawfix@0.11.2",
+      "delivers": "Portable plain readline CLI.",
+      "platforms": [
+        "macOS",
+        "Linux",
+        "WSL"
+      ]
+    },
+    "standaloneTui": {
+      "bundledWithNpm": false,
+      "delivers": "Separate chat-first OpenTUI release asset.",
+      "platforms": [
+        "Linux x64",
+        "Linux x64 baseline"
+      ],
+      "assets": [
+        "clawfix-tui-linux-x64-baseline.tar.gz",
+        "clawfix-tui-linux-x64.tar.gz"
+      ]
+    }
+  },
+  "detectors": {
+    "deterministicCount": 49,
+    "ids": [
+      "auto-update-enabled-warning",
+      "auto-update-restart-loop",
+      "browser-port-binding",
+      "browser-relay-handshake-spam",
+      "browser-relay-not-listening",
+      "browser-relay-outdated",
+      "browser-relay-wrong-port",
+      "codex-service-tier-not-fast",
+      "codex-session-store-permission",
+      "codex-shell-home-mismatch",
+      "config-reload-sigterm-cascade",
+      "context-overflow",
+      "discord-allowlist-empty",
+      "duplicate-plugin",
+      "filevault-blocks-reboot",
+      "gateway-extended-downtime",
+      "gateway-not-listening",
+      "gateway-not-running",
+      "gateway-watchdog-missing",
+      "gateway-zombie",
+      "ggml-metal-crash",
+      "heartbeat-no-model-override",
+      "high-token-usage",
+      "invalid-gh-token-override",
+      "large-workspace-files",
+      "launchd-corrupted-state",
+      "macos-app-metadata-upgrade",
+      "matrix-sync-timeout-spam",
+      "mem0-graph-free",
+      "missing-agents-md",
+      "native-codex-timeout-boundary",
+      "no-compaction-config",
+      "no-context-pruning",
+      "no-hybrid-search",
+      "no-memory-files",
+      "no-memory-flush",
+      "no-soul",
+      "openclaw-node-engine-mismatch",
+      "orphan-tool-calls",
+      "oversized-error-log",
+      "pi-backed-openai-codex-route",
+      "plaintext-secrets-in-config",
+      "port-conflict",
+      "provider-prefix-unregistered",
+      "session-transcript-not-indexed",
+      "stale-bundled-plugin-load-paths",
+      "stale-plist-env-secrets",
+      "stale-self-paired-node",
+      "state-dir-migration"
+    ]
+  },
+  "executableRepairs": {
+    "count": 5,
+    "items": [
+      {
+        "id": "auto-update-enabled-warning",
+        "title": "Disable OpenClaw auto-update",
+        "risk": "low"
+      },
+      {
+        "id": "gateway-loopback-no-auth",
+        "title": "Require a token on the gateway",
+        "risk": "medium"
+      },
+      {
+        "id": "gateway-not-running",
+        "title": "Restart the OpenClaw gateway",
+        "risk": "low"
+      },
+      {
+        "id": "no-hybrid-search",
+        "title": "Enable hybrid memory search",
+        "risk": "low"
+      },
+      {
+        "id": "no-memory-flush",
+        "title": "Enable memory flush on compaction",
+        "risk": "low"
+      }
+    ],
+    "safetyBoundary": "Repairs are deterministic catalog entries with preview, apply, verify, and rollback contracts."
+  },
+  "aiBoundary": {
+    "optional": true,
+    "serverControlled": true,
+    "purpose": "Explain unmatched diagnostic evidence and provide advisory analysis.",
+    "modelOutputCanBecomeExecutableShell": false,
+    "novelAiFindingsAutomaticallyRepairable": false
+  },
+  "compatibility": {
+    "supportedOpenClawVersions": [],
+    "supportStatement": "No broad OpenClaw compatibility range has been validated or asserted.",
+    "testedOpenClawVersions": [
+      {
+        "version": "2026.6.11",
+        "scope": "Real-machine diagnostic and guarded-repair scenarios in the Blaxel lab.",
+        "source": "REVIEW.md"
+      }
+    ]
+  },
+  "measuredOutcomes": {
+    "source": "https://clawfix.dev/api/stats",
+    "observedAt": "2026-07-27",
+    "totalDiagnoses": 205,
+    "recordedSuccesses": 5,
+    "unknown": 200,
+    "interpretation": "Unknown outcomes are missing follow-up, not failures. This snapshot does not establish a repair success rate."
+  },
+  "claimBoundary": "ClawFix diagnoses OpenClaw in one command and can apply only the supported repairs listed in this contract."
+}

docs/capabilities/v0.11.2.md

@@ -0,0 +1,74 @@
+# ClawFix 0.11.2 capability contract
+
+Evidence snapshot: **2026-07-27**. This file is generated; edit `evidence.json` or shipped source, then run `npm run capabilities:generate`.
+
+## Product boundary
+
+ClawFix diagnoses OpenClaw in one command and can apply only the supported repairs listed in this contract.
+
+- Deterministic detectors: **49**
+- Executable reviewed repairs: **5**
+- Node.js: `>=22.0.0`
+
+## Interfaces delivered
+
+### Installer
+
+- Download https://clawfix.dev/install to install-clawfix.sh.
+- Inspect the script and compare its SHA-256 with https://clawfix.dev/install/sha256.
+- Run bash install-clawfix.sh.
+
+Run `clawfix`. It delivers: Portable plain readline CLI installed under ~/.clawfix with a ~/.local/bin/clawfix launcher.
+
+### npm
+
+Run `npx clawfix@0.11.2`. It delivers: Portable plain readline CLI.
+
+### Standalone TUI
+
+The TUI is **not bundled with npm**. ClawFix 0.11.2 publishes these separate assets:
+
+- `clawfix-tui-linux-x64-baseline.tar.gz`
+- `clawfix-tui-linux-x64.tar.gz`
+
+Portable CLI platforms documented for this release: macOS, Linux, WSL.
+Standalone TUI platforms evidenced by the release assets: Linux x64, Linux x64 baseline.
+
+## Executable repair catalog
+
+| ID | Action | Risk |
+|---|---|---|
+| `auto-update-enabled-warning` | Disable OpenClaw auto-update | low |
+| `gateway-loopback-no-auth` | Require a token on the gateway | medium |
+| `gateway-not-running` | Restart the OpenClaw gateway | low |
+| `no-hybrid-search` | Enable hybrid memory search | low |
+| `no-memory-flush` | Enable memory flush on compaction | low |
+
+Repairs are deterministic catalog entries with preview, apply, verify, and rollback contracts.
+
+## AI boundary
+
+AI analysis is optional and controlled by the selected server. It may explain unmatched evidence, but model output never becomes executable shell and a novel AI finding is not automatically repairable.
+
+## OpenClaw compatibility evidence
+
+No broad OpenClaw compatibility range has been validated or asserted.
+
+- OpenClaw 2026.6.11: Real-machine diagnostic and guarded-repair scenarios in the Blaxel lab. ([source](../../REVIEW.md))
+
+## Measured outcomes
+
+The [public stats snapshot](https://clawfix.dev/api/stats) recorded:
+
+- Total diagnoses: **205**
+- Recorded successes: **5**
+- Unknown outcomes: **200**
+
+Unknown outcomes are missing follow-up, not failures. This snapshot does not establish a repair success rate.
+
+## Sources
+
+- Release metadata: https://api.github.com/repos/arcabotai/clawfix/releases/tags/v0.11.2
+- Detector catalog: [`src/known-issues.js`](../../src/known-issues.js)
+- Repair catalog: [`cli/core/repair-catalog.js`](../../cli/core/repair-catalog.js)
+- Machine-readable contract: [`v0.11.2.json`](./v0.11.2.json)

package.json

@@ -19,6 +19,8 @@
     "start": "node --env-file-if-exists=.env src/server.js",
     "dev": "node --env-file-if-exists=.env --watch src/server.js",
     "test": "node scripts/run-node-tests.mjs",
+    "capabilities:generate": "node scripts/generate-capability-contract.mjs",
+    "capabilities:check": "node scripts/generate-capability-contract.mjs --check",
     "hash:script": "node scripts/update-script-hash.mjs",
     "test:tui": "bun test --cwd cli/tui",
     "prove:remediation": "node scripts/prove-remediation.mjs .",