chore: import upstream snapshot with attribution

docs/build-from-source.md

@@ -0,0 +1,99 @@
+# Build from Source
+
+This guide is for anyone who wants to run MagenticLite from a clone of this
+repo — for example to make local changes to the backend or frontend, to test
+an unreleased commit, or to dig into the code.
+
+If you only want to run MagenticLite, the released `magentic_ui` package on
+PyPI is what you want — see [Installation](./installation.md) instead.
+
+## Prerequisites
+
+Platform-level prerequisites (Homebrew / WSL2 / KVM / `uv` / Python 3.12) are
+the same as a regular install — follow the [Installation guide](./installation.md#supported-platforms)
+through the **macOS** or **Windows (WSL)** prerequisites section, then come
+back here.
+
+In addition, building the frontend requires:
+
+- **Node.js v24 or later**
+- **pnpm v10+**
+
+```bash
+# Install Node via nvm
+curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash
+nvm install 24
+
+# Install pnpm
+npm install -g pnpm
+```
+
+## Clone the repo
+
+```bash
+git clone https://github.com/microsoft/magentic-ui.git
+cd magentic-ui
+```
+
+## Backend setup
+
+```bash
+uv venv --python=3.12 --seed .venv
+source .venv/bin/activate
+uv sync --all-extras
+```
+
+`uv sync` installs MagenticLite in editable mode along with all dev
+dependencies. The Quicksand VM image is downloaded automatically the first time
+you launch `magentic-ui`; you don't need to run a separate install step for it.
+
+## Frontend setup
+
+The frontend is a Vite + React app under `frontend/`. Production builds are
+written into `src/magentic_ui/backend/web/ui/`, where the backend serves them as
+static files.
+
+```bash
+cd frontend
+pnpm install
+```
+
+You then have two ways to run the UI, depending on what you're working on.
+
+### Option 1: Production-style run
+
+Build the frontend once into the backend's static directory, then launch the
+backend and let it serve the bundle. Use this when you're working only on
+backend code.
+
+```bash
+# from frontend/
+pnpm build      # outputs to ../src/magentic_ui/backend/web/ui/
+cd ..
+
+magentic-ui --port 8081
+```
+
+Open <http://127.0.0.1:8081/>. Re-run `pnpm build` whenever the frontend
+changes.
+
+### Option 2: Frontend dev mode
+
+Run the Vite dev server with hot reload, and run the backend separately. Use
+this when you're iterating on the UI.
+
+```bash
+# Terminal 1 — backend
+source .venv/bin/activate
+magentic-ui --port 8081
+
+# Terminal 2 — frontend dev server
+cd frontend
+pnpm dev        # serves at http://localhost:5173
+```
+
+Open <http://localhost:5173/>. The Vite dev server proxies API and WebSocket
+calls to the backend on port 8081.
+
+For UI component conventions, see
+[`frontend/src/components/ui/README.md`](../frontend/src/components/ui/README.md).