fix(server): wire WS event bridge to the bus channels actually publish to (#673)

* fix(server): wire WS event bridge to the bus channels actually publish to

include_all_routes() built the /v1/agents/events WebSocket router from
get_event_bus() — a global singleton nothing in `jarvis serve` publishes
to. The real bus lives at app.state.bus (set in server/app.py and handed
to every channel/agent). Events published on it silently never reached
any connected browser client, since the WS router was subscribed to a
different, disconnected EventBus instance entirely.

* fix(server): keep managed agent events on app bus

---------

Co-authored-by: Ari <ari.silva@paipe.co>
Co-authored-by: Elliot Slusky <elliot@slusky.com>

.github/clone-stats/badge.json

@@ -1,7 +1,7 @@
 {
   "schemaVersion": 1,
   "label": "Git Clones",
-  "message": "59,867",
+  "message": "190,252",
   "color": "green",
   "namedLogo": "git"
 }

.github/clone-stats/clone-data.json

@@ -1,6 +1,6 @@
 {
-  "total_clones": 59867,
-  "last_updated": "2026-05-16T06:49:33Z",
+  "total_clones": 190252,
+  "last_updated": "2026-08-14T07:19:51Z",
   "daily": {
     "2026-03-27": 2189,
     "2026-03-28": 1874,
@@ -50,6 +50,97 @@
     "2026-05-11": 1008,
     "2026-05-12": 1390,
     "2026-05-13": 1397,
-    "2026-05-14": 846
+    "2026-05-14": 846,
+    "2026-05-15": 1671,
+    "2026-05-16": 2264,
+    "2026-05-17": 654,
+    "2026-05-18": 1425,
+    "2026-05-19": 850,
+    "2026-05-20": 954,
+    "2026-05-21": 1605,
+    "2026-05-22": 612,
+    "2026-05-23": 2437,
+    "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,
+    "2026-06-11": 2564,
+    "2026-06-12": 1313,
+    "2026-06-13": 2804,
+    "2026-06-14": 1543,
+    "2026-06-15": 1379,
+    "2026-06-16": 1317,
+    "2026-06-17": 1170,
+    "2026-06-18": 1408,
+    "2026-06-19": 1350,
+    "2026-06-20": 1437,
+    "2026-06-21": 1426,
+    "2026-06-22": 1350,
+    "2026-06-23": 1468,
+    "2026-06-24": 1635,
+    "2026-06-25": 1640,
+    "2026-06-26": 1338,
+    "2026-06-27": 1338,
+    "2026-06-28": 1028,
+    "2026-06-29": 765,
+    "2026-06-30": 951,
+    "2026-07-01": 1134,
+    "2026-07-02": 593,
+    "2026-07-03": 537,
+    "2026-07-04": 411,
+    "2026-07-05": 485,
+    "2026-07-06": 555,
+    "2026-07-07": 905,
+    "2026-07-08": 1171,
+    "2026-07-09": 1857,
+    "2026-07-10": 1181,
+    "2026-07-11": 2185,
+    "2026-07-12": 1917,
+    "2026-07-13": 2102,
+    "2026-07-14": 2337,
+    "2026-07-15": 2362,
+    "2026-07-16": 2497,
+    "2026-07-17": 1773,
+    "2026-07-18": 1542,
+    "2026-07-19": 1445,
+    "2026-07-20": 1481,
+    "2026-07-21": 1528,
+    "2026-07-22": 1529,
+    "2026-07-23": 1209,
+    "2026-07-24": 1118,
+    "2026-07-25": 928,
+    "2026-07-26": 740,
+    "2026-07-27": 799,
+    "2026-07-28": 665,
+    "2026-07-29": 745,
+    "2026-07-30": 591,
+    "2026-07-31": 783,
+    "2026-08-01": 567,
+    "2026-08-02": 1248,
+    "2026-08-03": 724,
+    "2026-08-04": 708,
+    "2026-08-05": 647,
+    "2026-08-06": 604,
+    "2026-08-07": 624,
+    "2026-08-08": 706,
+    "2026-08-09": 1076,
+    "2026-08-10": 1060,
+    "2026-08-11": 2182,
+    "2026-08-12": 641,
+    "2026-08-13": 770
   }
 }

.github/workflows/autotag.yml

@@ -0,0 +1,92 @@
+name: Auto-tag on main push
+
+on:
+  push:
+    branches: [main]
+  workflow_dispatch:
+
+permissions:
+  contents: write
+  actions: write
+
+jobs:
+  tag:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+
+      - name: Compute dev version
+        id: version
+        run: |
+          set -euo pipefail
+          # Base version is the next patch above the latest plain release tag
+          # (vX.Y.Z) reachable from HEAD. pyproject.toml no longer carries a
+          # static version (#526 switched it to hatch-vcs), so the release tag
+          # is the source of truth. `.devN`/`.rcN`/`desktop-*` tags are excluded
+          # so they can't be mistaken for the release base.
+          # Any future manual `X.Y.Z` release will outrank every `X.Y.Z.devN`
+          # autotag — PEP 440 sorts dev releases strictly below the final.
+          LATEST_RELEASE=$(git tag --list 'v[0-9]*' --merged HEAD \
+            | grep -E '^v[0-9]+\.[0-9]+\.[0-9]+$' | sort -V | tail -1)
+          if [[ -z "$LATEST_RELEASE" ]]; then
+            echo "::error::No release tag (vX.Y.Z) reachable from HEAD"
+            exit 1
+          fi
+          BASE="${LATEST_RELEASE#v}"
+          MAJOR=$(echo "$BASE" | cut -d. -f1)
+          MINOR=$(echo "$BASE" | cut -d. -f2)
+          PATCH=$(echo "$BASE" | cut -d. -f3 | sed -E 's/[^0-9].*$//')
+          NEXT_PATCH=$((PATCH + 1))
+          BUILD=$(git rev-list --count HEAD)
+          VERSION="${MAJOR}.${MINOR}.${NEXT_PATCH}.dev${BUILD}"
+          TAG="v${VERSION}"
+          echo "version=${VERSION}" >> "$GITHUB_OUTPUT"
+          echo "tag=${TAG}" >> "$GITHUB_OUTPUT"
+          echo "Computed ${TAG} (base=${BASE})"
+
+      - name: Create and push tag
+        id: tag
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          TAG: ${{ steps.version.outputs.tag }}
+        run: |
+          set -euo pipefail
+          if git rev-parse "$TAG" >/dev/null 2>&1; then
+            EXISTING_SHA=$(git rev-parse "$TAG")
+            HEAD_SHA=$(git rev-parse HEAD)
+            if [[ "$EXISTING_SHA" != "$HEAD_SHA" ]]; then
+              echo "::error::Tag $TAG already exists at $EXISTING_SHA but HEAD is $HEAD_SHA"
+              exit 1
+            fi
+            echo "Tag $TAG already exists at HEAD, skipping creation"
+            echo "created=false" >> "$GITHUB_OUTPUT"
+            exit 0
+          fi
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+          git tag "$TAG"
+          git push origin "$TAG"
+          echo "Created and pushed $TAG"
+          echo "created=true" >> "$GITHUB_OUTPUT"
+
+      # Tag pushes made with the default GITHUB_TOKEN do NOT trigger other
+      # workflows (recursion prevention). workflow_dispatch is the documented
+      # exception, so we explicitly dispatch the downstream CD workflows here.
+      # See: https://docs.github.com/en/actions/security-guides/automatic-token-authentication
+      - name: Dispatch downstream workflows
+        if: steps.tag.outputs.created == 'true'
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          TAG: ${{ steps.version.outputs.tag }}
+        run: |
+          set -euo pipefail
+          echo "Dispatching pypi-publish.yml @ ${TAG}"
+          gh workflow run pypi-publish.yml \
+            --ref "${TAG}" \
+            -f tag="${TAG}"
+          echo "Dispatching desktop.yml @ ${TAG}"
+          gh workflow run desktop.yml \
+            --ref "${TAG}" \
+            -f tag="${TAG}"

.github/workflows/ci.yml

@@ -23,6 +23,8 @@ jobs:
 
       - name: Install uv
         uses: astral-sh/setup-uv@v8.0.0
+        with:
+          enable-cache: true
 
       - name: Install dependencies
         run: uv sync --extra dev --extra framework-comparison --extra server
@@ -30,6 +32,9 @@ jobs:
       - name: Ruff check
         run: uv run ruff check src/ tests/
 
+      - name: Ruff format check
+        run: uv run ruff format --check src/ tests/
+
   test:
     runs-on: ubuntu-latest
     steps:
@@ -55,6 +60,8 @@ jobs:
 
       - name: Install uv
         uses: astral-sh/setup-uv@v8.0.0
+        with:
+          enable-cache: true
 
       - name: Install dependencies
         run: uv sync --extra dev --extra framework-comparison --extra server
@@ -63,8 +70,13 @@ jobs:
         run: uv run maturin develop --manifest-path rust/crates/openjarvis-python/Cargo.toml
 
       - name: Run tests
+        # COVERAGE_CORE=sysmon uses CPython 3.12's sys.monitoring backend,
+        # which is dramatically cheaper than the default C trace function.
+        # -n auto fans the suite out across all runner cores via pytest-xdist.
+        env:
+          COVERAGE_CORE: sysmon
         run: |
-          uv run pytest tests/ -v --tb=short -m "not live and not cloud" \
+          uv run pytest tests/ -n auto -q --tb=short -m "not live and not cloud and not hub" \
             --cov=openjarvis \
             --cov-report=term-missing \
             --cov-report=xml \
@@ -72,12 +84,73 @@ jobs:
 
       - name: Upload coverage report
         if: always()
+        continue-on-error: true
+        timeout-minutes: 5
         uses: actions/upload-artifact@v4
         with:
           name: coverage-xml
           path: coverage.xml
           if-no-files-found: warn
 
+  # Windows job — empirically exercises the platform-specific code paths that
+  # the Ubuntu `test` job can never reach: GlobalMemoryStatusEx RAM detection
+  # (#373) and the cp9xx -> UTF-8 stdout reconfigure (#293). Also the only CI
+  # job that builds + imports the mandatory `openjarvis_rust` PyO3 extension
+  # on Windows. Public repo -> Windows runner minutes are free.
+  #
+  # All `run:` steps use static commands only (no `github.event.*`
+  # 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: ${{ matrix.python-version }}
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v8.0.0
+        with:
+          enable-cache: true
+
+      - name: Install dependencies
+        run: uv sync --extra dev --extra server
+
+      # Pure-Python check — runs before the Rust build so a flaky toolchain
+      # install can never mask the actual RAM-detection verification.
+      - name: Verify Windows RAM detection (#373)
+        shell: bash
+        run: |
+          uv run python -c "from openjarvis.core.config import _total_ram_gb; ram = _total_ram_gb(); print(f'GlobalMemoryStatusEx RAM = {ram} GB'); assert ram > 0, f'Windows RAM detection returned {ram}, expected > 0'"
+
+      - name: Run Windows-specific tests (hardware + CLI)
+        shell: bash
+        run: |
+          uv run pytest tests/hardware/test_hardware_profiles.py tests/cli/test_cli.py -v -m "not live and not cloud"
+
+      - name: Install Rust toolchain
+        uses: dtolnay/rust-toolchain@stable
+
+      - name: Build + import the PyO3 extension on Windows
+        shell: bash
+        run: |
+          uv run maturin develop --manifest-path rust/crates/openjarvis-python/Cargo.toml
+          uv run python -c "import openjarvis_rust; print('openjarvis_rust imports on Windows OK')"
+
+      - name: Smoke-test CLI
+        shell: bash
+        run: |
+          uv run jarvis --version
+
   rust:
     runs-on: ubuntu-latest
     defaults:

.github/workflows/claude-issues.yml

@@ -11,22 +11,33 @@ concurrency:
   group: claude-issues-${{ github.event.issue.number || github.run_id }}
   cancel-in-progress: true
 
+# Least-privilege: only what the issue-fixer job actually needs.
+# id-token (OIDC) is intentionally omitted — claude-code-action@v1 is passed
+# github_token directly, so OIDC is unused here.
 permissions:
   contents: write
   pull-requests: write
   issues: write
-  id-token: write
 
 jobs:
   fix:
     runs-on: ubuntu-latest
-    timeout-minutes: 60
+    timeout-minutes: 15
+    # Security gate: this job reaches secrets.ANTHROPIC_API_KEY and holds a
+    # write-scoped GITHUB_TOKEN. `issues` / `issue_comment` are public,
+    # attacker-controllable events that run in the base-repo context with full
+    # secret access, so the human-triggered paths are restricted to actors with
+    # write-level association (OWNER / MEMBER / COLLABORATOR). This blocks
+    # external / first-time contributors from draining the API budget or
+    # creating branches/PRs, while leaving maintainer use unaffected.
     if: |
       github.event_name == 'workflow_dispatch' ||
       (github.event_name == 'issues' &&
+       contains(fromJSON('["OWNER", "MEMBER", "COLLABORATOR"]'), github.event.issue.author_association) &&
        (contains(github.event.issue.labels.*.name, 'bug') ||
         contains(github.event.issue.labels.*.name, 'autofix'))) ||
       (github.event_name == 'issue_comment' &&
+       contains(fromJSON('["OWNER", "MEMBER", "COLLABORATOR"]'), github.event.comment.author_association) &&
        !github.event.issue.pull_request &&
        contains(github.event.comment.body, '@claude') &&
        github.actor != 'claude[bot]')

.github/workflows/claude-review.yml

@@ -11,23 +11,33 @@ concurrency:
   group: claude-review-${{ github.event.pull_request.number || github.event.issue.number || github.run_id }}
   cancel-in-progress: true
 
+# Least-privilege: PR review only needs to post comments on the PR.
+# id-token (OIDC) is omitted — claude-code-action@v1 is passed github_token
+# directly, so OIDC is unused here.
 permissions:
   contents: read
   pull-requests: write
   issues: write
-  id-token: write
 
 jobs:
   review:
     runs-on: ubuntu-latest
     timeout-minutes: 30
+    # Security gate: this job reaches secrets.ANTHROPIC_API_KEY. Both
+    # issue_comment and pull_request_review_comment are public,
+    # attacker-controllable events that run in the base-repo context with full
+    # secret access, so the @claude paths are restricted to actors with
+    # write-level association (OWNER / MEMBER / COLLABORATOR). External /
+    # first-time contributors cannot trigger the key; maintainers are unaffected.
     if: |
       github.event_name == 'workflow_dispatch' ||
       (github.event_name == 'issue_comment' &&
+       contains(fromJSON('["OWNER", "MEMBER", "COLLABORATOR"]'), github.event.comment.author_association) &&
        github.event.issue.pull_request &&
        contains(github.event.comment.body, '@claude') &&
        github.actor != 'claude[bot]') ||
       (github.event_name == 'pull_request_review_comment' &&
+       contains(fromJSON('["OWNER", "MEMBER", "COLLABORATOR"]'), github.event.comment.author_association) &&
        contains(github.event.comment.body, '@claude') &&
        github.actor != 'claude[bot]')
     steps:

.github/workflows/desktop.yml

@@ -2,11 +2,8 @@ name: Desktop Build & Release
 
 on:
   push:
-    branches: [main]
-    paths:
-      - 'frontend/**'
-      - '.github/workflows/desktop.yml'
     tags:
+      - 'v*'
       - 'desktop-v*'
   pull_request:
     branches: [main]
@@ -14,9 +11,14 @@ on:
       - 'frontend/**'
       - '.github/workflows/desktop.yml'
   workflow_dispatch:
+    inputs:
+      tag:
+        description: 'Tag to build (e.g. v1.0.2.dev500). If set, autotag dispatches use this. github.ref still controls the checkout.'
+        required: false
+        type: string
 
 concurrency:
-  group: desktop-${{ github.ref }}
+  group: desktop-${{ inputs.tag || github.ref }}
   cancel-in-progress: true
 
 permissions:
@@ -38,7 +40,8 @@ jobs:
             libappindicator3-dev \
             librsvg2-dev \
             patchelf \
-            libxdo-dev
+            libxdo-dev \
+            libdbus-1-dev
 
       - name: Setup Node.js
         uses: actions/setup-node@v6
@@ -64,23 +67,27 @@ jobs:
       - name: Create frontend dist stub
         run: mkdir -p frontend/dist && echo '<html><body></body></html>' > frontend/dist/index.html
 
-      - name: Cargo check
+      # `cargo test` builds the crate (same coverage as the old `cargo check`)
+      # and runs the unit tests, including the #331 uv-sync error-formatting
+      # helpers. Static command, no untrusted input — no injection surface.
+      - name: Cargo test
         working-directory: frontend/src-tauri
-        run: cargo check
+        run: cargo test
 
-  # Remove stale artifacts from the desktop-latest pre-release so that
-  # only the current build's files are available for download.
+  # Remove stale artifacts from the desktop-edge rolling pre-release so that
+  # only the current build's files are available for download. (The stable
+  # `desktop-latest` channel the installed app polls is never cleaned here.)
   clean-release:
     needs: [validate]
     if: github.event_name == 'push' || github.event_name == 'workflow_dispatch'
     runs-on: ubuntu-latest
     steps:
-      - name: Delete old assets from desktop-latest
+      - name: Delete old assets from desktop-edge
         if: "!startsWith(github.ref, 'refs/tags/')"
         env:
           GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
         run: |
-          TAG="desktop-latest"
+          TAG="desktop-edge"
           # List all asset IDs on the release and delete them
           ASSET_IDS=$(gh api "repos/${{ github.repository }}/releases/tags/${TAG}" \
             --jq '.assets[].id' 2>/dev/null || true)
@@ -108,6 +115,109 @@ jobs:
 
     steps:
       - uses: actions/checkout@v6
+        with:
+          # Full history + tags so the workflow_dispatch fallback in
+          # "Determine release info" can derive the dev version from the
+          # latest release tag (#526).
+          fetch-depth: 0
+
+      # Validate Apple credentials BEFORE the expensive work. Notarization is
+      # the very last thing `tauri-action` does, so a bad credential or a
+      # lapsed account agreement previously surfaced ~10 minutes in — after the
+      # Rust toolchain, npm install, two Ollama sidecar downloads and a
+      # universal cargo build — as a single opaque line:
+      #
+      #   failed to bundle project: failed codesign application: failed to
+      #   notarize app: Error: HTTP status code: 403. ...
+      #
+      # `notarytool history` is a read-only call (it submits nothing) that
+      # exercises the identical auth path, so every credential/account failure
+      # mode reaches us here first, in seconds, with the specific cause named.
+      # `xcrun` is preinstalled on macOS runners, hence placement before the
+      # toolchain steps rather than next to "Configure Apple signing".
+      - name: Preflight Apple notarization credentials
+        if: matrix.platform == 'macos-14'
+        env:
+          CERT: ${{ secrets.APPLE_CERTIFICATE }}
+          A_ID: ${{ secrets.APPLE_ID }}
+          A_PASS: ${{ secrets.APPLE_PASSWORD }}
+          A_TEAM: ${{ secrets.APPLE_TEAM_ID }}
+        shell: bash
+        run: |
+          set -uo pipefail
+
+          # Mirror the skip logic in "Configure Apple signing": without a
+          # certificate the build is unsigned and never notarizes, so there is
+          # nothing to preflight. Tag builds still hard-fail there.
+          if [ -z "$CERT" ]; then
+            echo "No Apple certificate configured; skipping notarization preflight."
+            exit 0
+          fi
+
+          missing=""
+          [ -z "$A_ID" ]   && missing="$missing APPLE_ID"
+          [ -z "$A_PASS" ] && missing="$missing APPLE_PASSWORD"
+          [ -z "$A_TEAM" ] && missing="$missing APPLE_TEAM_ID"
+          if [ -n "$missing" ]; then
+            echo "::error::APPLE_CERTIFICATE is set but notarization secrets are missing:$missing"
+            echo "::error::Signing would succeed and notarization would then fail. Set them or clear APPLE_CERTIFICATE."
+            exit 1
+          fi
+
+          # Retry only to absorb transient network faults. Credential and
+          # account errors are deterministic, so we classify and exit on the
+          # first definitive answer rather than retrying into the same wall.
+          attempt=1
+          while [ "$attempt" -le 3 ]; do
+            out=$(xcrun notarytool history \
+              --apple-id "$A_ID" \
+              --team-id "$A_TEAM" \
+              --password "$A_PASS" \
+              --output-format json 2>&1)
+            rc=$?
+
+            if [ $rc -eq 0 ]; then
+              echo "Apple notarization preflight OK — credentials valid, team reachable, agreements in effect."
+              exit 0
+            fi
+
+            case "$out" in
+              *"Invalid credentials"*|*"401"*)
+                echo "::error::Apple notarization preflight failed: invalid credentials (HTTP 401)."
+                echo "::error::APPLE_PASSWORD must be an app-specific password from appleid.apple.com,"
+                echo "::error::generated while signed in as the SAME Apple ID as APPLE_ID. A regular"
+                echo "::error::Apple ID password will not work, and a password minted under a different"
+                echo "::error::Apple ID authenticates as that other account."
+                exit 1
+                ;;
+              *"Invalid or inaccessible developer team ID"*)
+                echo "::error::Apple notarization preflight failed: APPLE_ID is not a member of team APPLE_TEAM_ID (HTTP 403)."
+                echo "::error::The Team ID must match the signing certificate. Read it from the cert's"
+                echo "::error::subject, where it appears as: Developer ID Application: NAME (TEAMID)."
+                echo "::error::If you belong to several teams, confirm APPLE_ID is a member of this one."
+                exit 1
+                ;;
+              *"required agreement"*|*"agreement"*)
+                echo "::error::Apple notarization preflight failed: the team has no in-effect agreement (HTTP 403)."
+                echo "::error::Apple reissues the Developer Program License Agreement periodically and"
+                echo "::error::notarization is refused until it is accepted. ONLY THE ACCOUNT HOLDER can"
+                echo "::error::accept it — team Admins cannot. Sign in to the account that owns this team:"
+                echo "::error::  1. https://developer.apple.com/account -> review any pending agreement"
+                echo "::error::  2. App Store Connect -> Business -> accept anything pending there too"
+                echo "::error::Certificates stay valid while this is outstanding, so signing still works."
+                exit 1
+                ;;
+            esac
+
+            echo "Preflight attempt ${attempt}/3 failed with a non-credential error."
+            echo "$out" | tail -5
+            attempt=$((attempt + 1))
+            [ "$attempt" -le 3 ] && sleep 10
+          done
+
+          echo "::error::Apple notarization preflight failed after 3 attempts. Last output:"
+          echo "$out" | tail -20
+          exit 1
 
       - name: Install system dependencies (Linux)
         if: matrix.platform == 'ubuntu-22.04'
@@ -119,7 +229,8 @@ jobs:
             libappindicator3-dev \
             librsvg2-dev \
             patchelf \
-            libxdo-dev
+            libxdo-dev \
+            libdbus-1-dev
 
       - name: Install Rust stable
         uses: dtolnay/rust-toolchain@stable
@@ -156,14 +267,55 @@ jobs:
         shell: bash
         run: |
           if [[ "${{ github.ref }}" == refs/tags/desktop-v* ]]; then
+            # Explicit stable desktop release tag
+            VERSION="${{ github.ref_name }}"
+            VERSION="${VERSION#desktop-v}"
             echo "tag=${{ github.ref_name }}" >> "$GITHUB_OUTPUT"
             echo "name=Desktop ${{ github.ref_name }}" >> "$GITHUB_OUTPUT"
             echo "prerelease=false" >> "$GITHUB_OUTPUT"
+          elif [[ "${{ github.ref }}" == refs/tags/v* ]]; then
+            # Auto-tagged rolling build from autotag.yml — use the same
+            # version as the CLI/PyPI release so all surfaces stay in sync.
+            # Rolling/dev builds go to the `desktop-edge` channel, NOT the
+            # `desktop-latest` channel the installed app polls — so users on
+            # stable are never auto-updated onto an unvetted dev build.
+            VERSION="${{ github.ref_name }}"
+            VERSION="${VERSION#v}"
+            echo "tag=desktop-edge" >> "$GITHUB_OUTPUT"
+            echo "name=Desktop (Edge Build)" >> "$GITHUB_OUTPUT"
+            echo "prerelease=true" >> "$GITHUB_OUTPUT"
           else
-            echo "tag=desktop-latest" >> "$GITHUB_OUTPUT"
-            echo "name=Desktop (Latest Build)" >> "$GITHUB_OUTPUT"
+            # workflow_dispatch fallback (manual UI dispatch without --ref).
+            # Derive a PEP 440 dev version aligned with autotag.yml so we
+            # don't burn the X.Y.Z release-version namespace.
+            # pyproject.toml no longer carries a static version (#526), so the
+            # base comes from the latest plain release tag (vX.Y.Z), matching
+            # autotag.yml. .dev/.rc/desktop-* tags are excluded.
+            LATEST_RELEASE=$(git tag --list 'v[0-9]*' --merged HEAD \
+              | grep -E '^v[0-9]+\.[0-9]+\.[0-9]+$' | sort -V | tail -1)
+            if [[ -z "$LATEST_RELEASE" ]]; then
+              echo "::error::No release tag (vX.Y.Z) reachable from HEAD"
+              exit 1
+            fi
+            BASE="${LATEST_RELEASE#v}"
+            MAJOR=$(echo "$BASE" | cut -d. -f1)
+            MINOR=$(echo "$BASE" | cut -d. -f2)
+            PATCH=$(echo "$BASE" | cut -d. -f3 | sed -E 's/[^0-9].*$//')
+            NEXT_PATCH=$((PATCH + 1))
+            BUILD=$(git rev-list --count HEAD)
+            VERSION="${MAJOR}.${MINOR}.${NEXT_PATCH}.dev${BUILD}"
+            # Manual dispatches are also dev builds -> the edge channel.
+            echo "tag=desktop-edge" >> "$GITHUB_OUTPUT"
+            echo "name=Desktop (Edge Build)" >> "$GITHUB_OUTPUT"
             echo "prerelease=true" >> "$GITHUB_OUTPUT"
           fi
+          echo "version=${VERSION}" >> "$GITHUB_OUTPUT"
+          # Tauri's build script requires strict SemVer (MAJOR.MINOR.PATCH[-pre][+build]).
+          # PEP 440 dev releases (`1.0.2.dev661`) are NOT valid SemVer, so we
+          # translate `.devN` to the SemVer-equivalent `-dev.N` prerelease form.
+          # PyPI keeps the PEP 440 form; only the Tauri bundle uses SemVer.
+          TAURI_VERSION="${VERSION/.dev/-dev.}"
+          echo "tauri_version=${TAURI_VERSION}" >> "$GITHUB_OUTPUT"
 
       - name: Configure Apple signing
         if: runner.os == 'macOS'
@@ -199,7 +351,11 @@ jobs:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
           TAURI_SIGNING_PRIVATE_KEY: ${{ secrets.TAURI_SIGNING_PRIVATE_KEY }}
           TAURI_SIGNING_PRIVATE_KEY_PASSWORD: ${{ secrets.TAURI_SIGNING_PRIVATE_KEY_PASSWORD }}
-          TAURI_CONFIG: '{"bundle":{"externalBin":["binaries/ollama"]}}'
+          TAURI_CONFIG: '{"version":"${{ steps.release-info.outputs.tauri_version }}","bundle":{"externalBin":["binaries/ollama"]}}'
+          # tauri-action runs beforeBuildCommand (npm run build:tauri -> vite
+          # build), which requires this at build time (#587). Strict for
+          # releases: a missing/empty secret fails the build by design.
+          VITE_SUPABASE_ANON_KEY: ${{ secrets.VITE_SUPABASE_ANON_KEY }}
         with:
           projectPath: frontend
           tauriScript: npx tauri
@@ -210,3 +366,43 @@ jobs:
           prerelease: ${{ steps.release-info.outputs.prerelease }}
           includeUpdaterJson: true
           args: ${{ matrix.args }}
+
+  # When a stable `desktop-v*` release is published, repoint the
+  # `desktop-latest` auto-update channel (the endpoint the installed app
+  # polls) at it. The stable release's own `latest.json` already references
+  # this release's signed assets, so we copy it verbatim — installed apps are
+  # only ever offered vetted stable builds, never `desktop-edge` dev builds.
+  refresh-stable-channel:
+    needs: [build-and-release]
+    if: startsWith(github.ref, 'refs/tags/desktop-v')
+    runs-on: ubuntu-latest
+    steps:
+      - name: Mirror stable latest.json into desktop-latest
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          STABLE_TAG: ${{ github.ref_name }}
+          REPO: ${{ github.repository }}
+        run: |
+          set -euo pipefail
+          # The stable release's updater manifest may take a moment to become
+          # downloadable after tauri-action publishes it; retry briefly.
+          URL="https://github.com/${REPO}/releases/download/${STABLE_TAG}/latest.json"
+          for attempt in 1 2 3 4 5; do
+            if curl -fsSL -o latest.json "$URL"; then
+              echo "Fetched ${STABLE_TAG}/latest.json on attempt ${attempt}"
+              break
+            fi
+            echo "latest.json not ready yet (attempt ${attempt}); sleeping 15s"
+            sleep 15
+          done
+          test -s latest.json || { echo "::error::Could not fetch ${URL}"; exit 1; }
+          # Ensure the channel release exists (prerelease so it never usurps
+          # the stable "Latest" badge), then replace its manifest in place.
+          if ! gh release view desktop-latest --repo "$REPO" >/dev/null 2>&1; then
+            gh release create desktop-latest --repo "$REPO" \
+              --prerelease \
+              --title "Desktop Auto-Update Channel" \
+              --notes "Auto-update channel pointer for the desktop app. Mirrors the latest stable \`desktop-v*\` release; the in-app updater polls this \`latest.json\`. Download the app from the latest stable release, not here."
+          fi
+          gh release upload desktop-latest latest.json --repo "$REPO" --clobber
+          echo "desktop-latest now mirrors ${STABLE_TAG}"

