docs(evals): rewrite evaluations guide to match the real CLI surface; add openjarvis-eval alias (#534 )

docs/user-guide/evaluations.md documented a standalone "openjarvis-evals" package, a "uv sync --extra eval" install, and an "openjarvis-eval" console script — a layout from commit bd493832 that was never an ancestor of main. Rewrite the page against the real surface (jarvis eval / python -m openjarvis.evals), document all 40 registered benchmark keys and 4 backends, fix the judge-model default, correct run-all semantics, and split the option reference into the jarvis-eval subset and the module CLI's research-only options. Add the one-line [project.scripts] alias openjarvis-eval = "openjarvis.evals.cli:main" (the click group the module CLI already dispatches to) so the long-documented command name works again. The page was a complete orphan: add it (and the equally orphaned benchmarks.md) to the mkdocs nav and link it from docs/index.md. Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
fix(evals): honor --base-url/--api-key for first-party eval backends (#535 )
2026-08-14 08:52:06 +00:00 · 2026-06-11 13:50:17 -07:00 · 2026-06-11 13:49:37 -07:00 · 2026-06-11 07:44:18 +00:00 · 2026-06-10 19:52:36 -07:00 · 2026-06-10 19:15:57 -07:00
265 changed files with 21654 additions and 1987 deletions
@@ -1,7 +1,7 @@
 {
  "schemaVersion": 1,
  "label": "Git Clones",
-  "message": "77,239",
+  "message": "110,366",
  "color": "green",
  "namedLogo": "git"
 }
@@ -1,6 +1,6 @@
 {
-  "total_clones": 77239,
-  "last_updated": "2026-05-25T07:37:53Z",
+  "total_clones": 110366,
+  "last_updated": "2026-06-11T07:44:18Z",
  "daily": {
    "2026-03-27": 2189,
    "2026-03-28": 1874,
@@ -60,6 +60,23 @@
    "2026-05-21": 1605,
    "2026-05-22": 612,
    "2026-05-23": 2437,
-    "2026-05-24": 4900
+    "2026-05-24": 4900,
+    "2026-05-25": 1319,
+    "2026-05-26": 1199,
+    "2026-05-27": 898,
+    "2026-05-28": 1276,
+    "2026-05-29": 2950,
+    "2026-05-30": 4338,
+    "2026-05-31": 1887,
+    "2026-06-01": 2072,
+    "2026-06-02": 1847,
+    "2026-06-03": 2164,
+    "2026-06-04": 2632,
+    "2026-06-05": 2127,
+    "2026-06-06": 2204,
+    "2026-06-07": 1174,
+    "2026-06-08": 2369,
+    "2026-06-09": 1361,
+    "2026-06-10": 1310
  }
 }
@@ -64,7 +64,7 @@ jobs:

      - name: Run tests
        run: |
-          uv run pytest tests/ -v --tb=short -m "not live and not cloud" \
+          uv run pytest tests/ -v --tb=short -m "not live and not cloud and not hub" \
            --cov=openjarvis \
            --cov-report=term-missing \
            --cov-report=xml \
@@ -90,13 +90,20 @@ jobs:
  # interpolation), so there is no workflow-injection surface here.
  test-windows:
    runs-on: windows-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        # 3.12 = common; 3.13 = the supported ceiling — installing there guards
+        # against a numpy/native wheel gap at the top of the range (#350), which
+        # is exactly how the source-build failure slips in on Windows.
+        python-version: ["3.12", "3.13"]
    steps:
      - uses: actions/checkout@v6

      - name: Set up Python
        uses: actions/setup-python@v6
        with:
-          python-version: "3.12"
+          python-version: ${{ matrix.python-version }}

      - name: Install uv
        uses: astral-sh/setup-uv@v8.0.0
@@ -39,6 +39,9 @@ Thumbs.db
 # Secrets
 .env
 .env.*
+# ...but keep checked-in example/templates (never contain real secrets)
+!.env.example
+!**/.env.example

 # Project
 *.sqlite
@@ -122,3 +125,8 @@ learning.db
 **/learning/benchmarks/
 **/teacher_traces/
 *.session.json
+
+# Local dev artifacts (hybrid worker logs + cli debug dumps)
+minion_logs/
+*.oj-debug.json
+oj-debug.*.json
@@ -8,17 +8,25 @@
    <a href="https://open-jarvis.github.io/OpenJarvis/"><img src="https://img.shields.io/badge/docs-mkdocs-blue" alt="Docs"></a>
    <img src="https://img.shields.io/badge/python-%3E%3D3.10-blue" alt="Python">
    <img src="https://img.shields.io/badge/license-Apache%202.0-green" alt="License">
-    <a href="https://discord.gg/YZZRxCAhmm"><img src="https://img.shields.io/badge/discord-join-7289da?logo=discord&logoColor=white" alt="Discord"></a>
+    <a href="https://discord.gg/CMVBmDQ5Fj"><img src="https://img.shields.io/badge/discord-join-7289da?logo=discord&logoColor=white" alt="Discord"></a>
    <a href="https://x.com/OpenJarvisAI"><img src="https://img.shields.io/badge/X-@OpenJarvisAI-black?logo=x&logoColor=white" alt="X / Twitter"></a>
  </p>
 </div>

 ---

+<div align="center">
+  <img alt="OpenJarvis demo reel" src="assets/openjarvis_demo_reel.webp" width="75%">
+</div>
+
+---
+
 > **[Documentation](https://open-jarvis.github.io/OpenJarvis/)**
 >
 > **[Project Site](https://scalingintelligence.stanford.edu/blogs/openjarvis/)**
 >
+> **[Paper](https://arxiv.org/abs/2605.17172)**
+>
 > **[Leaderboard](https://open-jarvis.github.io/OpenJarvis/leaderboard/)**
 >
 > **[Roadmap](https://open-jarvis.github.io/OpenJarvis/development/roadmap/)**
@@ -31,78 +39,44 @@ OpenJarvis is that stack. It is a framework for local-first personal AI, built a

 ## Installation

-**macOS / Linux:**
+Pick your platform and run one command. Each installer handles [uv](https://docs.astral.sh/uv/), the Python venv, Ollama, and a starter model — about 3 minutes on broadband.

-```bash
-curl -fsSL https://open-jarvis.github.io/OpenJarvis/install.sh | bash
-```
+| Platform | One-liner |
+|---|---|
+| **macOS · Linux · WSL2** | `curl -fsSL https://open-jarvis.github.io/OpenJarvis/install.sh \| bash` |
+| **Native Windows** | `irm https://open-jarvis.github.io/OpenJarvis/install.ps1 \| iex` |
+| **Desktop GUI** | Download `.exe` / `.dmg` / `.deb` / `.rpm` / `.AppImage` from the [latest release](https://github.com/open-jarvis/OpenJarvis/releases) |

-The installer handles everything for you — including [uv](https://docs.astral.sh/uv/), the Python venv, Ollama, and a small starter model. You don't need to install anything first.
+Then `jarvis` to start. The Rust extension and larger models continue downloading in the background; `jarvis doctor` shows status.

-**Windows:** the installer is a `bash` script and won't run in PowerShell or `cmd`. Pick one of:
-
- **WSL2 (recommended for the CLI / Python SDK)** — one-time setup in an admin PowerShell, then run the same `curl … | bash` inside Ubuntu:
-  ```powershell
-  wsl --install -d Ubuntu-24.04
-  ```
-  Open the Ubuntu shell that gets installed, then follow [WSL2 install instructions](https://open-jarvis.github.io/OpenJarvis/getting-started/wsl2/).
- **Desktop app** — download the [Windows installer (`.exe`)](https://github.com/open-jarvis/OpenJarvis/releases/download/desktop-v1.0.2/OpenJarvis_1.0.1_x64-setup.exe) from the latest [desktop release](https://github.com/open-jarvis/OpenJarvis/releases/tag/desktop-v1.0.2) (macOS `.dmg` and Linux `.deb`/`.rpm`/`.AppImage` are there too) for the GUI experience, no terminal required. **Prerequisite:** the desktop app expects [uv](https://docs.astral.sh/uv/) to be installed already — if it isn't, install it first in PowerShell, then launch the app:
-  ```powershell
-  powershell -ExecutionPolicy Bypass -c "irm https://astral.sh/uv/install.ps1 | iex"
-  ```
-
-About 3 minutes on a typical broadband connection. Then:
-
-```bash
-jarvis
-```
-
-The Rust extension and bigger models continue downloading in the background while you chat. Run `jarvis doctor` to see status.
-
-**Platforms:** macOS (Intel + Apple Silicon), Linux, WSL2 on Windows. Native Windows is not supported — use WSL2 or the desktop binary.
-
-**Manual install / contributors:** see [docs/getting-started/install.md](docs/getting-started/install.md).
+Platform-specific notes (WSL2 setup, native-Windows scheduled-task service, desktop prerequisites, manual / contributor install): see the [installation docs](https://open-jarvis.github.io/OpenJarvis/getting-started/install/).

 ## Quick Start

 ```bash
-curl -fsSL https://open-jarvis.github.io/OpenJarvis/install.sh | bash
-jarvis
+jarvis                          # start chatting (default: chat-simple)
+jarvis init --preset <name>     # switch to a starter config
 ```

-`jarvis init --preset <name>` switches to a starter config. Available presets: `morning-digest-mac`, `morning-digest-linux`, `morning-digest-minimal`, `deep-research`, `code-assistant`, `scheduled-monitor`, `chat-simple`.
+> Prefix `jarvis ...` with `uv run`, or `source .venv/bin/activate` first.

-## Starter Configs
+| Preset | What it does |
+|---|---|
+| `morning-digest-mac` / `morning-digest-linux` / `morning-digest-minimal` | Spoken daily briefing from email, calendar, health, news |
+| `deep-research` | Multi-hop research across indexed docs with citations |
+| `code-assistant` | Agent with code execution, file I/O, and shell access |
+| `scheduled-monitor` | Stateful agent on a schedule with memory |
+| `chat-simple` | Lightweight conversation, no tools |

-Install any preset with one command:
+Example:

 ```bash
-uv run jarvis init --preset morning-digest-mac   # or any preset below
+jarvis init --preset morning-digest-mac
+jarvis connect gdrive          # one OAuth covers Gmail / Calendar / Tasks
+jarvis digest --fresh          # generate and play your first briefing
 ```

-> Prefix every `jarvis ...` invocation with `uv run`, or activate the venv first (`source .venv/bin/activate`) so plain `jarvis ...` works for the rest of your shell session.
-
-| Preset | Use Case | What it does |
-|--------|----------|-------------|
-| `morning-digest-mac` | Daily Briefing (Mac) | Spoken briefing from email, calendar, health, news with Jarvis voice |
-| `morning-digest-linux` | Daily Briefing (Linux) | Same, with vLLM support for GPU servers |
-| `morning-digest-minimal` | Daily Briefing (minimal) | Just Gmail + Calendar, runs on any machine |
-| `deep-research` | Research Assistant | Multi-hop research across indexed docs with citations |
-| `code-assistant` | Code Companion | Agent with code execution, file I/O, and shell access |
-| `scheduled-monitor` | Persistent Monitor | Stateful agent that runs on a schedule with memory |
-| `chat-simple` | Simple Chat | Lightweight conversation, no tools needed |
-
-```bash
-# Example: Morning Digest on Mac
-uv run jarvis init --preset morning-digest-mac
-uv run jarvis connect gdrive          # one OAuth flow covers Gmail, Calendar, Tasks
-uv run jarvis digest --fresh          # generate and play your first briefing
-
-# Example: Deep Research
-uv run jarvis init --preset deep-research
-uv run jarvis memory index ./docs/    # requires the Rust extension — see Setup above
-uv run jarvis ask "Summarize all emails about Project X"
-```
+Per-preset deep dives: [morning digest](https://open-jarvis.github.io/OpenJarvis/user-guide/morning-digest/) · [deep research](https://open-jarvis.github.io/OpenJarvis/user-guide/deep-research/) · [code assistant](https://open-jarvis.github.io/OpenJarvis/user-guide/code-assistant/) · [scheduled monitor](https://open-jarvis.github.io/OpenJarvis/user-guide/scheduled-monitor/) · [chat simple](https://open-jarvis.github.io/OpenJarvis/user-guide/chat-simple/) · or the full [quickstart guide](https://open-jarvis.github.io/OpenJarvis/getting-started/quickstart/).

 ### Skills

@@ -149,7 +123,7 @@ Full documentation — including Docker deployment, cloud engines, development s
 ## Community

 - **GitHub:** [github.com/open-jarvis/OpenJarvis](https://github.com/open-jarvis/OpenJarvis)
- **Discord:** [discord.gg/YZZRxCAhmm](https://discord.gg/YZZRxCAhmm)
+- **Discord:** [discord.gg/CMVBmDQ5Fj](https://discord.gg/CMVBmDQ5Fj)
 - **X / Twitter:** [@OpenJarvisAI](https://x.com/OpenJarvisAI)
 - **Docs:** [open-jarvis.github.io/OpenJarvis](https://open-jarvis.github.io/OpenJarvis/)

@@ -106,6 +106,11 @@ enabled = true                            # Record traces for analysis
 db_path = "~/.openjarvis/traces.db"

 [server]
-host = "0.0.0.0"
+# Bind to loopback by default so the API is not exposed to the local network.
+# To serve other devices on your LAN, set host = "0.0.0.0" AND set an API key
+# (OPENJARVIS_API_KEY / `jarvis auth generate-key`) — startup refuses a
+# non-loopback bind without a key. The "server" security profile also flips
+# this to 0.0.0.0 intentionally.
+host = "127.0.0.1"
 port = 8000
 agent = "native_openhands"
@@ -0,0 +1,7 @@
+# Copy to `.env` in this directory (deploy/docker/.env) before `docker compose up`.
+# docker-compose.yml requires this — the container binds 0.0.0.0, so the
+# server refuses to start without an API key.
+#
+# Generate a key with:  jarvis auth generate-key
+# Then clients must send:  Authorization: Bearer <key>
+OPENJARVIS_API_KEY=
@@ -13,6 +13,8 @@ FROM python:3.12-slim-bookworm AS builder
 WORKDIR /app
 COPY pyproject.toml README.md ./
 COPY src/ src/
+COPY scripts/install scripts/install
+COPY deploy/windows deploy/windows

 # Copy built frontend into the server static directory
 COPY --from=frontend /src/openjarvis/server/static src/openjarvis/server/static/
@@ -17,6 +17,8 @@ RUN apt-get update && \
 WORKDIR /app
 COPY pyproject.toml README.md ./
 COPY src/ src/
+COPY scripts/install scripts/install
+COPY deploy/windows deploy/windows

 COPY --from=frontend /src/openjarvis/server/static src/openjarvis/server/static/

@@ -17,6 +17,8 @@ RUN apt-get update && \
 WORKDIR /app
 COPY pyproject.toml README.md ./
 COPY src/ src/
+COPY scripts/install scripts/install
+COPY deploy/windows deploy/windows

 COPY --from=frontend /src/openjarvis/server/static src/openjarvis/server/static/

@@ -8,6 +8,10 @@ services:
    environment:
      - OPENJARVIS_ENGINE_DEFAULT=ollama
      - OLLAMA_HOST=http://ollama:11434
+      # The container binds 0.0.0.0, so an API key is REQUIRED. Compose fails
+      # fast if OPENJARVIS_API_KEY is unset (set it in deploy/docker/.env —
+      # see .env.example, or `export` it). Generate one: `jarvis auth generate-key`.
+      - OPENJARVIS_API_KEY=${OPENJARVIS_API_KEY:?OPENJARVIS_API_KEY must be set (see deploy/docker/.env.example)}
    depends_on:
      ollama:
        condition: service_healthy
@@ -4,15 +4,27 @@
 <dict>
    <key>Label</key>
    <string>com.openjarvis</string>
+    <!-- Binds loopback only: the personal-device default, reachable from this
+         Mac but not the network, so no API key is required. To expose it on
+         your LAN, change the host below to 0.0.0.0 AND uncomment the
+         EnvironmentVariables block to set an API key (an unauthenticated
+         0.0.0.0 server will refuse to start). -->
    <key>ProgramArguments</key>
    <array>
        <string>/usr/local/bin/jarvis</string>
        <string>serve</string>
        <string>--host</string>
-        <string>0.0.0.0</string>
+        <string>127.0.0.1</string>
        <string>--port</string>
        <string>8000</string>
    </array>
+    <!--
+    <key>EnvironmentVariables</key>
+    <dict>
+        <key>OPENJARVIS_API_KEY</key>
+        <string>REPLACE_WITH_A_REAL_KEY</string>
+    </dict>
+    -->
    <key>RunAtLoad</key>
    <true/>
    <key>KeepAlive</key>
@@ -10,6 +10,11 @@ ExecStart=/opt/openjarvis/.venv/bin/jarvis serve --host 0.0.0.0 --port 8000
 Restart=on-failure
 RestartSec=5
 Environment=HOME=/opt/openjarvis
+# Binding 0.0.0.0 requires authentication. This file MUST exist and contain:
+#   OPENJARVIS_API_KEY=<key>      (generate one: `jarvis auth generate-key`)
+# It is not prefixed with "-", so the unit fails to start if the file is
+# missing — preventing an accidentally unauthenticated public server.
+EnvironmentFile=/etc/openjarvis/env

 [Install]
 WantedBy=multi-user.target
@@ -0,0 +1,126 @@
+# OpenJarvis on native Windows
+
+Phase-1 of the native-Windows-support RFC (#298). Mirrors the Linux
+(`deploy/systemd/`) and macOS (`deploy/launchd/`) deployments — but for
+PowerShell, without WSL2 or Docker.
+
+## One-liner install
+
+In an elevated-or-regular PowerShell:
+
+```powershell
+irm https://open-jarvis.github.io/OpenJarvis/install.ps1 | iex
+```
+
+What it does:
+
+1. Refuses non-Windows hosts and Windows < 10 1809.
+2. Checks Python 3.10 – 3.13 (3.14 has no numpy wheels yet — see #432).
+3. Checks `git` on PATH.
+4. Installs `uv` (https://astral.sh/uv) if absent.
+5. Clones the OpenJarvis repository to `%LOCALAPPDATA%\OpenJarvis`
+   (override with `$env:OPENJARVIS_HOME`).
+6. Runs `uv sync --extra server` so the FastAPI server entry point is
+   importable.
+7. Optionally prompts to register a scheduled task that auto-starts the
+   server at logon.
+
+Flags (when invoked directly rather than via `irm | iex`):
+
+| Flag | Effect |
+|------|--------|
+| `-Service` | Register the scheduled task without prompting |
+| `-SkipService` | Don't prompt; don't register |
+| `-Force` | Re-run all steps even if already done |
+
+`irm | iex` can't pass `param()` args into a piped script string, so
+the same knobs are honored via env vars when the corresponding flag is
+absent:
+
+```powershell
+$env:OPENJARVIS_SKIP_SERVICE = '1'
+irm https://open-jarvis.github.io/OpenJarvis/install.ps1 | iex
+```
+
+The available env vars: `OPENJARVIS_SKIP_SERVICE`, `OPENJARVIS_SERVICE`,
+`OPENJARVIS_FORCE`. If you need richer control, save the script first
+(`irm ... -OutFile install.ps1; .\install.ps1 -Force`).
+
+## Manual scheduled-task setup
+
+If you skipped the prompt during install, you can register / inspect /
+remove the task with `jarvis-service.ps1`:
+
+```powershell
+$srv = "$env:LOCALAPPDATA\OpenJarvis\src\deploy\windows\jarvis-service.ps1"
+
+# install (idempotent — replaces existing)
+powershell -ExecutionPolicy Bypass -File $srv install
+
+# status
+powershell -ExecutionPolicy Bypass -File $srv status
+
+# remove
+powershell -ExecutionPolicy Bypass -File $srv uninstall
+```
+
+The task runs as the current user with `LogonType=Interactive` and
+`RunLevel=Limited`. It restarts up to 3 times on failure (1-minute
+gap), has no execution-time limit, and starts when available (catches
+up if missed).
+
+## Loopback vs LAN-exposed
+
+By default the scheduled task binds `127.0.0.1` — reachable only from
+this machine, no API key required. This matches launchd parity (see
+`deploy/launchd/com.openjarvis.plist`).
+
+To expose on your LAN:
+
+```powershell
+# 1. Generate an API key. The server REFUSES to bind 0.0.0.0 without one.
+$env:OPENJARVIS_API_KEY = (uv run jarvis auth generate-key)
+
+# 2. Re-register the task with -ListenHost 0.0.0.0.
+powershell -ExecutionPolicy Bypass -File $srv install -ListenHost 0.0.0.0
+```
+
+`jarvis-service.ps1 install` refuses `-ListenHost 0.0.0.0` if
+`$env:OPENJARVIS_API_KEY` is unset — same guard as the systemd unit's
+`EnvironmentFile=/etc/openjarvis/env`.
+
+## Parity table
+
+| Concern | systemd | launchd | Windows |
+|---------|---------|---------|---------|
+| Service definition | `deploy/systemd/openjarvis.service` | `deploy/launchd/com.openjarvis.plist` | `deploy/windows/jarvis-service.ps1` (cmdlet-driven) |
+| Default bind | `0.0.0.0` (with API key) | `127.0.0.1` (no API key) | `127.0.0.1` (no API key) |
+| Restart on failure | `Restart=on-failure RestartSec=5` | `KeepAlive=true` | `RestartCount=3 RestartInterval=PT1M` |
+| Auto-start | `multi-user.target` | `RunAtLoad=true` | `AtLogOn` trigger |
+
+## Updating
+
+To pull the latest:
+
+```powershell
+cd "$env:LOCALAPPDATA\OpenJarvis\src"
+git pull --ff-only
+uv sync --extra server
+```
+
+Or re-run the installer with `-Force`:
+
+```powershell
+irm https://open-jarvis.github.io/OpenJarvis/install.ps1 | iex
+# (then re-run with the file directly, passing -Force)
+```
+
+## Uninstall
+
+```powershell
+powershell -ExecutionPolicy Bypass -File "$env:LOCALAPPDATA\OpenJarvis\src\deploy\windows\jarvis-service.ps1" uninstall
+Remove-Item -Recurse -Force "$env:LOCALAPPDATA\OpenJarvis"
+```
+
+Uninstalling does NOT remove `uv` (it's a separate tool — you may have
+other Python projects using it).
@@ -0,0 +1,529 @@
+<#
+.SYNOPSIS
+    OpenJarvis native Windows installer.
+
+.DESCRIPTION
+    Phase-1 of the native-Windows-support RFC (#298). Mirrors the
+    behavior of scripts/install/install.sh (the curl-pipe-bash installer
+    for Linux/WSL2/macOS) but for native Windows PowerShell - no WSL,
+    no Docker, no MSYS2.
+
+    Steps:
+      1. Refuse non-Windows / Windows < 10.
+      2. Check Python 3.10 - 3.13 on PATH (3.14 has no numpy wheels yet,
+         see #432).
+      3. Check git on PATH.
+      4. Install uv (https://astral.sh/uv) if absent.
+      5. Clone the OpenJarvis repository to $env:LOCALAPPDATA\OpenJarvis
+         (override with $env:OPENJARVIS_HOME).
+      6. Run `uv sync --extra server` so the FastAPI server entry point
+         is importable.
+      7. Optionally register the scheduled-task service (see
+         deploy/windows/jarvis-service.ps1).
+
+    Usage (one-liner):
+      irm https://open-jarvis.github.io/OpenJarvis/install.ps1 | iex
+
+    Usage (file invocation, supports flags):
+      irm https://open-jarvis.github.io/OpenJarvis/install.ps1 -OutFile install.ps1
+      .\install.ps1 -SkipService
+
+    Flags (when running the file directly):
+      -SkipService    Don't prompt for / install the scheduled task.
+      -Service        Install the scheduled task without prompting.
+      -Force          Re-run all steps even if already done.
+
+    Under `irm | iex` the param block is unreachable (Invoke-Expression
+    can't pass named args into a piped script string), so the same knobs
+    are honored via env vars when the corresponding flag is absent:
+      $env:OPENJARVIS_SKIP_SERVICE = '1'
+      $env:OPENJARVIS_SERVICE      = '1'
+      $env:OPENJARVIS_FORCE        = '1'
+
+.NOTES
+    Loopback default: the scheduled-task service binds 127.0.0.1, so no
+    API key is needed. To expose on the LAN, edit the registered task to
+    pass `--host 0.0.0.0` AND set $env:OPENJARVIS_API_KEY (an
+    unauthenticated 0.0.0.0 server refuses to start). See
+    deploy/windows/README.md.
+#>
+
+[CmdletBinding()]
+param(
+    [switch] $SkipService,
+    [switch] $Service,
+    [switch] $Force
+)
+
+$ErrorActionPreference = 'Stop'
+
+# Env-var fallback for the `irm | iex` path, where the param block is
+# unreachable (see header comment). Any explicit -switch wins; env vars
+# only fill in the gaps.
+if (-not $SkipService -and $env:OPENJARVIS_SKIP_SERVICE) { $SkipService = $true }
+if (-not $Service     -and $env:OPENJARVIS_SERVICE)      { $Service     = $true }
+if (-not $Force       -and $env:OPENJARVIS_FORCE)        { $Force       = $true }
+
+# ---------------------------------------------------------------------------
+# Output helpers - coloured but plain enough for Constrained Language Mode.
+# ---------------------------------------------------------------------------
+
+function Write-Info  ($msg) { Write-Host "[info]  $msg" -ForegroundColor Cyan }
+function Write-Ok    ($msg) { Write-Host "[ok]    $msg" -ForegroundColor Green }
+function Write-Warn2 ($msg) { Write-Host "[warn]  $msg" -ForegroundColor Yellow }
+function Write-Fail  ($msg) {
+    Write-Host "[fail]  $msg" -ForegroundColor Red
+    exit 1
+}
+
+# ---------------------------------------------------------------------------
+# Shared helpers - winget bootstrap + PATH refresh
+# ---------------------------------------------------------------------------
+
+# Pull the latest Machine + User PATH from the registry into the current
+# PowerShell session. Tools installed by `winget install` (Python, git,
+# Ollama, etc.) update the User PATH, but the running process inherits
+# the parent shell's environment - so without this refresh the just-
+# installed tool stays invisible to subsequent `Get-Command` calls.
+#
+# CRITICAL: registry PATH entries can be REG_EXPAND_SZ (with literal
+# `%VAR%` placeholders); the Python.org installer in per-user mode adds
+# entries like `%LOCALAPPDATA%\Programs\Python\Python313\` unexpanded.
+# `GetEnvironmentVariable` returns the raw string and PowerShell does
+# NOT auto-expand on assignment to `$env:Path`, so `Get-Command python`
+# would miss the just-installed binary. Expand explicitly.
+function Update-PathFromRegistry {
+    $machinePath = [System.Environment]::GetEnvironmentVariable('Path', 'Machine')
+    $userPath    = [System.Environment]::GetEnvironmentVariable('Path', 'User')
+    $combined    = "$machinePath;$userPath"
+    $env:Path = [System.Environment]::ExpandEnvironmentVariables($combined)
+}
+
+# Bootstrap a tool by winget id. Returns the resolved command source on
+# success, $null on failure. Caller decides whether failure is fatal.
+function Install-WithWinget {
+    param(
+        [string] $WingetId,    # e.g. 'Python.Python.3.13'
+        [string] $CommandName  # e.g. 'python' or 'git'
+    )
+    if (-not (Get-Command winget -ErrorAction SilentlyContinue)) {
+        # Windows 10 pre-2004 / Windows Server / locked-down corporate
+        # images may not have winget. Fall back to the caller's manual
+        # instructions.
+        return $null
+    }
+    Write-Info "  Installing $WingetId via winget (silent)..."
+    & winget install --id $WingetId --silent --accept-source-agreements --accept-package-agreements 2>&1 | Out-Null
+    if ($LASTEXITCODE -ne 0) {
+        Write-Warn2 "  winget install $WingetId exited $LASTEXITCODE"
+        return $null
+    }
+    Update-PathFromRegistry
+    $cmd = Get-Command $CommandName -ErrorAction SilentlyContinue
+    if ($cmd) { return $cmd.Source }
+    return $null
+}
+
+# ---------------------------------------------------------------------------
+# 1. OS check
+# ---------------------------------------------------------------------------
+
+Write-Info "Checking OS..."
+if ($PSVersionTable.Platform -and $PSVersionTable.Platform -ne 'Win32NT') {
+    Write-Fail "install.ps1 is for native Windows. On Linux/macOS use install.sh."
+}
+
+# Build number 17763 = Windows 10 1809 (the oldest LTS we test against).
+$build = [System.Environment]::OSVersion.Version.Build
+if ($build -lt 17763) {
+    Write-Fail "Windows 10 1809 (build 17763) or newer is required. Detected build $build."
+}
+Write-Ok "Windows build $build"
+
+# ---------------------------------------------------------------------------
+# 2. Python check
+# ---------------------------------------------------------------------------
+
+function Get-PythonCommand {
+    # Prefer `python3` (matches our cross-platform helper convention),
+    # fall back to `python` (the Windows store / python.org default).
+    foreach ($name in @('python3', 'python')) {
+        $cmd = Get-Command $name -ErrorAction SilentlyContinue
+        if ($cmd) { return $cmd.Source }
+    }
+    return $null
+}
+
+Write-Info "Checking Python (3.10 - 3.13)..."
+$pythonExe = Get-PythonCommand
+if (-not $pythonExe) {
+    Write-Info "Python not on PATH - attempting auto-install via winget..."
+    $pythonExe = Install-WithWinget -WingetId 'Python.Python.3.13' -CommandName 'python'
+    if (-not $pythonExe) {
+        Write-Fail @"
+Python 3.10 - 3.13 not found and auto-install via winget failed.
+
+Install manually from https://python.org (check 'Add python.exe to PATH'
+during install) or via winget:
+
+    winget install Python.Python.3.13
+
+Then re-run this installer.
+"@
+    }
+}
+
+$verRaw = & $pythonExe --version 2>&1
+$verMatch = [regex]::Match($verRaw, '(\d+)\.(\d+)\.(\d+)')
+if (-not $verMatch.Success) {
+    Write-Fail "Could not parse Python version from: $verRaw"
+}
+$pyMajor = [int]$verMatch.Groups[1].Value
+$pyMinor = [int]$verMatch.Groups[2].Value
+if ($pyMajor -ne 3 -or $pyMinor -lt 10 -or $pyMinor -gt 13) {
+    Write-Fail @"
+Found Python $pyMajor.$pyMinor at $pythonExe, but OpenJarvis requires
+3.10 - 3.13. Python 3.14 has no numpy Windows wheels yet (#432, will
+re-open once numpy ships cp314).
+"@
+}
+Write-Ok "Python $pyMajor.$pyMinor ($pythonExe)"
+
+# ---------------------------------------------------------------------------
+# 3. git check
+# ---------------------------------------------------------------------------
+
+Write-Info "Checking git..."
+$gitExe = (Get-Command git -ErrorAction SilentlyContinue).Source
+if (-not $gitExe) {
+    Write-Info "git not on PATH - attempting auto-install via winget..."
+    $gitExe = Install-WithWinget -WingetId 'Git.Git' -CommandName 'git'
+    if (-not $gitExe) {
+        Write-Fail @"
+git not found and auto-install via winget failed.
+
+Install manually via winget:
+
+    winget install Git.Git
+
+or download from https://git-scm.com, then re-run this installer.
+"@
+    }
+}
+Write-Ok "git ($gitExe)"
+
+# ---------------------------------------------------------------------------
+# 4. uv check / install
+# ---------------------------------------------------------------------------
+
+Write-Info "Checking uv..."
+$uvExe = (Get-Command uv -ErrorAction SilentlyContinue).Source
+if (-not $uvExe) {
+    Write-Info "Installing uv via astral.sh/uv (official PowerShell installer)..."
+    try {
+        Invoke-RestMethod -Uri 'https://astral.sh/uv/install.ps1' -UseBasicParsing | Invoke-Expression
+    } catch {
+        Write-Fail "uv install failed: $($_.Exception.Message)"
+    }
+    # The astral installer puts uv at %USERPROFILE%\.local\bin\uv.exe and
+    # adds that dir to the User PATH. The current process's PATH isn't
+    # refreshed automatically - prepend the install dir so the rest of
+    # this script picks it up.
+    $uvDir = Join-Path $env:USERPROFILE '.local\bin'
+    if (Test-Path (Join-Path $uvDir 'uv.exe')) {
+        $env:Path = "$uvDir;$env:Path"
+    }
+    $uvExe = (Get-Command uv -ErrorAction SilentlyContinue).Source
+    if (-not $uvExe) {
+        Write-Fail "uv installed but isn't on PATH. Re-open a fresh PowerShell and re-run."
+    }
+}
+Write-Ok "uv ($uvExe)"
+
+# ---------------------------------------------------------------------------
+# 5. Clone the repo
+# ---------------------------------------------------------------------------
+
+$installRoot = if ($env:OPENJARVIS_HOME) {
+    $env:OPENJARVIS_HOME
+} else {
+    Join-Path $env:LOCALAPPDATA 'OpenJarvis'
+}
+$srcDir = Join-Path $installRoot 'src'
+
+Write-Info "Install root: $installRoot"
+
+if (-not (Test-Path $installRoot)) {
+    New-Item -ItemType Directory -Path $installRoot | Out-Null
+}
+
+$repoUrl = if ($env:OPENJARVIS_REPO_URL) {
+    $env:OPENJARVIS_REPO_URL
+} else {
+    'https://github.com/open-jarvis/OpenJarvis.git'
+}
+
+if (Test-Path (Join-Path $srcDir '.git')) {
+    if ($Force) {
+        Write-Info "Force: pulling latest from $repoUrl..."
+        & $gitExe -C $srcDir pull --ff-only
+        if ($LASTEXITCODE -ne 0) { Write-Fail "git pull failed" }
+    } else {
+        Write-Ok "Repository already cloned (use -Force to update)"
+    }
+} else {
+    Write-Info "Cloning $repoUrl..."
+    & $gitExe clone --depth 1 $repoUrl $srcDir
+    if ($LASTEXITCODE -ne 0) { Write-Fail "git clone failed" }
+    Write-Ok "Cloned to $srcDir"
+}
+
+# ---------------------------------------------------------------------------
+# 6. uv sync --extra server
+# ---------------------------------------------------------------------------
+
+Write-Info "Running 'uv sync --extra server' in $srcDir (this can take a few minutes)..."
+Push-Location $srcDir
+try {
+    & $uvExe sync --extra server
+    if ($LASTEXITCODE -ne 0) {
+        Write-Fail "uv sync failed with exit code $LASTEXITCODE. Check the output above."
+    }
+} finally {
+    Pop-Location
+}
+Write-Ok "Dependencies installed"
+
+# ---------------------------------------------------------------------------
+# 7. Ollama - install + start + wait for daemon
+# ---------------------------------------------------------------------------
+
+Write-Info "Checking Ollama..."
+$ollamaExe = (Get-Command ollama -ErrorAction SilentlyContinue).Source
+if (-not $ollamaExe) {
+    Write-Info "  Ollama not on PATH - downloading the official installer (~150 MB)..."
+    $ollamaSetup = Join-Path $env:TEMP 'OllamaSetup.exe'
+    # SilentlyContinue is load-bearing in PS 5.1: the default progress
+    # bar renderer slows Invoke-WebRequest down 30x on large downloads
+    # (a known PS5.1 issue), turning a 30s download into 15+ minutes.
+    $prevProgress = $ProgressPreference
+    $ProgressPreference = 'SilentlyContinue'
+    try {
+        Invoke-WebRequest `
+            -Uri 'https://ollama.com/download/OllamaSetup.exe' `
+            -OutFile $ollamaSetup `
+            -UseBasicParsing
+    } catch {
+        Remove-Item $ollamaSetup -ErrorAction SilentlyContinue  # clean up partial download
+        $ProgressPreference = $prevProgress
+        Write-Fail "Ollama download failed: $($_.Exception.Message)`nInstall manually from https://ollama.com, then re-run."
+    } finally {
+        $ProgressPreference = $prevProgress
+    }
+    # OllamaSetup.exe is built with NSIS, whose silent-install flag is
+    # /S (uppercase). The Inno-Setup-style /silent would open the GUI
+    # and hang `Start-Process -Wait` indefinitely.
+    Write-Info "  Running OllamaSetup.exe /S (this can take a minute)..."
+    Start-Process -FilePath $ollamaSetup -ArgumentList '/S' -Wait
+    Remove-Item $ollamaSetup -ErrorAction SilentlyContinue
+    Update-PathFromRegistry
+    $ollamaExe = (Get-Command ollama -ErrorAction SilentlyContinue).Source
+    if (-not $ollamaExe) {
+        Write-Fail "Ollama installer ran but 'ollama' isn't on PATH. Open a fresh PowerShell and re-run, or install manually from https://ollama.com."
+    }
+}
+Write-Ok "Ollama ($ollamaExe)"
+
+# Make sure the daemon is actually responsive before pulling. The Ollama
+# Windows installer launches the tray app at install time, but on a re-
+# run with an existing install the daemon may not be running yet.
+Write-Info "Waiting for Ollama daemon..."
+$ollamaReady = $false
+for ($i = 0; $i -lt 60; $i++) {
+    # 'ollama list' writes to stderr until the daemon is reachable; under
+    # $ErrorActionPreference='Stop' the 2>&1 merge surfaces that as a
+    # terminating NativeCommandError that would abort the whole install on
+    # the very first probe. Swallow it and rely on $LASTEXITCODE so the
+    # Start-Process serve fallback below actually runs (issue #522).
+    try { & $ollamaExe list 2>&1 | Out-Null } catch { }
+    if ($LASTEXITCODE -eq 0) {
+        $ollamaReady = $true
+        break
+    }
+    if ($i -eq 5) {
+        # Daemon clearly isn't auto-running - start it ourselves. Ollama
+        # for Windows uses the tray app `ollama app.exe`; falling back to
+        # `ollama serve` works headless.
+        Start-Process -FilePath $ollamaExe -ArgumentList 'serve' -WindowStyle Hidden -ErrorAction SilentlyContinue
+    }
+    Start-Sleep -Seconds 1
+}
+if (-not $ollamaReady) {
+    Write-Warn2 "Ollama daemon didn't become ready in 60s. Continuing - bg-orchestrator will retry later."
+}
+
+# ---------------------------------------------------------------------------
+# 8. Pull a starter model (qwen3.5:2b - ~1.5 GB)
+# ---------------------------------------------------------------------------
+
+$modelPullOk = $false
+if ($ollamaReady) {
+    Write-Info "Pulling qwen3.5:2b (~1.5 GB) so 'jarvis' works on first run..."
+    & $ollamaExe pull 'qwen3.5:2b'
+    if ($LASTEXITCODE -eq 0) {
+        $modelPullOk = $true
+        Write-Ok "Starter model ready"
+    } else {
+        Write-Warn2 "ollama pull failed; the bg-orchestrator will retry once Ollama is reachable."
+    }
+} else {
+    Write-Warn2 "Skipping model pull - daemon wasn't ready."
+}
+
+# ---------------------------------------------------------------------------
+# 9. jarvis.cmd shim - so bare `jarvis` works in any new PowerShell
+# ---------------------------------------------------------------------------
+
+$binDir = Join-Path $installRoot 'bin'
+$shimPath = Join-Path $binDir 'jarvis.cmd'
+
+if (-not (Test-Path $binDir)) {
+    New-Item -ItemType Directory -Path $binDir | Out-Null
+}
+
+# %~dp0 in a .cmd file resolves to the directory containing the script,
+# so the shim is self-locating - moving %LOCALAPPDATA%\OpenJarvis won't
+# break it as long as the user moves the whole tree. `uv` is resolved
+# from PATH at runtime (astral installer adds it to User PATH); avoids
+# pinning to the install-time uv.exe path which can shift on uv updates.
+$shimContent = @"
+@echo off
+setlocal
+set "SRC=%~dp0..\src"
+uv run --project "%SRC%" jarvis %*
+"@
+Set-Content -Path $shimPath -Value $shimContent -Encoding ASCII
+
+# Add %LOCALAPPDATA%\OpenJarvis\bin to User PATH if it isn't already
+# there. The current process won't see it until restart - handled in the
+# final banner.
+#
+# Compare against the EXPANDED form: a previous install may have written
+# the entry as `%LOCALAPPDATA%\OpenJarvis\bin` (unexpanded) into User
+# PATH, and a literal `-ieq` against the expanded `$binDir` would miss
+# it and append a duplicate every re-run.
+$userPath = [System.Environment]::GetEnvironmentVariable('Path', 'User')
+$pathOnUser = $false
+if ($userPath) {
+    foreach ($entry in ($userPath -split ';')) {
+        $expanded = [System.Environment]::ExpandEnvironmentVariables($entry)
+        if ($expanded -ieq $binDir) { $pathOnUser = $true; break }
+    }
+}
+$pathNeedsRefresh = $false
+if (-not $pathOnUser) {
+    $newUserPath = if ($userPath) { "$userPath;$binDir" } else { $binDir }
+    [System.Environment]::SetEnvironmentVariable('Path', $newUserPath, 'User')
+    $pathNeedsRefresh = $true
+}
+Write-Ok "jarvis shim installed at $shimPath"
+
+# ---------------------------------------------------------------------------
+# 10. Optional: register the scheduled-task service
+# ---------------------------------------------------------------------------
+
+$serviceScript = Join-Path $srcDir 'deploy\windows\jarvis-service.ps1'
+$shouldInstallService = $false
+
+# Pre-check admin if the user wants the service - Register-ScheduledTask
+# requires elevation. We do this before the prompt so we don't ask "do
+# you want the service?" only to fail with Access Denied after they say
+# yes.
+$isAdmin = ([Security.Principal.WindowsPrincipal] `
+    [Security.Principal.WindowsIdentity]::GetCurrent()
+).IsInRole([Security.Principal.WindowsBuiltInRole]::Administrator)
+
+if ($Service -and -not $isAdmin) {
+    Write-Fail "-Service was requested, but this PowerShell is not elevated. Register-ScheduledTask needs admin rights - re-run from an elevated PowerShell, or drop -Service."
+}
+if ($Service) {
+    $shouldInstallService = $true
+} elseif ($SkipService) {
+    $shouldInstallService = $false
+} elseif (-not $isAdmin) {
+    # Default to skip-with-explanation when we can't elevate, rather
+    # than prompting and then failing at Register-ScheduledTask.
+    Write-Warn2 "Skipping scheduled-task setup - this PowerShell is not elevated."
+    Write-Warn2 "  Register-ScheduledTask requires admin. To install the service later:"
+    Write-Warn2 "    Right-click PowerShell -> Run as administrator, then run:"
+    Write-Warn2 "    powershell -ExecutionPolicy Bypass -File `"$serviceScript`" install"
+} else {
+    # Interactive prompt only when there's a real user at the keyboard
+    # AND stdin isn't piped. [Environment]::UserInteractive is the
+    # canonical PowerShell idiom for "is this a user session" (false for
+    # services, scheduled tasks, etc); we additionally guard against the
+    # `irm | iex` case where stdin is redirected.
+    $isInteractive = [Environment]::UserInteractive `
+        -and -not [System.Console]::IsInputRedirected
+    if ($isInteractive) {
+        $reply = Read-Host "Register OpenJarvis as a Windows scheduled task (auto-start at logon, loopback only)? [y/N]"
+        $shouldInstallService = ($reply -match '^[yY]')
+    } else {
+        Write-Warn2 "Non-interactive install - skipping scheduled-task setup."
+        Write-Warn2 "To register the service later, run (from an elevated PowerShell):"
+        Write-Warn2 "  powershell -ExecutionPolicy Bypass -File `"$serviceScript`" install"
+    }
+}
+
+if ($shouldInstallService) {
+    if (-not (Test-Path $serviceScript)) {
+        Write-Fail "Service script not found at $serviceScript (the clone may be missing files; try -Force)."
+    }
+    Write-Info "Installing scheduled task..."
+    & powershell -ExecutionPolicy Bypass -File $serviceScript install -InstallRoot $installRoot
+    if ($LASTEXITCODE -ne 0) {
+        Write-Fail "Scheduled task setup failed."
+    }
+    Write-Ok "Scheduled task 'OpenJarvis' registered (loopback default)."
+}
+
+# ---------------------------------------------------------------------------
+# 8. Final message
+# ---------------------------------------------------------------------------
+
+Write-Host ""
+Write-Host "  +----------------------------------+" -ForegroundColor Green
+Write-Host "  |   OpenJarvis install complete    |" -ForegroundColor Green
+Write-Host "  +----------------------------------+" -ForegroundColor Green
+Write-Host ""
+Write-Host "  Repo:    $srcDir"
+
+# Tell the truth about what the user can run next, given (a) whether the
+# starter model finished pulling and (b) whether the User-PATH update
+# needs a fresh PowerShell to take effect.
+$nextCmd = if ($modelPullOk) { 'jarvis' } else { 'jarvis doctor' }
+
+if ($pathNeedsRefresh) {
+    Write-Host ""
+    Write-Host "  Run it:  open a NEW PowerShell, then: $nextCmd" -ForegroundColor Yellow
+    Write-Host "           (the jarvis shim was added to your User PATH; the"
+    Write-Host "            current PowerShell won't see it until restart)"
+} else {
+    Write-Host "  Run it:  $nextCmd"
+}
+
+if (-not $modelPullOk) {
+    Write-Host ""
+    Write-Host "  NOTE: the qwen3.5:2b model didn't finish downloading." -ForegroundColor Yellow
+    Write-Host "        Chat will fail until the bg-orchestrator finishes the retry."
+    Write-Host "        'jarvis doctor' shows progress."
+}
+
+if ($shouldInstallService) {
+    Write-Host ""
+    Write-Host "  Service: schtasks /Query /TN OpenJarvis     (status)"
+    Write-Host "           powershell -File `"$serviceScript`" uninstall    (remove)"
+}
+Write-Host ""
+Write-Host "  Docs:    https://open-jarvis.github.io/OpenJarvis/"
+Write-Host ""
@@ -0,0 +1,208 @@
+<#
+.SYNOPSIS
+    Register / unregister the OpenJarvis Windows scheduled task.
+
+.DESCRIPTION
+    The Windows equivalent of deploy/systemd/openjarvis.service and
+    deploy/launchd/com.openjarvis.plist.
+
+    Registers a per-user scheduled task named "OpenJarvis" that starts
+    `jarvis serve` at logon and restarts on failure. Loopback default
+    (127.0.0.1) so no API key is required — matches launchd parity.
+
+    Subcommands:
+      install   — create or replace the task
+      uninstall — remove the task
+      status    — show task state
+
+    Arguments (install only):
+      -InstallRoot <path>  default: %LOCALAPPDATA%\OpenJarvis (matches
+                           install.ps1's default)
+      -ListenHost <addr>   default: 127.0.0.1 (loopback). Set to 0.0.0.0
+                           ONLY if you also set $env:OPENJARVIS_API_KEY
+                           — the server refuses to start unauthenticated
+                           on a non-loopback bind.
+      -ListenPort <int>    default: 8000
+
+    Usage:
+      powershell -ExecutionPolicy Bypass -File jarvis-service.ps1 install
+      powershell -ExecutionPolicy Bypass -File jarvis-service.ps1 uninstall
+      powershell -ExecutionPolicy Bypass -File jarvis-service.ps1 status
+#>
+
+[CmdletBinding()]
+param(
+    [Parameter(Position = 0)]
+    [ValidateSet('install', 'uninstall', 'status')]
+    [string] $Command = 'status',
+
+    [string] $InstallRoot,
+    [string] $ListenHost = '127.0.0.1',
+    [int]    $ListenPort = 8000
+)
+
+$ErrorActionPreference = 'Stop'
+$TaskName = 'OpenJarvis'
+
+function Write-Info  ($msg) { Write-Host "[info]  $msg" -ForegroundColor Cyan }
+function Write-Ok    ($msg) { Write-Host "[ok]    $msg" -ForegroundColor Green }
+function Write-Warn2 ($msg) { Write-Host "[warn]  $msg" -ForegroundColor Yellow }
+function Write-Fail  ($msg) {
+    Write-Host "[fail]  $msg" -ForegroundColor Red
+    exit 1
+}
+
+function Get-DefaultInstallRoot {
+    # Use $script: prefix so this is robust to being called from any
+    # function scope (PowerShell's default dynamic lookup would also
+    # work today, but $script: is the explicit contract).
+    if ($script:InstallRoot) { return $script:InstallRoot }
+    if ($env:OPENJARVIS_HOME) { return $env:OPENJARVIS_HOME }
+    return (Join-Path $env:LOCALAPPDATA 'OpenJarvis')
+}
+
+# ---------------------------------------------------------------------------
+# install
+# ---------------------------------------------------------------------------
+
+function Install-Task {
+    $root = Get-DefaultInstallRoot
+    $srcDir = Join-Path $root 'src'
+    if (-not (Test-Path $srcDir)) {
+        Write-Fail "OpenJarvis source not found at $srcDir. Run install.ps1 first."
+    }
+
+    $uvCmd = Get-Command uv -ErrorAction SilentlyContinue
+    if (-not $uvCmd) {
+        $uvFallback = Join-Path $env:USERPROFILE '.local\bin\uv.exe'
+        if (Test-Path $uvFallback) {
+            $uvPath = $uvFallback
+        } else {
+            Write-Fail "uv.exe not found on PATH or at $uvFallback. Re-run install.ps1."
+        }
+    } else {
+        $uvPath = $uvCmd.Source
+    }
+
+    # Safety: refuse to register a non-loopback bind without an API key.
+    # Mirrors deploy/systemd/openjarvis.service's EnvironmentFile guard.
+    $isLoopback = ($ListenHost -eq '127.0.0.1' -or $ListenHost -eq 'localhost')
+    if (-not $isLoopback -and -not $env:OPENJARVIS_API_KEY) {
+        Write-Fail @"
+ListenHost is $ListenHost (non-loopback) but `$env:OPENJARVIS_API_KEY is
+not set. An unauthenticated non-loopback bind is refused by jarvis serve
+and would also create a security hole. Set the env var first:
+
+    `$env:OPENJARVIS_API_KEY = (uv run jarvis auth generate-key)
+
+then re-run with -ListenHost 0.0.0.0.
+"@
+    }
+
+    # CRITICAL: scheduled tasks do NOT inherit the registering session's
+    # environment. If we registered the task now and stopped here, the
+    # task would launch at logon with a clean env, find no API key, and
+    # `jarvis serve` would refuse to bind 0.0.0.0 — failing silently every
+    # logon. Persist the key to the User env scope so the task's logon
+    # session picks it up. (Loopback path doesn't need the key, so this
+    # only runs for the explicit LAN-exposed case.)
+    if (-not $isLoopback) {
+        Write-Info "Persisting OPENJARVIS_API_KEY to User environment so the scheduled task can read it at logon."
+        [System.Environment]::SetEnvironmentVariable(
+            'OPENJARVIS_API_KEY',
+            $env:OPENJARVIS_API_KEY,
+            'User'
+        )
+    }
+
+    Write-Info "Registering scheduled task '$TaskName'..."
+    Write-Info "  Working dir : $srcDir"
+    Write-Info "  Listen      : $ListenHost`:$ListenPort"
+    Write-Info "  User        : $env:USERNAME"
+
+    # If a previous task exists, remove it first (idempotent install).
+    $existing = Get-ScheduledTask -TaskName $TaskName -ErrorAction SilentlyContinue
+    if ($existing) {
+        Write-Info "Existing task found — replacing."
+        Unregister-ScheduledTask -TaskName $TaskName -Confirm:$false
+    }
+
+    $action = New-ScheduledTaskAction `
+        -Execute $uvPath `
+        -Argument "run jarvis serve --host $ListenHost --port $ListenPort" `
+        -WorkingDirectory $srcDir
+
+    $trigger = New-ScheduledTaskTrigger -AtLogOn -User $env:USERNAME
+
+    $settings = New-ScheduledTaskSettingsSet `
+        -AllowStartIfOnBatteries `
+        -DontStopIfGoingOnBatteries `
+        -StartWhenAvailable `
+        -RestartCount 3 `
+        -RestartInterval (New-TimeSpan -Minutes 1) `
+        -ExecutionTimeLimit (New-TimeSpan -Seconds 0)
+
+    $principal = New-ScheduledTaskPrincipal `
+        -UserId $env:USERNAME `
+        -LogonType Interactive `
+        -RunLevel Limited
+
+    Register-ScheduledTask `
+        -TaskName $TaskName `
+        -Action $action `
+        -Trigger $trigger `
+        -Settings $settings `
+        -Principal $principal `
+        -Description 'OpenJarvis API server (loopback default — see deploy/windows/README.md)' | Out-Null
+
+    Write-Ok "Task '$TaskName' registered."
+    Write-Info "It will start automatically at next logon."
+    Write-Info "To start it now: Start-ScheduledTask -TaskName $TaskName"
+}
+
+# ---------------------------------------------------------------------------
+# uninstall
+# ---------------------------------------------------------------------------
+
+function Uninstall-Task {
+    $existing = Get-ScheduledTask -TaskName $TaskName -ErrorAction SilentlyContinue
+    if (-not $existing) {
+        Write-Warn2 "Task '$TaskName' is not registered — nothing to remove."
+        return
+    }
+    Write-Info "Stopping '$TaskName' (if running)..."
+    Stop-ScheduledTask -TaskName $TaskName -ErrorAction SilentlyContinue
+    Write-Info "Unregistering '$TaskName'..."
+    Unregister-ScheduledTask -TaskName $TaskName -Confirm:$false
+    Write-Ok "Task '$TaskName' removed."
+}
+
+# ---------------------------------------------------------------------------
+# status
+# ---------------------------------------------------------------------------
+
+function Show-Status {
+    $task = Get-ScheduledTask -TaskName $TaskName -ErrorAction SilentlyContinue
+    if (-not $task) {
+        Write-Host "Task '$TaskName' is not registered."
+        Write-Host "Install it with:"
+        Write-Host "  powershell -ExecutionPolicy Bypass -File `"$PSCommandPath`" install"
+        return
+    }
+    $info = Get-ScheduledTaskInfo -TaskName $TaskName
+    Write-Host "Task    : $TaskName"
+    Write-Host "State   : $($task.State)"
+    Write-Host "LastRun : $($info.LastRunTime)"
+    Write-Host "LastRes : 0x$('{0:X8}' -f $info.LastTaskResult)"
+    Write-Host "NextRun : $($info.NextRunTime)"
+}
+
+# ---------------------------------------------------------------------------
+# dispatch
+# ---------------------------------------------------------------------------
+
+switch ($Command) {
+    'install'   { Install-Task }
+    'uninstall' { Uninstall-Task }
+    'status'    { Show-Status }
+}
@@ -0,0 +1,45 @@
+# Showcase screenshots
+
+This directory holds the hero screenshot for each Showcase entry in `docs/showcase/`. Convention is one file per entry, named to match the entry's slug:
+
+| Entry | Screenshot path |
+|---|---|
+| `docs/showcase/morning-brief.md` | `morning-brief.png` |
+| `docs/showcase/persistent-memory.md` | `persistent-memory.png` |
+| `docs/showcase/cost-savings.md` | `cost-savings.png` |
+| `docs/showcase/discord-companion.md` | `discord-companion.png` |
+| `docs/showcase/coding-assistant.md` | `coding-assistant.png` |
+
+## Conventions
+
+| | |
+|---|---|
+| Format | PNG, sRGB, no alpha channel |
+| Size | 1600×1000 (4:2.5 — wider than 16:9, so screenshots don't get letterboxed in the docs grid) |
+| File size | Under 400 KB after `pngquant --quality 70-90 --speed 1` |
+| Loading | All `<img>` and `<figure>` tags in showcase pages use `loading=lazy` — these images are below the fold on the gallery page |
+
+## What to redact
+
+- Real email addresses
+- API keys, OAuth tokens, anything starting with `sk-`, `ghp_`, `xox`, `eyJ`
+- Personal phone numbers
+- Conversation partners' faces or full names (unless they've signed off)
+- File paths that include other people's home directories
+
+## What to keep
+
+- Model names ("llama3.1:8b", "qwen2.5:14b") — they're informative
+- Timestamps — proves the screenshot is recent
+- Dollar amounts on the leaderboard — the whole point
+- Emoji reactions, your own first name, your own avatar
+
+## Placeholder PNGs
+
+This directory ships with no images on the initial PR. The Showcase pages reference image paths that don't exist yet — MkDocs will render a broken-image placeholder, and the figcaption still conveys what should be there. Real screenshots arrive in follow-up PRs as Showcase entries are populated with each contributor's actual setup.
+
+If you're contributing the first real entry, drop your PNG at `docs/assets/showcase/<your-slug>.png` in the same PR that adds your markdown page. The image filename must match the slug used in the showcase page's `<img>` reference.
+
+## Regenerating screenshots in bulk
+
+A future enhancement (tracked as PR #3 in the showcase-tier roadmap) will add `scripts/showcase/regen_screenshots.py` — a Playwright-driven pipeline that boots a demo `jarvis serve` against a sealed config and captures fresh screenshots for every showcase entry on each release tag. Until that lands, screenshots are contributed manually by each Showcase author.
@@ -4,12 +4,25 @@ OpenJarvis provides Docker images for both CPU-only and GPU-accelerated deployme

 ## Quick Start

-The fastest way to get OpenJarvis running in Docker is with Docker Compose, which starts both the API server and an Ollama backend:
+The container binds `0.0.0.0`, so an **API key is required** — the server
+refuses to start on a non-loopback address without one. Set it first:
+
+```bash
+cd deploy/docker
+cp .env.example .env
+echo "OPENJARVIS_API_KEY=$(jarvis auth generate-key)" > .env   # or paste your own
+```
+
+Then start both the API server and an Ollama backend with Docker Compose:

 ```bash
 docker compose up -d
 ```

+`docker compose` reads `OPENJARVIS_API_KEY` from `.env` (or your shell
+environment) and fails fast if it is unset. Clients must then send
+`Authorization: Bearer <key>` on `/v1/*` and `/api/*` requests.
+
 This brings up two services:

 | Service  | Port  | Description                        |
@@ -24,6 +24,14 @@ launchctl load ~/Library/LaunchAgents/com.openjarvis.plist

 The service starts immediately (due to `RunAtLoad`) and will automatically restart at each login.

+!!! note "Binds loopback by default"
+    The plist binds `127.0.0.1` — reachable from this Mac but not the network,
+    the right default for a personal device, and no API key is needed. To
+    expose it on your LAN, change the host to `0.0.0.0` **and** uncomment the
+    `EnvironmentVariables` block to set `OPENJARVIS_API_KEY`
+    (`jarvis auth generate-key`); an unauthenticated `0.0.0.0` server refuses
+    to start.
+
 Verify it is running:

 ```bash
@@ -55,10 +63,17 @@ The provided plist file at `deploy/launchd/com.openjarvis.plist`:
        <string>/usr/local/bin/jarvis</string>
        <string>serve</string>
        <string>--host</string>
-        <string>0.0.0.0</string>
+        <string>127.0.0.1</string>
        <string>--port</string>
        <string>8000</string>
    </array>
+    <!-- To expose on the LAN: set host to 0.0.0.0 and uncomment this block.
+    <key>EnvironmentVariables</key>
+    <dict>
+        <key>OPENJARVIS_API_KEY</key>
+        <string>REPLACE_WITH_A_REAL_KEY</string>
+    </dict>
+    -->
    <key>RunAtLoad</key>
    <true/>
    <key>KeepAlive</key>
@@ -76,7 +91,7 @@ The provided plist file at `deploy/launchd/com.openjarvis.plist`:
 | Key                  | Value                          | Description                                                                                          |
 |----------------------|--------------------------------|------------------------------------------------------------------------------------------------------|
 | `Label`              | `com.openjarvis`               | Unique identifier for the service. Used with `launchctl` commands to manage the service.             |
-| `ProgramArguments`   | `["/usr/local/bin/jarvis", "serve", "--host", "0.0.0.0", "--port", "8000"]` | The command and arguments to execute. Each element of the command line is a separate string in the array. |
+| `ProgramArguments`   | `["/usr/local/bin/jarvis", "serve", "--host", "127.0.0.1", "--port", "8000"]` | The command and arguments to execute. Binds loopback by default; see the note above to expose on the LAN with an API key. |
 | `RunAtLoad`          | `true`                         | Start the service immediately when the plist is loaded (and on each login).                          |
 | `KeepAlive`          | `true`                         | Automatically restart the service if it exits for any reason. launchd monitors the process and relaunches it. |
 | `StandardOutPath`    | `/tmp/openjarvis.stdout.log`   | File where standard output is written. Contains server startup messages and access logs.             |
@@ -21,7 +21,17 @@ cd /opt/openjarvis/OpenJarvis && sudo -u openjarvis uv sync --extra server

 ## Installing the Service

-Copy the unit file to the systemd directory, reload the daemon, and enable the service:
+The unit binds `0.0.0.0`, so an **API key is required** — and the unit
+declares `EnvironmentFile=/etc/openjarvis/env` (no `-` prefix), so it will
+**fail to start** until that file exists with a key. Create it first:
+
+```bash
+sudo mkdir -p /etc/openjarvis
+echo "OPENJARVIS_API_KEY=$(jarvis auth generate-key)" | sudo tee /etc/openjarvis/env
+sudo chmod 600 /etc/openjarvis/env
+```
+
+Then copy the unit file, reload the daemon, and enable the service:

 ```bash
 sudo cp deploy/systemd/openjarvis.service /etc/systemd/system/
@@ -30,6 +40,10 @@ sudo systemctl enable openjarvis
 sudo systemctl start openjarvis
 ```

+Clients must send `Authorization: Bearer <key>` on `/v1/*` and `/api/*`
+requests. (If you instead bind to `127.0.0.1`, the key is optional and you
+can drop the `EnvironmentFile` line.)
+
 Verify it is running:

 ```bash
@@ -94,7 +94,7 @@ cd OpenJarvis

 The script handles everything:

-1. Checks for Python 3.10+ and Node.js 18+
+1. Checks for Python 3.10–3.13 and Node.js 18+
 2. Installs Ollama if not present and pulls a starter model
 3. Installs Python and frontend dependencies
 4. Starts the backend API server and frontend dev server
@@ -1,21 +1,30 @@
-"""Publish the canonical install.sh into the docs site.
+"""Publish the canonical install scripts into the docs site.
+
+Serves the installers at::
+
+    https://open-jarvis.github.io/OpenJarvis/install.sh   (Linux / macOS / WSL2)
+    https://open-jarvis.github.io/OpenJarvis/install.ps1  (native Windows)

-Serves the installer at ``https://open-jarvis.github.io/OpenJarvis/install.sh``
 so users have an HTTPS-valid, project-controlled install URL that does not
 depend on the externally-hosted ``openjarvis.ai`` domain — whose TLS config
 broke and which the project does not control (issue #337).

-Single source of truth: the script lives at ``scripts/install/install.sh``
-(also bundled into the wheel as ``_install_scripts/``). This copies it
-verbatim into the built site at ``install.sh`` on every ``mkdocs build``,
-so the published copy can never drift from the canonical one.
+Single source of truth: the scripts live under ``scripts/install/`` and
+``deploy/windows/`` (also bundled into the wheel as ``_install_scripts/``).
+This copies them verbatim into the built site on every ``mkdocs build``,
+so the published copies can never drift from the canonical ones.
 """

 from pathlib import Path

 import mkdocs_gen_files

-_SRC = Path("scripts/install/install.sh")
+# (source path, published URL path)
+_SCRIPTS = [
+    (Path("scripts/install/install.sh"), "install.sh"),
+    (Path("deploy/windows/install.ps1"), "install.ps1"),
+]

-with mkdocs_gen_files.open("install.sh", "wb") as dst:
-    dst.write(_SRC.read_bytes())
+for src, dest in _SCRIPTS:
+    with mkdocs_gen_files.open(dest, "wb") as out:
+        out.write(src.read_bytes())
@@ -1,6 +1,18 @@
 # Installation

-OpenJarvis ships a one-line installer for macOS, Linux, and WSL2.
+## Platform-specific guides
+
+| Platform | One-liner | Detailed guide |
+|---|---|---|
+| **macOS** | `curl -fsSL https://open-jarvis.github.io/OpenJarvis/install.sh \| bash` | [macOS install](macos.md) |
+| **Linux** | `curl -fsSL https://open-jarvis.github.io/OpenJarvis/install.sh \| bash` | [Linux install](linux.md) |
+| **WSL2 on Windows** | `curl -fsSL https://open-jarvis.github.io/OpenJarvis/install.sh \| bash` (run inside Ubuntu) | [WSL2 install](wsl2.md) |
+| **Native Windows** | `irm https://open-jarvis.github.io/OpenJarvis/install.ps1 \| iex` | [Native Windows install](windows-native.md) |
+| **Desktop GUI** | Download from the [latest release](https://github.com/open-jarvis/OpenJarvis/releases) | — |
+
+The bash and PowerShell installers do the same thing on their respective hosts. The rest of this page documents the bash installer in detail; the [native Windows guide](windows-native.md) is the equivalent reference for PowerShell.
+
+## Bash installer

 ```bash
 curl -fsSL https://open-jarvis.github.io/OpenJarvis/install.sh | bash
@@ -238,7 +238,7 @@ See the [Python SDK guide](../user-guide/python-sdk.md) for the full API referen

 | Requirement | Version | Install | Notes |
 |-------------|---------|---------|-------|
-| Python | 3.10+ | [python.org](https://www.python.org/downloads/) | Required |
+| Python | 3.10–3.13 | [python.org](https://www.python.org/downloads/) | Required. 3.14+ not yet supported (a core dependency lacks 3.14 wheels). |
 | uv | latest | `curl -LsSf https://astral.sh/uv/install.sh \| sh` or `brew install uv` (macOS) | Python package & project manager |
 | Git | any | [git-scm.com](https://git-scm.com/) or `brew install git` (macOS) | Required |
 | Rust | stable | `curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs \| sh` | Required for the Rust extension |
@@ -0,0 +1,83 @@
+# Native Windows (advanced)
+
+Phase-1 of the native-Windows-support RFC (#298). Mirrors the Linux
+(systemd) and macOS (launchd) deployments — but for PowerShell, without
+WSL2 or Docker. Choose this over [WSL2](wsl2.md) only if you want to
+avoid a Linux VM; WSL2 remains the smoother experience for most users.
+
+## What you get
+
+- A PowerShell installer that probes prerequisites, installs `uv`,
+  clones the repo, and runs `uv sync --extra server`.
+- An optional Windows scheduled-task service equivalent to the systemd
+  unit and launchd plist.
+- Loopback default — the service binds `127.0.0.1` so no API key is
+  required.
+
+## What you need
+
+- Windows 10 1809+ or Windows 11.
+- Python 3.10 – 3.13 (Python 3.14 has no numpy Windows wheels yet —
+  see [#432](https://github.com/open-jarvis/OpenJarvis/issues/432)).
+- `git` on PATH.
+- ~5 GB free disk on `%LOCALAPPDATA%`.
+
+## Install
+
+In any PowerShell:
+
+```powershell
+irm https://open-jarvis.github.io/OpenJarvis/install.ps1 | iex
+```
+
+The installer will:
+
+1. Refuse non-Windows hosts and old Windows builds.
+2. Confirm Python 3.10 – 3.13.
+3. Confirm `git`.
+4. Install `uv` if absent (via the official `astral.sh/uv` PowerShell
+   installer).
+5. Clone the repo to `%LOCALAPPDATA%\OpenJarvis\src`.
+6. Run `uv sync --extra server`.
+7. Prompt to register the scheduled-task service (skip with
+   `-SkipService`).
+
+## Run it
+
+```powershell
+cd "$env:LOCALAPPDATA\OpenJarvis\src"
+uv run jarvis serve
+```
+
+Open `http://127.0.0.1:8000/health` to verify.
+
+## Scheduled-task service
+
+If you skipped the prompt during install, register the auto-start task
+manually:
+
+```powershell
+$srv = "$env:LOCALAPPDATA\OpenJarvis\src\deploy\windows\jarvis-service.ps1"
+powershell -ExecutionPolicy Bypass -File $srv install
+```
+
+State:
+
+```powershell
+powershell -ExecutionPolicy Bypass -File $srv status
+```
+
+Remove:
+
+```powershell
+powershell -ExecutionPolicy Bypass -File $srv uninstall
+```
+
+See [`deploy/windows/README.md`](https://github.com/open-jarvis/OpenJarvis/blob/main/deploy/windows/README.md)
+for the LAN-exposed configuration and the parity table against
+systemd / launchd.
+
+## See also
+
+- [WSL2 install](wsl2.md) — the recommended Windows path.
+- [Full installer reference](install.md).
@@ -1,6 +1,9 @@
 # WSL2 Install

-OpenJarvis runs in WSL2 on Windows. Native Windows is not supported.
+OpenJarvis on Windows installs two ways: **WSL2** (this page — the
+recommended path; identical to native Linux) or **[native Windows
+(advanced)](windows-native.md)** (Phase-1; PowerShell installer, no
+WSL2 / no Docker). Pick WSL2 for the smoothest experience.

 ## One-time WSL setup

@@ -14,6 +14,18 @@ OpenJarvis is a research framework for composable, on-device AI systems.
 Build personal AI that runs on your hardware. Cloud APIs are optional.
 </p>

+<div class="grid cards" markdown>
+
+-   :material-image-multiple:{ .lg .middle } **See what people use it for**
+
+    ---
+
+    A gallery of real setups — morning briefs that summarize your overnight Slack and email, a Discord companion that knows your calendar, a code reviewer that works at 30,000 feet. Outcome-first, with links to the docs that explain how to build each one.
+
+    [:octicons-arrow-right-24: Browse the Showcase](showcase/index.md)
+
+</div>
+
 ---

 ## Why OpenJarvis?
@@ -171,7 +183,7 @@ OpenJarvis is built around five composable layers. Each has a clean interface an

    ---

-    CLI, Python SDK, and guides for [Morning Digest](user-guide/morning-digest.md), [Deep Research](user-guide/deep-research.md), [Code Assistant](user-guide/code-assistant.md), [Scheduled Monitor](user-guide/scheduled-monitor.md), [Simple Chat](user-guide/chat-simple.md), agents, memory, tools, and telemetry.
+    CLI, Python SDK, and guides for [Morning Digest](user-guide/morning-digest.md), [Deep Research](user-guide/deep-research.md), [Code Assistant](user-guide/code-assistant.md), [Scheduled Monitor](user-guide/scheduled-monitor.md), [Simple Chat](user-guide/chat-simple.md), [Evaluations](user-guide/evaluations.md), agents, memory, tools, and telemetry.

 -   **[Architecture](architecture/overview.md)**

@@ -12,8 +12,14 @@
  // Outlier detection — hide entries with values that are physically
  // implausible relative to their token count.  Thresholds are ~1000x
  // above legitimate per-token values to avoid false positives.
-  var MAX_ENERGY_WH_PER_TOKEN = 10;        // legit ≈ 0.001 Wh/tok
-  var MAX_FLOPS_PER_TOKEN = 1e17;           // legit ≈ 1e12 /tok
+  // Outlier bounds. Set well above realistic upper limits but tight
+  // enough to drop the pre-fix bimodal Group B (1-5 Wh/token, ~3e16
+  // FLOPs/token) — see the leaderboard PR for the full diagnosis.
+  // Realistic per-token rates on a consumer GPU + 10–30B local model:
+  // ~0.001 Wh/token, ~1e10–1e11 FLOPs/token. We allow 500× and 10,000×
+  // headroom respectively for inefficient hardware / larger models.
+  var MAX_ENERGY_WH_PER_TOKEN = 0.5;        // legit ≈ 0.001 Wh/tok
+  var MAX_FLOPS_PER_TOKEN = 1e15;           // legit ≈ 1e11 /tok
  var MAX_DOLLAR_PER_TOKEN = 25.0 / 1e6;   // hard ceiling: $25/1M output

  function isOutlier(row) {
@@ -29,6 +35,25 @@
    );
  }

+  // Distinguish "user actually has zero work done" from "user's energy /
+  // FLOPs telemetry never landed". The latter happens when the server
+  // submits with valid dollar savings + token counts but the per-record
+  // energy stamp was missing (pre-fix builds, GPU energy meter
+  // unavailable, etc.). Without this check those rows show as "0.00 Wh"
+  // and skew the rankings + headline totals.
+  //
+  // Threshold: 1000 tokens is well above any single chat-turn — if a
+  // user has that many tokens recorded but no measured energy, the
+  // telemetry is incomplete, not legitimately zero.
+  var MIN_TOKENS_FOR_TELEMETRY = 1000;
+
+  function isMissingTelemetry(row) {
+    var tokens = Number(row.total_tokens) || 0;
+    var energy = Number(row.energy_wh_saved) || 0;
+    var flops = Number(row.flops_saved) || 0;
+    return tokens > MIN_TOKENS_FOR_TELEMETRY && energy === 0 && flops === 0;
+  }
+
  function escapeHtml(s) {
    var el = document.createElement("span");
    el.textContent = s;
@@ -62,13 +87,24 @@
      var medal =
        rank === 1 ? "\uD83E\uDD47" : rank === 2 ? "\uD83E\uDD48" : rank === 3 ? "\uD83E\uDD49" : "";
      var row = pageRows[j];
+      // Render "—" for energy / FLOPs columns when telemetry didn't
+      // land (vs the user genuinely having 0). The dollar / request /
+      // token columns are unaffected because those measurements landed
+      // even when energy didn't.
+      var missing = isMissingTelemetry(row);
+      var energyCell = missing
+        ? '<td class="lb-number lb-missing" title="Energy telemetry missing for this entry">—</td>'
+        : '<td class="lb-number">' + Number(row.energy_wh_saved || 0).toFixed(2) + "</td>";
+      var flopsCell = missing
+        ? '<td class="lb-number lb-missing" title="FLOPs telemetry missing for this entry">—</td>'
+        : '<td class="lb-number">' + fmtLarge(Number(row.flops_saved || 0)) + "</td>";
      html +=
        "<tr>" +
        '<td><span class="lb-rank' + rankClass + '">' + (medal || rank) + "</span></td>" +
        '<td class="lb-name">' + escapeHtml(row.display_name) + "</td>" +
        '<td class="lb-number">$' + Number(row.dollar_savings || 0).toFixed(4) + "</td>" +
-        '<td class="lb-number">' + Number(row.energy_wh_saved || 0).toFixed(2) + "</td>" +
-        '<td class="lb-number">' + fmtLarge(Number(row.flops_saved || 0)) + "</td>" +
+        energyCell +
+        flopsCell +
        '<td class="lb-number">' + Number(row.total_calls || 0).toLocaleString() + "</td>" +
        '<td class="lb-number">' + Number(row.total_tokens || 0).toLocaleString() + "</td>" +
        "</tr>";
@@ -116,8 +152,15 @@
    }

    fetch(
+      // `methodology_version=gte.1` filter excludes rows that the
+      // leaderboard-correctness migration quarantined (version 0). Rows
+      // written by current and future clients carry version >= 1, so this
+      // is forward-compatible — pre-fix corrupt rows hide at the query
+      // level (fewer bytes over the wire than client-side outlier
+      // filtering), and downstream client-side checks remain as a
+      // belt-and-suspenders second line of defence.
      SUPABASE_URL +
-        "/rest/v1/savings_entries?select=display_name,dollar_savings,energy_wh_saved,flops_saved,total_calls,total_tokens&order=dollar_savings.desc&limit=1000",
+        "/rest/v1/savings_entries?select=display_name,dollar_savings,energy_wh_saved,flops_saved,total_calls,total_tokens&methodology_version=gte.1&order=dollar_savings.desc&limit=1000",
      {
        headers: {
          apikey: SUPABASE_ANON_KEY,
@@ -0,0 +1,104 @@
+---
+title: Contributing a Showcase Entry
+description: How to add your setup to the OpenJarvis Showcase
+---
+
+# Contributing a Showcase Entry
+
+The Showcase exists for one reason: to help a confused, curious, *non-technical* reader figure out whether OpenJarvis is worth their weekend. That goal sets every editorial choice on this page.
+
+## The format
+
+```markdown
+---
+title: <Your Title — short, capitalized>
+description: <One sentence. The hook a stranger sees in search results.>
+---
+
+# <emoji> <One-sentence hook — what it does FOR you, in plain English>
+
+<figure markdown>
+  ![<alt text>](../assets/showcase/<your-image>.png){ .showcase-screenshot loading=lazy }
+  <figcaption>A one-sentence caption that adds context the image can't show on its own.</figcaption>
+</figure>
+
+<2–3 short paragraphs of context: when do you use this, what changed for
+you, what the experience feels like. Concrete > abstract. "I read it on
+my phone before coffee" > "improves morning productivity."
+
+A bulleted list of two or three CONCRETE OUTCOMES works well — your
+calendar, your inbox, your code. Specific verbs and proper nouns.>
+
+## Why it's nice
+
+- **<one-line benefit>.** <one or two sentences of evidence>
+- **<one-line benefit>.** <one or two sentences of evidence>
+- **<one-line benefit>.** <one or two sentences of evidence>
+
+## How I set this up
+
+→ **[Tutorial: <name>](../tutorials/<file>.md)** is the closest match.
+
+→ **[Recipe: <name>](https://github.com/open-jarvis/OpenJarvis/tree/main/src/openjarvis/recipes/data)** if you want the exact config.
+
+→ **[<one more related doc>](../<path>.md)** if the reader is going deeper.
+```
+
+## Editorial conventions
+
+These are guardrails, not rules. Break them if you have a reason.
+
+### Lead with the outcome, not the technology
+
+❌ "Multi-channel routing with MCP-backed memory and an orchestrator agent."<br>
+✅ "Jarvis answers my Discord messages while I sleep."
+
+The reader doesn't know what an "orchestrator agent" is yet. They know what a Discord message is.
+
+### Show one screenshot. Make it the headline.
+
+A single, large, *interesting* screenshot beats five small ones. Crop it to show the result, not the UI chrome. If you can convey it in an image, don't write the paragraph.
+
+**Screenshot specs:**
+
+- 1600×1000 PNG, sRGB, no alpha
+- File path: `docs/assets/showcase/<your-slug>.png`
+- Redact: real email addresses, API keys, personal phone numbers, conversation partners' faces or full names (unless they've signed off)
+- Keep: model names, timestamps, dollar amounts, emoji reactions, your own first name
+
+### Specific over impressive
+
+❌ "Saves significant time every morning."<br>
+✅ "Cut my morning catch-up from 25 minutes to 2."
+
+Numbers, durations, dollar amounts, and named tools build trust. Adjectives don't.
+
+### Three paragraphs is plenty
+
+A reader who wants more clicks the "How I set this up →" link at the bottom. Showcase pages are a funnel into the docs, not a replacement for them. If you find yourself explaining configuration in the showcase entry, that material belongs in the linked tutorial.
+
+### "Why it's nice" is for the experience, not the architecture
+
+The bullets under **Why it's nice** should answer "what's different *for you*?" — not "what's different about how the framework works?". Save the architecture talk for the linked docs.
+
+❌ "Uses local SQLite for state with WAL mode for concurrent reads."<br>
+✅ "I can read my own memory file in a text editor. I can delete a line and the memory is gone."
+
+### Every entry must end with at least one "How I set this up →" link
+
+If there isn't a relevant tutorial yet, link to the closest [User Guide](../user-guide/cli.md) and open an issue noting that the tutorial is missing. We will write it.
+
+## Submitting
+
+1. **Fork** the repo and create a branch: `docs/showcase-<your-slug>`.
+2. **Add** your markdown file at `docs/showcase/<your-slug>.md` and screenshot at `docs/assets/showcase/<your-slug>.png`.
+3. **Add a tile** to the grid in `docs/showcase/index.md` (matches the existing pattern — emoji + title + 1-sentence summary + `[:octicons-arrow-right-24: See it](<your-slug>.md)`).
+4. **Open a PR** with the title `docs(showcase): <your title>`. Tag a maintainer if you'd like editorial feedback before merge.
+
+## Where this goes after merge
+
+Hannah and the docs team post merged showcase entries to **`#config-showcase`** in [the OpenJarvis Discord](https://discord.gg/openjarvis). You'll get tagged in the post — you don't have to do it yourself.
+
+## Questions, drafts, half-finished ideas
+
+Drop them in **`#config-showcase`** on Discord *before* opening a PR. Editorial feedback is faster on chat than in a PR review, and you'll save yourself a round of revisions.
@@ -0,0 +1,36 @@
+---
+title: Offline Code Reviewer
+description: Review a pull request on a transatlantic flight, no internet required
+---
+
+# 🛠️ Offline Code Reviewer — code review on an airplane
+
+<figure markdown>
+  ![Jarvis reviewing a diff with no internet connection](../assets/showcase/coding-assistant.png){ .showcase-screenshot loading=lazy }
+  <figcaption>Airplane mode in the menu bar. Jarvis reading a `git diff`, the surrounding files, and producing a code review at gate-level Wi-Fi (i.e., none).</figcaption>
+</figure>
+
+Earlier this month I was on a flight from SFO to FRA — eleven hours, no usable Wi-Fi. I had a teammate's pull request open in VS Code. I asked Jarvis to review it. It read the diff, read the three files the diff touched, read the project's `CLAUDE.md` for conventions, and produced a review with five comments — two of which caught real bugs.
+
+The review took about 40 seconds on the laptop's built-in GPU. No API call. No "you're offline" error. By the time we landed I'd dropped the comments into GitHub and the PR was merging.
+
+The same setup handles:
+
+- **Code review** — diff + context files + conventions, structured comments.
+- **Debugging** — paste a traceback, Jarvis reads the stack, opens the relevant files, suggests fixes.
+- **Test generation** — point at a function, get back a `pytest` file with edge cases.
+- **Documentation** — generate docstrings that actually match the code, because Jarvis has the file open.
+
+## Why it's nice
+
+- **It works on a plane.** Or a train, or a hotel with bad Wi-Fi, or your couch when Comcast is having a day. Same speed every time.
+- **It sees your repo, not a sanitized chunk.** Cloud coding assistants make you upload a context window. The local one just reads `git status` and the files you're working on.
+- **No "we trained on your code" question.** Your code never leaves your laptop. Period.
+
+## How I set this up
+
+→ **[Tutorial: Code Companion](../tutorials/code-companion.md)** walks through the ReAct-agent + git/file/shell tool stack this uses end-to-end.
+
+→ **[User Guide: Code Assistant](../user-guide/code-assistant.md)** is the focused recipe walkthrough for daily-driver code review.
+
+→ **[OpenAI-compatible server](../getting-started/quickstart.md)** — point your editor's existing AI integration (Cursor, Continue, Cody, Aider) at `localhost:8000`. They mostly don't know they're not talking to OpenAI.
@@ -0,0 +1,38 @@
+---
+title: Track Your Savings
+description: A leaderboard that tells you exactly how much you saved by running locally
+---
+
+# 💸 Track Your Savings — the leaderboard that makes local-first feel real
+
+<figure markdown>
+  ![OpenJarvis savings leaderboard with personal row highlighted](../assets/showcase/cost-savings.png){ .showcase-screenshot loading=lazy }
+  <figcaption>The public leaderboard. The bar on the right is what a month of my Jarvis usage would have cost on the cloud — measured per-query, not estimated.</figcaption>
+</figure>
+
+OpenJarvis tracks every inference call you make — the tokens, the latency, the GPU energy — and computes what that same call *would have cost* on OpenAI, Anthropic, Google, and Bedrock. There's a public leaderboard at **[/leaderboard](../leaderboard.md)** where anyone running Jarvis can opt in and watch their savings rack up.
+
+My current month is roughly:
+
+| | |
+|---|---|
+| Local inference cost | **`$0.00`** |
+| Cloud-equivalent cost | **`$342.18`** (Claude Sonnet 4.6 baseline) |
+| Energy used | **`1.4 kWh`** (~12¢ of grid power) |
+| Prompts sent to a third party | **`0`** |
+
+The dollar number is the hook. The bottom row is the actual reason I run Jarvis.
+
+## Why it's nice
+
+- **You can see what each query costs you.** Not estimated, not "roughly" — measured. Watt-hours per token, FLOPs per token, latency. Every primitive in OpenJarvis treats compute cost as a first-class quantity alongside accuracy.
+- **It makes "local-first" stop being abstract.** Watching a bar chart accumulate `$X` a week that *didn't* leave your hands is a different kind of motivating than "your data is private" claims that you can't verify.
+- **Privacy stops being an act of faith.** Every prompt I send to Jarvis can be traced through the codebase to local-only paths. No "cloud failover" hiding behind a switch.
+
+## How I set this up
+
+You don't, really — it's on by default. Every `jarvis ask`, `jarvis serve` request, and channel-routed message is metered by the [telemetry system](../telemetry.md). To opt your savings into the public leaderboard:
+
+→ **[Leaderboard guide](../leaderboard.md)** — one command to opt in, one command to opt out. Telemetry is local-only by default.
+
+→ **[Telemetry overview](../telemetry.md)** — what's measured, where it's stored, and how to inspect it yourself with `jarvis telemetry`.
@@ -0,0 +1,34 @@
+---
+title: Discord Companion
+description: Jarvis answers questions in your private Discord while you sleep — reads your notes, checks your calendar, schedules things
+---
+
+# 💬 Discord Companion — a personal assistant that lives in my Discord
+
+<figure markdown>
+  ![Jarvis answering a Discord DM about the user's calendar and notes](../assets/showcase/discord-companion.png){ .showcase-screenshot loading=lazy }
+  <figcaption>I DM'd Jarvis from my phone at midnight. It checked my Google Calendar, cross-referenced a note from last week, and answered — running on the Mac mini in my closet.</figcaption>
+</figure>
+
+I have a private Discord server with two channels and one user (me). Jarvis lives there. I can DM it from my phone, my laptop, or my watch — anywhere Discord runs. Sample things I've asked it this week:
+
+- "What's the address of the place I had that meeting last Tuesday?" → Jarvis searches my calendar + meeting notes, replies in 4 seconds.
+- "Reply to Mom's text from earlier saying I'll call tomorrow at 7." → drafts a reply, asks me to confirm, sends.
+- "Add 'Sam's birthday is March 12' to my long-term memory." → updates `MEMORY.md`, confirms.
+- "Summarize the last hour of conversation in `#deploys-prod`." → reads the Slack channel via MCP, summarizes.
+
+I used to use my phone's voice assistant for this. The two differences that matter: **Jarvis answers in three sentences, not one,** and **it actually has my context** — my notes, my calendar, my projects, my history.
+
+## Why it's nice
+
+- **Latency feels like talking to a person.** Local inference on a modest GPU is 5–10× faster than round-tripping to a cloud API. Question to answer in 3 seconds.
+- **The Discord interface is multi-device for free.** Same conversation thread on my phone, laptop, watch — no special app to install.
+- **It's already private.** A Discord server I run, talking to a model on a machine I own. The data trail is two endpoints I control.
+
+## How I set this up
+
+→ **[Tutorial: Messaging Hub](../tutorials/messaging-hub.md)** is the closest match — same channel-adapter + orchestrator-agent pattern, with Discord substituted for Slack.
+
+→ **[Channel docs](../user-guide/cli.md)** walks through Discord/Slack/Telegram/WhatsApp setup. Discord is two environment variables and a bot token.
+
+→ **[MCP integration guide](../user-guide/cli.md)** if you want Jarvis to reach into Notion, Linear, Gmail, etc.
@@ -0,0 +1,72 @@
+---
+title: Showcase
+description: What people actually do with OpenJarvis — outcomes first, scripts later
+---
+
+# Showcase
+
+These are stories from people who use OpenJarvis day to day. Each entry shows the **result** — a screenshot, a paragraph of context, and a short link to the docs that explain how to build it. If you're trying to figure out whether OpenJarvis is worth a weekend of your time, start here.
+
+!!! tip "New here?"
+    The Showcase answers *"what's possible?"*. When you find something you want for yourself, follow the **How I set this up** link at the bottom of each page — it lands on a [Tutorial](../tutorials/index.md) that walks through the build.
+
+<div class="grid cards" markdown>
+
+- :material-coffee:{ .lg .middle } **Morning Brief**
+
+    ---
+
+    Slack, email, GitHub, and calendar — read overnight, summarized into 5 bullets in your phone by 7am. Cuts the daily "what did I miss" tax to zero.
+
+    [:octicons-arrow-right-24: See it](morning-brief.md)
+
+- :material-brain:{ .lg .middle } **Memory That Doesn't Reset**
+
+    ---
+
+    Tell Jarvis you're allergic to shellfish once. Three months later it brings it up when you're restaurant-planning. Plain markdown files, no vector-DB tricks.
+
+    [:octicons-arrow-right-24: See it](persistent-memory.md)
+
+- :material-piggy-bank-outline:{ .lg .middle } **Track Your Savings**
+
+    ---
+
+    A leaderboard that tells you exactly how much you saved by running locally — and reminds you that none of your prompts ever left your house.
+
+    [:octicons-arrow-right-24: See it](cost-savings.md)
+
+- :material-message-text:{ .lg .middle } **Discord Companion**
+
+    ---
+
+    Jarvis answers questions in your private Discord while you sleep. Reads your notes, checks your calendar, schedules things, replies in your voice.
+
+    [:octicons-arrow-right-24: See it](discord-companion.md)
+
+- :material-code-tags-check:{ .lg .middle } **Offline Code Reviewer**
+
+    ---
+
+    Review a pull request on a transatlantic flight. Jarvis reads the diff, the surrounding files, and the project conventions — without an internet connection.
+
+    [:octicons-arrow-right-24: See it](coding-assistant.md)
+
+</div>
+
+---
+
+## Share your setup
+
+The Showcase grows from real users. If you've built something interesting on top of OpenJarvis — or just have a configuration you're proud of — the format is simple and the bar is low:
+
+1. **One-sentence hook**: what does this *do for you*?
+2. **A screenshot or 15-second screen recording**: the visible result.
+3. **2–3 short paragraphs**: when you use it, why it's nice (cost, privacy, speed, calm).
+4. **"How I set this up →"**: a link to the relevant [Tutorial](../tutorials/index.md), [User Guide](../user-guide/cli.md), or [Recipe](https://github.com/open-jarvis/OpenJarvis/tree/main/src/openjarvis/recipes/data).
+
+See [Contributing a Showcase Entry](CONTRIBUTING.md) for the template and the editorial conventions (screenshot sizing, what to redact, tone).
+
+## Want to talk to other people doing this?
+
+The **`#config-showcase`** channel in the [OpenJarvis Discord](https://discord.gg/openjarvis) is where people post and discuss personal setups. Drop a screenshot, ask "how would I do X?", or browse what others have shared.
@@ -0,0 +1,39 @@
+---
+title: Morning Brief
+description: Slack, email, GitHub, and calendar — summarized into a 5-bullet brief on your phone by 7am
+---
+
+# ☕ Morning Brief — Jarvis reads everything overnight so I don't have to
+
+<figure markdown>
+  ![Morning brief in Discord](../assets/showcase/morning-brief.png){ .showcase-screenshot loading=lazy }
+  <figcaption>The 7am brief that arrives in my private Discord — 5 bullets, two minutes to read, written by an agent that ran on my desk while I slept.</figcaption>
+</figure>
+
+Every morning at 7am, before my first coffee, a message appears in my private Discord with five bullets:
+
+- what shipped at work overnight (GitHub releases + merged PRs)
+- the two emails I actually need to act on (with one-line summaries)
+- anything mentioned in my team's `#general` Slack channel
+- today's calendar with the next 24 hours of meetings
+- one thing I asked Jarvis to track for me ("did Tuesday's deploy roll out cleanly?")
+
+It's the first thing I read on my phone, while I'm still in bed. The brief used to take me 25 minutes — opening four apps, scrolling, deciding what mattered. Now it's two minutes of reading and I'm done.
+
+## Why it's nice
+
+- **Costs me nothing per month.** It runs on a Mac mini in my closet. Same prompt-volume on the OpenAI API would be `~$18/month` based on the leaderboard's estimates.
+- **Nothing leaves my house.** My inbox, my Slack DMs, my calendar — Jarvis reads them locally and writes the digest locally. The only network call is the Discord webhook to my own private server.
+- **It learns my taste.** Over a few weeks Jarvis figured out that PR titles starting with `chore:` aren't worth surfacing and that I don't want to see calendar holds I created myself. The summarizer has a `MEMORY.md` it updates when I react with 👎 to a bullet.
+
+## What you'd need
+
+A laptop or mini-PC that stays on overnight, an inference engine (Ollama is the easy default), accounts on whichever surfaces you want summarized (Slack, Gmail, GitHub, Google Calendar), and a Discord (or Slack, or Telegram, or email) destination to post the brief to.
+
+## How I set this up
+
+→ **[Tutorial: Scheduled Personal Ops](../tutorials/scheduled-ops.md)** walks through the cron-scheduled agent pattern this uses. The morning-brief flavour is `orchestrator` agent + the channel adapters + the scheduler primitive — three primitives, one TOML recipe.
+
+→ **[User Guide: Morning Digest](../user-guide/morning-digest.md)** is the focused recipe walkthrough if you only want this one workflow.
+
+→ **[User Guide: Channels](../user-guide/cli.md)** for connecting Discord/Slack/Telegram as the destination.
@@ -0,0 +1,34 @@
+---
+title: Memory That Doesn't Reset
+description: Tell Jarvis something once. It remembers — three months later, across every conversation
+---
+
+# 🧠 Memory That Doesn't Reset — Jarvis actually knows me
+
+<figure markdown>
+  ![Jarvis remembering a user preference three months later](../assets/showcase/persistent-memory.png){ .showcase-screenshot loading=lazy }
+  <figcaption>Three months after I mentioned the allergy in passing, Jarvis brings it up — unprompted — while helping me pick a birthday-dinner restaurant.</figcaption>
+</figure>
+
+I mentioned to Jarvis once, in a throwaway sentence in April, that I'm allergic to shellfish. In July, when I asked it to help me pick a restaurant for my partner's birthday, it volunteered "you'll want to filter for menus that have non-shellfish options" — without being reminded, in a totally different conversation, on a different topic.
+
+That's not magic. The trick is that Jarvis writes to three plain markdown files in my home directory whenever it learns something worth remembering:
+
+- `SOUL.md` — how I want it to behave (tone, length, what to push back on)
+- `MEMORY.md` — facts about me, my projects, my preferences
+- `USER.md` — who I am: my role, my team, my context
+
+Every new conversation starts by reading those three files. I can open them in any text editor. I can delete a line and the memory is gone. The whole thing is `~6 KB` of markdown. No vector DB, no embedding cache, no opaque "personalization layer."
+
+## Why it's nice
+
+- **It's auditable.** I can read what Jarvis "knows" about me in 30 seconds. Most personal-AI products literally can't tell you.
+- **It's portable.** I keep my three files in iCloud Drive. When I set up Jarvis on a new machine, my memory comes with me — without re-onboarding.
+- **It compounds.** After two weeks Jarvis stopped re-asking what my code style is. After six weeks it stopped re-asking who's on my team. The conversations get shorter because the context is already there.
+- **It can't drift.** Vector retrieval can confidently surface the wrong "memory" and you'd never know. Plain markdown that I can read can't lie about what it contains.
+
+## How I set this up
+
+→ **[User Guide: Agents](../user-guide/agents.md)** explains the persistent-agent pattern, including how `SOUL.md` / `MEMORY.md` / `USER.md` are loaded at conversation start.
+
+→ **[Tutorial: Deep Research Assistant](../tutorials/deep-research.md)** uses the same persistent-memory primitive — a good place to see it in action with code.
@@ -440,6 +440,13 @@
  font-family: var(--md-code-font-family, monospace);
  font-size: 13px;
 }
+/* Placeholder for rows where energy / FLOPs telemetry didn't land.
+   Distinguishes "telemetry missing" from "user genuinely had 0 work
+   done" without making the row visually pop more than data rows. */
+.lb-missing {
+  color: var(--md-default-fg-color--light, #999);
+  font-style: italic;
+}

 /* ── DocSearch ───────────────────────────────────────────────────────── */
 #docsearch {
@@ -562,3 +569,18 @@
    display: none !important;
  }
 }
+
+/* ---------------------------------------------------------------------------
+ * Showcase screenshots
+ *
+ * Hero images on docs/showcase/* pages. Constrains width on wide screens and
+ * adds a subtle border so placeholder/broken-image states still look intentional
+ * before community-contributed screenshots populate docs/assets/showcase/.
+ * ------------------------------------------------------------------------- */
+.showcase-screenshot {
+  max-width: 100%;
+  height: auto;
+  border-radius: 8px;
+  border: 1px solid var(--md-default-fg-color--lightest, rgba(0, 0, 0, 0.08));
+  box-shadow: 0 2px 8px rgba(0, 0, 0, 0.06);
+}
@@ -83,33 +83,6 @@ dropped. Tests covering the patterns: [`tests/analytics/test_redaction.py`](../t
 - **Never** sold, shared with advertisers, or used for anything other
  than improving OpenJarvis.

-## Opting out
-
-Three independent ways to disable analytics — any one is sufficient:
-
-1. **Set an env var** (no config file edit needed):
-   ```bash
-   export DO_NOT_TRACK=1            # W3C convention, honored by other tools too
-   # or
-   export OPENJARVIS_NO_ANALYTICS=1 # project-specific, leaves other DNT-aware tools unaffected
-   ```
-   Both are checked at runtime; any truthy value (`1`, `true`, `yes`,
-   `on`) disables analytics for that process. Truthy = anything other
-   than empty, `0`, `false`, `no`, `off`.
-
-2. **Edit `~/.openjarvis/config.toml`**:
-   ```toml
-   [analytics]
-   enabled = false
-   ```
-
-3. **Delete the anon ID** (`rm ~/.openjarvis/anon_id`) — events for
-   the prior identity are orphaned, but a new identity will be
-   created on the next run. Combine with #1 or #2 to fully stop.
-
-Env-var opt-out takes precedence over the config file, so setting
-`DO_NOT_TRACK=1` overrides `enabled = true` in the config.
-
 ## Retention

 - Default retention: **365 days**, then events are deleted by PostHog
@@ -13,6 +13,7 @@ Agents are the agentic logic layer of OpenJarvis. They determine how a query is
 | `RLMAgent`          | `rlm`             | Yes             | Yes        | Recursive LM with persistent REPL            |
 | `OpenHandsAgent`    | `openhands`       | No              | Yes        | Wraps real openhands-sdk                     |
 | `ClaudeCodeAgent`   | `claude_code`     | No              | Yes        | Claude Agent SDK via Node.js subprocess       |
+| `OpenCodeAgent`     | `opencode`        | No              | Yes        | [opencode](https://opencode.ai) coding agent on your local engine |
 | `OperativeAgent`    | `operative`       | Yes             | Yes        | Persistent scheduled agent with state management |
 | `MonitorOperativeAgent` | `monitor_operative` | Yes        | Yes        | Long-horizon agent with 4 configurable strategy axes |

@@ -383,6 +384,64 @@ jarvis ask --agent claude_code "Refactor the tests to use pytest fixtures"

 ---

+## OpenCodeAgent
+
+The `OpenCodeAgent` delegates coding tasks to [opencode](https://opencode.ai), the open-source coding agent, running it **on your local engine**. opencode handles the agentic loop, file edits, and tool use; OpenJarvis supplies the model — keeping coding-agent work local-first.
+
+!!! warning "Requirements"
+    Requires the `opencode` binary on `PATH` (`npm i -g opencode-ai` or `brew install anomalyco/tap/opencode`). It is **not** bundled; `run()` returns a clear error if it is missing. No `ANTHROPIC_API_KEY` needed — inference goes through your OpenJarvis engine.
+
+**How it works:**
+
+1. Derives an OpenAI-compatible base URL from the `engine` (e.g. Ollama/vLLM/llama.cpp at `<host>/v1`) and writes an `opencode.json` in the workspace registering it as an `@ai-sdk/openai-compatible` provider (`openjarvis/<model>`).
+2. Spawns a headless `opencode serve` (loopback, random port) and waits for `/global/health`.
+3. Creates a session (`POST /session`) and sends the task (`POST /session/{id}/message`) with `model={providerID, modelID}` and the selected `agent` (`build` or `plan`).
+4. Parses the returned message `parts` — text parts → `content`, tool parts → `tool_results` — into an `AgentResult`.
+5. `close()` disposes the session/server.
+
+**Constructor parameters (selected):**
+
+| Parameter           | Type              | Default          | Description                                              |
+|---------------------|-------------------|------------------|----------------------------------------------------------|
+| `engine`            | `InferenceEngine` | --               | Used to derive the local OpenAI-compatible provider URL  |
+| `model`             | `str`             | --               | Model id served at the provider (e.g. `qwen3:8b`)        |
+| `workspace`         | `str`             | `os.getcwd()`    | Directory opencode operates in                           |
+| `agent`             | `str`             | `"build"`        | opencode agent: `build` (full access) or `plan` (read-only) |
+| `provider_base_url` | `str`             | derived          | Override the engine-derived OpenAI base URL              |
+| `provider_id`       | `str`             | `"openjarvis"`   | opencode provider id to register/use                     |
+| `model_id`          | `str`             | `model`          | Model id within the provider                             |
+| `server_password`   | `str`             | `$OPENCODE_SERVER_PASSWORD` | Optional basic-auth for the opencode server   |
+| `timeout`           | `int`             | `600`            | HTTP timeout in seconds                                  |
+
+```python
+from openjarvis.agents.opencode import OpenCodeAgent
+
+agent = OpenCodeAgent(engine, "qwen3:8b", workspace="/path/to/project", agent="build")
+result = agent.run("Add type hints to utils.py and run the tests")
+print(result.content)
+agent.close()
+```
+
+```bash
+# Via CLI (opencode must be installed)
+jarvis ask --agent opencode "Refactor the parser to use a state machine"
+```
+
+!!! tip "Pass-through providers"
+    If the `engine` has no derivable base URL, pass `model` as `provider/model` (e.g. `ollama/llama3`) and opencode resolves it from its own configuration — no `opencode.json` is written.
+
+!!! warning "Model capability matters"
+    opencode's agentic loop (planning + correct tool calls + multi-step
+    follow-through) needs a reasonably capable model. In testing, a **27B**
+    local model (Qwen3.5-27B served via vLLM) solved a 7-task coding suite
+    cleanly (create / edit / bug-fix / implement-to-pass-tests / multi-file,
+    verified by running the code and tests). An **8B** model (qwen3:8b) was
+    unreliable — malformed tool calls, syntactically broken code, and
+    half-finished tasks. Prefer a capable local model (or a cloud model) for
+    real coding work.
+
+---
+
 ## OperativeAgent

 The `OperativeAgent` is a persistent, scheduled autonomous agent with built-in session persistence and state recall. Designed for "Operators" -- autonomous agents that run on a schedule with automatic state management between ticks. Extends `ToolUsingAgent`.
@@ -1,14 +1,14 @@
 # Evaluations

-The OpenJarvis evaluation framework (`openjarvis-evals`) measures model **correctness and accuracy** on academic datasets. It is a separate package from the main OpenJarvis library and is designed specifically for research workflows where you need reproducible, dataset-driven quality assessments.
+The OpenJarvis evaluation framework (`openjarvis.evals`) measures model **correctness and accuracy** on academic datasets. It ships inside the main `openjarvis` package (at `src/openjarvis/evals/`) and is designed specifically for research workflows where you need reproducible, dataset-driven quality assessments.

 !!! info "Evals vs. Benchmarks"
    OpenJarvis has two distinct measurement systems that complement each other:

-    | System | Package | Measures | Entry Point |
-    |--------|---------|----------|-------------|
-    | **Evaluations** | `openjarvis-evals` | Correctness on academic datasets (accuracy, pass rate) | `openjarvis-eval` |
-    | **Benchmarks** | `openjarvis` | Engine performance (latency, throughput) | `jarvis bench` |
+    | System | Module | Measures | Entry Point |
+    |--------|--------|----------|-------------|
+    | **Evaluations** | `openjarvis.evals` | Correctness on academic datasets (accuracy, pass rate) | `jarvis eval` |
+    | **Benchmarks** | `openjarvis.bench` | Engine performance (latency, throughput) | `jarvis bench` |

    Use evaluations to answer "does this model get the right answer?" and benchmarks to answer "how fast does this model respond?". See the [Benchmarks guide](benchmarks.md) for the performance measurement system.

@@ -18,22 +18,38 @@ The OpenJarvis evaluation framework (`openjarvis-evals`) measures model **correc

 ## Installation

-The evaluation framework is a standalone package in the `evals/` directory. Install it alongside OpenJarvis:
+The evaluation framework is part of the main `openjarvis` package — no separate install or extra is required. The standard dev setup is enough:

 ```bash
-uv sync --extra eval
+uv sync --extra dev
 ```

-This installs the `openjarvis-eval` CLI entry point and all required dependencies (`datasets`, `huggingface-hub`, `tqdm`, `rich`).
+The framework's core dependencies (`click`, `datasets`, `rich`) are base dependencies of `openjarvis`. Two optional extras enable experiment tracking integrations:
+
+```bash
+uv sync --extra dev --extra eval-wandb     # Weights & Biases run tracking
+uv sync --extra dev --extra eval-sheets    # Google Sheets results export
+```

 !!! note "Python version requirement"
-    Python 3.10 requires the `tomli` package for TOML config parsing. The `evals/pyproject.toml` includes this as a conditional dependency, so it is installed automatically.
+    Python 3.10 requires the `tomli` package for TOML config parsing. `openjarvis` declares it as a conditional dependency, so it is installed automatically.
+
+## Entry Points
+
+Two equivalent entry points expose the framework:
+
+| Command | Surface |
+|---------|---------|
+| `jarvis eval {list,run,compare,report}` | Canonical CLI. `run` covers the common options; `compare` and `report` post-process result files. |
+| `python -m openjarvis.evals {list,run,run-all,summarize,reparse-judge}` | Full research surface, including judge configuration, the agentic runner, and episode mode. |
+
+The `openjarvis-eval` console script is an alias for `python -m openjarvis.evals` — same commands, same options. This guide uses `jarvis eval` wherever its option set suffices and the module form for research-only options.

 ---

 ## Datasets

-The framework ships with **30+ datasets** covering academic reasoning, agentic tasks, retrieval, conversation quality, and practical use-case benchmarks. Datasets are grouped by category below.
+The framework ships with **40 registered benchmarks** covering academic reasoning, agentic tasks, coding, retrieval, conversation quality, and practical use-case benchmarks. Datasets are grouped by category below; `uv run python -m openjarvis.evals list` prints the authoritative registry.

 ### Use-Case Benchmarks

@@ -64,6 +80,7 @@ These benchmarks measure reasoning and knowledge on established academic dataset
 | **MATH-500** | `math500` | reasoning | Competition-level math problems |
 | **NaturalReasoning** | `natural-reasoning` | reasoning | Natural language reasoning |
 | **HLE** | `hle` | reasoning | Humanity's Last Exam hard challenges |
+| **LiveResearchBench** | `liveresearchbench` | reasoning | Recent research comprehension (Salesforce) |
 | **SimpleQA** | `simpleqa` | chat | Short-form factual question answering |
 | **IPW** | `ipw` | chat | Intelligence Per Watt mixed benchmark |

@@ -79,6 +96,11 @@ These benchmarks test multi-step agent capabilities including tool use, code gen
 | **TerminalBench** | `terminalbench` | agentic | Terminal-based task completion |
 | **TerminalBench Native** | `terminalbench-native` | agentic | TerminalBench with native Docker execution |
 | **TerminalBench V2.1** | `terminalbench-v2.1` | agentic | TB v2.1 Harbor-style Docker tasks |
+| **PinchBench** | `pinchbench` | agentic | Real-world agent tasks |
+| **TauBench** | `taubench` | agentic | Multi-turn customer service |
+| **DeepResearchBench** | `liveresearch` | agentic | Deep research report generation |
+| **DeepResearchBench (alias)** | `deepresearch` | agentic | Same benchmark as `liveresearch` |
+| **ToolCall-15** | `toolcall15` | agentic | Tool calling benchmark |
 | **LifelongAgent** | `lifelong-agent` | agentic | Sequential task learning across sessions |
 | **PaperArena** | `paperarena` | agentic | Scientific paper analysis |
 | **DeepPlanning** | `deepplanning` | agentic | Shopping constraint planning |
@@ -87,6 +109,14 @@ These benchmarks test multi-step agent capabilities including tool use, code gen
 | **WebChoreArena** | `webchorearena` | agentic | Web chore tasks |
 | **WorkArena** | `workarena` | agentic | WorkArena++ enterprise workflows |

+Both `liveresearch` and `deepresearch` are registered keys for the DeepResearchBench report-generation benchmark.
+
+### Coding Benchmarks
+
+| Dataset | Key | Category | Description |
+|---------|-----|----------|-------------|
+| **LiveCodeBench** | `livecodebench` | coding | Competitive programming |
+
 ### Retrieval Benchmarks

 | Dataset | Key | Category | Description |
@@ -123,7 +153,7 @@ The framework includes two pre-built configs for evaluating models on the five c
 ### Cloud models

 ```bash
-uv run python -m openjarvis.evals --config src/openjarvis/evals/configs/use_case_v2_cloud.toml
+uv run jarvis eval run --config src/openjarvis/evals/configs/use_case_v2_cloud.toml
 ```

 This config evaluates **6 cloud models** (Claude Opus 4.6, Claude Haiku 4.5, Gemini 3.1 Pro, Gemini 3.1 Flash Lite, GPT-5.4, GPT-5 Mini) against all 5 use-case benchmarks with 30 samples each, producing a 6x5 = 30-run matrix. Results are written to `results/use-cases-v2-cloud/`.
@@ -131,7 +161,7 @@ This config evaluates **6 cloud models** (Claude Opus 4.6, Claude Haiku 4.5, Gem
 ### Local models

 ```bash
-uv run python -m openjarvis.evals --config src/openjarvis/evals/configs/use_case_v2_local.toml
+uv run jarvis eval run --config src/openjarvis/evals/configs/use_case_v2_local.toml
 ```

 This config evaluates **5 local models** via Ollama (Qwen3.5 122B-A10B, GPT-OSS 120B, GLM4, Qwen3.5 35B-A3B, GLM-4.7-Flash) against the same 5 benchmarks, producing a 5x5 = 25-run matrix. Uses 2 workers (suitable for single-GPU setups). Results are written to `results/use-cases-v2-local/`.
@@ -143,15 +173,22 @@ This config evaluates **5 local models** via Ollama (Qwen3.5 122B-A10B, GPT-OSS

 ## Inference Backends

-Every evaluation run routes model calls through one of two backends:
+Every evaluation run routes model calls through one of four backends:

 | Backend | Key | Description |
 |---------|-----|-------------|
 | **jarvis-direct** | `jarvis-direct` | Engine-level inference via `SystemBuilder`. Works for local (Ollama, vLLM, llama.cpp) and cloud models. |
 | **jarvis-agent** | `jarvis-agent` | Agent-level inference with tool calling. Uses `JarvisSystem.ask()` with the specified agent and tools. |
+| **hermes** | `hermes` | Real Hermes Agent (Nous Research) via subprocess. Requires `--base-url` and `--api-key`. |
+| **openclaw** | `openclaw` | Real OpenClaw via Node subprocess. Requires `--base-url` and `--api-key`. |

 Use `jarvis-direct` for most evaluations. Use `jarvis-agent` when the benchmark requires tool use — for example, GAIA tasks that reference files that must be read with `file_read`, or arithmetic tasks that benefit from `calculator`.

+The `hermes` and `openclaw` backends shell out to external agent frameworks and need an OpenAI-compatible endpoint for their model calls: pass `--base-url`/`--api-key`, set the `JARVIS_BACKEND_BASE_URL`/`JARVIS_BACKEND_API_KEY` environment variables, or add a `[backend.external]` section to your config (see [Config Reference](#backendexternal)).
+
+!!! note "TerminalBench Native"
+    `jarvis eval run --backend` additionally accepts `terminalbench-native`, a Docker-based execution backend used by the TerminalBench Native benchmark.
+
 ---

 ## CLI Usage
@@ -159,73 +196,106 @@ Use `jarvis-direct` for most evaluations. Use `jarvis-agent` when the benchmark
 ### List available benchmarks and backends

 ```bash
-openjarvis-eval list
+uv run python -m openjarvis.evals list
 ```

-Output:
+Abridged output (40 benchmarks, 4 backends):

 ```
-Benchmarks:
-  supergpqa    [reasoning  ] SuperGPQA multiple-choice
-  gaia         [agentic    ] GAIA agentic benchmark
-  frames       [rag        ] FRAMES multi-hop RAG
-  wildchat     [chat       ] WildChat conversation quality
-
-Backends:
-  jarvis-direct    Engine-level inference (local or cloud)
-  jarvis-agent     Agent-level inference with tool calling
+                         Available Benchmarks
+┌──────────────────────┬───────────┬───────────────────────────────────┐
+│ Name                 │ Category  │ Description                       │
+├──────────────────────┼───────────┼───────────────────────────────────┤
+│ supergpqa            │ reasoning │ SuperGPQA multiple-choice         │
+│ gpqa                 │ reasoning │ GPQA graduate-level MCQ           │
+│ ...                  │ ...       │ ...                               │
+│ livecodebench        │ coding    │ LiveCodeBench competitive progr.  │
+│ toolcall15           │ agentic   │ ToolCall-15 tool calling benchmark│
+└──────────────────────┴───────────┴───────────────────────────────────┘
+                         Available Backends
+┌───────────────┬──────────────────────────────────────────────────┐
+│ jarvis-direct │ Engine-level inference (local or cloud)          │
+│ jarvis-agent  │ Agent-level inference with tool calling          │
+│ hermes        │ Real Hermes Agent (Nous Research) via subprocess │
+│ openclaw      │ Real OpenClaw via Node subprocess                │
+└───────────────┴──────────────────────────────────────────────────┘
 ```

+`jarvis eval list` prints a similar table but currently shows a curated subset of the registry; the module form above is the authoritative listing.
+
 ### Run a single benchmark

 ```bash
-# Evaluate qwen3:8b on SuperGPQA (engine-level, 10 samples default)
-openjarvis-eval run -b supergpqa -m qwen3:8b
+# Evaluate qwen3:8b on SuperGPQA (engine-level, 10 samples)
+uv run jarvis eval run -b supergpqa -m qwen3:8b -n 10

-# Evaluate GPT-4o on GAIA using the agent backend with tools
-openjarvis-eval run -b gaia -m gpt-4o --backend jarvis-agent \
+# Evaluate GPT-5 Mini on GAIA using the agent backend with tools
+uv run jarvis eval run -b gaia -m gpt-5-mini --backend jarvis-agent \
    --agent orchestrator --tools calculator,file_read -n 50

-# Run FRAMES with vLLM engine, write output to a file
-openjarvis-eval run -b frames -m llama3:70b -e vllm \
+# Run FRAMES with the vLLM engine, write output to a file
+uv run jarvis eval run -b frames -m llama3:70b -e vllm \
    -o results/frames_llama70b.jsonl

 # Run WildChat with a higher temperature for chat quality
-openjarvis-eval run -b wildchat -m qwen3:8b --temperature 0.7 -n 100
+uv run jarvis eval run -b wildchat -m qwen3:8b --temperature 0.7 -n 100
 ```

-#### Full option reference
+#### `jarvis eval run` option reference

 | Option | Short | Type | Default | Description |
 |--------|-------|------|---------|-------------|
 | `--config` | `-c` | path | — | TOML config file; when provided, `-b` and `-m` are not required |
-| `--benchmark` | `-b` | choice | required* | `supergpqa`, `gaia`, `frames`, or `wildchat` |
-| `--backend` | | choice | `jarvis-direct` | `jarvis-direct` or `jarvis-agent` |
-| `--model` | `-m` | str | required* | Model identifier (e.g., `qwen3:8b`, `gpt-4o`) |
-| `--engine` | `-e` | str | auto | Engine key (`ollama`, `vllm`, `cloud`, ...) |
-| `--agent` | | str | `orchestrator` | Agent name for `jarvis-agent` backend |
-| `--tools` | | str | `""` | Comma-separated tool names (e.g., `calculator,file_read`) |
+| `--benchmark` | `-b` | str | required* | Any registered benchmark key (see `... list`) |
+| `--model` | `-m` | str | required* | Model identifier (e.g., `qwen3:8b`, `gpt-5-mini`) |
 | `--max-samples` | `-n` | int | all | Limit the number of samples evaluated |
-| `--max-workers` | `-w` | int | `4` | Parallel evaluation workers |
-| `--judge-model` | | str | `gpt-4o` | LLM used for judge-based scoring |
-| `--output` | `-o` | path | auto-generated | Output JSONL file path |
+| `--backend` | | choice | `jarvis-direct` | `jarvis-direct`, `jarvis-agent`, `hermes`, `openclaw`, or `terminalbench-native` |
+| `--base-url` | | str | — | OpenAI-compatible endpoint URL (env: `JARVIS_BACKEND_BASE_URL`) |
+| `--api-key` | | str | — | API key for the endpoint (env: `JARVIS_BACKEND_API_KEY`) |
+| `--agent` | | str | — | Agent name for `jarvis-agent` backend (e.g., `orchestrator`) |
+| `--engine` | `-e` | str | auto | Engine key (`ollama`, `vllm`, `cloud`, ...) |
+| `--tools` | | str | `""` | Comma-separated tool names (e.g., `calculator,file_read`) |
+| `--telemetry/--no-telemetry` | | flag | off | Enable telemetry collection during eval |
+| `--gpu-metrics/--no-gpu-metrics` | | flag | off | Enable GPU metric polling |
 | `--seed` | | int | `42` | Random seed for dataset shuffling |
-| `--split` | | str | dataset default | Override the dataset split |
 | `--temperature` | | float | `0.0` | Generation temperature |
 | `--max-tokens` | | int | `2048` | Maximum output tokens |
+| `--model-filter` | | str | — | Filter models by name substring (multi-model configs) |
+| `--output` | `-o` | path | auto-generated | Output JSONL file path |
+| `--wandb-project` / `--wandb-entity` / `--wandb-tags` / `--wandb-group` | | str | `""` | Weights & Biases tracking (requires `eval-wandb` extra) |
+| `--sheets-id` / `--sheets-worksheet` / `--sheets-creds` | | str | `""` | Google Sheets export (requires `eval-sheets` extra) |
 | `--verbose` | `-v` | flag | off | Enable debug logging |

 *Required when `--config` is not provided.

+#### Research-only options (`python -m openjarvis.evals run`)
+
+The module CLI accepts everything above plus research-grade options that `jarvis eval run` does not expose:
+
+| Option | Short | Type | Default | Description |
+|--------|-------|------|---------|-------------|
+| `--max-workers` | `-w` | int | `4` | Parallel evaluation workers |
+| `--judge-model` | | str | `gpt-5-mini-2025-08-07` | LLM used for judge-based scoring (see `--help` for the current default) |
+| `--judge-engine` | | str | `cloud` | Engine key for the LLM judge; use `vllm` to judge locally |
+| `--split` | | str | dataset default | Override the dataset split |
+| `--compact` | | flag | off | Dense single-table output |
+| `--trace-detail` | | flag | off | Full per-step trace listing |
+| `--agentic` | | flag | off | Use `AgenticRunner` for multi-turn agent execution |
+| `--episode-mode` | | flag | off | Sequential episode processing with lifelong learning (required for `lifelong-agent` and similar benchmarks) |
+| `--concurrency` | | int | `1` | Parallel query execution (AgenticRunner only) |
+| `--query-timeout` | | float | — | Per-query wall-clock timeout in seconds (AgenticRunner only) |
+
+Note: the module CLI's `--backend` choice covers `jarvis-direct`, `jarvis-agent`, `hermes`, and `openclaw`; `terminalbench-native` as a backend is available via `jarvis eval run` and TOML configs.
+
 ### Run all benchmarks at once

-The `run-all` command evaluates a single model against all four benchmarks sequentially and writes results to an output directory:
+The `run-all` command (module CLI only) evaluates a single model against **every registered benchmark** sequentially and writes results to an output directory:

 ```bash
-openjarvis-eval run-all -m qwen3:8b
+uv run python -m openjarvis.evals run-all -m qwen3:8b

 # With options
-openjarvis-eval run-all -m gpt-4o -n 100 --output-dir results/gpt4o/
+uv run python -m openjarvis.evals run-all -m gpt-5-mini -n 100 --output-dir results/gpt5mini/
 ```

 Output files are written as `{output_dir}/{benchmark}_{model-slug}.jsonl`. The model slug replaces `/` and `:` with `-`, so `qwen3:8b` becomes `qwen3-8b`.
@@ -235,7 +305,7 @@ Output files are written as `{output_dir}/{benchmark}_{model-slug}.jsonl`. The m
 After a run, inspect a JSONL results file:

 ```bash
-openjarvis-eval summarize results/supergpqa_qwen3-8b.jsonl
+uv run python -m openjarvis.evals summarize results/supergpqa_qwen3-8b.jsonl
 ```

 Output:
@@ -251,6 +321,55 @@ Accuracy:  0.7222
 Errors:    2
 ```

+The module CLI also provides `reparse-judge`, which re-parses stored judge output in a results file and recovers records whose judge verdicts initially failed to parse — useful after improving the judge-output parser without re-running inference.
+
+### Compare and report
+
+`jarvis eval` adds two post-processing commands for result files:
+
+```bash
+# Side-by-side metric comparison across runs
+uv run jarvis eval compare results/supergpqa_qwen3-8b.jsonl results/supergpqa_gpt-5-mini.jsonl
+
+# Detailed report (accuracy, latency, cost, per-subject breakdown) for one run
+uv run jarvis eval report results/supergpqa_qwen3-8b.jsonl
+```
+
+---
+
+## Evaluating an Already-Running Endpoint
+
+If you already have an OpenAI-compatible server running — `jarvis serve`, vLLM, SGLang, llama.cpp's server, or a hosted endpoint — point an eval directly at it with `--base-url` and `--api-key`:
+
+```bash
+# A vLLM server is already serving Qwen/Qwen3-8B on a GPU node:
+#   vllm serve Qwen/Qwen3-8B --port 8000
+uv run jarvis eval run -b supergpqa -m Qwen/Qwen3-8B \
+    --base-url http://gpu-node:8000/v1 \
+    --api-key local-key \
+    -n 50
+```
+
+The `-m` value must match a model id the server reports at `GET /v1/models`. Both flags fall back to the `JARVIS_BACKEND_BASE_URL` and `JARVIS_BACKEND_API_KEY` environment variables, so CI jobs can set them once:
+
+```bash
+export JARVIS_BACKEND_BASE_URL=http://gpu-node:8000/v1
+export JARVIS_BACKEND_API_KEY=local-key
+uv run jarvis eval run -b gaia -m Qwen/Qwen3-8B --backend jarvis-agent -n 25
+```
+
+For the external `hermes` and `openclaw` backends these values are **required** (the foreign frameworks need an endpoint to send model calls to).
+
+!!! tip "Engine-level alternative for vLLM"
+    The vLLM engine also honors the `VLLM_HOST` environment variable (default `http://localhost:8000`):
+
+    ```bash
+    VLLM_HOST=http://gpu-node:8000 uv run python -m openjarvis.evals run \
+        -b supergpqa -m Qwen/Qwen3-8B -e vllm -n 50
+    ```
+
+    `VLLM_HOST` is process-global — if the candidate and the judge both use the `vllm` engine, they share the same endpoint. Prefer `--base-url` when you need them separate.
+
 ---

 ## TOML Config System
@@ -260,7 +379,7 @@ For research workflows that compare multiple models across multiple benchmarks,
 ### Running from a config

 ```bash
-openjarvis-eval run --config src/openjarvis/evals/configs/full-suite.toml
+uv run jarvis eval run --config src/openjarvis/evals/configs/full-suite.toml
 ```

 When `--config` is provided, the `-b`/`--benchmark` and `-m`/`--model` options are not required. All settings come from the config file. The CLI expands the matrix, prints a progress table, and writes results to the configured `output_dir`.
@@ -269,7 +388,7 @@ When `--config` is provided, the `-b`/`--benchmark` and `-m`/`--model` options a

 A config file has six sections: `[meta]`, `[defaults]`, `[judge]`, `[run]`, `[[models]]`, and `[[benchmarks]]`. Only `[[models]]` and `[[benchmarks]]` are required — all other sections are optional and fall back to built-in defaults.

-```toml title="evals/configs/full-suite.toml"
+```toml title="src/openjarvis/evals/configs/full-suite.toml"
 # Suite-level metadata (optional)
 [meta]
 name = "full-suite-v1"
@@ -353,7 +472,7 @@ For example, `temperature` is resolved as: use `[defaults].temperature` (0.0), t

 A config requires only one `[[models]]` and one `[[benchmarks]]` entry:

-```toml title="evals/configs/minimal.toml"
+```toml title="src/openjarvis/evals/configs/minimal.toml"
 [[models]]
 name = "qwen3:8b"

@@ -365,7 +484,7 @@ This runs SuperGPQA against qwen3:8b with all default settings. Use this as a st

 ### Single-run config with full options

-```toml title="evals/configs/single-run.toml"
+```toml title="src/openjarvis/evals/configs/single-run.toml"
 [meta]
 name = "single-run-example"
 description = "Evaluate SuperGPQA with a single model and full configuration"
@@ -425,7 +544,8 @@ Configuration for the LLM used as a judge in GAIA, FRAMES, and WildChat scoring.

 | Field | Type | Default | Description |
 |-------|------|---------|-------------|
-| `model` | str | `"gpt-4o"` | Judge model identifier |
+| `model` | str | `"gpt-5-mini-2025-08-07"` | Judge model identifier |
+| `engine` | str | `None` | Engine key for the judge (e.g., `"vllm"` to judge locally; defaults to cloud) |
 | `provider` | str | `None` | Provider override (e.g., `"openai"`) |
 | `temperature` | float | `0.0` | Judge sampling temperature |
 | `max_tokens` | int | `1024` | Maximum judge output tokens |
@@ -444,6 +564,20 @@ Execution settings that apply to the entire suite.
 | `seed` | int | `42` | Random seed for dataset shuffling |
 | `telemetry` | bool | `false` | Enable GPU telemetry capture (energy, power, utilization, throughput) |
 | `gpu_metrics` | bool | `false` | Enable GPU metric polling via `pynvml` (requires `pynvml` or `nvidia-ml-py`) |
+| `warmup_samples` | int | `0` | Untimed warmup samples before measurement |
+| `energy_vendor` | str | `""` | GPU energy vendor override |
+| `max_turns` | int | `None` | Maximum agent turns per query |
+| `wandb_project` / `wandb_entity` / `wandb_tags` / `wandb_group` | str | `""` | Weights & Biases tracking |
+| `sheets_spreadsheet_id` / `sheets_worksheet` / `sheets_credentials_path` | str | `""` / `"Results"` / `""` | Google Sheets export |
+
+### `[backend.external]`
+
+Endpoint settings for the `hermes` and `openclaw` backends. Environment variables override TOML values.
+
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `base_url` | str | `None` | OpenAI-compatible endpoint URL (env: `JARVIS_BACKEND_BASE_URL`) |
+| `api_key` | str | `None` | API key for the endpoint (env: `JARVIS_BACKEND_API_KEY`) |

 ### `[[models]]`

@@ -451,7 +585,7 @@ One block per model. The `name` field is required.

 | Field | Type | Default | Description |
 |-------|------|---------|-------------|
-| `name` | str | required | Model identifier (e.g., `"qwen3:8b"`, `"gpt-4o"`) |
+| `name` | str | required | Model identifier (e.g., `"qwen3:8b"`, `"gpt-5-mini"`) |
 | `engine` | str | `None` | Engine key to use (`"ollama"`, `"vllm"`, `"cloud"`, ...) |
 | `provider` | str | `None` | Provider override for cloud models (e.g., `"openai"`) |
 | `temperature` | float | `None` | Override `[defaults].temperature` for this model |
@@ -468,10 +602,12 @@ One block per benchmark. The `name` field is required.

 | Field | Type | Default | Description |
 |-------|------|---------|-------------|
-| `name` | str | required | Benchmark key: `supergpqa`, `gaia`, `frames`, or `wildchat` |
-| `backend` | str | `"jarvis-direct"` | Inference backend: `jarvis-direct` or `jarvis-agent` |
+| `name` | str | required | Any registered benchmark key (see `uv run python -m openjarvis.evals list`) |
+| `backend` | str | `"jarvis-direct"` | `jarvis-direct`, `jarvis-agent`, `hermes`, `openclaw`, or `terminalbench-native` |
 | `max_samples` | int | `None` | Limit number of samples; `None` evaluates the full dataset |
 | `split` | str | `None` | Override the default dataset split |
+| `subset` | str | `None` | Dataset subset/variant (benchmark-specific) |
+| `record_ids` | list[str] | `None` | Evaluate only these record ids |
 | `agent` | str | `None` | Agent name for `jarvis-agent` backend (e.g., `"orchestrator"`) |
 | `tools` | list[str] | `[]` | Tool names for `jarvis-agent` backend |
 | `judge_model` | str | `None` | Override `[judge].model` for this benchmark only |
@@ -647,7 +783,7 @@ The `EvalRunner` processes samples concurrently using a `ThreadPoolExecutor`. Re

 ```bash
 # Use more workers for faster evaluation (if the engine supports concurrent requests)
-openjarvis-eval run -b supergpqa -m qwen3:8b -w 8 -n 500
+uv run python -m openjarvis.evals run -b supergpqa -m qwen3:8b -w 8 -n 500
 ```

 !!! warning "Worker count and engine load"
@@ -1,12 +1,12 @@
 {
  "name": "openjarvis-chat",
-  "version": "0.1.0",
+  "version": "1.0.1",
  "lockfileVersion": 3,
  "requires": true,
  "packages": {
    "": {
      "name": "openjarvis-chat",
-      "version": "0.1.0",
+      "version": "1.0.1",
      "dependencies": {
        "@base-ui/react": "^1.3.0",
        "@fontsource-variable/geist": "^5.2.8",
@@ -48,7 +48,8 @@
        "@vitejs/plugin-react": "^4.3.4",
        "typescript": "~5.7.0",
        "vite": "^6.0.0",
-        "vite-plugin-pwa": "^1.2.0"
+        "vite-plugin-pwa": "^1.2.0",
+        "vitest": "^3.2.6"
      },
      "engines": {
        "node": ">=20"
@@ -4064,6 +4065,17 @@
        "@babel/types": "^7.28.2"
      }
    },
+    "node_modules/@types/chai": {
+      "version": "5.2.3",
+      "resolved": "https://registry.npmjs.org/@types/chai/-/chai-5.2.3.tgz",
+      "integrity": "sha512-Mw558oeA9fFbv65/y4mHtXDs9bPnFMZAL/jxdPFUpOHHIXX91mcgEHbS5Lahr+pwZFR8A7GQleRWeI6cGFC2UA==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@types/deep-eql": "*",
+        "assertion-error": "^2.0.1"
+      }
+    },
    "node_modules/@types/d3-array": {
      "version": "3.2.2",
      "resolved": "https://registry.npmjs.org/@types/d3-array/-/d3-array-3.2.2.tgz",
@@ -4136,6 +4148,13 @@
        "@types/ms": "*"
      }
    },
+    "node_modules/@types/deep-eql": {
+      "version": "4.0.2",
+      "resolved": "https://registry.npmjs.org/@types/deep-eql/-/deep-eql-4.0.2.tgz",
+      "integrity": "sha512-c9h9dVVMigMPc4bwTvC5dxqtqJZwQPePsWjPlpSOnojbor6pGqdk541lfA7AqFQr5pB1BRdq0juY9db81BwyFw==",
+      "dev": true,
+      "license": "MIT"
+    },
    "node_modules/@types/estree": {
      "version": "1.0.8",
      "resolved": "https://registry.npmjs.org/@types/estree/-/estree-1.0.8.tgz",
@@ -4274,6 +4293,131 @@
        "vite": "^4.2.0 || ^5.0.0 || ^6.0.0 || ^7.0.0"
      }
    },
+    "node_modules/@vitest/expect": {
+      "version": "3.2.6",
+      "resolved": "https://registry.npmjs.org/@vitest/expect/-/expect-3.2.6.tgz",
+      "integrity": "sha512-1+7q9BtaKzEmO+fmNT3kYvoNn5Y71XWAx2Q5HRim4tTVRQVRv4uJFAQ5FbK0OPUeNP/WmVCpxYxoJdvuHVjzBQ==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@types/chai": "^5.2.2",
+        "@vitest/spy": "3.2.6",
+        "@vitest/utils": "3.2.6",
+        "chai": "^5.2.0",
+        "tinyrainbow": "^2.0.0"
+      },
+      "funding": {
+        "url": "https://opencollective.com/vitest"
+      }
+    },
+    "node_modules/@vitest/mocker": {
+      "version": "3.2.6",
+      "resolved": "https://registry.npmjs.org/@vitest/mocker/-/mocker-3.2.6.tgz",
+      "integrity": "sha512-EZOrpDbkKotFAP7wPAQV1UIyoGOk4oX7ynWhBhLB7v+meMHbQhU16oPpIYGTTe4oFlhpryGpgpcZP/sin3hYuw==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@vitest/spy": "3.2.6",
+        "estree-walker": "^3.0.3",
+        "magic-string": "^0.30.17"
+      },
+      "funding": {
+        "url": "https://opencollective.com/vitest"
+      },
+      "peerDependencies": {
+        "msw": "^2.4.9",
+        "vite": "^5.0.0 || ^6.0.0 || ^7.0.0-0"
+      },
+      "peerDependenciesMeta": {
+        "msw": {
+          "optional": true
+        },
+        "vite": {
+          "optional": true
+        }
+      }
+    },
+    "node_modules/@vitest/mocker/node_modules/estree-walker": {
+      "version": "3.0.3",
+      "resolved": "https://registry.npmjs.org/estree-walker/-/estree-walker-3.0.3.tgz",
+      "integrity": "sha512-7RUKfXgSMMkzt6ZuXmqapOurLGPPfgj6l9uRZ7lRGolvk0y2yocc35LdcxKC5PQZdn2DMqioAQ2NoWcrTKmm6g==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@types/estree": "^1.0.0"
+      }
+    },
+    "node_modules/@vitest/pretty-format": {
+      "version": "3.2.6",
+      "resolved": "https://registry.npmjs.org/@vitest/pretty-format/-/pretty-format-3.2.6.tgz",
+      "integrity": "sha512-lb7XXXzmm2h2ASzFnRvQpDo6onT1NmMJA3tkGTWiBFtRJ9lxGY3d3mm/Apt36gej2bkkOVLL/yTOtufDaFa/jA==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "tinyrainbow": "^2.0.0"
+      },
+      "funding": {
+        "url": "https://opencollective.com/vitest"
+      }
+    },
+    "node_modules/@vitest/runner": {
+      "version": "3.2.6",
+      "resolved": "https://registry.npmjs.org/@vitest/runner/-/runner-3.2.6.tgz",
+      "integrity": "sha512-HYcoSj1w5tcgUnzoF0HcyaAQjpA1gj9ftUJ7iSJSuipc02jW9gKkigwZbjFldAfYHA1fa8UZVRftdMY5msWM9Q==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@vitest/utils": "3.2.6",
+        "pathe": "^2.0.3",
+        "strip-literal": "^3.0.0"
+      },
+      "funding": {
+        "url": "https://opencollective.com/vitest"
+      }
+    },
+    "node_modules/@vitest/snapshot": {
+      "version": "3.2.6",
+      "resolved": "https://registry.npmjs.org/@vitest/snapshot/-/snapshot-3.2.6.tgz",
+      "integrity": "sha512-H+ZjNTWGpObenh0YnlBctAPnJSI20P81PL8BPzWpx54YXLLTm8hEsWawtcYLMrwvpK48hGxLLbCS+1KRXhsKhw==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@vitest/pretty-format": "3.2.6",
+        "magic-string": "^0.30.17",
+        "pathe": "^2.0.3"
+      },
+      "funding": {
+        "url": "https://opencollective.com/vitest"
+      }
+    },
+    "node_modules/@vitest/spy": {
+      "version": "3.2.6",
+      "resolved": "https://registry.npmjs.org/@vitest/spy/-/spy-3.2.6.tgz",
+      "integrity": "sha512-oq6BbH68WzcWmwtBrU9nqLeaXTR4XwJF7FSLkKEZo4i6eoXcrxjcwSuTvWBIRUTC6VC72nXYunzqgZA+IKdtxg==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "tinyspy": "^4.0.3"
+      },
+      "funding": {
+        "url": "https://opencollective.com/vitest"
+      }
+    },
+    "node_modules/@vitest/utils": {
+      "version": "3.2.6",
+      "resolved": "https://registry.npmjs.org/@vitest/utils/-/utils-3.2.6.tgz",
+      "integrity": "sha512-lI23nIs4bnT3T8NIoh+vFaz5s2/DdP0Jgt2jxwgWljvwn82cLJtyi/If+fjFyoLMGIOz0U/fKvWE0d4jsNQEfg==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@vitest/pretty-format": "3.2.6",
+        "loupe": "^3.1.4",
+        "tinyrainbow": "^2.0.0"
+      },
+      "funding": {
+        "url": "https://opencollective.com/vitest"
+      }
+    },
    "node_modules/accepts": {
      "version": "2.0.0",
      "resolved": "https://registry.npmjs.org/accepts/-/accepts-2.0.0.tgz",
@@ -4414,6 +4558,16 @@
        "url": "https://github.com/sponsors/ljharb"
      }
    },
+    "node_modules/assertion-error": {
+      "version": "2.0.1",
+      "resolved": "https://registry.npmjs.org/assertion-error/-/assertion-error-2.0.1.tgz",
+      "integrity": "sha512-Izi8RQcffqCeNVgFigKli1ssklIbpHnCYc6AknXGYoB6grJqyeby7jv12JUQgmTAnIDnbck1uxksT4dzN3PWBA==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">=12"
+      }
+    },
    "node_modules/ast-types": {
      "version": "0.16.1",
      "resolved": "https://registry.npmjs.org/ast-types/-/ast-types-0.16.1.tgz",
@@ -4654,6 +4808,16 @@
        "node": ">= 0.8"
      }
    },
+    "node_modules/cac": {
+      "version": "6.7.14",
+      "resolved": "https://registry.npmjs.org/cac/-/cac-6.7.14.tgz",
+      "integrity": "sha512-b6Ilus+c3RrdDk+JhLKUAQfzzgLEPy6wcXqS7f/xe1EETvsDP6GORG7SFuOs6cID5YkqchW/LXZbX5bc8j7ZcQ==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">=8"
+      }
+    },
    "node_modules/call-bind": {
      "version": "1.0.8",
      "resolved": "https://registry.npmjs.org/call-bind/-/call-bind-1.0.8.tgz",
@@ -4741,6 +4905,23 @@
        "url": "https://github.com/sponsors/wooorm"
      }
    },
+    "node_modules/chai": {
+      "version": "5.3.3",
+      "resolved": "https://registry.npmjs.org/chai/-/chai-5.3.3.tgz",
+      "integrity": "sha512-4zNhdJD/iOjSH0A05ea+Ke6MU5mmpQcbQsSOkgdaUMJ9zTlDTD/GYlwohmIE2u0gaxHYiVHEn1Fw9mZ/ktJWgw==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "assertion-error": "^2.0.1",
+        "check-error": "^2.1.1",
+        "deep-eql": "^5.0.1",
+        "loupe": "^3.1.0",
+        "pathval": "^2.0.0"
+      },
+      "engines": {
+        "node": ">=18"
+      }
+    },
    "node_modules/chalk": {
      "version": "5.6.2",
      "resolved": "https://registry.npmjs.org/chalk/-/chalk-5.6.2.tgz",
@@ -4793,6 +4974,16 @@
        "url": "https://github.com/sponsors/wooorm"
      }
    },
+    "node_modules/check-error": {
+      "version": "2.1.3",
+      "resolved": "https://registry.npmjs.org/check-error/-/check-error-2.1.3.tgz",
+      "integrity": "sha512-PAJdDJusoxnwm1VwW07VWwUN1sl7smmC3OKggvndJFadxxDRyFJBX/ggnu/KE4kQAB7a3Dp8f/YXC1FlUprWmA==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">= 16"
+      }
+    },
    "node_modules/class-variance-authority": {
      "version": "0.7.1",
      "resolved": "https://registry.npmjs.org/class-variance-authority/-/class-variance-authority-0.7.1.tgz",
@@ -5390,6 +5581,16 @@
        }
      }
    },
+    "node_modules/deep-eql": {
+      "version": "5.0.2",
+      "resolved": "https://registry.npmjs.org/deep-eql/-/deep-eql-5.0.2.tgz",
+      "integrity": "sha512-h5k/5U50IJJFpzfL6nO9jaaumfjO/f2NjK/oYB2Djzm4p9L+3T9qWpZqZ2hAbLPuuYq9wrU08WQyBTL5GbPk5Q==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">=6"
+      }
+    },
    "node_modules/deepmerge": {
      "version": "4.3.1",
      "resolved": "https://registry.npmjs.org/deepmerge/-/deepmerge-4.3.1.tgz",
@@ -5749,6 +5950,13 @@
        "node": ">= 0.4"
      }
    },
+    "node_modules/es-module-lexer": {
+      "version": "1.7.0",
+      "resolved": "https://registry.npmjs.org/es-module-lexer/-/es-module-lexer-1.7.0.tgz",
+      "integrity": "sha512-jEQoCwk8hyb2AZziIOLhDqpm5+2ww5uIE6lkO/6jcOCusfk6LhMHpXXfBLXTZ7Ydyt0j4VoUQv6uGNYbdW+kBA==",
+      "dev": true,
+      "license": "MIT"
+    },
    "node_modules/es-object-atoms": {
      "version": "1.1.1",
      "resolved": "https://registry.npmjs.org/es-object-atoms/-/es-object-atoms-1.1.1.tgz",
@@ -5975,6 +6183,16 @@
        "url": "https://github.com/sindresorhus/execa?sponsor=1"
      }
    },
+    "node_modules/expect-type": {
+      "version": "1.3.0",
+      "resolved": "https://registry.npmjs.org/expect-type/-/expect-type-1.3.0.tgz",
+      "integrity": "sha512-knvyeauYhqjOYvQ66MznSMs83wmHrCycNEN6Ao+2AeYEfxUIkuiVxdEa1qlGEPK+We3n0THiDciYSsCcgW/DoA==",
+      "dev": true,
+      "license": "Apache-2.0",
+      "engines": {
+        "node": ">=12.0.0"
+      }
+    },
    "node_modules/express": {
      "version": "5.2.1",
      "resolved": "https://registry.npmjs.org/express/-/express-5.2.1.tgz",
@@ -8156,6 +8374,13 @@
        "url": "https://github.com/sponsors/wooorm"
      }
    },
+    "node_modules/loupe": {
+      "version": "3.2.1",
+      "resolved": "https://registry.npmjs.org/loupe/-/loupe-3.2.1.tgz",
+      "integrity": "sha512-CdzqowRJCeLU72bHvWqwRBBlLcMEtIvGrlvef74kMnV2AolS9Y8xUv1I0U/MNAWMhBlKIoyuEgoJ0t/bbwHbLQ==",
+      "dev": true,
+      "license": "MIT"
+    },
    "node_modules/lowlight": {
      "version": "3.3.0",
      "resolved": "https://registry.npmjs.org/lowlight/-/lowlight-3.3.0.tgz",
@@ -9742,6 +9967,23 @@
      "integrity": "sha512-Yhpw4T9C6hPpgPeA28us07OJeqZ5EzQTkbfwuhsUg0c237RomFoETJgmp2sa3F/41gfLE6G5cqcYwznmeEeOlQ==",
      "license": "MIT"
    },
+    "node_modules/pathe": {
+      "version": "2.0.3",
+      "resolved": "https://registry.npmjs.org/pathe/-/pathe-2.0.3.tgz",
+      "integrity": "sha512-WUjGcAqP1gQacoQe+OBJsFA7Ld4DyXuUIjZ5cc75cLHvJ7dtNsTugphxIADwspS+AraAUePCKrSVtPLFj/F88w==",
+      "dev": true,
+      "license": "MIT"
+    },
+    "node_modules/pathval": {
+      "version": "2.0.1",
+      "resolved": "https://registry.npmjs.org/pathval/-/pathval-2.0.1.tgz",
+      "integrity": "sha512-//nshmD55c46FuFw26xV/xFAaB5HF9Xdap7HJBBnrKdAd6/GxDBaNA1870O79+9ueg61cZLSVc+OaFlfmObYVQ==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">= 14.16"
+      }
+    },
    "node_modules/picocolors": {
      "version": "1.1.1",
      "resolved": "https://registry.npmjs.org/picocolors/-/picocolors-1.1.1.tgz",
@@ -10987,6 +11229,13 @@
        "url": "https://github.com/sponsors/ljharb"
      }
    },
+    "node_modules/siginfo": {
+      "version": "2.0.0",
+      "resolved": "https://registry.npmjs.org/siginfo/-/siginfo-2.0.0.tgz",
+      "integrity": "sha512-ybx0WO1/8bSBLEWXZvEd7gMW3Sn3JFlW3TvX1nREbDLRNQNaeNN8WK0meBwPdAaOI7TtRRRJn/Es1zhrrCHu7g==",
+      "dev": true,
+      "license": "ISC"
+    },
    "node_modules/signal-exit": {
      "version": "4.1.0",
      "resolved": "https://registry.npmjs.org/signal-exit/-/signal-exit-4.1.0.tgz",
@@ -11072,6 +11321,13 @@
        "url": "https://github.com/sponsors/wooorm"
      }
    },
+    "node_modules/stackback": {
+      "version": "0.0.2",
+      "resolved": "https://registry.npmjs.org/stackback/-/stackback-0.0.2.tgz",
+      "integrity": "sha512-1XMJE5fQo1jGH6Y/7ebnwPOBEkIEnT4QF32d5R1+VXdXveM0IBMJt8zfaxX1P3QhVwrYe+576+jkANtSS2mBbw==",
+      "dev": true,
+      "license": "MIT"
+    },
    "node_modules/statuses": {
      "version": "2.0.2",
      "resolved": "https://registry.npmjs.org/statuses/-/statuses-2.0.2.tgz",
@@ -11081,6 +11337,13 @@
        "node": ">= 0.8"
      }
    },
+    "node_modules/std-env": {
+      "version": "3.10.0",
+      "resolved": "https://registry.npmjs.org/std-env/-/std-env-3.10.0.tgz",
+      "integrity": "sha512-5GS12FdOZNliM5mAOxFRg7Ir0pWz8MdpYm6AY6VPkGpbA7ZzmbzNcBJQ0GPvvyWgcY7QAhCgf9Uy89I03faLkg==",
+      "dev": true,
+      "license": "MIT"
+    },
    "node_modules/stdin-discarder": {
      "version": "0.2.2",
      "resolved": "https://registry.npmjs.org/stdin-discarder/-/stdin-discarder-0.2.2.tgz",
@@ -11294,6 +11557,26 @@
        "url": "https://github.com/sponsors/sindresorhus"
      }
    },
+    "node_modules/strip-literal": {
+      "version": "3.1.0",
+      "resolved": "https://registry.npmjs.org/strip-literal/-/strip-literal-3.1.0.tgz",
+      "integrity": "sha512-8r3mkIM/2+PpjHoOtiAW8Rg3jJLHaV7xPwG+YRGrv6FP0wwk/toTpATxWYOW0BKdWwl82VT2tFYi5DlROa0Mxg==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "js-tokens": "^9.0.1"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/antfu"
+      }
+    },
+    "node_modules/strip-literal/node_modules/js-tokens": {
+      "version": "9.0.1",
+      "resolved": "https://registry.npmjs.org/js-tokens/-/js-tokens-9.0.1.tgz",
+      "integrity": "sha512-mxa9E9ITFOt0ban3j6L5MpjwegGz6lBQmM1IJkWeBZGcMxto50+eWdjC/52xDbS2vy0k7vIMK0Fe2wfL9OQSpQ==",
+      "dev": true,
+      "license": "MIT"
+    },
    "node_modules/style-to-js": {
      "version": "1.1.21",
      "resolved": "https://registry.npmjs.org/style-to-js/-/style-to-js-1.1.21.tgz",
@@ -11459,6 +11742,20 @@
      "integrity": "sha512-+FbBPE1o9QAYvviau/qC5SE3caw21q3xkvWKBtja5vgqOWIHHJ3ioaq1VPfn/Szqctz2bU/oYeKd9/z5BL+PVg==",
      "license": "MIT"
    },
+    "node_modules/tinybench": {
+      "version": "2.9.0",
+      "resolved": "https://registry.npmjs.org/tinybench/-/tinybench-2.9.0.tgz",
+      "integrity": "sha512-0+DUvqWMValLmha6lr4kD8iAMK1HzV0/aKnCtWb9v9641TnP/MFb7Pc2bxoxQjTXAErryXVgUOfv2YqNllqGeg==",
+      "dev": true,
+      "license": "MIT"
+    },
+    "node_modules/tinyexec": {
+      "version": "0.3.2",
+      "resolved": "https://registry.npmjs.org/tinyexec/-/tinyexec-0.3.2.tgz",
+      "integrity": "sha512-KQQR9yN7R5+OSwaK0XQoj22pwHoTlgYqmUscPYoknOoWCWfj/5/ABTMRi69FrKU5ffPVh5QcFikpWJI/P1ocHA==",
+      "dev": true,
+      "license": "MIT"
+    },
    "node_modules/tinyglobby": {
      "version": "0.2.15",
      "resolved": "https://registry.npmjs.org/tinyglobby/-/tinyglobby-0.2.15.tgz",
@@ -11475,6 +11772,36 @@
        "url": "https://github.com/sponsors/SuperchupuDev"
      }
    },
+    "node_modules/tinypool": {
+      "version": "1.1.1",
+      "resolved": "https://registry.npmjs.org/tinypool/-/tinypool-1.1.1.tgz",
+      "integrity": "sha512-Zba82s87IFq9A9XmjiX5uZA/ARWDrB03OHlq+Vw1fSdt0I+4/Kutwy8BP4Y/y/aORMo61FQ0vIb5j44vSo5Pkg==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": "^18.0.0 || >=20.0.0"
+      }
+    },
+    "node_modules/tinyrainbow": {
+      "version": "2.0.0",
+      "resolved": "https://registry.npmjs.org/tinyrainbow/-/tinyrainbow-2.0.0.tgz",
+      "integrity": "sha512-op4nsTR47R6p0vMUUoYl/a+ljLFVtlfaXkLQmqfLR1qHma1h/ysYk4hEXZ880bf2CYgTskvTa/e196Vd5dDQXw==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">=14.0.0"
+      }
+    },
+    "node_modules/tinyspy": {
+      "version": "4.0.4",
+      "resolved": "https://registry.npmjs.org/tinyspy/-/tinyspy-4.0.4.tgz",
+      "integrity": "sha512-azl+t0z7pw/z958Gy9svOTuzqIk6xq+NSheJzn5MMWtWTFywIacg2wUlzKFGtt3cthx0r2SxMK0yzJOR0IES7Q==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">=14.0.0"
+      }
+    },
    "node_modules/tldts": {
      "version": "7.0.27",
      "resolved": "https://registry.npmjs.org/tldts/-/tldts-7.0.27.tgz",
@@ -12164,6 +12491,29 @@
        }
      }
    },
