feat(updater): add release notes tab and one-time post-install dialog

architecture/notes/nebula_app/gpui_shell/workspace/windowing/2026-10-01-installed-notes-visibility.md

@@ -0,0 +1,43 @@
+# Installed notes wait for a visible window
+
+## Status
+
+Implemented; isolated visibility regression passed on all selected native platforms.
+
+## Context
+
+The post-install notice is persistent and shown once. A resident first launch can have only a hidden workspace.
+
+## Evidence
+
+The original UpdateInstalled dispatch chose an MRU window without inspecting window_hidden, then persisted release_notes_shown before opening its dialog. Quitting before revealing that hidden window could consume a notice the user never saw.
+
+## Decision
+
+The update dialog capability owns one pending installed description in App memory. The process shell event dispatcher chooses a live visible workspace before claiming and opening it. Existing pump ticks retry after reveal; a destroyed handle leaves it pending. Failed persistent claims retry after five seconds. No activation or forced reveal is added.
+
+The complete process shell event dispatcher lives under windowing/shell_events, separately from window creation, transfer, geometry and snapshot responsibilities. Its existing event behavior is preserved.
+
+## Rejected alternatives
+
+- A hidden dialog must not count as a visible notice.
+- Forcing a background resident window to the foreground would change startup policy.
+- A second persisted notice state would duplicate the existing locked updater authority.
+
+## Consequences
+
+Only a successful persistent claim for a visible target consumes the pending notice. Process exit before reveal preserves the existing unclaimed update state. The pending payload is App-owned and does not create another worker or persistence format.
+
+## Validation
+
+An isolated GPUI regression sends the real installed event while the workspace is hidden, checks that no persistent acknowledgement exists, reveals it, and checks one acknowledgement. Existing rendered-dialog tests cover content and close/Escape.
+
+PR head e763523db8ad0bbe3a6d053cd11b1e46ee682adf passed all ten required checks. Its macOS ARM native suite passed 2583 tests (24 existing skips); the visibility regression passed in 3.046 seconds. Later cache changes require their own current-head CI result and do not replace this visibility evidence.
+
+## Supersedes
+
+None; refines the installed release-notes lifecycle.
+
+## Revisit when
+
+Resident window visibility or updater acknowledgement ownership changes.

architecture/notes/nebula_app/update_check/2026-09-30-installed-release-notes.md

@@ -0,0 +1,90 @@
+# Installed release descriptions
+
+## Status
+
+Proposed in this PR.
+
+## Context
+
+Users need to read the installed version's GitHub Release description in Settings,
+and see it once after an in-app update succeeds. A newer release can appear before
+that first launch; checking `/latest` cannot identify the installed description.
+
+## Evidence
+
+`update_check.rs` already parses the Release body for checksums but discards it.
+`update_download/handoff.rs` records the installer transaction, executable and
+result and verifies the running version when recovering the workspace.
+`update_state.json` already serializes prompt preferences with process/file locks.
+The GPUI component `TextView` already renders selectable Markdown in the product.
+
+The initial single-file cache could lose a pending release when Settings fetched
+the installed version before handoff preparation; an offline first launch then
+had no matching snapshot. Concurrent version writes also cannot share a replacing file.
+
+## Decision
+
+Retain the Release body as separate updater metadata. Cache it during a successful
+update check, then snapshot the matching version in the existing handoff directory
+before authorizing installation. This adds no installation authority or helper
+protocol field. Missing cached notes do not prevent installation.
+
+Cache each version in its own atomic file keyed by a SHA-256 digest of the version,
+using the existing digest dependency. Version strings cannot escape the updater
+directory, and installed-version reads do not evict pending-update metadata.
+The old single-file cache remains an exact-version read fallback for compatibility;
+new writes use only version-keyed files. Handoff snapshots keep their existing format.
+
+On startup require a successful result matching the transaction, installation and
+running version. Load the snapshot, or fetch that exact version's tag when no
+snapshot exists. Failed/offline reads leave the notice pending for a later launch.
+Claim the notice with the existing prompt-state process/file locks before showing
+it in the selected window. The optional `release_notes_shown` field defaults to
+unset for existing state files and is independent of update snooze/skip settings.
+
+Settings and the dialog share a read-only Markdown view with loading, empty,
+failure/retry and external-release states. Remote descriptions are rendered as
+content; only HTTP(S) links are opened by the view. Settings remain available on
+externally managed distributions; their updates do not create in-app handoffs.
+
+## Rejected alternatives
+
+- Inferring success from a changed version: also triggers on fresh installs,
+  manual installs and failed updates followed by a rollback.
+- Showing the latest description: can describe a version not yet installed.
+- Using the workspace restore acknowledgement: restoration and reading notes have
+  independent lifecycles; an offline metadata fetch must not consume the notice.
+- A second rich-text renderer or dependency: the existing TextView is sufficient.
+
+## Consequences
+
+Release text is stored under the existing updater directory, outside user
+settings. No new thread is added; discovery uses the existing startup check and
+view-owned background tasks. Automatic installation remains Windows/macOS only;
+other distributions can read their installed version's notes in Settings.
+
+Each cached file retains the existing 2 MiB read limit. Retained metadata grows
+with distinct versions rather than requests; pruning must preserve pending update
+notes and is separate from correcting version isolation.
+
+The shown marker gives at-most-once presentation across normal restarts and
+concurrent processes. As with existing update prompts, a crash after persisting
+that marker but before painting can consume the notice; Settings still exposes it.
+
+## Validation
+
+Focused regressions cover exact-version text, persisted snapshots, successful
+handoff, duplicate claims, rollback exclusion and existing workspace recovery.
+PR evidence records compilation, rendered UI checks and native CI separately.
+The cache regression reproduces a pending update followed by an installed-version
+Settings read, then verifies an offline handoff snapshot. Compatibility and
+untrusted version-path cases exercise the same production cache helpers.
+
+## Supersedes
+
+None.
+
+## Revisit when
+
+The updater accepts another release source, the handoff protocol changes, or
+release notes need a user acknowledgement rather than once-only presentation.