.github/workflows/docs.yml

@@ -41,6 +41,26 @@ jobs:
       - name: Install dependencies
         run: uv sync --extra docs
 
+      # Inject the public Supabase anon key so the savings leaderboard works on
+      # the published docs site. Missing/empty (e.g. fork PRs) leaves the
+      # leaderboard gracefully disabled. The key is read from env (not inlined)
+      # and JSON-encoded into a JS string literal to avoid any injection.
+      - name: Inject leaderboard Supabase anon key
+        env:
+          OPENJARVIS_LEADERBOARD_ANON: ${{ secrets.VITE_SUPABASE_ANON_KEY }}
+        run: |
+          python3 - <<'PY'
+          import json, os, pathlib
+
+          key = os.environ.get("OPENJARVIS_LEADERBOARD_ANON", "")
+          pathlib.Path("docs/javascripts/leaderboard-config.js").write_text(
+              "// Generated at docs-build time from the VITE_SUPABASE_ANON_KEY secret.\n"
+              "window.OPENJARVIS_SUPABASE_ANON_KEY = " + json.dumps(key) + ";\n",
+              encoding="utf-8",
+          )
+          print("leaderboard anon key:", "set" if key else "empty (leaderboard disabled)")
+          PY
+
       - name: Build documentation
         run: uv run mkdocs build
 

.github/workflows/frontend.yml

@@ -35,3 +35,8 @@ jobs:
       - run: npm ci
       - run: npx tsc --noEmit
       - run: npm run build
+        env:
+          # Optional: when the secret is unset the build still succeeds and the
+          # leaderboard is disabled (see src/lib/supabase.ts). No placeholder,
+          # so a keyless CI build doesn't bake in a bogus anon key.
+          VITE_SUPABASE_ANON_KEY: ${{ secrets.VITE_SUPABASE_ANON_KEY }}

.github/workflows/pypi-publish.yml

@@ -7,6 +7,16 @@ on:
     tags:
       - "v*"
   workflow_dispatch:
+    inputs:
+      tag:
+        description: 'Tag to publish (e.g. v1.0.2.dev500). Overrides github.ref.'
+        required: false
+        type: string
+      dry_run:
+        description: 'Dry run: build + validate, then publish to TestPyPI instead of PyPI (no production upload).'
+        required: false
+        default: false
+        type: boolean
 
 permissions:
   contents: read
@@ -17,13 +27,88 @@ jobs:
     runs-on: ubuntu-latest
     environment: pypi
     steps:
+      - name: Resolve target ref
+        id: ref
+        env:
+          INPUT_TAG: ${{ inputs.tag }}
+          DEFAULT_REF: ${{ github.ref_name }}
+        run: |
+          set -euo pipefail
+          if [[ -n "$INPUT_TAG" ]]; then
+            echo "ref=${INPUT_TAG}" >> "$GITHUB_OUTPUT"
+          else
+            echo "ref=${DEFAULT_REF}" >> "$GITHUB_OUTPUT"
+          fi
+
       - uses: actions/checkout@v6
+        with:
+          ref: ${{ steps.ref.outputs.ref }}
 
       - name: Install uv
         uses: astral-sh/setup-uv@v8.0.0
 
+      - name: Setup Node.js
+        uses: actions/setup-node@v6
+        with:
+          node-version: '22'
+          cache: 'npm'
+          cache-dependency-path: frontend/package-lock.json
+
+      - name: Build frontend and bundle into package
+        env:
+          VITE_SUPABASE_ANON_KEY: ${{ secrets.VITE_SUPABASE_ANON_KEY }}
+        run: |
+          set -euo pipefail
+          cd frontend
+          npm ci
+          # Vite is configured (frontend/vite.config.ts) with
+          # `outDir: '../src/openjarvis/server/static'` and
+          # `emptyOutDir: true`, so the build writes directly into the
+          # Python package's static dir and clears stale assets itself.
+          # No rm/cp is needed — and the previous `dist/`-assuming logic
+          # was broken because `frontend/dist/` is never produced.
+          npm run build
+          STATIC=../src/openjarvis/server/static
+          test -s "$STATIC/index.html" || {
+            echo "::error::${STATIC}/index.html missing or empty after build"
+            exit 1
+          }
+
+      - name: Resolve build version from tag
+        env:
+          REF: ${{ steps.ref.outputs.ref }}
+        run: |
+          set -euo pipefail
+          # Strip leading "v" (e.g. v1.0.3.dev825 -> 1.0.3.dev825).
+          VERSION="${REF#v}"
+          if ! [[ "$VERSION" =~ ^[0-9]+\.[0-9]+\.[0-9]+ ]]; then
+            echo "::error::ref '$REF' is not a version tag (expected vX.Y.Z[.devN]); pass -f tag=vX.Y.Z"
+            exit 1
+          fi
+          # pyproject.toml is now dynamic = ["version"] via hatch-vcs (#526), so
+          # there is no static line to sed. setuptools_scm cannot bump custom
+          # `.devN` tags, so we pin the exact build version explicitly — the
+          # published version always equals the pushed tag.
+          echo "SETUPTOOLS_SCM_PRETEND_VERSION=${VERSION}" >> "$GITHUB_ENV"
+          echo "Building version ${VERSION}"
+
       - name: Build package
         run: uv build
 
+      - name: Publish to TestPyPI (dry run)
+        if: ${{ inputs.dry_run }}
+        env:
+          UV_PUBLISH_TOKEN: ${{ secrets.TEST_PYPI_API_TOKEN }}
+        run: |
+          set -euo pipefail
+          if [[ -z "${UV_PUBLISH_TOKEN:-}" ]]; then
+            echo "::warning::TEST_PYPI_API_TOKEN is not set — skipping the TestPyPI upload."
+            echo "Build + twine check passed, which validated version derivation and packaging end to end."
+            echo "To exercise a real upload, add a TEST_PYPI_API_TOKEN secret (or a TestPyPI trusted publisher)."
+            exit 0
+          fi
+          uv publish --publish-url https://test.pypi.org/legacy/
+
       - name: Publish to PyPI
+        if: ${{ !inputs.dry_run }}
         run: uv publish

.gitignore

@@ -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
@@ -48,7 +51,11 @@ Thumbs.db
 *.log
 results/
 logs/
-traces/
+# Anchored to repo root — DO NOT use the unanchored form `traces/`.
+# hatchling honors .gitignore when building the wheel; an unanchored
+# `traces/` pattern matches src/openjarvis/traces/ and silently drops
+# the runtime module from the wheel (issue #372).
+/traces/
 coding_task_*
 get-pip.py
 # Junk from mocked-path tests that write to their mock's __repr__ as a path
@@ -99,6 +106,9 @@ src/openjarvis/channels/whatsapp_baileys_bridge/node_modules/
 # SQLite in-memory artifacts
 :memory:
 
+# Dogfood reports (regenerated locally; not for VCS)
+dogfood_report*.md
+
 # Second Repos
 Inline/
 scratch/
@@ -115,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

CHANGELOG.md

@@ -8,6 +8,151 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ## [Unreleased]
 
