diff --git a/README.md b/README.md
index e1ccb95..2c80414 100644
--- a/README.md
+++ b/README.md
@@ -1,12 +1,45 @@
 # SageTube
 
-A watch-first YouTube client for the desktop — search, browse channels and playlists, follow subscriptions, and stream videos in an embedded mpv player, with full yt-dlp download capability inherited from [YTSage](https://github.com/oop7/YTSage).
+A watch-first YouTube client for the desktop. Search, browse channels and
+playlists, follow subscriptions, and stream videos in an embedded mpv player —
+with the full yt-dlp download feature set inherited from
+[YTSage](https://github.com/oop7/YTSage).
 
-SageTube is a fork of [YTSage](https://github.com/oop7/YTSage) by [oop7](https://github.com/oop7) (MIT). The original YTSage documentation is preserved at [docs/UPSTREAM_README.md](docs/UPSTREAM_README.md).
+## Features
 
-## Status
+**Watching**
+- 📺 Embedded mpv player (Wayland/X11/Windows/macOS) with quality selector,
+  speed, volume, subtitles, fullscreen
+- 🔍 In-app YouTube search with thumbnail card grid
+- 📂 Channel browsing (Videos / Shorts / Live) and playlist views
+- 🔔 Local subscriptions — no Google account needed — with an aggregated feed;
+  optional real account feed via browser cookies
+- ⏯️ Watch history with resume positions and a persistent play queue
+- ⬇️ One click from any video card into the downloader
 
-Under active development. See the upstream README for the downloader feature set, which remains fully functional.
+**Downloading** (from YTSage)
+- Format table, audio extraction, subtitles, SponsorBlock, chapters,
+  playlists, trimming, speed limits, proxies, cookies, custom yt-dlp commands,
+  download history — see the [upstream README](docs/UPSTREAM_README.md)
+
+## Install
+
+```bash
+pip install .
+sagetube
+```
+
+Requires **libmpv** for playback (Arch: `pacman -S mpv`) — see
+[docs/BUILDING.md](docs/BUILDING.md). Without it the app works as a downloader.
+
+## Fork notes
+
+SageTube is a fork of [YTSage](https://github.com/oop7/YTSage) by
+[oop7](https://github.com/oop7) (MIT). The internal package keeps the
+`ytsage` name so upstream fixes remain mergeable — see
+[docs/UPSTREAM.md](docs/UPSTREAM.md). The fork also fixes a number of
+upstream bugs (unsafe partial-file cleanup, unverified binary updates,
+thread-safety issues, PATH corruption on Windows — see the git log).
 
 ## License
 
diff --git a/docs/BUILDING.md b/docs/BUILDING.md
new file mode 100644
index 0000000..13421af
--- /dev/null
+++ b/docs/BUILDING.md
@@ -0,0 +1,48 @@
+# Building & running SageTube
+
+## Requirements
+
+- Python >= 3.10
+- **libmpv** (system library; `python-mpv` binds to it at runtime)
+  - Arch: `sudo pacman -S mpv`
+  - Debian/Ubuntu: `sudo apt install libmpv2`
+  - Fedora: `sudo dnf install mpv-libs`
+  - macOS: `brew install mpv`
+  - Windows: place `libmpv-2.dll` next to the executable (builds from
+    https://github.com/shinchiro/mpv-winbuild-cmake/releases), or install mpv
+    and add it to PATH
+- ffmpeg (for download merging; the app can auto-install it)
+
+Without libmpv the app still runs — the Watch tab shows an install hint and
+search/browse/download work normally.
+
+## Run from source
+
+```bash
+python -m venv .venv && source .venv/bin/activate
+pip install -e .
+sagetube
+```
+
+On first start the app downloads its own SHA256-verified `yt-dlp` binary and
+the Deno runtime (yt-dlp's JS challenge solver) into the SageTube data dir:
+
+- Linux: `~/.local/share/SageTube/bin/`
+- macOS: `~/Library/Application Support/SageTube/bin/`
+- Windows: `%LOCALAPPDATA%\SageTube\bin\`
+
+## Notes on YouTube playback reliability
+
+Playback resolves streams through mpv's `ytdl_hook` using the managed yt-dlp.
+YouTube's CDN intermittently serves stalled streams to non-browser clients;
+the player retries automatically (twice, after 25 s of no playback). Keeping
+yt-dlp updated (built-in updater, stable or nightly channel) is the long-term
+fix channel for extractor breakage.
+
+## Release workflows
+
+The `.github/workflows/` files are inherited from upstream YTSage and target
+GitHub runners; they do not run on Gitea. If you set up Gitea Actions, note
+that the upstream Linux/Windows workflows download appimagetool and a bundled
+ffmpeg **without checksum verification** — add hash checks before reusing
+them for release artifacts.
diff --git a/docs/UPSTREAM.md b/docs/UPSTREAM.md
new file mode 100644
index 0000000..a007249
--- /dev/null
+++ b/docs/UPSTREAM.md
@@ -0,0 +1,38 @@
+# Tracking upstream YTSage
+
+SageTube keeps the full git history of [YTSage](https://github.com/oop7/YTSage)
+and the internal `ytsage` package name so upstream improvements can be merged.
+
+## Syncing
+
+```bash
+git fetch upstream            # upstream = https://github.com/oop7/YTSage.git
+git merge upstream/main
+```
+
+## Expected conflict zones
+
+Most SageTube features live in **new files** and merge cleanly. Conflicts are
+likely only in:
+
+| File | Reason |
+|---|---|
+| `ytsage/gui/ytsage_gui_main.py` | tab-shell edit in `init_ui` (`_setup_main_tabs`), closeEvent hook |
+| `ytsage/gui/ytsage_gui_analysis.py` | delegates subprocess execution to `YtdlpClient` |
+| `ytsage/utils/ytsage_constants.py` | SageTube data dirs, PATH prepend for managed binaries |
+| `ytsage/utils/ytsage_config_manager.py` | atomic save, defaults merge, player/feed/advanced keys |
+| `pyproject.toml` | name, version, deps (python-mpv), URLs |
+| `ytsage/languages/en.json` | added sections: player, cards, main_tabs, search, watch, browse, feed |
+
+Bug fixes made in this fork (see git log between the merge commit and the
+first feature commit) may also conflict if upstream fixes them differently —
+prefer whichever version is stricter about verification and thread safety.
+
+## SageTube-only modules (never conflict)
+
+- `ytsage/core/ytsage_client.py` — shared yt-dlp JSON invocation layer
+- `ytsage/core/ytsage_mpv.py` — libmpv probe
+- `ytsage/gui/ytsage_gui_player.py` — embedded mpv player
+- `ytsage/gui/ytsage_gui_watch.py` / `_search.py` / `_browse.py` / `_feed.py` — tabs
+- `ytsage/gui/ytsage_gui_router.py` / `_cards.py` — navigation + video cards
+- `ytsage/utils/ytsage_library_manager.py` — subscriptions/history/queue DB