diff --git a/README.md b/README.md
new file mode 100644
index 0000000..2648a69
--- /dev/null
+++ b/README.md
@@ -0,0 +1,110 @@
+<div align="center">
+
+<img src="assets/gitnexus-logo.svg" alt="NexusOS" width="96">
+
+# NexusOS
+
+**A local-first AI assistant platform.** Runs entirely on your machine — a
+Python/FastAPI backend, a bundled Ollama instance for inference, a persistent
+memory service, and a React frontend. No external AI provider is called.
+
+</div>
+
+---
+
+## What it is
+
+NexusOS ("Nexus") is a self-hosted assistant you actually own. All inference
+runs through a **locally bundled Ollama** on `localhost`; conversations, facts,
+and settings live in local SQLite. It ships with desktop branding (XFCE theme,
+icons, boot splash) so it can be run as a full assistant environment, not just
+a web app.
+
+- **Chat** — streaming responses from local Ollama models (SSE).
+- **Persistent memory** — a dedicated service auto-extracts durable facts from
+  each exchange and layers them into future prompts.
+- **Playbooks** — ordered YAML system-prompt records; the first is the active
+  persona, the rest are injected as reference context.
+- **Model management** — list, pull, and delete Ollama models from the UI/CLI.
+- **History** — full conversation persistence, search, edit, export.
+
+## Quick start
+
+Requires Python 3, Node, and a GPU is optional (CPU works).
+
+```bash
+# 1. Install deps into the Promethean venv (auto-selects AMD/NVIDIA/CPU)
+./bin/install.sh
+
+# 2. Launch the full stack (memory :8001, backend :8000, frontend :5173)
+./launch_nexus.sh
+```
+
+Python deps are layered: `requirements-base.txt` (GPU-agnostic core) plus one
+overlay — `requirements-amd.txt` (ROCm), `requirements-nvidia.txt` (CUDA), or
+`requirements-wsl.txt` (CPU-only). `bin/install.sh` picks the right one for the
+host.
+
+### Individual services
+
+```bash
+source Promethean/bin/activate
+
+uvicorn synapse.main:sio_app          --host 0.0.0.0 --port 8000 --reload   # backend
+uvicorn synapse.memory.service:app    --host 0.0.0.0 --port 8001 --reload   # memory
+cd interface/web && npm run dev                                             # frontend
+```
+
+## CLI (`ncp`)
+
+Start/stop services and drive the same features as the web UI over the REST API:
+
+```bash
+./management/nexus-cli.sh start        # backend + frontend (--backend|--frontend|--memory)
+./management/nexus-cli.sh stop
+
+ncp chat "<message>"                   # stream a reply
+ncp memory list | add <text> | rm <id>
+ncp playbook list | show <id>          # first playbook (*) = active system prompt
+ncp history [query]                    # recent conversations
+```
+
+## Architecture
+
+| Component | Location | Role |
+|---|---|---|
+| **Synapse** (backend) | `synapse/` | FastAPI app. `/chat/stream`, `/playbooks`, `/memory`, `/models`, `/conversations`, `/settings`, `/ollama`, `/icons`. Assembles the system prompt: active playbook → reference playbooks → memory facts → relevant past snippets. |
+| **Memory service** | `synapse/memory/` | Separate FastAPI app (:8001). `/memories/extract` uses an Ollama prompt to decide what to persist. Shares the SQLite DB with the backend. |
+| **Playbooks** | `synapse/playbooks/` + `data/playbooks/` | Ordered `{id}.yaml` records managed by `PlaybookManager`. |
+| **Ollama** | `ollama/bin/ollama` | Bundled binary; `OllamaManager` handles lifecycle + model selection (Vulkan GPU detection). HTTP API at `127.0.0.1:11434`. |
+| **Frontend** | `interface/web/` | React 19 + Vite. Pages: Chat, Playbooks, History, Models, Memory, Settings. |
+
+### Storage
+
+Most data lives in `synapse/memory/memory.db` (SQLite, WAL) — facts,
+conversations, messages, settings. Playbooks are the exception (YAML files in
+`data/playbooks/`). All paths are defined in `synapse/nexus_config.py`.
+
+## Layout
+
+```
+synapse/          FastAPI backend + memory service + playbook/ollama managers
+interface/web/    React + Vite frontend
+management/       nexus-cli.sh, ncp API client, control panel, desktop theme
+bin/              install, backup/restore, panel + provisioning scripts
+assets/           branding: icons, boot splash, XFCE/GTK theme
+data/playbooks/   active playbook YAML
+```
+
+## Configuration
+
+| Concern | Location |
+|---|---|
+| Ollama host | `OLLAMA_HOST` env (default `http://127.0.0.1:11434`) |
+| Filesystem paths | `synapse/nexus_config.py` |
+| Frontend API base URL | `interface/web/src/config.js` |
+| Python deps | `requirements-base.txt` + amd/nvidia/wsl overlay |
+
+---
+
+<div align="center"><sub>NexusOS · local AI, self-hosted on <a href="https://git.enderofwings.com/enderofwings/NexusOS">GitNexus</a></sub></div>