diff --git a/CHANGELOG.md b/CHANGELOG.md
index 1a0acc0a..bd0bb226 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -19,6 +19,7 @@ All notable changes to cmux are documented here.
 - Browser link middle-click handling now uses native WebKit behavior ([#416](https://github.com/manaflow-ai/cmux/pull/416))
 - Settings-window actions now route through a single command-palette/settings flow
 - Sentry upgraded with tracing, breadcrumbs, and dSYM upload support ([#366](https://github.com/manaflow-ai/cmux/pull/366))
+- Clarified session restore scope: cmux restores layout, working directory, scrollback, and browser history, but does not resume live terminal process state yet
 
 ### Fixed
 - Startup split hang when pressing Cmd+D then Ctrl+D early after launch ([#364](https://github.com/manaflow-ai/cmux/pull/364))
diff --git a/README.md b/README.md
index a9206e34..5fbf5a3a 100644
--- a/README.md
+++ b/README.md
@@ -194,6 +194,16 @@ Browser developer-tool shortcuts follow Safari defaults and are customizable in
 
 cmux NIGHTLY is a separate app with its own bundle ID, so it runs alongside the stable version. Built automatically from the latest `main` commit and auto-updates via its own Sparkle feed.
 
+## Session restore (current behavior)
+
+On relaunch, cmux currently restores app layout and metadata only:
+- Window/workspace/pane layout
+- Working directories
+- Terminal scrollback (best effort)
+- Browser URL and navigation history
+
+cmux does **not** restore live process state inside terminal apps. For example, active Claude Code/tmux/vim sessions are not resumed after restart yet.
+
 ## Star History
 
 <a href="https://star-history.com/#manaflow-ai/cmux&Date">
diff --git a/web/app/docs/getting-started/page.tsx b/web/app/docs/getting-started/page.tsx
index f37e5104..b941f231 100644
--- a/web/app/docs/getting-started/page.tsx
+++ b/web/app/docs/getting-started/page.tsx
@@ -68,6 +68,20 @@ cmux notify --title "Build Complete" --body "Your build finished"`}</CodeBlock>
         bar.
       </p>
 
+      <h2>Session restore (current behavior)</h2>
+      <p>After relaunch, cmux restores layout and metadata only:</p>
+      <ul>
+        <li>Window, workspace, and pane layout</li>
+        <li>Working directories</li>
+        <li>Terminal scrollback (best effort)</li>
+        <li>Browser URL and navigation history</li>
+      </ul>
+      <Callout>
+        cmux does not restore live process state yet. Active terminal app
+        sessions such as Claude Code, tmux, and vim are not resumed after app
+        restart.
+      </Callout>
+
       <h2>Requirements</h2>
       <ul>
         <li>macOS 14.0 or later</li>