+### Added
+
+**Vision input for `jarvis ask`** — attach images to a query with
+`-i`/`--image` (repeatable) or capture the current screen with
+`-S`/`--screen`, for vision-capable models such as `gemma3:4b`. Images flow
+through `Message.images` into Ollama's `/api/chat` `images` field; text-only
+requests are unaffected. A privacy guard warns before any image is sent to a
+non-local engine, and the security guardrail now preserves images when it
+sanitizes a flagged prompt. Screen capture uses the built-in Windows .NET
+stack with `mss`/`Pillow` fallbacks on other platforms. Adds the
+`JARVIS_NUM_CTX` environment variable to tune the Ollama context window
+(default `16384`).
+
+## [1.0.2] - 2026-05-24
+
+A patch release that fixes a packaging bug which broke the v1.0.1
+wheel on PyPI, silences a noisy startup warning, restores a working
+install path while `openjarvis.ai` is down, improves desktop
+first-boot diagnostics on Windows, and ships the RAM-detection fix
+for Windows that missed the v1.0.1 cutoff.
+
+### Fixed
+
+**`openjarvis/traces/` missing from the v1.0.1 PyPI wheel** (#372).
+The `.gitignore` carried an unanchored `traces/` pattern, which
+hatchling honored at wheel-build time and matched the runtime module
+`src/openjarvis/traces/` — silently dropping the whole package. Every
+fresh `pip install openjarvis==1.0.1` then failed at import with
+`ModuleNotFoundError: No module named 'openjarvis.traces'` on the
+first `jarvis ask`, learning, or server call. Anchored the pattern to
+`/traces/`. Verified: a clean `uv build` now produces a wheel
+containing all four `traces/` files.
+
+**`pynvml` deprecation `FutureWarning` on every command** (#389).
+Switched the dependency from the legacy `pynvml` package to NVIDIA's
+official `nvidia-ml-py` (same `pynvml` module name, no warning shim),
+and added defensive `warnings.filterwarnings` at every `import pynvml`
+site to suppress the warning even when `pynvml` is pulled in
+transitively.
+
+**Windows RAM detection returning `0.0 GB`** (#373). The Windows
+branch of `_total_ram_gb()` (via `GlobalMemoryStatusEx`) landed after
+the v1.0.1 cutoff, so v1.0.1 users still saw `0.0 GB` from `jarvis
+init`. Now shipping in the wheel. A new `windows-latest` CI job runs
+the real `GlobalMemoryStatusEx` path on every PR as a regression
+guard.
+
+**Desktop first-boot hung on "did not become healthy in time"**
+(#331). The Tauri boot path ran `uv sync` with stderr discarded and
+the exit code ignored, so a failed dependency install surfaced only
+as a generic 600-second health-check timeout. Now captures stderr,
+checks the exit status, and surfaces the actual `uv sync` error
+(with the diagnostic tail) before the long wait. The error-formatting
+logic is covered by unit tests.
+
+### Changed
+
+**Install URL moved to GitHub Pages** (#337, #352). The documented
+`openjarvis.ai/install.sh` URL was failing with `sslv3 alert
+handshake failure` (the domain is community-operated and had a broken
+TLS config). The canonical installer is now served from the
+project-controlled GitHub Pages site at
+`https://open-jarvis.github.io/OpenJarvis/install.sh`, generated from
+the same `scripts/install/install.sh` at docs-build time. The README
+also documents the WSL2 path for Windows and the `uv` prerequisite
+for the desktop binary, and the installer bails early with a clear
+message when run under Git Bash / MSYS2 / Cygwin.
+
+## [1.0.1] - 2026-05-17
+
+A patch release that closes the auto-update gap so the analytics
+module added in #351 actually reaches users on the desktop, adds
+runtime opt-out for that analytics, fixes the misleading upgrade
+hint the CLI was printing, and lands the ACE optimizer alongside
+DSPy and GEPA.
+
+### Added
+
+**ACE agent optimizer** (`learning/agents/ace_optimizer.py`). Adds
+[ACE](https://github.com/ace-agent/ace) as a third agent-learning
+policy alongside DSPy and GEPA. Where DSPy bootstraps few-shot
+examples and GEPA evolves prompt populations, ACE evolves a textual
+*playbook* of strategies the agent reads at inference time, updated
+by a Generator / Reflector / Curator triad. Pick via
+`[learning.agent] policy = "ace"`. Setup is manual (ACE isn't on
+PyPI and isn't a properly-packaged Python project as of v1.0.1) —
+see `docs/learning/ace.md` for the install path and trace-adapter
+behavior.
+
+**`jarvis self-update`** subcommand. Detects how OpenJarvis was
+installed (pip, uv tool, editable git checkout) by inspecting
+`openjarvis.__file__`, then runs the right upgrade command. Supports
+`--check` (print the command without running) and `-y` (skip the
+confirmation prompt). The post-command "new version available" hint
+now points users at this command instead of guessing at the right
+flow.
+
+**Desktop auto-update endpoint wired to the rolling
+`desktop-latest` GitHub release.** The Tauri updater plugin was
+configured on the build side (`createUpdaterArtifacts: true`,
+`includeUpdaterJson: true`, signing key in `TAURI_SIGNING_PRIVATE_KEY`)
+but inert on the runtime side (`active: false`, `endpoints: []`). The
+installed desktop app would never check. Both are now fixed; the app
+polls `releases/download/desktop-latest/latest.json` every 30 minutes
+and signature-verifies downloads against the minisign pubkey baked
+into the app. Full flow, key-rotation runbook, and dev escape hatch
+(`OPENJARVIS_NO_UPDATER=1`) documented in `docs/desktop-auto-update.md`.
+
+**Analytics env-var opt-out** (`DO_NOT_TRACK`, `OPENJARVIS_NO_ANALYTICS`).
+Tanvir's analytics module (#351) only respected the
+`[analytics] enabled` config-file setting. Both env vars are now
+honored in `is_analytics_enabled()` and in the install.sh beacon
+script. Any truthy value (`1`, `true`, `yes`, `on`) disables for
+that process; env opt-out takes precedence over the config file.
+Documented under a new "Opting out" section in `docs/telemetry.md`.
+
+### Changed
+
+**Version-check trigger widened.** The "new version available" hint
+in `_version_check.py` used to fire only on `{ask, chat, serve}` and
+hardcoded the wrong upgrade command (`git pull && uv sync` — only
+correct for editable installs). Now fires on every interactive
+command (`doctor`, `init`, `quickstart`, `model`, `agents`, `skill`,
+`memory`, `bench`, `telemetry`, `config`, `eval`, `optimize`, plus
+the original three) and uses install-detection to print the right
+upgrade command. Honors `JARVIS_NO_UPDATE_CHECK=1` and `CI=true` to
+stay silent in automation.
+
+**Desktop app version bumped 0.1.0 → 1.0.1** across
+`tauri.conf.json`, `frontend/package.json`, and
+`frontend/src-tauri/Cargo.toml` so the Python and desktop release
+streams are aligned and the auto-updater has a real version to
+compare against.
+
+### Migration from 1.0.0
+
+- **Importing `is_analytics_enabled`?** Same signature; behavior now
+  short-circuits on env opt-out before checking the config. Callers
+  that want the raw "is the config flag set" semantic should read
+  `cfg.enabled` directly.
+- **Editable-git users running `jarvis self-update`** get the
+  detected `git pull && uv sync` command pointed at their actual
+  checkout, not `~/OpenJarvis`. If you'd come to rely on the
+  hardcoded path, update your muscle memory.
+
 ## [1.0.0] - 2026-05-15
 
 The five-primitive architecture (Intelligence, Engine, Agents,

Makefile

@@ -0,0 +1,19 @@
+.PHONY: setup build test lint format
+
+# Mirrors .github/workflows/ci.yml so `make test` matches CI locally.
+
+setup:
+	uv sync --extra dev --extra framework-comparison --extra server
+
+build:
+	uv run maturin develop --manifest-path rust/crates/openjarvis-python/Cargo.toml
+
+test: build
+	uv run pytest tests/ -n auto -q --tb=short -m "not live and not cloud and not hub"
+
+lint:
+	uv run ruff check src/ tests/
+	uv run ruff format --check src/ tests/
+
+format:
+	uv run ruff format src/ tests/

README.md

@@ -4,19 +4,29 @@
   <p><i>Personal AI, On Personal Devices.</i></p>
 
   <p>
-    <a href="https://scalingintelligence.stanford.edu/blogs/openjarvis/"><img src="https://img.shields.io/badge/project-OpenJarvis-blue" alt="Project"></a>
+    <a href="https://arxiv.org/abs/2605.17172"><img src="https://img.shields.io/badge/arXiv-2605.17172-b31b1b.svg" alt="arXiv"></a>
+    <a href="https://openjarvis.stanford.edu/"><img src="https://img.shields.io/badge/project-OpenJarvis-blue" alt="Project"></a>
     <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/)**
+> **[Project Site](https://openjarvis.stanford.edu/)**
+>
+> **[Paper](https://arxiv.org/abs/2605.17172)**
 >
 > **[Leaderboard](https://open-jarvis.github.io/OpenJarvis/leaderboard/)**
 >
@@ -26,66 +36,48 @@
 
 Personal AI agents are exploding in popularity, but nearly all of them still route intelligence through cloud APIs. Your "personal" AI continues to depend on someone else's server. At the same time, our [Intelligence Per Watt](https://www.intelligence-per-watt.ai/) research showed that local language models already handle 88.7% of single-turn chat and reasoning queries, with intelligence efficiency improving 5.3× from 2023 to 2025. The models and hardware are increasingly ready. What has been missing is the software stack to make local-first personal AI practical.
 
-OpenJarvis is that stack. It is an opinionated framework for local-first personal AI, built around three core ideas: shared primitives for building on-device agents; evaluations that treat energy, FLOPs, latency, and dollar cost as first-class constraints alongside accuracy; and a learning loop that improves models using local trace data. The goal is simple: make it possible to build personal AI agents that run locally by default, calling the cloud only when truly necessary. OpenJarvis aims to be both a research platform and a production foundation for local AI, in the spirit of PyTorch.
+OpenJarvis is that stack. It is a framework for local-first personal AI, built around three core ideas: shared primitives for building on-device agents; evaluations that treat energy, FLOPs, latency, and dollar cost as first-class constraints alongside accuracy; and a learning loop that improves models using local trace data. The goal is simple: make it possible to build personal AI agents that run locally by default, calling the cloud only when truly necessary. OpenJarvis aims to be both a research platform and a production foundation for local AI, in the spirit of PyTorch.
 
 ## Installation
 
-```bash
-curl -fsSL https://openjarvis.ai/install.sh | bash
-```
+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.
 
-That's it. The installer handles everything: uv, the Python venv, Ollama, and pulling a small starter model. About 3 minutes on a typical broadband connection. Then:
+| 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) |
 
-```bash
-jarvis
-```
+Then `jarvis` to start. The Rust extension and larger models continue downloading in the background; `jarvis doctor` shows status.
 
-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.
-
-**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://openjarvis.ai/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
 
@@ -112,6 +104,8 @@ See the [Skills User Guide](https://open-jarvis.github.io/OpenJarvis/user-guide/
 
 ### Built-in Agents
 
+OpenJarvis ships with eight built-in agents across three execution modes (on-demand, scheduled, continuous):
+
 | Agent | Type | What it does |
 |-------|------|-------------|
 | `morning_digest` | Scheduled | Daily briefing from email, calendar, health, news — with TTS audio |
@@ -127,6 +121,13 @@ See the [User Guide](https://open-jarvis.github.io/OpenJarvis/user-guide/morning
 
 Full documentation — including Docker deployment, cloud engines, development setup, and tutorials — at **[open-jarvis.github.io/OpenJarvis](https://open-jarvis.github.io/OpenJarvis/)**.
 
+## Community
+
+- **GitHub:** [github.com/open-jarvis/OpenJarvis](https://github.com/open-jarvis/OpenJarvis)
+- **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/)
+
 ## Contributing
 
 We welcome contributions! See the [Contributing Guide](CONTRIBUTING.md) for incentives, contribution types, and the PR process.
@@ -145,7 +146,7 @@ Browse the [Roadmap](https://open-jarvis.github.io/OpenJarvis/development/roadma
 
 ## About
 
-OpenJarvis is part of [Intelligence Per Watt](https://www.intelligence-per-watt.ai/), a research initiative studying the efficiency of on-device AI systems. The project is developed at [Hazy Research](https://hazyresearch.stanford.edu/) and the [Scaling Intelligence Lab](https://scalingintelligence.stanford.edu/) at [Stanford SAIL](https://ai.stanford.edu/).
+OpenJarvis is part of [Intelligence Per Watt](https://www.intelligence-per-watt.ai/), a research initiative studying the intelligence efficiency of AI systems. The project is developed at [Hazy Research](https://hazyresearch.stanford.edu/) and the [Scaling Intelligence Lab](https://scalingintelligence.stanford.edu/) at [Stanford SAIL](https://ai.stanford.edu/).
 
 ## Sponsors
 
@@ -161,11 +162,14 @@ OpenJarvis is part of [Intelligence Per Watt](https://www.intelligence-per-watt.
 
 ## Citation
 ```bibtex
-@misc{saadfalcon2026openjarvis,
-  title={OpenJarvis: Personal AI, On Personal Devices},
-  author={Jon Saad-Falcon and Avanika Narayan and Herumb Shandilya and Hakki Orhun Akengin and Robby Manihani and Gabriel Bo and John Hennessy and Christopher R\'{e} and Azalia Mirhoseini},
-  year={2026},
-  howpublished={\url{https://scalingintelligence.stanford.edu/blogs/openjarvis/}},
+@misc{saadfalcon2026openjarvispersonalaipersonal,
+      title={OpenJarvis: Personal AI, On Personal Devices}, 
+      author={Jon Saad-Falcon and Avanika Narayan and Robby Manihani and Tanvir Bhathal and Herumb Shandilya and Hakki Orhun Akengin and Gabriel Bo and Andrew Park and Matthew Hart and Caia Costello and Chuan Li and Christopher Ré and Azalia Mirhoseini},
+      year={2026},
+      eprint={2605.17172},
+      archivePrefix={arXiv},
+      primaryClass={cs.LG},
+      url={https://arxiv.org/abs/2605.17172}, 
 }
 ```
 

configs/openjarvis/config.toml

@@ -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"

configs/openjarvis/examples/full-system-access.toml

@@ -0,0 +1,39 @@
+# Full system access: unrestricted shell and filesystem
+# Copy to ~/.openjarvis/config.toml
+#
+# WARNING: shell_exec runs arbitrary commands as your user. No command
+# allowlist, no denylist, no working-directory restriction. file_read and
+# file_write aren't restricted to any directory either. Only enable what you
+# actually want the agent to have. tools.enabled is the whole permission grant;
+# there's no second allowlist to configure.
+#
+# On macOS, this config alone does not reach TCC-protected data (Messages,
+# Mail, Photos, Safari). That requires Full Disk Access granted to the process
+# hosting the backend. See docs/user-guide/system-access.md.
+#
+# Usage:
+#   jarvis ask "What's using the most disk space in my home directory?"
+#   jarvis chat        # prompts before each shell_exec call
+
+[engine]
+default = "ollama"
+
+[intelligence]
+default_model = "qwen3.5:9b"
+
+[agent]
+default_agent = "orchestrator"
+max_turns = 10
+
+[tools]
+enabled = [
+    "shell_exec",
+    "file_read",
+    "file_write",
+    "apply_patch",
+    "code_interpreter",
+    "git_status",
+    "git_diff",
+    "think",
+    "calculator",
+]

deploy/docker/.env.example

@@ -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=

deploy/docker/Dockerfile

@@ -1,32 +1,83 @@
+# Base images are pinned to an immutable digest (in addition to a human-readable
+# tag) so every build resolves the exact same layers — reproducible builds and
+# safe rollbacks (#563).
+
 # Stage 1: Build frontend SPA
-FROM node:22-slim AS frontend
+FROM node:22.23.0-slim@sha256:d9f850096136edbc402debdd8729579a288aac64574ada0ff4db26b6ae58b0b2 AS frontend
+# Public Supabase anon key for the savings leaderboard; empty by default so
+# the image's leaderboard stays disabled (#589). Pass --build-arg to enable.
+ARG OPENJARVIS_LEADERBOARD_PUBLIC_ANON=
 
 WORKDIR /frontend
 COPY frontend/package.json frontend/package-lock.json* ./
 RUN npm ci --ignore-scripts 2>/dev/null || npm install
 COPY frontend/ .
-RUN npm run build
+RUN VITE_SUPABASE_ANON_KEY="${OPENJARVIS_LEADERBOARD_PUBLIC_ANON}" npm run build
 
 # Stage 2: Build Python package
-FROM python:3.12-slim-bookworm AS builder
+FROM python:3.12.13-slim-bookworm@sha256:76d4b7b6305788c6b4c6a19d6a22a3921bf802e9af4d5e1e5bd771208dba74bf AS builder
+
+RUN apt-get update && \
+    apt-get install -y --no-install-recommends build-essential ca-certificates curl && \
+    rm -rf /var/lib/apt/lists/*
+
+ENV PATH="/root/.cargo/bin:${PATH}"
+
+RUN curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | \
+        sh -s -- -y --profile minimal --default-toolchain none && \
+    rustup toolchain install 1.88 --profile minimal && \
+    rustup default 1.88
 
 WORKDIR /app
-COPY pyproject.toml README.md ./
+
+# Install dependencies from the committed lockfile (#567). `uv export --frozen`
+# reads uv.lock as-is (no re-resolution) and emits a fully pinned, hash-verified
+# requirements set; `--no-deps` then installs exactly that set. This is a
+# separate layer from the source copy so dependency installs stay cached when
+# only application code changes.
+COPY pyproject.toml uv.lock README.md ./
+RUN pip install --no-cache-dir uv && \
+    uv export --frozen --no-dev --extra server --no-emit-project > requirements.txt && \
+    uv pip install --system --no-deps -r requirements.txt && \
+    uv pip install --system --no-deps "maturin>=1.12.6,<2"
+
+# Copy the source and the non-src force-include paths (see pyproject
+# [tool.hatch.build.targets.wheel.force-include]) before building the project.
 COPY src/ src/
+COPY rust/ rust/
+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/
 
-RUN pip install --no-cache-dir uv && \
-    uv pip install --system ".[server]"
+# Install the project itself without re-resolving dependencies.
+RUN uv pip install --system --no-deps . && \
+    maturin build --release \
+        --manifest-path rust/crates/openjarvis-python/Cargo.toml \
+        --interpreter python3 \
+        --out /tmp/openjarvis-rust-wheel && \
+    uv pip install --system --no-deps /tmp/openjarvis-rust-wheel/*.whl && \
+    python3 -c "import openjarvis_rust; print('openjarvis_rust ok')" && \
+    python3 -m pip uninstall -y maturin && \
+    rm -rf /tmp/openjarvis-rust-wheel rust
 
 # Stage 3: Runtime
-FROM python:3.12-slim-bookworm
+FROM python:3.12.13-slim-bookworm@sha256:76d4b7b6305788c6b4c6a19d6a22a3921bf802e9af4d5e1e5bd771208dba74bf
 
 COPY --from=builder /usr/local /usr/local
 COPY --from=builder /app /app
 WORKDIR /app
 
+# Run as an unprivileged user — the server needs no root privileges, so dropping
+# them limits the blast radius of a compromise (#565). The app writes only to
+# $HOME (config/cache/state), which is owned by this user.
+RUN groupadd --system --gid 10001 openjarvis && \
+    useradd --system --uid 10001 --gid openjarvis \
+        --create-home --home-dir /home/openjarvis openjarvis
+ENV HOME=/home/openjarvis
+USER openjarvis
+
 EXPOSE 8000
 
 ENTRYPOINT ["jarvis"]

deploy/docker/Dockerfile.gpu

@@ -1,30 +1,69 @@
+# Base images are pinned to an immutable digest (in addition to a human-readable
+# tag) so every build resolves the exact same layers — reproducible builds and
+# safe rollbacks (#563).
+
 # Stage 1: Build frontend SPA
-FROM node:22-slim AS frontend
+FROM node:22.23.0-slim@sha256:d9f850096136edbc402debdd8729579a288aac64574ada0ff4db26b6ae58b0b2 AS frontend
+# Public Supabase anon key for the savings leaderboard; empty by default so
+# the image's leaderboard stays disabled (#589). Pass --build-arg to enable.
+ARG OPENJARVIS_LEADERBOARD_PUBLIC_ANON=
 
 WORKDIR /frontend
 COPY frontend/package.json frontend/package-lock.json* ./
 RUN npm ci --ignore-scripts 2>/dev/null || npm install
 COPY frontend/ .
-RUN npm run build
+RUN VITE_SUPABASE_ANON_KEY="${OPENJARVIS_LEADERBOARD_PUBLIC_ANON}" npm run build
 
 # Stage 2: Build Python package (NVIDIA CUDA 12.4)
-FROM nvidia/cuda:12.4.0-runtime-ubuntu22.04 AS builder
+FROM nvidia/cuda:12.4.0-runtime-ubuntu22.04@sha256:af8bd179ed3bf69d4b63b19a763662a6141f0f62ef099283f68d0b14b4bab0e3 AS builder
 
 RUN apt-get update && \
-    apt-get install -y --no-install-recommends python3 python3-pip python3-venv && \
+    apt-get install -y --no-install-recommends \
+        build-essential \
+        ca-certificates \
+        curl \
+        python3 \
+        python3-dev \
+        python3-pip \
+        python3-venv && \
     rm -rf /var/lib/apt/lists/*
 
+ENV PATH="/root/.cargo/bin:${PATH}"
+
+RUN curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | \
+        sh -s -- -y --profile minimal --default-toolchain none && \
+    rustup toolchain install 1.88 --profile minimal && \
+    rustup default 1.88
+
 WORKDIR /app
-COPY pyproject.toml README.md ./
+
+# Install dependencies from the committed lockfile (#567). See deploy/docker/Dockerfile
+# for the rationale behind the frozen export + --no-deps install.
+COPY pyproject.toml uv.lock README.md ./
+RUN pip install --no-cache-dir uv && \
+    uv export --frozen --no-dev --extra server --no-emit-project > requirements.txt && \
+    uv pip install --system --no-deps -r requirements.txt && \
+    uv pip install --system --no-deps "maturin>=1.12.6,<2"
+
 COPY src/ src/
+COPY rust/ rust/
+COPY scripts/install scripts/install
+COPY deploy/windows deploy/windows
 
 COPY --from=frontend /src/openjarvis/server/static src/openjarvis/server/static/
 
-RUN pip install --no-cache-dir uv && \
-    uv pip install --system ".[server]"
+RUN uv pip install --system --no-deps . && \
+    maturin build --release \
+        --manifest-path rust/crates/openjarvis-python/Cargo.toml \
+        --interpreter python3 \
+        --out /tmp/openjarvis-rust-wheel && \
+    uv pip install --system --no-deps /tmp/openjarvis-rust-wheel/*.whl && \
+    python3 -c "import openjarvis_rust; print('openjarvis_rust ok')" && \
+    python3 -m pip uninstall -y maturin && \
+    rm -rf /tmp/openjarvis-rust-wheel rust
 
 # Stage 3: Runtime
-FROM nvidia/cuda:12.4.0-runtime-ubuntu22.04
+FROM nvidia/cuda:12.4.0-runtime-ubuntu22.04@sha256:af8bd179ed3bf69d4b63b19a763662a6141f0f62ef099283f68d0b14b4bab0e3
 
 RUN apt-get update && \
     apt-get install -y --no-install-recommends python3 python3-pip && \
@@ -34,6 +73,14 @@ COPY --from=builder /usr/local /usr/local
 COPY --from=builder /app /app
 WORKDIR /app
 
+# Run as an unprivileged user (#565). NVIDIA device nodes (/dev/nvidia*) are
+# world-accessible, so GPU workloads do not require root.
+RUN groupadd --system --gid 10001 openjarvis && \
+    useradd --system --uid 10001 --gid openjarvis \
+        --create-home --home-dir /home/openjarvis openjarvis
+ENV HOME=/home/openjarvis
+USER openjarvis
+
 EXPOSE 8000
 
 ENTRYPOINT ["jarvis"]

deploy/docker/Dockerfile.gpu.rocm

@@ -1,30 +1,69 @@
+# Base images are pinned to an immutable digest (in addition to a human-readable
+# tag) so every build resolves the exact same layers — reproducible builds and
+# safe rollbacks (#563).
+
 # Stage 1: Build frontend SPA
-FROM node:22-slim AS frontend
+FROM node:22.23.0-slim@sha256:d9f850096136edbc402debdd8729579a288aac64574ada0ff4db26b6ae58b0b2 AS frontend
+# Public Supabase anon key for the savings leaderboard; empty by default so
+# the image's leaderboard stays disabled (#589). Pass --build-arg to enable.
+ARG OPENJARVIS_LEADERBOARD_PUBLIC_ANON=
 
 WORKDIR /frontend
 COPY frontend/package.json frontend/package-lock.json* ./
 RUN npm ci --ignore-scripts 2>/dev/null || npm install
 COPY frontend/ .
-RUN npm run build
+RUN VITE_SUPABASE_ANON_KEY="${OPENJARVIS_LEADERBOARD_PUBLIC_ANON}" npm run build
 
 # Stage 2: Build Python package (AMD ROCm 7.2)
-FROM rocm/dev-ubuntu-22.04:7.2 AS builder
+FROM rocm/dev-ubuntu-22.04:7.2@sha256:05af5f04a06b04676d4c7438997d0deadaeb7478961ad621376e199bf3aeb644 AS builder
 
 RUN apt-get update && \
-    apt-get install -y --no-install-recommends python3 python3-pip python3-venv && \
+    apt-get install -y --no-install-recommends \
+        build-essential \
+        ca-certificates \
+        curl \
+        python3 \
+        python3-dev \
+        python3-pip \
+        python3-venv && \
     rm -rf /var/lib/apt/lists/*
 
+ENV PATH="/root/.cargo/bin:${PATH}"
+
+RUN curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | \
+        sh -s -- -y --profile minimal --default-toolchain none && \
+    rustup toolchain install 1.88 --profile minimal && \
+    rustup default 1.88
+
 WORKDIR /app
-COPY pyproject.toml README.md ./
+
+# Install dependencies from the committed lockfile (#567). See deploy/docker/Dockerfile
+# for the rationale behind the frozen export + --no-deps install.
+COPY pyproject.toml uv.lock README.md ./
+RUN pip install --no-cache-dir uv && \
+    uv export --frozen --no-dev --extra server --no-emit-project > requirements.txt && \
+    uv pip install --system --no-deps -r requirements.txt && \
+    uv pip install --system --no-deps "maturin>=1.12.6,<2"
+
 COPY src/ src/
+COPY rust/ rust/
+COPY scripts/install scripts/install
+COPY deploy/windows deploy/windows
 
 COPY --from=frontend /src/openjarvis/server/static src/openjarvis/server/static/
 
-RUN pip install --no-cache-dir uv && \
-    uv pip install --system ".[server]"
+RUN uv pip install --system --no-deps . && \
+    maturin build --release \
+        --manifest-path rust/crates/openjarvis-python/Cargo.toml \
+        --interpreter python3 \
+        --out /tmp/openjarvis-rust-wheel && \
+    uv pip install --system --no-deps /tmp/openjarvis-rust-wheel/*.whl && \
+    python3 -c "import openjarvis_rust; print('openjarvis_rust ok')" && \
+    python3 -m pip uninstall -y maturin && \
+    rm -rf /tmp/openjarvis-rust-wheel rust
 
 # Stage 3: Runtime
-FROM rocm/dev-ubuntu-22.04:7.2
+FROM rocm/dev-ubuntu-22.04:7.2@sha256:05af5f04a06b04676d4c7438997d0deadaeb7478961ad621376e199bf3aeb644
 
 RUN apt-get update && \
     apt-get install -y --no-install-recommends python3 python3-pip && \
@@ -34,6 +73,18 @@ COPY --from=builder /usr/local /usr/local
 COPY --from=builder /app /app
 WORKDIR /app
 
+# Run as an unprivileged user (#565). ROCm GPU access is gated by the `video` and
+# `render` groups (see group_add in docker-compose.gpu.rocm.yml), so the user is
+# added to both; root is not required.
+RUN groupadd --system --gid 10001 openjarvis && \
+    useradd --system --uid 10001 --gid openjarvis \
+        --create-home --home-dir /home/openjarvis openjarvis && \
+    (getent group video  >/dev/null || groupadd --system video) && \
+    (getent group render >/dev/null || groupadd --system render) && \
+    usermod -aG video,render openjarvis
+ENV HOME=/home/openjarvis
+USER openjarvis
+
 EXPOSE 8000
 
 ENTRYPOINT ["jarvis"]

deploy/docker/Dockerfile.sandbox

@@ -1,15 +1,69 @@
-FROM python:3.12-slim
+# Base images are pinned to an immutable digest (in addition to a human-readable
+# tag) so every build resolves the exact same layers (#563).
 
-# Install Node.js 22
-RUN apt-get update && apt-get install -y --no-install-recommends \
-    curl ca-certificates && \
-    curl -fsSL https://deb.nodesource.com/setup_22.x | bash - && \
-    apt-get install -y nodejs && \
+# Node.js is sourced from the official, digest-pinned image rather than piping a
+# remote setup script into bash (`curl ... | bash -`), which performed no
+# checksum or signature verification of the downloaded installer (#566). The
+# image digest is the integrity check, and the copy is architecture-agnostic.
+FROM node:22.23.0-slim@sha256:d9f850096136edbc402debdd8729579a288aac64574ada0ff4db26b6ae58b0b2 AS node
+
+FROM python:3.12.13-slim-bookworm@sha256:76d4b7b6305788c6b4c6a19d6a22a3921bf802e9af4d5e1e5bd771208dba74bf AS builder
+
+RUN apt-get update && \
+    apt-get install -y --no-install-recommends build-essential ca-certificates curl && \
     rm -rf /var/lib/apt/lists/*
 
+ENV PATH="/root/.cargo/bin:${PATH}"
+
+RUN curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | \
+        sh -s -- -y --profile minimal --default-toolchain none && \
+    rustup toolchain install 1.88 --profile minimal && \
+    rustup default 1.88
+
 WORKDIR /app
+
+# Install dependencies from the committed lockfile (#567): `uv export --frozen`
+# reads uv.lock as-is and emits a pinned, hash-verified set installed with
+# --no-deps (no re-resolution). Copied first so this layer caches independently
+# of application source.
+COPY pyproject.toml uv.lock README.md ./
+RUN pip install --no-cache-dir uv && \
+    uv export --frozen --no-dev --extra server --no-emit-project > requirements.txt && \
+    uv pip install --system --no-deps -r requirements.txt && \
+    uv pip install --system --no-deps "maturin>=1.12.6,<2"
+
 COPY . .
-RUN pip install --no-cache-dir ".[server]"
+
+# Install the project itself without re-resolving dependencies.
+RUN uv pip install --system --no-deps . && \
+    maturin build --release \
+        --manifest-path rust/crates/openjarvis-python/Cargo.toml \
+        --interpreter python3 \
+        --out /tmp/openjarvis-rust-wheel && \
+    uv pip install --system --no-deps /tmp/openjarvis-rust-wheel/*.whl && \
+    python3 -c "import openjarvis_rust; print('openjarvis_rust ok')" && \
+    python3 -m pip uninstall -y maturin && \
+    rm -rf /tmp/openjarvis-rust-wheel rust/target
+
+FROM python:3.12.13-slim-bookworm@sha256:76d4b7b6305788c6b4c6a19d6a22a3921bf802e9af4d5e1e5bd771208dba74bf
+
+# libstdc++6 + ca-certificates are the only runtime requirements of the Node
+# binary copied below (the python slim image already provides libc/libgcc).
+RUN apt-get update && \
+    apt-get install -y --no-install-recommends ca-certificates libstdc++6 && \
+    rm -rf /var/lib/apt/lists/*
+
+COPY --from=builder /usr/local /usr/local
+COPY --from=builder /app /app
+
+# Transplant the Node.js runtime from the official image. Both images are Debian
+# bookworm, so the glibc/libstdc++ ABI matches.
+COPY --from=node /usr/local/bin/node /usr/local/bin/node
+COPY --from=node /usr/local/lib/node_modules /usr/local/lib/node_modules
+RUN ln -sf /usr/local/lib/node_modules/npm/bin/npm-cli.js /usr/local/bin/npm && \
+    ln -sf /usr/local/lib/node_modules/npm/bin/npx-cli.js /usr/local/bin/npx
+
+WORKDIR /app
 
 LABEL openjarvis-sandbox=true
 

deploy/docker/docker-compose.gpu.nvidia.yml

@@ -18,7 +18,9 @@ services:
               capabilities: [gpu]
 
   ollama:
-    image: ollama/ollama:latest
+    # Pinned to a fixed version + digest for reproducible deployments (#563);
+    # must match the tag in docker-compose.yml.
+    image: ollama/ollama:0.30.10@sha256:bfc9c6d53cc6989aa5131a6fde6b162b2802d4d337657f3253b5f69579bddeee
     environment:
       - NVIDIA_VISIBLE_DEVICES=all
       - NVIDIA_DRIVER_CAPABILITIES=compute,utility

deploy/docker/docker-compose.yml

@@ -8,13 +8,19 @@ 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
     restart: unless-stopped
 
   ollama:
-    image: ollama/ollama:latest
+    # Pinned to a fixed version + digest for reproducible deployments and
+    # predictable rollbacks (#563). Bump deliberately, not implicitly via :latest.
+    image: ollama/ollama:0.30.10@sha256:bfc9c6d53cc6989aa5131a6fde6b162b2802d4d337657f3253b5f69579bddeee
     ports:
       - "11434:11434"
     volumes:

deploy/launchd/com.openjarvis.plist

@@ -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>

deploy/posthog/posthog-hetzner-prep.sh

@@ -0,0 +1,142 @@
+#!/usr/bin/env bash
+# posthog-hetzner-prep.sh — one-shot Hetzner Cloud server prep for
+# OpenJarvis's self-hosted PostHog analytics backend.
+#
+# Run this on a fresh Ubuntu 22.04+ box (Hetzner CCX23 in Ashburn, or
+# similar) after pointing the desired domain at it. Idempotent: safe
+# to re-run if a step fails partway.
+#
+# Usage:
+#   sudo bash posthog-hetzner-prep.sh analytics.openjarvis.ai you@openjarvis.ai
+#
+# After it finishes:
+#   1. Visit https://<DOMAIN>/ and create the admin account.
+#   2. Create project "OpenJarvis".
+#   3. Settings → Project → grab the Project API Key (phc_…).
+#   4. Update src/openjarvis/core/config.py AnalyticsConfig defaults:
+#        host = "https://<DOMAIN>"
+#        key  = "phc_<new>"
+#   5. Ship a release. Frontend + backend + install.sh all read those
+#      same defaults via load_config().
+#
+# Cost: ~$35/mo on Hetzner CCX23 (4 dedicated vCPU / 16 GB / 240 GB
+# NVMe) in US-East. Add Hetzner Cloud Backups (+20%) for production.
+#
+# Retention: post-install, set 365 days in PostHog UI →
+#   Settings → Data Management → Event ingestion → Data retention.
+
+set -euo pipefail
+
+# ---- args ----
+if [[ $# -lt 2 ]]; then
+    cat >&2 <<'USAGE'
+posthog-hetzner-prep.sh: missing arguments.
+
+Usage:
+  sudo bash posthog-hetzner-prep.sh <domain> <admin_email>
+
+Examples:
+  sudo bash posthog-hetzner-prep.sh analytics.openjarvis.ai team@openjarvis.ai
+
+The domain must already resolve to this box (DNS A record) before
+the script runs — Let's Encrypt needs to reach this server on port 80.
+USAGE
+    exit 2
+fi
+
+DOMAIN="$1"
+ADMIN_EMAIL="$2"
+
+if [[ $EUID -ne 0 ]]; then
+    echo "posthog-hetzner-prep.sh: must be run as root (use sudo)." >&2
+    exit 1
+fi
+
+# ---- step 1: system prep ----
+echo "[1/5] apt update + base packages..."
+export DEBIAN_FRONTEND=noninteractive
+apt-get update -y
+apt-get install -y --no-install-recommends \
+    curl ufw ca-certificates gnupg \
+    apt-transport-https software-properties-common
+
+# ---- step 2: firewall ----
+echo "[2/5] firewall (UFW): 22/80/443 only..."
+ufw --force reset
+ufw default deny incoming
+ufw default allow outgoing
+ufw allow 22/tcp
+ufw allow 80/tcp
+ufw allow 443/tcp
+ufw --force enable
+
+# ---- step 3: swap (helps ClickHouse under load spikes) ----
+echo "[3/5] swap..."
+if [[ ! -f /swapfile ]]; then
+    fallocate -l 4G /swapfile
+    chmod 600 /swapfile
+    mkswap /swapfile
+    swapon /swapfile
+    if ! grep -q "/swapfile" /etc/fstab; then
+        echo "/swapfile none swap sw 0 0" >> /etc/fstab
+    fi
+else
+    echo "    /swapfile already present"
+fi
+
+# ---- step 4: docker ----
+echo "[4/5] docker..."
+if ! command -v docker >/dev/null 2>&1; then
+    curl -fsSL https://get.docker.com | sh
+else
+    echo "    docker already installed"
+fi
+systemctl enable --now docker
+
+# ---- step 5: posthog hobby deploy ----
+echo "[5/5] PostHog Hobby Deploy..."
+echo
+echo "    Domain:        $DOMAIN"
+echo "    Admin email:   $ADMIN_EMAIL"
+echo "    DNS A record:  verify it points to $(curl -fsS -m 5 https://api.ipify.org 2>/dev/null || echo "<this server>")"
+echo
+
+# PostHog's official one-liner. It writes a .env file with random
+# secrets, configures Caddy with Let's Encrypt TLS for the domain,
+# and brings up the full stack via docker-compose.
+/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/posthog/posthog/HEAD/bin/deploy-hobby)" -s -- \
+    --domain "$DOMAIN" \
+    --email "$ADMIN_EMAIL" || {
+    echo
+    echo "PostHog deploy script exited with an error. Common causes:"
+    echo "  - DNS for $DOMAIN doesn't resolve to this server yet (wait + retry)"
+    echo "  - Port 80 not reachable from the public internet (firewall / cloud SG)"
+    echo "  - Out of disk on /var/lib/docker (need 20+ GB free)"
+    echo
+    exit 1
+}
+
+cat <<EOF
+
+================================================================
+PostHog is up at https://$DOMAIN/
+
+Next steps:
+  1. Open https://$DOMAIN/ in a browser.
+  2. Create the first admin account (any email, your password).
+  3. Create project "OpenJarvis".
+  4. Settings → Project → Project API Key — copy the phc_… value.
+  5. Update src/openjarvis/core/config.py AnalyticsConfig defaults:
+        host = "https://$DOMAIN"
+        key  = "phc_<the-new-key>"
+  6. Settings → Data Management → set retention to 365 days.
+  7. Settings → Recordings → confirm Session Replay is OFF (default).
+  8. Ship a release of OpenJarvis with the new config defaults.
+
+Operational notes:
+  - Updates:    bash <(curl -fsSL https://raw.githubusercontent.com/posthog/posthog/HEAD/bin/upgrade-hobby)
+  - Logs:       docker compose -f /home/posthog/posthog/docker-compose.hobby.yml logs -f
+  - Disk usage: df -h          # bump VPS tier when /var/lib/docker > 70% full
+  - Backups:    enable Hetzner Cloud Backups in the Hetzner console
+================================================================
+EOF

deploy/systemd/openjarvis.service

@@ -10,6 +10,31 @@ 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.
+# Keep secrets here (mode 0600, owned by root) rather than inline Environment=
+# lines, which leak into `systemctl show` and the journal.
+EnvironmentFile=/etc/openjarvis/env
+
+# --- Sandboxing / hardening (#564) ---
+# Conservative set: tightens the unit without blocking the server's normal I/O
+# or local GPU inference. ProtectSystem=strict makes the whole filesystem
+# read-only except ReadWritePaths, so $HOME (config/cache/state under
+# /opt/openjarvis) stays writable.
+NoNewPrivileges=true
+ProtectSystem=strict
+ReadWritePaths=/opt/openjarvis
+ProtectHome=true
+PrivateTmp=true
+ProtectControlGroups=true
+ProtectKernelLogs=true
+ProtectKernelModules=true
+ProtectKernelTunables=true
+RestrictRealtime=true
+RestrictSUIDSGID=true
+LockPersonality=true
 
 [Install]
 WantedBy=multi-user.target

deploy/windows/README.md

@@ -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 desktop --group desktop-native` so the FastAPI server,
+   speech backend, and native extension are 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 desktop --group desktop-native
+```
+
+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).

deploy/windows/install.ps1

@@ -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 desktop --group desktop-native` so the FastAPI
+         server, speech backend, and native extension are 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 desktop --group desktop-native
+# ---------------------------------------------------------------------------
+
+Write-Info "Running 'uv sync --extra desktop --group desktop-native' in $srcDir (this can take a few minutes)..."
+Push-Location $srcDir
+try {
+    & $uvExe sync --extra desktop --group desktop-native
+    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 ""

deploy/windows/jarvis-service.ps1

@@ -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 }
+}

docs/architecture/engine.md

@@ -116,7 +116,7 @@ All providers produce the same output format consumed by agents:
 | **LM Studio** | `lmstudio` | OpenAI-compatible | 1234 | No (GPU optional) | Desktop GUI, easy model management |
 | **Exo** | `exo` | OpenAI-compatible | 52415 | No (distributed) | Distributed inference across heterogeneous devices |
 | **Nexa** | `nexa` | OpenAI-compatible | 18181 | No (CPU/GPU) | On-device inference with GGUF models |
-| **Lemonade** | `lemonade` | OpenAI-compatible | 8000 | AMD GPU/NPU | AMD consumer GPUs (RDNA), Ryzen AI NPUs |
+| **Lemonade** | `lemonade` | OpenAI-compatible | 13305 | AMD GPU/NPU | AMD consumer GPUs (RDNA), Ryzen AI NPUs |
 | **Uzu** | `uzu` | OpenAI-compatible | 8000 | Varies | Uzu inference runtime |
 | **Apple FM** | `apple_fm` | OpenAI-compatible | 8079 | Apple Silicon | Apple Foundation Model on-device inference |
 | **LiteLLM** | `litellm` | OpenAI-compatible | — | No | Unified proxy to 100+ LLM providers |
@@ -135,7 +135,7 @@ The Ollama backend communicates via Ollama's native HTTP API at `/api/chat` and
 
 The vLLM backend uses the OpenAI-compatible `/v1/chat/completions` API. It is recommended for datacenter GPUs (NVIDIA A100, H100, L40, A10, A30 and AMD MI300, MI325, MI350, MI355).
 
-- **Default host:** `http://localhost:8000`
+- **Default host:** `http://localhost:13305`
 - **Health check:** `GET /v1/models`
 - **Tool fallback:** If the server returns HTTP 400 when tools are included, the engine automatically retries without tools
 
@@ -204,7 +204,7 @@ The Nexa backend connects to the Nexa SDK on-device inference server via a FastA
 
 The Lemonade backend connects to the [Lemonade](https://lemonade-server.ai/) inference server, which is optimized for AMD consumer GPUs (RDNA architecture) and Ryzen AI Neural Processing Units (NPUs). It uses the OpenAI-compatible `/v1/chat/completions` API.
 
-- **Default host:** `http://localhost:8000`
+- **Default host:** `http://localhost:13305`
 - **Health check:** `GET /v1/models`
 - **Install:** Visit [lemonade-server.ai](https://lemonade-server.ai/) for platform-specific installation instructions
 - **Best for:** Ryzen AI GPUs and NPUs, and AMD-based desktop and laptop systems
@@ -357,7 +357,7 @@ host = "http://localhost:30000"
 # binary_path = ""
 
 # [engine.lemonade]
-# host = "http://localhost:8000"
+# host = "http://localhost:13305"
 ```
 
 The `EngineConfig` dataclass and its per-engine sub-dataclasses map these settings:
@@ -370,7 +370,7 @@ The `EngineConfig` dataclass and its per-engine sub-dataclasses map these settin
 | `SGLangEngineConfig` | `host` | `http://localhost:30000` | SGLang server URL |
 | `LlamaCppEngineConfig` | `host` | `http://localhost:8080` | llama.cpp server URL |
 | `LlamaCppEngineConfig` | `binary_path` | `""` | Path to llama.cpp binary (for managed mode) |
-| `LemonadeEngineConfig` | `host` | `http://localhost:8000` | Lemonade server URL |
+| `LemonadeEngineConfig` | `host` | `http://localhost:13305` | Lemonade server URL |
 
 !!! note "Backward compatibility"
     The old flat field names `ollama_host`, `vllm_host`, `llamacpp_host`, `llamacpp_path`, `sglang_host`, and `lemonade_host` under `[engine]` are still accepted as backward-compatible properties on `EngineConfig`. New configurations should use the nested sub-section format.

docs/assets/showcase/README.md

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

docs/deployment/docker.md

@@ -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                        |

docs/deployment/launchd.md

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

docs/deployment/systemd.md

@@ -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

docs/desktop-auto-update.md

@@ -0,0 +1,112 @@
+# Desktop auto-update
+
+The OpenJarvis desktop app ships with [Tauri's updater
+plugin](https://v2.tauri.app/plugin/updater/), which checks for new
+versions on launch and every 30 minutes. When a newer signed build is
+available, the app prompts the user to download and install it.
+
+## How it works
+
+```
+on launch / every 30 min
+        │
+        ▼
+GET https://github.com/open-jarvis/OpenJarvis/releases/download/desktop-latest/latest.json
+        │
+        ▼
+Parse manifest: { "version": "X.Y.Z", "platforms": { ... } }
+        │
+        ▼
+If manifest.version > installed_version:
+   download signed .dmg / .deb / .msi from manifest.platforms[target].url
+   verify against the minisign pubkey baked into the app
+   prompt user to install
+```
+
+The frontend code lives in
+[`frontend/src/components/Desktop/UpdateChecker.tsx`](../frontend/src/components/Desktop/UpdateChecker.tsx);
+the Tauri wiring is in
+[`frontend/src-tauri/tauri.conf.json`](../frontend/src-tauri/tauri.conf.json)
+under `plugins.updater`.
+
+## How releases reach the update endpoint
+
+The `Desktop Build & Release` GitHub Action
+([`.github/workflows/desktop.yml`](../.github/workflows/desktop.yml))
+builds signed binaries plus a `latest.json` manifest with the
+`tauri-action` step (`includeUpdaterJson: true` generates the manifest
+automatically). Where it publishes depends on the trigger.
+
+Three release streams exist:
+
+- **`desktop-latest`** (stable auto-update channel): **this is the
+  channel the installed app polls.** It is *not* built directly —
+  instead, when a stable `desktop-vX.Y.Z` release is published, the
+  `refresh-stable-channel` job copies that release's `latest.json`
+  into `desktop-latest`. So the app is only ever offered vetted stable
+  builds, and `latest.json` here points at the current `desktop-v*`
+  assets.
+- **`desktop-vX.Y.Z`** (tagged stable): created when someone pushes a
+  `desktop-v*` git tag. The user-facing stable release with full
+  installers; also the source of truth the stable channel mirrors.
+- **`desktop-edge`** (rolling pre-release): rebuilt on every push to
+  `main` (via the `autotag` → `desktop.yml` dispatch) and on manual
+  `workflow_dispatch`. Carries the most recent CI build for testers.
+  The shipped app does **not** poll this stream, so dev builds never
+  auto-install onto stable users.
+
+This split means security and telemetry-policy fixes reach users on
+the next **stable** `desktop-v*` tag — cut one to ship an update.
+Edge builds are available for anyone who wants to test `main` ahead of
+a stable tag, without risking the stable population.
+
+## Signing
+
+Binaries are signed by `tauri-action` using the minisign key pair
+referenced via these GitHub Actions secrets:
+
+| Secret | Purpose |
+|---|---|
+| `TAURI_SIGNING_PRIVATE_KEY` | Private key (PEM-formatted minisign) |
+| `TAURI_SIGNING_PRIVATE_KEY_PASSWORD` | Passphrase for the private key |
+
+The matching public key is baked into the app at
+`tauri.conf.json:plugins.updater.pubkey`. If you ever need to rotate
+the key, replace the public key in the JSON file *and* update both
+secrets atomically — mismatched keys cause every update download to
+fail signature verification with no recovery path other than a manual
+reinstall.
+
+## Disabling the updater locally
+
+For frontend development, set `VITE_OPENJARVIS_NO_UPDATER=1` in your
+shell before running `npm run tauri dev`. Vite injects any
+`VITE_`-prefixed env var into `import.meta.env`, and the
+`UpdateChecker.tsx` component honors it to skip the 30-minute poll.
+
+```bash
+export VITE_OPENJARVIS_NO_UPDATER=1
+npm run tauri dev
+```
+
+This is purely a dev escape hatch — it has no effect on production
+builds (where `import.meta.env.VITE_OPENJARVIS_NO_UPDATER` will be
+`undefined` unless you explicitly set it at build time).
+
+## Verifying a release manually
+
+```bash
+# Download the latest manifest and confirm it parses cleanly
+curl -fsSL https://github.com/open-jarvis/OpenJarvis/releases/download/desktop-latest/latest.json | jq .
+
+# Fields:
+#   version       — semver string, must match the tag (without leading "v")
+#   notes         — release notes string
+#   pub_date      — RFC3339 timestamp
+#   platforms     — map keyed by "<target>-<arch>" e.g. "darwin-aarch64"
+#                   each entry has { signature: "...", url: "..." }
+```
+
+A 404 on the manifest URL means the most recent desktop CI run
+didn't complete or didn't have signing secrets — check the
+`Desktop Build & Release` workflow logs.

docs/downloads.md

@@ -25,11 +25,11 @@ processing happens on your local machine — the app connects to the backend you
 
 | Platform | Download | Notes |
 |----------|----------|-------|
-| macOS (Apple Silicon) | [:material-download: **OpenJarvis.dmg**](https://github.com/open-jarvis/OpenJarvis/releases/download/desktop-latest/OpenJarvis_0.1.0_aarch64.dmg) | M1/M2/M3/M4 Macs |
-| Windows (64-bit) | [:material-download: **OpenJarvis-setup.exe**](https://github.com/open-jarvis/OpenJarvis/releases/download/desktop-latest/OpenJarvis_0.1.0_x64-setup.exe) | Windows 10+ |
-| Linux (DEB) | [:material-download: **OpenJarvis.deb**](https://github.com/open-jarvis/OpenJarvis/releases/download/desktop-latest/OpenJarvis_0.1.0_amd64.deb) | Ubuntu, Debian |
-| Linux (RPM) | [:material-download: **OpenJarvis.rpm**](https://github.com/open-jarvis/OpenJarvis/releases/download/desktop-latest/OpenJarvis-0.1.0-1.x86_64.rpm) | Fedora, RHEL |
-| Linux (AppImage) | [:material-download: **OpenJarvis.AppImage**](https://github.com/open-jarvis/OpenJarvis/releases/download/desktop-latest/OpenJarvis_0.1.0_amd64.AppImage) | Any distro |
+| macOS (Universal) | [:material-download: **OpenJarvis.dmg**](https://github.com/open-jarvis/OpenJarvis/releases/download/desktop-v1.0.2/OpenJarvis_1.0.1_universal.dmg) | Apple Silicon + Intel |
+| Windows (64-bit) | [:material-download: **OpenJarvis-setup.exe**](https://github.com/open-jarvis/OpenJarvis/releases/download/desktop-v1.0.2/OpenJarvis_1.0.1_x64-setup.exe) | Windows 10+ |
+| Linux (DEB) | [:material-download: **OpenJarvis.deb**](https://github.com/open-jarvis/OpenJarvis/releases/download/desktop-v1.0.2/OpenJarvis_1.0.1_amd64.deb) | Ubuntu, Debian |
+| Linux (RPM) | [:material-download: **OpenJarvis.rpm**](https://github.com/open-jarvis/OpenJarvis/releases/download/desktop-v1.0.2/OpenJarvis-1.0.1-1.x86_64.rpm) | Fedora, RHEL |
+| Linux (AppImage) | [:material-download: **OpenJarvis.AppImage**](https://github.com/open-jarvis/OpenJarvis/releases/download/desktop-v1.0.2/OpenJarvis_1.0.1_amd64.AppImage) | Any distro |
 
 !!! tip "All releases"
     Browse all versions on the [GitHub Releases](https://github.com/open-jarvis/OpenJarvis/releases) page.
@@ -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
@@ -109,7 +109,7 @@ If you prefer to run each step yourself:
     ```bash
     git clone https://github.com/open-jarvis/OpenJarvis.git
     cd OpenJarvis
-    uv sync --extra server
+    uv sync --extra desktop
     cd frontend && npm install && cd ..
     ```
 

docs/gen_install_script.py

@@ -0,0 +1,30 @@
+"""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)
+
+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 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
+
+# (source path, published URL path)
+_SCRIPTS = [
+    (Path("scripts/install/install.sh"), "install.sh"),
+    (Path("deploy/windows/install.ps1"), "install.ps1"),
+]
+
+for src, dest in _SCRIPTS:
+    with mkdocs_gen_files.open(dest, "wb") as out:
+        out.write(src.read_bytes())

docs/getting-started/configuration.md

@@ -17,6 +17,46 @@ The configuration file lives at:
 
 OpenJarvis creates the `~/.openjarvis/` directory and populates it with a default config when you run `jarvis init`.
 
+## Relocating the OpenJarvis directory
+
+OpenJarvis keeps **all** of its state — config, databases, caches, logs,
+credentials, skills, recipes, connectors — under a **single root** so it never
+clutters your home directory beyond one folder. By default that root is
+`~/.openjarvis`, but you can move it.
+
+The root is resolved in priority order:
+
+1. **`$OPENJARVIS_HOME`** — explicit override. Honored by both the installer
+   and the Python runtime.
+2. **`$XDG_DATA_HOME/openjarvis`** — used when `$XDG_DATA_HOME` is set (a single
+   `openjarvis` directory nested under it, per the XDG Base Directory spec).
+3. **`~/.openjarvis`** — the default. With no environment variables set, the
+   resolved path is exactly this, so existing installs are untouched.
+
+```bash
+# Relocate the whole install + runtime tree at install time:
+OPENJARVIS_HOME=~/apps/openjarvis curl -fsSL https://open-jarvis.github.io/OpenJarvis/install.sh | bash
+
+# Or for a single run / your shell profile:
+export OPENJARVIS_HOME=~/apps/openjarvis
+```
+
+Confirm where your data lives with:
+
+```bash
+jarvis config path
+```
+
+!!! note "Migration"
+    Because the default is unchanged, **no data migration is required** for
+    existing installs. If you set `OPENJARVIS_HOME` (or `XDG_DATA_HOME`) on a
+    machine that already has data in `~/.openjarvis`, OpenJarvis will look in
+    the new location and not see your old data — move it yourself if you want
+    to keep it: `mv ~/.openjarvis "$OPENJARVIS_HOME"`.
+
+`$OPENJARVIS_CONFIG` still points at an explicit `config.toml` file
+independently of the root, if you need to override just the config file path.
+
 ## Generating Configuration
 
 ### First-Time Setup
@@ -564,7 +604,7 @@ enforce_tool_confirmation = true
 | `scan_output` | bool | `true` | Whether to scan model output. |
 | `secret_scanner` | bool | `true` | Enable secret detection (API keys, tokens, passwords). |
 | `pii_scanner` | bool | `true` | Enable PII detection (emails, SSNs, credit cards). |
-| `enforce_tool_confirmation` | bool | `true` | Require confirmation before executing tools. |
+| `enforce_tool_confirmation` | bool | `true` | Accepted but **not currently enforced**. Whether you get prompts depends on the entry point. See [System Access](../user-guide/system-access.md#confirmation-behaviour). |
 
 !!! tip "Choosing a security mode"
     Use `"warn"` during development to see what would be flagged without disrupting output.

docs/getting-started/install.md

@@ -1,11 +1,34 @@
 # 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://openjarvis.ai/install.sh | bash
+curl -fsSL https://open-jarvis.github.io/OpenJarvis/install.sh | bash
 ```
 
+The installer downloads everything for you — including [uv](https://docs.astral.sh/uv/)
+(the Python package manager), the Python venv, Ollama, and a small starter
+model. **You don't need to install uv or any other prerequisite first.**
+
+!!! info "Install URL"
+    This script is served straight from the project's own GitHub Pages site,
+    so HTTPS always works. You may also see `https://openjarvis.ai/install.sh`
+    referenced in older docs — that domain is community-operated and has had
+    intermittent TLS issues ([#337](https://github.com/open-jarvis/OpenJarvis/issues/337)).
+    The `open-jarvis.github.io` URL above is the canonical one.
+
 About 3 minutes on a typical broadband connection. Type `jarvis` to start chatting.
 
 ## What the installer does

docs/getting-started/installation.md

@@ -41,7 +41,7 @@ If you prefer to run each step yourself:
     ```bash
     git clone https://github.com/open-jarvis/OpenJarvis.git
     cd OpenJarvis
-    uv sync --extra server
+    uv sync --extra desktop
     uv run maturin develop -m rust/crates/openjarvis-python/Cargo.toml
     cd frontend && npm install && cd ..
     ```
@@ -94,11 +94,11 @@ cd OpenJarvis
 
 | Platform | Download |
 |----------|----------|
-| macOS (Apple Silicon) | [:material-download: **OpenJarvis.dmg**](https://github.com/open-jarvis/OpenJarvis/releases/download/desktop-latest/OpenJarvis_0.1.0_aarch64.dmg) |
-| Windows (64-bit) | [:material-download: **OpenJarvis-setup.exe**](https://github.com/open-jarvis/OpenJarvis/releases/download/desktop-latest/OpenJarvis_0.1.0_x64-setup.exe) |
-| Linux (DEB) | [:material-download: **OpenJarvis.deb**](https://github.com/open-jarvis/OpenJarvis/releases/download/desktop-latest/OpenJarvis_0.1.0_amd64.deb) |
-| Linux (RPM) | [:material-download: **OpenJarvis.rpm**](https://github.com/open-jarvis/OpenJarvis/releases/download/desktop-latest/OpenJarvis-0.1.0-1.x86_64.rpm) |
-| Linux (AppImage) | [:material-download: **OpenJarvis.AppImage**](https://github.com/open-jarvis/OpenJarvis/releases/download/desktop-latest/OpenJarvis_0.1.0_amd64.AppImage) |
+| macOS (Universal) | [:material-download: **OpenJarvis.dmg**](https://github.com/open-jarvis/OpenJarvis/releases/download/desktop-v1.0.2/OpenJarvis_1.0.1_universal.dmg) |
+| Windows (64-bit) | [:material-download: **OpenJarvis-setup.exe**](https://github.com/open-jarvis/OpenJarvis/releases/download/desktop-v1.0.2/OpenJarvis_1.0.1_x64-setup.exe) |
+| Linux (DEB) | [:material-download: **OpenJarvis.deb**](https://github.com/open-jarvis/OpenJarvis/releases/download/desktop-v1.0.2/OpenJarvis_1.0.1_amd64.deb) |
+| Linux (RPM) | [:material-download: **OpenJarvis.rpm**](https://github.com/open-jarvis/OpenJarvis/releases/download/desktop-v1.0.2/OpenJarvis-1.0.1-1.x86_64.rpm) |
+| Linux (AppImage) | [:material-download: **OpenJarvis.AppImage**](https://github.com/open-jarvis/OpenJarvis/releases/download/desktop-v1.0.2/OpenJarvis_1.0.1_amd64.AppImage) |
 
 The app connects to `http://localhost:8000` automatically.
 
@@ -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 |
@@ -278,6 +278,7 @@ OpenJarvis uses optional extras to keep the base installation lightweight.
 
 | Extra | Install Command | Description |
 |-------|----------------|-------------|
+| `desktop` | `uv sync --extra desktop` | Desktop/API server plus local speech input |
 | `server` | `uv sync --extra server` | OpenAI-compatible API server (`jarvis serve`) |
 | `dev` | `uv sync --extra dev` | Development and testing tools |
 | `docs` | `uv sync --extra docs` | Documentation build tools |
@@ -285,7 +286,7 @@ OpenJarvis uses optional extras to keep the base installation lightweight.
 Combine extras:
 
 ```bash
-uv sync --extra server --extra memory-faiss --extra inference-cloud
+uv sync --extra desktop --extra memory-faiss --extra inference-cloud
 ```
 
 ## Setting Up an Inference Backend

docs/getting-started/linux.md

@@ -1,7 +1,7 @@
 # Linux Install
 
 ```bash
-curl -fsSL https://openjarvis.ai/install.sh | bash
+curl -fsSL https://open-jarvis.github.io/OpenJarvis/install.sh | bash
 ```
 
 Tested on: Ubuntu 22.04 / 24.04, Fedora 40, Debian 12, Arch.

docs/getting-started/macos.md

@@ -1,7 +1,7 @@
 # macOS Install
 
 ```bash
-curl -fsSL https://openjarvis.ai/install.sh | bash
+curl -fsSL https://open-jarvis.github.io/OpenJarvis/install.sh | bash
 ```
 
 Works on Intel and Apple Silicon. The installer auto-detects your CPU/GPU.

docs/getting-started/quickstart.md

@@ -135,6 +135,19 @@ cd OpenJarvis
 This launches the backend API server and a React frontend at [http://localhost:5173](http://localhost:5173).
 You get a ChatGPT-like interface with streaming responses, tool use, energy monitoring, and a telemetry dashboard — all running locally on your hardware.
 
+Web search is available through the built-in DuckDuckGo fallback. To use
+Tavily, add `TAVILY_API_KEY` under **Settings → Tools → Web Search** after the
+app starts, or export it before starting quickstart:
+
+```bash
+export TAVILY_API_KEY="tvly-..."
+./scripts/quickstart.sh
+```
+
+The script does not automatically source `.env` files. Run `source .env`
+first if that is where you keep the key. Stop any existing OpenJarvis server
+before restarting so it inherits the updated environment.
+
 To stop all services, press ++ctrl+c++ in the terminal.
 
 !!! tip "Environment variable"

docs/getting-started/windows-native.md

@@ -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 desktop --group desktop-native`.
+- 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 desktop --group desktop-native`.
+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).

docs/getting-started/wsl2.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
 
@@ -15,7 +18,7 @@ Then open the Ubuntu (or Debian) shell that gets installed.
 ## Install OpenJarvis
 
 ```bash
-curl -fsSL https://openjarvis.ai/install.sh | bash
+curl -fsSL https://open-jarvis.github.io/OpenJarvis/install.sh | bash
 ```
 
 About 3 minutes. Type `jarvis` to start.

docs/index.md

@@ -14,13 +14,25 @@ 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?
 
 Personal AI agents are exploding in popularity, but nearly all of them still route intelligence through cloud APIs. Your "personal" AI continues to depend on someone else's server. At the same time, our [Intelligence Per Watt](https://www.intelligence-per-watt.ai/) research showed that local language models already handle 88.7% of single-turn chat and reasoning queries, with intelligence efficiency improving 5.3× from 2023 to 2025. The models and hardware are increasingly ready. What has been missing is the software stack to make local-first personal AI practical.
 
-OpenJarvis is that stack. It is an opinionated framework for local-first personal AI, built around three core ideas: shared primitives for building on-device agents; evaluations that treat energy, FLOPs, latency, and dollar cost as first-class constraints alongside accuracy; and a learning loop that improves models using local trace data. The goal is simple: make it possible to build personal AI agents that run locally by default, calling the cloud only when truly necessary. OpenJarvis aims to be both a research platform and a production foundation for local AI, in the spirit of PyTorch.
+OpenJarvis is that stack. It is a framework for local-first personal AI, built around three core ideas: shared primitives for building on-device agents; evaluations that treat energy, FLOPs, latency, and dollar cost as first-class constraints alongside accuracy; and a learning loop that improves models using local trace data. The goal is simple: make it possible to build personal AI agents that run locally by default, calling the cloud only when truly necessary. OpenJarvis aims to be both a research platform and a production foundation for local AI, in the spirit of PyTorch.
 
 ---
 
@@ -54,13 +66,15 @@ OpenJarvis is that stack. It is an opinionated framework for local-first persona
 
     **Step 2.** Download and open the desktop app:
 
-    [Download for macOS](https://github.com/open-jarvis/OpenJarvis/releases/download/desktop-latest/OpenJarvis_0.1.0_universal.dmg){ .md-button .md-button--primary }
+    [Download for macOS](https://github.com/open-jarvis/OpenJarvis/releases/download/desktop-v1.0.2/OpenJarvis_1.0.1_universal.dmg){ .md-button .md-button--primary }
 
-    Also available for [Windows](https://github.com/open-jarvis/OpenJarvis/releases/download/desktop-latest/OpenJarvis_0.1.0_x64-setup.exe), [Linux (DEB)](https://github.com/open-jarvis/OpenJarvis/releases/download/desktop-latest/OpenJarvis_0.1.0_amd64.deb), and [Linux (RPM)](https://github.com/open-jarvis/OpenJarvis/releases/download/desktop-latest/OpenJarvis-0.1.0-1.x86_64.rpm). See the [Downloads](downloads.md) page for details.
+    Also available for [Windows](https://github.com/open-jarvis/OpenJarvis/releases/download/desktop-v1.0.2/OpenJarvis_1.0.1_x64-setup.exe), [Linux (DEB)](https://github.com/open-jarvis/OpenJarvis/releases/download/desktop-v1.0.2/OpenJarvis_1.0.1_amd64.deb), and [Linux (RPM)](https://github.com/open-jarvis/OpenJarvis/releases/download/desktop-v1.0.2/OpenJarvis-1.0.1-1.x86_64.rpm). See the [Downloads](downloads.md) page for details.
 
     The app connects to `http://localhost:8000` automatically.
 
-    !!! warning "macOS: run `xattr -cr /Applications/OpenJarvis.app` if the app shows as \"damaged\"."
+    !!! warning "macOS first launch"
+
+        Run `xattr -cr /Applications/OpenJarvis.app` if the app shows as "damaged".
 
 === "Python SDK"
 
@@ -104,9 +118,9 @@ OpenJarvis is that stack. It is an opinionated framework for local-first persona
 OpenJarvis is built around five composable layers. Each has a clean interface and can be swapped independently.
 
 1. **Intelligence** — Pick a model, or let OpenJarvis pick one for your hardware. Manages the full catalog of local models across providers.
-2. **Agents** — Multi-step reasoning with tool use. Seven built-in agent types from simple chat to orchestrated workflows.
-3. **Tools** — Web search, calculator, file I/O, code interpreter, retrieval, and any external MCP server.
-4. **Engine** — The inference runtime: [Ollama](https://ollama.com), [vLLM](https://github.com/vllm-project/vllm), [SGLang](https://github.com/sgl-project/sglang), [llama.cpp](https://github.com/ggerganov/llama.cpp), cloud APIs, and more. Auto-detects your hardware and recommends the best fit.
+2. **Engine** — The inference runtime: [Ollama](https://ollama.com), [vLLM](https://github.com/vllm-project/vllm), [SGLang](https://github.com/sgl-project/sglang), [llama.cpp](https://github.com/ggerganov/llama.cpp), cloud APIs, and more. Auto-detects your hardware and recommends the best fit.
+3. **Agents** — Multi-step reasoning with tool use. Eight built-in agent types from simple chat to orchestrated workflows.
+4. **Tools & Memory** — Web search, calculator, file I/O, code interpreter, retrieval, persistent local state, and any external MCP server.
 5. **Learning** — Your AI gets better over time. Every interaction generates traces that drive automatic improvements to model weights, prompts, and agent behavior.
 
 ---
@@ -169,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)**
 
@@ -201,16 +215,19 @@ OpenJarvis is built around five composable layers. Each has a clean interface an
 
 OpenJarvis is part of [Intelligence Per Watt](https://www.intelligence-per-watt.ai/), a research initiative studying the efficiency of on-device AI systems. Developed at [Hazy Research](https://hazyresearch.stanford.edu/) and the [Scaling Intelligence Lab](https://scalingintelligence.stanford.edu/) at [Stanford SAIL](https://ai.stanford.edu/).
 
-Read the [blog post](https://scalingintelligence.stanford.edu/blogs/openjarvis/) for the full research motivation, architecture details, and experimental results.
+Read the [blog post](https://openjarvis.stanford.edu/) for the full research motivation, architecture details, and experimental results.
 
 ## Citation
 
 ```bibtex
-@misc{saadfalcon2026openjarvis,
-  title={OpenJarvis: Personal AI, On Personal Devices},
-  author={Jon Saad-Falcon and Avanika Narayan and Herumb Shandilya and Hakki Orhun Akengin and Robby Manihani and Gabriel Bo and John Hennessy and Christopher R\'{e} and Azalia Mirhoseini},
-  year={2026},
-  howpublished={\url{https://scalingintelligence.stanford.edu/blogs/openjarvis/}},
+@misc{saadfalcon2026openjarvispersonalaipersonal,
+      title={OpenJarvis: Personal AI, On Personal Devices}, 
+      author={Jon Saad-Falcon and Avanika Narayan and Robby Manihani and Tanvir Bhathal and Herumb Shandilya and Hakki Orhun Akengin and Gabriel Bo and Andrew Park and Matthew Hart and Caia Costello and Chuan Li and Christopher Ré and Azalia Mirhoseini},
+      year={2026},
+      eprint={2605.17172},
+      archivePrefix={arXiv},
+      primaryClass={cs.LG},
+      url={https://arxiv.org/abs/2605.17172}, 
 }
 ```
 
@@ -225,3 +242,5 @@ Read the [blog post](https://scalingintelligence.stanford.edu/blogs/openjarvis/)
   <a href="https://research.ibm.com/">IBM Research</a> &bull;
   <a href="https://hai.stanford.edu/">Stanford HAI</a>
 </p>
+
+Follow [@OpenJarvisAI](https://x.com/OpenJarvisAI) on X for updates.

docs/javascripts/leaderboard-config.js

@@ -0,0 +1,12 @@
+// Public Supabase config for the savings leaderboard.
+//
+// This file is loaded *before* leaderboard.js and supplies the anon key it
+// reads from `window.OPENJARVIS_SUPABASE_ANON_KEY`. The key is injected at
+// docs-build time from the VITE_SUPABASE_ANON_KEY repo secret (see
+// .github/workflows/docs.yml). It is intentionally empty here so that local
+// `mkdocs build` and fork pull requests — which have no secret — render the
+// graceful "Leaderboard not configured yet" message instead of failing.
+//
+// The anon key is public by design: Supabase Row-Level Security protects the
+// data, so shipping it in the public docs bundle is expected.
+window.OPENJARVIS_SUPABASE_ANON_KEY = "";

docs/javascripts/leaderboard.js

@@ -1,9 +1,9 @@
 (function () {
   "use strict";
 
-  var SUPABASE_URL = "https://mtbtgpwzrbostweaanpr.supabase.co";
-  var SUPABASE_ANON_KEY =
-    "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJzdXBhYmFzZSIsInJlZiI6Im10YnRncHd6cmJvc3R3ZWFhbnByIiwicm9sZSI6ImFub24iLCJpYXQiOjE3NzMxODk0OTQsImV4cCI6MjA4ODc2NTQ5NH0._xMlqCfljtXpwPj54H-ghxfLFO-jiq4W2WhpU8vVL1c";
+  var SUPABASE_URL =
+    window.OPENJARVIS_SUPABASE_URL || "https://mtbtgpwzrbostweaanpr.supabase.co";
+  var SUPABASE_ANON_KEY = window.OPENJARVIS_SUPABASE_ANON_KEY || "";
 
   var PAGE_SIZE = 50;
   var allRows = [];
@@ -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,

docs/leaderboard.md

@@ -55,5 +55,5 @@ See how the OpenJarvis community saves money, energy, and compute by running AI
 <div id="leaderboard-pagination" class="lb-pagination"></div>
 
 <p style="font-size:12px;opacity:0.6;margin-top:12px">
-*Dollar savings estimated vs. Claude Opus 4.6 API pricing ($5/1M input, $25/1M output tokens). Assumes local open-source models produce roughly the same number of tokens per request as cloud models.
+*Dollar savings estimated vs. Claude Fable 5 API pricing ($10/1M input, $50/1M output tokens). Assumes local open-source models produce roughly the same number of tokens per request as cloud models.
 </p>

docs/learning/ace.md

@@ -0,0 +1,135 @@
+# ACE optimizer (Agentic Context Engineering)
+
+OpenJarvis supports [ACE](https://github.com/ace-agent/ace) as a third
+optimizer alongside DSPy and GEPA. Where DSPy bootstraps few-shot
+examples and GEPA evolves prompts via reflective mutation, **ACE
+evolves a textual *playbook*** — annotated natural-language strategies
+the agent reads at inference time. The playbook is updated by a
+Generator / Reflector / Curator triad of LLM calls.
+
+## When to pick ACE
+
+| Task shape | DSPy | GEPA | ACE |
+|---|---|---|---|
+| Single-turn QA with crisp metric | strong | strong | weaker |
+| Long-running agent that should accumulate guidance | weak | medium | strong |
+| Open-domain where strategies matter more than templates | weak | medium | strong |
+| When you want to *read* what the optimizer learned | medium | medium | strong |
+
+ACE's headline artifact is `final_playbook.txt` — a human-readable
+file like:
+
+```
+## STRATEGIES & INSIGHTS
+[str-00001] helpful=5 harmful=0 :: When the user asks for unit
+                                   conversion, prefer the exact
+                                   rational form before rounding.
+[str-00002] helpful=3 harmful=1 :: Cite a primary source before
+                                   stating a date claim.
+```
+
+If reading those strategies feels like the form of "what learning
+should produce" for your task, ACE is the right choice.
+
+## Setup
+
+ACE is **not on PyPI** as of OpenJarvis v1.0.1, and the upstream
+repository is structured as a research codebase (multiple top-level
+directories) rather than a Python package. There's no `learning-ace`
+extra for that reason. Install ACE manually instead:
+
+```bash
+# 1. Clone ACE somewhere outside your OpenJarvis checkout
+git clone https://github.com/ace-agent/ace.git ~/code/ace
+cd ~/code/ace
+curl -LsSf https://astral.sh/uv/install.sh | sh   # if you don't have uv
+uv sync
+
+# 2. Make ACE's src/ importable from your OpenJarvis venv
+echo "$HOME/code/ace/src" > \
+  "$(python -c 'import site; print(site.getsitepackages()[0])')/ace.pth"
+
+# 3. Set the API key for whichever provider ACE will call
+cp ~/code/ace/.env.example ~/code/ace/.env
+# Edit ~/code/ace/.env to set API_KEY for your chosen provider.
+
+# 4. Verify the import resolves from OpenJarvis's venv
+python -c "from openjarvis.learning.agents.ace_optimizer import HAS_ACE; print(HAS_ACE)"
+# True
+```
+
+If `HAS_ACE` prints `False`, the `.pth` file isn't being picked up —
+verify the path matches `site.getsitepackages()[0]` for the same
+Python interpreter you're using to run OpenJarvis.
+
+## Configuration
+
+ACE is configured under `[learning.agent.ace]` in your OpenJarvis
+config TOML:
+
+```toml
+[learning.agent]
+policy = "ace"
+
+[learning.agent.ace]
+# ACE's three roles. Empty = inherit from the intelligence primitive's
+# default cloud model.
+generator_model = "claude-opus-4-7"
+reflector_model = "claude-opus-4-7"
+curator_model = "claude-sonnet-4-6"
+
+api_provider = "openai"     # sambanova | together | openai | commonstack
+
+num_epochs = 1
+max_num_rounds = 3
+playbook_token_budget = 80000
+max_tokens = 4096
+
+task_name = "openjarvis"
+save_dir = ""               # default: ~/.openjarvis/learning/ace/<task>/
+
+min_traces = 20
+```
+
+## Running
+
+Once configured, the same orchestrator that runs DSPy / GEPA also runs
+ACE — pick it via the `policy` field above. To force a one-shot run:
+
+```bash
+jarvis optimize agent --policy ace
+```
+
+ACE writes intermediate state and the final playbook to `save_dir`.
+The OpenJarvis runtime will pick up the playbook on next agent start
+(via the same sidecar overlay mechanism the Skills System uses).
+
+## Trace adapter behavior
+
+OpenJarvis traces are adapted into ACE's `train_samples` /
+`val_samples` / `test_samples` format via a 70 / 15 / 15 split
+(order-preserving for reproducibility). Each trace becomes a
+`{question: trace.query, ground_truth_answer: trace.result}` sample.
+Traces with empty `query` or `result` are dropped before splitting.
+
+The `DataProcessor` ACE expects is built from `_TraceDataProcessor`
+in `src/openjarvis/learning/agents/ace_optimizer.py` — it does a
+case-insensitive substring match for `answer_is_correct` and averages
+that for aggregate accuracy. If you're optimizing for a domain where
+substring matching is the wrong correctness signal (math problems,
+code, structured outputs), subclass `_TraceDataProcessor` and pass it
+through your own callsite to `ACEAgentOptimizer.optimize()`.
+
+## Limitations in v1.0.1
+
+- **No automatic install.** Document above is the only path.
+- **The trace adapter uses substring correctness.** Override for
+  domain-specific scoring.
+- **Single provider per run.** ACE assigns the same `api_provider` to
+  all three roles. To mix providers, run ACE outside OpenJarvis and
+  hand-deliver the resulting playbook into `save_dir`.
+
+These will get revisited once ACE publishes a PyPI package or stable
+provider interface — track
+[ace-agent/ace#issues](https://github.com/ace-agent/ace/issues) for
+upstream changes that would let us tighten the wrapper.

docs/showcase/CONTRIBUTING.md

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

docs/showcase/coding-assistant.md

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

docs/showcase/cost-savings.md

@@ -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`.

docs/showcase/discord-companion.md

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

docs/showcase/index.md

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

docs/showcase/morning-brief.md

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

docs/showcase/persistent-memory.md

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

docs/stylesheets/extra.css

@@ -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);
+}

docs/telemetry.md

@@ -0,0 +1,124 @@
+# Telemetry
+
+OpenJarvis ships **anonymous usage telemetry** by default so the team can
+see where the product breaks, what features people actually use, and
+how to make it better. This page documents exactly what is and isn't
+collected, where the data goes, and how to opt out.
+
+## TL;DR
+
+- **On by default**, anonymous, no chat content.
+- **Anonymous** — one random UUID per install, no email, no name, no IP.
+- **No chat content, ever.** Only counts, timings, and feature names.
+- **Self-hosted backend** on the OpenJarvis team's PostHog instance —
+  data is not sold or shared with third parties.
+- **365-day retention**, after which events are deleted automatically.
+
+## What we collect
+
+### Lifecycle events
+
+| Event | Source | Why we send it |
+|---|---|---|
+| `install_started` | `install.sh` | Top of install funnel |
+| `install_stage_completed` | `install.sh` | Per-stage timing — where do people drop off? |
+| `install_completed` | `install.sh` | Did the install succeed? |
+| `install_failed` | `install.sh` | Which stage failed, and on what OS |
+| `app_opened` | Backend + frontend | DAU / WAU / MAU |
+| `setup_completed` | Frontend | First-run wizard finished |
+| `first_chat_sent` | Backend | First-ever message — activation |
+| `uninstall_started` | `uninstall.sh` (if user runs it) | Churn signal |
+
+### Usage events
+
+| Event | Why we send it |
+|---|---|
+| `chat_session_ended` | Aggregated per-session: turn count, tokens, latency, tool count |
+| `tool_first_used` | Which built-in tools are actually adopted |
+| `model_changed` | How often users switch models |
+| `feature_used` | Which features get traffic, which don't |
+| `connector_auth_completed` | Which connectors people set up |
+| `error_shown_to_user` | User-visible error class (not stack trace) |
+| `feedback_submitted` | Was a rating given? Was a comment included? |
+| `settings_changed` | Which settings get toggled |
+| `usage_daily_summary` | Once-per-day aggregated counts |
+
+The canonical, authoritative list with every property name and its
+type validator lives in
+[`src/openjarvis/analytics/events.py`](../src/openjarvis/analytics/events.py).
+That file is the only place new events can be added — PR review is
+the gate.
+
+## What we never collect
+
+Hard guardrails, enforced by code:
+
+- **Chat content** — prompts, model outputs, system messages, tool args.
+- **File paths** — anything matching `~/`, `$HOME`, `/Users/<name>`, `/home/<name>`, `file://`.
+- **Emails, names, phone numbers, addresses.**
+- **IP addresses** (IPv4 + IPv6). PostHog's IP geo lookup is disabled server-side too.
+- **MAC addresses, hardware serials, drive UUIDs.**
+- **Stack traces** — only error class enums.
+- **API keys, OAuth tokens, JWTs, bearer tokens, password assignments** —
+  matched and dropped at value level.
+- **Hostnames** that look personal (e.g. `alice-macbook.local`).
+- **Lists, dicts, sets** — composite values are never sent so PII can't
+  smuggle through inside containers.
+
+Two independent filters run before every event leaves the machine:
+
+1. [`src/openjarvis/analytics/redaction.py`](../src/openjarvis/analytics/redaction.py) — value-level pattern matching (20+ regexes for PII).
+2. [`src/openjarvis/analytics/events.py`](../src/openjarvis/analytics/events.py) — structural allowlist (event name + property name + type validator).
+
+Any failure at either layer → the event or property is silently
+dropped. Tests covering the patterns: [`tests/analytics/test_redaction.py`](../tests/analytics/test_redaction.py).
+
+## Where the data goes
+
+- **Today** (alpha): PostHog Cloud (US region) free tier. Disclosed
+  here for transparency.
+- **Production target**: A self-hosted PostHog instance at
+  `analytics.openjarvis.ai`, Hetzner US-East. Single-tenant, operated
+  by the OpenJarvis team.
+- **Never** sold, shared with advertisers, or used for anything other
+  than improving OpenJarvis.
+
+## Retention
+
+- Default retention: **365 days**, then events are deleted by PostHog
+  automatically.
+- `jarvis analytics reset-id` lets you orphan all of your past events
+  by generating a fresh anonymous ID for future events.
+
+## How identity works
+
+A single UUID v4 is generated on first install and stored at
+`~/.openjarvis/anon_id`. The install script, backend, and frontend all
+read the same file so events across the full lifecycle tie to one
+person — without us ever knowing who that person is.
+
+Delete the file (`rm ~/.openjarvis/anon_id`) and a fresh UUID will be
+generated next time the app runs. The previous UUID and its events
+are then orphaned.
+
+## For researchers and contributors
+
+- **Adding an event**: edit `src/openjarvis/analytics/events.py`,
+  declare the spec, then update this page. PR review enforces both.
+- **Adding a PII pattern**: edit `src/openjarvis/analytics/redaction.py`
+  and add a test case in `tests/analytics/test_redaction.py`.
+- **Inspecting what your install sends**: run with
+  `OPENJARVIS_LOG_LEVEL=DEBUG` and grep for `Analytics`. You'll see
+  every event name and (redacted) property dict before it ships.
+
+## Related
+
+- Local telemetry (FLOPs, energy, latency stored in
+  `~/.openjarvis/telemetry.db`) is a **separate** subsystem documented
+  in [`src/openjarvis/telemetry/`](../src/openjarvis/telemetry/). It
+  never leaves the machine and is controlled by `[telemetry]` (not
+  `[analytics]`) in `config.toml`.
+- The leaderboard / contest opt-in (`OptInModal.tsx`) is a separate,
+  voluntary feature that publicly shares your energy and savings on
+  the OpenJarvis leaderboard. It is **not** the same as analytics and
+  requires explicit opt-in with a display name and email.

docs/user-guide/agents.md

@@ -13,11 +13,77 @@ 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 |
 
 ---
 
+## Persistent Persona: SOUL.md, MEMORY.md, USER.md
+
+Every agent's system prompt is assembled at conversation start by the `SystemPromptBuilder`, which injects up to three optional Markdown files -- the **persistent persona**. They are plain text you own and edit, loaded at the start of each conversation. There is no vector database or embedding cache behind them.
+
+| File | What it holds | Example line |
+|------|---------------|--------------|
+| `SOUL.md` | How the agent should behave -- tone, length, what to push back on | `Be concise. Challenge weak assumptions.` |
+| `MEMORY.md` | Facts about you, your projects, your preferences | `I deploy to Postgres, never MySQL.` |
+| `USER.md` | Who you are -- role, team, context | `Backend engineer at Acme, on the payments team.` |
+
+This persona is distinct from the retrieval [memory backend](memory.md): the persona is always-on Markdown context loaded into the prompt, while the memory backend is searchable long-term storage the agent queries on demand.
+
+### Where they live
+
+By default the files are read from the config directory:
+
+```
+~/.openjarvis/SOUL.md
+~/.openjarvis/MEMORY.md
+~/.openjarvis/USER.md
+```
+
+(The config directory honors `$OPENJARVIS_HOME` / `$XDG_DATA_HOME` when set.) The paths are configurable under `[memory_files]`:
+
+```toml
+[memory_files]
+soul_path    = "~/.openjarvis/SOUL.md"
+memory_path  = "~/.openjarvis/MEMORY.md"
+user_path    = "~/.openjarvis/USER.md"
+persona_name = ""    # optional named persona -- see below
+```
+
+### How they're loaded
+
+At the start of each conversation, `SystemPromptBuilder` reads each file as UTF-8 and adds its contents as a section of the system prompt, after the agent template and before the skill catalog:
+
+- **All three are optional.** A missing or empty file is skipped, so any subset works and an install with no persona files behaves exactly as before.
+- **Edits apply to the next conversation.** The files are read once when a conversation's prompt is built, so there is no restart or re-indexing -- edit or delete a line and it takes effect the next time you start a conversation.
+- **Each section is length-capped.** Files are truncated to a per-section character budget so a large `MEMORY.md` cannot crowd out the rest of the prompt.
+
+### Named personas
+
+A single install can answer as different personas without changing global config. A named persona lives in its own directory:
+
+```
+~/.openjarvis/personas/<name>/SOUL.md
+~/.openjarvis/personas/<name>/MEMORY.md
+~/.openjarvis/personas/<name>/USER.md
+```
+
+Select one per invocation, or opt out entirely:
+
+```bash
+jarvis ask --persona work  "summarize my open PRs"
+jarvis ask --persona none  "what is 2 + 2?"     # inject no persona
+```
+
+Set `persona_name` under `[memory_files]` to make a named persona the default. `persona_name = "none"` (equivalently `--persona none`) disables persona injection for that run.
+
+### Editing them
+
+`SOUL.md`, `MEMORY.md`, and `USER.md` are plain Markdown -- open them in any editor. `MEMORY.md` and `USER.md` can also be updated by the agent itself through the `memory_manage` and `user_profile_manage` tools when those are enabled, so the agent can record a new fact mid-conversation. These tools always target the default `MEMORY.md` and `USER.md` (under `~/.openjarvis/`), never a named persona's copies -- edit those by hand.
+
+---
+
 ## BaseAgent ABC
 
 All agents extend the abstract `BaseAgent` class.
@@ -383,6 +449,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`.

docs/user-guide/cli.md

@@ -66,6 +66,8 @@ jarvis ask "What is the capital of France?"
 | `--no-context`                | flag    | off        | Disable memory context injection                       |
 | `-a`, `--agent AGENT`         | string  | none       | Agent to use (`simple`, `orchestrator`)                |
 | `--tools TOOLS`               | string  | none       | Comma-separated tool names to enable                   |
+| `-i`, `--image PATH`          | path    | none       | Image file for a vision model (e.g. `gemma3:4b`); repeatable |
+| `-S`, `--screen`              | flag    | off        | Capture the current screen and send it to the vision model  |
 
 ### Direct Mode vs Agent Mode
 
@@ -105,6 +107,39 @@ jarvis ask --no-context "Tell me about Python"
 jarvis ask --max-tokens 2048 "Write a detailed essay about AI"
 ```
 
+### Vision Input
+
+Vision-capable models (such as `gemma3:4b`) can read images alongside your
+text prompt. Attach one or more image files with `-i`/`--image`, or capture
+the current screen with `-S`/`--screen`:
+
+```bash
+# Ask about a local image
+jarvis ask -i screenshot.png "What is shown in this image?"
+
+# Send multiple images (the flag is repeatable)
+jarvis ask -i chart-a.png -i chart-b.png "Compare these two charts"
+
+# Capture the current screen and ask about it
+jarvis ask --screen "Summarize what's on my screen"
+```
+
+Vision runs in **direct mode** only. If you also pass `--agent`, the image is
+ignored and a note is printed — re-run with `--agent ""` to force direct mode.
+
+The Ollama context window can be tuned for large images or long prompts with
+the `JARVIS_NUM_CTX` environment variable (default `16384`):
+
+```bash
+JARVIS_NUM_CTX=8192 jarvis ask --screen "What's on my screen?"
+```
+
+!!! note "Keep vision on-device"
+    Images are sensitive. OpenJarvis prints a privacy warning before sending
+    an image to a non-local engine, so a screenshot never leaves your machine
+    unnoticed. Use a local engine (e.g. `ollama` with `gemma3:4b`) to keep
+    vision fully local.
+
 ### JSON Output Format
 
 When using `--json` in **direct mode**, the output includes:

docs/user-guide/data-boundary-scan.md

@@ -0,0 +1,174 @@
+# Data-boundary scan
+
+`jarvis scan --data-boundaries` reports application-level data boundaries in the
+current OpenJarvis configuration. It complements the existing host/environment
+scan, which checks OS posture such as disk encryption, cloud-sync agents, remote
+access tools, and exposed engine ports.
+
+The data-boundary scan is a configuration diagnostic. It is not a vulnerability
+scanner, a legal privacy assessment, a network monitor, or an OAuth-scope audit.
+
+## Run the scan
+
+```bash
+jarvis scan --data-boundaries
+jarvis scan --data-boundaries --json
+jarvis scan --data-boundaries --json --show-paths
+jarvis scan --data-boundaries --strict
+```
+
+`--strict` exits with status code `1` when the report contains either a `fail`
+or a `warn` finding. Use it when CI or pre-demo checks need to enforce a
+conservative local-only posture.
+
+Without `--strict`, the command always exits `0` even when fail or warn findings
+are present. This is useful for exploratory review.
+
+On a fresh `jarvis init` configuration, common warn findings include
+`server.host = "0.0.0.0"` and `telemetry.enabled = true`. Running
+`jarvis scan --data-boundaries --strict` after init therefore exits `1` until
+those defaults are tightened.
+
+Absolute paths and connector file basenames are redacted by default so JSON
+reports can be pasted into issues without revealing local usernames, mount
+points, or account labels. Use `--show-paths` only for local debugging.
+
+## What it checks
+
+The scan inspects configuration values, environment-variable presence, and the
+existence of known local runtime files. It does not read private content from
+memory databases, trace databases, connector credentials, prompt files, logs, or
+OAuth token files.
+
+The current checks cover:
+
+- cloud-capable model provider, engine, and default model settings
+- local memory context injection combined with cloud-capable inference
+- traces, telemetry, learning, training, and spec-search settings
+- automatic memory service (`tools.storage.enabled` / `[memory].enabled`)
+- deep research engine and model settings
+- security bypass flags when cloud inference is configured
+- unset `security.profile` (informational)
+- web search, browser, local file, shell, code, knowledge chunk scanning, and MCP tool surfaces
+- local knowledge.db composition with cloud-capable Deep Research targets
+- server binding and unauthenticated A2A exposure
+- channel enablement, channel credential fields, and channel credential env vars
+- skills, skill auto-sync, digest sources, and cloud speech/TTS backends such as Cartesia
+- local stores such as `knowledge.db`, `credentials.toml`, `memory.db`, `traces.db`,
+  `telemetry.db`, `scheduler.db`, embeddings, skill index, `.vault_key`, and memory files
+- connector credential files under `connectors/*.json`, without reading them
+- API-key and other runtime credential environment variables (presence only)
+- a scope note for frontend credential storage when cloud/API-key surfaces exist
+
+Configured database paths (for example `traces.db_path` or `memory.db_path`)
+are resolved from config when set, not only the default locations under the
+OpenJarvis home directory.
+
+Static Deep Research targeting uses configuration only (no request overrides):
+`deep_research.engine` or `engine.default`, and `deep_research.model` or
+`server.model` or `intelligence.default_model`.
+
+Model identifiers that contain vendor names (for example `deepseek-r1` or
+`openai/gpt-oss`) are not treated as cloud-bound when their effective engine is
+explicitly local, such as Ollama.
+
+## Status levels
+
+| Status | Meaning |
+| --- | --- |
+| `fail` | A configuration composition is likely incompatible with strict local-only use. |
+| `warn` | A configured surface may send data outside the local runtime or persist sensitive data. |
+| `info` | A relevant setting or local store exists, with no immediate fail or warn condition. |
+
+The command reports potential data paths. It does not prove that a path has been
+used during a specific run.
+
+JSON output includes `"schema_version": 1` for stable downstream parsing.
+
+## Strict local-only checklist
+
+For a conservative local-only setup, review these settings:
+
+```toml
+[analytics]
+enabled = false
+
+[traces]
+enabled = false
+
+[telemetry]
+enabled = false
+
+[agent]
+context_from_memory = false
+
+[intelligence]
+provider = ""
+preferred_engine = ""
+default_model = ""  # local model name only
+
+[engine]
+default = "ollama"  # or another local engine
+
+[tools]
+enabled = ""
+
+[tools.storage]
+enabled = false
+
+[tools.mcp]
+enabled = false
+servers = ""
+
+[channel]
+enabled = false
+
+[learning]
+enabled = false
+auto_update = false
+training_enabled = false
+
+[learning.spec_search]
+enabled = false
+
+[server]
+host = "127.0.0.1"
+
+[security]
+profile = "personal"
+
+[a2a]
+enabled = false
+```
+
+Also unset cloud and channel credentials from the process environment when they
+are not needed.
+
+## Scope and non-goals
+
+The scan intentionally avoids reading private data. In particular, it does not:
+
+- read connector JSON contents or OAuth scopes
+- inspect browser `localStorage` or Tauri secure storage
+- inspect frontend credential storage directly
+- inspect installed skill source code
+- intercept runtime network traffic
+- classify provider retention or training policies
+- prove that a configured path was used at runtime
+
+Frontend credential storage is tracked separately from this CLI diagnostic. If a
+cloud/API-key surface is present, the scan emits an informational scope note so
+users know that browser/Tauri credential storage must be reviewed separately.
+
+## Configuration resolution
+
+The scan follows the same explicit configuration override used by the runtime:
+if `OPENJARVIS_CONFIG` is set, that file is audited. Otherwise the scan uses
+the default OpenJarvis config path under the resolved OpenJarvis home. If the
+home directory cannot be resolved, the command reports a `config-root-error`
+finding instead of crashing.
+
+## See also
+
+- [Security](security.md) — three-layer security model (host scan, config scan, BoundaryGuard)
+- [Configuration](../getting-started/configuration.md) — full config reference

docs/user-guide/evaluations.md

@@ -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,48 @@ 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
+```
+
+TauBench additionally requires Python 3.12 or newer and the upstream `tau2`
+package. Install the pinned revision explicitly before running that benchmark:
+
+```bash
+uv pip install "tau2 @ git+https://github.com/sierra-research/tau2-bench.git@fc0055dc4e0a316c3f83133267fbd6faaa770992"
+```
+
+OpenJarvis does not install third-party packages automatically when an
+evaluation is imported or run.
 
 !!! 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 +90,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 +106,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 +119,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 +163,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 +171,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 +183,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 +206,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 +315,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 +331,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 +389,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 +398,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 +482,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 +494,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 +554,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 +574,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 +595,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 +612,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 +793,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"

docs/user-guide/security.md

@@ -2,6 +2,20 @@
 
 OpenJarvis includes a security layer that scans prompts and model outputs for secrets, personally identifiable information (PII), and sensitive file paths. The system is designed to be composable: scanners run as a pipeline, and the `GuardrailsEngine` wrapper drops in front of any inference backend without changing how the rest of your code works.
 
+## Three layers of security review
+
+OpenJarvis separates host posture, application data boundaries, and runtime prompt guardrails:
+
+| Layer | Command / component | What it checks |
+| --- | --- | --- |
+| Host scan | `jarvis scan` | Disk encryption, cloud-sync agents, exposed engine ports, remote-access tools |
+| Data-boundary scan | `jarvis scan --data-boundaries` | Configured inference, memory, traces, channels, tools, and local stores |
+| Runtime guardrails | `GuardrailsEngine` / BoundaryGuard | Secrets, PII, and file-policy violations in live prompts and outputs |
+
+Use the host scan before storing sensitive data on the machine. Use the data-boundary scan to verify whether your `config.toml` is local-only, cloud-capable, or mixed. Use BoundaryGuard during inference when you need live redaction or blocking.
+
+See [Data Boundary Scan](data-boundary-scan.md) for the application config diagnostic and [BoundaryGuard](#guardrailsengine) below for runtime scanning.
+
 ---
 
 ## Overview
@@ -392,7 +406,7 @@ enforce_tool_confirmation = true
 | `secret_scanner` | `bool` | `true` | Run `SecretScanner` on all text |
 | `pii_scanner` | `bool` | `true` | Run `PIIScanner` on all text |
 | `audit_log_path` | `str` | `~/.openjarvis/audit.db` | Path to the SQLite audit log |
-| `enforce_tool_confirmation` | `bool` | `true` | Require explicit confirmation before tool execution |
+| `enforce_tool_confirmation` | `bool` | `true` | Accepted by the loader but **not currently enforced**. See [System Access](system-access.md#confirmation-behaviour) for when prompts actually happen |
 
 !!! tip "Start with warn, tighten later"
     `mode = "warn"` is a good starting point. It lets you observe what patterns are being triggered without disrupting normal usage. Switch to `"redact"` once you are satisfied that the scanner isn't producing too many false positives for your workload.
@@ -446,8 +460,15 @@ guarded = GuardrailsEngine(
 
 ---
 
+## Data boundary scan
+
+See [Data Boundary Scan](data-boundary-scan.md) for the application config diagnostic (`jarvis scan --data-boundaries`).
+
+---
+
 ## See Also
 
+- [Data Boundary Scan](data-boundary-scan.md) — application config and local-store diagnostic (`jarvis scan --data-boundaries`)
 - [Architecture: Security](../architecture/security.md) — pipeline design, event flow, and file policy integration
 - [API Reference: Security](../api-reference/openjarvis/security/index.md) — full class and function signatures
 - [Tools](tools.md) — how `FileReadTool` uses file policy

docs/user-guide/skills.md

@@ -148,6 +148,14 @@ jarvis skill sync openclaw --search "web3|crypto"
 jarvis skill install github:user/repo/path/to/skill --url https://github.com/user/repo
 ```
 
+For example, install the Hermes Tweet skill when you want an agent to search
+Twitter/X, read tweet replies, monitor tweets, export followers, and run
+gated post, reply, or DM workflows:
+
+```bash
+jarvis skill install github:Xquik-dev/hermes-tweet/skills/hermes-tweet --url https://github.com/Xquik-dev/hermes-tweet
+```
+
 ### Config-Driven Auto Import
 
 Add sources to `~/.openjarvis/config.toml` for automatic syncing:

docs/user-guide/system-access.md

@@ -0,0 +1,198 @@
+# System Access
+
+How to give an agent access to the machine it runs on, and where the real
+limits are.
+
+!!! warning
+    `shell_exec` runs arbitrary commands as your user. There is no command
+    allowlist, no denylist, and no sandbox unless you turn one on. An agent
+    holding this tool can do anything you can do from a terminal.
+
+---
+
+## Start here: you probably have no tools enabled
+
+If the agent tells you it can't run commands or read files, that's usually not
+a permissions problem. It means no tools were enabled in the first place.
+
+Tools come from `tools.enabled`, falling back to `agent.tools`. Both default to
+empty, and an empty value builds the agent with **zero tools**. Nothing is
+enabled by default.
+
+First check whether you have a config file at all:
+
+```bash
+cat ~/.openjarvis/config.toml
+```
+
+If it isn't there, that's your answer. Create it:
+
+```toml
+[engine]
+default = "ollama"
+
+[intelligence]
+default_model = "qwen3.5:9b"
+
+[agent]
+default_agent = "orchestrator"
+
+[tools]
+enabled = ["shell_exec", "file_read", "file_write", "think"]
+```
+
+There's a fuller version at
+`configs/openjarvis/examples/full-system-access.toml`.
+
+Then confirm the list actually resolved:
+
+```bash
+python -c "from openjarvis.core.config import load_config; print(load_config().tools.enabled)"
+```
+
+---
+
+## What the tools reach
+
+| Tool | Scope |
+|------|-------|
+| `shell_exec` | Any command, as your user. 30s default timeout, 300s max, output capped at 100 KB per stream. |
+| `file_read` | Any readable path. 1 MB cap. |
+| `file_write` | Any writable path. 10 MB cap, can create parent directories. |
+| `apply_patch` | Applies unified diffs to any path. |
+| `code_interpreter` | Python in a subprocess, behind a coarse pattern blocklist. |
+
+`file_read` and `file_write` take an `allowed_dirs` argument that limits them to
+a set of directories, but no config key populates it. When it's empty every path
+is allowed. If you want a filesystem jail today, use the container sandbox
+instead of relying on these tools to enforce one.
+
+### Sensitive filenames
+
+`file_read` and `file_write` refuse names matching a short glob list: `.env`,
+`*.pem`, `id_rsa`, `credentials.*` and a dozen or so others. It matches on the
+filename only, not the path or the contents, and only those two tools consult
+it. `shell_exec`, `apply_patch` and `code_interpreter` skip it entirely, so
+`cat ~/.ssh/id_rsa` through `shell_exec` works fine. Treat it as protection
+against fat fingers, not as a security boundary.
+
+---
+
+## Confirmation behaviour
+
+`shell_exec`, `git_commit` and `agent_kill` are marked `requires_confirmation`.
+What that translates to depends entirely on how you launched the agent:
+
+| Entry point | Behaviour |
+|-------------|-----------|
+| `jarvis chat` | Prompts before each call. |
+| `jarvis ask` | Auto-approves. |
+| `jarvis agent ask` | Auto-approves. Pass `--no-yes` if you want prompts. |
+| HTTP server, desktop app | Auto-approves. Tools you added to an agent's toolkit count as pre-approved. |
+| Embedded via `SystemBuilder` | No callback is wired, so these tools fail closed. |
+
+That last row catches people out. If `shell_exec` returns "requires
+confirmation but no confirmation callback is available", you're constructing the
+agent yourself and need to pass a `confirm_callback`.
+
+!!! note "`enforce_tool_confirmation` doesn't do anything"
+    The config loader accepts `security.enforce_tool_confirmation`, but nothing
+    on the tool execution path reads it. Setting it won't change confirmation
+    behaviour anywhere. Use the table above instead.
+
+---
+
+## macOS: Full Disk Access
+
+On macOS the operating system is the real boundary, not the config. Shell
+access and ordinary file access start working as soon as you enable the tools.
+TCC-protected data does not: Messages, Mail, Photos, Safari history, Contacts
+and Calendar all stay locked, and no config key will change that.
+
+Grant Full Disk Access to whichever process hosts the backend. Child processes
+inherit it:
+
+| How you run OpenJarvis | Grant access to |
+|------------------------|-----------------|
+| CLI (`jarvis ask`, `jarvis chat`) | Your terminal (Terminal, iTerm, Warp) |
+| Desktop app | `OpenJarvis.app`, which spawns `jarvis serve` beneath it |
+| launchd (`deploy/launchd/com.openjarvis.plist`) | The `jarvis` binary, as its own entry |
+
+System Settings, then Privacy & Security, then Full Disk Access, then **+**.
+
+A launchd daemon gets its own TCC context, so granting access to Terminal does
+nothing for it. Add `/usr/local/bin/jarvis` separately.
+
+To check whether the grant took:
+
+```bash
+head -c 16 ~/Library/Messages/chat.db >/dev/null 2>&1 \
+  && echo "granted" || echo "denied"
+```
+
+Restart the host process after you change the setting.
+
+### Driving Mac apps
+
+AppleScript works through `shell_exec`:
+
+```
+osascript -e 'tell application "Music" to play'
+```
+
+macOS asks for Automation permission once per target app, the first time you
+touch it.
+
+---
+
+## What you can't do
+
+There's no computer use. OpenJarvis can't see your screen, move the pointer or
+send keystrokes. No tool for it is registered and no input automation library
+appears anywhere in the codebase, so granting Accessibility or Screen Recording
+buys you nothing on its own.
+
+The `click` and `type` actions you'll find are Playwright, scoped to a browser
+page rather than the desktop.
+
+Some of this is reachable through `shell_exec` if you bring the tooling
+yourself. `screencapture` will take screenshots once you've granted Screen
+Recording, and something like `cliclick` will move the pointer. That gets you
+scripted actions. It doesn't get you an agent that looks at the screen and
+works out where to click.
+
+---
+
+## Narrowing access
+
+Access widens and narrows through `tools.enabled`. Drop entries to take
+capabilities away. That list is the whole grant.
+
+Two stronger isolation options exist. Both are off by default:
+
+```toml
+[sandbox]
+enabled = true          # run tools inside a container
+runtime = "docker"
+
+[security.capabilities]
+enabled = true          # RBAC over declared tool capabilities
+policy_path = "~/.openjarvis/policy.yaml"
+```
+
+!!! note "Capabilities are open by default even once enabled"
+    `CapabilityPolicy` is built with `default_deny=False` and no config key
+    exposes that flag, so an agent with no explicit policy entry gets every
+    capability. Write entries for every agent you mean to restrict.
+
+For anything untrusted, reach for `docker_shell_exec` and
+`code_interpreter_docker` rather than the host-side versions.
+
+---
+
+## See also
+
+- [Security](security.md) for scanners, the audit log and guardrails
+- [Tools](tools.md) for the full registry
+- [Code Assistant](code-assistant.md) for a narrower shell-enabled setup
+- [External MCP Servers](mcp-external-servers.md) for capabilities OpenJarvis doesn't ship

frontend/package.json

@@ -1,7 +1,7 @@
 {
   "name": "openjarvis-chat",
   "private": true,
-  "version": "0.1.0",
+  "version": "1.0.1",
   "type": "module",
   "engines": {
     "node": ">=20"
@@ -11,13 +11,14 @@
     "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",
     "@fontsource-variable/geist": "^5.2.8",
     "@tailwindcss/vite": "^4.2.1",
-    "@tauri-apps/api": "^2",
+    "@tauri-apps/api": "^2.11.1",
     "@tauri-apps/plugin-autostart": "^2",
     "@tauri-apps/plugin-dialog": "^2.7.0",
     "@tauri-apps/plugin-global-shortcut": "^2",
@@ -30,6 +31,7 @@
     "katex": "^0.16.38",
     "lucide-react": "^0.576.0",
     "motion": "^12.38.0",
+    "posthog-js": "^1.373.2",
     "react": "^19.0.0",
     "react-dom": "^19.0.0",
     "react-markdown": "^10.1.0",
@@ -47,12 +49,13 @@
     "zustand": "^5.0.11"
   },
   "devDependencies": {
-    "@tauri-apps/cli": "^2",
+    "@tauri-apps/cli": "^2.11.4",
     "@types/react": "^19.0.0",
     "@types/react-dom": "^19.0.0",
     "@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"
   }
 }

frontend/src-tauri/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "openjarvis-desktop"
-version = "0.1.0"
+version = "1.0.1"
 description = "OpenJarvis Desktop — Native AI assistant with energy monitoring, trace debugging, and learning visualization"
 edition = "2021"
 license = "MIT"
@@ -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"
@@ -23,9 +24,22 @@ serde_json = "1"
 reqwest = { version = "0.12", features = ["json", "multipart"] }
 tokio = { version = "1", features = ["full"] }
 
+# Cloud API keys are stored in the OS credential store via `keyring`. keyring v3
+# enables NO backend by default — without an explicit per-platform feature it
+# silently falls back to a non-persistent in-memory mock, so keys would not
+# survive an app restart. Each desktop target opts into its native store.
 [target.'cfg(target_os = "macos")'.dependencies]
 objc = "0.2"
 dispatch = "0.2"
+keyring = { version = "3", features = ["apple-native"] }
+
+[target.'cfg(target_os = "windows")'.dependencies]
+keyring = { version = "3", features = ["windows-native"] }
+
+[target.'cfg(target_os = "linux")'.dependencies]
+# Blocking Secret Service backend (no internal async runtime, so it is safe to
+# call from the tokio-driven Tauri commands). Needs libdbus-1-dev at build time.
+keyring = { version = "3", features = ["sync-secret-service", "crypto-rust"] }
 
 [features]
 default = ["custom-protocol"]

frontend/src-tauri/Info.plist

@@ -0,0 +1,14 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+  <key>NSAppTransportSecurity</key>
+  <dict>
+    <!-- The desktop API URL is user-configurable, so it cannot be represented
+         by Tauri's single, build-time exceptionDomain setting. Keep this
+         exception scoped to WKWebView; native URLSession traffic retains ATS. -->
+    <key>NSAllowsArbitraryLoadsInWebContent</key>
+    <true/>
+  </dict>
+</dict>
+</plist>

frontend/src-tauri/tauri.conf.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://schema.tauri.app/config/2",
   "productName": "OpenJarvis",
-  "version": "0.1.0",
+  "version": "1.0.1",
   "identifier": "com.openjarvis.desktop",
   "build": {
     "frontendDist": "../dist",
@@ -24,7 +24,7 @@
       }
     ],
     "security": {
-      "csp": "default-src 'self'; script-src 'self' 'unsafe-inline'; style-src 'self' 'unsafe-inline'; connect-src 'self' http://localhost:* http://127.0.0.1:* ws://localhost:* ws://127.0.0.1:*; img-src 'self' data: blob:"
+      "csp": "default-src 'self'; script-src 'self' 'unsafe-inline'; style-src 'self' 'unsafe-inline'; connect-src 'self' http: https: ws: wss:; img-src 'self' data: blob:"
     }
   },
   "bundle": {
@@ -45,7 +45,6 @@
     "macOS": {
       "entitlements": "Entitlements.plist",
       "minimumSystemVersion": "10.15",
-      "exceptionDomain": "",
       "frameworks": [],
       "providerShortName": null,
       "signingIdentity": "-"
@@ -58,9 +57,11 @@
   },
   "plugins": {
     "updater": {
-      "active": false,
+      "active": true,
       "pubkey": "dW50cnVzdGVkIGNvbW1lbnQ6IG1pbmlzaWduIHB1YmxpYyBrZXk6IDFFNzUzMzhEOEY2MjNEMDMKUldRRFBXS1BqVE4xSG8vK0lkUWN4WnZQYVIrbmc4RmpoOGlJWTBLTE15RlIya3JvQisvdUR3a0QK",
-      "endpoints": []
+      "endpoints": [
+        "https://github.com/open-jarvis/OpenJarvis/releases/download/desktop-latest/latest.json"
+      ]
     },
     "deep-link": {
       "desktop": {

frontend/src/App.tsx

@@ -14,13 +14,23 @@ import { Toaster } from './components/ui/sonner';
 import { useAppStore } from './lib/store';
 import { fetchModels, fetchServerInfo, fetchSavings, submitSavings, isTauri } from './lib/api';
 import { OptInModal } from './components/OptInModal';
+import { UpdateChecker } from './components/Desktop/UpdateChecker';
+import { track, hashId } from './lib/analytics';
 
 export default function App() {
   const [setupDone, setSetupDone] = useState(!isTauri());
-  const handleSetupReady = useCallback(() => setSetupDone(true), []);
+  const handleSetupReady = useCallback(() => {
+    setSetupDone(true);
+    // 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);
   const setModelsLoading = useAppStore((s) => s.setModelsLoading);
-  const setSelectedModel = useAppStore((s) => s.setSelectedModel);
   const selectedModel = useAppStore((s) => s.selectedModel);
   const setServerInfo = useAppStore((s) => s.setServerInfo);
   const setSavings = useAppStore((s) => s.setSavings);
@@ -59,7 +69,6 @@ export default function App() {
     fetchModels()
       .then((m) => {
         setModels(m);
-        if (!selectedModel && m.length > 0) setSelectedModel(m[0].id);
       })
       .catch(() => setModels([]))
       .finally(() => setModelsLoading(false));
@@ -78,7 +87,7 @@ export default function App() {
           setSavings(data);
           if (optInEnabled && optInDisplayName && data) {
             const claudeEntry = data.per_provider.find(
-              (p) => p.provider === 'claude-opus-4.6',
+              (p) => p.provider === 'claude-fable-5',
             );
             const dollarSavings = claudeEntry ? claudeEntry.total_cost : 0;
             const energySaved = data.per_provider.reduce(
@@ -116,6 +125,36 @@ export default function App() {
     }
   }, []); // eslint-disable-line react-hooks/exhaustive-deps
 
+  // Fire model_changed when the user switches models. First mount is
+  // not a "change" — only emit when both prev and current are real and
+  // differ.
+  useEffect(() => {
+    const prev = prevModelRef.current;
+    const curr = selectedModel || '';
+    prevModelRef.current = curr;
+    if (!prev || !curr || prev === curr) return;
+    void (async () => {
+      const [fromHash, toHash] = await Promise.all([
+        hashId(prev),
+        hashId(curr),
+      ]);
+      track('model_changed', {
+        from_model_hash: fromHash,
+        to_model_hash: toHash,
+      });
+    })();
+  }, [selectedModel]);
+
+  // app_opened — one-shot per app launch, fires after analytics has had
+  // a chance to initialize. platform + version are super-properties
+  // registered in analytics.ts initAnalytics, so no per-call props needed.
+  useEffect(() => {
+    const t = setTimeout(() => {
+      track('app_opened', {});
+    }, 500);
+    return () => clearTimeout(t);
+  }, []);
+
   const toggleSystemPanel = useAppStore((s) => s.toggleSystemPanel);
 
   // Global keyboard shortcuts
@@ -134,34 +173,6 @@ export default function App() {
     return () => window.removeEventListener('keydown', handleKeyDown);
   }, [commandPaletteOpen, setCommandPaletteOpen, toggleSystemPanel]);
 
-  // Desktop auto-update check — disabled during local development.
-  // Re-enable for production releases by uncommenting below.
-  // const updateChecked = useRef(false);
-  // useEffect(() => {
-  //   if (!isTauri() || updateChecked.current) return;
-  //   updateChecked.current = true;
-  //   (async () => {
-  //     try {
-  //       const { check } = await import('@tauri-apps/plugin-updater');
-  //       const update = await check();
-  //       if (update) {
-  //         await update.downloadAndInstall();
-  //         const { toast } = await import('sonner');
-  //         toast.info('Update ready', {
-  //           description: 'A new version has been downloaded. Restart to apply.',
-  //           duration: Infinity,
-  //           action: {
-  //             label: 'Restart Now',
-  //             onClick: async () => {
-  //               const { relaunch } = await import('@tauri-apps/plugin-process');
-  //               await relaunch();
-  //             },
-  //           },
-  //         });
-  //       }
-  //     } catch {}
-  //   })();
-  // }, []);
 
   if (!setupDone) {
     return <SetupScreen onReady={handleSetupReady} />;
@@ -169,6 +180,7 @@ export default function App() {
 
   return (
     <>
+      <UpdateChecker />
       <Routes>
         <Route element={<Layout />}>
           <Route index element={<ChatPage />} />

frontend/src/components/ApprovalBell.tsx

@@ -0,0 +1,264 @@
+import { useCallback, useEffect, useRef, useState } from 'react';
+import { Bell, CheckCircle, ChevronDown, ChevronUp, Clock, XCircle } from 'lucide-react';
+import { approveAction, denyAction, fetchPendingApprovals } from '../lib/api';
+import type { PendingApproval } from '../lib/api';
+
+const TIER_STYLES: Record<string, { label: string; color: string; bg: string }> = {
+  trivial: { label: 'Trivial', color: 'var(--color-text-secondary)', bg: 'color-mix(in srgb, var(--color-text-secondary) 10%, transparent)' },
+  low:     { label: 'Low',     color: '#3b82f6',                    bg: 'rgba(59,130,246,0.12)' },
+  medium:  { label: 'Medium',  color: 'var(--color-warning)',       bg: 'color-mix(in srgb, var(--color-warning) 12%, transparent)' },
+  high:    { label: 'High',    color: 'var(--color-error)',         bg: 'color-mix(in srgb, var(--color-error) 12%, transparent)' },
+};
+
+function timeAgo(iso: string): string {
+  const diff = Date.now() - new Date(iso).getTime();
+  const m = Math.floor(diff / 60000);
+  if (m < 1) return 'just now';
+  if (m < 60) return `${m}m ago`;
+  const h = Math.floor(m / 60);
+  if (h < 24) return `${h}h ago`;
+  return `${Math.floor(h / 24)}d ago`;
+}
+
+export function ApprovalBell() {
+  const [approvals, setApprovals] = useState<PendingApproval[]>([]);
+  const [open, setOpen] = useState(false);
+  const [expanded, setExpanded] = useState<Record<string, boolean>>({});
+  const [processing, setProcessing] = useState<Record<string, boolean>>({});
+  const containerRef = useRef<HTMLDivElement>(null);
+
+  const load = useCallback(async () => {
+    try {
+      setApprovals(await fetchPendingApprovals());
+    } catch {
+      // backend may not be running yet
+    }
+  }, []);
+
+  useEffect(() => {
+    load();
+    const id = setInterval(load, 10000);
+    return () => clearInterval(id);
+  }, [load]);
+
+  useEffect(() => {
+    if (!open) return;
+    const handler = (e: MouseEvent) => {
+      if (containerRef.current && !containerRef.current.contains(e.target as Node)) {
+        setOpen(false);
+      }
+    };
+    document.addEventListener('mousedown', handler);
+    return () => document.removeEventListener('mousedown', handler);
+  }, [open]);
+
+  const handleApprove = async (id: string) => {
+    setProcessing(p => ({ ...p, [id]: true }));
+    try {
+      await approveAction(id);
+      setApprovals(prev => prev.filter(a => a.id !== id));
+    } finally {
+      setProcessing(p => ({ ...p, [id]: false }));
+    }
+  };
+
+  const handleDeny = async (id: string) => {
+    setProcessing(p => ({ ...p, [id]: true }));
+    try {
+      await denyAction(id);
+      setApprovals(prev => prev.filter(a => a.id !== id));
+    } finally {
+      setProcessing(p => ({ ...p, [id]: false }));
+    }
+  };
+
+  const count = approvals.length;
+
+  return (
+    <div ref={containerRef} className="fixed top-2 right-3 z-40">
+      {/* Bell trigger */}
+      <button
+        onClick={() => setOpen(o => !o)}
+        className="relative p-2 rounded-lg transition-colors cursor-pointer"
+        title="Agent approvals"
+        style={{
+          color: count > 0 ? 'var(--color-text)' : 'var(--color-text-secondary)',
+          background: open
+            ? 'var(--color-bg-tertiary)'
+            : count > 0
+            ? 'color-mix(in srgb, var(--color-error) 8%, transparent)'
+            : 'transparent',
+        }}
+      >
+        <Bell size={17} />
+        {count > 0 && (
+          <span
+            className="absolute -top-0.5 -right-0.5 min-w-[16px] h-4 flex items-center justify-center rounded-full text-[10px] font-bold px-1 leading-none"
+            style={{ background: 'var(--color-error)', color: '#fff' }}
+          >
+            {count > 99 ? '99+' : count}
+          </span>
+        )}
+      </button>
+
+      {/* Dropdown */}
+      {open && (
+        <div
+          className="absolute right-0 top-full mt-1 rounded-xl shadow-2xl overflow-hidden flex flex-col"
+          style={{
+            width: '340px',
+            maxHeight: '500px',
+            background: 'var(--color-bg-secondary)',
+            border: '1px solid var(--color-border)',
+          }}
+        >
+          {/* Header */}
+          <div
+            className="flex items-center justify-between px-4 py-3 shrink-0"
+            style={{ borderBottom: '1px solid var(--color-border)' }}
+          >
+            <div className="flex items-center gap-2">
+              <Bell size={13} style={{ color: 'var(--color-accent)' }} />
+              <span className="text-sm font-semibold" style={{ color: 'var(--color-text)' }}>
+                Agent Approvals
+              </span>
+            </div>
+            {count > 0 && (
+              <span
+                className="text-[11px] font-medium px-2 py-0.5 rounded-full"
+                style={{
+                  background: 'color-mix(in srgb, var(--color-error) 12%, transparent)',
+                  color: 'var(--color-error)',
+                }}
+              >
+                {count} pending
+              </span>
+            )}
+          </div>
+
+          {/* Body */}
+          <div className="overflow-y-auto flex-1">
+            {count === 0 ? (
+              <div className="flex flex-col items-center justify-center py-12 gap-2">
+                <CheckCircle size={26} style={{ color: 'var(--color-text-secondary)', opacity: 0.35 }} />
+                <span className="text-sm" style={{ color: 'var(--color-text-secondary)' }}>
+                  No pending approvals
+                </span>
+              </div>
+            ) : (
+              approvals.map((action, idx) => {
+                const tier = TIER_STYLES[action.tier] ?? TIER_STYLES.medium;
+                const isExpanded = !!expanded[action.id];
+                const isLoading = !!processing[action.id];
+                const hasPayload = Object.keys(action.payload ?? {}).length > 0;
+
+                return (
+                  <div
+                    key={action.id}
+                    className="px-4 py-3"
+                    style={{
+                      borderBottom: idx < count - 1 ? '1px solid var(--color-border)' : 'none',
+                    }}
+                  >
+                    {/* Row 1: action type + tier + time */}
+                    <div className="flex items-center justify-between mb-1.5">
+                      <span
+                        className="text-[11px] font-mono font-semibold"
+                        style={{ color: 'var(--color-accent)' }}
+                      >
+                        {action.action_type}
+                      </span>
+                      <div className="flex items-center gap-2">
+                        <span
+                          className="text-[10px] font-semibold uppercase tracking-wider px-1.5 py-0.5 rounded"
+                          style={{ background: tier.bg, color: tier.color }}
+                        >
+                          {tier.label}
+                        </span>
+                        <span
+                          className="text-[10px] flex items-center gap-0.5"
+                          style={{ color: 'var(--color-text-secondary)' }}
+                        >
+                          <Clock size={9} />
+                          {timeAgo(action.created_at)}
+                        </span>
+                      </div>
+                    </div>
+
+                    {/* Description */}
+                    <p
+                      className="text-[13px] mb-2.5 leading-snug"
+                      style={{ color: 'var(--color-text)' }}
+                    >
+                      {action.description}
+                    </p>
+
+                    {/* Expandable payload */}
+                    {hasPayload && (
+                      <button
+                        className="flex items-center gap-1 text-[11px] mb-2 cursor-pointer"
+                        style={{ color: 'var(--color-text-secondary)' }}
+                        onClick={() =>
+                          setExpanded(e => ({ ...e, [action.id]: !e[action.id] }))
+                        }
+                      >
+                        {isExpanded ? <ChevronUp size={11} /> : <ChevronDown size={11} />}
+                        {isExpanded ? 'Hide details' : 'View details'}
+                      </button>
+                    )}
+
+                    {isExpanded && (
+                      <pre
+                        className="text-[10px] rounded-lg p-2.5 mb-2.5 overflow-x-auto"
+                        style={{
+                          background: 'var(--color-bg-tertiary)',
+                          color: 'var(--color-text-secondary)',
+                          fontFamily: 'monospace',
+                          whiteSpace: 'pre-wrap',
+                          wordBreak: 'break-all',
+                          lineHeight: '1.5',
+                        }}
+                      >
+                        {JSON.stringify(action.payload, null, 2)}
+                      </pre>
+                    )}
+
+                    {/* Approve / Deny */}
+                    <div className="flex gap-2">
+                      <button
+                        onClick={() => handleApprove(action.id)}
+                        disabled={isLoading}
+                        className="flex-1 flex items-center justify-center gap-1.5 py-1.5 rounded-lg text-xs font-semibold transition-opacity cursor-pointer disabled:opacity-40"
+                        style={{
+                          background: 'color-mix(in srgb, var(--color-success) 12%, transparent)',
+                          color: 'var(--color-success)',
+                          border: '1px solid color-mix(in srgb, var(--color-success) 22%, transparent)',
+                        }}
+                      >
+                        <CheckCircle size={12} />
+                        Approve
+                      </button>
+                      <button
+                        onClick={() => handleDeny(action.id)}
+                        disabled={isLoading}
+                        className="flex-1 flex items-center justify-center gap-1.5 py-1.5 rounded-lg text-xs font-semibold transition-opacity cursor-pointer disabled:opacity-40"
+                        style={{
+                          background: 'color-mix(in srgb, var(--color-error) 12%, transparent)',
+                          color: 'var(--color-error)',
+                          border: '1px solid color-mix(in srgb, var(--color-error) 22%, transparent)',
+                        }}
+                      >
+                        <XCircle size={12} />
+                        Deny
+                      </button>
+                    </div>
+                  </div>
+                );
+              })
+            )}
+          </div>
+        </div>
+      )}
+    </div>
+  );
+}

frontend/src/components/Chat/ChatArea.tsx

@@ -15,6 +15,7 @@ function getGreeting(): string {
 }
 
 export function ChatArea() {
+  const activeId = useAppStore((s) => s.activeId);
   const messages = useAppStore((s) => s.messages);
   const streamState = useAppStore((s) => s.streamState);
   const systemPanelOpen = useAppStore((s) => s.systemPanelOpen);
@@ -22,6 +23,10 @@ export function ChatArea() {
   const navigate = useNavigate();
   const listRef = useRef<HTMLDivElement>(null);
   const shouldAutoScroll = useRef(true);
+  const wasStreaming = useRef(false);
+  const lastScrollTop = useRef(0);
+  const isCurrentChatStreaming = streamState.isStreaming && streamState.conversationId === activeId;
+  const currentStreamContent = isCurrentChatStreaming ? streamState.content : '';
 
   // Check if any data sources are connected
   const [hasConnectedSources, setHasConnectedSources] = useState<boolean | null>(null);
@@ -34,18 +39,37 @@ export function ChatArea() {
   }, []);
 
   useEffect(() => {
+    // Sending a message always pins the view to the bottom, even if the
+    // user had scrolled up to read earlier messages.
+    if (isCurrentChatStreaming && !wasStreaming.current) {
+      shouldAutoScroll.current = true;
+    }
+    wasStreaming.current = isCurrentChatStreaming;
     if (shouldAutoScroll.current && listRef.current) {
       listRef.current.scrollTop = listRef.current.scrollHeight;
     }
-  }, [messages, streamState.content]);
+  }, [messages, currentStreamContent, isCurrentChatStreaming]);
 
   const handleScroll = () => {
     if (!listRef.current) return;
     const { scrollTop, scrollHeight, clientHeight } = listRef.current;
-    shouldAutoScroll.current = scrollHeight - scrollTop - clientHeight < 100;
+    const distance = scrollHeight - scrollTop - clientHeight;
+    const scrolledUp = scrollTop < lastScrollTop.current;
+    lastScrollTop.current = scrollTop;
+    if (scrolledUp && distance >= 1) {
+      // Any upward scroll away from the bottom stops autoscroll immediately,
+      // so streaming content never fights the user (no jitter). Sub-1px
+      // upward movement (elastic bounce settling at the bottom) is ignored.
+      shouldAutoScroll.current = false;
+    } else if (!scrolledUp) {
+      // Re-engage when scrolled back to the bottom. < 2 rather than < 1:
+      // at fractional zoom levels the at-bottom residual can reach 1px,
+      // which would otherwise leave autoscroll permanently disengaged.
+      shouldAutoScroll.current = distance < 2;
+    }
   };
 
-  const isEmpty = messages.length === 0 && !streamState.isStreaming;
+  const isEmpty = messages.length === 0 && !isCurrentChatStreaming;
 
   const PanelIcon = systemPanelOpen ? PanelRightClose : PanelRightOpen;
 
@@ -146,14 +170,29 @@ export function ChatArea() {
           </div>
         ) : (
           <div className="max-w-[var(--chat-max-width)] mx-auto px-4 py-6">
-            {messages.map((msg) => (
-              <MessageBubble key={msg.id} message={msg} />
-            ))}
-            {streamState.isStreaming && streamState.content === '' && (
-              <div className="flex justify-start mb-4">
-                <StreamingDots phase={streamState.phase} />
-              </div>
-            )}
+            {messages.map((msg, i) => {
+              const isLastAssistant =
+                i === messages.length - 1 && msg.role === 'assistant';
+              return (
+                <MessageBubble
+                  key={msg.id}
+                  message={msg}
+                  isLive={isLastAssistant && isCurrentChatStreaming}
+                />
+              );
+            })}
+            {(() => {
+              if (!isCurrentChatStreaming || streamState.content !== '') return null;
+              // For research messages the ResearchTimeline handles its own
+              // pre-content loading state — suppress the generic dots.
+              const last = messages[messages.length - 1];
+              if (last?.role === 'assistant' && last.isResearch) return null;
+              return (
+                <div className="flex justify-start mb-4">
+                  <StreamingDots phase={streamState.phase} />
+                </div>
+              );
+            })()}
           </div>
         )}
       </div>

frontend/src/components/Chat/InputArea.tsx

@@ -1,11 +1,79 @@
 import { useState, useRef, useCallback, useEffect } from 'react';
-import { Send, Square, Paperclip } from 'lucide-react';
+import { Send, Square, Paperclip, Search } from 'lucide-react';
+import { toast } from 'sonner';
 import { useAppStore, generateId } from '../../lib/store';
-import { streamChat } from '../../lib/sse';
+import { streamChat, streamResearch } from '../../lib/sse';
 import { fetchSavings, getBase } from '../../lib/api';
+import { listConnectors, getSyncStatus } from '../../lib/connectors-api';
+import { serializeToolCallArguments } from '../../lib/tool-call';
 import { MicButton } from './MicButton';
 import { useSpeech } from '../../hooks/useSpeech';
-import type { ChatMessage, ToolCallInfo, TokenUsage, MessageTelemetry } from '../../types';
+import type {
+  ChatMessage,
+  MessageTelemetry,
+  ResearchSearchTrace,
+  ResearchSource,
+  TokenUsage,
+  ToolCallInfo,
+} from '../../types';
+
+// While Deep Research is toggled on, poll connected sources for sync
+// progress so we can surface "Searching over N items — sync in progress"
+// next to the toggle. Polling is gated on `enabled` so toggling DR off
+// stops the network chatter immediately.
+function useResearchCorpusSync(enabled: boolean): {
+  syncing: boolean;
+  itemsSynced: number;
+} {
+  const [state, setState] = useState({ syncing: false, itemsSynced: 0 });
+
+  useEffect(() => {
+    if (!enabled) {
+      setState({ syncing: false, itemsSynced: 0 });
+      return;
+    }
+    let cancelled = false;
+
+    const poll = async () => {
+      try {
+        const list = await listConnectors();
+        const connected = list.filter((c) => c.connected);
+        if (connected.length === 0) {
+          if (!cancelled) setState({ syncing: false, itemsSynced: 0 });
+          return;
+        }
+        const results = await Promise.all(
+          connected.map(async (c) => {
+            try {
+              return await getSyncStatus(c.connector_id);
+            } catch {
+              return null;
+            }
+          }),
+        );
+        let syncing = false;
+        let itemsSynced = 0;
+        for (const r of results) {
+          if (!r) continue;
+          if (r.state === 'syncing') syncing = true;
+          itemsSynced += r.items_synced ?? 0;
+        }
+        if (!cancelled) setState({ syncing, itemsSynced });
+      } catch {
+        // Network blip — leave previous state intact.
+      }
+    };
+
+    poll();
+    const interval = setInterval(poll, 5000);
+    return () => {
+      cancelled = true;
+      clearInterval(interval);
+    };
+  }, [enabled]);
+
+  return state;
+}
 
 export function InputArea() {
   const [input, setInput] = useState('');
@@ -26,8 +94,18 @@ export function InputArea() {
   const setStreamState = useAppStore((s) => s.setStreamState);
   const resetStream = useAppStore((s) => s.resetStream);
   const modelLoading = useAppStore((s) => s.modelLoading);
+  const deepResearch = useAppStore((s) => s.deepResearch);
+  const setDeepResearch = useAppStore((s) => s.setDeepResearch);
+  const corpusSync = useResearchCorpusSync(deepResearch);
+  const isCurrentChatStreaming = streamState.isStreaming && streamState.conversationId === activeId;
 
-  const { state: speechState, available: speechAvailable, startRecording, stopRecording } = useSpeech();
+  const {
+    state: speechState,
+    error: speechError,
+    available: speechAvailable,
+    startRecording,
+    stopRecording,
+  } = useSpeech();
 
   // Abort in-flight stream when the user switches models mid-generation.
   // This prevents errors from trying to continue a stream with a stale model.
@@ -52,6 +130,12 @@ export function InputArea() {
     : streamState.isStreaming ? 'streaming'
     : undefined;
 
+  useEffect(() => {
+    if (speechError) {
+      toast.error(speechError, { duration: 8000 });
+    }
+  }, [speechError]);
+
   const handleMicClick = useCallback(async () => {
     if (speechState === 'recording') {
       try {
@@ -86,6 +170,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('');
 
@@ -114,6 +202,7 @@ export function InputArea() {
       role: 'assistant',
       content: '',
       timestamp: Date.now(),
+      isResearch: deepResearch || undefined,
     };
     addMessage(convId, assistantMsg);
 
@@ -131,12 +220,17 @@ export function InputArea() {
     let usage: TokenUsage | undefined;
     let complexity: { score: number; tier: string; suggested_max_tokens: number } | undefined;
     const toolCalls: ToolCallInfo[] = [];
+    const researchTraces: ResearchSearchTrace[] = [];
+    const researchSourcesByRef = new Map<number, ResearchSource>();
+    const flushSources = () =>
+      Array.from(researchSourcesByRef.values()).sort((a, b) => a.ref - b.ref);
     let lastFlush = 0;
     let ttftMs: number | undefined;
 
     setStreamState({
+      conversationId: convId,
       isStreaming: true,
-      phase: 'Generating...',
+      phase: deepResearch ? 'Researching...' : 'Generating...',
       elapsedMs: 0,
       activeToolCalls: [],
       content: '',
@@ -145,10 +239,137 @@ export function InputArea() {
       timestamp: Date.now(),
       level: 'info',
       category: 'chat',
-      message: `Request: "${content.slice(0, 80)}${content.length > 80 ? '...' : ''}" → ${selectedModel}`,
+      message: deepResearch
+        ? `Research: "${content.slice(0, 80)}${content.length > 80 ? '...' : ''}"`
+        : `Request: "${content.slice(0, 80)}${content.length > 80 ? '...' : ''}" → ${selectedModel}`,
     });
 
     try {
+      if (deepResearch) {
+        for await (const ev of streamResearch(
+          content,
+          selectedModel,
+          controller.signal,
+        )) {
+          if (ev.type === 'search_call') {
+            const trace: ResearchSearchTrace = {
+              id: generateId(),
+              query: ev.arguments?.query ?? '',
+              person: ev.arguments?.person,
+              timeRange: ev.arguments?.time_range,
+              status: 'pending',
+            };
+            researchTraces.push(trace);
+            setStreamState({ phase: `Searching: ${trace.query}` });
+            updateLastAssistant(
+              convId,
+              accumulatedContent,
+              undefined,
+              undefined,
+              undefined,
+              undefined,
+              [...researchTraces],
+              flushSources(),
+            );
+            useAppStore.getState().addLogEntry({
+              timestamp: Date.now(),
+              level: 'info',
+              category: 'tool',
+              message: `Search: "${trace.query}"${trace.person ? ` (person: ${trace.person})` : ''}`,
+            });
+          } else if (ev.type === 'search_result') {
+            const pending = [...researchTraces].reverse().find((t) => t.status === 'pending');
+            if (pending) {
+              pending.status = 'complete';
+              pending.numHits = ev.num_hits;
+              pending.topTitles = ev.top_titles;
+            }
+            if (ev.sources) {
+              for (const src of ev.sources) {
+                if (src && typeof src.ref === 'number' && !researchSourcesByRef.has(src.ref)) {
+                  researchSourcesByRef.set(src.ref, src);
+                }
+              }
+            }
+            updateLastAssistant(
+              convId,
+              accumulatedContent,
+              undefined,
+              undefined,
+              undefined,
+              undefined,
+              [...researchTraces],
+              flushSources(),
+            );
+          } else if (ev.type === 'synthesis') {
+            if (!ttftMs) ttftMs = Date.now() - startTime;
+            accumulatedContent += ev.text;
+            setStreamState({ content: accumulatedContent, phase: '' });
+            const now = Date.now();
+            if (now - lastFlush >= 80) {
+              updateLastAssistant(
+                convId,
+                accumulatedContent,
+                undefined,
+                undefined,
+                undefined,
+                undefined,
+                [...researchTraces],
+                flushSources(),
+              );
+              lastFlush = now;
+            }
+          } else if (ev.type === 'system_metrics') {
+            // Live GPU sample — feed straight to the System panel so Power
+            // (W) and Energy (kJ) tick up in real time as the agent runs.
+            useAppStore.getState().setLiveEnergy({
+              power_w: ev.power_w,
+              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 = {
+                prompt_tokens: ev.usage.prompt_tokens ?? 0,
+                completion_tokens: ev.usage.completion_tokens ?? 0,
+                total_tokens:
+                  ev.usage.total_tokens ??
+                  (ev.usage.prompt_tokens ?? 0) +
+                    (ev.usage.completion_tokens ?? 0),
+              };
+              // Optimistically roll this research turn into the session
+              // counters so the Session panel updates the moment the
+              // stream finishes, regardless of how /v1/savings aggregates
+              // research telemetry server-side.
+              useAppStore.getState().incrementSavings(usage);
+            }
+            // Hold the final live numbers visible for a beat so the panel
+            // doesn't flash to 0 between the SSE close and the next
+            // /v1/telemetry/energy poll picking up the persisted record.
+            window.setTimeout(() => {
+              useAppStore.getState().setLiveEnergy(null);
+            }, 1500);
+            break;
+          }
+        }
+      } else {
       for await (const sseEvent of streamChat(
         { model: selectedModel, messages: apiMessages, stream: true, temperature, max_tokens: maxTokens },
         controller.signal,
@@ -169,7 +390,7 @@ export function InputArea() {
             const tc: ToolCallInfo = {
               id: generateId(),
               tool: data.tool,
-              arguments: data.arguments || '',
+              arguments: serializeToolCallArguments(data.arguments),
               status: 'running',
             };
             toolCalls.push(tc);
@@ -180,7 +401,7 @@ export function InputArea() {
             updateLastAssistant(convId, accumulatedContent, [...toolCalls]);
             useAppStore.getState().addLogEntry({
               timestamp: Date.now(), level: 'info', category: 'tool',
-              message: `Calling ${data.tool}(${data.arguments || ''})`,
+              message: `Calling ${data.tool}(${serializeToolCallArguments(data.arguments)})`,
             });
           } catch {}
         } else if (eventName === 'tool_call_end') {
@@ -225,6 +446,7 @@ export function InputArea() {
           } catch {}
         }
       }
+      }
     } catch (err: any) {
       if (err.name === 'AbortError') {
         // User cancelled or model switch — keep whatever was accumulated
@@ -238,13 +460,19 @@ export function InputArea() {
           message: `Stream error: ${errMsg}`,
         });
       }
+      // If we tore out mid-research, make sure the live System panel
+      // numbers don't get stuck on the last sample.
+      useAppStore.getState().setLiveEnergy(null);
     } finally {
       if (!accumulatedContent) {
         accumulatedContent = 'No response was generated. Please try again.';
       }
       const totalMs = Date.now() - startTime;
       const _CLOUD_PREFIXES = ['gpt-', 'o1-', 'o3-', 'o4-', 'claude-', 'gemini-', 'openrouter/', 'MiniMax-', 'chatgpt-'];
-      const engineLabel = _CLOUD_PREFIXES.some(p => selectedModel.startsWith(p)) ? 'cloud' : 'ollama';
+      const selectedOwner = useAppStore.getState().models.find((m) => m.id === selectedModel)?.owned_by;
+      const engineLabel = selectedOwner === 'litellm'
+        ? 'litellm'
+        : _CLOUD_PREFIXES.some(p => selectedModel.startsWith(p)) ? 'cloud' : 'ollama';
       const telemetry: MessageTelemetry = {
         engine: engineLabel,
         model_id: selectedModel,
@@ -278,6 +506,8 @@ export function InputArea() {
         usage,
         telemetry,
         audioMeta,
+        researchTraces.length > 0 ? researchTraces : undefined,
+        researchSourcesByRef.size > 0 ? flushSources() : undefined,
       );
       if (timerRef.current) {
         clearInterval(timerRef.current);
@@ -290,9 +520,15 @@ export function InputArea() {
       });
       abortRef.current = null;
 
-      fetchSavings()
-        .then((data) => useAppStore.getState().setSavings(data))
-        .catch(() => {});
+      // Research path updates session counters optimistically from the
+      // `done` event's usage payload — re-fetching here would overwrite
+      // it with a potentially stale snapshot if the server's research
+      // telemetry hasn't been merged into /v1/savings yet.
+      if (!deepResearch) {
+        fetchSavings()
+          .then((data) => useAppStore.getState().setSavings(data))
+          .catch(() => {});
+      }
     }
   }, [
     input,
@@ -304,6 +540,9 @@ export function InputArea() {
     updateLastAssistant,
     setStreamState,
     resetStream,
+    deepResearch,
+    temperature,
+    maxTokens,
   ]);
 
   const handleKeyDown = (e: React.KeyboardEvent) => {
@@ -315,6 +554,38 @@ export function InputArea() {
 
   return (
     <div className="px-4 pb-4 pt-2" style={{ maxWidth: 'var(--chat-max-width)', margin: '0 auto', width: '100%' }}>
+      <div className="mb-2 flex flex-col gap-1">
+        <div className="flex items-center gap-2">
+          <button
+            type="button"
+            onClick={() => setDeepResearch(!deepResearch)}
+            disabled={streamState.isStreaming}
+            aria-pressed={deepResearch}
+            className="inline-flex items-center gap-1.5 px-2.5 py-1 rounded-full text-xs transition-colors cursor-pointer disabled:cursor-default disabled:opacity-50"
+            style={{
+              background: deepResearch ? 'var(--color-accent-subtle)' : 'transparent',
+              border: `1px solid ${deepResearch ? 'var(--color-accent)' : 'var(--color-border)'}`,
+              color: deepResearch ? 'var(--color-accent)' : 'var(--color-text-tertiary)',
+            }}
+            title={deepResearch ? 'Deep Research: on' : 'Deep Research: off'}
+          >
+            <Search size={12} />
+            Deep Research
+          </button>
+        </div>
+        {deepResearch && corpusSync.syncing && corpusSync.itemsSynced > 0 && (
+          <div
+            className="text-[11px] leading-snug"
+            style={{ color: 'var(--color-text-tertiary)' }}
+          >
+            Searching over{' '}
+            <span key={corpusSync.itemsSynced} className="sync-bump" style={{ color: 'var(--color-text-secondary)' }}>
+              {corpusSync.itemsSynced.toLocaleString()}
+            </span>{' '}
+            items — sync in progress, results will improve as more data is indexed.
+          </div>
+        )}
+      </div>
       <div
         className="flex items-center gap-2 rounded-2xl px-4 py-3 transition-shadow"
         style={{
@@ -328,13 +599,13 @@ 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' }}
           disabled={streamState.isStreaming || modelLoading}
         />
-        {streamState.isStreaming ? (
+        {isCurrentChatStreaming ? (
           <button
             onClick={stopStreaming}
             className="p-2 rounded-xl transition-colors shrink-0 cursor-pointer"
@@ -353,13 +624,13 @@ export function InputArea() {
             />
             <button
               onClick={sendMessage}
-              disabled={!input.trim() || modelLoading}
+              disabled={streamState.isStreaming || !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>

frontend/src/components/Chat/MessageBubble.tsx

@@ -8,6 +8,8 @@ import 'katex/dist/katex.min.css';
 import { Copy, Check } from 'lucide-react';
 import { AudioPlayer } from './AudioPlayer';
 import { ToolCallCard } from './ToolCallCard';
+import { ResearchTimeline } from './ResearchTimeline';
+import { rehypeCitations } from '../../lib/rehype-citations';
 import { XRayFooter } from './XRayFooter';
 import type { ChatMessage } from '../../types';
 
@@ -19,6 +21,7 @@ function stripThinkTags(text: string): string {
 
 interface Props {
   message: ChatMessage;
+  isLive?: boolean;
 }
 
 function getTextContent(node: any): string {
@@ -97,9 +100,27 @@ function CopyMessageButton({ content }: { content: string }) {
   );
 }
 
-export function MessageBubble({ message }: Props) {
+export function MessageBubble({ message, isLive = false }: Props) {
   const isUser = message.role === 'user';
 
+  const cleanContent = useMemo(() => stripThinkTags(message.content), [message.content]);
+
+  // Build a ref→source lookup once per render. Memoized so the rehype plugin
+  // identity stays stable until the source list actually changes.
+  const sourcesMap = useMemo(() => {
+    const m = new Map<number, NonNullable<ChatMessage['researchSources']>[number]>();
+    for (const s of message.researchSources ?? []) {
+      if (typeof s.ref === 'number') m.set(s.ref, s);
+    }
+    return m;
+  }, [message.researchSources]);
+
+  const rehypePlugins = useMemo(() => {
+    const base: any[] = [[rehypeHighlight, { detect: true }], rehypeKatex];
+    if (sourcesMap.size > 0) base.push([rehypeCitations, { sources: sourcesMap }]);
+    return base;
+  }, [sourcesMap]);
+
   if (isUser) {
     return (
       <div className="flex justify-end mb-4">
@@ -119,10 +140,17 @@ export function MessageBubble({ message }: Props) {
     );
   }
 
-  const cleanContent = useMemo(() => stripThinkTags(message.content), [message.content]);
-
   return (
     <div className="group mb-6">
+      {/* Deep Research timeline (steps + status) */}
+      {(message.isResearch || (message.researchTraces && message.researchTraces.length > 0)) && (
+        <ResearchTimeline
+          traces={message.researchTraces ?? []}
+          isLive={isLive}
+          hasContent={cleanContent.length > 0}
+        />
+      )}
+
       {/* Tool calls */}
       {message.toolCalls && message.toolCalls.length > 0 && (
         <div className="mb-3 flex flex-col gap-2">
@@ -140,7 +168,7 @@ export function MessageBubble({ message }: Props) {
         <div className="prose max-w-none">
           <ReactMarkdown
             remarkPlugins={[remarkGfm, remarkMath]}
-            rehypePlugins={[[rehypeHighlight, { detect: true }], rehypeKatex]}
+            rehypePlugins={rehypePlugins}
             components={{
               pre: CodeBlockPre,
             }}
@@ -154,7 +182,11 @@ export function MessageBubble({ message }: Props) {
       <div className="flex items-center gap-2 mt-1.5">
         <CopyMessageButton content={cleanContent} />
       </div>
-      <XRayFooter usage={message.usage} telemetry={message.telemetry} />
+      <XRayFooter
+        usage={message.usage}
+        telemetry={message.telemetry}
+        isResearch={message.isResearch}
+      />
     </div>
   );
 }

frontend/src/components/Chat/ResearchTimeline.tsx

@@ -0,0 +1,236 @@
+import { useEffect, useRef, useState } from 'react';
+import { ChevronDown, ChevronUp } from 'lucide-react';
+import type { ResearchSearchTrace, TimeRange } from '../../types';
+
+interface Props {
+  traces: ResearchSearchTrace[];
+  isLive: boolean;
+  hasContent: boolean;
+}
+
+const SHORT_DATE = new Intl.DateTimeFormat('en-US', {
+  month: 'short',
+  day: 'numeric',
+});
+
+function fmtDate(iso: string): string | null {
+  const d = new Date(iso);
+  if (Number.isNaN(d.getTime())) return null;
+  return SHORT_DATE.format(d);
+}
+
+function formatTimeRange(tr: TimeRange | string | undefined): string | null {
+  if (!tr) return null;
+  if (typeof tr === 'string') return tr.trim() || null;
+  const start = tr.start ? fmtDate(tr.start) : null;
+  const end = tr.end ? fmtDate(tr.end) : null;
+  if (start && end) return start === end ? start : `${start} – ${end}`;
+  if (start) return `after ${start}`;
+  if (end) return `before ${end}`;
+  return null;
+}
+
+function summarizeTraces(traces: ResearchSearchTrace[]): string {
+  const n = traces.length;
+  const hits = traces.reduce((s, t) => s + (t.numHits ?? 0), 0);
+  const searchLabel = `${n} ${n === 1 ? 'search' : 'searches'}`;
+  if (hits === 0) return searchLabel;
+  return `${searchLabel} · ${hits} ${hits === 1 ? 'result' : 'results'}`;
+}
+
+function StatusLine({ text }: { text: string }) {
+  return (
+    <div
+      className="text-xs leading-relaxed animate-pulse"
+      style={{ color: 'var(--color-text-tertiary)' }}
+    >
+      {text}…
+    </div>
+  );
+}
+
+function TimelineStep({
+  index,
+  trace,
+  isLive,
+}: {
+  index: number;
+  trace: ResearchSearchTrace;
+  isLive: boolean;
+}) {
+  const pending = trace.status === 'pending';
+  const active = pending && isLive;
+  const meta: string[] = [];
+  if (trace.person) meta.push(`person: ${trace.person}`);
+  const formattedTime = formatTimeRange(trace.timeRange);
+  if (formattedTime) meta.push(`time: ${formattedTime}`);
+
+  return (
+    <div className="relative pl-4">
+      {/* Step indicator dot, sitting on the vertical rail */}
+      <div
+        className="absolute left-0 top-[7px] w-1.5 h-1.5 rounded-full"
+        style={{
+          background: active
+            ? 'var(--color-accent)'
+            : 'var(--color-text-tertiary)',
+          opacity: active ? 1 : 0.6,
+          transform: 'translateX(-3px)',
+          boxShadow: active ? '0 0 0 3px var(--color-accent-subtle)' : 'none',
+          transition: 'background 200ms, box-shadow 200ms',
+        }}
+      />
+
+      <div
+        className="text-[10px] uppercase tracking-[0.08em] mb-0.5"
+        style={{
+          color: active ? 'var(--color-accent)' : 'var(--color-text-tertiary)',
+        }}
+      >
+        Search {index}
+      </div>
+
+      <div
+        className="text-sm"
+        style={{ color: 'var(--color-text)', fontWeight: 450 }}
+      >
+        “{trace.query}”
+      </div>
+
+      {meta.length > 0 && (
+        <div
+          className="text-[11px] mt-0.5"
+          style={{ color: 'var(--color-text-tertiary)' }}
+        >
+          {meta.join(' · ')}
+        </div>
+      )}
+
+      {active ? (
+        <div
+          className="mt-2 h-px overflow-hidden relative"
+          style={{ background: 'var(--color-border)' }}
+        >
+          <div
+            className="research-shimmer absolute inset-y-0 w-1/4"
+            style={{ background: 'var(--color-accent)' }}
+          />
+        </div>
+      ) : trace.numHits != null ? (
+        <div
+          className="text-[11px] mt-1"
+          style={{ color: 'var(--color-text-tertiary)' }}
+        >
+          {trace.numHits} {trace.numHits === 1 ? 'result' : 'results'}
+        </div>
+      ) : null}
+
+      {trace.topTitles && trace.topTitles.length > 0 && (
+        <div
+          className="text-[11px] mt-0.5 truncate"
+          style={{ color: 'var(--color-text-tertiary)', opacity: 0.75 }}
+        >
+          {trace.topTitles.slice(0, 2).join(' · ')}
+        </div>
+      )}
+    </div>
+  );
+}
+
+export function ResearchTimeline({ traces, isLive, hasContent }: Props) {
+  const showAnalyzing = isLive && traces.length === 0 && !hasContent;
+  const allComplete =
+    traces.length > 0 && traces.every((t) => t.status === 'complete');
+  const showSynthesizing = isLive && allComplete && !hasContent;
+
+  // Auto-collapse the timeline the moment synthesis text begins streaming.
+  // Subsequent user toggles win — we only fire the auto-collapse once per
+  // false→true transition of hasContent.
+  const [expanded, setExpanded] = useState(true);
+  const prevHasContent = useRef(false);
+  useEffect(() => {
+    if (hasContent && !prevHasContent.current) {
+      setExpanded(false);
+    }
+    prevHasContent.current = hasContent;
+  }, [hasContent]);
+
+  if (!showAnalyzing && traces.length === 0) return null;
+
+  // No collapse affordance before any traces have arrived — just the
+  // analyzing status sitting alone.
+  if (traces.length === 0) {
+    return (
+      <div className="mb-4">
+        <div className="relative pl-4">
+          <div
+            className="absolute left-0 top-[7px] w-1.5 h-1.5 rounded-full"
+            style={{
+              background: 'var(--color-accent)',
+              transform: 'translateX(-3px)',
+              boxShadow: '0 0 0 3px var(--color-accent-subtle)',
+            }}
+          />
+          <StatusLine text="Analyzing query" />
+        </div>
+      </div>
+    );
+  }
+
+  const summary = summarizeTraces(traces);
+  const Chevron = expanded ? ChevronUp : ChevronDown;
+
+  return (
+    <div className="mb-4">
+      <button
+        type="button"
+        onClick={() => setExpanded((e) => !e)}
+        className="flex items-center gap-2 text-[11px] mb-2 cursor-pointer transition-colors"
+        style={{
+          color: 'var(--color-text-tertiary)',
+          background: 'transparent',
+          border: 'none',
+          padding: 0,
+        }}
+        title={expanded ? 'Collapse search trace' : 'Expand search trace'}
+      >
+        <span>{summary}</span>
+        <Chevron size={12} />
+      </button>
+
+      {expanded && (
+        <div className="relative">
+          <div
+            aria-hidden
+            className="absolute top-1 bottom-1 left-0 w-px"
+            style={{ background: 'var(--color-border)' }}
+          />
+          <div className="flex flex-col gap-3">
+            {traces.map((t, i) => (
+              <TimelineStep
+                key={t.id}
+                index={i + 1}
+                trace={t}
+                isLive={isLive}
+              />
+            ))}
+
+            {showSynthesizing && (
+              <div className="relative pl-4">
+                <div
+                  className="absolute left-0 top-[7px] w-1.5 h-1.5 rounded-full"
+                  style={{
+                    background: 'var(--color-accent)',
+                    transform: 'translateX(-3px)',
+                    boxShadow: '0 0 0 3px var(--color-accent-subtle)',
+                  }}
+                />
+                <StatusLine text="Synthesizing findings" />
+              </div>
+            )}
+          </div>
+        </div>
+      )}
+    </div>
+  );
+}

frontend/src/components/Chat/SystemPanel.tsx

@@ -29,8 +29,8 @@ interface TelemetryStats {
 }
 
 const CLOUD_PRICING = [
-  { name: 'GPT-5.3', input: 2.00, output: 10.00, primary: true },
-  { name: 'Claude Opus 4.6', input: 5.00, output: 25.00, primary: false },
+  { name: 'GPT-5.6 Sol', input: 5.00, output: 30.00, primary: true },
+  { name: 'Claude Fable 5', input: 10.00, output: 50.00, primary: false },
   { name: 'Gemini 3.1 Pro', input: 2.00, output: 12.00, primary: false },
 ];
 
@@ -39,6 +39,7 @@ export function SystemPanel() {
   const toggleSystemPanel = useAppStore((s) => s.toggleSystemPanel);
   const optInEnabled = useAppStore((s) => s.optInEnabled);
   const setOptInModalOpen = useAppStore((s) => s.setOptInModalOpen);
+  const liveEnergy = useAppStore((s) => s.liveEnergy);
   const [energy, setEnergy] = useState<EnergyData | null>(null);
   const [telemetry, setTelemetry] = useState<TelemetryStats | null>(null);
 
@@ -129,13 +130,15 @@ export function SystemPanel() {
             <MiniStat
               icon={Zap}
               label="Power"
-              value={(energy?.avg_power_w ?? 0).toFixed(1)}
+              value={(liveEnergy?.power_w ?? energy?.avg_power_w ?? 0).toFixed(1)}
               unit="W"
             />
             <MiniStat
               icon={Activity}
               label="Energy"
-              value={((energy?.total_energy_j ?? 0) / 1000).toFixed(1)}
+              value={(
+                ((liveEnergy?.energy_j ?? energy?.total_energy_j ?? 0) / 1000)
+              ).toFixed(1)}
               unit="kJ"
             />
           </div>

frontend/src/components/Chat/ToolCallCard.tsx

@@ -1,6 +1,7 @@
 import { useState } from 'react';
 import { ChevronDown, ChevronRight, Loader2, CheckCircle2, XCircle } from 'lucide-react';
 import type { ToolCallInfo } from '../../types';
+import { serializeToolCallArguments } from '../../lib/tool-call';
 
 interface Props {
   toolCall: ToolCallInfo;
@@ -35,7 +36,10 @@ export function ToolCallCard({ toolCall }: Props) {
   const [expanded, setExpanded] = useState(false);
   const config = statusConfig[toolCall.status];
   const StatusIcon = config.icon;
-  const preview = previewArgs(toolCall.arguments);
+  // Persisted conversations may contain the pre-fix object payload despite
+  // the TypeScript contract, so normalize again at the final render boundary.
+  const argumentsText = serializeToolCallArguments(toolCall.arguments);
+  const preview = previewArgs(argumentsText);
 
   return (
     <div
@@ -95,7 +99,7 @@ export function ToolCallCard({ toolCall }: Props) {
           className="px-2.5 pb-2 pt-0.5"
           style={{ borderTop: '1px solid var(--color-border-subtle, var(--color-border))' }}
         >
-          {toolCall.arguments && (
+          {argumentsText && (
             <div className="mt-1.5">
               <div
                 style={{
@@ -120,7 +124,7 @@ export function ToolCallCard({ toolCall }: Props) {
                   wordBreak: 'break-all',
                 }}
               >
-                {formatJson(toolCall.arguments)}
+                {formatJson(argumentsText)}
               </pre>
             </div>
           )}

frontend/src/components/Chat/XRayFooter.tsx

@@ -5,19 +5,26 @@ import type { TokenUsage, MessageTelemetry } from '../../types';
 interface Props {
   usage?: TokenUsage;
   telemetry?: MessageTelemetry;
+  isResearch?: boolean;
 }
 
 function formatMs(ms: number): string {
   return ms < 1000 ? `${Math.round(ms)}ms` : `${(ms / 1000).toFixed(1)}s`;
 }
 
-export function XRayFooter({ usage, telemetry }: Props) {
+export function XRayFooter({ usage, telemetry, isResearch = false }: Props) {
   const [expanded, setExpanded] = useState(false);
 
-  // Build collapsed summary parts
+  // Build collapsed summary parts. For Deep Research responses we hide the
+  // chat-side engine/model (which doesn't reflect the planner that actually
+  // produced the answer) and label the response with the mode instead.
   const parts: string[] = [];
-  if (telemetry?.engine) parts.push(telemetry.engine);
-  if (telemetry?.model_id) parts.push(telemetry.model_id);
+  if (isResearch) {
+    parts.push('Deep Research');
+  } else {
+    if (telemetry?.engine) parts.push(telemetry.engine);
+    if (telemetry?.model_id) parts.push(telemetry.model_id);
+  }
   if (telemetry?.complexity_tier) parts.push(telemetry.complexity_tier);
   if (telemetry?.total_ms) parts.push(formatMs(telemetry.total_ms));
   if (usage && (usage.prompt_tokens || usage.completion_tokens)) {
@@ -32,7 +39,9 @@ export function XRayFooter({ usage, telemetry }: Props) {
 
   // Build expanded rows
   const rows: Array<{ label: string; value: string; color?: string }> = [];
-  if (telemetry?.engine) {
+  if (isResearch) {
+    rows.push({ label: 'Mode', value: 'Deep Research' });
+  } else if (telemetry?.engine) {
     const modelDetail = telemetry.model_id || '';
     rows.push({ label: 'Engine', value: `${telemetry.engine}${modelDetail ? ` (${modelDetail})` : ''}` });
   }

frontend/src/components/CommandPalette.tsx

@@ -1,7 +1,15 @@
-import { useState, useRef, useEffect } from 'react';
+import { useState, useRef, useEffect, useCallback } from 'react';
 import { Search, Cpu, X, Download, Loader2, Trash2, Check, Cloud, Key, Eye, EyeOff } from 'lucide-react';
 import { useAppStore } from '../lib/store';
-import { pullModel, deleteModel, fetchModels, preloadModel, isTauri } from '../lib/api';
+import {
+  pullModel,
+  deleteModel,
+  fetchModels,
+  preloadModel,
+  isTauri,
+  getCloudKeyStatus,
+  saveCloudKey,
+} from '../lib/api';
 
 /** Popular models that users can download from the catalogue. */
 const CATALOGUE_MODELS = [
@@ -23,7 +31,6 @@ const CATALOGUE_MODELS = [
 interface CloudProvider {
   name: string;
   envKey: string;
-  storageKey: string;
   models: Array<{ id: string; desc: string }>;
 }
 
@@ -31,7 +38,6 @@ const CLOUD_PROVIDERS: CloudProvider[] = [
   {
     name: 'OpenAI',
     envKey: 'OPENAI_API_KEY',
-    storageKey: 'openjarvis-openai-key',
     models: [
       { id: 'gpt-4o', desc: 'GPT-4o — fast, multimodal' },
       { id: 'gpt-4o-mini', desc: 'GPT-4o Mini — cheap, fast' },
@@ -41,7 +47,6 @@ const CLOUD_PROVIDERS: CloudProvider[] = [
   {
     name: 'Anthropic',
     envKey: 'ANTHROPIC_API_KEY',
-    storageKey: 'openjarvis-anthropic-key',
     models: [
       { id: 'claude-sonnet-4-6', desc: 'Claude Sonnet 4.6 — balanced' },
       { id: 'claude-opus-4-6', desc: 'Claude Opus 4.6 — most capable' },
@@ -51,7 +56,6 @@ const CLOUD_PROVIDERS: CloudProvider[] = [
   {
     name: 'Google',
     envKey: 'GEMINI_API_KEY',
-    storageKey: 'openjarvis-gemini-key',
     models: [
       { id: 'gemini-2.5-pro', desc: 'Gemini 2.5 Pro — flagship' },
       { id: 'gemini-2.5-flash', desc: 'Gemini 2.5 Flash — fast' },
@@ -61,7 +65,6 @@ const CLOUD_PROVIDERS: CloudProvider[] = [
   {
     name: 'OpenRouter',
     envKey: 'OPENROUTER_API_KEY',
-    storageKey: 'openjarvis-openrouter-key',
     models: [
       { id: 'openrouter/auto', desc: 'Auto — best model for the task' },
       { id: 'openrouter/anthropic/claude-sonnet-4', desc: 'Claude Sonnet 4 via OpenRouter' },
@@ -70,16 +73,6 @@ const CLOUD_PROVIDERS: CloudProvider[] = [
   },
 ];
 
-function getStoredKey(storageKey: string): string {
-  try { return localStorage.getItem(storageKey) || ''; } catch { return ''; }
-}
-function setStoredKey(storageKey: string, value: string): void {
-  try {
-    if (value) localStorage.setItem(storageKey, value);
-    else localStorage.removeItem(storageKey);
-  } catch {}
-}
-
 type Tab = 'installed' | 'catalogue' | 'cloud';
 
 export function CommandPalette() {
@@ -92,11 +85,10 @@ export function CommandPalette() {
   const [deleting, setDeleting] = useState<string | null>(null);
   const [customModel, setCustomModel] = useState('');
   const [showKeys, setShowKeys] = useState<Record<string, boolean>>({});
-  const [apiKeys, setApiKeys] = useState<Record<string, string>>(() => {
-    const keys: Record<string, string> = {};
-    for (const p of CLOUD_PROVIDERS) keys[p.storageKey] = getStoredKey(p.storageKey);
-    return keys;
-  });
+  const [apiKeys, setApiKeys] = useState<Record<string, string>>({});
+  const [cloudKeyStatus, setCloudKeyStatus] = useState<Record<string, boolean>>({});
+  const [cloudKeyError, setCloudKeyError] = useState<string | null>(null);
+  const [savingKey, setSavingKey] = useState<string | null>(null);
   const inputRef = useRef<HTMLInputElement>(null);
 
   const models = useAppStore((s) => s.models);
@@ -106,6 +98,20 @@ export function CommandPalette() {
   const setCommandPaletteOpen = useAppStore((s) => s.setCommandPaletteOpen);
 
   const installedIds = new Set(models.map((m) => m.id));
+  const desktopKeyStorage = isTauri();
+
+  const refreshCloudKeyStatus = useCallback(async () => {
+    if (!desktopKeyStorage) {
+      setCloudKeyStatus({});
+      return;
+    }
+    try {
+      setCloudKeyStatus(await getCloudKeyStatus());
+      setCloudKeyError(null);
+    } catch (e: any) {
+      setCloudKeyError(e?.message || 'Failed to read cloud key status');
+    }
+  }, [desktopKeyStorage]);
 
   const filtered = tab === 'installed'
     ? (query
@@ -122,6 +128,10 @@ export function CommandPalette() {
     inputRef.current?.focus();
   }, []);
 
+  useEffect(() => {
+    void refreshCloudKeyStatus();
+  }, [refreshCloudKeyStatus]);
+
   useEffect(() => {
     setSelectedIdx(0);
   }, [query, tab]);
@@ -133,18 +143,17 @@ export function CommandPalette() {
     }
   }, [pullSuccess]);
 
-  const handleSelect = async (modelId: string) => {
+  const handleSelect = async (modelId: string, owner?: string) => {
     const previousModel = selectedModel;
     setSelectedModel(modelId);
     setCommandPaletteOpen(false);
 
     if (modelId !== previousModel) {
-      const { createConversation, setModelLoading, addLogEntry } = useAppStore.getState();
-      createConversation(modelId);
+      const { setModelLoading, addLogEntry } = useAppStore.getState();
       setModelLoading(true);
       addLogEntry({ timestamp: Date.now(), level: 'info', category: 'model', message: `Switching to ${modelId}...` });
       try {
-        await preloadModel(modelId);
+        await preloadModel(modelId, owner);
         addLogEntry({ timestamp: Date.now(), level: 'info', category: 'model', message: `${modelId} loaded` });
       } catch (e: any) {
         addLogEntry({ timestamp: Date.now(), level: 'error', category: 'model', message: `Failed to load ${modelId}: ${e.message}` });
@@ -210,24 +219,29 @@ export function CommandPalette() {
   };
 
   const handleSaveKey = async (provider: CloudProvider, value: string) => {
-    setStoredKey(provider.storageKey, value);
-    setApiKeys((prev) => ({ ...prev, [provider.storageKey]: value }));
+    const keyValue = value.trim();
+    setSavingKey(provider.envKey);
+    setCloudKeyError(null);
 
-    // Also save to Tauri backend so the server process picks up the key
-    if (isTauri()) {
-      try {
-        const { invoke } = await import('@tauri-apps/api/core');
-        await invoke('save_cloud_key', { keyName: provider.envKey, keyValue: value });
-      } catch {}
+    try {
+      await saveCloudKey(provider.envKey, keyValue);
+      setApiKeys((prev) => ({ ...prev, [provider.envKey]: '' }));
+      await refreshCloudKeyStatus();
+      useAppStore.getState().addLogEntry({
+        timestamp: Date.now(), level: 'info', category: 'model',
+        message: `${provider.name} API key ${keyValue ? 'saved' : 'removed'}. Refreshing model list...`,
+      });
+      await refreshModels();
+    } catch (e: any) {
+      setCloudKeyError(e?.message || `Failed to save ${provider.name} API key`);
+    } finally {
+      setSavingKey(null);
     }
+  };
 
-    useAppStore.getState().addLogEntry({
-      timestamp: Date.now(), level: 'info', category: 'model',
-      message: `${provider.name} API key ${value ? 'saved' : 'removed'}. Refreshing model list…`,
-    });
-
-    // Refresh the model list so cloud models appear immediately.
-    await refreshModels();
+  const handleKeyBlur = (provider: CloudProvider) => {
+    const draft = apiKeys[provider.envKey] || '';
+    if (draft.trim()) void handleSaveKey(provider, draft);
   };
 
   const handleKeyDown = (e: React.KeyboardEvent) => {
@@ -241,7 +255,8 @@ export function CommandPalette() {
       setSelectedIdx((i) => Math.max(i - 1, 0));
     } else if (e.key === 'Enter' && tab === 'installed' && filtered.length > 0) {
       e.preventDefault();
-      handleSelect((filtered[selectedIdx] as any).id);
+      const model = filtered[selectedIdx] as (typeof models)[number];
+      handleSelect(model.id, model.owned_by);
     }
   };
 
@@ -323,6 +338,11 @@ export function CommandPalette() {
             <Check size={12} /> Downloaded {pullSuccess} successfully
           </div>
         )}
+        {tab === 'cloud' && cloudKeyError && (
+          <div className="px-4 py-2 text-xs" style={{ color: 'var(--color-error)', background: 'rgba(220,38,38,0.05)' }}>
+            {cloudKeyError}
+          </div>
+        )}
 
         {/* Results */}
         <div className="max-h-[400px] overflow-y-auto py-2">
@@ -346,11 +366,15 @@ export function CommandPalette() {
                     onMouseEnter={() => setSelectedIdx(idx)}
                   >
                     <button
-                      onClick={() => handleSelect(model.id)}
+                      onClick={() => handleSelect(model.id, model.owned_by)}
                       className="flex items-center gap-3 flex-1 min-w-0 text-left cursor-pointer"
                       style={{ background: 'none', border: 'none', padding: 0 }}
                     >
-                      <Cpu size={16} style={{ color: isActive ? 'var(--color-accent)' : 'var(--color-text-tertiary)' }} />
+                      {model.owned_by === 'litellm' ? (
+                        <Cloud size={16} style={{ color: isActive ? 'var(--color-accent)' : 'var(--color-text-tertiary)' }} />
+                      ) : (
+                        <Cpu size={16} style={{ color: isActive ? 'var(--color-accent)' : 'var(--color-text-tertiary)' }} />
+                      )}
                       <div className="flex-1 min-w-0">
                         <div className="text-sm truncate" style={{ color: isActive ? 'var(--color-accent)' : 'var(--color-text)', fontWeight: isActive ? 500 : 400 }}>
                           {model.id}
@@ -362,17 +386,19 @@ export function CommandPalette() {
                         </span>
                       )}
                     </button>
-                    <button
-                      onClick={() => handleDelete(model.id)}
-                      disabled={isDeleting}
-                      className="p-1 rounded transition-colors cursor-pointer"
-                      style={{ color: 'var(--color-text-tertiary)', opacity: 0 }}
-                      title="Delete model"
-                      onMouseEnter={(e) => { e.currentTarget.style.opacity = '1'; e.currentTarget.style.color = 'var(--color-error)'; }}
-                      onMouseLeave={(e) => { e.currentTarget.style.opacity = '0'; e.currentTarget.style.color = 'var(--color-text-tertiary)'; }}
-                    >
-                      {isDeleting ? <Loader2 size={14} className="animate-spin" /> : <Trash2 size={14} />}
-                    </button>
+                    {model.owned_by !== 'litellm' && (
+                      <button
+                        onClick={() => handleDelete(model.id)}
+                        disabled={isDeleting}
+                        className="p-1 rounded transition-colors cursor-pointer"
+                        style={{ color: 'var(--color-text-tertiary)', opacity: 0 }}
+                        title="Delete model"
+                        onMouseEnter={(e) => { e.currentTarget.style.opacity = '1'; e.currentTarget.style.color = 'var(--color-error)'; }}
+                        onMouseLeave={(e) => { e.currentTarget.style.opacity = '0'; e.currentTarget.style.color = 'var(--color-text-tertiary)'; }}
+                      >
+                        {isDeleting ? <Loader2 size={14} className="animate-spin" /> : <Trash2 size={14} />}
+                      </button>
+                    )}
                   </div>
                 );
               })
@@ -431,13 +457,17 @@ export function CommandPalette() {
             /* ── Cloud Models tab ── */
             <div className="px-4 py-2">
               <div className="text-[11px] mb-3" style={{ color: 'var(--color-text-tertiary)' }}>
-                Add your API keys to use cloud models. Keys are stored locally on your device only.
+                {desktopKeyStorage
+                  ? 'Add your API keys to use cloud models. Keys are stored in secure desktop storage.'
+                  : 'Configure cloud provider keys in the server environment to use cloud models.'}
               </div>
 
               {CLOUD_PROVIDERS.map((provider) => {
-                const key = apiKeys[provider.storageKey] || '';
-                const hasKey = !!key;
-                const isVisible = showKeys[provider.storageKey];
+                const key = apiKeys[provider.envKey] || '';
+                const hasSavedKey = !!cloudKeyStatus[provider.envKey];
+                const hasKey = hasSavedKey || !!key.trim();
+                const isVisible = showKeys[provider.envKey];
+                const isSaving = savingKey === provider.envKey;
 
                 return (
                   <div key={provider.name} className="mb-4">
@@ -458,26 +488,28 @@ export function CommandPalette() {
                         <input
                           type={isVisible ? 'text' : 'password'}
                           value={key}
-                          onChange={(e) => setApiKeys((prev) => ({ ...prev, [provider.storageKey]: e.target.value }))}
-                          onBlur={() => handleSaveKey(provider, apiKeys[provider.storageKey] || '')}
-                          placeholder={`${provider.envKey}`}
+                          onChange={(e) => setApiKeys((prev) => ({ ...prev, [provider.envKey]: e.target.value }))}
+                          onBlur={() => handleKeyBlur(provider)}
+                          placeholder={hasSavedKey ? 'Saved in secure storage' : provider.envKey}
+                          disabled={!desktopKeyStorage || isSaving}
                           className="flex-1 text-xs px-2 py-1.5 bg-transparent outline-none font-mono"
                           style={{ color: 'var(--color-text)' }}
                         />
                         <button
-                          onClick={() => setShowKeys((prev) => ({ ...prev, [provider.storageKey]: !prev[provider.storageKey] }))}
+                          onClick={() => setShowKeys((prev) => ({ ...prev, [provider.envKey]: !prev[provider.envKey] }))}
                           className="px-2 cursor-pointer" style={{ color: 'var(--color-text-tertiary)' }}
                         >
                           {isVisible ? <EyeOff size={12} /> : <Eye size={12} />}
                         </button>
                       </div>
-                      {hasKey && (
+                      {hasSavedKey && (
                         <button
                           onClick={() => handleSaveKey(provider, '')}
+                          disabled={isSaving}
                           className="px-2 py-1 rounded-lg text-[10px] cursor-pointer"
-                          style={{ color: 'var(--color-error)', border: '1px solid var(--color-error)' }}
+                          style={{ color: 'var(--color-error)', border: '1px solid var(--color-error)', opacity: isSaving ? 0.5 : 1 }}
                         >
-                          Remove
+                          {isSaving ? 'Saving' : 'Remove'}
                         </button>
                       )}
                     </div>

frontend/src/components/Dashboard/CostComparison.tsx

@@ -2,8 +2,8 @@ import { DollarSign, TrendingDown, Cloud, HardDrive } from 'lucide-react';
 import { useAppStore } from '../../lib/store';
 
 const CLOUD_PRICING = [
-  { name: 'GPT-5.3', input: 2.00, output: 10.00 },
-  { name: 'Claude Opus 4.6', input: 5.00, output: 25.00 },
+  { name: 'GPT-5.6 Sol', input: 5.00, output: 30.00 },
+  { name: 'Claude Fable 5', input: 10.00, output: 50.00 },
   { name: 'Gemini 3.1 Pro', input: 2.00, output: 12.00 },
 ];
 

frontend/src/components/Desktop/SavingsDashboard.tsx

@@ -1,6 +1,7 @@
 import { useState, useEffect, useCallback } from 'react';
 import type React from 'react';
 import { invoke } from '@tauri-apps/api/core';
+import { LEADERBOARD_ENABLED, SUPABASE_ANON_KEY, SUPABASE_URL } from '../../lib/supabase';
 
 // ---------------------------------------------------------------------------
 // Types
@@ -221,8 +222,8 @@ const styles: Record<string, React.CSSProperties> = {
 };
 
 const PROVIDER_COLORS: Record<string, string> = {
-  'gpt-5.3': colors.green,
-  'claude-opus-4.6': colors.yellow,
+  'gpt-5.6-sol': colors.green,
+  'claude-fable-5': colors.yellow,
   'gemini-3.1-pro': colors.accent,
 };
 
@@ -279,9 +280,6 @@ function getOrCreateAnonId(): string {
   return id;
 }
 
-const SUPABASE_URL = 'https://mtbtgpwzrbostweaanpr.supabase.co';
-const SUPABASE_KEY = 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJzdXBhYmFzZSIsInJlZiI6Im10YnRncHd6cmJvc3R3ZWFhbnByIiwicm9sZSI6ImFub24iLCJpYXQiOjE3NzMxODk0OTQsImV4cCI6MjA4ODc2NTQ5NH0._xMlqCfljtXpwPj54H-ghxfLFO-jiq4W2WhpU8vVL1c';
-
 const REFRESH_INTERVAL_MS = 5000;
 
 export function SavingsDashboard({ apiUrl }: { apiUrl: string }) {
@@ -318,15 +316,16 @@ export function SavingsDashboard({ apiUrl }: { apiUrl: string }) {
     return () => clearInterval(timer);
   }, [fetchData]);
 
-  // Share savings to Supabase when opted in and data changes
+  // Share savings to Supabase when opted in and data changes. Skipped entirely
+  // when no anon key was built in (leaderboard disabled).
   useEffect(() => {
-    if (!optInEnabled || !displayName || !data) return;
+    if (!LEADERBOARD_ENABLED || !optInEnabled || !displayName || !data) return;
     const dollarSavings = data.per_provider.reduce((s, p) => s + p.total_cost, 0);
     const energySaved = data.per_provider.reduce((s, p) => s + (p.energy_wh || 0), 0);
     const flopsSaved = data.per_provider.reduce((s, p) => s + (p.flops || 0), 0);
     invoke('submit_savings', {
       supabaseUrl: SUPABASE_URL,
-      supabaseKey: SUPABASE_KEY,
+      supabaseKey: SUPABASE_ANON_KEY,
       payload: {
         anon_id: anonId,
         display_name: displayName,

frontend/src/components/Desktop/UpdateChecker.tsx

@@ -3,6 +3,25 @@ import React, { useState, useEffect, useCallback, useRef } from 'react';
 type UpdateState = 'idle' | 'available' | 'downloading' | 'ready' | 'error';
 
 const CHECK_INTERVAL_MS = 30 * 60 * 1000; // 30 minutes
+const DISABLED_KEY = 'oj-auto-update-disabled';
+
+export function isAutoUpdateDisabled(): boolean {
+  try {
+    return localStorage.getItem(DISABLED_KEY) === '1';
+  } catch {
+    return false;
+  }
+}
+
+export function setAutoUpdateDisabled(disabled: boolean): void {
+  try {
+    if (disabled) {
+      localStorage.setItem(DISABLED_KEY, '1');
+    } else {
+      localStorage.removeItem(DISABLED_KEY);
+    }
+  } catch {}
+}
 
 export function UpdateChecker() {
   const [state, setState] = useState<UpdateState>('idle');
@@ -13,6 +32,7 @@ export function UpdateChecker() {
   const updateRef = useRef<any>(null);
 
   const checkForUpdate = useCallback(async () => {
+    if (isAutoUpdateDisabled()) return;
     try {
       const { check } = await import('@tauri-apps/plugin-updater');
       const update = await check();
@@ -28,10 +48,20 @@ export function UpdateChecker() {
   }, []);
 
   useEffect(() => {
-    // Check if we're in a Tauri environment
     if (typeof window === 'undefined' || !(window as any).__TAURI_INTERNALS__) {
       return;
     }
+    if (isAutoUpdateDisabled()) return;
+
+    // Local dev escape hatch: skip the auto-update poll if explicitly
+    // disabled. Vite exposes any ``VITE_``-prefixed env var on
+    // ``import.meta.env``, so a frontend dev can ``export
+    // VITE_OPENJARVIS_NO_UPDATER=1`` before ``npm run tauri dev`` to
+    // silence the 30-min poll. See docs/desktop-auto-update.md.
+    const noUpdater = (import.meta as any).env?.VITE_OPENJARVIS_NO_UPDATER;
+    if (noUpdater === '1' || noUpdater === 'true') {
+      return;
+    }
 
     checkForUpdate();
     const interval = setInterval(checkForUpdate, CHECK_INTERVAL_MS);
@@ -50,9 +80,7 @@ export function UpdateChecker() {
       const contentLength = update.contentLength ?? 0;
 
       await update.downloadAndInstall((event: any) => {
-        if (event.event === 'Started' && event.data?.contentLength) {
-          // Content length received
-        } else if (event.event === 'Progress') {
+        if (event.event === 'Progress') {
           downloaded += event.data?.chunkLength ?? 0;
           if (contentLength > 0) {
             setProgress(Math.min(100, Math.round((downloaded / contentLength) * 100)));
@@ -75,13 +103,18 @@ export function UpdateChecker() {
       const { relaunch } = await import('@tauri-apps/plugin-process');
       await relaunch();
     } catch {
-      // Fallback: inform user to restart manually
       setErrorMsg('Please restart the application manually');
       setState('error');
       setTimeout(() => setState('idle'), 5000);
     }
   }, []);
 
+  const handleDisable = useCallback(() => {
+    setAutoUpdateDisabled(true);
+    setState('idle');
+    setDismissed(false);
+  }, []);
+
   if (state === 'idle' || dismissed) return null;
 
   return (
@@ -91,7 +124,8 @@ export function UpdateChecker() {
           <span>Update available: <strong>v{version}</strong></span>
           <div style={styles.actions}>
             <button style={styles.primaryBtn} onClick={handleDownload}>Download</button>
-            <button style={styles.secondaryBtn} onClick={() => setDismissed(true)}>Dismiss</button>
+            <button style={styles.secondaryBtn} onClick={() => setDismissed(true)}>Later</button>
+            <button style={styles.muteBtn} onClick={handleDisable}>Disable auto-updates</button>
           </div>
         </div>
       )}
@@ -140,6 +174,7 @@ const styles: Record<string, React.CSSProperties> = {
   actions: {
     display: 'flex',
     gap: '8px',
+    alignItems: 'center',
   },
   primaryBtn: {
     padding: '4px 14px',
@@ -170,6 +205,15 @@ const styles: Record<string, React.CSSProperties> = {
     fontSize: '12px',
     cursor: 'pointer',
   },
+  muteBtn: {
+    padding: '0',
+    border: 'none',
+    backgroundColor: 'transparent',
+    color: '#585b70',
+    fontSize: '11px',
+    cursor: 'pointer',
+    textDecoration: 'underline',
+  },
   progressBar: {
     flex: 1,
     maxWidth: '300px',

frontend/src/components/Layout.tsx

@@ -1,5 +1,6 @@
 import { useEffect, useState } from 'react';
 import { Outlet, useNavigate } from 'react-router';
+import { ApprovalBell } from './ApprovalBell';
 import { Sidebar } from './Sidebar/Sidebar';
 import { SystemPulse } from './SystemPulse';
 import { useAppStore } from '../lib/store';
@@ -27,6 +28,7 @@ export function Layout() {
     <div className="flex flex-col h-full w-full overflow-hidden relative" style={{ paddingTop: '3px' }}>
       <div className="hud-backdrop" aria-hidden="true" />
       <SystemPulse apiReachable={apiReachable} />
+      <ApprovalBell />
 
       {/* Health check banner */}
       {apiReachable === false && (

frontend/src/components/SetupScreen.tsx

@@ -1,6 +1,13 @@
-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';
+import { isEmbedOnlyModel } from '../lib/model-capabilities';
 
 const STEPS = [
   { key: 'ollama_ready', label: 'Inference Engine', icon: Cpu, detail: 'Starting Ollama...' },
@@ -70,10 +77,35 @@ 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();
+        const hadSelection = !!store.selectedModel;
+        store.setModels(models);
+        store.setModelsLoading(false);
+        const chatModels = models.filter((m) => !isEmbedOnlyModel(m.id));
+        const recommended = rec.model && chatModels.some((m) => m.id === rec.model)
+          ? rec.model
+          : chatModels[0]?.id || '';
+        if (recommended && !hadSelection) {
+          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 +149,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}

frontend/src/components/Sidebar/ConversationList.tsx

@@ -22,6 +22,9 @@ export function ConversationList({ searchQuery }: Props) {
   const navigate = useNavigate();
   const conversations = useAppStore((s) => s.conversations);
   const activeId = useAppStore((s) => s.activeId);
+  const streamingConversationId = useAppStore((s) =>
+    s.streamState.isStreaming ? s.streamState.conversationId : null,
+  );
   const selectConversation = useAppStore((s) => s.selectConversation);
   const deleteConversation = useAppStore((s) => s.deleteConversation);
 
@@ -43,6 +46,7 @@ export function ConversationList({ searchQuery }: Props) {
     <div className="flex flex-col gap-0.5 py-1">
       {filtered.map((conv) => {
         const isActive = conv.id === activeId;
+        const isStreaming = conv.id === streamingConversationId;
         return (
           <div
             key={conv.id}
@@ -82,11 +86,18 @@ export function ConversationList({ searchQuery }: Props) {
                 e.stopPropagation();
                 deleteConversation(conv.id);
               }}
-              className="p-1.5 mr-1 rounded opacity-0 group-hover:opacity-100 transition-opacity cursor-pointer"
+              disabled={isStreaming}
+              className="p-1.5 mr-1 rounded opacity-0 group-hover:opacity-100 transition-opacity cursor-pointer disabled:cursor-not-allowed disabled:opacity-30"
               style={{ color: 'var(--color-text-tertiary)' }}
-              onMouseEnter={(e) => (e.currentTarget.style.color = 'var(--color-error)')}
+              onMouseEnter={(e) => {
+                if (!isStreaming) e.currentTarget.style.color = 'var(--color-error)';
+              }}
               onMouseLeave={(e) => (e.currentTarget.style.color = 'var(--color-text-tertiary)')}
-              title="Delete conversation"
+              title={
+                isStreaming
+                  ? 'Stop generating before deleting this conversation'
+                  : 'Delete conversation'
+              }
             >
               <Trash2 size={14} />
             </button>

frontend/src/components/Sidebar/Sidebar.tsx

@@ -33,6 +33,7 @@ export function Sidebar() {
   const serverInfo = useAppStore((s) => s.serverInfo);
   const setCommandPaletteOpen = useAppStore((s) => s.setCommandPaletteOpen);
   const modelLoading = useAppStore((s) => s.modelLoading);
+  const deepResearch = useAppStore((s) => s.deepResearch);
 
   const settings = useAppStore((s) => s.settings);
   const updateSettings = useAppStore((s) => s.updateSettings);
@@ -143,8 +144,13 @@ export function Sidebar() {
               <Cpu size={14} />
             )}
             <div className="flex-1 min-w-0">
-              <span className="truncate block text-left" style={{ color: 'var(--color-text)' }}>
-                {selectedModel || serverInfo?.model || 'Select model'}
+              <span
+                className="truncate block text-left"
+                style={{ color: deepResearch ? 'var(--color-accent)' : 'var(--color-text)' }}
+              >
+                {deepResearch
+                  ? 'Deep Research'
+                  : selectedModel || serverInfo?.model || 'Select model'}
               </span>
               {modelLoading && (
                 <span className="text-[10px] block text-left" style={{ color: 'var(--color-accent)' }}>

frontend/src/index.css

@@ -707,4 +707,50 @@
   --color-foreground: var(--foreground);
   --color-background: var(--background);
   /* Keep project radius tokens — don't override with shadcn calc values */
+}
+
+/* Deep Research timeline — pending-step shimmer */
+@keyframes openjarvis-research-shimmer {
+  0% { transform: translateX(-120%); }
+  100% { transform: translateX(420%); }
+}
+.research-shimmer {
+  animation: openjarvis-research-shimmer 1.6s ease-in-out infinite;
+}
+
+/* Sync progress pulse — fires on each items_synced bump so the
+   "12,450 / 99,840" label visibly breathes between polls. */
+@keyframes openjarvis-sync-bump {
+  0% { opacity: 0.55; }
+  100% { opacity: 1; }
+}
+.sync-bump {
+  animation: openjarvis-sync-bump 400ms ease-out;
+}
+
+/* Deep Research inline citation pills — small rounded chips that flow
+   with the surrounding text and link out to the cited email. */
+.research-citation {
+  display: inline-block;
+  vertical-align: baseline;
+  margin: 0 1px;
+  padding: 0 6px;
+  min-width: 1.25em;
+  text-align: center;
+  font-size: 0.72em;
+  font-weight: 600;
+  line-height: 1.5;
+  color: var(--color-accent);
+  background: var(--color-accent-subtle);
+  border-radius: 9999px;
+  text-decoration: none;
+  cursor: pointer;
+  transition: background 150ms, color 150ms;
+  /* Keep the pill from inheriting prose link styles (underline, bold). */
+  border-bottom: none;
+}
+.research-citation:hover {
+  color: var(--color-on-accent, #ffffff);
+  background: var(--color-accent);
+  text-decoration: none;
 }

frontend/src/lib/analytics.ts

@@ -0,0 +1,208 @@
+/**
+ * Frontend analytics client.
+ *
+ * Thin wrapper around posthog-js that:
+ *   - Pulls its identity (anon_id, host, project key) from the backend
+ *     via GET /v1/analytics/identity, so all backend / install.sh /
+ *     frontend events tie to the same person.
+ *   - Initializes posthog-js with autocapture, session replay, and
+ *     pageviews disabled — we send only events we explicitly call out.
+ *   - Registers the app version as a super-property so every event
+ *     carries it uniformly (no per-event repetition needed).
+ *   - Fails silently when the backend isn't reachable, when analytics
+ *     is disabled, or when the SDK throws — must never break the UI.
+ *
+ * Opt-out matches the backend: if /identity returns enabled=false
+ * (analytics disabled in config), the SDK is never
+ * initialized and track() becomes a no-op.
+ */
+
+import posthog from 'posthog-js';
+import { getBase } from './api';
+
+/**
+ * Mirror of the Python event catalog (src/openjarvis/analytics/events.py
+ * REGISTRY). Anything not in this set is dropped with a console.warn at
+ * track() time, so typos and unallowed events don't silently ship.
+ *
+ * KEEP IN SYNC with the Python REGISTRY. CI could enforce this later.
+ */
+const KNOWN_EVENTS = new Set<string>([
+  'install_started',
+  'install_stage_completed',
+  'install_completed',
+  'install_failed',
+  'uninstall_started',
+  'app_opened',
+  'setup_completed',
+  'first_chat_sent',
+  'chat_session_ended',
+  'tool_first_used',
+  'model_changed',
+  'connector_auth_completed',
+  'feature_used',
+  'feedback_submitted',
+  'error_shown_to_user',
+  'settings_changed',
+  'usage_daily_summary',
+]);
+
+// Hardcoded app version — should match the backend.
+// TODO: wire to Vite define() so this comes from package.json at build time.
+const APP_VERSION = '0.1.0';
+
+interface AnalyticsIdentity {
+  enabled: boolean;
+  anon_id: string;
+  host: string;
+  key: string;
+}
+
+let initialized = false;
+let enabledState = false;
+let cachedAnonId = '';
+
+/**
+ * Fetch identity from the backend and initialize the SDK.
+ * Idempotent — safe to call multiple times.
+ */
+export async function initAnalytics(): Promise<void> {
+  if (initialized) return;
+  initialized = true; // claim the slot even on failure paths
+
+  try {
+    const base = getBase();
+    if (!base) return;
+
+    const resp = await fetch(`${base}/v1/analytics/identity`);
+    if (!resp.ok) return;
+
+    const identity: AnalyticsIdentity = await resp.json();
+    if (!identity.enabled || !identity.key || !identity.anon_id) {
+      return;
+    }
+
+    cachedAnonId = identity.anon_id;
+
+    posthog.init(identity.key, {
+      api_host: identity.host,
+      bootstrap: { distinctID: identity.anon_id },
+      // No surprise data collection — only events we call out by name.
+      autocapture: false,
+      capture_pageview: false,
+      capture_pageleave: false,
+      disable_session_recording: true,
+      // No /decide call for feature flags (saves a request, we don't use them yet).
+      advanced_disable_decide: true,
+      // No PostHog person profiles — we're not making accounts, just sending events.
+      person_profiles: 'never',
+      // Don't try to load IP geolocation; backend disables this too.
+      ip: false,
+      // Best-effort sending only.
+      loaded: () => {
+        enabledState = true;
+      },
+    });
+
+    // Set distinct_id explicitly in case bootstrap raced.
+    posthog.identify(identity.anon_id);
+
+    // Register version + platform as super-properties so they're attached
+    // to every event automatically, without per-call-site repetition.
+    posthog.register({
+      version: APP_VERSION,
+      platform: detectPlatform(),
+    });
+  } catch {
+    // Any failure → analytics off, silently.
+  }
+}
+
+/**
+ * Send one event. Properties are passed through to PostHog; redaction
+ * happens server-side for backend events. Unknown event names are
+ * dropped here with a console.warn so typos surface in dev rather than
+ * silently landing in the analytics warehouse.
+ */
+export function track(
+  event: string,
+  properties: Record<string, unknown> = {},
+): void {
+  if (!enabledState) return;
+  if (!KNOWN_EVENTS.has(event)) {
+    if (import.meta.env.DEV) {
+      console.warn(
+        `[analytics] Unknown event "${event}" dropped. ` +
+          `Add it to KNOWN_EVENTS in lib/analytics.ts and to the Python ` +
+          `REGISTRY in src/openjarvis/analytics/events.py.`,
+      );
+    }
+    return;
+  }
+  try {
+    posthog.capture(event, properties);
+  } catch {
+    // never throw
+  }
+}
+
+/** Force-flush queued events. Call on visibilitychange / pagehide. */
+export function flush(): void {
+  if (!enabledState) return;
+  try {
+    // posthog-js queues then flushes async; this is best-effort.
+    // The SDK doesn't expose a direct flush, but the page lifecycle
+    // hooks below cause a beacon-style flush automatically.
+  } catch {
+    // never throw
+  }
+}
+
+export function isAnalyticsEnabled(): boolean {
+  return enabledState;
+}
+
+export function getAnonId(): string {
+  return cachedAnonId;
+}
+
+/**
+ * Hash an identifier to a 16-char sha256 hex prefix.
+ *
+ * Used for model / tool names that we want to cohort on without
+ * actually shipping the raw value (e.g. proprietary model names a
+ * power user has configured). Mirror of the backend's
+ * :func:`openjarvis.analytics.redaction.hash_id`.
+ */
+export async function hashId(s: string): Promise<string> {
+  if (!s) return '';
+  try {
+    const data = new TextEncoder().encode(s);
+    const buf = await crypto.subtle.digest('SHA-256', data);
+    return Array.from(new Uint8Array(buf))
+      .slice(0, 8)
+      .map((b) => b.toString(16).padStart(2, '0'))
+      .join('');
+  } catch {
+    return '';
+  }
+}
+
+/**
+ * Detect platform string conforming to the events.py allowlist:
+ * "tauri-macos" | "tauri-linux" | "tauri-windows" | "web".
+ */
+export function detectPlatform(): string {
+  const ua =
+    typeof navigator !== 'undefined' ? navigator.userAgent.toLowerCase() : '';
+  const isTauri =
+    typeof window !== 'undefined' &&
+    !!(window as unknown as { __TAURI_INTERNALS__?: unknown })
+      .__TAURI_INTERNALS__;
+  if (isTauri) {
+    if (ua.includes('mac')) return 'tauri-macos';
+    if (ua.includes('windows')) return 'tauri-windows';
+    return 'tauri-linux';
+  }
+  return 'web';
+}

frontend/src/lib/api.auth.test.ts

@@ -0,0 +1,138 @@
+import { afterEach, beforeEach, describe, expect, it, vi } 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';
+const fetchMock = vi.fn<typeof fetch>();
+
+// 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(() => {
+  vi.resetModules();
+  vi.stubEnv('VITE_SUPABASE_ANON_KEY', 'test-anon-key');
+  fetchMock.mockReset();
+  globalThis.fetch = fetchMock;
+  (globalThis as unknown as { localStorage: MemoryStorage }).localStorage =
+    new MemoryStorage();
+});
+
+afterEach(() => {
+  vi.unstubAllEnvs();
+  (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',
+    });
+  });
+});
+
+describe('tool credentials', () => {
+  it('reads credential status from the local server', async () => {
+    fetchMock.mockResolvedValue(
+      new Response(JSON.stringify({ TAVILY_API_KEY: true }), {
+        status: 200,
+        headers: { 'Content-Type': 'application/json' },
+      }),
+    );
+    const { fetchToolCredentialStatus } = await freshApi();
+
+    await expect(fetchToolCredentialStatus('web_search')).resolves.toEqual({
+      TAVILY_API_KEY: true,
+    });
+    expect(fetchMock).toHaveBeenCalledWith(
+      '/v1/tools/web_search/credentials/status',
+      { headers: {} },
+    );
+  });
+
+  it('saves a tool credential through the local server', async () => {
+    fetchMock.mockResolvedValue(new Response('{}', { status: 200 }));
+    const { saveToolCredentials } = await freshApi();
+
+    await saveToolCredentials('web_search', {
+      TAVILY_API_KEY: 'tvly-test',
+    });
+
+    expect(fetchMock).toHaveBeenCalledWith('/v1/tools/web_search/credentials', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ TAVILY_API_KEY: 'tvly-test' }),
+    });
+  });
+
+  it('deletes a tool credential through the local server', async () => {
+    fetchMock.mockResolvedValue(new Response('{}', { status: 200 }));
+    const { deleteToolCredential } = await freshApi();
+
+    await deleteToolCredential('web_search', 'TAVILY_API_KEY');
+
+    expect(fetchMock).toHaveBeenCalledWith(
+      '/v1/tools/web_search/credentials/TAVILY_API_KEY',
+      { method: 'DELETE', headers: {} },
+    );
+  });
+});