diff --git a/README.md b/README.md
index 2e8e0b13..5f3062fe 100644
--- a/README.md
+++ b/README.md
@@ -1,74 +1,42 @@
-
+# Shift
-# Plasma Mobile
+Convergence mode for Plasma Mobile. One shell that works as a phone and
+adapts to a desktop when you connect a monitor, keyboard, or mouse.
-This repository contains shell components for Plasma Mobile.
+Shift is a fork of [plasma-mobile](https://invent.kde.org/plasma/plasma-mobile).
+The upstream phone UI is untouched; convergence adds a layer on top.
-* Project page: [plasma-mobile.org](https://plasma-mobile.org)
-* Repository: [invent.kde.org/plasma/plasma-mobile](https://invent.kde.org/plasma/plasma-mobile)
-* Documentation: [invent.kde.org/plasma/plasma-mobile/-/wikis/home](https://invent.kde.org/plasma/plasma-mobile/-/wikis/home)
-* Development channel: [matrix.to/#/#plasmamobile:matrix.org](https://matrix.to/#/#plasmamobile:matrix.org)
+### What convergence mode changes
-### Reporting issues
-* How to report issues: [invent.kde.org/plasma/plasma-mobile/-/wikis/Issue-Tracking](https://invent.kde.org/plasma/plasma-mobile/-/wikis/Issue-Tracking)
-* Shell issue tracker: [invent.kde.org/plasma/plasma-mobile/-/issues](https://invent.kde.org/plasma/plasma-mobile/-/issues)
-* General issue tracker: [https://invent.kde.org/teams/plasma-mobile/issues/-/issues](https://invent.kde.org/teams/plasma-mobile/issues/-/issues)
+* Navigation panel replaced by a dock with running-app indicators,
+ favourites, context menus, and hover tooltips
+* App drawer opens as a floating popup above the dock
+* Window management: edge tiling, edge maximize, close buttons, task
+ context menus, Overview integration
+* Status bar gains a system tray, date display, and hover highlights
+* Screen space reserved for the dock via layer-shell exclusive zone
+* Desktop niceties: right-click wallpaper settings, minimize-all on
+ home press, clickable page indicators
### Locations
-* [components/mobileshell](components/mobileshell) - private shell component library (API not guaranteed to be stable!)
+
+* [components/mobileshell](components/mobileshell) - private shell component library
* [containments](containments) - shell panels (homescreens, status bar, task panel)
-* [kcms](kcms) - settings module
-* [look-and-feel](look-and-feel/contents) - Plasma look-and-feel packages (ex. lockscreen, logout, etc.)
-* [shell](shell) - Plasma shell package, provides implementations for applet and containment configuration dialogs
-* [quicksettings](quicksettings) - quick settings packages for the action drawer
-* [tests](tests) - small runnable snippets that can be used to test parts of the shell without loading all of Plasma
+* [envmanager](envmanager) - convergence mode environment manager (kwinrc, etc.)
+* [kwin/scripts](kwin/scripts) - KWin scripts for convergence window behaviour
+* [kcms](kcms) - settings modules
+* [look-and-feel](look-and-feel/contents) - Plasma look-and-feel packages
+* [shell](shell) - Plasma shell package
+* [quicksettings](quicksettings) - quick settings for the action drawer
-
-
-
-### Test on a development machine
-
-See the [documentation page](https://invent.kde.org/plasma/plasma-mobile/-/wikis/Building-and-Testing-Locally) for more details.
-
-It is recommended to use `kdesrc-build` to build this from source. See [this page](https://community.kde.org/Get_Involved/development) in order to set it up.
-
-Dependencies:
-* KDE Frameworks 6 setup (plasma-framework and its dependencies)
-* plasma-nano
-* plasma-workspace
-* plasma-nm
-* plasma-pa
-* bluez-qt
-* Milou (for search)
-* Kirigami
-* Kirigami Addons
-* feedbackd (optional: for vibrations)
-
-To start the shell in a window, run:
+### Building
```
-QT_QPA_PLATFORM=wayland dbus-run-session kwin_wayland --xwayland "plasmashell -p org.kde.plasma.mobileshell"
+cmake -B build
+cmake --build build
+cmake --install build
```
-Useful options:
-- Specify the `--output-count` flag for the number of displays
-- Specify `--width` and `--height` for the window size
+### Upstream
-```
-QT_QPA_PLATFORM=wayland dbus-run-session kwin_wayland --xwayland "plasmashell -p org.kde.plasma.mobileshell" --output-count 2 --width 360 --height 720
-```
-
-### Device specific configuration
-
-See [/devices/README.md](/devices/README.md) for more details on setting device specific configuration (ex. notches, screen curves).
-
----
-
-
-
-
-
-
+See [pm_README.md](pm_README.md) for the original Plasma Mobile README.
diff --git a/pm_README.md b/pm_README.md
new file mode 100644
index 00000000..2e8e0b13
--- /dev/null
+++ b/pm_README.md
@@ -0,0 +1,74 @@
+
+
+# Plasma Mobile
+
+This repository contains shell components for Plasma Mobile.
+
+* Project page: [plasma-mobile.org](https://plasma-mobile.org)
+* Repository: [invent.kde.org/plasma/plasma-mobile](https://invent.kde.org/plasma/plasma-mobile)
+* Documentation: [invent.kde.org/plasma/plasma-mobile/-/wikis/home](https://invent.kde.org/plasma/plasma-mobile/-/wikis/home)
+* Development channel: [matrix.to/#/#plasmamobile:matrix.org](https://matrix.to/#/#plasmamobile:matrix.org)
+
+### Reporting issues
+* How to report issues: [invent.kde.org/plasma/plasma-mobile/-/wikis/Issue-Tracking](https://invent.kde.org/plasma/plasma-mobile/-/wikis/Issue-Tracking)
+* Shell issue tracker: [invent.kde.org/plasma/plasma-mobile/-/issues](https://invent.kde.org/plasma/plasma-mobile/-/issues)
+* General issue tracker: [https://invent.kde.org/teams/plasma-mobile/issues/-/issues](https://invent.kde.org/teams/plasma-mobile/issues/-/issues)
+
+### Locations
+* [components/mobileshell](components/mobileshell) - private shell component library (API not guaranteed to be stable!)
+* [containments](containments) - shell panels (homescreens, status bar, task panel)
+* [kcms](kcms) - settings module
+* [look-and-feel](look-and-feel/contents) - Plasma look-and-feel packages (ex. lockscreen, logout, etc.)
+* [shell](shell) - Plasma shell package, provides implementations for applet and containment configuration dialogs
+* [quicksettings](quicksettings) - quick settings packages for the action drawer
+* [tests](tests) - small runnable snippets that can be used to test parts of the shell without loading all of Plasma
+
+
+
+
+### Test on a development machine
+
+See the [documentation page](https://invent.kde.org/plasma/plasma-mobile/-/wikis/Building-and-Testing-Locally) for more details.
+
+It is recommended to use `kdesrc-build` to build this from source. See [this page](https://community.kde.org/Get_Involved/development) in order to set it up.
+
+Dependencies:
+* KDE Frameworks 6 setup (plasma-framework and its dependencies)
+* plasma-nano
+* plasma-workspace
+* plasma-nm
+* plasma-pa
+* bluez-qt
+* Milou (for search)
+* Kirigami
+* Kirigami Addons
+* feedbackd (optional: for vibrations)
+
+To start the shell in a window, run:
+
+```
+QT_QPA_PLATFORM=wayland dbus-run-session kwin_wayland --xwayland "plasmashell -p org.kde.plasma.mobileshell"
+```
+
+Useful options:
+- Specify the `--output-count` flag for the number of displays
+- Specify `--width` and `--height` for the window size
+
+```
+QT_QPA_PLATFORM=wayland dbus-run-session kwin_wayland --xwayland "plasmashell -p org.kde.plasma.mobileshell" --output-count 2 --width 360 --height 720
+```
+
+### Device specific configuration
+
+See [/devices/README.md](/devices/README.md) for more details on setting device specific configuration (ex. notches, screen curves).
+
+---
+
+
+
+
+
+