+    "node_modules/vite-node": {
+      "version": "3.2.4",
+      "resolved": "https://registry.npmjs.org/vite-node/-/vite-node-3.2.4.tgz",
+      "integrity": "sha512-EbKSKh+bh1E1IFxeO0pg1n4dvoOTt0UDiXMd/qn++r98+jPO1xtJilvXldeuQ8giIB5IkpjCgMleHMNEsGH6pg==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "cac": "^6.7.14",
+        "debug": "^4.4.1",
+        "es-module-lexer": "^1.7.0",
+        "pathe": "^2.0.3",
+        "vite": "^5.0.0 || ^6.0.0 || ^7.0.0-0"
+      },
+      "bin": {
+        "vite-node": "vite-node.mjs"
+      },
+      "engines": {
+        "node": "^18.0.0 || ^20.0.0 || >=22.0.0"
+      },
+      "funding": {
+        "url": "https://opencollective.com/vitest"
+      }
+    },
    "node_modules/vite-plugin-pwa": {
      "version": "1.2.0",
      "resolved": "https://registry.npmjs.org/vite-plugin-pwa/-/vite-plugin-pwa-1.2.0.tgz",
@@ -12195,6 +12545,79 @@
        }
      }
    },
+    "node_modules/vitest": {
+      "version": "3.2.6",
+      "resolved": "https://registry.npmjs.org/vitest/-/vitest-3.2.6.tgz",
+      "integrity": "sha512-xejya+bT/j/+R/AGa1XOfRxLmNUlLtlwjRsFUILF+xHfzElmGcmFydy2gqqIrd62ptIEfwVMofd19uNWD9L7Nw==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@types/chai": "^5.2.2",
+        "@vitest/expect": "3.2.6",
+        "@vitest/mocker": "3.2.6",
+        "@vitest/pretty-format": "^3.2.6",
+        "@vitest/runner": "3.2.6",
+        "@vitest/snapshot": "3.2.6",
+        "@vitest/spy": "3.2.6",
+        "@vitest/utils": "3.2.6",
+        "chai": "^5.2.0",
+        "debug": "^4.4.1",
+        "expect-type": "^1.2.1",
+        "magic-string": "^0.30.17",
+        "pathe": "^2.0.3",
+        "picomatch": "^4.0.2",
+        "std-env": "^3.9.0",
+        "tinybench": "^2.9.0",
+        "tinyexec": "^0.3.2",
+        "tinyglobby": "^0.2.14",
+        "tinypool": "^1.1.1",
+        "tinyrainbow": "^2.0.0",
+        "vite": "^5.0.0 || ^6.0.0 || ^7.0.0-0",
+        "vite-node": "3.2.4",
+        "why-is-node-running": "^2.3.0"
+      },
+      "bin": {
+        "vitest": "vitest.mjs"
+      },
+      "engines": {
+        "node": "^18.0.0 || ^20.0.0 || >=22.0.0"
+      },
+      "funding": {
+        "url": "https://opencollective.com/vitest"
+      },
+      "peerDependencies": {
+        "@edge-runtime/vm": "*",
+        "@types/debug": "^4.1.12",
+        "@types/node": "^18.0.0 || ^20.0.0 || >=22.0.0",
+        "@vitest/browser": "3.2.6",
+        "@vitest/ui": "3.2.6",
+        "happy-dom": "*",
+        "jsdom": "*"
+      },
+      "peerDependenciesMeta": {
+        "@edge-runtime/vm": {
+          "optional": true
+        },
+        "@types/debug": {
+          "optional": true
+        },
+        "@types/node": {
+          "optional": true
+        },
+        "@vitest/browser": {
+          "optional": true
+        },
+        "@vitest/ui": {
+          "optional": true
+        },
+        "happy-dom": {
+          "optional": true
+        },
+        "jsdom": {
+          "optional": true
+        }
+      }
+    },
    "node_modules/web-namespaces": {
      "version": "2.0.1",
      "resolved": "https://registry.npmjs.org/web-namespaces/-/web-namespaces-2.0.1.tgz",
@@ -12343,6 +12766,23 @@
        "url": "https://github.com/sponsors/ljharb"
      }
    },
