Enforce desktop release contract and improve MCP failure handling

.github/workflows/release.yml

@@ -37,6 +37,20 @@ permissions:
   contents: read
 
 jobs:
+  release-documentation:
+    name: Release Documentation
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1
+        with:
+          persist-credentials: false
+
+      - name: Reject stale release availability language
+        if: github.ref_type == 'tag' || (github.event_name == 'workflow_dispatch' && inputs.create_release)
+        env:
+          RELEASE_TAG: ${{ inputs.tag || github.ref_name }}
+        run: python3 eng/verify-release-docs.py "$RELEASE_TAG"
+
   public-compatibility-smoke:
     permissions:
       contents: read
@@ -86,7 +100,10 @@ jobs:
 
   build-release-assets:
     name: Build ${{ matrix.asset }} assets
-    needs: public-compatibility-smoke
+    needs:
+      - release-documentation
+      - public-compatibility-smoke
+      - desktop-first-success
     runs-on: ${{ matrix.os }}
     strategy:
       fail-fast: false
@@ -235,6 +252,11 @@ jobs:
           & $cliBin version
           if ($LASTEXITCODE -ne 0) { exit $LASTEXITCODE }
 
+          if ($IsLinux) {
+            python3 "$root/eng/verify-desktop-first-success.py" --cli $cliBin --gateway $gatewayBin
+            if ($LASTEXITCODE -ne 0) { exit $LASTEXITCODE }
+          }
+
           $desktopArchive = Join-Path $archives "openclaw-desktop-$rid.zip"
           $gatewayArchive = Join-Path $archives "openclaw-gateway-aot-$rid.zip"
           $cliArchive = Join-Path $archives "openclaw-cli-aot-$rid.zip"
@@ -282,6 +304,47 @@ jobs:
           name: release-assets-${{ matrix.rid }}
           path: artifacts/release-archives/*
 
+  desktop-first-success:
+    name: Desktop First-Success Contract
+    runs-on: ubuntu-latest
+    timeout-minutes: 30
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1
+        with:
+          persist-credentials: false
+
+      - name: Setup .NET
+        uses: actions/setup-dotnet@a98b56852c35b8e3190ac28c8c2271da59106c68
+        with:
+          dotnet-version: ${{ env.DOTNET_VERSION }}
+
+      - name: Cache NuGet packages
+        uses: actions/cache@55cc8345863c7cc4c66a329aec7e433d2d1c52a9
+        with:
+          path: ${{ env.NUGET_PACKAGES }}
+          key: nuget-${{ runner.os }}-${{ hashFiles('OpenClaw.Net.slnx', '**/*.csproj', '**/*.props', '**/*.targets') }}
+          restore-keys: |
+            nuget-${{ runner.os }}-
+
+      - name: Validate packaged smoke fixture
+        run: python3 -m unittest discover -s eng -p "test_verify_desktop_first_success.py"
+
+      - name: Restore desktop contract tests
+        run: dotnet restore src/OpenClaw.Tests
+
+      - name: Build desktop contract tests
+        run: dotnet build --no-restore -c Release src/OpenClaw.Tests ${{ env.FAST_BUILD_PROPERTIES }}
+
+      - name: Run local-agent first-success contract
+        run: dotnet test --no-build -c Release --filter "Category=DesktopRelease" --verbosity normal --logger "trx;LogFileName=desktop-first-success.trx" src/OpenClaw.Tests
+
+      - name: Upload desktop contract results
+        if: always()
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a
+        with:
+          name: desktop-first-success-results
+          path: "**/desktop-first-success.trx"
+
   publish-github-release:
     name: Publish GitHub Release
     needs: build-release-assets
@@ -327,9 +390,9 @@ jobs:
           - openclaw-desktop-osx-arm64.zip
           - openclaw-desktop-linux-x64.zip
 
-          These archives bundle Companion, the NativeAOT gateway, and the NativeAOT CLI. Standalone gateway and CLI archives are also attached for operators.
+          These archives bundle AgentQi Companion, the NativeAOT gateway, and the NativeAOT CLI. Standalone gateway and CLI archives are also attached for operators.
 
-          Release verification for this exact tag includes the deterministic pinned public-plugin compatibility gate. The moving latest-package canary is reported separately and is not release-blocking.
+          Release verification for this exact tag includes the deterministic pinned public-plugin compatibility gate, the AgentQi Companion local-agent first-success contract, and the release-documentation availability check. The moving latest-package canary is reported separately and is not release-blocking.
 
           Windows and macOS assets are currently unsigned unless this workflow is extended with signing secrets. See docs/RELEASES.md for the expected first-run warnings and the signing path.
           EOF

CHANGELOG.md

@@ -6,6 +6,9 @@ All notable changes to this project are tracked in this file.
 
 ### Release Engineering
 
