chore: import upstream snapshot with attribution

docs/TRANSPARENCY_NOTE.md

@@ -0,0 +1,172 @@
+# MagenticLite (aka Magentic 2.0) Transparency Notes
+
+## Overview
+
+MagenticLite (aka Magentic 2.0) is a powerful open-source agentic application that works with you to help you complete tasks across the web browser and your local file system. Built as the successor to [Magentic-UI](https://www.microsoft.com/en-us/research/publication/magentic-ui-report/), MagenticLite was optimized to work with small language models (SLMs) — making it leaner, faster, and more accessible without sacrificing capability.
+
+Unlike its predecessor, which required SOTA frontier models to achieve desired performance, MagenticLite delivers strong agentic capabilities at a fraction of the cost and compute, while keeping you in control at critical steps.
+
+> Looking for the previous version of Magentic-UI optimized to run with frontier models? It lives on the `magentic-ui-0.1.x` branch.
+
+---
+
+## What Can MagenticLite Do?
+
+MagenticLite operates its own browser and can access folders that the user grants it access to, working fluidly across both to complete useful, real-world tasks. It can handle a wide range of tasks — from web research and form filling, to file management, data analysis, and code writing and execution.
+
+Every reasoning trace and action is fully visible to the user. Users can steer the agent at any point, either in natural language or by directly taking control of the browser, ensuring they remain in the driver's seat throughout.
+
+---
+
+## Intended Uses
+
+MagenticLite is a research prototype best suited to explore, experience, and deploy agentic assistance for tasks that require web navigation and local file system interaction.
+
+> **MagenticLite should always be used with human supervision.**
+
+Examples of tasks it can accomplish:
+
+- Fill online forms and make bookings on your behalf
+- Research and analyze information across the browser and your local file system
+- Manage and analyze your local file system
+- Complete simple coding tasks locally
+
+MagenticLite is being shared with the research community to foster further research on agentic systems that keep people in control. It is intended to be used by domain experts who are independently capable of evaluating the quality of outputs, safety issues, and potential harms before acting on them.
+
+---
+
+## Out-of-Scope Uses
+
+We do not recommend using MagenticLite in commercial or real-world applications without further testing and development. It is being released for research purposes.
+
+MagenticLite may not work as expected if used with models other than the recommended setup: **Fara1.5** for browser use and **MagenticBrain** for orchestration and coding.
+
+MagenticLite is **not** well suited for tasks that:
+
+- Rely on audio or video data
+- Involve long-duration tasks (e.g., summarizing 100+ papers)
+- Require real-time fast actions such as playing online games
+
+MagenticLite should always be used with a human in the loop. It was not designed or evaluated for all possible downstream purposes. Developers should consider its inherent limitations as they select use cases, and evaluate and mitigate for accuracy, safety, and fairness concerns specific to each intended downstream use.
+
+MagenticLite should **not** be used in:
+
+- Highly regulated domains or high-stakes situations where inaccurate outputs could suggest actions that lead to injury or negatively impact an individual's health, legal, financial, or life opportunities
+- High-risk decision making (e.g., in law enforcement, legal, finance, or healthcare)
+
+---
+
+## How to Get Started
+
+To begin using MagenticLite, follow instructions in the README page or check our installation guide under `/docs`.
+
+---
+
+## Evaluation
+
+MagenticLite was evaluated on its ability to solve complex agentic tasks, both in standard benchmark settings and on a custom evaluation dataset designed around priority use cases.
+
+### Evaluation Methods
+
+Evaluations were driven by hero use cases reflecting real everyday tasks — including form filling, browser research, and file system management. A custom evaluation dataset was built around these scenarios to measure performance on tasks that reflect actual user value, complementing standard benchmarks rather than simply optimizing for them.
+
+**Recommended models for evaluation:** MagenticLite was developed and tested using **Fara1.5** and **MagenticBrain** as the recommended model configuration. These are the models on which all evaluations and safety testing were conducted. Users may substitute other models, but performance, safety behavior, and benchmark results are not guaranteed outside of the tested configuration.
+
+In addition to quality performance testing, MagenticLite was assessed from a Responsible AI perspective. Based on these results, mitigations were implemented to minimize susceptibility to misuse. See the [Risks and Mitigations](#risks-and-mitigations) section below.
+
+---
+
+## Limitations
+
+- MagenticLite was developed for research and experimental purposes. Further testing and validation are needed before considering its application in commercial or real-world scenarios.
+- MagenticLite was designed and tested primarily using the **English language**. Performance in other languages may vary and should be assessed by someone who is both an expert in the expected outputs and a native speaker of that language.
+- Outputs generated by AI may include factual errors, fabrication, or speculation. Users are responsible for assessing the accuracy of generated content. All decisions leveraging outputs of the system should be made with human oversight and not be based solely on system outputs.
+- All evaluations and safety testing — including critical point handling, XPIA, and code-harm tests — were conducted on the **Fara1.5 + MagenticBrain** configuration. Performance and safety behavior have not been tested on other model combinations.
+- Users with limited GPU capacity may run only one of the two models, but not all use cases will be unlocked. Users who run MagenticLite without Fara should be aware that critical point detection for browser actions relies on Fara's trained behavior.
+- MagenticLite inherits any biases, errors, or omissions produced by the underlying model used.
+- There has not been a systematic effort to ensure that all deployment configurations are protected from all security vulnerabilities such as indirect prompt injection attacks.
+- MagenticLite plans one step at a time rather than committing to a full upfront plan, making it more adaptive and easier to course-correct — a deliberate design choice for SLM-based orchestration.
+
+A list of tasks and usage patterns that are not well supported is documented in `docs/limitations.md`.
+
+---
+
+## Best Practices
+
+MagenticLite is a highly capable agent, proficient at interacting with websites, operating over local files, and writing or executing Python code. Like all LLM-based systems, it can and will make mistakes. To safely operate MagenticLite:
+
+- **Always run it within Quicksand**, a Python wrapper for QEMU VM that provides strong isolation boundaries and is available as part of this open-source release. Strictly limit its access to only essential resources — avoid exposing unnecessary files, folders, or credentials to the agent.
+- **Avoid logging into websites** through the agent unnecessarily.
+- **Never share sensitive data** you would not confidently send to external providers. MagenticLite shares browser screenshots with model providers, including all data entered on websites within its browser session.
+- **Ensure careful human oversight:** meticulously review proposed actions and monitor progress before giving approval.
+- **Approach outputs with appropriate skepticism** — MagenticLite can hallucinate, misattribute sources, or be misled by deceptive or low-quality online content.
+
+We strongly encourage users to pair MagenticLite with models that support robust Responsible AI mitigations. For reference on responsible AI best practices:
+
+- [Announcing new AI safety & Responsible AI features in Azure](https://techcommunity.microsoft.com/t5/ai-azure-ai-services-blog/announcing-new-ai-safety-amp-responsible-ai-features-in-azure/ba-p/3983686)
+- [Azure OpenAI Overview](https://learn.microsoft.com/en-us/legal/cognitive-services/openai/overview)
+- [Azure OpenAI Transparency Note](https://learn.microsoft.com/en-us/legal/cognitive-services/openai/transparency-note)
+- [OpenAI Usage Policies](https://openai.com/policies/usage-policies)
+- [Azure OpenAI Code of Conduct](https://learn.microsoft.com/en-us/legal/cognitive-services/openai/code-of-conduct)
+
+Users are reminded to be mindful of data privacy concerns and are encouraged to review the privacy policies associated with any models and data storage solutions interfacing with MagenticLite. It is the user's responsibility to ensure that the use of MagenticLite complies with relevant data protection regulations and organizational guidelines.
+
+---
+
+## Risks and Mitigations
+
+The risk surface spans the files and websites the agents have access to. The two primary risk categories are:
+
+- **Data leakage from prompt injection.** Untrusted content encountered in the browser or in user-supplied files may attempt to manipulate the agent into exfiltrating data or taking unintended actions. MagenticLite shares browser screenshots with model providers, including any data entered on websites within its session.
+- **Undesired or destructive actions** across the user's local file system, the operated browser, or executed code — including irreversible operations the user did not intend to authorize.
+
+### Mitigations
+
+MagenticLite mitigates these risks through a layered approach:
+
+- **Sandboxed execution environment.** All browser sessions and code execution happen inside Quicksand, a Python wrapper around a QEMU VM that provides strong isolation boundaries from the host system. This limits the blast radius of both prompt injection and undesired actions.
+- **Human intervention at critical points in the browser.** Fara's training surfaces actions that warrant user approval (e.g., transactions, irreversible submissions, login flows), pausing for explicit user confirmation before proceeding.
+- **Code action classification at the MagenticLite harness level.** The allow / require_approval / deny tables categorize every tool call and bash command from the Orchestrator model, blocking destructive operations and routing risky ones through user approval.
+- **User guidance on limiting data exposure.** We recommend that users:
+  - Grant the agent access to only the folders strictly necessary for the task
+  - Avoid logging into websites through the agent unless required
+  - Never share sensitive data they would not confidently send to external model providers
+  - Use the recommended model configuration (Fara1.5 + MagenticBrain), where critical point detection has been tested
+
+Users who choose to disable Fara, substitute alternative models, or run MagenticLite outside the sandboxed VM forfeit one or more of these mitigations and should evaluate the residual risk for their use case.
+
+### How Critical Point Detection Works
+
+In Magentic-UI 0.1, critical point detection was handled by prompting the configured frontier model (e.g., GPT-4o) to flag actions that warranted user review. This prompting-based safety layer no longer exists in this release. Instead, critical point detection has been moved closer to where each kind of action originates:
+
+**Browser actions → handled by Fara's trained behavior.**
+The need for human intervention in browser use is rarely black-and-white and contains many gray areas. Rather than rely on post-hoc prompting, we trained Fara on traces that include correctly calibrated critical points, so the model itself learns when to surface an action for user approval. This generalizes better than prompting and avoids the latency overhead of routing each step through a separate large model. Users who do not run Fara should be aware that this safeguard depends on Fara's training and is not provided by MagenticLite itself.
+
+**Code and tool actions → handled by the MagenticLite harness.**
+MagenticBrain works with a discrete set of tools and bash commands, which makes a deterministic, list-based approach well-suited. The harness applies an **allow / require_approval / deny** classification to every tool call and bash command before execution:
+
+| Classification | Description |
+|---|---|
+| **Allow** | Low-risk, reversible actions execute automatically (e.g., reading a file, listing a directory) |
+| **Require approval** | Actions with potential side effects pause and prompt the user for explicit approval before running |
+| **Deny** | Destructive or irreversible actions (e.g., recursive deletes outside the working folder, certain network operations) are blocked outright |
+
+This split — model-level for browser, harness-level for code — reflects the different shapes of the two action spaces: continuous and ambiguous in the browser, discrete and enumerable in code.
+
+> **Important note for users familiar with Magentic-UI 0.1:** Because critical point detection is no longer provided by MagenticLite itself, running this release with a browser-use model other than Fara, or with a coding model that bypasses the harness, will not give you the same safety behavior that was tested and approved in 0.1. We strongly recommend the recommended model configuration described above.
+
+---
+
+## License
+
+**MIT License**
+
+Nothing disclosed here, including the Out of Scope Uses section, should be interpreted as or deemed a restriction or modification to the license the code is released under.
+
+---
+
+## Contact
+
+We welcome feedback and collaboration from our audience. If you have suggestions, questions, or observe unexpected/offensive behavior in our technology, please contact us at [magui@service.microsoft.com](mailto:magui@service.microsoft.com).
+
+If the team receives reports of undesired behavior or identifies issues independently, we will update this repository with appropriate mitigations.

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).

docs/configuration.md

@@ -0,0 +1,145 @@
+# Configuration
+
+For most users, the **Settings** panel inside the app is all you need. It walks you through model endpoints during the first-launch onboarding flow, and lets you change everything later from **Settings → Models** (and the other Settings tabs).
+
+If you'd rather use a YAML file — for example to share a setup across machines or check it into source control — the same options are also exposed via `config.yaml`. The repo ships a [`config.yaml.example`](../config.yaml.example) at the project root that you can copy as a starting point:
+
+```bash
+cp config.yaml.example config.yaml
+# then edit config.yaml to taste, and pass it on launch:
+magentic-ui --port 8081 --config config.yaml
+```
+
+Each option below shows both the YAML key and (where applicable) the equivalent place in the UI.
+
+## How configuration is stored
+
+MagenticLite keeps your effective configuration in a local database, not in the YAML file. There are three ways that database can be populated, and the rule is simple — **whichever source wrote last wins, and the result persists across restarts**:
+
+- **Onboarding UI** — runs once on first launch and writes your answers to the database.
+- **Settings UI** — change anything at any time; the new values overwrite the database immediately.
+- **YAML file via `--config`** — at startup, MagenticLite reads `config.yaml` and **merges** it into the database (only fields you explicitly set are overwritten; the rest are left alone). This means starting with `--config` every time effectively pins those YAML fields back to your file values on every launch, regardless of what the UI changed in between.
+
+A handful of **Settings → General** options — the display preferences like theme, "show reasoning details", "show tool call details" — are saved to your browser's local storage instead of the backend database. They're per-browser, not per-installation, and they don't show up in `config.yaml`. Other items in the same panel (e.g. agent step limits) do write to the database like the rest of Settings.
+
+```bash
+magentic-ui --port 8081 --config config.yaml
+```
+
+To start fresh — clear the saved model endpoints and re-run the onboarding flow — pass `--reset-config`:
+
+```bash
+magentic-ui --port 8081 --reset-config
+```
+
+This only clears the model endpoints (orchestrator and browser-use); other configuration (sandbox, agent mode, tool approval) is preserved.
+
+You can combine the two: `--reset-config` first clears the model endpoints, then `--config` (if also passed) seeds them from your YAML file.
+
+## Model clients
+
+`model_client_configs` tells MagenticLite which model serves which agent role. There are two roles:
+
+- `orchestrator` — used in the `all` and `omniagent_only` agent modes.
+- `web_surfer` — used in the `all` and `websurfer_only` agent modes.
+
+Each entry is an OpenAI-compatible client config — any server that speaks `/v1/chat/completions` (vLLM, an OpenAI-compatible managed endpoint, your own gateway, …) will work. The full set of fields:
+
+```yaml
+model_client_configs:
+  orchestrator:
+    provider: OpenAIChatCompletionClient
+    config:
+      model: <model id the server expects>
+      base_url: <https://your-endpoint/v1>
+      api_key: <bearer token; leave as a placeholder if your server requires none>
+      max_retries: 5
+      model_info:
+        vision: false
+        function_calling: false
+        json_output: true
+        family: unknown
+        structured_output: false
+        multiple_system_messages: false
+
+  web_surfer:
+    provider: OpenAIChatCompletionClient
+    config:
+      model: <model id the server expects>
+      base_url: <https://your-endpoint/v1>
+      api_key: <bearer token>
+      max_retries: 5
+      model_info:
+        vision: true # browser-use models are vision-language
+        function_calling: false
+        json_output: true
+        family: unknown
+        structured_output: false
+        multiple_system_messages: false
+```
+
+Notes:
+
+- `model_info` describes the capabilities of the model behind the endpoint. The values shown above are the ones MagenticLite has been tested with for the orchestrator (text-only) and browser-use (vision) roles; use them as-is unless you have a reason to differ for your specific model.
+- **MagenticLite is tuned for the recommended models ([MagenticBrain](https://aka.ms/MagenticBrain-foundry) for the orchestrator, [Fara](https://aka.ms/fara-foundry) for browser use).** Pointing the same fields at a different model will probably work, but expect to tweak prompts and run your own evals; the orchestrator and browser-use code paths are not generic across arbitrary models.
+- **Azure OpenAI** is supported via `config.yaml` only (the in-app Settings UI doesn't expose it yet): set `provider: AzureOpenAIChatCompletionClient` and use Azure-specific keys (`azure_endpoint`, `azure_deployment`, `api_version`, `azure_ad_token_provider`) under `config`. See [`config.yaml.example`](../config.yaml.example) for a worked example.
+- If you don't have an endpoint to point at yet, see the [Model Hosting Guide](./model-hosting-guide.md) for one end-to-end way to stand one up.
+
+## Agent mode
+
+`agent_mode` controls which agents are active. It can also be changed in **Settings → Models** without restarting. The three modes let you trade capability for setup cost — you can run with both agents, or with only one of them if that's all your task needs.
+
+| Mode             | Description                                                                                 |
+| ---------------- | ------------------------------------------------------------------------------------------- |
+| `all`            | Orchestrator + Browser use — capable of both local tasks and web browsing (default)         |
+| `omniagent_only` | Orchestrator only — local tasks only; only `model_client_configs.orchestrator` required     |
+| `websurfer_only` | Browser use only — web browsing tasks only; only `model_client_configs.web_surfer` required |
+
+Which mode to pick:
+
+- **`all`** is the default and gives you the full product. You need both an orchestrator endpoint and a browser-use endpoint.
+- **`omniagent_only`** is useful if you only want local file / code-execution work and don't have a browser-use endpoint to point at. The agent can't use web browser.
+- **`websurfer_only`** is useful if you only want web automation and don't have an orchestrator endpoint to point at. The agent can't read or write local files.
+
+```yaml
+agent_mode: all
+```
+
+## Sandbox
+
+`sandbox.type` controls how agent code runs:
+
+| Type        | Description                                                   |
+| ----------- | ------------------------------------------------------------- |
+| `quicksand` | Lightweight QEMU VM with browser isolation (recommended)      |
+| `null`      | No isolation — agent runs on host directly (dev/testing only) |
+
+```yaml
+sandbox:
+  type: quicksand
+```
+
+See [Quicksand browser architecture](./dev/quicksand-browser-architecture.md) for the technical details and environment variables.
+
+## Tool approval
+
+MagenticLite's safety harness prompts the user before executing potentially dangerous tool calls. Three policies are available:
+
+| Policy                       | Behavior                                                                    |
+| ---------------------------- | --------------------------------------------------------------------------- |
+| `auto_approve`               | Execute all tool calls without prompting (eval / trusted setups only)       |
+| `require_approval_untrusted` | Prompt before tool calls deemed untrusted; auto-approve read-only (default) |
+| `require_approval_all`       | Prompt before every tool call                                               |
+
+Set the policy in YAML:
+
+```yaml
+harness_config:
+  orchestrator:
+    approval_policy: require_approval_untrusted
+```
+
+## Next steps
+
+- [Model Hosting Guide](./model-hosting-guide.md) — stand up a model endpoint to point `model_client_configs` at.
+- [Troubleshooting](./troubleshooting.md) — what to do when something doesn't work.

docs/installation.md

@@ -0,0 +1,135 @@
+# Installation
+
+This guide walks you through installing MagenticLite. It covers macOS and Windows (WSL); Linux is similar to the Windows/WSL path.
+
+## Supported platforms
+
+| Platform           | Status                           | Notes                                                              |
+| ------------------ | -------------------------------- | ------------------------------------------------------------------ |
+| macOS ARM64        | ✅ tested                        | Apple Silicon.                                                     |
+| Windows x64 + WSL2 | ✅ tested                        | Run everything inside the Ubuntu shell. Requires KVM enabled.      |
+| Linux x64 (native) | ⚠️ untested but expected to work | Same path as WSL2 minus the `wsl --install` step.                  |
+| Windows ARM64      | ❌ not supported                 | Not currently supported. Support may be added in a future release. |
+
+Pick the section that matches your machine and follow it end to end. The "Install and run" steps at the bottom apply to both platforms.
+
+## Install prerequisites on macOS
+
+Tested on macOS ARM64 (Apple Silicon).
+
+```bash
+# Install Homebrew if you don't have it
+/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
+
+# If you just installed Homebrew, add it to your shell PATH
+# (Apple Silicon path; for Intel Macs use /usr/local/bin/brew)
+eval "$(/opt/homebrew/bin/brew shellenv)"
+
+# Python 3.12+
+brew install python@3.12
+
+# uv (Python package manager)
+curl -LsSf https://astral.sh/uv/install.sh | sh
+source $HOME/.local/bin/env  # add uv to PATH for this shell
+```
+
+Skip ahead to [Install and run MagenticLite](#install-and-run-magenticlite).
+
+## Install prerequisites on Windows (WSL)
+
+Tested on Windows 11 x64 with WSL2 + Ubuntu.
+
+### 1. Install WSL and Ubuntu
+
+In **PowerShell as Administrator**:
+
+```powershell
+wsl --install
+```
+
+Reboot if prompted, then launch Ubuntu — either from the Start menu, or by running `wsl` (or `ubuntu`) in a new PowerShell window — and complete the first-time user setup. **Every command from here on runs inside the Ubuntu (WSL) shell.**
+
+### 2. Enable KVM
+
+```bash
+sudo usermod -aG kvm $USER
+```
+
+Close and reopen the WSL terminal for the group change to take effect.
+
+KVM gives the [Quicksand](https://microsoft.github.io/quicksand/) VM hardware acceleration. Without it the VM falls back to software emulation, which is significantly slower.
+
+### 3. Install tools
+
+```bash
+# uv (Python package manager) — installed first because we use uv to manage Python
+curl -LsSf https://astral.sh/uv/install.sh | sh
+source $HOME/.local/bin/env  # add uv to PATH for this shell
+
+# Python 3.12 (managed by uv; the apt python3.12 package isn't available on Ubuntu 22.04)
+uv python install 3.12
+```
+
+## Install and run MagenticLite
+
+Once the platform-specific prerequisites are in place, the install + run steps are the same on both platforms.
+
+```bash
+# Create a project directory
+mkdir magentic-lite && cd magentic-lite
+
+# Create and activate a virtual environment
+uv venv --python=3.12 --seed .venv
+source .venv/bin/activate
+
+# Install the latest 0.2.x release from PyPI
+uv pip install "magentic_ui>=0.2.0"
+
+# Run
+magentic-ui --port 8081
+```
+
+Then visit <http://127.0.0.1:8081/> in your browser.
+
+For subsequent runs:
+
+```bash
+cd magentic-lite
+source .venv/bin/activate
+magentic-ui --port 8081
+```
+
+> Only one MagenticLite instance can run at a time on the same port (default 8081).
+
+## Coming from Magentic-UI 0.1.x?
+
+If you previously ran a 0.1.x release of Magentic-UI on the same machine, two things to know:
+
+- **Pin the version when you install.** PyPI still hosts the 0.1.x line under the same `magentic_ui` package name, so a plain `uv pip install magentic_ui` may pick up an older release. Pin to a 0.2.x version explicitly:
+
+  ```bash
+  uv pip install "magentic_ui>=0.2.0"
+  ```
+
+- **Use a fresh data directory.** MagenticLite (0.2.x) does not migrate the 0.1.x database. To keep the two installs side-by-side, point this run at a different `--appdir`:
+
+  ```bash
+  magentic-ui --port 8081 --appdir ~/.magentic-lite
+  ```
+
+  Without `--appdir`, MagenticLite uses the same default data directory as 1.0, which can lead to confusing state.
+
+## A note on running MagenticLite as a shared service
+
+MagenticLite is designed to be installed and run **locally on your own machine** by the same person who uses it. We don't recommend hosting it as a shared service for other users:
+
+- **Concurrent multi-user sessions weren't a design goal**, so the UX degrades when several people share one instance.
+- **The app exposes host-level capabilities to whoever can reach it** — most notably the file-system mounting controls used for browser uploads and downloads. Running it as a multi-user service effectively grants every user of that service the same file-system access as the host account.
+
+If you do choose to host it, treat the resulting URL as you would shell access to the host machine.
+
+## Next steps
+
+- [Model Hosting Guide](./model-hosting-guide.md) — get a model endpoint to point MagenticLite at.
+- [Configuration](./configuration.md) — sandbox, agent mode, and tool approval policies.
+- [Troubleshooting](./troubleshooting.md) — common issues and fixes.

docs/limitations.md

@@ -0,0 +1,12 @@
+# Limitations
+
+MagenticLite is a research prototype. Some things it doesn't handle well today:
+
+- **Summarization is limited.** Tasks that ask MagenticLite to read a long source and produce a faithful summary often miss important content or oversimplify.
+- **Long multi-turn conversations degrade.** Quality drops as the conversation history grows, especially for tasks that require keeping many earlier details in mind.
+- **Steering may not always stick.** Even when you successfully redirect the browser-use agent ([Fara](https://aka.ms/fara-foundry)) mid-task, [MagenticBrain](https://aka.ms/MagenticBrain-foundry) may ignore your correction once Fara returns and dispatch Fara back to the original sub-task. The agent's overall plan can be stubborn that way.
+- **Very large files or contexts don't fit.** Tasks that require reading or producing very large documents (well beyond a typical chat-sized prompt) will fail or truncate.
+- **Uploading files inside the browser isn't supported.** The browser-use agent cannot complete flows that require attaching a file from your local disk through a webpage's upload control.
+- **Images aren't supported as task inputs.** Any task that hinges on the agent opening an image file you provide (e.g. "describe this picture", "extract text from this screenshot") will not succeed.
+
+If you hit something not on this list and aren't sure whether it's expected, please file an issue.

docs/model-hosting-guide.md

@@ -0,0 +1,84 @@
+# Model Hosting Guide
+
+MagenticLite talks to models through an **OpenAI-compatible `/v1/chat/completions` endpoint**. This guide walks through hosting the recommended models with **Microsoft Foundry Managed Compute** on Azure.
+
+After deployment, you end up with three values to paste into MagenticLite's onboarding (or into **Settings → Models**): an OpenAI-compatible URL, a model name, and an API key.
+
+> **Each model needs its own endpoint.** MagenticLite uses one model for the orchestrator role and another for browser use. In Foundry, that means **two deployments**, each with its own URL and key.
+
+---
+
+## Microsoft Foundry Managed Compute
+
+### Prerequisites
+
+- An [Azure subscription](https://azure.microsoft.com/free/) with a valid payment method. Free and trial subscriptions don't work for GPU deployments.
+- A **hub-based** project in Foundry. The newer "Foundry project" type does not support Managed Compute. If you don't have one, create it from the [Foundry portal](https://ai.azure.com/) under **+ New project → Hub-based project**. Pick a region with H100 or A100 inventory (East US 2 and Sweden Central are good defaults).
+- Quota for enough dedicated vCPUs in the chosen region. **Standard_NC24ads_A100_v4** is a good VM SKU for both [Fara1.5-9B](https://aka.ms/fara-foundry) and [MagenticBrain](https://aka.ms/MagenticBrain-foundry) for testing and typical single-user use, and each instance consumes 24 vCPUs from the quota family. In [Azure Quotas](https://portal.azure.com/#view/Microsoft_Azure_Capacity/QuotaMenuBlade/~/overview), select **Machine learning**, then request **Standard NCADSA100v4 Family Cluster Dedicated vCPUs** in the same region as your Foundry project. For the usual two-deployment setup with Fara and MagenticBrain running concurrently at instance count 1, request 48 dedicated vCPUs. Larger A100 or H100 SKUs also work if you want extra headroom or have them readily available, but they cost more. Approval can take 24–48 hours.
+
+### 1. Deploy the model
+
+You'll repeat this once per model role you want to use (browser use and/or orchestrator).
+
+1. Open the model card in [Foundry Explore models](https://ai.azure.com/explore/models): [Fara1.5-9B](https://aka.ms/fara-foundry) for browser use or [MagenticBrain-14B](https://aka.ms/MagenticBrain-foundry) for orchestration.
+
+2. On the model card, click **Use this model**. If Foundry asks you to select a project, choose an existing hub-based project or create a new one. For a new project, keep the default hub unless you already have a shared hub for this work, and pick a region with GPU inventory such as East US 2 or Sweden Central.
+
+   If project creation fails with a `Microsoft.Resources/subscriptions/resourcegroups/write` authorization error, your account can see the model but cannot create the Azure resource group behind the Foundry project. Use an existing project where you have access, or ask the subscription owner to grant you a role such as Contributor on the subscription or target resource group, then refresh your credentials and try again.
+
+3. Continue to the deployment wizard. If you're presented with purchase options, pick **Managed Compute**.
+
+4. Configure the deployment:
+
+   | Field           | Value                                                                                                      |
+   | --------------- | ---------------------------------------------------------------------------------------------------------- |
+   | Endpoint name   | anything, e.g. `fara-15-9b-magentic-lite`. Becomes part of the URL.                                        |
+   | Deployment name | anything, e.g. `fara1-5-9b-1` or `magenticbrain-14b-1`. This is for tracking the deployment in Foundry.    |
+   | Virtual machine | **Standard_NC24ads_A100_v4**. Larger A100 or H100 SKUs also work, but they are usually unnecessary for testing. |
+   | Instance count  | **1**. Foundry may default to 3 instances; reduce it to 1 for testing or typical single-user use to avoid unnecessary cost. |
+
+   Both Fara and MagenticBrain are served by vLLM under the hood, so the deployed endpoint exposes a fully OpenAI-compatible `/v1/chat/completions` route — text and vision-language requests both work.
+
+5. Click **Deploy**.
+
+   Provisioning takes ~15–20 minutes per model: Foundry allocates the VM, pulls the container, and warms up vLLM. **Billing starts when the VM is allocated**, not when the endpoint reaches `Healthy`.
+
+### 2. Connect MagenticLite
+
+For each deployment, open **Models + endpoints** in your Foundry project and click into the deployment:
+
+- **REST endpoint** (Details tab): copy the endpoint through `/v1`, for example `https://<endpoint-name>.<region>.inference.ml.azure.com/v1`.
+- **Model ID** (deployment details): use the model name segment after `/models/`, for example `Fara1.5-9B` or `MagenticBrain-14B`. Do not use the deployment name here.
+- **Primary key** (Consume tab): the API key Foundry generated for that endpoint.
+
+Open MagenticLite and fill in the **Browser use model** card (and/or the **Orchestrator** card). On first launch this is part of the onboarding flow; if you've already onboarded, find the same fields under **Settings → Models**.
+
+| Field        | Browser use model (Fara)                                      | Orchestrator model (MagenticBrain)                             |
+| ------------ | ------------------------------------------------------------- | -------------------------------------------------------------- |
+| Endpoint URL | `https://<fara-endpoint>.<region>.inference.ml.azure.com/v1`  | `https://<brain-endpoint>.<region>.inference.ml.azure.com/v1`  |
+| Model Name   | `Fara1.5-9B`                                                  | `MagenticBrain-14B`                                            |
+| API Key      | the primary key from the Fara endpoint's Consume tab          | the primary key from the MagenticBrain endpoint's Consume tab  |
+
+Click **Verify & Save**. See [Verification fails](#verification-fails) below if you hit an error.
+
+### 3. Idle behavior and cost
+
+Foundry Managed Compute deployments **do not scale to zero**. The VM stays allocated and billed by the hour for as long as the deployment exists, whether or not traffic is flowing. An A100 deployment in East US 2 runs roughly $3–4 per hour at list price (H100 is roughly twice that); check the [Azure VM pricing page](https://azure.microsoft.com/pricing/details/virtual-machines/linux/) for current rates in your region. Multiply by the number of deployments you keep running.
+
+To stop the meter, **delete the deployment** from the **Models + endpoints** page. Redeploying from the catalog later takes the same ~15–20 minutes.
+
+---
+
+## Verification fails
+
+When you click **Verify & Save**, MagenticLite sends a probe request to the endpoint:
+
+- During onboarding, a successful verification finishes the onboarding flow and sends you to the sample-tasks page.
+- In Settings, the button updates to **Connection Verified** (with a check icon) once the endpoint responds.
+
+If verification fails, the banner usually pinpoints the problem:
+
+| Symptom (banner)                                                      | Likely cause                                                                                            |
+| --------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------- |
+| `Endpoint returned HTTP 401` or `403`                                 | API Key field is empty or wrong (different endpoints return one or the other for the same problem)      |
+| `Connection refused — is the server running?` or other network errors | Endpoint URL is wrong (typo in the host, missing `https://`, VPN/firewall issue)                        |

docs/troubleshooting.md

@@ -0,0 +1,87 @@
+# Troubleshooting
+
+## Model endpoint cold starts
+
+If you're using a managed model endpoint that scales to zero when idle (Hugging Face Inference Endpoints with scale-to-zero, for example), the **first call after the endpoint has been idle** may take **30–90 seconds** while the platform brings a replica back up. During that window you may see:
+
+- a `503` response or a `Verify & Save` error in MagenticLite's Settings, or
+- the first chat turn appearing to hang.
+
+Wait a minute and try again. Subsequent requests respond at normal speed until the endpoint scales to zero again.
+
+See the [Model Hosting Guide](./model-hosting-guide.md#a3-scale-to-zero-and-cold-starts) for the full explanation.
+
+## Settings → Models verification fails
+
+When you click **Verify & Save**, MagenticLite sends a probe request to the endpoint. Common failures:
+
+| Symptom (banner)                                                      | Likely cause                                                                                       |
+| --------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------- |
+| `Endpoint returned HTTP 401` or `403`                                 | API Key field is empty or wrong (different endpoints return one or the other for the same problem) |
+| `Endpoint returned HTTP 503` on the first attempt                     | Cold start — see the section above; wait a minute and click Verify again                           |
+| `Connection refused — is the server running?` or other network errors | Endpoint URL is wrong (typo in the host, missing `https://`, VPN/firewall issue)                   |
+
+Re-check the values against the source you copied them from (the Hugging Face dashboard, the Foundry deployment page, etc.) and try again.
+
+## Installation and runtime
+
+### `magentic-ui` command not found
+
+Your virtual environment isn't activated. Re-activate it and try again:
+
+```bash
+deactivate                    # if another env is active
+source .venv/bin/activate
+magentic-ui --port 8081
+```
+
+### Port 8081 already in use
+
+Another MagenticLite process is already running on the same port. Stop it, or run on a different port:
+
+```bash
+magentic-ui --port 8082
+```
+
+### Quicksand VM fails to start (Linux/WSL2)
+
+- Confirm KVM is available: `[ -e /dev/kvm ] && echo ok` should print `ok`.
+- Confirm your user is in the `kvm` group: `groups | grep -q kvm && echo ok`. If not, run `sudo usermod -aG kvm $USER` and restart your shell.
+- Without KVM the VM falls back to software emulation, which is significantly slower but should still work.
+
+### Browser viewer is blank or unresponsive
+
+- Make sure the Quicksand VM is healthy (check the MagenticLite logs for `quicksand` errors).
+- Check that any local firewall isn't blocking the noVNC port the app picks for the embedded browser viewer.
+- Restart MagenticLite — the browser is recreated on each session.
+
+## Coming from Magentic-UI 0.1.x?
+
+The 0.1.x line of Magentic-UI is still on PyPI under the same `magentic_ui` package name, and its on-disk data lives in the same default app directory. A few things to be aware of:
+
+### `pip install` picks up Magentic-UI 0.1.x instead of MagenticLite
+
+A plain `uv pip install magentic_ui` (no version pin) may resolve to a 0.1.x release. Pin to a 0.2.x version explicitly:
+
+```bash
+uv pip install "magentic_ui>=0.2.0"
+```
+
+(Adjust the version to whatever 0.2.x release you intend to run.)
+
+### MagenticLite reads / writes my old Magentic-UI 0.1.x data
+
+MagenticLite (0.2.x) doesn't migrate the 0.1.x database. By default both versions use the same app directory, which can lead to confusing state. To keep them separate, point MagenticLite at a different `--appdir`:
+
+```bash
+magentic-ui --port 8081 --appdir ~/.magentic-lite
+```
+
+## Still having issues?
+
+- Re-check the [Installation Guide](./installation.md) and [Configuration](./configuration.md).
+- Search [GitHub Issues](https://github.com/microsoft/magentic-ui/issues) for similar problems.
+- Open a new issue and include:
+  1. A detailed description of your problem
+  2. Information about your system (OS, hardware acceleration support, MagenticLite version)
+  3. Steps to reproduce the issue