docs: add v1.0 upgrade guide with UX changes documentation

3 files changed, 66 insertions, 54 deletions

diff --git a/CHANGES.md b/CHANGES.md
deleted file mode 100644
index 1fc4fac4f..000000000
--- a/CHANGES.md
+++ /dev/null
@@ -1,53 +0,0 @@
-# OpenCode 1.0
-
-OpenCode 1.0 is a rewrite of the TUI
-
-We went from the go+bubbletea based TUI which suffered from both performance and capability issues to an in-house
-framework (OpenTUI) written in zig+solidjs.
-
-The new TUI mostly works like the old one as it's connecting to the same
-opencode server.
-
-There are some notable UX changes:
-
-1. The session history is more compressed, only showing the full details of the edit
-   and bash tool.
-
-2. We've added a command bar which almost everything flows through. Can press
-   ctrl+p to bring it up in any context and see everything you can do.
-
-3. Added a session sidebar (can be toggled) with some useful information.
-
-We've also stripped out some functionality that we were not sure if anyone
-actually used - if something important is missing please open an issue and we'll add it back
-quickly.
-
-### Breaking Changes
-
-## Keybinds
-
-### Renamed
-
-- messages_revert -> messages_undo
-- switch_agent -> agent_cycle
-- switch_agent_reverse -> agent_cycle_reverse
-- switch_mode -> agent_cycle
-- switch_mode_reverse -> agent_cycle_reverse
-
-### Removed
-
-- messages_layout_toggle
-- messages_next
-- messages_previous
-- file_diff_toggle
-- file_search
-- file_close
-- file_list
-- app_help
-- project_init
-- tool_details
-- thinking_blocks
-- session_child_cycle
-- session_child_cycle_reverse
-- model_cycle_recent
-- model_cycle_recent_reverse
diff --git a/packages/web/astro.config.mjs b/packages/web/astro.config.mjs
index 7d509cabc..24987ca35 100644
--- a/packages/web/astro.config.mjs
+++ b/packages/web/astro.config.mjs
@@ -65,7 +65,7 @@ export default defineConfig({
         "providers",
         "enterprise",
         "troubleshooting",
-
+        "1-0",
         {
           label: "Usage",
           items: ["tui", "cli", "ide", "zen", "share", "github", "gitlab"],
diff --git a/packages/web/src/content/docs/1-0.mdx b/packages/web/src/content/docs/1-0.mdx
new file mode 100644
index 000000000..50aa08a97
--- /dev/null
+++ b/packages/web/src/content/docs/1-0.mdx
@@ -0,0 +1,65 @@
+---
+title: Migrating to 1.0
+description: What's new in OpenCode 1.0.
+---
+
+OpenCode 1.0 is a complete rewrite of the TUI.
+
+We moved from the go+bubbletea based TUI which had performance and capability issues to an in-house framework (OpenTUI) written in zig+solidjs.
+
+The new TUI works like the old one since it connects to the same opencode server.
+
+---
+
+## Upgrading
+
+You will not be autoupgraded to 1.0 if you are currently using a previous
+version.
+
+
+To upgrade manually, run
+```bash
+$ opencode upgrade 1.0.0
+```
+
+---
+
+## UX changes
+
+The session history is more compressed, only showing full details of the edit and bash tool.
+
+We added a command bar which almost everything flows through. Press ctrl+p to bring it up in any context and see everything you can do.
+
+Added a session sidebar (can be toggled) with useful information.
+
+We removed some functionality that we weren't sure anyone actually used. If something important is missing please open an issue and we'll add it back quickly.
+
+---
+
+## Breaking changes
+
+### Keybinds renamed
+
+- messages_revert -> messages_undo
+- switch_agent -> agent_cycle
+- switch_agent_reverse -> agent_cycle_reverse
+- switch_mode -> agent_cycle
+- switch_mode_reverse -> agent_cycle_reverse
+
+### Keybinds removed
+
+- messages_layout_toggle
+- messages_next
+- messages_previous
+- file_diff_toggle
+- file_search
+- file_close
+- file_list
+- app_help
+- project_init
+- tool_details
+- thinking_blocks
+- session_child_cycle
+- session_child_cycle_reverse
+- model_cycle_recent
+- model_cycle_recent_reverse