+    "node_modules/why-is-node-running": {
+      "version": "2.3.0",
+      "resolved": "https://registry.npmjs.org/why-is-node-running/-/why-is-node-running-2.3.0.tgz",
+      "integrity": "sha512-hUrmaWBdVDcxvYqnyh09zunKzROWjbZTiNy8dBEjkS7ehEDQibXJ7XvlmtbwuTclUiIyN+CyXQD4Vmko8fNm8w==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "siginfo": "^2.0.0",
+        "stackback": "0.0.2"
+      },
+      "bin": {
+        "why-is-node-running": "cli.js"
+      },
+      "engines": {
+        "node": ">=8"
+      }
+    },
    "node_modules/workbox-background-sync": {
      "version": "7.4.0",
      "resolved": "https://registry.npmjs.org/workbox-background-sync/-/workbox-background-sync-7.4.0.tgz",
@@ -11,7 +11,8 @@
    "build": "tsc -b && vite build",
    "build:tauri": "tsc -b && vite build --outDir dist",
    "preview": "vite preview",
-    "tauri": "tauri"
+    "tauri": "tauri",
+    "test": "vitest run"
  },
  "dependencies": {
    "@base-ui/react": "^1.3.0",
@@ -54,6 +55,7 @@
    "@vitejs/plugin-react": "^4.3.4",
    "typescript": "~5.7.0",
    "vite": "^6.0.0",
-    "vite-plugin-pwa": "^1.2.0"
+    "vite-plugin-pwa": "^1.2.0",
+    "vitest": "^3.2.6"
  }
 }