nebula_app/i18n/en-US.json

@@ -211,7 +211,8 @@
         "advanced": "advanced session tray restore startup autostart login silent",
         "backup": "backup cloud sync export restore webdav s3 sftp 123 nextcloud synology nas r2 minio snapshots",
         "agents": "agents agent hook hooks claude codex opencode cursor kimi pi omp copilot grok",
-        "mobile": "mobile phone android ios remote pairing qr lan relay"
+        "mobile": "mobile phone android ios remote pairing qr lan relay",
+        "release_notes": "release notes changelog what is new"
       }
     },
     "opacity": {
@@ -1471,7 +1472,13 @@
     "later": "Later",
     "prepare_failed": "Could not prepare the update: {error}. Pebrel will stay open.",
     "draft_changed": "A document changed while preparing to exit. Save or discard the latest changes, then retry.",
-    "in_progress": "This installation is being updated. Wait for the update to finish; Pebrel will reopen automatically."
+    "in_progress": "This installation is being updated. Wait for the update to finish; Pebrel will reopen automatically.",
+    "release_notes_title": "Release notes",
+    "release_notes_loading": "Loading release notes…",
+    "release_notes_failed": "Could not load release notes: {error}",
+    "release_notes_retry": "Retry",
+    "release_notes_empty": "This release has no description.",
+    "open_release": "Open release"
   },
   "files.filter_placeholder": "Filter files...",
   "files.match_case": "Match case",

nebula_app/i18n/ja-JP.json

@@ -44,7 +44,8 @@
         "advanced": "詳細設定 セッション トレイ 復元 起動 自動起動 ログイン サイレント",
         "backup": "バックアップ クラウド 同期 ストレージ エクスポート 復元 スナップショット 資格情報 パスワード",
         "agents": "エージェント フック 連携",
-        "mobile": "モバイル スマートフォン スマホ リモート ペアリング QRコード ローカルネットワーク リレー ネットワークアダプター 閲覧専用 通知"
+        "mobile": "モバイル スマートフォン スマホ リモート ペアリング QRコード ローカルネットワーク リレー ネットワークアダプター 閲覧専用 通知",
+        "release_notes": "リリースノート 更新内容 変更履歴"
       }
     },
     "opacity": {

nebula_app/i18n/zh-CN.json

@@ -211,7 +211,8 @@
         "advanced": "高级 会话 托盘 恢复 自启动 静默启动 开机 登录",
         "backup": "云备份 云同步 云存储 备份 导出 恢复 坚果云 123云盘 群晖 快照",
         "agents": "智能体 钩子 接入",
-        "mobile": "手机 远程 配对 二维码 局域网 中转 网卡 只看 手机通知"
+        "mobile": "手机 远程 配对 二维码 局域网 中转 网卡 只看 手机通知",
+        "release_notes": "更新内容 更新日志 版本说明"
       }
     },
     "opacity": {
@@ -1471,7 +1472,13 @@
     "later": "稍后",
     "prepare_failed": "更新准备失败：{error}。Pebrel 将保持打开。",
     "draft_changed": "准备退出期间文档发生了变化。请保存或放弃最新修改后重试。",
-    "in_progress": "当前安装正在更新，请等待更新完成，Pebrel 随后会自动重新打开。"
+    "in_progress": "当前安装正在更新，请等待更新完成，Pebrel 随后会自动重新打开。",
+    "release_notes_title": "更新内容",
+    "release_notes_loading": "正在加载更新内容…",
+    "release_notes_failed": "无法加载更新内容：{error}",
+    "release_notes_retry": "重试",
+    "release_notes_empty": "此版本未提供更新说明。",
+    "open_release": "打开发布页"
   },
   "files.filter_placeholder": "过滤文件...",
   "files.match_case": "区分大小写",

nebula_app/src/gpui_shell/mod.rs

@@ -38,6 +38,7 @@ mod molecule_view;
 mod motion;
 pub mod network_settings;
 pub mod prelude;
+mod release_notes;
 mod scientific_render;
 pub mod session_restore;
 #[cfg(all(test, feature = "gpui-test-support"))]
@@ -75,6 +76,7 @@ pub(crate) enum GpuiShellEvent {
     MuxAttach,
     RuntimeControl(std::sync::Arc<crate::runtime_api::RuntimeDispatch>),
     UpdateAvailable(crate::update_check::UpdateCheckResult),
+    UpdateInstalled(crate::update_check::release_notes::ReleaseNotes),
     SshPrompt(std::sync::Arc<crate::ssh_prompt::Prompt>),
     OpenDirectories(Vec<String>),
     ElevatedLaunch(std::sync::Arc<crate::platform::elevation::handover::Dispatch>),