EVMCOD · Oct 30, 2026 · Oct 30, 2026
diff --git a/README.md b/README.md
@@ -1,20 +1,52 @@
 # ConductLoop
 
-> Local-first second brain and AI-agent cockpit. Python + SQLite backend, native macOS app (Tauri), bring-your-own-key models.
+> Your notes, searchable and askable, on your own computer. Free and open source (MIT).
 
-ConductLoop indexes your own material — an Obsidian vault, memory/notes folders, code repositories, a skills directory, project playbooks and a list of URLs you want to watch — into a single local SQLite database with full-text search (FTS5), fuzzy matching and optional local semantic embeddings. On top of that index it runs a **Brain** (RAG chat with citations) and a set of AI agents/teams (Boardroom, tasks, runs, scheduler) using the model provider *you* configure.
+![ConductLoop: your notes, a box to ask, search and the recent notes](docs/screenshots/02-your-notes.png)
 
-- **Website:** <https://conductloop.com>
-- **macOS builds:** [EVMCOD/conductloop-releases](https://github.com/EVMCOD/conductloop-releases/releases/latest)
-- **Price:** free. There is no license gate, subscription or trial in the app.
+ConductLoop reads your notes (an Obsidian vault or any folder of Markdown) and lets you search them and ask questions about them. Answers come from your notes, with their sources. Everything stays on your computer: the index is a local SQLite file, and the AI is the model you choose, with your own key (Anthropic, OpenAI, MiniMax, any OpenAI-compatible server, or a local Ollama). Without a key it still searches, and answers with the lines of your notes that match.
 
-> The Python package is still named `ops_dashboard` for backwards compatibility. The product name is **ConductLoop**.
+It never writes into your notes folder: its own notes (daily briefing, agent notes) go to a folder of their own.
+
+## Download
+
+| System | Download | Notes |
+|---|---|---|
+| macOS 13 or later, Apple Silicon | [ConductLoop.dmg](https://github.com/EVMCOD/conductloop-releases/releases/latest/download/ConductLoop-macos-aarch64.dmg) | Signed and notarized. Updates itself (ConductLoop → Check for Updates…). The in-app browser needs macOS 14 or later. |
+| **Linux** x86_64 · beta | [AppImage](https://github.com/EVMCOD/conductloop-releases/releases/download/v1.2.3-linux-experimental.1/ConductLoop_1.2.3_amd64.AppImage) · [.deb](https://github.com/EVMCOD/conductloop-releases/releases/download/v1.2.3-linux-experimental.1/ConductLoop_1.2.3_amd64.deb) | Tested on Ubuntu 22.04 and 24.04. No in-app browser; no automatic updates yet. |
+| **Windows** 10/11 x64 · beta | [setup.exe](https://github.com/EVMCOD/conductloop-releases/releases/download/v1.2.3-windows-experimental.1/ConductLoop_1.2.3_x64-setup.exe) | Not code-signed, so SmartScreen says "Windows protected your PC": click **More info**, then **Run anyway**. No in-app browser; no automatic updates yet. |
+
+All releases, with checksums: [conductloop-releases](https://github.com/EVMCOD/conductloop-releases/releases).
+
+## The first minute
+
+1. **Open it.** The welcome page asks for the folder with your notes ("Choose…") and indexes it.
+2. **Ask or search** from the home page. Each result opens the note.
+3. **Optional:** paste an AI key in Credentials for written answers. It is stored in the system keychain (the Keychain on a Mac) or in an encrypted file, and never shown again.
+
+| Ask your notes | Search them |
+|---|---|
+| ![The Brain answering from the notes, with numbered sources](docs/screenshots/04-ask-your-notes.png) | ![Search results with the words around each match](docs/screenshots/03-search.png) |
+
+## And beyond your notes
+
+- **A team of AI agents.** Ask the CEO agent and it splits the work across a CTO, Head of Product, CMO and CFO, and writes one answer. Or create your own agents with tools and a schedule.
+- **Connectors** for GitHub, Slack, Gmail and more, read-only unless you allow writes; every write waits for your confirmation. They keep their tokens in the system keychain only, so they need macOS or Linux with a keyring.
+- **MCP both ways.** Plug MCP servers in as tools for your agents (read-only by default; anything that writes waits for you). From a source install, `ops mcp` lets Claude or another agent search and ask your notes.
+- **Backups** of the local database, daily and before every upgrade, restorable from Setup.
+- **It learns from your 👍/👎**: proposed rules that you approve, all stored on your computer.
+
+The screenshots use a fictional vault. Dark theme: ◐ in the corner.
 
 ---
 
-## Principles
+## For developers
 
-### Local-first
+> The Python package is still named `ops_dashboard` for backwards compatibility. The product name is **ConductLoop**.
+
+### Principles
+
+#### Local-first
 - The server is a stdlib `http.server` that binds to `127.0.0.1:7777` by default.
 - All indexed content, memory, tasks and settings live in a local SQLite file (`ops.db`). Location, in order of precedence:
   1. `$OPS_DATA_DIR/ops.db`
@@ -25,7 +57,7 @@ ConductLoop indexes your own material — an Obsidian vault, memory/notes folder
 - Error reporting to Sentry is **opt-in** (only if you set `SENTRY_DSN`).
 - If you install `sentence-transformers`, the embedding model (`all-MiniLM-L6-v2`) is downloaded once from Hugging Face and then runs locally.
 
-### BYOK (bring your own key)
+#### BYOK (bring your own key)
 The Brain talks directly to the provider you configure; nothing is proxied through ConductLoop servers.
 
 | Provider (`BRAIN_PROVIDER`) | Needs |
@@ -41,12 +73,9 @@ The Brain talks directly to the provider you configure; nothing is proxied throu
 
 ---
 
-## Install
-
-### macOS app
-Download the latest `.dmg` from [conductloop-releases](https://github.com/EVMCOD/conductloop-releases/releases/latest), drag ConductLoop to `/Applications` and open it. Requires **macOS 13 (Ventura) or later** on Apple Silicon; the built-in browser needs **macOS 14 (Sonoma) or later** (on macOS 13 everything else works). The app is a Tauri v2 shell that starts the bundled Python server as a sidecar and shows it in a native WebView.
+### Install
 
-### From source (macOS / Linux)
+#### From source (macOS / Linux)
 Requires Python **3.13+** (CI runs 3.14).
 
 ```bash
@@ -71,14 +100,14 @@ Dependency sets:
 
 `pip install -e .` also installs the `ops` CLI entry point.
 
-### Configuration
+#### Configuration
 A fresh install is empty: no projects, teams or URLs. Point it at your content with environment variables (see `.env.example`), e.g. `OPS_VAULT_ROOT`, `OPS_WORKSPACE`, `OPS_SKILLS_DIR`, `OPS_REPOS`, `OPS_PROJECTS_FILE`, `OPS_LIVE_URLS_FILE`. Set `CONDUCTLOOP_DEMO=1` (with a throwaway `CONDUCTLOOP_DB_PATH` and `OPS_DATA_DIR`) to load fictional demo data instead; see [`docs/FIRST-5-MINUTES.md`](docs/FIRST-5-MINUTES.md).
 
 Optional notification webhooks (Slack / Discord / Telegram) are described in `config.example.json`. Remote access from a phone is documented in [`docs/REMOTE.md`](docs/REMOTE.md) (Tailscale; nothing is exposed publicly by default).
 
 ---
 
-## Usage
+### Usage
 
 ```bash
 make help        # list targets
@@ -94,7 +123,7 @@ Selected `ops` / `python -m ops_dashboard` commands: `index`, `find`, `brain`, `
 
 ---
 
-## Development
+### Development
 
 ```bash
 python3 -m venv .venv && . .venv/bin/activate
@@ -108,7 +137,7 @@ pytest -m "not live"                # hermetic test suite (what CI runs)
 
 Tests marked `live` need the network or real credentials; they never run by default or in CI.
 
-### Layout
+#### Layout
 ```
 ops_dashboard/          Python package: server.py (HTTP API + UI), cli.py (typer CLI),
                         db*.py (SQLite schema/queries), brain.py (RAG + providers),
@@ -119,16 +148,16 @@ scripts/, bin/          launchd jobs, release and maintenance scripts
 tests/                  pytest suite
 ```
 
-### Desktop app
+#### Desktop app
 See [`desktop/README.md`](desktop/README.md) and [`desktop/docs/DISTRIBUTION.md`](desktop/docs/DISTRIBUTION.md). Building and signing a release needs your own Apple Developer ID and your own Tauri updater key; neither is in this repository.
 
 Linux (experimental) and Windows are **not shipped**. [`docs/PORTABILITY.md`](docs/PORTABILITY.md) is the audit of everything that is macOS-only today, with the plan to port it.
 
 ---
 
-## Contributing & security
+### Contributing & security
 - [CONTRIBUTING.md](CONTRIBUTING.md)
 - [SECURITY.md](SECURITY.md) — please report vulnerabilities privately, not in public issues.
 
-## License
+### License
 [MIT](LICENSE). The ConductLoop name and logo are not covered by the license.
diff --git a/docs/screenshots/01-welcome.png b/docs/screenshots/01-welcome.png
diff --git a/docs/screenshots/02-your-notes.png b/docs/screenshots/02-your-notes.png
diff --git a/docs/screenshots/03-search.png b/docs/screenshots/03-search.png
diff --git a/docs/screenshots/04-ask-your-notes.png b/docs/screenshots/04-ask-your-notes.png
diff --git a/docs/screenshots/07-your-notes-dark.png b/docs/screenshots/07-your-notes-dark.png