@@ -1384,7 +1384,7 @@ source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "0bb0228f477c0900c880fd78c8759b95c7636dbd7842707f49e132378aa2acdc"
 dependencies = [
 "heck 0.4.1",
- "proc-macro-crate 2.0.2",
+ "proc-macro-crate 2.0.0",
 "proc-macro-error",
 "proc-macro2",
 "quote",
@@ -2593,7 +2593,7 @@ dependencies = [

 [[package]]
 name = "openjarvis-desktop"
-version = "0.1.0"
+version = "1.0.1"
 dependencies = [
 "dispatch",
 "objc",
@@ -2611,6 +2611,7 @@ dependencies = [
 "tauri-plugin-single-instance",
 "tauri-plugin-updater",
 "tokio",
+ "toml_edit 0.22.27",
 ]

 [[package]]
@@ -3018,11 +3019,10 @@ dependencies = [

 [[package]]
 name = "proc-macro-crate"
-version = "2.0.2"
+version = "2.0.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "b00f26d3400549137f92511a46ac1cd8ce37cb5598a96d382381458b992a5d24"
+checksum = "7e8366a6159044a37876a2b9817124296703c586a5c92e2c53751fa06d8d43e8"
 dependencies = [
- "toml_datetime 0.6.3",
 "toml_edit 0.20.2",
 ]

@@ -4766,7 +4766,7 @@ checksum = "185d8ab0dfbb35cf1399a6344d8484209c088f75f8f68230da55d48d95d43e3d"
 dependencies = [
 "serde",
 "serde_spanned 0.6.9",
- "toml_datetime 0.6.3",
+ "toml_datetime 0.6.11",
 "toml_edit 0.20.2",
 ]

@@ -4802,9 +4802,9 @@ dependencies = [

 [[package]]
 name = "toml_datetime"
-version = "0.6.3"
+version = "0.6.11"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "7cda73e2f1397b1262d6dfdcef8aafae14d1de7748d66822d3bfeeb6d03e5e4b"
+checksum = "22cddaf88f4fbc13c51aebbf5f8eceb5c7c5a9da2ac40a13519eb5b0a0e8f11c"
 dependencies = [
 "serde",
 ]
@@ -4834,7 +4834,7 @@ source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "1b5bb770da30e5cbfde35a2d7b9b8a2c4b8ef89548a7a6aeab5c9a576e3e7421"
 dependencies = [
 "indexmap 2.13.0",
- "toml_datetime 0.6.3",
+ "toml_datetime 0.6.11",
 "winnow 0.5.40",
 ]

@@ -4847,10 +4847,22 @@ dependencies = [
 "indexmap 2.13.0",
 "serde",
 "serde_spanned 0.6.9",
- "toml_datetime 0.6.3",
+ "toml_datetime 0.6.11",
 "winnow 0.5.40",
 ]

+[[package]]
+name = "toml_edit"
+version = "0.22.27"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "41fe8c660ae4257887cf66394862d21dbca4a6ddd26f04a3560410406a2f819a"
+dependencies = [
+ "indexmap 2.13.0",
+ "toml_datetime 0.6.11",
+ "toml_write",
+ "winnow 0.7.14",
+]
+
 [[package]]
 name = "toml_edit"
 version = "0.23.10+spec-1.0.0"
@@ -4872,6 +4884,12 @@ dependencies = [
 "winnow 0.7.14",
 ]

+[[package]]
+name = "toml_write"
+version = "0.1.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "5d99f8c9a7727884afe522e9bd5edbfc91a3312b36a77b5fb8926e4c31a41801"
+
 [[package]]
 name = "toml_writer"
 version = "1.0.6+spec-1.1.0"
@@ -9,6 +9,7 @@ license = "MIT"
 tauri-build = { version = "2", features = [] }

 [dependencies]
+toml_edit = "0.22"
 tauri = { version = "2", features = ["tray-icon"] }
 tauri-plugin-notification = "2"
 tauri-plugin-shell = "2"
@@ -21,7 +21,12 @@ export default function App() {
  const [setupDone, setSetupDone] = useState(!isTauri());
  const handleSetupReady = useCallback(() => {
    setSetupDone(true);
-    track('setup_completed', { preset: 'default' });
+    // Only fire once per install — guard against setup screen re-appearing
+    // on reinstalls or dev reloads.
+    if (!localStorage.getItem('oj-setup-completed')) {
+      localStorage.setItem('oj-setup-completed', '1');
+      track('setup_completed', { preset: 'default' });
+    }
  }, []);
  const prevModelRef = useRef<string>('');
  const setModels = useAppStore((s) => s.setModels);
@@ -1,5 +1,6 @@
 import { useState, useRef, useCallback, useEffect } from 'react';
 import { Send, Square, Paperclip, Search } from 'lucide-react';
+import { toast } from 'sonner';
 import { useAppStore, generateId } from '../../lib/store';
 import { streamChat, streamResearch } from '../../lib/sse';
 import { fetchSavings, getBase } from '../../lib/api';
@@ -155,6 +156,10 @@ export function InputArea() {
  const sendMessage = useCallback(async () => {
    const content = input.trim();
    if (!content || streamState.isStreaming) return;
+    if (!selectedModel) {
+      toast.error('Pick a model first (⌘K)');
+      return;
+    }

    setInput('');

@@ -303,6 +308,23 @@ export function InputArea() {
              energy_j: ev.energy_j,
              duration_s: ev.duration_s,
            });
+          } else if (ev.type === 'error') {
+            // Backend setup/worker failure (Ollama down, planner model
+            // missing, KnowledgeStore locked, etc.). Without surfacing the
+            // message, the user sees only the generic "No response was
+            // generated" fallback and has no way to self-diagnose.
+            const msg = ev.message || 'Research failed (no detail provided)';
+            accumulatedContent = accumulatedContent
+              ? `${accumulatedContent}\n\n**Research stopped:** ${msg}`
+              : `**Research failed:** ${msg}`;
+            setStreamState({ content: accumulatedContent, phase: '' });
+            useAppStore.getState().addLogEntry({
+              timestamp: Date.now(),
+              level: 'error',
+              category: 'chat',
+              message: `Deep Research error: ${msg}`,
+            });
+            toast.error(msg, { duration: 8000 });
          } else if (ev.type === 'done') {
            if (ev.usage) {
              usage = {
@@ -555,7 +577,7 @@ export function InputArea() {
          value={input}
          onChange={(e) => setInput(e.target.value)}
          onKeyDown={handleKeyDown}
-          placeholder="Message OpenJarvis..."
+          placeholder={selectedModel ? 'Message OpenJarvis...' : 'Pick a model first (⌘K)...'}
          rows={1}
          className="flex-1 bg-transparent outline-none resize-none text-sm leading-relaxed"
          style={{ color: 'var(--color-text)', maxHeight: '200px' }}
@@ -580,13 +602,13 @@ export function InputArea() {
            />
            <button
              onClick={sendMessage}
-              disabled={!input.trim() || modelLoading}
+              disabled={!input.trim() || modelLoading || !selectedModel}
+              title={selectedModel ? 'Send message' : 'Pick a model first (⌘K)'}
              className="p-2 rounded-xl transition-colors shrink-0 cursor-pointer disabled:opacity-30 disabled:cursor-default"
              style={{
                background: input.trim() ? 'var(--color-accent)' : 'var(--color-bg-tertiary)',
                color: input.trim() ? 'white' : 'var(--color-text-tertiary)',
              }}
-              title="Send message"
            >
              <Send size={16} />
            </button>
@@ -1,6 +1,12 @@
-import { useState, useEffect, useCallback } from 'react';
+import { useState, useEffect, useCallback, useRef } from 'react';
 import { Loader2, CheckCircle2, XCircle, Cpu, Server, Database } from 'lucide-react';
-import { getSetupStatus, type SetupStatus } from '../lib/api';
+import {
+  getSetupStatus,
+  fetchModels,
+  fetchRecommendedModel,
+  type SetupStatus,
+} from '../lib/api';
+import { useAppStore } from '../lib/store';

 const STEPS = [
  { key: 'ollama_ready', label: 'Inference Engine', icon: Cpu, detail: 'Starting Ollama...' },
@@ -70,10 +76,33 @@ function StepRow({

 export function SetupScreen({ onReady }: { onReady: () => void }) {
  const [status, setStatus] = useState<SetupStatus | null>(null);
+  const handedOffRef = useRef(false);
  const poll = useCallback(async () => {
    const s = await getSetupStatus();
    if (s) setStatus(s);
-    if (s?.phase === 'ready') {
+    if (s?.phase === 'ready' && !handedOffRef.current) {
+      handedOffRef.current = true;
+      // Pre-select a model BEFORE handing off so the chat is usable on
+      // first send. Without this, the main app's post-mount fetch can
+      // lose a race to a fast first message and Ollama 400s.
+      try {
+        const [models, rec] = await Promise.all([
+          fetchModels().catch(() => []),
+          fetchRecommendedModel().catch(() => ({ model: '', reason: '' })),
+        ]);
+        const store = useAppStore.getState();
+        store.setModels(models);
+        store.setModelsLoading(false);
+        const recommended = rec.model && models.some((m) => m.id === rec.model)
+          ? rec.model
+          : models[0]?.id || '';
+        if (recommended && !store.selectedModel) {
+          store.setSelectedModel(recommended);
+        }
+      } catch {
+        // Non-fatal: store.setModels auto-selects on later fetch, and
+        // the InputArea guards the empty-model case with a toast.
+      }
      setTimeout(() => onReady(), 600);
    }
  }, [onReady]);
@@ -117,7 +146,14 @@ export function SetupScreen({ onReady }: { onReady: () => void }) {

        {/* Steps */}
        <div className="flex flex-col gap-2 mb-8">
-          {STEPS.map((step) => (
+          {(status?.source === 'custom'
+            ? [
+                { key: 'ollama_ready' as const, label: 'Inference Engine', icon: Cpu, detail: 'Connecting to your server...' },
+                { key: 'model_ready' as const, label: 'Endpoint', icon: Database, detail: 'Checking endpoint...' },
+                { key: 'server_ready' as const, label: 'API Server', icon: Server, detail: 'Starting server...' },
+              ]
+            : STEPS
+          ).map((step) => (
            <StepRow
              key={step.key}
              icon={step.icon}
@@ -0,0 +1,85 @@
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+
+// Regression for #266: the frontend must send the local API key as a Bearer
+// token on /v1 + /api requests, or `jarvis serve` with a key configured 401s
+// every data-plane call. These tests cover the pure helpers (getApiKey,
+// authHeaders) that source the key and build the header.
+
+const SETTINGS_KEY = 'openjarvis-settings';
+
+// Minimal in-memory localStorage stub so the helpers can run under node
+// (no jsdom dependency).
+class MemoryStorage {
+  private store = new Map<string, string>();
+  getItem(k: string): string | null {
+    return this.store.has(k) ? (this.store.get(k) as string) : null;
+  }
+  setItem(k: string, v: string): void {
+    this.store.set(k, String(v));
+  }
+  removeItem(k: string): void {
+    this.store.delete(k);
+  }
+  clear(): void {
+    this.store.clear();
+  }
+}
+
+beforeEach(() => {
+  (globalThis as unknown as { localStorage: MemoryStorage }).localStorage =
+    new MemoryStorage();
+});
+
+afterEach(() => {
+  (globalThis as unknown as { localStorage?: MemoryStorage }).localStorage =
+    undefined;
+});
+
+async function freshApi() {
+  // Re-import to pick up the current localStorage stub.
+  return await import('./api');
+}
+
+describe('getApiKey', () => {
+  it('returns empty string when no key is configured', async () => {
+    const { getApiKey } = await freshApi();
+    expect(getApiKey()).toBe('');
+  });
+
+  it('reads apiKey from the openjarvis-settings localStorage blob', async () => {
+    localStorage.setItem(
+      SETTINGS_KEY,
+      JSON.stringify({ apiUrl: 'http://x', apiKey: 'sk-local-123' }),
+    );
+    const { getApiKey } = await freshApi();
+    expect(getApiKey()).toBe('sk-local-123');
+  });
+
+  it('returns empty string when the blob has no apiKey field', async () => {
+    localStorage.setItem(SETTINGS_KEY, JSON.stringify({ apiUrl: 'http://x' }));
+    const { getApiKey } = await freshApi();
+    expect(getApiKey()).toBe('');
+  });
+});
+
+describe('authHeaders', () => {
+  it('omits Authorization when no key is set (keyless default unchanged)', async () => {
+    const { authHeaders } = await freshApi();
+    expect(authHeaders()).toEqual({});
+  });
+
+  it('adds a Bearer Authorization header when a key is set', async () => {
+    localStorage.setItem(SETTINGS_KEY, JSON.stringify({ apiKey: 'sk-local-123' }));
+    const { authHeaders } = await freshApi();
+    expect(authHeaders()).toEqual({ Authorization: 'Bearer sk-local-123' });
+  });
+
+  it('merges extra headers alongside Authorization', async () => {
+    localStorage.setItem(SETTINGS_KEY, JSON.stringify({ apiKey: 'sk-local-123' }));
+    const { authHeaders } = await freshApi();
+    expect(authHeaders({ 'Content-Type': 'application/json' })).toEqual({
+      'Content-Type': 'application/json',
+      Authorization: 'Bearer sk-local-123',
+    });
+  });
+});
@@ -52,6 +52,50 @@ export const getBase = (): string => {
  return '';
 };

+// Resolve the local server API key (OPENJARVIS_API_KEY). When `jarvis serve`
+// is started with a key, AuthMiddleware 401s every /v1 and /api request that
+// lacks a Bearer token — so the frontend must send it (#266). Sourced from the
+// same settings blob as the API URL, with an optional build-time env override.
+// Returns '' when unset, so a keyless local server keeps working unchanged.
+export const getApiKey = (): string => {
+  try {
+    const raw = localStorage.getItem('openjarvis-settings');
+    if (raw) {
+      const parsed = JSON.parse(raw);
+      if (parsed.apiKey) return String(parsed.apiKey);
+    }
+  } catch {}
+  if (import.meta.env.VITE_OPENJARVIS_API_KEY) {
+    return import.meta.env.VITE_OPENJARVIS_API_KEY as string;
+  }
+  return '';
+};
+
+// Build request headers with the Bearer Authorization token when a local key
+// is configured, merging any caller-supplied headers. Adds no Authorization
+// header when no key is set, so keyless local dev is byte-for-byte unchanged.
+export const authHeaders = (
+  extra: Record<string, string> = {},
+): Record<string, string> => {
+  const key = getApiKey();
+  return key ? { ...extra, Authorization: `Bearer ${key}` } : { ...extra };
+};
+
+// Centralized fetch for the local server: prepends getBase() and injects the
+// Bearer auth header (when a key is set) on every call. Using this everywhere
+// guarantees no /v1 or /api request is sent without auth — the bug in #266 was
+// that direct fetch() calls omitted the header and 401'd. `path` is the
+// server-relative path (e.g. "/v1/savings").
+export const apiFetch = (
+  path: string,
+  init: RequestInit = {},
+): Promise<Response> => {
+  const headers = authHeaders(
+    (init.headers as Record<string, string> | undefined) ?? {},
+  );
+  return fetch(`${getBase()}${path}`, { ...init, headers });
+};
+
 async function tauriInvoke<T>(command: string, args: Record<string, unknown> = {}): Promise<T> {
  const { invoke } = await import('@tauri-apps/api/core');
  const apiUrl = getBase();
@@ -69,6 +113,7 @@ export interface SetupStatus {
  server_ready: boolean;
  model_ready: boolean;
  error: string | null;
+  source?: 'ollama' | 'custom'; // drives source-aware setup labels
 }

 export async function getSetupStatus(): Promise<SetupStatus | null> {
@@ -94,14 +139,14 @@ export async function fetchModels(): Promise<ModelInfo[]> {
      // Fall through to fetch
    }
  }
-  const res = await fetch(`${getBase()}/v1/models`);
+  const res = await apiFetch(`/v1/models`);
  if (!res.ok) throw new Error(`Failed to fetch models: ${res.status}`);
  const data = await res.json();
  return data.data || [];
 }

 export async function fetchRecommendedModel(): Promise<{ model: string; reason: string }> {
-  const res = await fetch(`${getBase()}/v1/recommended-model`);
+  const res = await apiFetch(`/v1/recommended-model`);
  if (!res.ok) return { model: '', reason: 'Failed to fetch' };
  return res.json();
 }
@@ -118,7 +163,7 @@ export async function pullModel(modelName: string): Promise<void> {
      throw new Error(e?.message || e || 'Download failed');
    }
  }
-  const res = await fetch(`${getBase()}/v1/models/pull`, {
+  const res = await apiFetch(`/v1/models/pull`, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ model: modelName }),
@@ -139,7 +184,7 @@ export async function deleteModel(modelName: string): Promise<void> {
      throw new Error(e?.message || e || 'Delete failed');
    }
  }
-  const res = await fetch(`${getBase()}/v1/models/${encodeURIComponent(modelName)}`, {
+  const res = await apiFetch(`/v1/models/${encodeURIComponent(modelName)}`, {
    method: 'DELETE',
  });
  if (!res.ok) {
@@ -172,13 +217,13 @@ export async function preloadModel(modelName: string): Promise<void> {
 }

 export async function fetchSavings(): Promise<SavingsData> {
-  const res = await fetch(`${getBase()}/v1/savings`);
+  const res = await apiFetch(`/v1/savings`);
  if (!res.ok) throw new Error(`Failed to fetch savings: ${res.status}`);
  return res.json();
 }

 export async function fetchServerInfo(): Promise<ServerInfo> {
-  const res = await fetch(`${getBase()}/v1/info`);
+  const res = await apiFetch(`/v1/info`);
  if (!res.ok) throw new Error(`Failed to fetch server info: ${res.status}`);
  return res.json();
 }
@@ -220,7 +265,7 @@ export async function fetchEnergy(): Promise<unknown> {
      return await tauriInvoke('fetch_energy', { apiUrl: getBase() });
    } catch {}
  }
-  const res = await fetch(`${getBase()}/v1/telemetry/energy`);
+  const res = await apiFetch(`/v1/telemetry/energy`);
  if (!res.ok) throw new Error(`Failed: ${res.status}`);
  return res.json();
 }
@@ -231,7 +276,7 @@ export async function fetchTelemetry(): Promise<unknown> {
      return await tauriInvoke('fetch_telemetry', { apiUrl: getBase() });
    } catch {}
  }
-  const res = await fetch(`${getBase()}/v1/telemetry/stats`);
+  const res = await apiFetch(`/v1/telemetry/stats`);
  if (!res.ok) throw new Error(`Failed: ${res.status}`);
  return res.json();
 }
@@ -242,7 +287,7 @@ export async function fetchTraces(limit: number = 50): Promise<unknown> {
      return await tauriInvoke('fetch_traces', { apiUrl: getBase(), limit });
    } catch {}
  }
-  const res = await fetch(`${getBase()}/v1/traces?limit=${limit}`);
+  const res = await apiFetch(`/v1/traces?limit=${limit}`);
  if (!res.ok) throw new Error(`Failed: ${res.status}`);
  return res.json();
 }
@@ -278,7 +323,7 @@ export async function transcribeAudio(audioBlob: Blob, filename = 'recording.web
  }
  const formData = new FormData();
  formData.append('file', audioBlob, filename);
-  const res = await fetch(`${getBase()}/v1/speech/transcribe`, {
+  const res = await apiFetch(`/v1/speech/transcribe`, {
    method: 'POST',
    body: formData,
  });
@@ -294,7 +339,7 @@ export async function fetchSpeechHealth(): Promise<SpeechHealth> {
      return { available: false };
    }
  }
-  const res = await fetch(`${getBase()}/v1/speech/health`);
+  const res = await apiFetch(`/v1/speech/health`);
  if (!res.ok) return { available: false };
  return res.json();
 }
@@ -378,14 +423,14 @@ export interface AgentMessage {
 }

 export async function fetchManagedAgents(): Promise<ManagedAgent[]> {
-  const res = await fetch(`${getBase()}/v1/managed-agents`);
+  const res = await apiFetch(`/v1/managed-agents`);
  if (!res.ok) throw new Error(`Failed: ${res.status}`);
  const data = await res.json();
  return data.agents || [];
 }

 export async function fetchManagedAgent(agentId: string): Promise<ManagedAgent> {
-  const res = await fetch(`${getBase()}/v1/managed-agents/${agentId}`);
+  const res = await apiFetch(`/v1/managed-agents/${agentId}`);
  if (!res.ok) throw new Error(`Failed: ${res.status}`);
  return res.json();
 }
@@ -396,7 +441,7 @@ export async function createManagedAgent(body: {
  template_id?: string;
  config?: Record<string, unknown>;
 }): Promise<ManagedAgent> {
-  const res = await fetch(`${getBase()}/v1/managed-agents`, {
+  const res = await apiFetch(`/v1/managed-agents`, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify(body),
@@ -409,7 +454,7 @@ export async function updateManagedAgent(
  agentId: string,
  body: Partial<{ name: string; agent_type: string; config: Record<string, unknown> }>,
 ): Promise<ManagedAgent> {
-  const res = await fetch(`${getBase()}/v1/managed-agents/${agentId}`, {
+  const res = await apiFetch(`/v1/managed-agents/${agentId}`, {
    method: 'PATCH',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify(body),
@@ -419,29 +464,29 @@ export async function updateManagedAgent(
 }

 export async function deleteManagedAgent(agentId: string): Promise<void> {
-  const res = await fetch(`${getBase()}/v1/managed-agents/${agentId}`, { method: 'DELETE' });
+  const res = await apiFetch(`/v1/managed-agents/${agentId}`, { method: 'DELETE' });
  if (!res.ok) throw new Error(`Failed: ${res.status}`);
 }

 export async function pauseManagedAgent(agentId: string): Promise<void> {
-  const res = await fetch(`${getBase()}/v1/managed-agents/${agentId}/pause`, { method: 'POST' });
+  const res = await apiFetch(`/v1/managed-agents/${agentId}/pause`, { method: 'POST' });
  if (!res.ok) throw new Error(`Failed: ${res.status}`);
 }

 export async function resumeManagedAgent(agentId: string): Promise<void> {
-  const res = await fetch(`${getBase()}/v1/managed-agents/${agentId}/resume`, { method: 'POST' });
+  const res = await apiFetch(`/v1/managed-agents/${agentId}/resume`, { method: 'POST' });
  if (!res.ok) throw new Error(`Failed: ${res.status}`);
 }

 export async function fetchAgentTasks(agentId: string): Promise<AgentTask[]> {
-  const res = await fetch(`${getBase()}/v1/managed-agents/${agentId}/tasks`);
+  const res = await apiFetch(`/v1/managed-agents/${agentId}/tasks`);
  if (!res.ok) throw new Error(`Failed: ${res.status}`);
  const data = await res.json();
  return data.tasks || [];
 }

 export async function createAgentTask(agentId: string, description: string): Promise<AgentTask> {
-  const res = await fetch(`${getBase()}/v1/managed-agents/${agentId}/tasks`, {
+  const res = await apiFetch(`/v1/managed-agents/${agentId}/tasks`, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ description }),
@@ -451,7 +496,7 @@ export async function createAgentTask(agentId: string, description: string): Pro
 }

 export async function fetchAgentChannels(agentId: string): Promise<ChannelBinding[]> {
-  const res = await fetch(`${getBase()}/v1/managed-agents/${agentId}/channels`);
+  const res = await apiFetch(`/v1/managed-agents/${agentId}/channels`);
  if (!res.ok) throw new Error(`Failed: ${res.status}`);
  const data = await res.json();
  return data.bindings || [];
@@ -495,7 +540,7 @@ export async function sendblueVerify(
  apiKeyId: string,
  apiSecretKey: string,
 ): Promise<{ valid: boolean; numbers: string[]; raw: unknown }> {
-  const res = await fetch(`${getBase()}/v1/channels/sendblue/verify`, {
+  const res = await apiFetch(`/v1/channels/sendblue/verify`, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ api_key_id: apiKeyId, api_secret_key: apiSecretKey }),
@@ -512,7 +557,7 @@ export async function sendblueRegisterWebhook(
  apiSecretKey: string,
  webhookUrl: string,
 ): Promise<{ registered: boolean; status: number }> {
-  const res = await fetch(`${getBase()}/v1/channels/sendblue/register-webhook`, {
+  const res = await apiFetch(`/v1/channels/sendblue/register-webhook`, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
@@ -534,7 +579,7 @@ export async function sendblueTest(
  fromNumber: string,
  toNumber: string,
 ): Promise<{ sent: boolean; status: number }> {
-  const res = await fetch(`${getBase()}/v1/channels/sendblue/test`, {
+  const res = await apiFetch(`/v1/channels/sendblue/test`, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
@@ -552,20 +597,20 @@ export async function sendblueTest(
 }

 export async function sendblueHealth(): Promise<{ channel_connected: boolean; bridge_wired: boolean; ready: boolean }> {
-  const res = await fetch(`${getBase()}/v1/channels/sendblue/health`);
+  const res = await apiFetch(`/v1/channels/sendblue/health`);
  if (!res.ok) return { channel_connected: false, bridge_wired: false, ready: false };
  return res.json();
 }

 export async function fetchTemplates(): Promise<AgentTemplate[]> {
-  const res = await fetch(`${getBase()}/v1/templates`);
+  const res = await apiFetch(`/v1/templates`);
  if (!res.ok) throw new Error(`Failed: ${res.status}`);
  const data = await res.json();
  return data.templates || [];
 }

 export async function runManagedAgent(agentId: string): Promise<void> {
-  const res = await fetch(`${getBase()}/v1/managed-agents/${agentId}/run`, { method: 'POST' });
+  const res = await apiFetch(`/v1/managed-agents/${agentId}/run`, { method: 'POST' });
  if (!res.ok) {
    const body = await res.json().catch(() => ({ detail: res.statusText }));
    throw new Error(body.detail || `Failed: ${res.status}`);
@@ -573,7 +618,7 @@ export async function runManagedAgent(agentId: string): Promise<void> {
 }

 export async function recoverManagedAgent(agentId: string): Promise<{ recovered: boolean; checkpoint: unknown }> {
-  const res = await fetch(`${getBase()}/v1/managed-agents/${agentId}/recover`, { method: 'POST' });
+  const res = await apiFetch(`/v1/managed-agents/${agentId}/recover`, { method: 'POST' });
  if (!res.ok) {
    const body = await res.json().catch(() => ({ detail: res.statusText }));
    throw new Error(body.detail || `Failed: ${res.status}`);
@@ -588,7 +633,7 @@ export async function fetchAgentState(agentId: string): Promise<{
  messages: AgentMessage[];
  checkpoint: unknown;
 }> {
-  const res = await fetch(`${getBase()}/v1/managed-agents/${agentId}/state`);
+  const res = await apiFetch(`/v1/managed-agents/${agentId}/state`);
  if (!res.ok) throw new Error(`Failed: ${res.status}`);
  return res.json();
 }
@@ -617,7 +662,7 @@ export async function sendAgentMessage(
    onDone?: (fullContent: string, usage?: Record<string, number>, telemetry?: Record<string, unknown>) => void;
  },
 ): Promise<AgentMessage> {
-  const res = await fetch(`${getBase()}/v1/managed-agents/${agentId}/messages`, {
+  const res = await apiFetch(`/v1/managed-agents/${agentId}/messages`, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ content, mode, stream: true }),
@@ -722,15 +767,34 @@ export async function sendAgentMessage(
  return res.json();
 }

+/**
+ * Ask the agent a question by triggering an ad-hoc run.
+ *
+ * Posts the question as an `immediate`, non-streamed message — the backend
+ * stores it and spawns a real agent tick (`execute_tick`) that consumes it as
+ * the run's input (tools, trace, and all), rather than a raw one-shot chat.
+ * Returns immediately with the stored user message; progress is observed via
+ * the `/v1/agents/events` WebSocket and the resulting trace.
+ */
+export async function askAgent(agentId: string, content: string): Promise<AgentMessage> {
+  const res = await apiFetch(`/v1/managed-agents/${agentId}/messages`, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({ content, mode: 'immediate', stream: false }),
+  });
+  if (!res.ok) throw new Error(`Failed: ${res.status}`);
+  return res.json();
+}
+
 export async function fetchAgentMessages(agentId: string): Promise<AgentMessage[]> {
-  const res = await fetch(`${getBase()}/v1/managed-agents/${agentId}/messages`);
+  const res = await apiFetch(`/v1/managed-agents/${agentId}/messages`);
  if (!res.ok) throw new Error(`Failed: ${res.status}`);
  const data = await res.json();
  return data.messages || [];
 }

 export async function fetchErrorAgents(): Promise<ManagedAgent[]> {
-  const res = await fetch(`${getBase()}/v1/agents/errors`);
+  const res = await apiFetch(`/v1/agents/errors`);
  if (!res.ok) throw new Error(`Failed: ${res.status}`);
  const data = await res.json();
  return data.agents || [];
@@ -770,7 +834,7 @@ export interface ToolInfo {
 }

 export async function fetchAvailableTools(): Promise<ToolInfo[]> {
-  const res = await fetch(`${getBase()}/v1/tools`);
+  const res = await apiFetch(`/v1/tools`);
  if (!res.ok) throw new Error(`Failed: ${res.status}`);
  const data = await res.json();
  return data.tools || [];
@@ -780,7 +844,7 @@ export async function saveToolCredentials(
  toolName: string,
  credentials: Record<string, string>,
 ): Promise<void> {
-  const res = await fetch(`${getBase()}/v1/tools/${toolName}/credentials`, {
+  const res = await apiFetch(`/v1/tools/${toolName}/credentials`, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify(credentials),
@@ -804,26 +868,26 @@ export interface AgentTraceDetail {
 }

 export async function fetchLearningLog(agentId: string): Promise<LearningLogEntry[]> {
-  const res = await fetch(`${getBase()}/v1/managed-agents/${agentId}/learning`);
+  const res = await apiFetch(`/v1/managed-agents/${agentId}/learning`);
  if (!res.ok) throw new Error(`Failed: ${res.status}`);
  const data = await res.json();
  return data.learning_log || [];
 }

 export async function triggerLearning(agentId: string): Promise<void> {
-  const res = await fetch(`${getBase()}/v1/managed-agents/${agentId}/learning/run`, { method: 'POST' });
+  const res = await apiFetch(`/v1/managed-agents/${agentId}/learning/run`, { method: 'POST' });
  if (!res.ok) throw new Error(`Failed: ${res.status}`);
 }

 export async function fetchAgentTraces(agentId: string, limit = 20): Promise<AgentTrace[]> {
-  const res = await fetch(`${getBase()}/v1/managed-agents/${agentId}/traces?limit=${limit}`);
+  const res = await apiFetch(`/v1/managed-agents/${agentId}/traces?limit=${limit}`);
  if (!res.ok) throw new Error(`Failed: ${res.status}`);
  const data = await res.json();
  return data.traces || [];
 }

 export async function fetchAgentTrace(agentId: string, traceId: string): Promise<AgentTraceDetail> {
-  const res = await fetch(`${getBase()}/v1/managed-agents/${agentId}/traces/${traceId}`);
+  const res = await apiFetch(`/v1/managed-agents/${agentId}/traces/${traceId}`);
  if (!res.ok) throw new Error(`Failed: ${res.status}`);
  return res.json();
 }
@@ -884,20 +948,39 @@ export interface MemoryStats {

 export interface MemoryConfig {
  backend: string;
+  // Set by the server when the native `openjarvis_rust` extension is missing,
+  // so the UI can show the real cause instead of a healthy-looking config.
+  available?: boolean;
+  detail?: string | null;
  context_from_memory: boolean;
  context_top_k: number;
  context_min_score: number;
  context_max_tokens: number;
 }

+/**
+ * Extract the server's `detail` message from a failed JSON response so the UI
+ * surfaces the real cause (e.g. "openjarvis_rust extension is not installed")
+ * instead of a blanket fallback string (#502).
+ */
+async function memoryErrorDetail(res: Response, fallback: string): Promise<string> {
+  try {
+    const data = await res.json();
+    if (data && typeof data.detail === 'string' && data.detail) return data.detail;
+  } catch {
+    // Non-JSON body — fall through to the generic message below.
+  }
+  return fallback;
+}
+
 export async function getMemoryStats(): Promise<MemoryStats> {
-  const res = await fetch(`${getBase()}/v1/memory/stats`);
+  const res = await apiFetch(`/v1/memory/stats`);
  if (!res.ok) throw new Error('Failed to fetch memory stats');
  return res.json();
 }

 export async function searchMemory(query: string, topK: number = 5): Promise<MemorySearchResult[]> {
-  const res = await fetch(`${getBase()}/v1/memory/search`, {
+  const res = await apiFetch(`/v1/memory/search`, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ query, top_k: topK }),
@@ -908,26 +991,26 @@ export async function searchMemory(query: string, topK: number = 5): Promise<Mem
 }

 export async function storeMemory(content: string, metadata?: Record<string, unknown>): Promise<void> {
-  const res = await fetch(`${getBase()}/v1/memory/store`, {
+  const res = await apiFetch(`/v1/memory/store`, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ content, metadata }),
  });
-  if (!res.ok) throw new Error('Failed to store memory');
+  if (!res.ok) throw new Error(await memoryErrorDetail(res, 'Failed to store memory'));
 }

-export async function indexMemoryPath(path: string): Promise<{ chunks_indexed: number }> {
-  const res = await fetch(`${getBase()}/v1/memory/index`, {
+export async function indexMemoryPath(path: string): Promise<{ chunks_indexed: number; note?: string }> {
+  const res = await apiFetch(`/v1/memory/index`, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ path }),
  });
-  if (!res.ok) throw new Error('Failed to index path');
+  if (!res.ok) throw new Error(await memoryErrorDetail(res, 'Failed to index path'));
  return res.json();
 }

 export async function getMemoryConfig(): Promise<MemoryConfig> {
-  const res = await fetch(`${getBase()}/v1/memory/config`);
+  const res = await apiFetch(`/v1/memory/config`);
  if (!res.ok) throw new Error('Failed to fetch memory config');
  return res.json();
 }
@@ -949,18 +1032,61 @@ export interface PendingApproval {
 }

 export async function fetchPendingApprovals(): Promise<PendingApproval[]> {
-  const res = await fetch(`${getBase()}/v1/approvals/pending`);
+  const res = await apiFetch(`/v1/approvals/pending`);
  if (!res.ok) throw new Error(`Failed: ${res.status}`);
  const data = await res.json();
  return data.actions || [];
 }

 export async function approveAction(actionId: string): Promise<void> {
-  const res = await fetch(`${getBase()}/v1/approvals/${actionId}/approve`, { method: 'POST' });
+  const res = await apiFetch(`/v1/approvals/${actionId}/approve`, { method: 'POST' });
  if (!res.ok) throw new Error(`Failed: ${res.status}`);
 }

 export async function denyAction(actionId: string): Promise<void> {
-  const res = await fetch(`${getBase()}/v1/approvals/${actionId}/deny`, { method: 'POST' });
+  const res = await apiFetch(`/v1/approvals/${actionId}/deny`, { method: 'POST' });
  if (!res.ok) throw new Error(`Failed: ${res.status}`);
 }
+
+// ---------------------------------------------------------------------------
+// Inference source (desktop only)
+// ---------------------------------------------------------------------------
+
+export type InferenceSource = {
+  kind: 'ollama' | 'custom';
+  model?: string;
+  host?: string;
+  engine?: string;
+};
+
+export async function getInferenceSource(): Promise<InferenceSource> {
+  if (isTauri()) {
+    try {
+      const { invoke } = await import('@tauri-apps/api/core');
+      return await invoke<InferenceSource>('get_inference_source');
+    } catch (e: any) {
+      throw new Error(e?.message ?? e ?? 'Failed to read inference source');
+    }
+  }
+  return { kind: 'ollama' };
+}
+
+export async function setInferenceSource(
+  src: InferenceSource & { apiKey?: string },
+): Promise<void> {
+  if (!isTauri()) throw new Error('Inference source is configurable in the desktop app only.');
+  try {
+    const { invoke } = await import('@tauri-apps/api/core');
+    await invoke<void>('set_inference_source', {
+      kind: src.kind,
+      model: src.model ?? null,
+      host: src.host ?? null,
+      engine: src.engine ?? null,
+      apiKey: src.apiKey ?? null,
+    });
+  } catch (e: any) {
+    // Surface the backend's actionable error strings (e.g. "A server URL is
+    // required…", "Could not store the API key…") as proper Error instances.
+    throw new Error(e?.message ?? e ?? 'Failed to save inference source');
+  }
+}
@@ -70,6 +70,10 @@ export type ThemeMode = 'light' | 'dark' | 'system';
 interface Settings {
  theme: ThemeMode;
  apiUrl: string;
+  // Local server API key (OPENJARVIS_API_KEY). Sent as a Bearer token on
+  // /v1 + /api requests so a key-protected `jarvis serve` doesn't 401 the
+  // frontend (#266). Empty = no auth header (keyless local default).
+  apiKey: string;
  fontSize: 'small' | 'default' | 'large';
  defaultModel: string;
  defaultAgent: string;
@@ -82,6 +86,7 @@ function loadSettings(): Settings {
  const defaults: Settings = {
    theme: 'system',
    apiUrl: '',
+    apiKey: '',
    fontSize: 'default',
    defaultModel: '',
    defaultAgent: '',
@@ -438,7 +443,12 @@ export const useAppStore = create<AppState>((set, get) => {

    // ── Models & server ────────────────────────────────────────────

-    setModels: (models: ModelInfo[]) => set({ models }),
+    setModels: (models: ModelInfo[]) =>
+      set((state) =>
+        !state.selectedModel && models.length > 0
+          ? { models, selectedModel: models[0].id }
+          : { models },
+      ),
    setModelsLoading: (loading: boolean) => set({ modelsLoading: loading }),
    setSelectedModel: (model: string) => set({ selectedModel: model }),
    setServerInfo: (info: ServerInfo | null) => set({ serverInfo: info }),
@@ -9,7 +9,6 @@ import {
  fetchAgentChannels,
  bindAgentChannel,
  unbindAgentChannel,
-  fetchAgentMessages,
  fetchTemplates,
  createManagedAgent,
  pauseManagedAgent,
@@ -17,10 +16,11 @@ import {
  deleteManagedAgent,
  runManagedAgent,
  recoverManagedAgent,
-  sendAgentMessage,
+  askAgent,
  fetchLearningLog,
  triggerLearning,
  fetchAgentTraces,
+  fetchAgentTrace,
  fetchManagedAgent,
  fetchAvailableTools,
  saveToolCredentials,
@@ -32,8 +32,9 @@ import {
  sendblueTest,
  sendblueHealth,
 } from '../lib/api';
-import type { AgentTask, ChannelBinding, AgentTemplate, AgentMessage, ManagedAgent, LearningLogEntry, AgentTrace, ToolInfo } from '../lib/api';
+import type { AgentTask, ChannelBinding, AgentTemplate, ManagedAgent, LearningLogEntry, AgentTrace, AgentTraceDetail, ToolInfo } from '../lib/api';
 import { useAgentEvents } from '../lib/useAgentEvents';
+import type { AgentEvent } from '../lib/useAgentEvents';
 import {
  Plus,
  Bot,
@@ -60,6 +61,7 @@ import {
  Copy,
  Check,
  Pencil,
+  Loader2,
 } from 'lucide-react';
 import { SOURCE_CATALOG } from '../types/connectors';
 import type { ConnectRequest } from '../types/connectors';
@@ -1403,20 +1405,20 @@ function AgentConfigGrid({ agent, onAgentUpdated }: { agent: ManagedAgent; onAge
    let cancelled = false;
    async function checkModel() {
      try {
-        const res = await fetch('http://localhost:11434/api/tags');
-        if (!res.ok) { setModelAvailable('unknown'); return; }
-        const data = await res.json();
-        const loadedNames: string[] = (data.models || []).map((m: { name: string }) => m.name);
-        if (!cancelled) {
-          setOllamaModels(loadedNames);
-          if (currentModel === '(default)') {
-            setModelAvailable(loadedNames.length > 0 ? 'available' : 'unknown');
-          } else {
-            const isLoaded = loadedNames.some(
-              (n) => n === currentModel || n.startsWith(currentModel + ':') || currentModel.startsWith(n.split(':')[0])
-            );
-            setModelAvailable(isLoaded ? 'available' : 'unavailable');
-          }
+        // Ask the backend which models are installed rather than hitting
+        // Ollama directly from the browser: the backend always knows where
+        // Ollama lives (incl. remote) and there's no cross-origin/CORS issue,
+        // which is what made the check spuriously report "Not available".
+        const installed = (await fetchModels()).map((m) => m.id);
+        if (cancelled) return;
+        setOllamaModels(installed);
+        if (currentModel === '(default)') {
+          setModelAvailable(installed.length > 0 ? 'available' : 'unknown');
+        } else {
+          const isInstalled = installed.some(
+            (n) => n === currentModel || n.startsWith(currentModel + ':') || currentModel.startsWith(n.split(':')[0])
+          );
+          setModelAvailable(isInstalled ? 'available' : 'unavailable');
        }
      } catch {
        if (!cancelled) setModelAvailable('unknown');
@@ -1428,21 +1430,15 @@ function AgentConfigGrid({ agent, onAgentUpdated }: { agent: ManagedAgent; onAge

  async function startEditingModel() {
    try {
-      const fetched = await fetchModels();
-      setModels(fetched.map((m) => m.id));
-    } catch { /* ignore */ }
-    // Also refresh Ollama models for availability indication
-    try {
-      const res = await fetch('http://localhost:11434/api/tags');
-      if (res.ok) {
-        const data = await res.json();
-        setOllamaModels((data.models || []).map((m: { name: string }) => m.name));
-      }
+      const fetched = (await fetchModels()).map((m) => m.id);
+      setModels(fetched);
+      // Same backend list drives both the dropdown and the availability dots.
+      setOllamaModels(fetched);
    } catch { /* ignore */ }
    setEditingModel(true);
  }

-  function isModelLoaded(modelId: string): boolean {
+  function isModelInstalled(modelId: string): boolean {
    return ollamaModels.some(
      (n) => n === modelId || n.startsWith(modelId + ':') || modelId.startsWith(n.split(':')[0])
    );
@@ -1480,10 +1476,10 @@ function AgentConfigGrid({ agent, onAgentUpdated }: { agent: ManagedAgent; onAge
          style={{ background: 'var(--color-bg)', border: '1px solid var(--color-border)', color: 'var(--color-text)' }}
        >
          {models.map((m) => {
-            const loaded = isModelLoaded(m);
+            const installed = isModelInstalled(m);
            return (
-              <option key={m} value={m} style={!loaded ? { color: 'var(--color-text-tertiary)' } : undefined}>
-                {m}{!loaded ? ' (not loaded)' : ''}
+              <option key={m} value={m} style={!installed ? { color: 'var(--color-text-tertiary)' } : undefined}>
+                {m}{!installed ? ' (not installed)' : ''}
              </option>
            );
          })}
@@ -1546,498 +1542,421 @@ function AgentConfigGrid({ agent, onAgentUpdated }: { agent: ManagedAgent; onAge
 // Detail view — Interact tab
 // ---------------------------------------------------------------------------

-/** AgentMessage extended with optional response metadata for the footer. */
-type InteractMessage = AgentMessage & {
-  _elapsed?: string;
-  _toolCalls?: number;
-  _usage?: Record<string, number>;
-  _telemetry?: Record<string, unknown>;
-  _toolCallDetails?: ToolCallInfo[];
-};
+/** One entry in the live activity feed assembled from agent events. */
+type LiveItem =
+  | { kind: 'note'; id: string; label: string }
+  | { kind: 'tool'; id: string; tool: ToolCallInfo };

-function AgentResponseFooter({
-  msg, copiedId, onCopy,
-}: {
-  msg: InteractMessage;
-  copiedId: string | null;
-  onCopy: (id: string) => void;
-}) {
-  const [expanded, setExpanded] = useState(false);
-  const u = msg._usage;
-  const t = msg._telemetry as Record<string, unknown> | undefined;
-  const elapsed = msg._elapsed;
-  const toolCallDetails = msg._toolCallDetails || [];
-  const toolCalls = msg._toolCalls ?? toolCallDetails.length;
-
-  // Build summary line like Chat: "ollama - qwen3.5:9b - 18.3s - 50 tokens"
-  const parts: string[] = [];
-  if (t?.engine) parts.push(String(t.engine));
-  if (t?.model_id) parts.push(String(t.model_id));
-  if (elapsed) parts.push(`${elapsed}s`);
-  if (u?.prompt_tokens) parts.push(`${u.prompt_tokens} input tokens`);
-  if (u?.completion_tokens) parts.push(`${u.completion_tokens} output tokens`);
-  if (toolCalls > 0) parts.push(`${toolCalls} tool ${toolCalls === 1 ? 'call' : 'calls'}`);
-
-  const summary = parts.length > 0 ? parts.join(' - ') : elapsed ? `${elapsed}s` : '';
-
-  // Build expanded rows
-  const rows: Array<{ label: string; value: string }> = [];
-  if (t?.engine) rows.push({ label: 'Engine', value: `${t.engine}${t.model_id ? ` (${t.model_id})` : ''}` });
-  if (u) {
-    const tokenParts = [];
-    if (u.completion_tokens) tokenParts.push(`${u.completion_tokens} generated`);
-    if (u.prompt_tokens) tokenParts.push(`${u.prompt_tokens} prompt`);
-    if (tokenParts.length) rows.push({ label: 'Tokens', value: tokenParts.join(' · ') });
-  }
-  if (toolCallDetails.length > 0) {
-    toolCallDetails.forEach((tc, i) => {
-      const prefix = toolCallDetails.length > 1 ? `Tool ${i + 1}` : 'Tool';
-      const args = tc.arguments ? ` ${tc.arguments}` : '';
-      rows.push({ label: prefix, value: `${tc.tool}(${args.trim()})` });
-    });
-  } else if (toolCalls > 0) {
-    rows.push({ label: 'Tool calls', value: `${toolCalls}` });
-  }
-  if (t?.tokens_per_sec) rows.push({ label: 'Speed', value: `${Math.round(Number(t.tokens_per_sec))} tok/s` });
-  if (t?.total_ms) rows.push({ label: 'Latency', value: `${(Number(t.total_ms) / 1000).toFixed(1)}s total` });
-
-  if (!summary) return null;
-
-  return (
-    <div style={{ borderTop: '1px solid var(--color-border-subtle)', marginTop: 6 }}>
-      <div style={{ display: 'flex', alignItems: 'center', paddingTop: 4 }}>
-        <button
-          onClick={() => rows.length > 0 && setExpanded(!expanded)}
-          style={{
-            flex: 1, display: 'flex', alignItems: 'center', gap: 6,
-            background: 'none', border: 'none', cursor: rows.length > 0 ? 'pointer' : 'default',
-            padding: 0, textAlign: 'left',
-          }}
-        >
-          <span style={{ width: 4, height: 4, borderRadius: '50%', background: 'var(--color-accent)', flexShrink: 0 }} />
-          <span style={{ fontSize: 11, color: 'var(--color-text-tertiary)', fontFamily: 'system-ui' }}>
-            {summary}
-          </span>
-          {rows.length > 0 && (
-            <span style={{ fontSize: 10, color: 'var(--color-text-tertiary)' }}>
-              {expanded ? '▲' : '▼'}
-            </span>
-          )}
-        </button>
-        <button
-          onClick={() => onCopy(msg.id)}
-          style={{
-            background: 'none', border: 'none', cursor: 'pointer',
-            color: 'var(--color-text-tertiary)', padding: 2,
-            display: 'flex', alignItems: 'center',
-          }}
-          title="Copy response"
-        >
-          {copiedId === msg.id ? <Check size={12} /> : <Copy size={12} />}
-        </button>
-      </div>
-      {expanded && rows.length > 0 && (
-        <div style={{
-          borderRadius: 6, marginTop: 4, padding: '6px 10px',
-          background: 'rgba(0, 0, 0, 0.15)',
-        }}>
-          <div style={{
-            display: 'grid', gridTemplateColumns: 'auto 1fr',
-            columnGap: 12, rowGap: 2,
-          }}>
-            {rows.map((row) => (
-              <div key={row.label} style={{ display: 'contents' }}>
-                <span style={{ fontSize: 11, color: 'var(--color-text-tertiary)', fontFamily: 'monospace' }}>
-                  {row.label}
-                </span>
-                <span style={{ fontSize: 11, color: 'var(--color-text-secondary)', fontFamily: 'monospace' }}>
-                  {row.value}
-                </span>
-              </div>
-            ))}
-          </div>
-        </div>
-      )}
-    </div>
-  );
+/** Convert a persisted trace step into a ToolCallInfo for ToolCallCard. */
+function stepToToolCall(
+  step: AgentTraceDetail['steps'][number],
+  idx: number,
+): ToolCallInfo {
+  const input = (step.input ?? {}) as { tool?: string; args?: unknown };
+  const out = step.output as unknown;
+  const result =
+    typeof out === 'string'
+      ? out
+      : out && typeof out === 'object' && 'result' in out
+        ? String((out as { result: unknown }).result ?? '')
+        : out != null
+          ? JSON.stringify(out)
+          : '';
+  const args = input.args;
+  return {
+    id: `step-${idx}`,
+    tool: input.tool || step.step_type || 'step',
+    arguments:
+      typeof args === 'string' ? args : args != null ? JSON.stringify(args) : '',
+    status: 'success',
+    result,
+    latency: step.duration ? step.duration * 1000 : undefined,
+  };
 }

-function InteractTab({ agentId, agentStatus }: { agentId: string; agentStatus: string }) {
-  const [messages, setMessages] = useState<InteractMessage[]>([]);
+// ---------------------------------------------------------------------------
+// Interact tab — trace viewer (top) + follow-up chat (bottom).
+//
+// The chat input doesn't open a side-channel chat; it triggers a real ad-hoc
+// agent run (execute_tick) with the user's question as input. The trace area
+// shows that run live (tick + tool calls over the events WebSocket) and, when
+// idle, the last run's trace steps plus the agent's resulting findings — so
+// users can interrogate the agent about its work ("tell me more about X").
+// ---------------------------------------------------------------------------
+function InteractTab({ agentId, agentStatus, onRunStateChange }: { agentId: string; agentStatus: string; onRunStateChange?: () => void }) {
+  const [agent, setAgent] = useState<ManagedAgent | null>(null);
+  const [activity, setActivity] = useState('');
+  const [running, setRunning] = useState(agentStatus === 'running');
+  const [liveItems, setLiveItems] = useState<LiveItem[]>([]);
+  const [lastTrace, setLastTrace] = useState<AgentTraceDetail | null>(null);
  const [input, setInput] = useState('');
  const [sending, setSending] = useState(false);
-  const [waitingForResponse, setWaitingForResponse] = useState(false);
-  const [progressLabel, setProgressLabel] = useState('');
-  const [streamingContent, setStreamingContent] = useState('');
-  const [streamingToolCalls, setStreamingToolCalls] = useState<ToolCallInfo[]>([]);
-  const [currentActivity, setCurrentActivity] = useState('');
-  const [liveStatus, setLiveStatus] = useState(agentStatus);
-  const [streamElapsedMs, setStreamElapsedMs] = useState(0);
-  const [copiedId, setCopiedId] = useState<string | null>(null);
-  const bottomRef = useRef<HTMLDivElement>(null);
-  const scrollContainerRef = useRef<HTMLDivElement>(null);
+  const [errorMsg, setErrorMsg] = useState('');
+  const [question, setQuestion] = useState(''); // question driving the current/last run
+  const [elapsedMs, setElapsedMs] = useState(0);
+
+  const startRef = useRef(0);
  const timerRef = useRef<ReturnType<typeof setInterval> | null>(null);
-  // Tail-mode flag: when the user is pinned to the bottom of the transcript
-  // (within NEAR_BOTTOM_THRESHOLD px) we keep auto-scrolling as new content
-  // streams in. If they manually scroll up, we stop following so the view
-  // doesn't get yanked back down.
-  const isNearBottomRef = useRef(true);
+  const runningRef = useRef(running);
+  runningRef.current = running;
+  const bottomRef = useRef<HTMLDivElement>(null);

-  // Keep a ref of local metadata so polling doesn't overwrite it
-  const localMetaRef = useRef<Map<string, {
-    _elapsed?: string;
-    _toolCalls?: number;
-    _usage?: Record<string, number>;
-    _telemetry?: Record<string, unknown>;
-    _toolCallDetails?: ToolCallInfo[];
-  }>>(new Map());
+  const clearTimer = useCallback(() => {
+    if (timerRef.current) {
+      clearInterval(timerRef.current);
+      timerRef.current = null;
+    }
+  }, []);

-  const loadData = useCallback(async () => {
+  // Load idle snapshot: agent record (status + findings) and the latest trace.
+  const loadIdle = useCallback(async () => {
    try {
-      const [msgs, agent] = await Promise.all([
-        fetchAgentMessages(agentId),
-        fetchManagedAgent(agentId),
-      ]);
-      // Merge server messages with locally-stored metadata, and hydrate
-      // server-persisted tool_calls into _toolCallDetails so they survive
-      // page reloads.
-      const merged: InteractMessage[] = msgs.map((m) => {
-        const meta = localMetaRef.current.get(m.content?.slice(0, 100) || '');
-        const base = meta ? { ...m, ...meta } : { ...m };
-        if (!base._toolCallDetails && m.tool_calls && m.tool_calls.length > 0) {
-          base._toolCallDetails = m.tool_calls.map((tc, i) => ({
-            id: `${m.id}-tc-${i}`,
-            tool: tc.tool,
-            arguments: tc.arguments || '',
-            status: tc.success === false ? 'error' : 'success',
-            result: tc.result,
-            latency: tc.latency,
-          }));
-          if (base._toolCalls == null) base._toolCalls = m.tool_calls.length;
+      const a = await fetchManagedAgent(agentId);
+      setAgent(a);
+      setActivity(a.current_activity || '');
+      try {
+        const traces = await fetchAgentTraces(agentId, 1);
+        if (traces.length > 0) {
+          const detail = await fetchAgentTrace(agentId, traces[0].id);
+          setLastTrace(detail);
        }
-        return base;
-      });
-      setMessages(merged);
-      setLiveStatus(agent.status);
-      setCurrentActivity(agent.current_activity || '');
+      } catch {
+        /* trace store may be empty */
+      }
    } catch {
-      // ignore
+      /* ignore */
    }
  }, [agentId]);

  useEffect(() => {
-    loadData();
-    // Fallback slow poll — WS is primary, this catches missed events / dropped sockets
-    const interval = setInterval(loadData, 30000);
-    return () => clearInterval(interval);
-  }, [loadData]);
+    loadIdle();
+  }, [loadIdle]);

-  // Event-driven refresh — fires when the server reports agent activity
-  useAgentEvents(agentId, loadData, [
-    'agent_tick_start',
-    'agent_tick_end',
-    'agent_tick_error',
-    'agent_message_received',
-    'tool_call_end',
-    'inference_end',
-  ]);
-
-  useEffect(() => { setLiveStatus(agentStatus); }, [agentStatus]);
-
-  // Clean up elapsed-time timer on unmount
+  // Tick the elapsed timer while running.
  useEffect(() => {
-    return () => {
-      if (timerRef.current) {
-        clearInterval(timerRef.current);
-        timerRef.current = null;
-      }
-    };
-  }, []);
-
-  // Track whether the user is near the bottom. Called on every scroll
-  // event; only flips the ref, never triggers a re-render.
-  const handleScroll = useCallback(() => {
-    const el = scrollContainerRef.current;
-    if (!el) return;
-    const distance = el.scrollHeight - el.scrollTop - el.clientHeight;
-    isNearBottomRef.current = distance < 80; // px threshold
-  }, []);
-
-  // Initial landing: jump to the bottom once the first batch of messages
-  // arrives. Subsequent poll updates honor the tail-mode ref.
-  const hasScrolled = useRef(false);
-  useEffect(() => {
-    if (!hasScrolled.current && messages.length > 0) {
-      bottomRef.current?.scrollIntoView({ behavior: 'auto' });
-      hasScrolled.current = true;
-      isNearBottomRef.current = true;
+    if (!running) {
+      clearTimer();
+      return;
    }
-  }, [messages]);
+    if (!startRef.current) startRef.current = Date.now();
+    timerRef.current = setInterval(
+      () => setElapsedMs(Date.now() - startRef.current),
+      100,
+    );
+    return clearTimer;
+  }, [running, clearTimer]);

-  // Stream auto-follow: only scroll while the user is pinned to the bottom.
-  // If they've scrolled up to re-read something, stay put.
-  useEffect(() => {
-    if (streamingContent && isNearBottomRef.current) {
-      bottomRef.current?.scrollIntoView({ behavior: 'smooth' });
-    }
-  }, [streamingContent]);
+  const finishRun = useCallback(() => {
+    setRunning(false);
+    startRef.current = 0;
+    clearTimer();
+    // Give the backend a beat to persist summary_memory + trace, then refresh
+    // both this tab and the parent (so the detail/list status badge flips back
+    // from "running" to "idle" without waiting for the slow background poll).
+    setTimeout(() => {
+      loadIdle();
+      onRunStateChange?.();
+    }, 500);
+  }, [clearTimer, loadIdle, onRunStateChange]);

-  async function handleSend(mode: 'immediate' | 'queued') {
-    if (!input.trim()) return;
-    const text = input.trim();
-    setInput('');
-    setSending(true);
-
-    // Show user message immediately as a local bubble
-    const localMsg: AgentMessage = {
-      id: `local-${Date.now()}`,
-      agent_id: agentId,
-      direction: 'user_to_agent',
-      content: text,
-      mode,
-      status: 'delivered',
-      created_at: Date.now() / 1000,
-    };
-    setMessages((prev) => [localMsg, ...prev]);
-    setSending(false);
-    setWaitingForResponse(true);
-    setProgressLabel('Initializing agent...');
-    setStreamingContent('');
-    setStreamingToolCalls([]);
-    // Sending is explicit user intent — always scroll and re-engage
-    // tail-mode so the subsequent stream follows along.
-    isNearBottomRef.current = true;
-    requestAnimationFrame(() => {
-      bottomRef.current?.scrollIntoView({ behavior: 'smooth' });
-    });
-
-    // Start elapsed-time timer
-    const startTime = Date.now();
-    setStreamElapsedMs(0);
-    timerRef.current = setInterval(() => {
-      setStreamElapsedMs(Date.now() - startTime);
-    }, 100);
-
-    let toolCount = 0;
-    let responseUsage: Record<string, number> | undefined;
-    let responseTelemetry: Record<string, unknown> | undefined;
-    const collectedToolCalls: ToolCallInfo[] = [];
-    try {
-      const response = await sendAgentMessage(agentId, text, mode, {
-        onProgress: (label) => {
-          setProgressLabel(label);
-          toolCount++;
-        },
-        onContentDelta: (_delta, full) => setStreamingContent(full),
-        onToolCallStart: ({ tool, arguments: args }) => {
-          toolCount++;
+  // Live trace: assemble events from the agent events WebSocket.
+  const onEvent = useCallback(
+    (ev: AgentEvent) => {
+      const data = ev.data || {};
+      switch (ev.type) {
+        case 'agent_tick_start': {
+          startRef.current = Date.now();
+          setElapsedMs(0);
+          setRunning(true);
+          setErrorMsg('');
+          setLiveItems([{ kind: 'note', id: `start-${ev.timestamp}`, label: 'Run started' }]);
+          break;
+        }
+        case 'tool_call_start': {
+          const id = `tc-${ev.timestamp}-${Math.random().toString(36).slice(2, 6)}`;
+          const args = data.arguments;
          const tc: ToolCallInfo = {
-            id: `tc-${Date.now()}-${collectedToolCalls.length}`,
-            tool,
-            arguments: args,
+            id,
+            tool: String(data.tool || 'tool'),
+            arguments:
+              typeof args === 'string' ? args : args != null ? JSON.stringify(args) : '',
            status: 'running',
          };
-          collectedToolCalls.push(tc);
-          setStreamingToolCalls([...collectedToolCalls]);
-          setProgressLabel(`Calling ${tool}...`);
-        },
-        onToolCallEnd: ({ tool, success, latency, result }) => {
-          const match = [...collectedToolCalls]
-            .reverse()
-            .find((t) => t.tool === tool && t.status === 'running');
-          if (match) {
-            match.status = success ? 'success' : 'error';
-            match.latency = latency;
-            match.result = result;
+          setLiveItems((prev) => [...prev, { kind: 'tool', id, tool: tc }]);
+          break;
+        }
+        case 'tool_call_end': {
+          setLiveItems((prev) => {
+            const next = [...prev];
+            for (let i = next.length - 1; i >= 0; i--) {
+              const it = next[i];
+              if (
+                it.kind === 'tool' &&
+                it.tool.tool === String(data.tool) &&
+                it.tool.status === 'running'
+              ) {
+                next[i] = {
+                  ...it,
+                  tool: {
+                    ...it.tool,
+                    status: data.success === false ? 'error' : 'success',
+                    result:
+                      typeof data.result === 'string' ? data.result : it.tool.result,
+                    latency:
+                      typeof data.latency === 'number'
+                        ? data.latency * 1000
+                        : it.tool.latency,
+                  },
+                };
+                break;
+              }
+            }
+            return next;
+          });
+          break;
+        }
+        case 'agent_tick_end':
+        case 'agent_tick_error': {
+          if (ev.type === 'agent_tick_error') {
+            setErrorMsg(String(data.error || 'The run failed.'));
          }
-          setStreamingToolCalls([...collectedToolCalls]);
-          setProgressLabel('');
-        },
-        onDone: (_content, usage, telemetry) => {
-          setStreamingContent('');
-          responseUsage = usage;
-          responseTelemetry = telemetry;
-        },
-      });
-      const elapsed = ((Date.now() - startTime) / 1000).toFixed(1);
-      // Add the agent's response as a local bubble immediately
-      if (response && response.content) {
-        const meta = {
-          _elapsed: elapsed,
-          _toolCalls: toolCount,
-          _usage: responseUsage,
-          _telemetry: responseTelemetry,
-          _toolCallDetails: collectedToolCalls.length > 0 ? [...collectedToolCalls] : undefined,
-        };
-        // Store metadata keyed by content prefix so polling preserves it
-        localMetaRef.current.set(response.content.slice(0, 100), meta);
-        setMessages((prev) => [
-          {
-            ...response,
-            id: response.id || `response-${Date.now()}`,
-            direction: 'agent_to_user' as const,
-            ...meta,
-          },
-          ...prev,
-        ]);
+          finishRun();
+          break;
+        }
      }
-      // Also refresh from server to sync any persisted messages
-      await loadData();
+    },
+    [finishRun],
+  );
+
+  useAgentEvents(agentId, onEvent, [
+    'agent_tick_start',
+    'tool_call_start',
+    'tool_call_end',
+    'agent_tick_end',
+    'agent_tick_error',
+  ]);
+
+  // Fallback poll — WS is primary, but this catches missed tick_end events and
+  // runs started elsewhere (e.g. the scheduler or the Overview "Run" button).
+  useEffect(() => {
+    const iv = setInterval(async () => {
+      try {
+        const a = await fetchManagedAgent(agentId);
+        setActivity(a.current_activity || '');
+        if (a.status === 'running' && !runningRef.current) {
+          setRunning(true);
+        } else if (a.status !== 'running' && runningRef.current) {
+          finishRun();
+        }
+      } catch {
+        /* ignore */
+      }
+    }, 3000);
+    return () => clearInterval(iv);
+  }, [agentId, finishRun]);
+
+  // Keep pinned to the newest live item.
+  useEffect(() => {
+    if (running) bottomRef.current?.scrollIntoView({ behavior: 'smooth' });
+  }, [liveItems, running]);
+
+  async function handleAsk() {
+    const q = input.trim();
+    if (!q || running || sending) return;
+    setInput('');
+    setQuestion(q);
+    setErrorMsg('');
+    setSending(true);
+    setLiveItems([{ kind: 'note', id: 'queued', label: 'Starting run…' }]);
+    startRef.current = Date.now();
+    setElapsedMs(0);
+    try {
+      // immediate, non-streamed → triggers a real agent run that consumes the
+      // question as input. tick_start over the WS confirms; poll is the backstop.
+      await askAgent(agentId, q);
+      setRunning(true);
+      onRunStateChange?.(); // flip the parent status badge to "running" now
    } catch {
-      // ignore
+      setErrorMsg('Could not start the agent run.');
+      setLiveItems([]);
    } finally {
-      setWaitingForResponse(false);
-      setStreamingContent('');
-      setStreamingToolCalls([]);
-      setProgressLabel('');
-      if (timerRef.current) {
-        clearInterval(timerRef.current);
-        timerRef.current = null;
-      }
-      setStreamElapsedMs(0);
+      setSending(false);
    }
  }

-  // Reverse so newest messages appear at the bottom (closest to input).
-  // Filter out agent responses with empty content.
-  const displayMessages = [...messages]
-    .filter((m) => m.direction === 'user_to_agent' || m.content.trim())
-    .reverse();
+  const isBusy = running || sending;
+  const findings = agent?.summary_memory?.trim() || '';
+  const traceSteps = lastTrace?.steps ?? [];

  return (
-    <div className="flex flex-col" style={{ minHeight: 320 }}>
+    <div className="flex flex-col" style={{ minHeight: 360 }}>
+      {/* ── Trace area header ──────────────────────────────── */}
+      <div className="flex items-center justify-between mb-2">
+        <div
+          className="flex items-center gap-2 text-sm font-medium"
+          style={{ color: 'var(--color-text)' }}
+        >
+          <Activity size={14} style={{ color: 'var(--color-accent)' }} />
+          Activity trace
+        </div>
+        <div
+          className="flex items-center gap-2 text-xs"
+          style={{ color: 'var(--color-text-tertiary)' }}
+        >
+          {isBusy ? (
+            <>
+              <span
+                className="inline-block w-2 h-2 rounded-full animate-pulse"
+                style={{ background: 'var(--color-accent)' }}
+              />
+              Running{elapsedMs > 0 ? ` · ${(elapsedMs / 1000).toFixed(1)}s` : ''}
+            </>
+          ) : (
+            <>
+              {agent?.last_run_at
+                ? `Last run ${new Date(agent.last_run_at * 1000).toLocaleString()}`
+                : 'Idle'}
+              {lastTrace && ` · ${lastTrace.outcome}`}
+            </>
+          )}
+        </div>
+      </div>
+
+      {/* ── Trace area body ────────────────────────────────── */}
      <div
-        ref={scrollContainerRef}
-        onScroll={handleScroll}
-        className="flex-1 overflow-y-auto space-y-3 pb-4"
-        style={{ maxHeight: 'calc(100vh - 400px)' }}
+        className="flex-1 overflow-y-auto rounded-lg p-3 space-y-3"
+        style={{
+          background: 'var(--color-bg-secondary)',
+          border: '1px solid var(--color-border)',
+          maxHeight: 'calc(100vh - 360px)',
+          minHeight: 200,
+        }}
      >
-        {displayMessages.length === 0 && !waitingForResponse && (
-          <div className="text-sm text-center py-8" style={{ color: 'var(--color-text-tertiary)' }}>
-            No messages yet. Send a message to interact with this agent.
+        {question && (
+          <div className="text-xs" style={{ color: 'var(--color-text-tertiary)' }}>
+            <span style={{ color: 'var(--color-text-secondary)' }}>Question:</span> {question}
          </div>
        )}
-        {displayMessages.map((msg) => (
-          <div key={msg.id} className="space-y-2">
-            {/* Tool calls rendered as their own full-width entries (like Claude Code) */}
-            {msg.direction === 'agent_to_user' && msg._toolCallDetails && msg._toolCallDetails.length > 0 && (
-              <div className="flex flex-col items-start gap-2 max-w-[75%]">
-                {msg._toolCallDetails.map((tc) => (
-                  <ToolCallCard key={tc.id} toolCall={tc} />
+
+        {errorMsg && (
+          <div
+            className="text-sm px-3 py-2 rounded-lg"
+            style={{
+              background: 'rgba(255,80,80,0.08)',
+              border: '1px solid var(--color-error)',
+              color: 'var(--color-error)',
+            }}
+          >
+            {errorMsg}
+          </div>
+        )}
+
+        {isBusy ? (
+          /* LIVE view — current tick */
+          <>
+            {liveItems.map((it) =>
+              it.kind === 'tool' ? (
+                <ToolCallCard key={it.id} toolCall={it.tool} />
+              ) : (
+                <div
+                  key={it.id}
+                  className="flex items-center gap-2 text-sm"
+                  style={{ color: 'var(--color-text-secondary)' }}
+                >
+                  <span
+                    className="inline-block w-2 h-2 rounded-full animate-pulse"
+                    style={{ background: 'var(--color-accent)' }}
+                  />
+                  {it.label}
+                </div>
+              ),
+            )}
+            <div
+              className="flex items-center gap-2 text-sm"
+              style={{ color: 'var(--color-text-secondary)' }}
+            >
+              <Loader2 size={13} className="animate-spin" style={{ color: 'var(--color-accent)' }} />
+              {activity || 'Agent is working…'}
+            </div>
+          </>
+        ) : (
+          /* IDLE view — last run's trace + findings */
+          <>
+            {traceSteps.length > 0 && (
+              <div className="space-y-2">
+                {traceSteps.map((s, i) => (
+                  <ToolCallCard key={i} toolCall={stepToToolCall(s, i)} />
                ))}
              </div>
            )}
-            {/* Message bubble */}
-            <div className={`flex ${msg.direction === 'user_to_agent' ? 'justify-end' : 'justify-start'}`}>
+            {findings ? (
              <div
-                className="max-w-[75%] px-3 py-2 rounded-lg text-sm"
+                className="px-3 py-2 rounded-lg text-sm"
                style={{
-                  background: msg.direction === 'user_to_agent' ? 'var(--color-accent)' : 'var(--color-bg-secondary)',
-                  color: msg.direction === 'user_to_agent' ? 'var(--color-on-accent)' : 'var(--color-text)',
-                  border: msg.direction === 'agent_to_user' ? '1px solid var(--color-border)' : 'none',
+                  background: 'var(--color-bg)',
+                  border: '1px solid var(--color-border)',
+                  color: 'var(--color-text)',
                }}
              >
-                {msg.direction === 'agent_to_user' ? (
-                  <div className="prose prose-sm prose-invert max-w-none"><ReactMarkdown remarkPlugins={[remarkGfm]}>{msg.content}</ReactMarkdown></div>
-                ) : (
-                  <p>{msg.content}</p>
-                )}
-                <p className="text-xs mt-1 opacity-70">
-                  {msg.status === 'pending' ? 'sending...' : new Date(msg.created_at * 1000).toLocaleTimeString()}
-                </p>
-                {msg.direction === 'agent_to_user' && (
-                  <AgentResponseFooter msg={msg} copiedId={copiedId} onCopy={(id) => {
-                    navigator.clipboard.writeText(msg.content);
-                    setCopiedId(id);
-                    setTimeout(() => setCopiedId(null), 2000);
-                  }} />
-                )}
-              </div>
-            </div>
-          </div>
-        ))}
-        {/* Progress indicator — shown when waiting but no streamed content or tool calls yet */}
-        {(waitingForResponse || sending) && !streamingContent && streamingToolCalls.length === 0 && (
-          <div className="flex justify-start">
-            <div
-              className="px-3 py-2 rounded-lg text-sm"
-              style={{
-                background: 'var(--color-bg-secondary)',
-                border: '1px solid var(--color-border)',
-                color: 'var(--color-text-secondary)',
-              }}
-            >
-              <div className="flex items-center gap-2">
-                <span className="inline-block w-2 h-2 rounded-full animate-pulse" style={{ background: 'var(--color-accent)' }} />
-                {sending
-                  ? 'Sending message...'
-                  : progressLabel || 'Agent is thinking...'}
-              </div>
-            </div>
-          </div>
-        )}
-        {/* Live tool call cards rendered as their own entries in the flow */}
-        {waitingForResponse && streamingToolCalls.length > 0 && (
-          <div className="flex flex-col items-start gap-2 max-w-[75%]">
-            {streamingToolCalls.map((tc) => (
-              <ToolCallCard key={tc.id} toolCall={tc} />
-            ))}
-          </div>
-        )}
-        {/* Streaming content bubble — real-time response */}
-        {waitingForResponse && streamingContent && (
-          <div className="flex justify-start">
-            <div
-              className="max-w-[75%] px-3 py-2 rounded-lg text-sm"
-              style={{
-                background: 'var(--color-bg-secondary)',
-                border: '1px solid var(--color-border)',
-                color: 'var(--color-text)',
-              }}
-            >
-              {progressLabel && (
-                <div className="flex items-center gap-2 mb-2 text-xs" style={{ color: 'var(--color-text-secondary)' }}>
-                  <span className="inline-block w-2 h-2 rounded-full animate-pulse" style={{ background: 'var(--color-accent)' }} />
-                  {progressLabel}
+                <div className="text-xs mb-1" style={{ color: 'var(--color-text-tertiary)' }}>
+                  Result
+                </div>
+                <div className="prose prose-sm prose-invert max-w-none">
+                  <ReactMarkdown remarkPlugins={[remarkGfm]}>{findings}</ReactMarkdown>
                </div>
-              )}
-              <div className="prose prose-sm prose-invert max-w-none">
-                <ReactMarkdown remarkPlugins={[remarkGfm]}>{streamingContent}</ReactMarkdown>
              </div>
-              <p className="text-xs mt-1 opacity-70">
-                {streamElapsedMs > 0 && `${(streamElapsedMs / 1000).toFixed(1)}s elapsed`}
-              </p>
-            </div>
-          </div>
+            ) : (
+              traceSteps.length === 0 && (
+                <div
+                  className="text-sm text-center py-8"
+                  style={{ color: 'var(--color-text-tertiary)' }}
+                >
+                  No runs yet. Ask a question below to run the agent.
+                </div>
+              )
+            )}
+          </>
        )}
        <div ref={bottomRef} />
      </div>
-      {/* Input area */}
-      <div
-        className="mt-3 pt-3"
-        style={{ borderTop: '1px solid var(--color-border)' }}
-      >
+
+      {/* ── Follow-up chat input ───────────────────────────── */}
+      <div className="mt-3 pt-3" style={{ borderTop: '1px solid var(--color-border)' }}>
        <textarea
          value={input}
          onChange={(e) => setInput(e.target.value)}
          onKeyDown={(e) => {
            if (e.key === 'Enter' && !e.shiftKey) {
              e.preventDefault();
-              handleSend('immediate');
+              handleAsk();
            }
          }}
-          placeholder="Send a message to this agent..."
+          placeholder={isBusy ? 'Agent is running…' : "Ask a follow-up about this agent's work…"}
+          disabled={isBusy}
          className="w-full px-3 py-2 rounded-lg text-sm bg-transparent outline-none resize-none"
-          style={{ border: '1px solid var(--color-border)', color: 'var(--color-text)', minHeight: 72 }}
+          style={{
+            border: '1px solid var(--color-border)',
+            color: 'var(--color-text)',
+            minHeight: 64,
+            opacity: isBusy ? 0.6 : 1,
+          }}
        />
-        <div className="flex gap-2 mt-2">
+        <div className="flex items-center justify-between mt-2">
+          <span className="text-xs" style={{ color: 'var(--color-text-tertiary)' }}>
+            Sends your question as an ad-hoc run — results appear in the trace above.
+          </span>
          <button
-            onClick={() => handleSend('immediate')}
-            disabled={sending || waitingForResponse || !input.trim()}
+            onClick={handleAsk}
+            disabled={isBusy || !input.trim()}
            className="flex items-center gap-1.5 px-3 py-1.5 rounded-lg text-sm cursor-pointer font-medium"
-            style={{ background: 'var(--color-accent)', color: 'var(--color-on-accent)', opacity: sending || !input.trim() ? 0.5 : 1 }}
+            style={{
+              background: 'var(--color-accent)',
+              color: 'var(--color-on-accent)',
+              opacity: isBusy || !input.trim() ? 0.5 : 1,
+            }}
          >
-            <Send size={13} /> Send
+            {isBusy ? <Loader2 size={13} className="animate-spin" /> : <Send size={13} />}
+            {isBusy ? 'Running' : 'Ask'}
          </button>
        </div>
      </div>
@@ -3616,10 +3535,15 @@ export function AgentsPage() {
          }
          prevStatuses.current[agent.id] = agent.status;
        }
+        // Keep the agent list — and the derived selectedAgent status badge —
+        // live. This poll previously fetched statuses only to fire error
+        // toasts and threw the result away, so a detail header could stay
+        // stuck on "running" after a tick finished on the backend.
+        setManagedAgents(agents);
      } catch {}
-    }, 30000);
+    }, 5000);
    return () => clearInterval(interval);
-  }, []);
+  }, [setManagedAgents]);

  if (loading) {
    return (
@@ -3903,7 +3827,7 @@ export function AgentsPage() {
        )}

        {/* Tab: Interact */}
-        {detailTab === 'interact' && <InteractTab agentId={selectedAgent.id} agentStatus={selectedAgent.status} />}
+        {detailTab === 'interact' && <InteractTab agentId={selectedAgent.id} agentStatus={selectedAgent.status} onRunStateChange={refresh} />}

        {/* Tab: Channels */}
        {detailTab === 'channels' && (
@@ -19,7 +19,7 @@ import {
  RefreshCw,
 } from 'lucide-react';
 import { useAppStore, type ThemeMode } from '../lib/store';
-import { checkHealth, fetchSpeechHealth, getMemoryStats } from '../lib/api';
+import { checkHealth, fetchSpeechHealth, getMemoryStats, getInferenceSource, setInferenceSource, type InferenceSource } from '../lib/api';
 import { isAutoUpdateDisabled, setAutoUpdateDisabled } from '../components/Desktop/UpdateChecker';

 function OllamaModelList() {
@@ -162,6 +162,35 @@ export function SettingsPage() {
    try { return parseInt(localStorage.getItem('openjarvis-memory-max-tokens') || '2048'); } catch { return 2048; }
  });

+  const [srcKind, setSrcKind] = useState<InferenceSource['kind']>('ollama');
+  const [customHost, setCustomHost] = useState('http://localhost:1234/v1');
+  const [customModel, setCustomModel] = useState('');
+  const [customEngine, setCustomEngine] = useState('lmstudio');
+  const [customKey, setCustomKey] = useState('');
+  const [srcMsg, setSrcMsg] = useState('');
+
+  useEffect(() => {
+    getInferenceSource().then((s) => {
+      setSrcKind(s.kind);
+      if (s.host) setCustomHost(s.host);
+      if (s.model) setCustomModel(s.model);
+      if (s.engine) setCustomEngine(s.engine);
+    }).catch(() => {});
+  }, []);
+
+  const saveSource = useCallback(async () => {
+    try {
+      if (srcKind === 'custom') {
+        await setInferenceSource({ kind: 'custom', host: customHost, model: customModel, engine: customEngine, apiKey: customKey || undefined });
+      } else {
+        await setInferenceSource({ kind: 'ollama' });
+      }
+      setSrcMsg('Saved — restart the app to apply.');
+    } catch (e: any) {
+      setSrcMsg(e?.message ?? 'Failed to save.');
+    }
+  }, [srcKind, customHost, customModel, customEngine, customKey]);
+
  useEffect(() => {
    checkHealth().then(setHealthy);
    fetchSpeechHealth()
@@ -316,6 +345,73 @@ export function SettingsPage() {
                }}
              />
            </SettingRow>
+            <SettingRow label="API key" description="Required only if the server was started with an API key">
+              <input
+                type="password"
+                value={settings.apiKey}
+                onChange={(e) => { updateSettings({ apiKey: e.target.value }); showSaved(); }}
+                placeholder="OPENJARVIS_API_KEY"
+                autoComplete="off"
+                className="text-sm px-3 py-1.5 rounded-lg outline-none w-56"
+                style={{
+                  background: 'var(--color-bg-secondary)',
+                  color: 'var(--color-text)',
+                  border: '1px solid var(--color-border)',
+                }}
+              />
+            </SettingRow>
+          </Section>
+
+          {/* Inference source */}
+          <Section title="Inference source">
+            <SettingRow label="Source" description="Where the app runs models. Applies after restart.">
+              <select
+                value={srcKind}
+                onChange={(e) => { setSrcKind(e.target.value as InferenceSource['kind']); setSrcMsg(''); }}
+                className="text-sm px-3 py-1.5 rounded-lg outline-none w-56"
+                style={{ background: 'var(--color-bg-secondary)', color: 'var(--color-text)', border: '1px solid var(--color-border)' }}
+              >
+                <option value="ollama">Bundled Ollama (default)</option>
+                <option value="custom">Custom OpenAI-compatible server</option>
+              </select>
+            </SettingRow>
+            {srcKind === 'custom' && (
+              <>
+                <SettingRow label="Server URL" description="e.g. LM Studio: http://localhost:1234/v1">
+                  <input type="text" value={customHost} onChange={(e) => { setCustomHost(e.target.value); setSrcMsg(''); }} placeholder="http://localhost:1234/v1"
+                    className="text-sm px-3 py-1.5 rounded-lg outline-none w-56"
+                    style={{ background: 'var(--color-bg-secondary)', color: 'var(--color-text)', border: '1px solid var(--color-border)' }} />
+                </SettingRow>
+                <SettingRow label="Model" description="Model id served by your endpoint">
+                  <input type="text" value={customModel} onChange={(e) => { setCustomModel(e.target.value); setSrcMsg(''); }} placeholder="qwen2.5-7b-instruct"
+                    className="text-sm px-3 py-1.5 rounded-lg outline-none w-56"
+                    style={{ background: 'var(--color-bg-secondary)', color: 'var(--color-text)', border: '1px solid var(--color-border)' }} />
+                </SettingRow>
+                <SettingRow label="Server type" description="OpenAI-compatible engine">
+                  <select value={customEngine} onChange={(e) => { setCustomEngine(e.target.value); setSrcMsg(''); }}
+                    className="text-sm px-3 py-1.5 rounded-lg outline-none w-56"
+                    style={{ background: 'var(--color-bg-secondary)', color: 'var(--color-text)', border: '1px solid var(--color-border)' }}>
+                    <option value="lmstudio">LM Studio</option>
+                    <option value="vllm">vLLM</option>
+                    <option value="sglang">SGLang</option>
+                    <option value="llamacpp">llama.cpp</option>
+                    <option value="mlx">MLX</option>
+                  </select>
+                </SettingRow>
+                <SettingRow label="API key (optional)" description="Only if your server requires one">
+                  <input type="password" value={customKey} onChange={(e) => { setCustomKey(e.target.value); setSrcMsg(''); }} placeholder="leave blank if none"
+                    className="text-sm px-3 py-1.5 rounded-lg outline-none w-56"
+                    style={{ background: 'var(--color-bg-secondary)', color: 'var(--color-text)', border: '1px solid var(--color-border)' }} />
+                </SettingRow>
+              </>
+            )}
+            <SettingRow label="" description={srcMsg}>
+              <button onClick={saveSource}
+                className="text-sm px-3 py-1.5 rounded-lg outline-none cursor-pointer"
+                style={{ background: 'var(--color-accent, var(--color-bg-tertiary))', color: 'var(--color-text)', border: '1px solid var(--color-border)' }}>
+                Save inference source
+              </button>
+            </SettingRow>
          </Section>

          {/* Models */}
@@ -1 +1 @@
-{"root":["./src/app.tsx","./src/main.tsx","./src/vite-env.d.ts","./src/components/commandpalette.tsx","./src/components/errorboundary.tsx","./src/components/layout.tsx","./src/components/optinmodal.tsx","./src/components/setupscreen.tsx","./src/components/systempulse.tsx","./src/components/chat/audioplayer.tsx","./src/components/chat/chatarea.tsx","./src/components/chat/inputarea.tsx","./src/components/chat/messagebubble.tsx","./src/components/chat/micbutton.tsx","./src/components/chat/streamingdots.tsx","./src/components/chat/systempanel.tsx","./src/components/chat/toolcallcard.tsx","./src/components/chat/xrayfooter.tsx","./src/components/dashboard/costcomparison.tsx","./src/components/dashboard/energydashboard.tsx","./src/components/dashboard/tracedebugger.tsx","./src/components/sidebar/conversationlist.tsx","./src/components/sidebar/sidebar.tsx","./src/components/setup/ingestdashboard.tsx","./src/components/setup/readyscreen.tsx","./src/components/setup/setupwizard.tsx","./src/components/setup/sourceconnectflow.tsx","./src/components/setup/sourcepicker.tsx","./src/components/ui/button.tsx","./src/components/ui/dialog.tsx","./src/components/ui/input.tsx","./src/components/ui/select.tsx","./src/components/ui/sonner.tsx","./src/components/ui/tooltip.tsx","./src/hooks/usespeech.ts","./src/lib/analytics.ts","./src/lib/api.ts","./src/lib/connectors-api.ts","./src/lib/deep-link.ts","./src/lib/profanity.ts","./src/lib/sse.ts","./src/lib/store.ts","./src/lib/useagentevents.ts","./src/lib/utils.ts","./src/pages/agentspage.tsx","./src/pages/chatpage.tsx","./src/pages/dashboardpage.tsx","./src/pages/datasourcespage.tsx","./src/pages/getstartedpage.tsx","./src/pages/logspage.tsx","./src/pages/settingspage.tsx","./src/types/connectors.ts","./src/types/index.ts"],"version":"5.7.3"}
+{"root":["./src/app.tsx","./src/main.tsx","./src/vite-env.d.ts","./src/components/approvalbell.tsx","./src/components/commandpalette.tsx","./src/components/errorboundary.tsx","./src/components/layout.tsx","./src/components/optinmodal.tsx","./src/components/setupscreen.tsx","./src/components/systempulse.tsx","./src/components/chat/audioplayer.tsx","./src/components/chat/chatarea.tsx","./src/components/chat/inputarea.tsx","./src/components/chat/messagebubble.tsx","./src/components/chat/micbutton.tsx","./src/components/chat/researchtimeline.tsx","./src/components/chat/streamingdots.tsx","./src/components/chat/systempanel.tsx","./src/components/chat/toolcallcard.tsx","./src/components/chat/xrayfooter.tsx","./src/components/dashboard/costcomparison.tsx","./src/components/dashboard/energydashboard.tsx","./src/components/dashboard/tracedebugger.tsx","./src/components/sidebar/conversationlist.tsx","./src/components/sidebar/sidebar.tsx","./src/components/setup/ingestdashboard.tsx","./src/components/setup/readyscreen.tsx","./src/components/setup/setupwizard.tsx","./src/components/setup/sourceconnectflow.tsx","./src/components/setup/sourcepicker.tsx","./src/components/ui/button.tsx","./src/components/ui/dialog.tsx","./src/components/ui/input.tsx","./src/components/ui/select.tsx","./src/components/ui/sonner.tsx","./src/components/ui/tooltip.tsx","./src/hooks/usespeech.ts","./src/lib/analytics.ts","./src/lib/api.ts","./src/lib/connectors-api.ts","./src/lib/deep-link.ts","./src/lib/profanity.ts","./src/lib/rehype-citations.ts","./src/lib/sse.ts","./src/lib/store.ts","./src/lib/useagentevents.ts","./src/lib/utils.ts","./src/pages/agentspage.tsx","./src/pages/chatpage.tsx","./src/pages/dashboardpage.tsx","./src/pages/datasourcespage.tsx","./src/pages/getstartedpage.tsx","./src/pages/logspage.tsx","./src/pages/settingspage.tsx","./src/types/connectors.ts","./src/types/index.ts"],"version":"5.7.3"}
@@ -150,6 +150,14 @@ nav:
      - Quick Start: getting-started/quickstart.md
      - Code Snippets: getting-started/snippets.md
      - Configuration: getting-started/configuration.md
+  - Showcase:
+      - Overview: showcase/index.md
+      - Morning Brief: showcase/morning-brief.md
+      - Memory That Doesn't Reset: showcase/persistent-memory.md
+      - Track Your Savings: showcase/cost-savings.md
+      - Discord Companion: showcase/discord-companion.md
+      - Offline Code Reviewer: showcase/coding-assistant.md
+      - Contributing: showcase/CONTRIBUTING.md
  - Tutorials:
      - Overview: tutorials/index.md
      - Deep Research Assistant: tutorials/deep-research.md
@@ -185,6 +193,8 @@ nav:
      - External MCP Servers: user-guide/mcp-external-servers.md
      - Scheduler: user-guide/scheduler.md
      - Telemetry: user-guide/telemetry.md
+      - Evaluations: user-guide/evaluations.md
+      - Benchmarks: user-guide/benchmarks.md
      - Security: user-guide/security.md
      - LLM-guided spec search: user-guide/llm-guided-spec-search.md
  - Leaderboard: leaderboard.md
@@ -7,7 +7,11 @@ name = "OpenJarvis"
 version = "1.0.2"
 description = "OpenJarvis — modular AI assistant backend with composable intelligence primitives"
 readme = "README.md"
-requires-python = ">=3.10"
+# Upper bound: numpy 2.2.x (pinned transitively via datasets/pandas) ships no
+# cp314 Windows wheel, so under Python 3.14 uv would compile numpy from source
+# (Meson) and fail on Windows boxes without a C toolchain (#350). Cap to the
+# range that has prebuilt wheels; matches the classifiers (3.10–3.13).
+requires-python = ">=3.10,<3.14"
 license = {text = "Apache-2.0"}
 authors = [
    {name = "Open Jarvis Contributors"},
@@ -29,12 +33,13 @@ dependencies = [
    "ddgs>=9.11.4",
    "httpx>=0.27",
    "openai>=1.30",
-    "posthog>=3.0",
    "nvidia-ml-py>=12.560.30",
+    "posthog>=3.0",
    "python-telegram-bot>=22.6",
    "rich>=13",
    "tomli>=2.0; python_version < '3.11'",
    "tomlkit>=0.12",
+    "websockets>=15.0.1",
 ]

 [project.optional-dependencies]
@@ -80,19 +85,13 @@ server = [
    "python-multipart>=0.0.9",
 ]
 openhands = ["openhands-sdk>=1.0; python_version >= '3.12'"]
-gpu-metrics = ["nvidia-ml-py>=12.560.30"]
+gpu-metrics = ["pynvml>=12.0"]
 energy-amd = ["amdsmi>=6.1"]
 energy-apple = ["zeus-ml[apple]"]
-energy-all = ["nvidia-ml-py>=12.560.30", "amdsmi>=6.1", "zeus-ml[apple]"]
+energy-all = ["pynvml>=12.0", "amdsmi>=6.1", "zeus-ml[apple]"]
 orchestrator-training = ["torch>=2.0", "transformers>=4.40"]
 learning-dspy = ["dspy>=2.6"]
 learning-gepa = ["gepa>=0.1"]
-# ACE (Agentic Context Engineering) is supported via
-# ``openjarvis.learning.agents.ace_optimizer`` but ACE upstream isn't on
-# PyPI and isn't structured as an installable Python package as of
-# v1.0.1, so there's no ``learning-ace`` extra. To use ACE, follow the
-# manual setup in docs/learning/ace.md (clone the upstream repo, add
-# its ``src/`` to PYTHONPATH).
 channel-telegram = ["python-telegram-bot>=21.0"]
 channel-discord = ["discord.py>=2.3"]
 channel-slack = ["slack-sdk>=3.27"]
@@ -153,6 +152,7 @@ Issues = "https://github.com/open-jarvis/OpenJarvis/issues"

 [project.scripts]
 jarvis = "openjarvis.cli:main"
+openjarvis-eval = "openjarvis.evals.cli:main"

 [tool.hatch.build.targets.wheel]
 packages = ["src/openjarvis"]
@@ -161,6 +161,7 @@ packages = ["src/openjarvis"]
 "src/openjarvis/agents/claude_code_runner" = "_node_modules/claude_code_runner"
 "src/openjarvis/channels/whatsapp_baileys_bridge" = "_node_modules/whatsapp_baileys_bridge"
 "scripts/install" = "_install_scripts"
+"deploy/windows" = "_deploy/windows"

 [tool.pytest.ini_options]
 testpaths = ["tests"]
@@ -174,7 +175,9 @@ markers = [
    "live_channel: requires real channel credentials (env vars)",
    "nvidia: requires NVIDIA GPU",
    "slow: long-running test",
+    "hub: downloads real datasets from the HuggingFace Hub at runtime; excluded from the default CI lane (run with -m hub)",
    "live_external: requires HERMES_AGENT_PATH and OPENCLAW_PATH; spawns real foreign-framework subprocesses",
+    "modal: requires Modal token + network; runs real swebench harness on Modal",
 ]

 [tool.ruff]
@@ -188,11 +191,12 @@ select = ["E", "F", "I", "W"]
 "src/openjarvis/evals/datasets/*.py" = ["E501"]
 "src/openjarvis/evals/scorers/*.py" = ["E501"]
 # hybrid/ is research code with long prompt strings and paradigm-specific
-# config dicts — same relaxation as evals research code above.
-"src/openjarvis/agents/hybrid/*.py" = ["E501"]
-# research_loop.py carries the multi-paragraph planner system prompt as
-# inline string literals; line-length wrapping would harm readability of
-# the prompt itself.
+# config dicts — same relaxation as evals research code above. The ``**`` glob
+# also covers subpackages (e.g. hybrid/skillorchestra/), which the prior
+# ``hybrid/*.py`` glob missed.
+"src/openjarvis/agents/hybrid/**/*.py" = ["E501"]
+# research_loop.py carries long prompt strings too (documented in CLAUDE.md);
+# the ignore was missing here.
 "src/openjarvis/agents/research_loop.py" = ["E501"]

 [dependency-groups]
@@ -20,6 +20,14 @@ members = [
    "crates/openjarvis-scheduler",
 ]

+# Minimum supported Rust version. The workspace uses let-chains (via rig-core)
+# and `is_multiple_of` (openjarvis-skills), both stabilized in Rust 1.88 —
+# building on 1.86/1.87 fails with cryptic E0658 errors deep in dependencies
+# (see #252). Declared here and pinned in rust-toolchain.toml so users get a
+# clear "requires rustc 1.88" signal instead.
+[workspace.package]
+rust-version = "1.88"
+
 [workspace.dependencies]
 serde = { version = "1", features = ["derive"] }
 serde_json = "1"
@@ -32,8 +32,7 @@ impl LoopGuard {
        // Check identical calls
        if self.seen_hashes.contains(&hash) {
            return Some(format!(
-                "Loop detected: identical call to '{}' with same arguments",
-                tool_name
+                "Loop detected: identical call to '{tool_name}' with same arguments"
            ));
        }
        self.seen_hashes.insert(hash);
@@ -355,7 +355,7 @@ impl<M: CompletionModel + 'static> OjAgent for MonitorOperativeAgent<M> {
                // Loop guard check
                if let Some(loop_msg) = guard.check(&action, &action_input) {
                    return Ok(AgentResult {
-                        content: format!("Agent stopped: {}", loop_msg),
+                        content: format!("Agent stopped: {loop_msg}"),
                        tool_results: all_tool_results,
                        turns: turn,
                        metadata: self.strategy_metadata(),
@@ -379,7 +379,7 @@ impl<M: CompletionModel + 'static> OjAgent for MonitorOperativeAgent<M> {
                let compressed = self.compress_observation(&tool_result.content);

                history.push(RigMessage::assistant(&text));
-                current_input = format!("Observation: {}", compressed);
+                current_input = format!("Observation: {compressed}");

                all_tool_results.push(tool_result);
            } else {
@@ -202,7 +202,7 @@ impl<M: CompletionModel + 'static> OjAgent for NativeOpenHandsAgent<M> {

                if let Some(loop_msg) = guard.check(tool_name, &args_str) {
                    return Ok(AgentResult {
-                        content: format!("Agent stopped: {}", loop_msg),
+                        content: format!("Agent stopped: {loop_msg}"),
                        tool_results: all_tool_results,
                        turns: turn,
                        metadata: HashMap::new(),
@@ -221,7 +221,7 @@ impl<M: CompletionModel + 'static> OjAgent for NativeOpenHandsAgent<M> {

                let obs = Self::truncate_observation(&tool_result.content, 4000);
                history.push(RigMessage::assistant(&text));
-                current_input = format!("Output:\n{}", obs);
+                current_input = format!("Output:\n{obs}");

                all_tool_results.push(tool_result);
                continue;
@@ -231,7 +231,7 @@ impl<M: CompletionModel + 'static> OjAgent for NativeOpenHandsAgent<M> {
            if let Some((action, action_input)) = Self::parse_action(&text) {
                if let Some(loop_msg) = guard.check(&action, &action_input) {
                    return Ok(AgentResult {
-                        content: format!("Agent stopped: {}", loop_msg),
+                        content: format!("Agent stopped: {loop_msg}"),
                        tool_results: all_tool_results,
                        turns: turn,
                        metadata: HashMap::new(),
@@ -253,7 +253,7 @@ impl<M: CompletionModel + 'static> OjAgent for NativeOpenHandsAgent<M> {

                let obs = Self::truncate_observation(&tool_result.content, 4000);
                history.push(RigMessage::assistant(&text));
-                current_input = format!("Result: {}", obs);
+                current_input = format!("Result: {obs}");

                all_tool_results.push(tool_result);
                continue;
@@ -143,7 +143,7 @@ impl<M: CompletionModel + 'static> OjAgent for NativeReActAgent<M> {
            if let Some((action, action_input)) = Self::parse_action(&text) {
                if let Some(loop_msg) = guard.check(&action, &action_input) {
                    return Ok(AgentResult {
-                        content: format!("Agent stopped: {}", loop_msg),
+                        content: format!("Agent stopped: {loop_msg}"),
                        tool_results: all_tool_results,
                        turns: turn,
                        metadata: HashMap::new(),
@@ -104,8 +104,7 @@ pub fn get_engine_static(
        ))),
        other => Err(OpenJarvisError::Engine(
            openjarvis_core::error::EngineError::ModelNotFound(format!(
-                "Unknown engine: {}",
-                other
+                "Unknown engine: {other}"
            )),
        )),
    }
@@ -28,7 +28,7 @@ impl LlamaCppEngine {
        let host = if host.starts_with("http") {
            host
        } else {
-            format!("http://{}", host)
+            format!("http://{host}")
        };
        let host = host.trim_end_matches('/').to_string();
        let timeout = std::time::Duration::from_secs_f64(timeout_secs);
@@ -120,8 +120,7 @@ impl InferenceEngine for LlamaCppEngine {
            let status = resp.status();
            let body = resp.text().unwrap_or_default();
            return Err(OpenJarvisError::Engine(EngineError::Http(format!(
-                "llama.cpp returned {}: {}",
-                status, body
+                "llama.cpp returned {status}: {body}"
            ))));
        }

@@ -119,7 +119,7 @@ impl InferenceEngine for OllamaEngine {
                        ToolCall {
                            id: tc["id"]
                                .as_str()
-                                .unwrap_or(&format!("call_{}", i))
+                                .unwrap_or(&format!("call_{i}"))
                                .to_string(),
                            name: func["name"].as_str().unwrap_or("").to_string(),
                            arguments: args,
@@ -84,7 +84,7 @@ impl OpenAICompatEngine {
        if let Some(ref key) = self.api_key {
            headers.insert(
                reqwest::header::AUTHORIZATION,
-                format!("Bearer {}", key).parse().unwrap(),
+                format!("Bearer {key}").parse().unwrap(),
            );
        }
        headers
@@ -239,7 +239,7 @@ impl InferenceEngine for OpenAICompatEngine {
        if let Some(ref key) = self.api_key {
            headers.insert(
                reqwest::header::AUTHORIZATION,
-                format!("Bearer {}", key).parse().unwrap(),
+                format!("Bearer {key}").parse().unwrap(),
            );
        }

@@ -107,8 +107,7 @@ fn rig_request_to_oj_messages(request: &CompletionRequest) -> Vec<Message> {
            .collect::<Vec<_>>()
            .join("\n\n");
        messages.push(Message::system(format!(
-            "Relevant context:\n{}",
-            doc_context
+            "Relevant context:\n{doc_context}"
        )));
    }

@@ -24,7 +24,7 @@ impl SGLangEngine {
        let host = if host.starts_with("http") {
            host
        } else {
-            format!("http://{}", host)
+            format!("http://{host}")
        };
        let host = host.trim_end_matches('/').to_string();
        let timeout = std::time::Duration::from_secs_f64(timeout_secs);
@@ -115,8 +115,7 @@ impl InferenceEngine for SGLangEngine {
            let status = resp.status();
            let body = resp.text().unwrap_or_default();
            return Err(OpenJarvisError::Engine(EngineError::Http(format!(
-                "SGLang returned {}: {}",
-                status, body
+                "SGLang returned {status}: {body}"
            ))));
        }

@@ -26,7 +26,7 @@ impl VLLMEngine {
        let host = if host.starts_with("http") {
            host
        } else {
-            format!("http://{}", host)
+            format!("http://{host}")
        };
        let host = host.trim_end_matches('/').to_string();
        let timeout = std::time::Duration::from_secs_f64(timeout_secs);
@@ -70,7 +70,7 @@ impl VLLMEngine {
        if let Some(ref key) = self.api_key {
            headers.insert(
                reqwest::header::AUTHORIZATION,
-                format!("Bearer {}", key).parse().unwrap(),
+                format!("Bearer {key}").parse().unwrap(),
            );
        }
        headers
@@ -135,8 +135,7 @@ impl InferenceEngine for VLLMEngine {
            let status = resp.status();
            let body = resp.text().unwrap_or_default();
            return Err(OpenJarvisError::Engine(EngineError::Http(format!(
-                "vLLM returned {}: {}",
-                status, body
+                "vLLM returned {status}: {body}"
            ))));
        }

@@ -231,7 +230,7 @@ impl InferenceEngine for VLLMEngine {
        if let Some(ref key) = self.api_key {
            headers.insert(
                reqwest::header::AUTHORIZATION,
-                format!("Bearer {}", key).parse().unwrap(),
+                format!("Bearer {key}").parse().unwrap(),
            );
        }

@@ -78,8 +78,7 @@ impl AgentAdvisorPolicy {
                recs.push(Recommendation {
                    rec_type: "routing".to_string(),
                    suggestion: format!(
-                        "Query class '{}' has {} failures — consider different model or agent",
-                        qclass, count,
+                        "Query class '{qclass}' has {count} failures — consider different model or agent",
                    ),
                    severity: "high".to_string(),
                });
@@ -160,7 +159,7 @@ mod tests {
        let traces: Vec<TraceInfo> = (0..5)
            .map(|i| TraceInfo {
                outcome: "failure".into(),
-                query: format!("query {}", i),
+                query: format!("query {i}"),
                tool_call_count: 8,
                total_latency_seconds: 2.0,
            })
@@ -178,7 +177,7 @@ mod tests {
        let traces: Vec<TraceInfo> = (0..5)
            .map(|i| TraceInfo {
                outcome: "failure".into(),
-                query: format!("def func_{}():", i),
+                query: format!("def func_{i}():"),
                tool_call_count: 2,
                total_latency_seconds: 1.0,
            })
@@ -209,7 +209,7 @@ mod tests {
    fn test_max_examples_trim() {
        let mut policy = ICLUpdaterPolicy::new(0.0, 3, 3);
        for i in 0..5 {
-            policy.add_example(format!("q{}", i), format!("r{}", i), 0.5, HashMap::new());
+            policy.add_example(format!("q{i}"), format!("r{i}"), 0.5, HashMap::new());
        }
        assert_eq!(policy.example_db().len(), 3);
        assert_eq!(policy.example_db()[0].query, "q2");
@@ -97,7 +97,7 @@ impl McpServer {
                let resp = McpResponse::error(
                    Value::Null,
                    -32700,
-                    &format!("Parse error: {}", e),
+                    &format!("Parse error: {e}"),
                );
                serde_json::to_string(&resp).unwrap_or_default()
            }
@@ -93,7 +93,7 @@ impl PyEngine {
            ),
            other => {
                return Err(PyErr::new::<pyo3::exceptions::PyValueError, _>(
-                    format!("Unknown engine: {}", other),
+                    format!("Unknown engine: {other}"),
                ));
            }
        };
@@ -20,8 +20,7 @@ impl PySchedulerStore {
    fn create_task(&self, name: &str, schedule_type: &str, schedule_value: &str) -> PyResult<String> {
        let st = openjarvis_scheduler::ScheduleType::parse(schedule_type).ok_or_else(|| {
            PyErr::new::<pyo3::exceptions::PyValueError, _>(format!(
-                "invalid schedule_type '{}', expected cron/interval/once",
-                schedule_type
+                "invalid schedule_type '{schedule_type}', expected cron/interval/once"
            ))
        })?;
        let task = self.inner.create_task(name, st, schedule_value);
@@ -41,8 +40,7 @@ impl PySchedulerStore {
    fn update_status(&self, id: &str, status: &str) -> PyResult<bool> {
        let s = openjarvis_scheduler::TaskStatus::parse(status).ok_or_else(|| {
            PyErr::new::<pyo3::exceptions::PyValueError, _>(format!(
-                "invalid status '{}', expected active/paused/cancelled/completed",
-                status
+                "invalid status '{status}', expected active/paused/cancelled/completed"
            ))
        })?;
        Ok(self.inner.update_status(id, s))
@@ -266,8 +266,7 @@ impl PyHybridMemory {
                }
                other => {
                    return Err(PyErr::new::<pyo3::exceptions::PyValueError, _>(format!(
-                        "Unknown backend key: {}. Supported: sqlite, bm25, faiss, colbert",
-                        other
+                        "Unknown backend key: {other}. Supported: sqlite, bm25, faiss, colbert"
                    )));
                }
            };
@@ -303,7 +303,7 @@ mod tests {
                event_type: SecurityEventType::SecretDetected,
                timestamp: 1000.0 + i as f64,
                findings: vec![],
-                content_preview: format!("event {}", i),
+                content_preview: format!("event {i}"),
                action_taken: "warn".into(),
            };
            logger.log(&event).unwrap();
@@ -135,14 +135,13 @@ pub fn check_ssrf(url_str: &str) -> Option<String> {

    if BLOCKED_HOSTS.contains(canonical_host.as_str()) {
        return Some(format!(
-            "Blocked host: {} (cloud metadata endpoint)",
-            canonical_host
+            "Blocked host: {canonical_host} (cloud metadata endpoint)"
        ));
    }

    if let Some(ip) = literal_ip {
        if is_private_ip(&ip) {
-            return Some(format!("URL resolves to private IP: {}", ip));
+            return Some(format!("URL resolves to private IP: {ip}"));
        }
        return None;
    }
@@ -153,7 +152,7 @@ pub fn check_ssrf(url_str: &str) -> Option<String> {
        _ => 80,
    });

-    let addr_str = format!("{}:{}", canonical_host, port);
+    let addr_str = format!("{canonical_host}:{port}");
    if let Ok(addrs) = addr_str.to_socket_addrs() {
        for addr in addrs {
            if is_private_ip(&addr.ip()) {
@@ -207,7 +206,7 @@ mod tests {
    fn test_ipv4_mapped_ipv6_rfc1918_is_private() {
        for s in ["::ffff:10.0.0.1", "::ffff:172.16.0.1", "::ffff:192.168.1.1"] {
            let v6: Ipv6Addr = s.parse().unwrap();
-            assert!(is_private_ip(&IpAddr::V6(v6)), "{} should be private", s);
+            assert!(is_private_ip(&IpAddr::V6(v6)), "{s} should be private");
        }
    }

@@ -244,7 +243,7 @@ mod tests {
            "http://[::ffff:172.16.0.1]/",
        ] {
            let result = check_ssrf(url);
-            assert!(result.is_some(), "{} must be blocked", url);
+            assert!(result.is_some(), "{url} must be blocked");
        }
    }

@@ -230,7 +230,7 @@ impl SessionStore {
            params![session_id, remove_up_to as i64],
        );

-        let summary = format!("[consolidated {} earlier messages]", remove_up_to);
+        let summary = format!("[consolidated {remove_up_to} earlier messages]");
        let now = now_secs();
        let _ = self.conn.execute(
            "INSERT INTO session_messages (session_id, role, content, channel, timestamp)
@@ -292,15 +292,13 @@ impl SessionStore {
            let cutoff = now_secs() - self.max_age_hours * 3600.0;
            format!(
                "SELECT session_id FROM sessions
-                 WHERE last_activity >= {}
-                 ORDER BY last_activity DESC LIMIT {}",
-                cutoff, limit
+                 WHERE last_activity >= {cutoff}
+                 ORDER BY last_activity DESC LIMIT {limit}"
            )
        } else {
            format!(
                "SELECT session_id FROM sessions
-                 ORDER BY last_activity DESC LIMIT {}",
-                limit
+                 ORDER BY last_activity DESC LIMIT {limit}"
            )
        };

@@ -356,7 +354,7 @@ impl SessionStore {
                params![checkpoint_id, session_id],
                |row| Ok((row.get(0)?, row.get(1)?)),
            )
-            .map_err(|e| format!("Checkpoint not found: {}", e))?;
+            .map_err(|e| format!("Checkpoint not found: {e}"))?;

        let deleted: usize = self
            .conn
@@ -573,7 +571,7 @@ mod tests {

        for i in 0..10 {
            store
-                .save_message(&s.session_id, "user", &format!("msg {}", i), "irc")
+                .save_message(&s.session_id, "user", &format!("msg {i}"), "irc")
                .unwrap();
        }

@@ -48,7 +48,7 @@ impl BaseTool for CalculatorTool {
            Ok(result) => Ok(ToolResult::success("calculator", result.to_string())),
            Err(e) => Ok(ToolResult::failure(
                "calculator",
-                format!("Error evaluating '{}': {}", expression, e),
+                format!("Error evaluating '{expression}': {e}"),
            )),
        }
    }
@@ -63,7 +63,7 @@ impl BaseTool for FileReadTool {
        if is_sensitive_file(path) {
            return Ok(ToolResult::failure(
                "file_read",
-                format!("Access denied: '{}' is a sensitive file", path_str),
+                format!("Access denied: '{path_str}' is a sensitive file"),
            ));
        }

@@ -71,7 +71,7 @@ impl BaseTool for FileReadTool {
            Ok(content) => Ok(ToolResult::success("file_read", content)),
            Err(e) => Ok(ToolResult::failure(
                "file_read",
-                format!("Error reading '{}': {}", path_str, e),
+                format!("Error reading '{path_str}': {e}"),
            )),
        }
    }
@@ -94,7 +94,7 @@ impl BaseTool for FileWriteTool {
        if is_sensitive_file(path) {
            return Ok(ToolResult::failure(
                "file_write",
-                format!("Access denied: '{}' is a sensitive file", path_str),
+                format!("Access denied: '{path_str}' is a sensitive file"),
            ));
        }

@@ -103,7 +103,7 @@ impl BaseTool for FileWriteTool {
                if let Err(e) = std::fs::create_dir_all(parent) {
                    return Ok(ToolResult::failure(
                        "file_write",
-                        format!("Error creating directory: {}", e),
+                        format!("Error creating directory: {e}"),
                    ));
                }
            }
@@ -116,7 +116,7 @@ impl BaseTool for FileWriteTool {
            )),
            Err(e) => Ok(ToolResult::failure(
                "file_write",
-                format!("Error writing '{}': {}", path_str, e),
+                format!("Error writing '{path_str}': {e}"),
            )),
        }
    }
@@ -21,7 +21,7 @@ fn run_git(args: &[&str], cwd: Option<&str>) -> Result<String, String> {
                Err(String::from_utf8_lossy(&output.stderr).to_string())
            }
        }
-        Err(e) => Err(format!("Failed to run git: {}", e)),
+        Err(e) => Err(format!("Failed to run git: {e}")),
    }
 }

@@ -84,7 +84,7 @@ impl BaseTool for GitLogTool {
    fn execute(&self, params: &Value) -> Result<ToolResult, OpenJarvisError> {
        let cwd = params["cwd"].as_str();
        let n = params["n"].as_i64().unwrap_or(10);
-        match run_git(&["log", "--oneline", &format!("-{}", n)], cwd) {
+        match run_git(&["log", "--oneline", &format!("-{n}")], cwd) {
            Ok(output) => Ok(ToolResult::success("git_log", output)),
            Err(e) => Ok(ToolResult::failure("git_log", e)),
        }
@@ -83,7 +83,7 @@ impl BaseTool for HttpRequestTool {
                } else {
                    body
                };
-                let content = format!("Status: {}\n{}", status, truncated);
+                let content = format!("Status: {status}\n{truncated}");
                if status < 400 {
                    Ok(ToolResult::success("http_request", content))
                } else {
@@ -92,7 +92,7 @@ impl BaseTool for HttpRequestTool {
            }
            Err(e) => Ok(ToolResult::failure(
                "http_request",
-                format!("Request failed: {}", e),
+                format!("Request failed: {e}"),
            )),
        }
    }
@@ -61,8 +61,7 @@ impl BaseTool for ShellExecTool {
                let exit_code = output.status.code().unwrap_or(-1);

                let content = format!(
-                    "Exit code: {}\n--- stdout ---\n{}\n--- stderr ---\n{}",
-                    exit_code, stdout, stderr
+                    "Exit code: {exit_code}\n--- stdout ---\n{stdout}\n--- stderr ---\n{stderr}"
                );

                if output.status.success() {
@@ -73,7 +72,7 @@ impl BaseTool for ShellExecTool {
            }
            Err(e) => Ok(ToolResult::failure(
                "shell_exec",
-                format!("Failed to execute: {}", e),
+                format!("Failed to execute: {e}"),
            )),
        }
    }
@@ -66,7 +66,7 @@ impl ToolExecutor {
                if !policy.check(aid, cap, "") {
                    return Err(OpenJarvisError::Tool(ToolError::CapabilityDenied(
                        aid.to_string(),
-                        format!("{} (tool: {})", cap, tool_name),
+                        format!("{cap} (tool: {tool_name})"),
                    )));
                }
            }
@@ -170,7 +170,7 @@ impl MemoryBackend for KnowledgeGraphMemory {
        top_k: usize,
    ) -> Result<Vec<RetrievalResult>, OpenJarvisError> {
        let conn = self.conn.lock();
-        let pattern = format!("%{}%", query);
+        let pattern = format!("%{query}%");
        let mut stmt = conn
            .prepare(
                "SELECT name, entity_type, properties
@@ -233,8 +233,8 @@ mod tests {
        let store = TraceStore::in_memory().unwrap();
        for i in 0..5 {
            let trace = Trace {
-                trace_id: format!("t{}", i),
-                query: format!("query {}", i),
+                trace_id: format!("t{i}"),
+                query: format!("query {i}"),
                ..Default::default()
            };
            store.save(&trace).unwrap();
@@ -0,0 +1,10 @@
+# Pin the Rust toolchain for the openjarvis_rust workspace.
+#
+# The workspace requires Rust >= 1.88: rig-core uses let-chains and
+# openjarvis-skills uses `is_multiple_of`, both stabilized in 1.88. On older
+# stable toolchains the build fails with cryptic E0658 errors deep inside a
+# transitive dependency (see #252). Pinning here makes rustup install/select a
+# compatible toolchain automatically and gives a clear requirement up front.
+[toolchain]
+channel = "1.88"
+components = ["rustfmt", "clippy"]
@@ -28,6 +28,22 @@ fi

 cd "$SRC_DIR"
 if uv run maturin develop -m "$MANIFEST" >>"$LOG" 2>&1; then
+    # Verify the extension actually imports from THIS venv before declaring
+    # success. `maturin develop` can report success while installing the .so
+    # into a different venv than the one that runs the server, which leaves
+    # memory silently broken at runtime (#502). Only the import check below
+    # proves the serving venv can load it.
+    if ! uv run python -c "import openjarvis_rust" >>"$LOG" 2>&1; then
+        rc=$?
+        {
+            echo "build-extension.sh: maturin succeeded but 'import openjarvis_rust'"
+            echo "failed in the serving venv ($SRC_DIR/.venv) — the extension was"
+            echo "not installed where the server runs. (exit=$rc)"
+            tail -n 50 "$LOG" 2>/dev/null || true
+        } > "$FAILED"
+        rm -f "$BUILT"
+        exit "$rc"
+    fi
    tmp="$BUILT.tmp"
    date -u +"%Y-%m-%dT%H:%M:%SZ" > "$tmp"
    mv "$tmp" "$BUILT"
@@ -73,23 +73,142 @@ EOF
 fi

 # ---- prereq probe ----
+#
+# `git` and `curl` are the only host tools we require. On the supported
+# platforms we can auto-install both; if that fails we fall back to a
+# clear "here's the exact command" error rather than a generic refusal.
 need() {
-    if ! command -v "$1" >/dev/null 2>&1; then
-        cat >&2 <<EOF
-install.sh: '$1' is required but not found.
+    if command -v "$1" >/dev/null 2>&1; then
+        return 0
+    fi
+    case "$(uname -s)" in
+        Darwin)  bootstrap_macos_tool "$1" ;;
+        Linux)   bootstrap_linux_tool "$1" ;;
+        *)       fail_missing_tool "$1" ;;
+    esac
+}

-Install hints:
-  macOS:        xcode-select --install (provides git, curl)
-  Debian/Ubuntu: sudo apt install git curl
-  Fedora/RHEL:   sudo dnf install git curl
-  Arch:          sudo pacman -S git curl
+bootstrap_macos_tool() {
+    local tool="$1"
+    # On macOS, git AND curl ship as part of the Xcode Command Line Tools.
+    # `xcode-select --install` opens a system dialog — useless in a
+    # headless SSH session, so refuse fast there rather than polling for
+    # 20 minutes against something that will never arrive.
+    if [[ -z "${SSH_TTY:-}${SSH_CONNECTION:-}" ]]; then
+        :  # local GUI session — proceed
+    else
+        cat >&2 <<EOF
+install.sh: '$tool' not found, and this looks like a headless SSH session
+(SSH_CONNECTION is set). The xcode-select GUI installer can't run here.
+
+Install '$tool' over SSH with one of:
+  - From a GUI login: 'xcode-select --install' (then re-run this script)
+  - Or: a third-party manager — Homebrew / MacPorts / nix
+
+Re-run this script once '$tool' is on PATH.
 EOF
        exit 1
    fi
+    echo "install.sh: '$tool' not found — installing Xcode Command Line Tools (provides git + curl)..."
+    echo "  A system dialog will open. Click 'Install' and accept the license."
+    xcode-select --install 2>/dev/null || true
+    local waited=0
+    while ! command -v "$tool" >/dev/null 2>&1; do
+        if (( waited >= 600 )); then  # 10 minutes
+            echo "install.sh: timed out waiting for Xcode Command Line Tools."
+            echo "  Finish the install via the dialog, then re-run this command."
+            exit 1
+        fi
+        sleep 5
+        waited=$((waited + 5))
+        if (( waited % 60 == 0 )); then
+            echo "  …still waiting for '$tool' to appear (${waited}s)"
+        fi
+    done
+    echo "  '$tool' installed."
 }
+
+bootstrap_linux_tool() {
+    local tool="$1"
+    # We need passwordless sudo (or already-root) — stdin is the curl
+    # pipe, so an interactive password prompt will either hang or fail
+    # silently under `set -euo pipefail`. Check up-front and fail with a
+    # clear message rather than a confusing hang.
+    if [[ "$(id -u)" -ne 0 ]] && ! sudo -n true 2>/dev/null; then
+        cat >&2 <<EOF
+install.sh: '$tool' is not installed, and we need sudo to install it via
+the system package manager — but sudo would prompt for a password and
+stdin is occupied by the curl pipe.
+
+Two ways forward:
+
+  1. Install '$tool' yourself, then re-run this installer:
+       Debian/Ubuntu: sudo apt install -y $tool
+       Fedora/RHEL:   sudo dnf install -y $tool
+       Arch:          sudo pacman -S $tool
+
+  2. Pre-authenticate sudo before piping (caches credentials for 5 min):
+       sudo -v && curl -fsSL https://open-jarvis.github.io/OpenJarvis/install.sh | bash
+EOF
+        exit 1
+    fi
+    local sudo=""
+    [[ "$(id -u)" -ne 0 ]] && sudo="sudo"
+    echo "install.sh: '$tool' not found — installing via the system package manager..."
+    # Use `;` not `&&` between update and install so a transient apt
+    # update failure (mirror flake, expired cache) doesn't block install
+    # from a still-usable local index.
+    if command -v apt-get >/dev/null 2>&1; then
+        $sudo apt-get update -q || true
+        $sudo apt-get install -y "$tool"
+    elif command -v dnf >/dev/null 2>&1; then
+        $sudo dnf install -y "$tool"
+    elif command -v yum >/dev/null 2>&1; then
+        $sudo yum install -y "$tool"
+    elif command -v pacman >/dev/null 2>&1; then
+        $sudo pacman -S --noconfirm "$tool"
+    elif command -v zypper >/dev/null 2>&1; then
+        $sudo zypper install -y "$tool"
+    elif command -v apk >/dev/null 2>&1; then
+        $sudo apk add --no-cache "$tool"
+    else
+        fail_missing_tool "$tool"
+    fi
+    if ! command -v "$tool" >/dev/null 2>&1; then
+        fail_missing_tool "$tool"
+    fi
+}
+
+fail_missing_tool() {
+    cat >&2 <<EOF
+install.sh: '$1' is required but not found and we couldn't install it automatically.
+
+Install hints:
+  macOS:         xcode-select --install (provides git, curl)
+  Debian/Ubuntu: sudo apt install $1
+  Fedora/RHEL:   sudo dnf install $1
+  Arch:          sudo pacman -S $1
+
+Re-run this script once '$1' is on PATH.
+EOF
+    exit 1
+}
+
 need git
 need curl

+# ---- python command ----
+# Prefer `python3` (Linux / macOS / WSL convention); fall back to `python`
+# on minimal distros that only ship the unversioned name. This is used by
+# the analytics beacon and state-file helpers below — uv installs its own
+# interpreter into the venv later, so this is only for the bootstrap shims.
+PY_CMD="python3"
+if ! command -v python3 >/dev/null 2>&1; then
+    if command -v python >/dev/null 2>&1; then
+        PY_CMD="python"
+    fi
+fi
+
 # ---- env ----
 OPENJARVIS_HOME="${OPENJARVIS_HOME:-$HOME/.openjarvis}"
 OPENJARVIS_REPO_URL="${OPENJARVIS_REPO_URL:-https://github.com/open-jarvis/OpenJarvis.git}"
@@ -123,17 +242,6 @@ INSTALL_START_EPOCH="$(date +%s)"
 CURRENT_STAGE=""

 analytics_enabled() {
-    # Honor the same opt-out env vars as the Python analytics module
-    # (``src/openjarvis/analytics/identity.py::is_analytics_enabled``).
-    # ``DO_NOT_TRACK`` is W3C convention; ``OPENJARVIS_NO_ANALYTICS`` is
-    # the project-specific override. Any truthy value disables.
-    for var in DO_NOT_TRACK OPENJARVIS_NO_ANALYTICS; do
-        val="${!var:-}"
-        case "$(printf '%s' "$val" | tr '[:upper:]' '[:lower:]' | xargs)" in
-            ""|0|false|no|off) ;;
-            *) return 1 ;;
-        esac
-    done
    return 0
 }

@@ -154,15 +262,19 @@ detect_arch() {
 }

 get_anon_id() {
+    # POSIX shell UUID v4 — no Python required so this works on hosts
+    # where python3/python aren't on PATH yet (#484). The script must
+    # not crash on those hosts; analytics are best-effort.
    if [[ -f "$ANON_ID_FILE" ]]; then
        cat "$ANON_ID_FILE"
        return
    fi
-    local new_id
-    new_id="$(python3 -c 'import uuid; print(uuid.uuid4())' 2>/dev/null || echo "")"
-    if [[ -z "$new_id" ]]; then
-        return
+    local raw new_id
+    raw="$(od -An -tx1 -N16 /dev/urandom 2>/dev/null | tr -d ' \n')" || true
+    if [[ ${#raw} -ne 32 ]]; then
+        return 0  # /dev/urandom unreadable — skip analytics silently
    fi
+    new_id="${raw:0:8}-${raw:8:4}-${raw:12:4}-${raw:16:4}-${raw:20:12}"
    echo "$new_id" > "$ANON_ID_FILE"
    echo "$new_id"
 }
@@ -183,6 +295,13 @@ stage_label() {

 beacon() {
    # Args: event_name stage_label elapsed_ms exit_code
+    #
+    # No Python required (#484) — uses curl + shell-built JSON. All
+    # inputs are from controlled sources: $event is a fixed-vocabulary
+    # string (install_started / install_stage_completed / install_failed
+    # / install_completed), $stage comes from stage_label(), the numeric
+    # args are validated by the arithmetic that produced them, and
+    # $anon_id is a fresh UUID. No general-purpose JSON escaping needed.
    local event="$1"
    local stage="${2:-}"
    local elapsed_ms="${3:-0}"
@@ -200,50 +319,35 @@ beacon() {
    os="$(detect_os)"
    arch="$(detect_arch)"

-    python3 - "$ANALYTICS_HOST" "$ANALYTICS_KEY" "$event" "$anon_id" \
-        "$os" "$arch" "$stage" "$elapsed_ms" "$exit_code" \
-        >/dev/null 2>&1 <<'PYEOF' || true
-import json
-import sys
-import urllib.request
+    local props
+    props='"os":"'"$os"'","arch":"'"$arch"'","installer_version":"0.1.1"'
+    if [[ -n "$stage" ]]; then
+        props="${props},\"stage\":\"$stage\""
+    fi
+    # Map elapsed_ms → total_elapsed_ms for install_completed events
+    # (matches the old Python beacon's behavior).
+    if [[ "$event" = "install_completed" ]]; then
+        props="${props},\"total_elapsed_ms\":${elapsed_ms}"
+    elif [[ "$elapsed_ms" != "0" ]]; then
+        props="${props},\"elapsed_ms\":${elapsed_ms}"
+    fi
+    if [[ "$exit_code" != "0" ]]; then
+        props="${props},\"exit_code\":${exit_code}"
+    fi

-host, key, event, distinct_id, os_val, arch, stage, elapsed_ms, exit_code = sys.argv[1:10]
-props = {
-    "os": os_val,
-    "arch": arch,
-    "installer_version": "0.1.1",
-}
-if stage:
-    props["stage"] = stage
-if elapsed_ms and elapsed_ms != "0":
-    try:
-        props["elapsed_ms"] = int(elapsed_ms)
-    except ValueError:
-        pass
-if exit_code and exit_code != "0":
-    try:
-        props["exit_code"] = int(exit_code)
-    except ValueError:
-        pass
-if event == "install_completed":
-    props["total_elapsed_ms"] = props.pop("elapsed_ms", 0)
-payload = {
-    "api_key": key,
-    "event": event,
-    "distinct_id": distinct_id,
-    "properties": props,
-}
-req = urllib.request.Request(
-    f"{host}/i/v0/e/",
-    data=json.dumps(payload).encode("utf-8"),
-    headers={"Content-Type": "application/json"},
-    method="POST",
-)
-try:
-    urllib.request.urlopen(req, timeout=5)
-except Exception:
-    pass
-PYEOF
+    local payload
+    payload="{\"api_key\":\"$ANALYTICS_KEY\",\"event\":\"$event\",\"distinct_id\":\"$anon_id\",\"properties\":{$props}}"
+
+    # Fire and forget. `|| true` is load-bearing: the script runs under
+    # `set -e` via the ERR trap, and we never want a flaky PostHog post
+    # to abort an install. The trap is already installed; without the
+    # explicit `|| true` a 5xx or DNS failure would tickle it.
+    curl -s -X POST \
+        -H 'Content-Type: application/json' \
+        -d "$payload" \
+        --max-time 5 \
+        "${ANALYTICS_HOST}/i/v0/e/" \
+        >/dev/null 2>&1 || true
 }

 _on_install_error() {
@@ -259,19 +363,47 @@ state_done() {
 }

 mark_done() {
-    if [[ ! -f "$STATE_FILE" ]]; then
+    # Shell-only state-file update so the install never crashes when no
+    # python3/python is on PATH (#484). awk regenerates the file from
+    # scratch each call, which is robust against any prior format drift.
+    #
+    # Format: a flat JSON object of `"<step_name>": true` lines plus a
+    # `"wsl": true|false` trailer. state_done() matches against this
+    # with a grep — the content only has to be greppable, but we keep
+    # it valid JSON for any tooling that wants to parse it.
+    local key="$1"
+    if [[ ! -f "$STATE_FILE" ]] || [[ ! -s "$STATE_FILE" ]]; then
        echo '{}' > "$STATE_FILE"
    fi
-    python3 - "$STATE_FILE" "$1" "$WSL" <<'PYEOF'
-import json, sys
-path, key, wsl = sys.argv[1], sys.argv[2], sys.argv[3]
-with open(path) as f:
-    data = json.load(f)
-data[key] = True
-data["wsl"] = bool(int(wsl))
-with open(path, "w") as f:
-    json.dump(data, f, indent=2)
-PYEOF
+
+    # Already marked? Nothing to do.
+    if grep -q "\"$key\":[[:space:]]*true" "$STATE_FILE"; then
+        return 0
+    fi
+
+    local wsl_bool
+    wsl_bool="$([[ $WSL -eq 1 ]] && echo true || echo false)"
+
+    local tmp="${STATE_FILE}.tmp.$$"
+    awk -v new_key="$key" -v wsl="$wsl_bool" '
+    /"[^"]+":[[:space:]]*true/ {
+        match($0, /"[^"]+"/)
+        k = substr($0, RSTART + 1, RLENGTH - 2)
+        # wsl is rewritten on every call — skip the existing entry so
+        # we do not emit it twice with potentially different values.
+        if (k != "wsl") keys[++n] = k
+    }
+    END {
+        keys[++n] = new_key
+        print "{"
+        for (i = 1; i <= n; i++) {
+            printf "  \"%s\": true,\n", keys[i]
+        }
+        printf "  \"wsl\": %s\n", wsl
+        print "}"
+    }
+    ' "$STATE_FILE" > "$tmp"
+    mv "$tmp" "$STATE_FILE"
 }

 step() {
@@ -316,8 +448,77 @@ copy_scripts() {
    chmod +x "$SCRIPTS_DIR"/*.sh
 }

+# Parse pyproject.toml's requires-python and return the newest minor
+# version usable. E.g. ">=3.10,<3.14" → "3.13". Falls back to the
+# previous hardcoded "3.11" if pyproject can't be read or the spec
+# can't be parsed (#476 — installer should track the project's allowed
+# range instead of hardcoding 3.11).
+parse_requires_python() {
+    local pyproject="$1"
+    local fallback="3.11"
+    if [[ ! -f "$pyproject" ]]; then
+        echo "$fallback"
+        return 0
+    fi
+    local spec
+    spec="$(grep '^requires-python' "$pyproject" | head -1)"
+    if [[ -z "$spec" ]]; then
+        echo "$fallback"
+        return 0
+    fi
+    # Inclusive upper bound first ("<=3.13" allows 3.13 itself). Must
+    # match before the exclusive-bound branch, since "<=" contains "<"
+    # and the exclusive regex would otherwise extract "3.13" and
+    # subtract 1 (returning 3.12) — masking the inclusive intent.
+    local max_incl
+    max_incl="$(echo "$spec" | sed -n 's/.*<=\([0-9][0-9]*\.[0-9][0-9]*\).*/\1/p' | head -1)"
+    if [[ -n "$max_incl" ]]; then
+        echo "$max_incl"
+        return 0
+    fi
+    # Exclusive upper bound ("<3.14" means 3.13 is the highest allowed).
+    local max
+    max="$(echo "$spec" | sed -n 's/.*<\([0-9][0-9]*\.[0-9][0-9]*\).*/\1/p' | head -1)"
+    if [[ -z "$max" ]]; then
+        echo "$fallback"
+        return 0
+    fi
+    local major minor
+    major="${max%.*}"
+    minor="${max#*.}"
+    minor=$((minor - 1))
+    if (( minor < 10 )); then
+        echo "$fallback"
+    else
+        echo "${major}.${minor}"
+    fi
+}
+
 create_venv() {
-    uv venv --python 3.11 "$VENV_DIR"
+    # Read pyproject.toml's requires-python upper bound and target the
+    # highest version in range (#476). Falls back to 3.11 if pyproject
+    # can't be parsed. uv bootstraps a managed Python if the host
+    # doesn't have the requested version (fresh macOS without
+    # xcode-select, fresh Ubuntu 24.04 which only ships 3.12, etc).
+    #
+    # stderr from the first attempt is captured to a log so a genuine
+    # failure (disk full, broken venv dir, permission denied) is still
+    # surfaceable when the bootstrap fallback also fails.
+    local py_version
+    py_version="$(parse_requires_python "$SRC_DIR/pyproject.toml")"
+    echo "    Target Python: $py_version (from pyproject.toml requires-python)"
+
+    local err_log="$STATE_DIR/venv-create.err"
+    if ! uv venv --python "$py_version" "$VENV_DIR" 2>"$err_log"; then
+        echo "    No system Python $py_version — uv will download a managed one..."
+        uv python install "$py_version"
+        if ! uv venv --python "$py_version" "$VENV_DIR"; then
+            echo "    venv creation failed. First attempt's stderr:"
+            sed 's/^/      /' "$err_log" >&2
+            return 1
+        fi
+    fi
+    rm -f "$err_log"
 }

 editable_install() {
@@ -336,23 +537,54 @@ install_ollama() {
 start_ollama() {
    if pgrep -f "ollama serve" >/dev/null 2>&1; then
        echo "    ollama serve already running"
+        wait_for_ollama || true
        return 0
    fi
    if [[ "$WSL" -eq 1 ]] || ! command -v systemctl >/dev/null 2>&1; then
        nohup ollama serve > "$STATE_DIR/ollama.log" 2>&1 &
-        sleep 1
    else
        systemctl --user start ollama 2>/dev/null \
-            || (nohup ollama serve > "$STATE_DIR/ollama.log" 2>&1 & sleep 1)
+            || nohup ollama serve > "$STATE_DIR/ollama.log" 2>&1 &
    fi
+    # `|| true` is load-bearing — wait_for_ollama returns 1 on timeout
+    # and we're under `set -euo pipefail` via the `step` wrapper. We want
+    # the warning to surface in the final banner, not abort the install.
+    wait_for_ollama || true
 }

+# Poll `ollama list` until the daemon responds, up to 60 seconds. Replaces
+# the old fixed `sleep 1` which raced the model pull on slower hosts.
+# Cold-start latency on low-spec ARM boards or under heavy load can run
+# past 30s; 60 is the conservative ceiling. Returns 1 on timeout — caller
+# MUST guard with `|| true` (see start_ollama).
+wait_for_ollama() {
+    local waited=0
+    while ! ollama list >/dev/null 2>&1; do
+        if (( waited >= 60 )); then
+            echo "    warning: ollama daemon not responding after 60s — check $STATE_DIR/ollama.log"
+            return 1
+        fi
+        sleep 1
+        waited=$((waited + 1))
+    done
+}
+
+# Tracks whether the foreground model pull actually succeeded. If it
+# didn't, the final completion banner needs to say so loudly rather than
+# claiming chat is ready.
+MODEL_PULL_OK=0
+
 pull_default_model() {
    if [[ "$MINIMAL" -eq 1 ]]; then
        echo "    --minimal set; skipping model pull"
+        MODEL_PULL_OK=1  # nothing to pull → not a failure
        return 0
    fi
-    ollama pull qwen3.5:2b || echo "    warning: ollama pull failed; bg-orchestrator will retry"
+    if ollama pull qwen3.5:2b; then
+        MODEL_PULL_OK=1
+    else
+        echo "    warning: ollama pull failed; bg-orchestrator will retry in the background"
+    fi
 }

 write_config() {
@@ -367,6 +599,11 @@ install_symlinks() {
    ln -sf "$SCRIPTS_DIR/jarvis-uninstall.sh" "$HOME/.local/bin/jarvis-uninstall"
 }

+# Tracks whether the user needs to source ~/.bashrc / ~/.zshrc / open a
+# new terminal before `jarvis` will resolve. Set only when ensure_path
+# actually modified the user's rc file.
+PATH_MODIFIED=0
+
 ensure_path() {
    case ":$PATH:" in
        *":$HOME/.local/bin:"*) return 0 ;;
@@ -378,6 +615,9 @@ ensure_path() {
        rc="$HOME/.bashrc"
    fi
    if grep -q "OpenJarvis" "$rc" 2>/dev/null; then
+        # rc already has our PATH line from a prior install; just remind.
+        PATH_MODIFIED=1
+        PATH_MODIFIED_RC="$rc"
        return 0
    fi
    {
@@ -385,7 +625,8 @@ ensure_path() {
        echo '# OpenJarvis'
        echo 'export PATH="$HOME/.local/bin:$PATH"'
    } >> "$rc"
-    echo "    Added ~/.local/bin to PATH in $rc — run: source $rc"
+    PATH_MODIFIED=1
+    PATH_MODIFIED_RC="$rc"
 }

 detach_bg_orchestrator() {
@@ -442,10 +683,53 @@ beacon "install_completed" "" "$INSTALL_TOTAL_MS"
 # Clear ERR trap — we succeeded; any later non-zero exit shouldn't beacon a failure.
 trap - ERR

+echo
+echo "Done."
+echo
+
+# Tell the truth about what the user has to do next, given (a) whether
+# the foreground model pull actually succeeded and (b) whether the PATH
+# update needs a shell refresh. The four combinations:
+#
+#   PATH ok + model ok   -> "type jarvis"
+#   PATH new + model ok  -> "source rc && jarvis  (or open new terminal)"
+#   PATH ok + model bad  -> "model still downloading; jarvis doctor"
+#   PATH new + model bad -> "source rc && jarvis doctor; chat works once download finishes"
+#
+# `jarvis` and `jarvis doctor` need PATH equally, so the source/restart
+# guidance goes first when PATH was modified.
+NEXT_CMD="jarvis"
+if [[ "$MODEL_PULL_OK" -ne 1 ]]; then
+    NEXT_CMD="jarvis doctor"
+fi
+
+if [[ "$PATH_MODIFIED" -eq 1 ]]; then
+    cat <<EOF
+A PATH update was written to ${PATH_MODIFIED_RC:-your shell rc file}. To
+pick it up in THIS terminal:
+
+  source ${PATH_MODIFIED_RC:-~/.bashrc} && $NEXT_CMD
+
+Or open a new terminal and run: $NEXT_CMD
+
+EOF
+else
+    cat <<EOF
+Run: $NEXT_CMD
+
+EOF
+fi
+
+if [[ "$MODEL_PULL_OK" -ne 1 ]]; then
+    cat <<EOF
+NOTE: the qwen3.5:2b model didn't finish downloading. 'jarvis doctor'
+shows the retry progress; chat will work once the download completes
+in the background.
+
+EOF
+fi
+
 cat <<EOF
-
-Done. Type 'jarvis' to start chatting.
-
 Background work continues silently:
  - Rust toolchain + maturin extension build
  - Bigger model downloads
@@ -11,7 +11,6 @@ from __future__ import annotations
 import argparse
 import json
 import os
-import webbrowser
 from http.server import BaseHTTPRequestHandler, HTTPServer
 from pathlib import Path
 from typing import Any, Dict, List
@@ -19,6 +18,8 @@ from urllib.parse import parse_qs, urlencode, urlparse

 import httpx

+from openjarvis.core import open_browser
+
 CONFIG_DIR = Path.home() / ".openjarvis" / "connectors"
 CONFIG_DIR.mkdir(parents=True, exist_ok=True)

@@ -144,7 +145,7 @@ def do_google() -> None:
        })
    )
    print("  Opening browser...")
-    webbrowser.open(url)
+    open_browser(url)
    code = _wait_for_code()

    resp = httpx.post(
@@ -192,7 +193,7 @@ def do_strava() -> None:
        })
    )
    print("  Opening browser...")
-    webbrowser.open(url)
+    open_browser(url)
    code = _wait_for_code()

    resp = httpx.post(
@@ -303,7 +304,7 @@ def do_spotify() -> None:
        })
    )
    print("  Opening browser...")
-    webbrowser.open(url)
+    open_browser(url)
    code = _wait_for_code(port=spotify_port)

    import base64
@@ -47,19 +47,24 @@ echo "  └───────────────────────
 echo -e "${NC}"

 # ── 1. Check Python ──────────────────────────────────────────────────
+# Prefer python3, fall back to python (Windows / minimal distros that ship
+# only the unversioned name).
 info "Checking Python..."
 if command -v python3 &>/dev/null; then
-  PY_VERSION=$(python3 -c "import sys; print(f'{sys.version_info.major}.{sys.version_info.minor}')")
-  PY_MAJOR=$(echo "$PY_VERSION" | cut -d. -f1)
-  PY_MINOR=$(echo "$PY_VERSION" | cut -d. -f2)
-  if [ "$PY_MAJOR" -ge 3 ] && [ "$PY_MINOR" -ge 10 ]; then
-    ok "Python $PY_VERSION"
-  else
-    fail "Python 3.10+ required (found $PY_VERSION)"
-  fi
+  PY_CMD="python3"
+elif command -v python &>/dev/null; then
+  PY_CMD="python"
 else
  fail "Python 3 not found. Install from https://python.org"
 fi
+PY_VERSION=$("$PY_CMD" -c "import sys; print(f'{sys.version_info.major}.{sys.version_info.minor}')")
+PY_MAJOR=$(echo "$PY_VERSION" | cut -d. -f1)
+PY_MINOR=$(echo "$PY_VERSION" | cut -d. -f2)
+if [ "$PY_MAJOR" -ge 3 ] && [ "$PY_MINOR" -ge 10 ]; then
+  ok "Python $PY_VERSION ($PY_CMD)"
+else
+  fail "Python 3.10+ required (found $PY_VERSION)"
+fi

 # ── 2. Check / install uv ───────────────────────────────────────────
 info "Checking uv..."
@@ -182,6 +187,7 @@ info "Opening $URL ..."
 case "$(uname -s)" in
  Darwin) open "$URL" ;;
  Linux)  xdg-open "$URL" 2>/dev/null || true ;;
+  MINGW*|MSYS*|CYGWIN*) cmd /c start "" "$URL" 2>/dev/null || true ;;
  *)      true ;;
 esac

@@ -32,7 +32,21 @@ def get_rust_module() -> _types.ModuleType:
    return openjarvis_rust


-RUST_AVAILABLE: bool = True
+def _detect_rust() -> bool:
+    """Return ``True`` if the compiled ``openjarvis_rust`` extension is importable.
+
+    Computed once at import time. Modules with a Python fallback (e.g.
+    ``security.ssrf``) consult this flag instead of hardcoding availability,
+    so the fallback is actually reachable when the extension was not built.
+    """
+    try:
+        get_rust_module()
+    except ImportError:
+        return False
+    return True
+
+
+RUST_AVAILABLE: bool = _detect_rust()


 # ---------------------------------------------------------------------------
@@ -2,6 +2,7 @@

 from __future__ import annotations

+import secrets
 from typing import Any, Callable, Dict, List, Optional

 from openjarvis.a2a.protocol import (
@@ -17,6 +18,11 @@ class A2AServer:
    """A2A server that processes incoming tasks via agent execution.

    Can be mounted as routes in the FastAPI server.
+
+    When *auth_token* is set, every :meth:`handle_request` call must present a
+    matching bearer token or it is rejected before any agent runs. The token
+    is advertised on the agent card's ``authentication`` field. When unset,
+    the server is unauthenticated — only mount it on a trusted network.
    """

    def __init__(
@@ -25,21 +31,51 @@ class A2AServer:
        *,
        handler: Optional[Callable[[str], str]] = None,
        bus: Optional[EventBus] = None,
+        auth_token: Optional[str] = None,
    ) -> None:
        self._card = agent_card
        self._handler = handler
        self._bus = bus
+        self._auth_token = auth_token or None
        self._tasks: Dict[str, A2ATask] = {}
+        if self._auth_token:
+            # Advertise the required scheme on the discovery card.
+            self._card.authentication = {"schemes": ["bearer"]}

    @property
    def agent_card(self) -> AgentCard:
        return self._card

-    def handle_request(self, request_data: Dict[str, Any]) -> Dict[str, Any]:
-        """Process a JSON-RPC 2.0 A2A request."""
+    def authenticate(self, token: Optional[str]) -> bool:
+        """Constant-time check of a presented bearer *token*.
+
+        Returns ``True`` when no ``auth_token`` is configured (auth disabled).
+        """
+        if not self._auth_token:
+            return True
+        return bool(token) and secrets.compare_digest(token, self._auth_token)
+
+    def handle_request(
+        self,
+        request_data: Dict[str, Any],
+        *,
+        token: Optional[str] = None,
+    ) -> Dict[str, Any]:
+        """Process a JSON-RPC 2.0 A2A request.
+
+        *token* is the bearer credential extracted by the transport (e.g. the
+        HTTP ``Authorization`` header). It is validated before dispatch when
+        the server is configured with an ``auth_token``.
+        """
+        req_id = request_data.get("id", "")
+        if not self.authenticate(token):
+            return A2AResponse(
+                error={"code": -32001, "message": "Unauthorized"},
+                request_id=req_id,
+            ).to_dict()
+
        method = request_data.get("method", "")
        params = request_data.get("params", {})
-        req_id = request_data.get("id", "")

        if method == "tasks/send":
            return self._handle_task_send(params, req_id)
@@ -54,6 +54,11 @@ try:
 except ImportError:
    pass

+try:
+    import openjarvis.agents.opencode  # noqa: F401
+except ImportError:
+    pass
+
 try:
    import openjarvis.agents.operative  # noqa: F401
 except ImportError:
@@ -79,11 +84,6 @@ try:
 except ImportError:
    pass

-try:
-    import openjarvis.agents.proactive_agent  # noqa: F401
-except ImportError:
-    pass
-
 # Hybrid local+cloud paradigm agents (Minions, Conductor, Archon, Advisors,
 # SkillOrchestra, ToolOrchestra). Each module registers under its own name
 # via @AgentRegistry.register(). Optional deps may make some unavailable.
@@ -121,6 +121,23 @@ class BaseAgent(ABC):
            payload.update(data)
            self._bus.publish(EventType.AGENT_TURN_END, payload)

+    def _apply_persona(self, system_prompt: Optional[str]) -> Optional[str]:
+        """Append SOUL/MEMORY/USER persona to a self-assembled system prompt.
+
+        Agents like ``monitor_operative`` / ``operative`` build their own
+        system prompt and bypass ``_build_messages`` (and thus the prompt
+        builder). This lets them honor the same persona files as one-shot
+        ``jarvis ask`` (#376) by *appending* persona to — never replacing —
+        their specialized instructions. No-op when no ``prompt_builder`` is
+        wired or no persona files exist.
+        """
+        if self._prompt_builder is None:
+            return system_prompt
+        persona = self._prompt_builder.persona_sections()
+        if not persona:
+            return system_prompt
+        return f"{system_prompt}\n\n{persona}" if system_prompt else persona
+
    def _build_messages(
        self,
        input: str,
@@ -307,6 +324,7 @@ class ToolUsingAgent(BaseAgent):
        interactive: bool = False,
        confirm_callback: Optional[Any] = None,
        skill_few_shot_examples: Optional[List[str]] = None,
+        prompt_builder: Optional[Any] = None,
    ) -> None:
        super().__init__(
            engine,
@@ -314,6 +332,7 @@ class ToolUsingAgent(BaseAgent):
            bus=bus,
            temperature=temperature,
            max_tokens=max_tokens,
+            prompt_builder=prompt_builder,
        )
        from openjarvis.tools._stubs import ToolExecutor

@@ -112,10 +112,15 @@ class ChannelAgent:
            friendly = (
                f"Sorry, I ran into an error while processing your request: {exc}"
            )
+            # First positional arg is the DESTINATION (per-adapter native
+            # ID — Discord channel ID, Slack channel ID, etc.); not the
+            # channel TYPE label. The `conversation_id=` kwarg is the
+            # native message ID for reply threading (per DiscordChannel
+            # / SlackChannel / etc. send() contract — see #459).
            self._channel.send(
-                msg.channel,
+                msg.conversation_id,
                friendly,
-                conversation_id=msg.conversation_id,
+                conversation_id=msg.message_id,
            )
            return

@@ -130,10 +135,11 @@ class ChannelAgent:
        else:
            reply = response_text

+        # Same field-mapping as the error path above (#459).
        self._channel.send(
-            msg.channel,
+            msg.conversation_id,
            reply,
-            conversation_id=msg.conversation_id,
+            conversation_id=msg.message_id,
        )

    # ------------------------------------------------------------------
--- a/Show More
+++ b/Show More