+- Standardized the desktop product name as AgentQi Companion while preserving OpenClaw.NET runtime, package, protocol, and storage identities.
+- Added a release-blocking desktop first-success contract covering Companion preset persistence, shared preset capabilities, sequential multi-tool selection, and an Ollama-compatible tool round trip.
+- Added a release documentation gate that rejects tags still described as future or unavailable work, and updated v0.3.0 availability guidance.
 - Made the deterministic pinned public-plugin compatibility smoke run on pull requests and `main` pushes, while keeping the moving latest-package canary scheduled/manual and non-blocking.
 - Added the pinned public-plugin compatibility smoke as a prerequisite for release asset builds.
 - Pinned Supermemory's complete plugin/peer test set and kept a separate latest-peer canary so release verification is reproducible while upstream drift remains visible.

README.md

@@ -15,18 +15,18 @@
 
 Run an assistant locally or host a gateway for your team. Connect a hosted or local model, give it tools and memory, and work through desktop chat, the browser, messaging channels, or APIs. Developers can extend the runtime in .NET and deploy supported capabilities with NativeAOT.
 
-**OpenClaw.NET** is the runtime and repository. **AgentQi [OpenClaw.NET]** is the Avalonia desktop companion; [AgentQi.dev](https://agentqi.dev) is the documentation and ecosystem home.
+**OpenClaw.NET** is the runtime and repository. **AgentQi Companion** is the Avalonia desktop product for OpenClaw.NET; [AgentQi.dev](https://agentqi.dev) is the documentation and ecosystem home.
 
 This is an independent .NET implementation inspired by [OpenClaw](https://github.com/openclaw/openclaw), with practical ecosystem compatibility. It is not affiliated with or endorsed by the upstream project.
 
 ## Meet the desktop companion
 
-Chat is the starting point. AgentQi brings setup, connections, activity, memory, history, and settings into one desktop interface, with light and dark themes.
+Chat is the starting point. AgentQi Companion brings setup, connections, activity, memory, history, and settings into one desktop interface, with light and dark themes.
 
 <picture>
   <source media="(prefers-color-scheme: dark)" srcset="docs/images/companion/agentqi-dark.png" />
   <source media="(prefers-color-scheme: light)" srcset="docs/images/companion/agentqi-light.png" />
-  <img src="docs/images/companion/agentqi-light.png" alt="AgentQi Avalonia desktop companion: chat welcome screen, setup shortcuts, navigation sidebar, and Configure via chat option" width="1200" />
+  <img src="docs/images/companion/agentqi-light.png" alt="AgentQi Companion for OpenClaw.NET: chat welcome screen, setup shortcuts, navigation sidebar, and Configure via chat option" width="1200" />
 </picture>
 
 *Companion welcome screen from `main`, before connecting a gateway. Packaged releases may show an earlier interface.*
@@ -39,7 +39,7 @@ Chat configuration covers supported scalar settings, not every operation. Creden
 
 ## Download And Run Desktop
 
-Choose a desktop bundle from the [latest release](https://github.com/clawdotnet/openclaw.net/releases/latest). Each includes Companion, the NativeAOT gateway, and the NativeAOT CLI.
+Choose a desktop bundle from the [latest release](https://github.com/clawdotnet/openclaw.net/releases/latest). Each includes AgentQi Companion, the NativeAOT gateway, and the NativeAOT CLI.
 
 | Platform | Download |
 | --- | --- |
@@ -119,7 +119,7 @@ Tool: echo(hello): ok
 | Area | Capabilities |
 | --- | --- |
 | Agent runtime | Streaming, tool execution, cancellation, retries, sessions, memory, and token-usage reporting. |
-| Interfaces | AgentQi desktop companion, browser chat and admin UI, CLI, terminal UI, OpenAI-compatible HTTP endpoints, MCP, and WebSockets. |
+| Interfaces | AgentQi Companion, browser chat and admin UI, CLI, terminal UI, OpenAI-compatible HTTP endpoints, MCP, and WebSockets. |
 | Models | OpenAI, Claude, Gemini, Azure OpenAI, DeepSeek, Ollama, and OpenAI-compatible providers; named profiles and optional embedded local inference. |
 | Tools and channels | 80+ native and optional tool surfaces for files, web, sessions, databases, email, home automation, and more; adapters for Telegram, WhatsApp, Teams, Slack, Discord, and other channels. The active set depends on configuration. |
 | Extensions | MCP servers and interactive MCP Apps, reusable `SKILL.md` packages, first-party .NET integrations, and supported OpenClaw TS/JS plugins. |

docs/ARCHITECTURE_BOUNDARIES.md

@@ -8,9 +8,19 @@ OpenClaw.NET is a NativeAOT-friendly agent runtime and gateway for local and sel
 | --- | --- | --- |
 | **OpenClaw.NET** | Repository and runtime identity | Owns runtime correctness, local/self-hosted execution, gateway and CLI primitives, durable state, recovery, replay, and plugin execution compatibility. |
 | **AgentQi** | Documentation and ecosystem umbrella | Owns the broader developer/operator experience, ecosystem discovery, trust and lifecycle UX, and future multi-instance or fleet-level management. |
+| **AgentQi Companion** | Desktop product for OpenClaw.NET | Owns the chat-first desktop experience for setup and operation of one OpenClaw.NET runtime. “For OpenClaw.NET” describes the relationship; it is not a package, protocol, or storage rename. |
 | **AgentQiX** | Reserved likely future runtime identity | No current package, repository, or runtime rename is implied. A migration requires an explicit naming decision, compatibility plan, and release boundary. |
 
-The current rule is therefore to keep runtime capabilities in OpenClaw.NET and describe cross-runtime ecosystem or managed-product work under AgentQi. Do not introduce AgentQiX naming into runtime packages or user-facing migration guidance until that separate decision is made.
+The current rule is therefore to keep runtime capabilities in OpenClaw.NET, use AgentQi Companion for the desktop application, and describe cross-runtime ecosystem or managed-product work under AgentQi. Do not introduce AgentQiX naming into runtime packages or user-facing migration guidance until that separate decision is made.
+
+### Naming surfaces
+
+| Surface | Canonical label |
+| --- | --- |
+| Repository, runtime, gateway, CLI, packages, protocols, settings, and GitHub release titles | **OpenClaw.NET** |
+| Desktop window chrome, application metadata, desktop-bundle descriptions, and desktop documentation | **AgentQi Companion**; use **AgentQi Companion for OpenClaw.NET** when the relationship needs explanation |
+| Documentation and ecosystem navigation | **AgentQi** and **AgentQi.dev** |
+| Future runtime references | Keep **AgentQiX** reserved until an explicit migration decision and compatibility plan exist |
 
 ## OpenClaw.NET Core
 

docs/RELEASES.md

@@ -2,7 +2,7 @@
 
 OpenClaw.NET's low-friction desktop path is the **desktop bundle** published on [GitHub Releases](https://github.com/clawdotnet/openclaw.net/releases/latest). It bundles:
 
-- Companion
+- AgentQi Companion
 - the NativeAOT gateway
 - the NativeAOT CLI
 
@@ -74,7 +74,7 @@ A release is ready only when all of the following are true for the exact tag com
 
 Use **full CI** only when all required lanes above passed for that exact commit. Report the non-blocking latest-package canary separately so upstream drift is visible without making a moving dependency a release gate.
 
-> **v0.2.0 verification note:** v0.2.0 was published before the pinned public compatibility job became a release-workflow dependency. Its successful build and platform smokes did not establish public-plugin compatibility. The reliability and recovery work currently marked **main only** in the [roadmap](ROADMAP.md) also landed after the v0.2.0 tag.
+> **v0.2.0 verification note:** v0.2.0 was published before the pinned public compatibility job became a release-workflow dependency. Its successful build and platform smokes did not establish public-plugin compatibility. The reliability and recovery work documented in the [roadmap](ROADMAP.md) landed after v0.2.0 and was first released in v0.3.0.
 
 The workflow currently builds:
 
@@ -84,7 +84,7 @@ The workflow currently builds:
 
 The macOS runner label is intentionally ARM-native for the `osx-arm64` artifact. Add an Intel macOS row only if you want to support older Intel Macs and have a runner that can NativeAOT publish that RID reliably.
 
-### Companion Release Smoke
+### AgentQi Companion Release Smoke
 
 Before publishing a public desktop release, run this manual smoke on at least one desktop bundle:
 

docs/ROADMAP.md

@@ -2,15 +2,15 @@
 
 ## Release Availability
 
-The roadmap describes the current `main` branch, not necessarily the latest published binaries. [v0.2.0](https://github.com/clawdotnet/openclaw.net/tree/v0.2.0) was cut before the reliability integration listed below. Items marked **main only** target **v0.3.0** and are not available in v0.2.0. A v0.2.1 release, if needed, is reserved for corrective release or compatibility work rather than this feature set.
+The roadmap describes the current `main` branch, which may move ahead of published binaries. The reliability, recovery, and AgentQi Companion work listed as recently completed is available in [v0.3.0](https://github.com/clawdotnet/openclaw.net/tree/v0.3.0) and later. Consult each future item for an explicit target release rather than assuming that `main` is already packaged.
 
 ## Recently Completed
 
-- **Companion token protection and migration** (**main only; target v0.3.0**): OS-backed token storage now automatically migrates legacy JSON/fallback credentials with read-back verification, preserves recoverable copies on failure, respects Remember token and plaintext opt-in, and uses atomic private file writes. See [Companion token storage](companion-token-storage.md).
+- **Companion token protection and migration** (**released in v0.3.0**): OS-backed token storage now automatically migrates legacy JSON/fallback credentials with read-back verification, preserves recoverable copies on failure, respects Remember token and plaintext opt-in, and uses atomic private file writes. See [Companion token storage](companion-token-storage.md).
 
-- **Run explanation and recovery view** (**main only; target v0.3.0**): admin console, Dashboard, and Companion session details combine recorded run/goal state, goal notes, session-scoped pending approvals, checkpoints, and recent tool failure evidence with contextual recovery guidance. Existing timelines remain available for investigation; the view does not authorize or replay actions.
+- **Run explanation and recovery view** (**released in v0.3.0**): admin console, Dashboard, and Companion session details combine recorded run/goal state, goal notes, session-scoped pending approvals, checkpoints, and recent tool failure evidence with contextual recovery guidance. Existing timelines remain available for investigation; the view does not authorize or replay actions.
 
-- **Real-run regression import and offline replay** (**main only; target v0.3.0**): import a redacted, complete text exchange from a gateway trajectory export and run recorded provider/tool fixtures through `RuntimeScenarioRunner`, with independent assertions and strict consumption checks. Includes an executable sample; see [trajectory replay](testing/trajectory-replay.md).
+- **Real-run regression import and offline replay** (**released in v0.3.0**): import a redacted, complete text exchange from a gateway trajectory export and run recorded provider/tool fixtures through `RuntimeScenarioRunner`, with independent assertions and strict consumption checks. Includes an executable sample; see [trajectory replay](testing/trajectory-replay.md).
 
 - Browser sessions invalidate after local operator account updates, deletion, or disablement.
 - Goal completion accepts completed tool work; model status updates run alone and blocked transitions require three observations. Resume resets continuation and blocker counters.
@@ -70,10 +70,10 @@ These are strong candidates for the next roadmap phases because they extend the
 
 The runtime already includes CLI insights, URL safety validation, and trajectory export. The next additions build on those capabilities:
 
-1. **Durable action reconciliation (main only, opt-in; target v0.3.0)**: persisted dispatch journal, stable provider adapter keys, completed-result reuse, and blocking of unknown outcomes before replay. See [durable actions](durable-actions.md). Provider-specific adapters and executor-bypassing jobs need individual integration.
-2. **Expanded regression capture (main only; target v0.3.0)**: opt-in bounded automatic capture, structured failed/blocked tool replay, and offline multimodal URL-content verification. See [trajectory replay](testing/trajectory-replay.md).
-3. **Full-instance backup and restore (main only; target v0.3.0)**: offline inventory plans capture durable state and secret-reference manifests, verify checksums, and restore into a new isolated directory with SQLite validation and no dispatch. See [instance backup](instance-backup.md).
-4. **Guided recovery controls (main only; target v0.3.0)**: permission-aware goal pause/resume and evidence-backed action reconciliation with revision, approval, and budget checks. Complements the run explanation view; see [guided recovery](guided-recovery.md).
+1. **Durable action reconciliation (released in v0.3.0, opt-in)**: persisted dispatch journal, stable provider adapter keys, completed-result reuse, and blocking of unknown outcomes before replay. See [durable actions](durable-actions.md). Provider-specific adapters and executor-bypassing jobs need individual integration.
+2. **Expanded regression capture (released in v0.3.0)**: opt-in bounded automatic capture, structured failed/blocked tool replay, and offline multimodal URL-content verification. See [trajectory replay](testing/trajectory-replay.md).
+3. **Full-instance backup and restore (released in v0.3.0)**: offline inventory plans capture durable state and secret-reference manifests, verify checksums, and restore into a new isolated directory with SQLite validation and no dispatch. See [instance backup](instance-backup.md).
+4. **Guided recovery controls (released in v0.3.0)**: permission-aware goal pause/resume and evidence-backed action reconciliation with revision, approval, and budget checks. Complements the run explanation view; see [guided recovery](guided-recovery.md).
 
 ## Security Hardening (Likely Breaking)
 

docs/RUN_RECOVERY.md

@@ -1,6 +1,6 @@
 # Run explanation and recovery
 
-> **Release availability:** Available on `main` and targeted for v0.3.0; not included in v0.2.0. See the [roadmap](ROADMAP.md).
+> **Release availability:** Included in v0.3.0 and later; not included in v0.2.0. See the [roadmap](ROADMAP.md).
 
 Open a session in the admin console, Dashboard, or Companion's Sessions tab. The **Run explanation and recovery** section shows a snapshot of the recorded state and the next steps appropriate to it. Refresh the session to see changes.