Docs update for Agent Canvas v1.6.0 release

[DevinVinson]

Summary

Agent Canvas v1.6.0 is a substantial minor release that adds 12 features, most notably the Electron desktop app for macOS and Windows, enriched plugin inspection, MCP connection-health cards, a skill-install restart banner, a title-generation LLM profile selector, and cloud-aware navigation changes. Several of these features introduce new UI surfaces or install paths that have no documentation today. There are no breaking changes, but multiple pages need new sections or updates to stay accurate.

Release notes source: https://github.com/OpenHands/agent-canvas/releases/tag/v1.6.0

This issue was drafted by an AI agent (OpenHands) on behalf of a maintainer.

---

What Changed in the Release

Features

• Electron desktop app for macOS and Windows (#1864, #1911, #1897)
  Agent Canvas is now available as a native desktop application. On macOS, users download a .dmg file from the GitHub Releases page, drag "Agent Canvas" to Applications, and clear the quarantine attribute (xattr -d com.apple.quarantine "/Applications/Agent Canvas.app") because the app is ad-hoc signed. On Windows, users download and run Agent-Canvas-Setup-<version>.exe (NSIS installer); Windows SmartScreen warns because the installer is unsigned — users click "More info → Run anyway". First launch on either platform downloads the agent server from PyPI (shows a loading screen with progress). Intel Macs are build-from-source only. The desktop loading screen includes an expandable startup-log console (see below).

• Expandable startup-log console on desktop loading screen (#1878)
  The desktop app's loading screen now has a "Show details" toggle that expands a scrollable console showing all service startup logs. If startup fails, the screen stays open in a failure state (danger summary, console auto-expanded, "Copy logs" and "Quit" buttons) instead of quitting. This gives users diagnostic information without needing to find terminal logs.

• Plugin detail modal now shows contents (#1690)
  Clicking a plugin in the Plugins page now opens a detail modal that shows two new sections: "Skills in this plugin bundle" (icon, name, description per skill, including command-derived skills) and "Files" (an expandable directory tree with an inline, syntax-highlighted file viewer). Re-clicking the selected file closes the viewer. Works for installed, local, and marketplace plugins. Sections are hidden when the backend predates the new API fields.

• One-click restart to activate chat-installed skills (#1830)
  When a user installs a skill from chat (via /add-skill <github-url>), a pinned banner now appears above the message composer explaining that the skill cannot load in the current conversation. The banner names the installed skill and offers a "Start new conversation with this skill" button, which creates a new conversation rooted in the same workspace directory. Dismissing the banner hides it for the session; installing another skill resurfaces it. The banner does not appear on Cloud backends.

• Actionable connection health on installed MCP server cards (#1833)
  Installed MCP server cards now display a live connection-health indicator. Each card shows a status dot (green for connected, red for failure) and a status line. For servers with known credential probes (GitHub, Linear), the card distinguishes "credentials verified" from "credentials failed" vs. "connectivity-only." Failed cards show actionable buttons: "Retry," "Update credentials" (or "Re-authorize"), and "View documentation." Error text is redacted — secrets and tokens embedded in URLs are replaced with **********. Health is seeded from the pre-save connection test, so cards show a verdict immediately after install. Fixing credentials via the card's edit action refreshes the status without a page reload.

• Cloud-aware Skills/Plugins nav and new Integrations link (#1890)
  When the active backend is OpenHands Cloud: the Customize → Skills item is relabeled "Skills and Plugins" and becomes an external link to {cloudHost}/settings/skills (opens in a new tab); the Plugins nav item is hidden; Settings → Cloud is renamed "All Cloud Settings"; and a new Settings → Integrations item appears linking to {cloudHost}/settings/integrations/. On local backends, nav is unchanged.

• Agent Canvas update-availability card in settings (#1898)
  The Settings page now shows a card below the nav items displaying the current Agent Canvas version. On load, it checks the npm registry and shows a green "Up to date" pill or an "Update available" pill. Expanding the card reveals: status line, a "Check for updates" button, copyable npm and Docker upgrade commands, and a link to the GitHub release notes. If the registry is unreachable, no pill appears and a quiet failure note is shown.

• Title generation profile preference in settings (#1910)
  A new "Conversation titles" section in Settings → Application lets users choose which LLM profile generates conversation titles. The default is "Automatic" (uses the active local profile). Selecting a specific profile allows using a cheaper or more reliable model for title generation without changing the agent's main model. The preference is persisted with other app-level settings and stays consistent across profile rename/delete.

• Cloud org ID and automation telemetry forwarding (#1924, #1917)
  Internal telemetry improvements. Not user-facing — no doc changes needed.

Bug Fixes

• Preserve secret values on edit (#1889)
  Previously, editing a secret could clear the stored value. Secrets now preserve their values during edit. Users who experienced lost secrets after editing should no longer see this behavior.

• Keep LLM Profiles reachable while an ACP agent is active (#1915)
  The Settings → LLM page is now accessible even when an ACP agent profile (e.g., Claude Code, Codex) is the active agent. Previously, the LLM Profiles section could become unreachable.

• Fix paginated workspace folder listings (#1566)
  Large workspace directories now paginate correctly. Previously, only the first page of files was shown.

• Locked Cloud backend reconnect modal (#1807)
  The Cloud backend reconnection modal no longer gets stuck in a locked state.

• Streaming deduplication fixes (#1865, #1896)
  Fixes duplicate rendering of final events and streamed reasoning. Internal rendering improvement — no doc change needed.

• Desktop loading screen styling, Windows dev server spawn, telemetry fixes (#1876, #1859, #1831, #1848, #1872, #1892, #1919)
  Internal fixes and polish. No doc changes needed.

Maintenance

• Bump @openhands/extensions to 0.11.0 (#1880), bump software-agent-sdk to 1.37.0 and automation to 1.2.0 (#1906), bump automation to 1.3.1 (#1934)
  Dependency updates. No doc changes unless docs cite specific SDK versions.

• CI, refactoring, Helm release-please (#1861, #1873, #1884)
  Internal. No doc changes.

---

Current Doc Coverage

Already covered (relevantly)

Page	Path	Relevance
Install	openhands/usage/agent-canvas/setup.mdx	Covers npm, Docker, npx, from-source install. The "Choose An Install Method" table and tab set will need a Desktop App entry.
Plugins	openhands/usage/agent-canvas/plugins.mdx	Mentions "Inspect plugin details" in a bullet list but does not describe what the detail modal shows. Needs a section on plugin contents.
Customize and Settings	openhands/usage/agent-canvas/customize-and-settings.mdx	Describes Customize vs. Settings split and lists Settings sections. Will need updates for the new cloud-aware nav behavior and the "Conversation titles" subsection.
MCP Settings	openhands/usage/settings/mcp-settings.mdx	Covers MCP configuration. No mention of connection-health cards or recovery actions.
Application Settings	openhands/usage/settings/application-settings.mdx	Covers budget and git author settings. Does not mention title generation profile.
LLM Profiles	openhands/usage/agent-canvas/llm-profiles.mdx	Covers LLM profile configuration. Relevant cross-reference target for title generation profile.
Troubleshooting	openhands/usage/agent-canvas/troubleshooting.mdx	Existing troubleshooting. Desktop startup failures could link here.

Still missing or thin

• Desktop app install and usage: No documentation exists for the Electron desktop app on any platform. The entire install-update-uninstall lifecycle, the loading screen, and the startup-log console are undocumented.
• Plugin detail modal contents: The plugins page says you can "Inspect plugin details" but never describes the skill list, file tree, or syntax-highlighted viewer users now see.
• MCP connection health: No docs describe the health indicator on MCP server cards, the credential-verification flow, the error-text redaction, or the recovery buttons (Retry / Update credentials / View documentation).
• Skill-install restart banner: The /add-skill workflow and the resulting restart banner are undocumented. Users have no reference for what happens after installing a skill from chat.
• Title generation profile: The new Settings → Application → Conversation titles selector is not documented.
• Cloud-aware nav changes: The Customize and Settings docs describe a static nav structure that is now different on Cloud backends.
• Update-availability card: The version-check card in Settings is not documented.

---

Proposed Doc Work

1. Add desktop app install method to setup.mdx

Type: Section addition to existing page
File: openhands/usage/agent-canvas/setup.mdx

Add a "Desktop App (macOS & Windows)" entry to the "Choose An Install Method" table and a corresponding tab in the "Verify Prerequisites," "Install And Run," "Stop," "Update," and "Uninstall" tab sets.

Suggested content:

• Prerequisites tab: Node.js is not needed; uv is bundled. Mention macOS Sequoia compatibility note.
• Install and Run tab: Two sub-sections for macOS and Windows.
  • macOS: download .dmg from GitHub Releases, drag to Applications, run xattr -d com.apple.quarantine "/Applications/Agent Canvas.app" (explain why: ad-hoc signed, quarantined on download). Note Intel Macs need build-from-source. First launch downloads the agent server (takes a few minutes, progress shown on loading screen).
  • Windows: download Agent-Canvas-Setup-<version>.exe from GitHub Releases, run installer, handle SmartScreen warning ("More info → Run anyway"). First launch downloads the agent server.
• Stop tab: Quit the app normally. Mention there are no orphaned processes (fixed in this release).
• Update tab: Reference the update-availability card in Settings, and provide manual steps (download new installer/DMG).
• Uninstall tab: macOS → drag to Trash. Windows → Settings → Apps.

2. Document plugin detail modal contents in plugins.mdx

Type: Section addition to existing page
File: openhands/usage/agent-canvas/plugins.mdx

Add a new section titled "Inspect Plugin Contents" (or expand the existing mention) after "View Attached Plugins During a Conversation."

Suggested content:

• Explain that clicking a plugin opens a detail modal with metadata plus two content sections.
• Skills section: describes the "Skills in this plugin bundle" area showing icon, name, and description per skill (including command-derived skills like city-weather:now).
• Files section: describes the expandable directory tree and inline syntax-highlighted file viewer. Mention re-clicking closes the viewer, binary files show a fallback, and loading errors are handled gracefully.
• Note that contents appear for installed, local, and marketplace plugins, and that sections are hidden on older backends that don't return the new fields.

3. Document MCP connection health on server cards

Type: Section addition to existing page
File: openhands/usage/settings/mcp-settings.mdx

Add a section titled "Connection Health on Installed Servers" after the current configuration content.

Suggested content:

• Explain the status indicator (green dot = connected, red dot = failure) on each installed MCP server card.
• Describe the three status types: "Connected — credentials verified (N tools)," credentials failure, and "Reachable — credentials not verified" (connectivity-only, for servers without known credential probes).
• List the recovery actions: "Retry" (re-tests), "Update credentials" (opens the server edit form), "View documentation."
• Mention that error text is redacted — secrets in URLs are replaced with **********.
• Note that health is seeded from the pre-save test, so cards show status immediately after install. Fixing credentials via the card refreshes status without a page reload.

4. Document the skill-install restart banner

Type: Section addition to existing page
File: openhands/usage/agent-canvas/customize-and-settings.mdx (under the Skills subsection) or as a new subsection on the conversations or plugins page.

Suggested content:

• Explain the /add-skill <github-url> workflow: the agent fetches and installs the skill into <workspace>/.agents/skills/<name>/.
• Note that skills load once per conversation, so a freshly installed skill is not available in the current conversation.
• Describe the banner: it appears above the message composer, names the installed skill, and offers "Start new conversation with this skill." The new conversation opens in the same workspace folder with the skill loaded.
• Mention dismiss behavior (session-scoped, resurfaces on new install) and that the banner does not appear on Cloud backends.

5. Document title generation profile preference

Type: Section addition to existing page
File: openhands/usage/settings/application-settings.mdx

Add a section titled "Conversation Title Generation" or "Title Generation Profile."

Suggested content:

• Explain the new "Conversation titles" area in Settings → Application.
• Describe the profile selector: "Automatic" (default, uses the active local LLM profile) or a specific saved profile.
• Explain the use case: use a cheaper or faster model for title generation without changing the agent's primary model.
• Note that the preference persists and stays consistent if the selected profile is renamed or deleted.
• Cross-link to LLM Profiles and Model Configuration.

6. Update cloud-aware nav behavior in customize-and-settings.mdx

Type: Section addition to existing page
File: openhands/usage/agent-canvas/customize-and-settings.mdx

Add a note or subsection explaining how the Customize and Settings navigation differs on Cloud backends:

• Customize → Skills becomes "Skills and Plugins" and links externally to {cloudHost}/settings/skills.
• Customize → Plugins is hidden on Cloud backends.
• Settings → Cloud is renamed "All Cloud Settings."
• Settings → Integrations is a new Cloud-only item linking externally to {cloudHost}/settings/integrations/.

7. Document the update-availability card in settings — Optional

Type: Section addition to existing page
File: openhands/usage/agent-canvas/setup.mdx (in the Update section) or openhands/usage/agent-canvas/customize-and-settings.mdx

Suggested content:

• Mention that the Settings page shows the installed Agent Canvas version and checks the npm registry for updates.
• Describe the two states: "Up to date" (green pill) and "Update available" (with copyable upgrade commands and a link to GitHub release notes).
• Note: if the registry is unreachable, the card degrades gracefully with no pill and no toast.

This is optional because the update-availability card is self-explanatory in the UI, but mentioning it in docs helps users who update via the command line know where to check.

---

Notes for the Implementer

PRs worth referencing

• Desktop app core: #1864, macOS: #1911, Windows: #1897
• Desktop startup console: #1878
• Plugin detail modal: #1690
• Skill install banner: #1830
• MCP connection health: #1833
• Cloud nav changes: #1890
• Update card: #1898
• Title generation profile: #1910

Technical details

• The desktop app is an Electron wrapper around the same web UI. It bundles uv and downloads the agent server on first launch. The loading screen is a separate Electron BrowserWindow with a preload script (electron/preload.cjs) bridging main-process logs to the renderer.
• MCP connection health uses the existing POST /api/mcp/test endpoint. Credential probes are tool-specific (get_me for GitHub, list_teams for Linear). The health store is in-memory and per-session.
• The skill-install restart banner parses ExecuteBashObservation events for a marker string from fetch_skill.py. It creates a new conversation via the API with workingDir set to the install root.
• The title generation profile is a new field on the app-level settings, passed to POST /api/conversations as title_llm_profile.

Style guide reminders

• Use Title Case for H1/H2 headings per openhands/DOC_STYLE_GUIDE.md.
• Use present tense and active voice.
• Use fenced code blocks for commands.
• Use absolute internal links (e.g. /openhands/usage/agent-canvas/setup).
• Use <Note> and <Warning> Mintlify components where appropriate.
• If adding a new page, update the navigation in docs.json.
• Run mint broken-links after edits to catch dead links.