fix(config): deserialize skill source tables (#703 )

chore: update clone traffic data [skip ci]
2026-08-14 08:52:06 +00:00 · 2026-08-05 20:50:42 -07:00 · 2026-08-05 08:31:05 +00:00 · 2026-08-04 08:31:51 +00:00 · 2026-08-03 09:38:25 +00:00 · 2026-08-02 08:20:07 +00:00
952 changed files with 108802 additions and 20432 deletions
@@ -0,0 +1,16 @@
+# CODEOWNERS — gates which approvals satisfy the "Require review from
+# Code Owners" branch ruleset on `main`.
+#
+# Anyone listed here may approve PRs against the patterns they own.
+# Combined with the matching branch ruleset toggle, only their approvals
+# count toward the merge requirement. Non-owners can still leave reviews
+# and comments; their approvals simply do not unblock merge.
+#
+# See: https://docs.github.com/repositories/managing-your-repositories-settings-and-features/customizing-your-repository/about-code-owners
+#
+# To add more owners, append GitHub handles (`@username`) or team slugs
+# (`@open-jarvis/<team>`) to the line below. To gate specific paths
+# differently, add a more-specific pattern beneath it (later, more
+# specific rules win).
+
+* @jonsaadfalcon @ANarayan @robbym-dev
@@ -0,0 +1,98 @@
+name: Pearl Model Validation
+description: Track conversion and validation of a Pearl-compatible mining model
+labels: ["type:feature", "area:mining"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Use this template when promoting a raw Hugging Face model to a
+        Pearl-compatible `pearl-ai/*-pearl` mining model. A model should remain
+        `planned` in OpenJarvis until this checklist is complete.
+  - type: input
+    id: raw_model
+    attributes:
+      label: Raw model
+      placeholder: e.g., Qwen/Qwen3.5-9B
+    validations:
+      required: true
+  - type: input
+    id: pearl_model
+    attributes:
+      label: Pearl model artifact
+      placeholder: e.g., pearl-ai/Qwen3.5-9B-pearl
+    validations:
+      required: true
+  - type: dropdown
+    id: target_provider
+    attributes:
+      label: Target provider
+      options:
+        - vllm-pearl
+        - cpu-pearl
+        - apple-mps-pearl
+    validations:
+      required: true
+  - type: textarea
+    id: quantization_recipe
+    attributes:
+      label: Quantization recipe
+      description: Link or paste the recipe used to create the Pearl model artifact.
+      placeholder: |
+        - compressed-tensors config:
+        - 7-bit mining layers:
+        - 8-bit non-mining layers:
+        - calibration data:
+        - SmoothQuant settings:
+    validations:
+      required: true
+  - type: textarea
+    id: hardware
+    attributes:
+      label: Validation hardware
+      placeholder: |
+        - GPU:
+        - VRAM:
+        - driver/CUDA:
+        - Docker image/tag:
+        - Pearl commit/ref:
+    validations:
+      required: true
+  - type: checkboxes
+    id: acceptance
+    attributes:
+      label: Acceptance checks
+      options:
+        - label: Model loads in Pearl's vLLM miner container
+          required: true
+        - label: vLLM registers Pearl's quantization plugin
+          required: true
+        - label: Mining layers use int7 NoisyGEMM
+          required: true
+        - label: Non-mining layers use int8 vanilla Pearl GEMM
+          required: true
+        - label: `jarvis mine init --model <pearl-model-id>` succeeds
+          required: true
+        - label: `jarvis mine start` succeeds
+          required: true
+        - label: `jarvis ask` succeeds through the mining engine
+          required: true
+        - label: `jarvis mine status` reports gateway/mining metrics
+          required: true
+        - label: `jarvis mine validate-model --allow-planned` passes
+          required: true
+        - label: Gateway/miner logs show no submission errors
+          required: true
+  - type: textarea
+    id: artifacts
+    attributes:
+      label: Artifacts
+      description: Attach logs, metrics, model config, and command output.
+      placeholder: |
+        - /v1/models output:
+        - `jarvis mine status` output:
+        - `jarvis mine validate-model --output` JSON:
+        - gateway metrics excerpt:
+        - miner logs:
+        - PR/commit that flips status to validated:
+    validations:
+      required: true
@@ -1,7 +1,7 @@
 {
  "schemaVersion": 1,
  "label": "Git Clones",
-  "message": "0",
+  "message": "181,942",
  "color": "green",
  "namedLogo": "git"
 }
@@ -1,5 +1,137 @@
 {
-  "total_clones": 0,
-  "last_updated": "",
-  "daily": {}
+  "total_clones": 181942,
+  "last_updated": "2026-08-05T08:31:05Z",
+  "daily": {
+    "2026-03-27": 2189,
+    "2026-03-28": 1874,
+    "2026-03-29": 933,
+    "2026-03-30": 755,
+    "2026-03-31": 872,
+    "2026-04-01": 539,
+    "2026-04-02": 806,
+    "2026-04-03": 1377,
+    "2026-04-04": 678,
+    "2026-04-05": 734,
+    "2026-04-06": 750,
+    "2026-04-07": 813,
+    "2026-04-08": 1280,
+    "2026-04-09": 981,
+    "2026-04-10": 1142,
+    "2026-04-11": 706,
+    "2026-04-12": 813,
+    "2026-04-13": 1058,
+    "2026-04-14": 868,
+    "2026-04-15": 895,
+    "2026-04-16": 889,
+    "2026-04-17": 2341,
+    "2026-04-18": 1487,
+    "2026-04-19": 1339,
+    "2026-04-20": 1428,
+    "2026-04-21": 1216,
+    "2026-04-22": 1768,
+    "2026-04-23": 1050,
+    "2026-04-24": 1245,
+    "2026-04-25": 1116,
+    "2026-04-26": 1211,
+    "2026-04-27": 1606,
+    "2026-04-28": 1090,
+    "2026-04-29": 1332,
+    "2026-04-30": 943,
+    "2026-05-01": 1252,
+    "2026-05-02": 1326,
+    "2026-05-03": 1832,
+    "2026-05-04": 1830,
+    "2026-05-05": 3854,
+    "2026-05-06": 1521,
+    "2026-05-07": 1216,
+    "2026-05-08": 661,
+    "2026-05-09": 796,
+    "2026-05-10": 814,
+    "2026-05-11": 1008,
+    "2026-05-12": 1390,
+    "2026-05-13": 1397,
+    "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
+  }
 }
@@ -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}"
@@ -0,0 +1,27 @@
+name: Bash tests
+
+on:
+  pull_request:
+    paths:
+      - 'scripts/install/**'
+      - 'tests/install/bash/**'
+      - '.github/workflows/bash-tests.yml'
+  push:
+    branches: [main]
+    paths:
+      - 'scripts/install/**'
+      - 'tests/install/bash/**'
+
+jobs:
+  bats:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install bats-core
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y bats
+
+      - name: Run bats tests
+        run: bats tests/install/bash/
@@ -14,29 +14,34 @@ jobs:
  lint:
    runs-on: ubuntu-latest
    steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v6

      - name: Set up Python
-        uses: actions/setup-python@v5
+        uses: actions/setup-python@v6
        with:
          python-version: "3.12"

      - name: Install uv
-        uses: astral-sh/setup-uv@v4
+        uses: astral-sh/setup-uv@v8.0.0
+        with:
+          enable-cache: true

      - name: Install dependencies
-        run: uv sync --extra dev
+        run: uv sync --extra dev --extra framework-comparison --extra server

      - 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:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v6

      - name: Set up Python
-        uses: actions/setup-python@v5
+        uses: actions/setup-python@v6
        with:
          python-version: "3.12"

@@ -44,7 +49,7 @@ jobs:
        uses: dtolnay/rust-toolchain@stable

      - name: Cargo cache
-        uses: actions/cache@v4
+        uses: actions/cache@v5
        with:
          path: |
            ~/.cargo/registry
@@ -54,16 +59,97 @@ jobs:
          restore-keys: rust-${{ runner.os }}-

      - name: Install uv
-        uses: astral-sh/setup-uv@v4
+        uses: astral-sh/setup-uv@v8.0.0
+        with:
+          enable-cache: true

      - name: Install dependencies
-        run: uv sync --extra dev
+        run: uv sync --extra dev --extra framework-comparison --extra server

      - name: Build Rust extension
        run: uv run maturin develop --manifest-path rust/crates/openjarvis-python/Cargo.toml

      - name: Run tests
-        run: uv run pytest tests/ -v --tb=short -m "not live and not cloud"
+        # 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/ -n auto -q --tb=short -m "not live and not cloud and not hub" \
+            --cov=openjarvis \
+            --cov-report=term-missing \
+            --cov-report=xml \
+            --cov-fail-under=60
+
+      - 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
@@ -71,7 +157,7 @@ jobs:
      run:
        working-directory: rust
    steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v6

      - name: Install Rust toolchain
        uses: dtolnay/rust-toolchain@stable
@@ -79,7 +165,7 @@ jobs:
          components: clippy

      - name: Cargo cache
-        uses: actions/cache@v4
+        uses: actions/cache@v5
        with:
          path: |
            ~/.cargo/registry
@@ -11,27 +11,38 @@ 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]')
    steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v6
        with:
          fetch-depth: 0

@@ -1,8 +1,6 @@
 name: Claude PR Review

 on:
-  pull_request:
-    types: [opened, synchronize]
  issue_comment:
    types: [created]
  pull_request_review_comment:
@@ -13,28 +11,37 @@ 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 == 'pull_request' ||
      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:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v6

      - name: Read review instructions
        id: review
@@ -2,23 +2,23 @@ name: Desktop Build & Release

 on:
  push:
-    branches: [main]
-    paths:
-      - 'desktop/**'
-      - 'frontend/**'
-      - '.github/workflows/desktop.yml'
    tags:
+      - 'v*'
      - 'desktop-v*'
  pull_request:
    branches: [main]
    paths:
-      - 'desktop/**'
      - '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:
@@ -29,7 +29,7 @@ jobs:
    runs-on: ubuntu-22.04

    steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v6

      - name: Install system dependencies
        run: |
@@ -40,10 +40,11 @@ jobs:
            libappindicator3-dev \
            librsvg2-dev \
            patchelf \
-            libxdo-dev
+            libxdo-dev \
+            libdbus-1-dev

      - name: Setup Node.js
-        uses: actions/setup-node@v4
+        uses: actions/setup-node@v6
        with:
          node-version: '22'

@@ -51,10 +52,6 @@ jobs:
        working-directory: frontend
        run: npm install

-      - name: Install desktop dependencies
-        working-directory: desktop
-        run: npm install
-
      - name: TypeScript type-check
        working-directory: frontend
        run: npx tsc --noEmit
@@ -65,28 +62,32 @@ jobs:
      - name: Rust cache
        uses: swatinem/rust-cache@v2
        with:
-          workspaces: 'desktop/src-tauri -> target'
+          workspaces: 'frontend/src-tauri -> target'

      - name: Create frontend dist stub
        run: mkdir -p frontend/dist && echo '<html><body></body></html>' > frontend/dist/index.html

-      - name: Cargo check
-        working-directory: desktop/src-tauri
-        run: 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 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)
@@ -113,7 +114,12 @@ jobs:
    runs-on: ${{ matrix.platform }}

    steps:
-      - uses: actions/checkout@v4
+      - 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

      - name: Install system dependencies (Linux)
        if: matrix.platform == 'ubuntu-22.04'
@@ -125,7 +131,8 @@ jobs:
            libappindicator3-dev \
            librsvg2-dev \
            patchelf \
-            libxdo-dev
+            libxdo-dev \
+            libdbus-1-dev

      - name: Install Rust stable
        uses: dtolnay/rust-toolchain@stable
@@ -135,10 +142,10 @@ jobs:
      - name: Rust cache
        uses: swatinem/rust-cache@v2
        with:
-          workspaces: 'desktop/src-tauri -> target'
+          workspaces: 'frontend/src-tauri -> target'

      - name: Setup Node.js
-        uses: actions/setup-node@v4
+        uses: actions/setup-node@v6
        with:
          node-version: '22'

@@ -146,14 +153,10 @@ jobs:
        working-directory: frontend
        run: npm install

-      - name: Install desktop dependencies
-        working-directory: desktop
-        run: npm install
-
      - name: Download Ollama sidecar
        shell: bash
        run: |
-          cd desktop/scripts && chmod +x download-ollama.sh
+          cd frontend/src-tauri/scripts && chmod +x download-ollama.sh
          if [[ "${{ matrix.platform }}" == "macos-14" ]]; then
            ./download-ollama.sh aarch64-apple-darwin
            ./download-ollama.sh x86_64-apple-darwin
@@ -166,14 +169,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'
@@ -209,9 +253,13 @@ 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: desktop
+          projectPath: frontend
          tauriScript: npx tauri
          tagName: ${{ steps.release-info.outputs.tag }}
          releaseName: ${{ steps.release-info.outputs.name }}
@@ -220,3 +268,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}"
@@ -28,25 +28,45 @@ jobs:
  build:
    runs-on: ubuntu-latest
    steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v6

      - name: Set up Python
-        uses: actions/setup-python@v5
+        uses: actions/setup-python@v6
        with:
          python-version: "3.12"

      - name: Install uv
-        uses: astral-sh/setup-uv@v4
+        uses: astral-sh/setup-uv@v8.0.0

      - 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

      - name: Upload artifact
        if: github.ref == 'refs/heads/main' && github.event_name != 'pull_request'
-        uses: actions/upload-pages-artifact@v3
+        uses: actions/upload-pages-artifact@v5.0.0
        with:
          path: site/

@@ -60,4 +80,4 @@ jobs:
    steps:
      - name: Deploy to GitHub Pages
        id: deployment
-        uses: actions/deploy-pages@v4
+        uses: actions/deploy-pages@v5
@@ -24,9 +24,9 @@ jobs:
      run:
        working-directory: frontend
    steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v6

-      - uses: actions/setup-node@v4
+      - uses: actions/setup-node@v6
        with:
          node-version: '22'
          cache: 'npm'
@@ -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 }}
@@ -0,0 +1,118 @@
+name: Installer integration
+
+on:
+  pull_request:
+    paths:
+      - 'scripts/install/**'
+      - 'src/openjarvis/cli/**'
+      - 'tests/install/**'
+      - '.github/workflows/installer-integration.yml'
+  schedule:
+    - cron: '0 6 * * *'
+
+jobs:
+  container-matrix:
+    name: ${{ matrix.image }}
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        image:
+          - ubuntu:22.04
+          - ubuntu:24.04
+          - fedora:40
+
+    container: ${{ matrix.image }}
+
+    steps:
+      - name: Install prereqs (Ubuntu/Debian)
+        if: contains(matrix.image, 'ubuntu') || contains(matrix.image, 'debian')
+        run: |
+          apt-get update
+          apt-get install -y curl git python3 sudo
+
+      - name: Install prereqs (Fedora)
+        if: contains(matrix.image, 'fedora')
+        run: |
+          dnf install -y curl git python3 sudo
+
+      - name: Create non-root user
+        run: useradd -m -s /bin/bash testuser
+
+      - uses: actions/checkout@v4
+        with:
+          path: openjarvis-src
+
+      - name: Install Ollama mock
+        run: install -m 755 "$GITHUB_WORKSPACE/openjarvis-src/tests/install/bash/stubs/ollama-mock" /usr/local/bin/ollama
+
+      - name: Run installer
+        run: |
+          chown -R testuser:testuser /home/testuser "$GITHUB_WORKSPACE/openjarvis-src"
+          su testuser -c '
+            export OPENJARVIS_REPO_URL=file://'"$GITHUB_WORKSPACE"'/openjarvis-src
+            cd '"$GITHUB_WORKSPACE"'/openjarvis-src
+            bash scripts/install/install.sh --no-bg-orchestrator
+          '
+
+      - name: Verify install state
+        run: |
+          su testuser -c '
+            test -d ~/.openjarvis/src
+            test -d ~/.openjarvis/.venv
+            test -f ~/.openjarvis/config.toml
+            test -f ~/.openjarvis/.state/install-state.json
+            test -L ~/.local/bin/jarvis
+          '
+
+      - name: Verify jarvis --version
+        run: su testuser -c '~/.local/bin/jarvis --version'
+
+      - name: Verify jarvis doctor exits 0
+        run: su testuser -c '~/.local/bin/jarvis doctor'
+
+      - name: Verify uninstall is clean
+        run: |
+          su testuser -c '
+            ~/.local/bin/jarvis-uninstall
+            test ! -d ~/.openjarvis
+            test ! -L ~/.local/bin/jarvis
+          '
+
+  macos:
+    name: ${{ matrix.os }}
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [macos-14, macos-15]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install Ollama mock
+        run: sudo install -m 755 tests/install/bash/stubs/ollama-mock /usr/local/bin/ollama
+
+      - name: Run installer
+        run: |
+          export OPENJARVIS_REPO_URL=file://$(pwd)
+          bash scripts/install/install.sh --no-bg-orchestrator
+
+      - name: Verify install state
+        run: |
+          test -d ~/.openjarvis/src
+          test -d ~/.openjarvis/.venv
+          test -f ~/.openjarvis/config.toml
+          test -L ~/.local/bin/jarvis
+
+      - name: Verify jarvis --version
+        run: ~/.local/bin/jarvis --version
+
+      - name: Verify jarvis doctor exits 0
+        run: ~/.local/bin/jarvis doctor
+
+      - name: Verify uninstall is clean
+        run: |
+          ~/.local/bin/jarvis-uninstall
+          test ! -d ~/.openjarvis
+          test ! -L ~/.local/bin/jarvis
@@ -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:
-      - uses: actions/checkout@v4
+      - 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@v4
+        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
@@ -13,11 +13,13 @@ jobs:
    runs-on: ubuntu-latest

    steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v6
+        with:
+          token: ${{ secrets.TRAFFIC_TOKEN }}

      - name: Fetch clone traffic
        env:
-          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          GH_TOKEN: ${{ secrets.TRAFFIC_TOKEN }}
        run: |
          gh api repos/${{ github.repository }}/traffic/clones > /tmp/traffic.json

@@ -39,17 +39,27 @@ Thumbs.db
 # Secrets
 .env
 .env.*
+# ...but keep checked-in example/templates (never contain real secrets)
+!.env.example
+!**/.env.example

 # Project
 *.sqlite
 *.db
 *.jsonl
 *.npz
+*.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
+MagicMock/

 # MkDocs build output
 site/
@@ -57,12 +67,14 @@ site/
 # Frontend
 frontend/node_modules/
 frontend/dist/
+
+# Desktop
+desktop/node_modules/
+desktop/dist/
 src/openjarvis/server/static/

 # Desktop (Tauri)
-desktop/node_modules/
-desktop/dist/
-desktop/src-tauri/target/
+frontend/src-tauri/target/

 # Worktrees
 .worktrees/
@@ -90,4 +102,31 @@ CLAUDE.md
 research_mining_*
 .python-version
 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/
+
+# ---------------------------------------------------------------------------
+# Distillation runtime artifacts (defense in depth — these should always live
+# in ~/.openjarvis/, never inside the source tree, but we ignore them here in
+# case OPENJARVIS_HOME is misconfigured during dev)
+# ---------------------------------------------------------------------------
+.openjarvis/
+learning.db
+**/learning/sessions/
+**/learning/pending_review/
+**/learning/benchmarks/
+**/teacher_traces/
+*.session.json
+
+# Local dev artifacts (hybrid worker logs + cli debug dumps)
+minion_logs/
+*.oj-debug.json
+oj-debug.*.json
@@ -10,7 +10,253 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).

 ### Added

-#### Skills System (Plans 1, 2A, 2B)
+**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,
+Tools & Memory, Learning) is now stable, with efficiency and
+on-device learning as first-class capabilities alongside accuracy.
+Companion blog post:
+[From Minions to OpenJarvis: A Retrospective on Two Years in Local AI](https://hazyresearch.stanford.edu/blog/2026-05-19-minions-to-openjarvis-retrospective).
+
+### Highlights
+
+**Five composable primitives.** Intelligence, Engine, Agents, Tools & Memory,
+and Learning each sit behind a single typed interface — any slot is
+substitutable without touching the rest. The composition layer is
+`JarvisSystem` in `src/openjarvis/system.py`, driven by a TOML config.
+
+**Built-in agents across three execution modes.** Eight agents spanning a
+single-turn chat baseline, a deep-research agent with inline citations,
+a CodeAct-style coder, and a continuous monitor with memory compression
+for long-horizon workflows. Execution modes cover on-demand, scheduled,
+and continuous.
+
+**Starter presets.** Eight preset configs installable via
+`jarvis init --preset <name>` bundle an agent with a hardware-appropriate
+engine, connectors, and tools. Variants cover Apple Silicon, Linux GPU
+servers, and CPU-only laptops, plus a quickstart for LLM-guided spec search.
+
+**Inference engines.** Four first-class local engines (Ollama, vLLM, SGLang,
+llama.cpp) and five cloud providers (OpenAI, Anthropic, Google Gemini,
+OpenRouter, MiniMax) sit behind a single `Engine` interface. Discovery
+in `engine/_discovery.py` picks a sensible default per host.
+
+### Added — hybrid local-cloud capabilities
+
+**Per-query routing via a query-complexity analyzer**
+(`src/openjarvis/learning/routing/complexity.py`). Produces a 0.0–1.0
+complexity score with code/math/reasoning signals and a suggested token
+budget, populating `RoutingContext` so easy queries stay local and only
+queries that need frontier capability escalate.
+
+**LLM-guided spec search** (`src/openjarvis/learning/spec_search/`).
+`SpecSearchOrchestrator` wires diagnose → plan → execute → gate into a
+single learning session: a frontier model reads traces, proposes
+coordinated edits across all five primitives, and a held-out benchmark
+gate (`gate/benchmark_gate.py`, `gate/regression.py`, `gate/cold_start.py`)
+accepts only non-regressing edits. Ships with the `spec-search-quickstart`
+preset and a runnable tutorial at `examples/openjarvis/spec_search_quickstart.py`.
+
+**Six hybrid coordination paradigms** in `src/openjarvis/agents/hybrid/`.
+Each paradigm pairs a local student with a frontier cloud teacher under
+a different orchestration shape, as `LocalCloudAgent` subclasses:
+
+- `minions` — reactive single-local + single-cloud loop
+- `conductor` — static DAG planner
+- `advisors` — executor ↔ advisor loop
+- `archon` — generate → rank → fuse
+- `skillorchestra` — per-query router across local skills
+- `toolorchestra` — RL'd local model with a tool pool
+
+A runner CLI (`python -m openjarvis.agents.hybrid.runner --cell <name>`)
+and a 35-cell experiment registry (one TOML per method × benchmark ×
+model triple) let researchers run, score, and compare these on equal
+footing. Includes a Modal-backed SWE-bench-Verified harness scorer
+(`evals/scorers/swebench_harness.py`).
+
+### Added — efficiency as a first-class constraint
+
+**Hardware-agnostic energy telemetry at 50ms resolution** across NVIDIA
+(`telemetry/energy_nvidia.py`), AMD (`telemetry/energy_amd.py`), Apple
+Silicon (`telemetry/energy_apple.py`), and Intel RAPL
+(`telemetry/energy_rapl.py`). Energy, dollar cost, FLOPs, and latency
+are treated as evaluation targets alongside accuracy.
+
+**Instrumentation for FLOPs, batch, steady-state, ITL, phase energy, and
+vLLM-specific metrics.** Joined per-query by the aggregator
+(`telemetry/aggregator.py`) so traces carry accuracy + efficiency together.
+
+### Added — local learning loop
+
+**Closed-loop optimization across the stack** — model weights via SFT
+(`learning/intelligence/sft_trainer.py`) and GRPO
+(`learning/intelligence/grpo_trainer.py` plus an orchestrator-specific
+variant under `learning/intelligence/orchestrator/`), prompts via DSPy
+(`learning/agents/dspy_optimizer.py`), agent logic via GEPA
+(`learning/agents/gepa_optimizer.py`), and engine + stack configuration
+via LLM-guided spec search. `LearningOrchestrator` coordinates triggers
+and applies optimizer overlays at discovery time so improvements compound
+across primitives.
+
+### Added — cross-framework evaluation
+
+**External agentic-framework evaluation via subprocess.** The
+`evals/backends/external/` subpackage wraps Hermes Agent and OpenClaw as
+one-shot subprocess backends behind the existing `InferenceBackend` ABC.
+The `evals/comparison/` toolkit provides path + commit-pin enforcement
+(`third_party.py`), config templating (`make_configs.py`), and LaTeX
+table generation (`table_gen.py`).
+
+Ships with a new optional extra `framework-comparison` (depends on
+`polars`), a `live_external` pytest marker for integration tests
+requiring real foreign-framework installations, and a `ToolOrchestra`
+evaluation dataset (`evals/datasets/toolorchestra.py`) alongside the
+existing 30+ benchmark suite.
+
+### Added — Skills System (Plans 1, 2A, 2B)

 - **Skills core** — every skill is a tool. Skills appear in a system prompt catalog, agents invoke them on demand, content (pipeline results, markdown instructions, or both) gets injected into context.
  - `SkillManifest` + `SkillStep` types with tags, depends, invocation flags, markdown content
@@ -66,13 +312,45 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
  - `docs/getting-started/configuration.md` — expanded with skills config sections
  - `CLAUDE.md` — updated architecture section

+### Examples & Tutorials
+
+- `examples/openjarvis/spec_search_quickstart.py` — runnable end-to-end
+  LLM-guided spec search session.
+- `docs/user-guide/llm-guided-spec-search.md` — paper-aligned user guide.
+- `docs/architecture/learning.md` — Learning primitive deep-dive covering
+  routing, spec search, optimizers, and the orchestrator.
+- `docs/tutorials/` — code-companion, deep-research, messaging-hub,
+  scheduled-ops, and skills-workflow walkthroughs.
+- `src/openjarvis/agents/hybrid/registry/*.toml` — 35-cell registry of
+  paradigm × benchmark × model experiments.
+
+### Migration from 0.x
+
+- **`learning/distillation/` is now `learning/spec_search/`.** The
+  subsystem was renamed to match the LLM-guided spec search semantics
+  documented in the companion paper. Update any imports
+  (`from openjarvis.learning.distillation.*` →
+  `from openjarvis.learning.spec_search.*`). The `jarvis distillation`
+  CLI command is removed; use `spec_search`-prefixed config keys instead.
+- **`_third_party.toml` no longer ships default paths.** Set
+  `HERMES_AGENT_PATH` and `OPENCLAW_PATH` env vars to point at your
+  local checkouts before running the framework-comparison harness;
+  missing or empty paths now raise `ThirdPartyNotFoundError` with an
+  actionable hint.
+- **Engine `generate_full` return shape extended.**
+  `JarvisAgentBackend.generate_full` and `JarvisDirectBackend.generate_full`
+  now return the spec §6.2 extended fields (`energy_joules`,
+  `peak_power_w`, `tool_calls`, `turn_count`, `framework`,
+  `framework_commit`, `error`). Existing callers that didn't read these
+  fields are unaffected; new callers can rely on cross-framework parity.
+
 ### Fixed

- **Trace metadata flow** — `ToolResult.metadata` now propagates through `TOOL_CALL_END` event to `TraceStep.metadata` (was silently dropped at the event-bus boundary)
- **TaintSet JSON serialization** — `ToolExecutor._json_safe_metadata()` filters non-JSON-serializable values (like `TaintSet`) from event payloads before they reach `TraceStore`
- **Non-dict YAML frontmatter** — source resolvers handle `yaml.safe_load()` returning a string instead of a dict (discovered on real OpenClaw imports)
- **OpenClaw category/name queries** — `jarvis skill install openclaw:owner/slug` now correctly splits into category + name match
- **SkillDiscovery trace compatibility** — `_extract_tool_sequence` reads from `step.input["tool"]` (the actual `TraceStep` format), not the nonexistent `step.tool_name` attribute
- **LearningOrchestrator skill trigger** — `_maybe_optimize_skills` runs BEFORE the SFT-data short-circuit (skills are tagged via trace metadata, not mined as SFT pairs)
- **PinchBenchScorer constructor** — `SkillBenchmarkRunner` constructs `PinchBenchScorer(judge_backend, model)` instead of no-args
- **EvalRunner results access** — reads per-task data from `eval_runner.results` property, not nonexistent `summary.results`
+- **Trace metadata flow** — `ToolResult.metadata` now propagates through `TOOL_CALL_END` event to `TraceStep.metadata` (was silently dropped at the event-bus boundary).
+- **TaintSet JSON serialization** — `ToolExecutor._json_safe_metadata()` filters non-JSON-serializable values (like `TaintSet`) from event payloads before they reach `TraceStore`.
+- **Non-dict YAML frontmatter** — source resolvers handle `yaml.safe_load()` returning a string instead of a dict (discovered on real OpenClaw imports).
+- **OpenClaw category/name queries** — `jarvis skill install openclaw:owner/slug` now correctly splits into category + name match.
+- **SkillDiscovery trace compatibility** — `_extract_tool_sequence` reads from `step.input["tool"]` (the actual `TraceStep` format), not the nonexistent `step.tool_name` attribute.
+- **LearningOrchestrator skill trigger** — `_maybe_optimize_skills` runs BEFORE the SFT-data short-circuit (skills are tagged via trace metadata, not mined as SFT pairs).
+- **PinchBenchScorer constructor** — `SkillBenchmarkRunner` constructs `PinchBenchScorer(judge_backend, model)` instead of no-args.
+- **EvalRunner results access** — reads per-task data from `eval_runner.results` property, not nonexistent `summary.results`.
@@ -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/
@@ -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/wfXEkpPX"><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,87 +36,49 @@

 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

-### Prerequisites
+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.

-| Tool | Install |
-|------|---------|
-| **Python 3.10+** | [python.org](https://www.python.org/downloads/) |
-| **uv** (Python package manager) | `curl -LsSf https://astral.sh/uv/install.sh \| sh` — or `brew install uv` on macOS |
-| **Rust** | `curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs \| sh` |
-| **Git** | [git-scm.com](https://git-scm.com/) — or `brew install git` on macOS |
+| 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) |

-> **macOS users:** see the full [macOS Installation Guide](https://open-jarvis.github.io/OpenJarvis/getting-started/macos/) for a step-by-step walkthrough including Homebrew setup.
+Then `jarvis` to start. The Rust extension and larger models continue downloading in the background; `jarvis doctor` shows status.

-### Setup
-
-```bash
-git clone https://github.com/open-jarvis/OpenJarvis.git
-cd OpenJarvis
-uv sync                           # core framework
-uv sync --extra server             # + FastAPI server
-
-# Build the Rust extension
-uv run maturin develop -m rust/crates/openjarvis-python/Cargo.toml
-```
-
-> **Python 3.14+:** set `PYO3_USE_ABI3_FORWARD_COMPATIBILITY=1` before the `maturin` command.
-
-You also need a local inference backend: [Ollama](https://ollama.com), [vLLM](https://github.com/vllm-project/vllm), [SGLang](https://github.com/sgl-project/sglang), or [llama.cpp](https://github.com/ggerganov/llama.cpp). Alternatively, use the `cloud` engine with [OpenAI](https://openai.com), [Anthropic](https://anthropic.com), [Google Gemini](https://ai.google.dev), [OpenRouter](https://openrouter.ai), or [MiniMax](https://www.minimax.io) by setting the corresponding API key environment variable.
+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
-# 1. Install and detect hardware
-git clone https://github.com/open-jarvis/OpenJarvis.git
-cd OpenJarvis
-uv sync
-uv run jarvis init
-
-# 2. Start Ollama and pull a model
-curl -fsSL https://ollama.com/install.sh | sh
-ollama serve &
-ollama pull qwen3:8b
-
-# 3. Ask a question
-uv run jarvis ask "What is the capital of France?"
+jarvis                          # start chatting (default: chat-simple)
+jarvis init --preset <name>     # switch to a starter config
 ```

-`jarvis init` auto-detects your hardware and recommends the best engine. Run `uv run jarvis doctor` at any time to diagnose issues.
+> 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
-jarvis init --preset morning-digest-mac   # or any preset below
-```
-
-| 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
 jarvis init --preset morning-digest-mac
-jarvis connect gdrive          # one OAuth flow covers Gmail, Calendar, Tasks
-jarvis digest --fresh           # generate and play your first briefing
-
-# Example: Deep Research
-jarvis init --preset deep-research
-jarvis memory index ./docs/    # index your documents
-jarvis ask "Summarize all emails about Project X"
+jarvis connect gdrive          # one OAuth covers Gmail / Calendar / Tasks
+jarvis digest --fresh          # generate and play your first briefing
 ```

+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

 Skills teach agents how to better use tools and improve their reasoning. Every skill is a tool — agents discover them from a catalog and invoke them on demand.
@@ -132,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 |
@@ -147,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.
@@ -165,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

@@ -181,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}, 
 }
 ```

@@ -17,6 +17,7 @@ Check for logic errors, edge cases, and off-by-one errors. Pay particular attent
 - **Rust-Python bridge (PyO3) boundaries** — type conversions, error propagation, GIL handling
 - **Async/await patterns** — missing awaits, unclosed resources, blocking calls in async contexts
 - **Registry pattern compliance** — new components (engines, tools, agents, channels) must register via `ToolRegistry`, `EngineRegistry`, `AgentRegistry`, `ChannelRegistry`, etc. in `src/openjarvis/core/registry.py`
+- **Mining provider compliance** — new mining providers must register via `MinerRegistry` and expose an idempotent `ensure_registered()` for the autouse-clear test convention
 - **Event bus integration** — new lifecycle events should use `EventBus` from `src/openjarvis/core/events.py`

 ### 4. Testing
@@ -106,9 +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"
-
-[security]
-enabled = false                           # Disable for eval (no PII scanning overhead)
@@ -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",
+]
@@ -0,0 +1,76 @@
+# LLM-Guided Spec Search — quickstart configuration
+# Copy to ~/.openjarvis/config.toml and run:
+#   python -m openjarvis_examples.spec_search_quickstart
+#
+# This config has two parts:
+#   1. The agent system being optimized (intelligence / engine / agent / tools).
+#      Same schema as the other examples in this directory; parsed by
+#      ``openjarvis.core.config.load_config``.
+#   2. ``[learning.spec_search]`` and its sub-tables — the search hyperparameters
+#      consumed by ``SpecSearchOrchestrator.from_config`` and ``SpecSearchLoop``.
+#
+# Defaults below match the paper (Saad-Falcon et al., 2026):
+#   - max_regression = 0.01    (epsilon in GateOK)
+#   - stagnation_k   = 5       (Algorithm 1 stopping rule)
+#   - composite_reward weights (alpha, beta, gamma, delta) = (0.5, 0.1, 0.1, 0.3)
+#
+# Teacher API keys come from your environment / credentials store, not this file.
+
+# ---------------------------------------------------------------------------
+# Agent system being optimized
+# ---------------------------------------------------------------------------
+
+[engine]
+default = "ollama"               # swap to "vllm" on H100/RTX 6000 / DGX Spark
+
+[intelligence]
+default_model = "qwen3.5:9b"     # the local student
+# default_model = "qwen3.5:27b-fp8"  # workstation tier
+
+[agent]
+default_agent = "orchestrator"   # multi-turn, tool-using
+max_turns = 10
+
+[tools]
+enabled = [
+    "code_interpreter",
+    "file_read",
+    "web_search",
+    "think",
+    "calculator",
+]
+
+# ---------------------------------------------------------------------------
+# LLM-guided spec search hyperparameters (paper §3.3, Algorithm 1)
+# ---------------------------------------------------------------------------
+
+[learning.spec_search]
+enabled = true
+teacher_model = "claude-opus-4-6"      # frontier proposer
+teacher_engine = "cloud"               # CloudEngine registry key (uses LiteLLM)
+autonomy_mode  = "tiered"              # auto | tiered | manual
+
+# Per-session bounds (one diagnose / plan / execute / record pass)
+min_traces                   = 20
+max_cost_per_session_usd     = 5.0
+max_tool_calls_per_diagnosis = 30
+
+# Multi-session loop (paper Algorithm 1 stopping)
+stagnation_k        = 5      # stop after this many sessions with no gate-score gain
+stagnation_eps      = 0.001  # delta below this counts as no improvement
+max_total_cost_usd  = 50.0   # cumulative teacher-cost budget across all sessions
+
+# GateOK predicate — accept iff target cluster improves AND every other cluster
+# regresses by at most max_regression (epsilon in the paper).
+max_regression           = 0.01   # paper default: 1%
+min_improvement          = 0.0
+benchmark_subsample_size = 50
+benchmark_version        = "personal_v1"
+
+# Composite reward (paper Eq. 1) — used only when an Intelligence edit triggers
+# LoRA / GRPO training inside an accepted edit. The held-out gate is unaffected.
+[learning.spec_search.composite_reward]
+alpha = 0.5     # accuracy weight
+beta  = 0.1     # energy penalty
+gamma = 0.1     # latency penalty
+delta = 0.3     # cost penalty
@@ -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=
@@ -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"]
@@ -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"]
@@ -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"]
@@ -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

@@ -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
@@ -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:
@@ -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>
@@ -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
@@ -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
@@ -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).
@@ -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 ""
@@ -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 }
+}
@@ -1,121 +0,0 @@
-# OpenJarvis Desktop
-
-Tauri 2.0 native desktop application for OpenJarvis with auto-updates, energy monitoring, trace debugging, and learning visualization.
-
-## Development Setup
-
-```bash
-# Prerequisites: Node.js 22+, Rust stable, system deps (see below)
-
-cd desktop
-npm install
-cargo tauri dev    # Hot-reload development mode
-cargo tauri build  # Production build
-```
-
-### Linux System Dependencies
-
-```bash
-sudo apt-get install -y \
-  libwebkit2gtk-4.1-dev libgtk-3-dev libappindicator3-dev \
-  librsvg2-dev patchelf libxdo-dev
-```
-
-## Auto-Update Architecture
-
-Every push to `main` (touching `desktop/` or the workflow) triggers a CI pipeline that:
-
-1. Validates TypeScript + Rust (`validate` job)
-2. Builds for Linux, macOS (ARM + Intel), and Windows (`build-and-release` job)
-3. Creates/updates a `desktop-latest` pre-release on GitHub Releases
-4. Uploads platform installers and a signed `latest.json` manifest
-
-The desktop app checks `latest.json` on startup and every 30 minutes. When a newer version is found, it shows a banner prompting the user to download and relaunch.
-
-```
-Push to main -> CI builds -> desktop-latest release -> latest.json
-                                                          |
-Desktop app checks periodically <-------------------------+
-  -> "Update available" banner
-  -> Download in background
-  -> "Relaunch now" prompt
-```
-
-## Releases
-
-### Rolling (Nightly)
-
-Automatic on every push to `main`. Users on the desktop app receive updates seamlessly.
-
-### Stable (Versioned)
-
-```bash
-# Bump version in all 3 config files
-./scripts/bump-desktop-version.sh 1.0.1
-
-# Commit and tag
-git add desktop/package.json desktop/src-tauri/tauri.conf.json desktop/src-tauri/Cargo.toml
-git commit -m "chore(desktop): bump version to 1.0.1"
-git tag desktop-v1.0.1
-git push origin main --tags
-```
-
-CI creates a versioned GitHub Release (e.g., `desktop-v1.0.1`) with full installers.
-
-## Code Signing
-
-### Update Signing (Required for Auto-Updates)
-
-Generate a key pair for signing update manifests:
-
-```bash
-cargo tauri signer generate -w ~/.tauri/openjarvis.key
-```
-
-Set the public key in `src-tauri/tauri.conf.json` under `plugins.updater.pubkey`, then add these GitHub Secrets:
-
-| Secret | Description |
-|--------|-------------|
-| `TAURI_SIGNING_PRIVATE_KEY` | Contents of the `.key` file |
-| `TAURI_SIGNING_PRIVATE_KEY_PASSWORD` | Password used during generation |
-
-### macOS Code Signing & Notarization (Required for Distribution)
-
-Without these secrets, macOS users will see *"OpenJarvis is damaged and can't be opened"* due to Gatekeeper. The CI workflow will **fail release builds** (tag pushes) if signing secrets are missing.
-
-**Prerequisites:** Apple Developer Program membership ($99/year) — [developer.apple.com/programs](https://developer.apple.com/programs/)
-
-| Secret | How to obtain |
-|--------|---------------|
-| `APPLE_CERTIFICATE` | In Keychain Access, export your **Developer ID Application** certificate as `.p12`. Then: `base64 -i cert.p12 \| pbcopy` |
-| `APPLE_CERTIFICATE_PASSWORD` | The password you set during the `.p12` export |
-| `APPLE_SIGNING_IDENTITY` | Full CN string from the certificate, e.g. `"Developer ID Application: Open Jarvis Inc (XXXXXXXXXX)"` |
-| `APPLE_ID` | The Apple ID email associated with your Developer account |
-| `APPLE_PASSWORD` | An **app-specific password** generated at [appleid.apple.com](https://appleid.apple.com) (not your account password) |
-| `APPLE_TEAM_ID` | 10-character team ID from [developer.apple.com/account](https://developer.apple.com/account) |
-
-Add all 6 secrets in **GitHub → Settings → Secrets and variables → Actions**.
-
-#### Local Signing Test
-
-```bash
-export APPLE_SIGNING_IDENTITY="Developer ID Application: ..."
-cd desktop && npm run tauri build -- --target universal-apple-darwin
-```
-
-### Windows Authenticode (Optional)
-
-| Secret | Description |
-|--------|-------------|
-| `WINDOWS_CERTIFICATE` | Base64-encoded `.pfx` certificate |
-| `WINDOWS_CERTIFICATE_PASSWORD` | Certificate password |
-
-Windows signing is optional — unsigned Windows builds work but show a SmartScreen warning on first launch.
-
-## Dashboard Panels
-
- **Energy** — Real-time power monitoring (recharts)
- **Traces** — Timeline inspection with step-type color coding
- **Learning** — Policy visualization (GRPO/bandit stats)
- **Memory** — Search and stats for memory backends
- **Admin** — Health checks, agent management, server control
@@ -1,12 +0,0 @@
-<!doctype html>
-<html lang="en">
-  <head>
-    <meta charset="UTF-8" />
-    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
-    <title>OpenJarvis Desktop</title>
-  </head>
-  <body>
-    <div id="root"></div>
-    <script type="module" src="/src/main.tsx"></script>
-  </body>
-</html>
@@ -1,32 +0,0 @@
-{
-  "name": "openjarvis-desktop",
-  "private": true,
-  "version": "0.1.0",
-  "type": "module",
-  "scripts": {
-    "dev": "npm --prefix ../frontend run dev",
-    "build": "npm --prefix ../frontend run build:tauri",
-    "preview": "npm --prefix ../frontend run preview",
-    "tauri": "tauri"
-  },
-  "dependencies": {
-    "@tauri-apps/api": "^2",
-    "@tauri-apps/plugin-notification": "^2",
-    "@tauri-apps/plugin-shell": "^2",
-    "@tauri-apps/plugin-global-shortcut": "^2",
-    "@tauri-apps/plugin-autostart": "^2",
-    "@tauri-apps/plugin-updater": "^2",
-    "@tauri-apps/plugin-process": "^2",
-    "react": "^19.0.0",
-    "react-dom": "^19.0.0",
-    "recharts": "^2.15.0"
-  },
-  "devDependencies": {
-    "@tauri-apps/cli": "^2",
-    "@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"
-  }
-}
@@ -1,27 +0,0 @@
-[package]
-name = "openjarvis-desktop"
-version = "0.1.0"
-description = "OpenJarvis Desktop — Native AI assistant with energy monitoring, trace debugging, and learning visualization"
-edition = "2021"
-license = "MIT"
-
-[build-dependencies]
-tauri-build = { version = "2", features = [] }
-
-[dependencies]
-tauri = { version = "2", features = ["tray-icon"] }
-tauri-plugin-notification = "2"
-tauri-plugin-shell = "2"
-tauri-plugin-global-shortcut = "2"
-tauri-plugin-autostart = "2"
-tauri-plugin-updater = "2"
-tauri-plugin-single-instance = "2"
-tauri-plugin-process = "2"
-serde = { version = "1", features = ["derive"] }
-serde_json = "1"
-reqwest = { version = "0.12", features = ["json", "multipart"] }
-tokio = { version = "1", features = ["full"] }
-
-[features]
-default = ["custom-protocol"]
-custom-protocol = ["tauri/custom-protocol"]
@@ -1,20 +0,0 @@
-<?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>com.apple.security.app-sandbox</key>
-    <false/>
-    <key>com.apple.security.network.client</key>
-    <true/>
-    <key>com.apple.security.network.server</key>
-    <true/>
-    <key>com.apple.security.files.user-selected.read-write</key>
-    <true/>
-    <key>com.apple.security.cs.allow-jit</key>
-    <true/>
-    <key>com.apple.security.cs.allow-unsigned-executable-memory</key>
-    <true/>
-    <key>com.apple.security.cs.disable-library-validation</key>
-    <true/>
-</dict>
-</plist>
@@ -1,3 +0,0 @@
-fn main() {
-    tauri_build::build();
-}
@@ -1,6 +0,0 @@
-// Prevents additional console window on Windows in release
-#![cfg_attr(not(debug_assertions), windows_subsystem = "windows")]
-
-fn main() {
-    openjarvis_desktop::run();
-}
@@ -0,0 +1,450 @@
+<!DOCTYPE html>
+<html>
+<head>
+<meta charset="utf-8">
+<style>
+*{margin:0;padding:0;box-sizing:border-box}
+html,body,:root{
+  background:transparent !important;
+  background-color:transparent !important;
+  font-family:-apple-system,BlinkMacSystemFont,"SF Pro Text",sans-serif;
+  color:#fff;height:100%;overflow:hidden;
+}
+#container{
+  display:flex;flex-direction:column;
+  height:100%;padding:8px 12px;
+}
+#messages{
+  flex:1;overflow-y:auto;
+  display:flex;flex-direction:column;gap:6px;
+  margin-bottom:8px;padding:12px;
+  border-radius:16px;
+  background:rgba(30,30,30,0.88);
+  border:1px solid rgba(255,255,255,0.20);
+}
+#messages:empty{display:none}
+#messages::-webkit-scrollbar{width:6px}
+#messages::-webkit-scrollbar-thumb{background:rgba(255,255,255,0.15);border-radius:3px}
+#messages::-webkit-scrollbar-track{background:transparent}
+.msg{
+  padding:8px 12px;border-radius:12px;
+  font-size:13px;line-height:1.55;max-width:90%;
+  white-space:pre-wrap;word-wrap:break-word;
+  -webkit-user-select:text;user-select:text;
+}
+.msg.user{
+  align-self:flex-end;
+  background:rgba(59,130,246,0.35);
+  color:rgba(255,255,255,0.95);
+}
+.msg.assistant{
+  align-self:flex-start;
+  background:rgba(255,255,255,0.20);
+  color:rgba(255,255,255,0.88);
+  white-space:normal;
+}
+.msg.assistant > p{margin:0 0 6px 0;white-space:pre-wrap}
+.msg.assistant > p:last-child{margin-bottom:0}
+.msg.assistant h1,.msg.assistant h2,.msg.assistant h3{
+  font-size:14px;font-weight:600;margin:6px 0 4px 0;
+}
+.msg.assistant ul,.msg.assistant ol{margin:2px 0 6px 18px;padding:0}
+.msg.assistant li{margin:1px 0}
+.msg.assistant a{color:#93c5fd;text-decoration:underline}
+.msg.assistant code{
+  background:rgba(0,0,0,0.35);
+  padding:1px 5px;border-radius:4px;
+  font-family:"SF Mono",Menlo,Monaco,monospace;
+  font-size:12px;
+}
+.msg.assistant pre{
+  background:rgba(0,0,0,0.40);
+  padding:8px 10px;border-radius:8px;
+  margin:4px 0;overflow-x:auto;
+  border:1px solid rgba(255,255,255,0.08);
+}
+.msg.assistant pre code{
+  background:transparent;padding:0;border-radius:0;
+  font-size:11.5px;line-height:1.4;white-space:pre;
+}
+.msg.assistant strong{font-weight:600;color:#fff}
+.msg.assistant em{font-style:italic}
+.msg.assistant del{opacity:0.6;text-decoration:line-through}
+
+/* Streaming caret — pulses at the end of the in-progress bubble */
+.caret{
+  display:inline-block;width:6px;height:13px;
+  vertical-align:text-bottom;margin-left:2px;
+  background:rgba(255,255,255,0.85);
+  animation:caret-blink 1s steps(1) infinite;
+}
+@keyframes caret-blink{50%{opacity:0}}
+
+/* Thinking dots — shown while waiting for the first token */
+.thinking{
+  display:inline-flex;gap:4px;align-items:center;padding:2px 0;
+}
+.thinking span{
+  width:6px;height:6px;border-radius:50%;
+  background:rgba(255,255,255,0.65);
+  animation:thinking-bounce 1.2s ease-in-out infinite;
+}
+.thinking span:nth-child(2){animation-delay:0.15s}
+.thinking span:nth-child(3){animation-delay:0.30s}
+@keyframes thinking-bounce{
+  0%,60%,100%{transform:translateY(0);opacity:0.4}
+  30%{transform:translateY(-4px);opacity:1}
+}
+#input-bar{
+  display:flex;align-items:center;gap:6px;
+  border-radius:16px;padding:6px 8px;
+  background:rgba(30,30,30,0.88);
+  border:1px solid rgba(255,255,255,0.20);
+  flex-shrink:0;
+}
+#model-wrap{
+  position:relative;flex-shrink:0;
+}
+#model-select{
+  background:rgba(255,255,255,0.08);color:rgba(255,255,255,0.6);
+  border:none;border-radius:8px;padding:4px 22px 4px 8px;
+  font-size:11px;outline:none;cursor:pointer;
+  max-width:140px;
+  -webkit-appearance:none;appearance:none;
+}
+#model-select:hover{background:rgba(255,255,255,0.14);color:#fff}
+#model-wrap .arrow{
+  position:absolute;right:7px;top:50%;transform:translateY(-50%);
+  pointer-events:none;color:rgba(255,255,255,0.35);
+}
+#model-select option,#model-select optgroup{
+  background:#1e1e1e;color:#eee;
+}
+#input{
+  flex:1;background:transparent;border:none;outline:none;
+  color:#fff;font-size:14px;padding:6px 10px;
+}
+#input::placeholder{color:rgba(255,255,255,0.35)}
+.btn{
+  display:flex;align-items:center;justify-content:center;
+  width:30px;height:30px;border-radius:50%;border:none;
+  background:rgba(255,255,255,0.10);
+  color:rgba(255,255,255,0.6);cursor:pointer;
+  transition:background .15s,color .15s;flex-shrink:0;
+}
+.btn:hover{background:rgba(255,255,255,0.20);color:#fff}
+.btn:disabled{opacity:0.25;cursor:default}
+.btn:disabled:hover{background:rgba(255,255,255,0.10)}
+</style>
+</head>
+<body>
+<div id="container">
+  <div id="messages"></div>
+  <div id="input-bar">
+    <button id="new-btn" class="btn" title="New conversation">
+      <svg width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2.5" stroke-linecap="round" stroke-linejoin="round"><line x1="12" y1="5" x2="12" y2="19"/><line x1="5" y1="12" x2="19" y2="12"/></svg>
+    </button>
+    <div id="model-wrap">
+      <select id="model-select"><option>loading...</option></select>
+      <svg class="arrow" width="10" height="10" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2.5" stroke-linecap="round" stroke-linejoin="round"><polyline points="6 9 12 15 18 9"/></svg>
+    </div>
+    <input id="input" type="text" placeholder="Ask Jarvis anything..." autofocus>
+    <button id="send-btn" class="btn" disabled title="Send">
+      <svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><line x1="12" y1="19" x2="12" y2="5"/><polyline points="5 12 12 5 19 12"/></svg>
+    </button>
+  </div>
+</div>
+<script type="application/json" id="saved-data">__SAVED_MESSAGES__</script>
+<script type="application/json" id="cloud-data">__CLOUD_MODELS__</script>
+<script>
+const input=document.getElementById('input');
+const sendBtn=document.getElementById('send-btn');
+const messagesEl=document.getElementById('messages');
+let streaming=false,abort=null,model='qwen3.5:4b';
+let convId='', convTitle='Overlay chat', convCreated=Date.now();
+let messages=[];
+
+function genId(){return Date.now().toString(36)+Math.random().toString(36).slice(2,8)}
+
+// Restore previous conversation
+try{
+  const raw=document.getElementById('saved-data').textContent.trim();
+  if(raw&&raw!=='__SAVED_PLACEHOLDER__'){
+    const saved=JSON.parse(raw);
+    if(saved.id){convId=saved.id;convTitle=saved.title||convTitle;convCreated=saved.createdAt||convCreated;messages=saved.messages||[]}
+    else if(Array.isArray(saved)){messages=saved}
+  }
+}catch{}
+if(!convId) convId=genId();
+if(messages.length) renderAll();
+
+// Build model dropdown: local (installed) + cloud (keyed)
+const modelSelect=document.getElementById('model-select');
+let cloudModels=[];
+try{
+  const cd=document.getElementById('cloud-data').textContent.trim();
+  if(cd&&cd!=='__CLOUD_PLACEHOLDER__') cloudModels=JSON.parse(cd);
+}catch{}
+
+fetch('/v1/models').then(r=>r.json()).then(d=>{
+  const local=(Array.isArray(d)?d:(d.data||d.models||[])).map(m=>m.id||m.name).filter(Boolean);
+  while(modelSelect.firstChild) modelSelect.removeChild(modelSelect.firstChild);
+  if(local.length){
+    const g=document.createElement('optgroup');g.label='Local';
+    local.forEach(id=>{const o=document.createElement('option');o.value=id;o.textContent=id;g.appendChild(o)});
+    modelSelect.appendChild(g);
+  }
+  if(cloudModels.length){
+    const g=document.createElement('optgroup');g.label='Cloud';
+    cloudModels.forEach(id=>{const o=document.createElement('option');o.value=id;o.textContent=id;g.appendChild(o)});
+    modelSelect.appendChild(g);
+  }
+  // Restore saved model or pick first available
+  const saved=messages.length&&messages[0].model;
+  if(saved&&modelSelect.querySelector('option[value="'+CSS.escape(saved)+'"]')){modelSelect.value=saved}
+  model=modelSelect.value||model;
+}).catch(()=>{});
+modelSelect.addEventListener('change',()=>{model=modelSelect.value});
+
+const SEND='<svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><line x1="12" y1="19" x2="12" y2="5"/><polyline points="5 12 12 5 19 12"/></svg>';
+const STOP='<svg width="16" height="16" viewBox="0 0 24 24" fill="currentColor"><rect x="6" y="6" width="12" height="12" rx="2"/></svg>';
+
+function renderAll(){
+  while(messagesEl.firstChild) messagesEl.removeChild(messagesEl.firstChild);
+  for(const m of messages) bubble(m.role,m.content);
+  scroll();
+}
+function bubble(role,text){
+  const d=document.createElement('div');
+  d.className='msg '+(role==='user'?'user':'assistant');
+  if(role==='assistant') setHtml(d, md(text||''));
+  else d.textContent=text;
+  messagesEl.appendChild(d);
+  return d;
+}
+function scroll(){messagesEl.scrollTop=messagesEl.scrollHeight}
+
+// Safe HTML injection helper. All incoming LLM/user text is escaped
+// via escHtml() before any markdown transformations, so the string
+// reaching this function only contains tags from our controlled
+// regex replacements. We use Range.createContextualFragment which is
+// the W3C-recommended way to construct a DocumentFragment from HTML.
+function setHtml(el,html){
+  while(el.firstChild) el.removeChild(el.firstChild);
+  const range=document.createRange();
+  range.selectNodeContents(el);
+  el.appendChild(range.createContextualFragment(html));
+}
+
+// --- Minimal markdown renderer (inline, no deps) ---
+//     Handles: fenced code, inline code, headings, bold, italic,
+//     strikethrough, links, ordered/unordered lists, paragraphs.
+function escHtml(s){
+  return s.replace(/&/g,'&amp;').replace(/</g,'&lt;').replace(/>/g,'&gt;')
+          .replace(/"/g,'&quot;').replace(/'/g,'&#39;');
+}
+function md(src){
+  if(!src)return '';
+  const blocks=[],inlines=[];
+  // 1. Extract fenced code blocks first so their contents aren't touched.
+  src=src.replace(/```(\w*)\n?([\s\S]*?)```/g,(_,lang,code)=>{
+    blocks.push({lang,code});
+    return '\u0000CB'+(blocks.length-1)+'\u0000';
+  });
+  // 2. Extract inline code (single-line backticks).
+  src=src.replace(/`([^`\n]+)`/g,(_,c)=>{
+    inlines.push(c);
+    return '\u0000IC'+(inlines.length-1)+'\u0000';
+  });
+  // 3. Escape everything else.
+  src=escHtml(src);
+  // 4. Headings.
+  src=src.replace(/^###\s+(.+)$/gm,'<h3>$1</h3>')
+         .replace(/^##\s+(.+)$/gm,'<h2>$1</h2>')
+         .replace(/^#\s+(.+)$/gm,'<h1>$1</h1>');
+  // 5. Bold / italic / strikethrough.
+  src=src.replace(/\*\*([^*\n]+)\*\*/g,'<strong>$1</strong>')
+         .replace(/__([^_\n]+)__/g,'<strong>$1</strong>')
+         .replace(/(^|[^*\w])\*([^*\n]+)\*(?!\*)/g,'$1<em>$2</em>')
+         .replace(/(^|[^_\w])_([^_\n]+)_(?!_)/g,'$1<em>$2</em>')
+         .replace(/~~([^~\n]+)~~/g,'<del>$1</del>');
+  // 6. Links — url is escaped above, so quotes are safe.
+  src=src.replace(/\[([^\]\n]+)\]\(([^)\s]+)\)/g,'<a href="$2" target="_blank" rel="noopener">$1</a>');
+  // 7. Unordered + ordered lists.
+  src=src.replace(/(?:^[-*]\s+.+(?:\n|$))+/gm,block=>{
+    const items=block.trim().split('\n')
+      .map(l=>'<li>'+l.replace(/^[-*]\s+/,'')+'</li>').join('');
+    return '<ul>'+items+'</ul>';
+  });
+  src=src.replace(/(?:^\d+\.\s+.+(?:\n|$))+/gm,block=>{
+    const items=block.trim().split('\n')
+      .map(l=>'<li>'+l.replace(/^\d+\.\s+/,'')+'</li>').join('');
+    return '<ol>'+items+'</ol>';
+  });
+  // 8. Paragraphs: split on blank lines, wrap non-block chunks in <p>.
+  src=src.split(/\n{2,}/).map(chunk=>{
+    const t=chunk.trim();
+    if(!t)return '';
+    if(/^<(h\d|ul|ol|pre|blockquote)/.test(t))return t;
+    if(t.startsWith('\u0000CB'))return t;
+    return '<p>'+t.replace(/\n/g,'<br>')+'</p>';
+  }).join('');
+  // 9. Restore inline code.
+  src=src.replace(/\u0000IC(\d+)\u0000/g,(_,i)=>'<code>'+escHtml(inlines[+i])+'</code>');
+  // 10. Restore fenced code blocks.
+  src=src.replace(/\u0000CB(\d+)\u0000/g,(_,i)=>{
+    const b=blocks[+i];
+    const cls=b.lang?' class="lang-'+escHtml(b.lang)+'"':'';
+    return '<pre><code'+cls+'>'+escHtml(b.code)+'</code></pre>';
+  });
+  return src;
+}
+const THINKING='<span class="thinking"><span></span><span></span><span></span></span>';
+const CARET='<span class="caret"></span>';
+const CLOUD_PFX=['gpt-','o1-','o3-','o4-','claude-','gemini-','openrouter/','chatgpt-'];
+function save(){
+  const conv={id:convId,title:convTitle,createdAt:convCreated,updatedAt:Date.now(),model,
+    messages:messages.map((m,i)=>{
+      const o={id:convId+'_'+i,role:m.role,content:m.content,timestamp:m.timestamp||Date.now()};
+      if(m.usage)o.usage=m.usage;
+      if(m.telemetry)o.telemetry=m.telemetry;
+      return o;
+    })};
+  try{window.webkit.messageHandlers.overlay.postMessage('save:'+JSON.stringify(conv))}catch{}
+}
+
+input.addEventListener('input',()=>{sendBtn.disabled=!input.value.trim()||streaming});
+input.addEventListener('keydown',e=>{
+  if(e.key==='Enter'&&!e.shiftKey){e.preventDefault();send()}
+});
+document.addEventListener('keydown',e=>{
+  if(e.key==='Escape'){
+    if(streaming){abort&&abort.abort()}
+    else{try{window.webkit.messageHandlers.overlay.postMessage('hide')}catch{}}
+  }
+});
+sendBtn.addEventListener('click',()=>{if(streaming){abort&&abort.abort()}else send()});
+document.getElementById('new-btn').addEventListener('click',()=>{
+  convId=genId();convTitle='Overlay chat';convCreated=Date.now();
+  messages=[];
+  while(messagesEl.firstChild) messagesEl.removeChild(messagesEl.firstChild);
+  save();input.focus();
+});
+
+async function send(){
+  const text=input.value.trim();
+  if(!text||streaming)return;
+  input.value='';sendBtn.disabled=true;
+
+  messages.push({role:'user',content:text,timestamp:Date.now()});
+  if(messages.length===1) convTitle=text.slice(0,50)+(text.length>50?'...':'');
+  bubble('user',text);scroll();save();
+
+  streaming=true;abort=new AbortController();
+  setHtml(sendBtn,STOP);sendBtn.disabled=false;
+  const b=bubble('assistant','');
+  // Show thinking dots until the first token arrives.
+  setHtml(b,THINKING);
+  scroll();
+
+  let acc='',usage=null,complexity=null,ttft=0;
+  const t0=Date.now();
+  // Throttle markdown re-renders to ~30fps so tight streams don't
+  // rebuild the DOM on every single token.
+  let pending=false;
+  const render=()=>{
+    if(pending)return;
+    pending=true;
+    requestAnimationFrame(()=>{
+      pending=false;
+      setHtml(b, md(acc)+CARET);
+      scroll();
+    });
+  };
+  try{
+    const r=await fetch('/v1/chat/completions',{
+      method:'POST',headers:{'Content-Type':'application/json'},
+      body:JSON.stringify({model,messages,stream:true}),
+      signal:abort.signal
+    });
+    if(!r.ok)throw new Error(r.status);
+    const reader=r.body.getReader(),dec=new TextDecoder();
+    let buf='';
+    for(;;){
+      const{done,value}=await reader.read();
+      if(done)break;
+      buf+=dec.decode(value,{stream:true});
+      const lines=buf.split('\n');buf=lines.pop()||'';
+      for(const ln of lines){
+        if(!ln.startsWith('data: '))continue;
+        const d=ln.slice(6);if(d==='[DONE]')break;
+        try{
+          const p=JSON.parse(d);
+          if(p.usage)usage=p.usage;
+          if(p.complexity)complexity=p.complexity;
+          const c=p.choices?.[0]?.delta?.content;
+          if(c){if(!ttft)ttft=Date.now()-t0;acc+=c;render()}
+        }catch{}
+      }
+    }
+  }catch(e){
+    if(e.name!=='AbortError'){
+      acc='Could not get a response. Is the backend running?';
+      b.textContent=acc;
+    }
+  }finally{
+    streaming=false;abort=null;
+    setHtml(sendBtn,SEND);sendBtn.disabled=!input.value.trim();
+    input.focus();
+    // Final render without the caret.
+    if(acc) setHtml(b, md(acc));
+    else if(b.querySelector('.thinking')) b.textContent='';
+  }
+  if(acc){
+    const totalMs=Date.now()-t0;
+    const engine=CLOUD_PFX.some(p=>model.startsWith(p))?'cloud':'ollama';
+    const telem={engine,model_id:model,total_ms:totalMs,ttft_ms:ttft||undefined,
+      tokens_per_sec:usage?.completion_tokens?usage.completion_tokens/(totalMs/1000):undefined,
+      complexity_score:complexity?.score,complexity_tier:complexity?.tier,
+      suggested_max_tokens:complexity?.suggested_max_tokens};
+    messages.push({role:'assistant',content:acc,timestamp:Date.now(),usage:usage||undefined,telemetry:telem});
+    save();
+  }
+}
+
+window.addEventListener('focus',()=>input.focus());
+
+// --- Drag-to-move: click anywhere to drag, with threshold so
+//     clicks on inputs/buttons still work normally ---
+(function(){
+  let down=false,dragging=false,sx=0,sy=0;
+  const THRESH=3;
+  const INTERACTIVE='input,select,button,textarea,a,label,[contenteditable="true"],[role="button"]';
+  document.addEventListener('mousedown',e=>{
+    if(e.target.closest('select'))return;
+    down=true;dragging=false;sx=e.screenX;sy=e.screenY;
+  });
+  // macOS native select menus swallow the mouseup — reset on change too
+  document.getElementById('model-select').addEventListener('mousedown',()=>{down=false;dragging=false});
+  document.getElementById('model-select').addEventListener('change',()=>{down=false;dragging=false});
+  document.addEventListener('mousemove',e=>{
+    if(!down)return;
+    // If the mouse button is no longer pressed (e.g. the user released
+    // it over a native menu that swallowed mouseup), abort the drag.
+    if(e.buttons===0){down=false;dragging=false;return;}
+    const dx=e.screenX-sx,dy=e.screenY-sy;
+    if(!dragging){
+      if(Math.abs(dx)+Math.abs(dy)<THRESH)return;
+      dragging=true;
+    }
+    sx=e.screenX;sy=e.screenY;
+    try{window.webkit.messageHandlers.overlay.postMessage('drag:'+dx+','+dy)}catch{}
+  });
+  const reset=()=>{down=false;dragging=false};
+  document.addEventListener('mouseup',reset);
+  window.addEventListener('blur',reset);
+  document.addEventListener('mouseleave',reset);
+})();
+</script>
+</body>
+</html>
@@ -1,71 +0,0 @@
-{
-  "$schema": "https://schema.tauri.app/config/2",
-  "productName": "OpenJarvis",
-  "version": "0.1.0",
-  "identifier": "com.openjarvis.desktop",
-  "build": {
-    "frontendDist": "../../frontend/dist",
-    "devUrl": "http://localhost:5173",
-    "beforeDevCommand": "npm run dev",
-    "beforeBuildCommand": "npm run build"
-  },
-  "app": {
-    "windows": [
-      {
-        "title": "OpenJarvis",
-        "width": 1280,
-        "height": 800,
-        "minWidth": 900,
-        "minHeight": 600,
-        "resizable": true,
-        "fullscreen": false,
-        "decorations": true,
-        "transparent": false
-      }
-    ],
-    "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:"
-    }
-  },
-  "bundle": {
-    "active": true,
-    "targets": "all",
-    "createUpdaterArtifacts": true,
-    "icon": [
-      "icons/32x32.png",
-      "icons/128x128.png",
-      "icons/128x128@2x.png",
-      "icons/icon.icns",
-      "icons/icon.ico",
-      "icons/icon.png"
-    ],
-    "category": "Utility",
-    "shortDescription": "On-device AI assistant with energy monitoring and trace debugging",
-    "longDescription": "OpenJarvis Desktop wraps the OpenJarvis research framework in a native desktop application with real-time energy monitoring, trace debugging, learning curve visualization, and memory browsing.",
-    "macOS": {
-      "entitlements": "Entitlements.plist",
-      "minimumSystemVersion": "10.15",
-      "exceptionDomain": "",
-      "frameworks": [],
-      "providerShortName": null,
-      "signingIdentity": "-"
-    },
-    "windows": {
-      "certificateThumbprint": null,
-      "digestAlgorithm": "sha256",
-      "timestampUrl": "http://timestamp.digicert.com"
-    }
-  },
-  "plugins": {
-    "updater": {
-      "active": false,
-      "pubkey": "dW50cnVzdGVkIGNvbW1lbnQ6IG1pbmlzaWduIHB1YmxpYyBrZXk6IDFFNzUzMzhEOEY2MjNEMDMKUldRRFBXS1BqVE4xSG8vK0lkUWN4WnZQYVIrbmc4RmpoOGlJWTBLTE15RlIya3JvQisvdUR3a0QK",
-      "endpoints": []
-    },
-    "deep-link": {
-      "desktop": {
-        "schemes": ["openjarvis"]
-      }
-    }
-  }
-}
@@ -1,116 +0,0 @@
-import React, { useState } from 'react';
-import { UpdateChecker } from './components/UpdateChecker';
-import { SavingsDashboard } from './components/SavingsDashboard';
-import { EnergyDashboard } from './components/EnergyDashboard';
-import { TraceDebugger } from './components/TraceDebugger';
-import { LearningCurve } from './components/LearningCurve';
-import { MemoryBrowser } from './components/MemoryBrowser';
-import { AdminPanel } from './components/AdminPanel';
-import { SettingsPanel } from './components/SettingsPanel';
-import { AgentsPanel } from './components/AgentsPanel';
-
-type TabId = 'savings' | 'energy' | 'traces' | 'learning' | 'memory' | 'agents' | 'admin' | 'settings';
-
-interface Tab {
-  id: TabId;
-  label: string;
-}
-
-const TABS: Tab[] = [
-  { id: 'savings', label: 'Savings' },
-  { id: 'energy', label: 'Energy' },
-  { id: 'traces', label: 'Traces' },
-  { id: 'learning', label: 'Learning' },
-  { id: 'memory', label: 'Memory' },
-  { id: 'agents', label: 'Agents' },
-  { id: 'admin', label: 'Admin' },
-  { id: 'settings', label: 'Settings' },
-];
-
-const API_URL = 'http://localhost:8000';
-
-export function App() {
-  const [activeTab, setActiveTab] = useState<TabId>('savings');
-
-  return (
-    <div style={styles.container}>
-      <header style={styles.header}>
-        <h1 style={styles.title}>OpenJarvis Desktop</h1>
-        <nav style={styles.nav}>
-          {TABS.map((tab) => (
-            <button
-              key={tab.id}
-              onClick={() => setActiveTab(tab.id)}
-              style={{
-                ...styles.tabButton,
-                ...(activeTab === tab.id ? styles.activeTab : {}),
-              }}
-            >
-              {tab.label}
-            </button>
-          ))}
-        </nav>
-      </header>
-
-      <UpdateChecker />
-
-      <main style={styles.main}>
-        {activeTab === 'savings' && <SavingsDashboard apiUrl={API_URL} />}
-        {activeTab === 'energy' && <EnergyDashboard apiUrl={API_URL} />}
-        {activeTab === 'traces' && <TraceDebugger apiUrl={API_URL} />}
-        {activeTab === 'learning' && <LearningCurve apiUrl={API_URL} />}
-        {activeTab === 'memory' && <MemoryBrowser apiUrl={API_URL} />}
-        {activeTab === 'agents' && <AgentsPanel apiUrl={API_URL} />}
-        {activeTab === 'admin' && <AdminPanel apiUrl={API_URL} />}
-        {activeTab === 'settings' && <SettingsPanel />}
-      </main>
-    </div>
-  );
-}
-
-const styles: Record<string, React.CSSProperties> = {
-  container: {
-    minHeight: '100vh',
-    backgroundColor: '#1e1e2e',
-    color: '#cdd6f4',
-    fontFamily: '-apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif',
-  },
-  header: {
-    display: 'flex',
-    alignItems: 'center',
-    justifyContent: 'space-between',
-    padding: '12px 24px',
-    borderBottom: '1px solid #313244',
-    backgroundColor: '#181825',
-  },
-  title: {
-    fontSize: '18px',
-    fontWeight: 600,
-    margin: 0,
-    color: '#89b4fa',
-  },
-  nav: {
-    display: 'flex',
-    gap: '4px',
-  },
-  tabButton: {
-    padding: '8px 16px',
-    border: 'none',
-    borderRadius: '6px',
-    backgroundColor: 'transparent',
-    color: '#a6adc8',
-    cursor: 'pointer',
-    fontSize: '14px',
-    fontWeight: 500,
-    transition: 'all 0.15s ease',
-  },
-  activeTab: {
-    backgroundColor: '#313244',
-    color: '#cdd6f4',
-  },
-  main: {
-    padding: '24px',
-    height: 'calc(100vh - 60px)',
-    overflow: 'auto',
-  },
-};
@@ -1,9 +0,0 @@
-import React from 'react';
-import ReactDOM from 'react-dom/client';
-import { App } from './App';
-
-ReactDOM.createRoot(document.getElementById('root')!).render(
-  <React.StrictMode>
-    <App />
-  </React.StrictMode>,
-);
@@ -1,21 +0,0 @@
-{
-  "compilerOptions": {
-    "target": "ES2020",
-    "useDefineForClassFields": true,
-    "lib": ["ES2020", "DOM", "DOM.Iterable"],
-    "module": "ESNext",
-    "skipLibCheck": true,
-    "moduleResolution": "bundler",
-    "allowImportingTsExtensions": true,
-    "isolatedModules": true,
-    "moduleDetection": "force",
-    "noEmit": true,
-    "jsx": "react-jsx",
-    "strict": true,
-    "noUnusedLocals": false,
-    "noUnusedParameters": false,
-    "noFallthroughCasesInSwitch": true,
-    "forceConsistentCasingInFileNames": true
-  },
-  "include": ["src"]
-}
@@ -1 +0,0 @@
-{"root":["./src/App.tsx","./src/main.tsx","./src/components/AdminPanel.tsx","./src/components/EnergyDashboard.tsx","./src/components/LearningCurve.tsx","./src/components/MemoryBrowser.tsx","./src/components/TraceDebugger.tsx","./src/components/UpdateChecker.tsx","./src/hooks/useTauriApi.ts"],"version":"5.7.3"}
@@ -1,20 +0,0 @@
-import { defineConfig } from 'vite';
-import react from '@vitejs/plugin-react';
-
-export default defineConfig({
-  plugins: [react()],
-  build: {
-    outDir: 'dist',
-    emptyOutDir: true,
-  },
-  server: {
-    port: 5173,
-    strictPort: true,
-    proxy: {
-      '/v1': 'http://localhost:8000',
-      '/health': 'http://localhost:8000',
-    },
-  },
-  clearScreen: false,
-  envPrefix: ['VITE_', 'TAURI_'],
-});
@@ -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.
@@ -553,3 +553,60 @@ metric can be improved without degrading another.
 The optimization framework has full Rust parity via the `openjarvis-learning`
 crate, with PyO3 bindings exposing `OptimizationStore` and `LLMOptimizer`
 to Python.
+
+---
+
+## LLM-Guided Spec Search (Frontier-Driven Harness Learning)
+
+LLM-guided spec search uses a frontier closed-source model (the "teacher") as a meta-engineer for the local student's full harness — not just its weights. Instead of pushing knowledge into a small model's weights, we push a frontier model's engineering judgement into the surrounding configuration: prompts, routing, agent class, tool availability, and tool descriptions.
+
+### Where it lives
+
+`learning/spec_search/` is the fifth subsystem within the Learning pillar, alongside `learning/routing/`, `learning/optimize/`, `learning/training/`, and `learning/intelligence/`.
+
+### Four-phase loop
+
+```
+Trigger → Diagnose → Plan → Execute → Record
+```
+
+1. **Diagnose** — TeacherAgent (frontier model with diagnostic tools) analyzes traces, runs student/teacher comparisons, identifies 2-5 failure clusters with evidence.
+2. **Plan** — LearningPlanner converts diagnosis into a typed LearningPlan with deterministic risk tier assignment and patch/replace downgrade.
+3. **Execute** — Per-edit loop: EditApplier validates + applies, BenchmarkGate scores, CheckpointStore commits or rolls back.
+4. **Record** — LearningSession persisted to SQLite + JSON artifact.
+
+### Key components
+
+| Component | Module | Purpose |
+|-----------|--------|---------|
+| `SpecSearchOrchestrator` | `orchestrator.py` | Top-level session driver |
+| `TeacherAgent` | `diagnose/teacher_agent.py` | Frontier model tool-calling loop |
+| `DiagnosisRunner` | `diagnose/runner.py` | Phase 1 orchestration |
+| `LearningPlanner` | `plan/planner.py` | Diagnosis → typed LearningPlan |
+| `EditApplier` + registry | `execute/base.py` | Abstract applier interface |
+| `BenchmarkGate` | `gate/benchmark_gate.py` | Benchmark-based accept/reject |
+| `CheckpointStore` | `checkpoint/store.py` | Git-backed config rollback |
+| `SessionStore` | `storage/session_store.py` | SQLite session persistence |
+
+### Relationship to existing subsystems
+
+| Existing | Relationship |
+|----------|-------------|
+| `LearningOrchestrator` | Sibling — stays untouched |
+| `LLMOptimizer` / `OptimizationStore` | Sibling — grid-search vs root-cause |
+| `LearnedRouterPolicy` | Reused — routing edits update it |
+| `TraceJudge` | Reused — benchmark scoring |
+| `PersonalBenchmarkSynthesizer` | Extended — auto-refresh, gold answers |
+| `TraceStore` | Reused — read-only access from diagnostic tools |
+
+### Risk tier system
+
+Every edit is assigned a tier from a deterministic lookup table:
+
+| Tier | Ops | Behavior |
+|------|-----|----------|
+| `auto` | Model routing/params, tool add/remove/description, agent params | Apply if gate passes |
+| `review` | System prompt edits, agent class, few-shot exemplars | Queue for user approval |
+| `manual` | LoRA fine-tuning (v2) | Never auto-apply |
+
+See [LLM-guided spec search guide](../user-guide/llm-guided-spec-search.md) for the architecture and the building blocks.
@@ -45,7 +45,7 @@ The memory pipeline includes document ingestion, chunking, embedding generation,

 The Learning system is the fifth primitive, connecting the other four through **trace-driven feedback**. Every agent interaction can produce a `Trace` capturing the full sequence of steps — routing decisions, memory retrieval, inference calls, tool invocations, and final responses. The `TraceAnalyzer` computes statistics from accumulated traces, and the `TraceDrivenPolicy` uses these statistics to learn which model/agent/tool combinations produce the best outcomes for different query types.

-The learning system is configured through nested sub-sections in `config.toml`: `[learning.routing]` controls the router policy (heuristic, learned, sft, grpo), `[learning.intelligence]` controls the model-level learning policy, `[learning.agent]` controls agent advisor and ICL updater policies, and `[learning.metrics]` sets the composite reward function weights.
+The learning system is configured through nested sub-sections in `config.toml`: `[learning.routing]` controls the router policy (heuristic, learned, sft, grpo), `[learning.intelligence]` controls the model-level learning policy, `[learning.agent]` controls agent advisor and ICL updater policies, and `[learning.metrics]` sets the composite reward function weights. The pillar also includes LLM-guided spec search, a frontier-driven loop that improves the local harness — see [Learning architecture: LLM-guided spec search](learning.md#llm-guided-spec-search-frontier-driven-harness-learning).

 ---

@@ -0,0 +1,45 @@
+# Showcase screenshots
+
+This directory holds the hero screenshot for each Showcase entry in `docs/showcase/`. Convention is one file per entry, named to match the entry's slug:
+
+| Entry | Screenshot path |
+|---|---|
+| `docs/showcase/morning-brief.md` | `morning-brief.png` |
+| `docs/showcase/persistent-memory.md` | `persistent-memory.png` |
+| `docs/showcase/cost-savings.md` | `cost-savings.png` |
+| `docs/showcase/discord-companion.md` | `discord-companion.png` |
+| `docs/showcase/coding-assistant.md` | `coding-assistant.png` |
+
+## Conventions
+
+| | |
+|---|---|
+| Format | PNG, sRGB, no alpha channel |
+| Size | 1600×1000 (4:2.5 — wider than 16:9, so screenshots don't get letterboxed in the docs grid) |
+| File size | Under 400 KB after `pngquant --quality 70-90 --speed 1` |
+| Loading | All `<img>` and `<figure>` tags in showcase pages use `loading=lazy` — these images are below the fold on the gallery page |
+
+## What to redact
+
+- Real email addresses
+- API keys, OAuth tokens, anything starting with `sk-`, `ghp_`, `xox`, `eyJ`
+- Personal phone numbers
+- Conversation partners' faces or full names (unless they've signed off)
+- File paths that include other people's home directories
+
+## What to keep
+
+- Model names ("llama3.1:8b", "qwen2.5:14b") — they're informative
+- Timestamps — proves the screenshot is recent
+- Dollar amounts on the leaderboard — the whole point
+- Emoji reactions, your own first name, your own avatar
+
+## Placeholder PNGs
+
+This directory ships with no images on the initial PR. The Showcase pages reference image paths that don't exist yet — MkDocs will render a broken-image placeholder, and the figcaption still conveys what should be there. Real screenshots arrive in follow-up PRs as Showcase entries are populated with each contributor's actual setup.
+
+If you're contributing the first real entry, drop your PNG at `docs/assets/showcase/<your-slug>.png` in the same PR that adds your markdown page. The image filename must match the slug used in the showcase page's `<img>` reference.
+
+## Regenerating screenshots in bulk
+
+A future enhancement (tracked as PR #3 in the showcase-tier roadmap) will add `scripts/showcase/regen_screenshots.py` — a Playwright-driven pipeline that boots a demo `jarvis serve` against a sealed config and captures fresh screenshots for every showcase entry on each release tag. Until that lands, screenshots are contributed manually by each Showcase author.
@@ -4,12 +4,25 @@ OpenJarvis provides Docker images for both CPU-only and GPU-accelerated deployme

 ## Quick Start

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

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

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

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

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

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

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

 ## Installing the Service

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

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

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

 ```bash
@@ -0,0 +1,711 @@
+# Spec B — Apple Silicon enablement for Pearl mining
+
+| | |
+|---|---|
+| **Date** | 2026-05-05 |
+| **Status** | Design — Phase 0 investigation complete; v1 scope reduced (see §1.5) |
+| **Owner** | OpenJarvis team (parallel-agent friendly) |
+| **Companion spec** | [Spec A — vLLM-Pearl mining integration (v1)](2026-05-05-vllm-pearl-mining-integration-design.md) |
+| **Repos referenced** | `OpenJarvis`, `pearl-research-labs/pearl`, possibly upstream `ml-explore/mlx`, `ggerganov/llama.cpp` |
+
+> **For agents picking this up cold:** read §1 ("Cold-start brief") first, then **§1.5 ("Phase 0 findings")** which substantially simplifies v1 scope. The original Phase 1–4 GPU-kernel plan in §5–§8 is preserved as the v2/v3 path; v1 ships using upstream Pearl's PyTorch reference and pure-Rust miner.
+
+## 1. Cold-start brief
+
+**One-paragraph problem statement.** OpenJarvis is adding a `mining` subsystem (Spec A) that lets users mine the Pearl PoUW blockchain through their local LLM inference. Pearl's reference miner is CUDA-only and bound to NVIDIA Hopper (`sm_90a`, H100/H200) — most OpenJarvis users on Apple Silicon are locked out at the protocol level. **This spec is the plan to unblock them.** The OJ-side integration work is small (a new `MiningProvider` implementation that drops into the existing `MinerRegistry` from Spec A); the substantial work is a Metal port of Pearl's `NoisyGEMM` kernel and a matching plugin into an Apple-native inference backend (MLX or llama.cpp Metal). The Pearl validation path is plonky2-STARK-based and **already hardware-neutral** — see §3 for the evidence — so a correct Metal implementation produces blocks Pearl validators accept without any consensus changes.
+
+**Three things to know before doing any work.**
+
+1. The Pearl validator (`pearl/zk-pow/src/api/verify.rs::verify_block`) operates on a STARK proof and references no hardware. **The protocol does not care what GPU produced the work** as long as the math is correct and the proof verifies. CUDA-only is a performance choice, not a consensus choice.
+2. Pearl's CUDA kernel (`pearl/miner/pearl-gemm/csrc/gemm/`) uses Hopper-only primitives (TMA, WGMMA, thread-block clusters, CUTLASS 3.x). A Metal port is **not a translation** — it's a from-scratch reimplementation against a different programming model. Plan effort accordingly.
+3. The OJ integration boundary is the `MiningProvider` ABC defined in Spec A §4.4. **Do not modify Spec A.** Add a new provider file (`mining/mlx_pearl.py` or `mining/llamacpp_pearl_metal.py`), implement the ABC, register via `MinerRegistry`, ship a new optional extra. Everything else in Spec A — sidecar shape, config schema, telemetry adapter contract, v2 fee/pool seams — applies unchanged.
+
+## 1.5. Phase 0 findings — significant scope simplification (2026-05-05)
+
+Phase 0 investigation produced four findings that reshape this spec. **The original §5–§8 plan (Metal NoisyGEMM kernel + custom MLX/llama.cpp plugin) is preserved as v2/v3, but is no longer required for v1.**
+
+### 1.5.1 The validator is hardware-neutral (confirmed)
+
+`zk-pow/src/api/verify.rs::verify_block` and `verify_plain_proof` are pure Rust + plonky2; no CUDA, no GPU paths, no hardware introspection. §3.1's claim is **verified by direct code reading** (see file paths in §11). The protocol accepts blocks from any implementation that produces correct math.
+
+### 1.5.2 A complete hardware-neutral miner already exists upstream
+
+`pearl/zk-pow/src/ffi/mine.rs::mine()` is a pure-Rust mining function:
+
+- Generates random `i8` matrices `A` (m×k) and `B` (k×n) with values in `[-64, 64]`
+- Computes blake3-derived noise via `circuit/pearl_noise.rs::compute_noise_for_indices`
+- Performs the noised dot products in tile patterns (`PeriodicPattern.rows_pattern × cols_pattern`)
+- Hashes the jackpot tile and checks the difficulty target
+- Returns a `PlainProof` that `verify_plain_proof` accepts
+
+It is exposed to Python via `py-pearl-mining` (`pearl_mining.mine`). Dependencies: pure Rust (`zk-pow`, `pearl-blake3`, `blake3`, `rayon`, `pyo3`, `tikv-jemallocator`). **No CUDA, no platform-specific code in the Cargo dependency tree.**
+
+### 1.5.3 A PyTorch reference of the *production* NoisyGEMM also exists upstream
+
+`pearl/miner/miner-base/src/miner_base/noisy_gemm.py::NoisyGemm` is a complete PyTorch reference of the same NoisyGEMM that vllm-miner accelerates with the H100 CUDA kernel:
+
+- `noise_A`, `noise_B`, `gemm`, `noisy_gemm` methods replicating the kernel's math in `torch.matmul` calls
+- The denoising path produces **bit-exact results** versus a vanilla `torch.matmul(A.int32, B.int32)` — verified by the `assert torch.equal(result, expected)` test at `miner/miner-base/tests/test_noisy_gemm.py:92`. The "fp16 tolerance" budget I assumed in the original §5.2 is unnecessary for the int7×int7→int32 protocol path
+- Dependencies: `torch==2.11.0`, `blake3`, `numpy`, `pearl-gateway`, `py-pearl-mining` — all install on macOS arm64
+
+### 1.5.4 Empirical confirmation (2026-05-05, on this hardware)
+
+`py-pearl-mining` was built from the upstream source on the spec author's M2 Max. The build produced `py_pearl_mining-0.1.0-cp312-abi3-macosx_11_0_arm64.whl` in 56 seconds. End-to-end mining cycle:
+
+```
+running mine(m=256, n=128, k=1024, rank=32) on Apple Silicon CPU…
+  mine() returned a proof in 0.078s
+  verify_plain_proof: ok=True, msg='Mining solution verified successfully' (0.3 ms)
+END-TO-END MINING ON APPLE SILICON SUCCEEDED
+```
+
+The test difficulty here is `nbits=0x1D2FFFFF` (the test fixture from `py-pearl-mining/tests/test_python_api.py`), much lower than mainnet difficulty — so 78 ms is **per-share at the test difficulty**, not real expected wall-clock per share at the network's current difficulty. But the *correctness* of the path is proven.
+
+### 1.5.5 Reframed v1 — what to build, what to defer
+
+| Layer | Original plan (§5–§8) | New v1 plan |
+|---|---|---|
+| Reference oracle (Phase 0-B) | Build from scratch in PyTorch, validate against H100 CUDA | **Already exists upstream** — `miner-base.noisy_gemm` + `pearl_mining.mine`. OJ ships a thin wrapper, no reimplementation. |
+| Inference-backend plugin (Phase 2) | Custom MLX or llama.cpp Metal plugin doing NoisyGEMM | **Deferred to v2.** v1 is **decoupled mining** — mining runs as a separate process via the upstream Rust miner; user's existing inference (Ollama, MLX, llama.cpp) is unaffected. |
+| Metal NoisyGEMM kernel (Phase 1) | Months of GPU-kernel engineering | **Deferred to v3** as a perf optimization once v1 ships and demand is proven. Original §6.1 content preserved as the v3 plan. |
+| OJ provider integration (Phase 3) | New `MiningProvider` impl | **v1 ships this** — see §13. `MiningProvider` ABC from Spec A unchanged. |
+| Bringup + verification (Phase 4) | Hardware matrix + testnet | **v1 ships this** — see §14. Same hardware matrix, simpler scope. |
+| Pearl coordination (Phase 0-A) | Confirm upstream-vs-fork posture | Still needed (see §12) — but the bar is lower since v1 doesn't require any code from us in Pearl's tree. |
+
+### 1.5.6 Honest performance expectations for v1
+
+This is **not** competitive mining. The point of vllm-miner is that it amortizes mining work over LLM inference matmuls (the matmul you're already doing for inference *is* the mining work). v1 here decouples them: your CPU does mining, your GPU does inference. The hashrate will be low. **But it works today, and it ships with a credible upgrade path.** Document this transparently in `mine doctor` and the user guide.
+
+The v2 (PyTorch-MPS NoisyGEMM coupled with MLX/llama.cpp inference) and v3 (native Metal kernel) work paths in §5–§8 remain the route to competitive Apple Silicon mining. They're explicitly not blocking v1.
+
+## 2. Why this is its own spec
+
+Spec A's scope is the v1 integration that ships today on the only working configuration (vLLM + sm90). Apple Silicon enablement is a separate, parallelizable workstream because:
+
+- **Different ownership boundary.** Spec A is Python integration of an existing Pearl Docker image. Spec B is GPU-kernel engineering with potential upstream contribution to Pearl. These need different reviewers, different CI surfaces (no H100 needed, but Apple Silicon required), and different release cadence.
+- **Different timeline.** Spec A is weeks. Spec B is plausibly months for the kernel work alone.
+- **Different blast radius.** Spec A ships zero risk to non-mining users; even mining users who edit the wrong config get a clear error. Spec B carries protocol-correctness risk — a bug in NoisyGEMM produces invalid blocks that get rejected by validators.
+- **Parallel-agent ergonomics.** The user has explicitly asked for this spec to be picked up by a separate agent in parallel. Self-containment is a design goal.
+
+## 3. Evidence: Apple Silicon support is possible
+
+### 3.1 The validator is hardware-neutral
+
+`pearl/zk-pow/src/api/verify.rs::verify_block`:
+
+```rust
+pub fn verify_block(public_params: &PublicProofParams, proof: &ZKProof, cache: &mut CircuitCache) -> Result<()> {
+    let (params, pis) = prepare_verification(public_params, proof, None)?;
+    PearlRecursion::compile_circuits(params, cache, false)?;
+    verify_with_cache(params, cache, &pis, proof)
+}
+```
+
+Verification is `PearlRecursion::verify(params, cache, pis, &proof.plonky2_proof)` — a recursive plonky2 STARK check. No GPU code path, no CUDA dependency. Validator nodes run pure Rust.
+
+The mining work consists of three things, all of which are mathematical specifications — not implementation specifications:
+
+1. A NoisyGEMM result whose noise pattern is derived from blake3 of a per-block key
+2. A blake3 commitment hash over the noised matmul that meets a difficulty target
+3. A plonky2 STARK proof that ties the result to the commitment
+
+Any implementation that produces matching outputs is acceptable to the network. **This is the design intent of PoUW** — the work has to be replayable and verifiable, but not hardware-bound.
+
+### 3.2 The Pearl team explicitly anticipates non-CUDA plugins
+
+From `pearl/miner/README.md`:
+
+> "Currently only mining via vLLM is supported, in the future we hope to supply plugins for other LLM inference libraries, like SGLang, TensorRT-LLM, Ollama, ..."
+
+Apple is not in their list, but the framing — "supply plugins for other LLM inference libraries" — implies the boundary is at the inference backend, not at the consensus protocol. Confirms the architectural read.
+
+### 3.3 Reference implementation exists in py-pearl-mining
+
+`pearl/py-pearl-mining/` is a PyO3 crate exposing Pearl mining primitives in Python. **Read it before designing the Metal port** — it likely contains the protocol-relevant constants in a hardware-neutral form, suitable as a reference oracle for Phase 0 testing (§5).
+
+## 4. Scope
+
+### 4.1 In scope
+
+- **Phase 0** (§5): protocol-acceptance verification + Pearl-team coordination + Python reference oracle
+- **Phase 1** (§6.1): Metal NoisyGEMM kernel — the substantive engineering
+- **Phase 2** (§6.2): inference-backend plugin — MLX or llama.cpp Metal
+- **Phase 3** (§7): OJ provider integration — new `MiningProvider` impl, new optional extra, registry hookup
+- **Phase 4** (§8): verification matrix across Apple Silicon variants and bringup on Pearl testnet
+- Documentation deliverables and the upstream-contribution path
+
+### 4.2 Out of scope
+
+- Pool support and the 20% OJ fee (Spec A §8.5; that lives in a future v2 pool spec)
+- Custody, signing, or routing Pearl funds (Spec A anti-goal; same here)
+- AMD ROCm enablement (separate spec, parallel structure to this one)
+- Intel Arc / Mac Intel / older CUDA enablement (separate specs)
+- Modifying anything in Spec A. **Spec B is purely additive.**
+- Pearl protocol changes (none required; see §3.1)
+
+### 4.3 Explicit non-goal: economic competitiveness
+
+This spec does not promise that Apple Silicon mining will be **profitable**. The performance gap to a tuned H100 kernel is likely large (§6.1.5 discusses why). What this spec *does* promise: a correct, working Apple Silicon path that's enabled the day the kernel ships, with a transparent doctor surface that tells Mac users honestly what their hashrate looks like. Whether it's worth the electricity is a user decision.
+
+## 5. Phase 0 — investigation, coordination, reference oracle
+
+The phase that costs the least and prevents the most rework. Three workstreams in parallel.
+
+### 5.1 Workstream P0-A: Pearl-side coordination
+
+**Goal:** Confirm protocol acceptance in writing from Pearl maintainers; align on whether OJ contributes upstream or ships independently.
+
+**Steps:**
+
+1. Open a GitHub Discussion on `pearl-research-labs/pearl`: "Apple Silicon / Metal NoisyGEMM enablement — coordination". Reference Spec B URL.
+2. Get explicit confirmation from a Pearl maintainer that:
+   - Validator path is hardware-neutral as believed (§3.1).
+   - There is no Pearl-internal Metal port already in flight that would conflict.
+   - LICENSE compatibility allows OJ-authored kernel code to be either contributed upstream (preferred) or distributed alongside OJ.
+3. Discuss the upstream-vs-fork question. Strong default: **contribute upstream into a new `pearl/miner/pearl-gemm-metal/` crate**, paralleling `pearl-gemm/`, so Pearl owns the kernel long-term and we benefit from their CI and review. Fork only if upstream contribution is blocked.
+
+**Exit criteria:**
+
+- [ ] Written confirmation of protocol acceptance
+- [ ] Agreement on contribution model (upstream / coordinated fork / independent)
+- [ ] No duplicate-effort risk
+
+### 5.2 Workstream P0-B: build a reference oracle
+
+**Goal:** A pure-Python (or pure-Rust) implementation of NoisyGEMM that produces bit-exact-or-fp16-tolerance-bounded outputs versus Pearl's CUDA reference. **Used as the test oracle for Phase 1** — without it, you can't verify the Metal kernel's correctness against a portable baseline.
+
+**Steps:**
+
+1. Read `pearl/miner/pearl-gemm/csrc/gemm/` end-to-end. Catalog the protocol-relevant constants in `pearl_gemm_constants.hpp`:
+   - `kAxEBLScaleFactor = 1 << 14`
+   - `kEARxBpEBScaleFactor = 1 << 12`
+   - `kIntToFp16ScaleFactor = 1 << 12`
+   - `kEBRScaleFactorDenoise`, `kEALScaleFactorDenoise`
+2. Read `pearl/py-pearl-mining/` to see what's already exposed in Python. If a reference impl already lives there, **use it**; do not duplicate.
+3. If gaps exist, build them in PyTorch (CPU). Mirror the structure of the CUDA kernels:
+   - `noise_generation.cu` → `noise_generation.py` — derive `EAL`, `EAR`, `EBL`, `EBR` from blake3-of-key + seed
+   - `pearl_gemm` (matmul + noise) → `pearl_gemm.py` — compute `Y_noisy = (A + EAL·EAR) × (B + EBL·EBR)` with the documented scaling
+   - `inner_hash_kernel.cu` → `inner_hash.py` — blake3 commitment over the noised matmul
+   - `denoise_converter.cu` → `denoise.py` — recover `Y_clean = A·B` from `Y_noisy` and the noise components
+   - `pow_utils.hpp` → `pow_check.py` — difficulty target check
+4. Cross-check: run a corpus of 100+ inputs through the Pearl CUDA reference (on an H100 dev box; see §5.4) and through the Python reference. Assert outputs match within the documented tolerance — most likely **bit-exact for int paths and fp16-tolerance for the denoised result**.
+
+**Exit criteria:**
+
+- [ ] `tools/pearl-reference-oracle/` (in OJ repo, or separate repo) builds and tests pass
+- [ ] Parity confirmed against Pearl CUDA on ≥100 input sets
+- [ ] Constants table documented in this spec (replace the bullet list above with the verified values)
+
+### 5.3 Workstream P0-C: Apple-side viability
+
+**Goal:** Decide between MLX and llama.cpp Metal as the integration host before designing the kernel.
+
+**Decision criteria:**
+
+| Factor | MLX (`ml-explore/mlx`, `mlx-lm`) | llama.cpp Metal (`ggerganov/llama.cpp`) |
+|---|---|---|
+| Op-replacement hooks | Less mature; would likely require monkey-patching `mlx.nn.Linear` or upstream PR adding plugin hooks | More mature; `ggml` op tree is open and Metal backend has clear extension points (`ggml-metal.metal`) |
+| Apple-native quantization story | Excellent (4-bit, 8-bit native ops) | Good but not as native |
+| Inference-quality fidelity for OJ users today | High — MLX-LM is the de facto Mac LLM stack | High — also widely used |
+| Upstream-contribution complexity | Higher (smaller team, less plugin culture) | Lower (large open community, clear contributor flow) |
+| Ecosystem alignment with OJ engine map | OJ's `engine/` doesn't currently have an MLX engine; would need both | OJ already has llama.cpp via `engine/openai_compat_engines.py` |
+
+**Recommendation:** **llama.cpp Metal first**, MLX as a fast-follow. Reasoning: ggml's op tree gives a cleaner extension path for a custom NoisyGEMM op; OJ already has llama.cpp engine wiring; and the upstream-contribution path is more navigable. MLX is a better long-term fit for Apple-native users but is currently a harder integration target.
+
+**Steps:**
+
+1. Spike: implement a no-op "custom op" passthrough in llama.cpp Metal. ~1-2 days work to confirm the integration mechanism is real and the build pipeline cooperates.
+2. Spike: same in MLX. Compare effort.
+3. Pick one. Document the decision in this spec.
+
+**Exit criteria:**
+
+- [ ] Decision made and documented in §6.2
+- [ ] Trivial plugin hook proven on the chosen backend
+
+### 5.4 Hardware required for Phase 0
+
+- One H100/H200 box (cloud rental fine — Lambda, RunPod, Crusoe). Used for: running Pearl's CUDA reference to capture parity test vectors, running the Pearl Docker miner end-to-end as a known-good baseline.
+- Apple Silicon dev machines: M2 Max minimum, M3/M4 Pro+ preferred. M-series Ultra ideal for any perf experiments.
+- Estimated cloud cost for Phase 0: < $200.
+
+## 6. Phases 1 and 2 — kernel and plugin
+
+### 6.1 Phase 1 — Metal NoisyGEMM kernel
+
+**Goal:** A Metal compute-shader implementation of NoisyGEMM that produces outputs matching the Phase 0 reference oracle, performant enough to make Mac mining a real (if low-yield) feature.
+
+#### 6.1.1 Implementation surface
+
+Two viable targets, in order of preference:
+
+**A. Direct Metal Shading Language (MSL) compute kernels.** Maximum control, maximum performance ceiling, maximum effort. The CUDA reference is highly tuned (TMA, WGMMA, multi-stage pipelines); a direct MSL port can lean on Apple's matmul intrinsics where they exist (`simdgroup_matrix` ops on M3+).
+
+**B. Metal Performance Shaders Graph (MPSGraph).** Higher-level than raw MSL; uses Apple's tuned matmul kernels under the hood; limited control over the in-kernel commitment hash. Likely path: do the matmul via MPSGraph, do noise generation + commitment hashing as separate kernels, accept the perf hit from less fusion.
+
+**Recommendation:** Start with B for correctness and shipping speed; profile; move hot paths to A only if economically justified. Apple's matmul intrinsics are fast enough that the perf gap to a fused implementation may be acceptable.
+
+#### 6.1.2 Algorithm structure
+
+Following the Pearl CUDA reference, end-to-end work performed for one mining attempt:
+
+1. **Quantize inputs.** `A: fp16 → int8 + scale_A`, `B: fp16 → int8 + scale_B`. Match Pearl's `quantize_kernel.cu` semantics (per-row or per-channel scales — verify via Phase 0 oracle).
+2. **Generate noise tensors.** From `key_A`, `key_B` (per-block blake3-derived seeds), produce `EAL` (m, R), `EAR` (k, R), `EBL` (k, R), `EBR` (n, R) of int8. Scale factors per `pearl_gemm_constants.hpp`.
+3. **Noisy matmul.** Compute `Y_noisy = (A + EAL · EAR_T) × (B + EBL · EBR_T)`. Output is int32 then converted to fp16.
+4. **Inner-hash commitment.** blake3 over `Y_noisy` (or a row-tile of it) to produce the PoW target candidate. This is the hottest path — the noise + commitment loop runs at every share.
+5. **PoW check.** Compare commitment digest against the difficulty target (`make_pow_target_tensor` semantics from Pearl's Python interface).
+6. **On hit: denoise.** Compute `Y_clean = Y_noisy - (noise contributions)` to feed back into vLLM/MLX as the actual matmul output. Inference cannot be wrong.
+7. **Post-hit: STARK proof generation.** When a share meets the network difficulty target, the miner generates a plonky2 STARK proof tying the noisy matmul + commitment to the block. This proving step is **separate from the Metal kernel** — it runs in pure Rust via Pearl's existing `zk-pow/` and `py-pearl-mining` code paths and should work cross-platform unchanged. Cost: seconds-to-minutes of CPU per block. Confirm cross-platform builds during Phase 0-C and §7.5.
+
+#### 6.1.3 Crate / package layout
+
+Strong preference: **upstream contribution to Pearl** as `pearl/miner/pearl-gemm-metal/` paralleling the existing `pearl-gemm/`:
+
+```
+pearl/miner/pearl-gemm-metal/
+    Cargo.toml          (or pyproject.toml + setup.py — match Pearl conventions)
+    metal/              (.metal MSL source files)
+    src/
+        lib.rs          (or src/pearl_gemm_metal/__init__.py)
+    tests/
+```
+
+If upstream contribution is blocked (Phase 0 outcome), fork with attribution into `OpenJarvis/vendor/pearl-gemm-metal/` and document the divergence policy in this spec.
+
+#### 6.1.4 Testing
+
+- **Parity tests.** Each kernel (noise gen, matmul, inner hash, denoise, PoW check) tested independently against the Phase 0 reference oracle. Bit-exact for int paths; fp16-tolerance bounded for fp paths (specific tolerance: TBD via Phase 0 measurement).
+- **End-to-end correctness.** Full mining attempt produces a candidate proof that the reference Rust prover (`zk-pow/`) accepts.
+- **Hardware fuzz.** Run on M1 Pro, M2 Max, M3 Max, M4 Max, and M-Ultra variants. Catch any silently-wrong hardware behavior (Metal feature variance across generations is real).
+
+#### 6.1.5 Performance expectations
+
+Honest baseline: **expect 0.05–0.2× the share rate of an H100** on a high-end M-Ultra, and proportionally less on smaller chips. Reasons:
+
+- H100 has dedicated FP8/FP16 tensor cores with WGMMA throughput Apple Silicon does not match
+- Pearl's CUDA kernel is heavily fused (matmul + noise + commitment in one kernel via TMA pipelining); a Metal version will likely be less fused
+- 70B model bandwidth requirements stress unified memory
+
+This is fine. Mac mining is a feature for Apple Silicon owners who want to participate, not a competitive yield product. Document it transparently in `mine doctor` and the user guide.
+
+#### 6.1.6 Exit criteria for Phase 1
+
+- [ ] Parity tests pass on M2 Max and M4 Max
+- [ ] End-to-end mining attempt produces a valid proof accepted by `zk-pow::verify_block`
+- [ ] Performance characterized and published (M-series matrix)
+- [ ] Code merged upstream OR forked-with-policy per Phase 0 outcome
+
+### 6.2 Phase 2 — Inference-backend plugin
+
+**Goal:** A llama.cpp Metal (or MLX, per Phase 0-C) plugin that swaps the standard quantized linear op for Phase 1's NoisyGEMM during inference, so a Mac running this plugin produces both correct LLM outputs and valid mining shares.
+
+#### 6.2.1 Path: llama.cpp Metal (assuming Phase 0-C selected this)
+
+- Add a custom `ggml` op `GGML_OP_PEARL_NOISY_GEMM` with a Metal backend implementation that calls Phase 1's kernels.
+- Plugin entry point: a small library that, when loaded, replaces the default linear op in the model graph during loading.
+- Build artifact: `libpearl_metal_plugin.dylib` (or static lib).
+
+#### 6.2.2 Path: MLX (alternate)
+
+- Define `mlx.NoisyLinear` as a subclass of `mlx.nn.Linear` that calls Phase 1's kernels via a custom Metal op binding.
+- Provide a model-loading shim: `from openjarvis.mining import patch_mlx_for_pearl; patch_mlx_for_pearl()` that monkey-patches `mlx.nn.Linear` instances at load time. Less elegant; works.
+
+#### 6.2.3 Inference-quality regression tests
+
+The plugin is correctness-critical: a noised model that doesn't fully denoise produces degraded responses. Test:
+
+- Load a small reference model (e.g., a 1-3B parameter Pearl-blessed model if one exists for testing, otherwise the smallest model the protocol accepts).
+- Run a fixed prompt set through both noised+denoised and standard paths.
+- Assert outputs are bit-exact or within fp16 tolerance.
+- Run OJ's existing eval framework (`src/openjarvis/evals/`) on a small benchmark (e.g., an MMLU subset registered as a Pearl-mining-mode dataset). Assert no degradation > the tolerance budget. Falling back to `lm-eval-harness` is acceptable if OJ's eval surface for Mac is incomplete at the time.
+
+#### 6.2.4 Exit criteria
+
+- [ ] Plugin loads in chosen backend
+- [ ] End-to-end inference produces correct outputs (regression tests pass)
+- [ ] Mining shares are submitted to a Pearl testnet during inference
+- [ ] At least one block found on testnet from a Mac
+
+## 7. Phase 3 — OpenJarvis provider integration
+
+Where the OJ-side work is small. Inherits the entire `MiningProvider` ABC, registry, sidecar, config schema, telemetry adapter, and v2 seams from Spec A unchanged.
+
+### 7.1 New files
+
+```
+src/openjarvis/mining/
+    llamacpp_pearl_metal.py    # OR mlx_pearl.py — depending on Phase 2 path
+                                # @MinerRegistry.register("llamacpp-pearl-metal")
+                                # implements MiningProvider ABC from Spec A §4.4
+```
+
+### 7.2 New optional extra
+
+```toml
+# pyproject.toml
+mining-pearl-metal = [
+    "pearl-metal-plugin>=0.1",   # the Phase 2 plugin, however published
+    # MLX path adds: "mlx>=0.X", "mlx-lm>=0.X"
+    # llama.cpp path adds: "llama-cpp-python>=0.X" with Metal extras
+]
+```
+
+### 7.3 Capability detection
+
+```python
+# src/openjarvis/mining/llamacpp_pearl_metal.py
+class LlamaCppPearlMetalProvider(MiningProvider):
+    provider_id = "llamacpp-pearl-metal"
+
+    @classmethod
+    def detect(cls, hw: HardwareInfo, engine_id: str, model: str) -> MiningCapabilities:
+        if hw.platform != "darwin":
+            return MiningCapabilities(False, reason="Apple Silicon required (platform != darwin)")
+        if hw.gpu is None or hw.gpu.vendor != "apple":
+            return MiningCapabilities(False, reason="Apple Silicon GPU required")
+        if engine_id not in {"llamacpp", "llama-cpp"}:
+            return MiningCapabilities(False, reason=f"engine '{engine_id}' has no Pearl Metal plugin; use llamacpp")
+        if not _pearl_metal_plugin_available():
+            return MiningCapabilities(False, reason="install with `uv sync --extra mining-pearl-metal`")
+        if not _model_has_pearl_variant(model):
+            return MiningCapabilities(False, reason=f"model '{model}' has no Pearl-blessed variant")
+        return MiningCapabilities(True, estimated_hashrate=_estimate_hashrate(hw))
+```
+
+Each branch is exactly the kind of "why can't I mine" message Spec A's `mine doctor` surfaces verbatim.
+
+### 7.4 Lifecycle
+
+Unlike Spec A's vLLM provider which orchestrates a Docker container, the Apple provider runs **two coordinated subprocesses directly on the host**:
+
+1. The inference server (llama.cpp server with the Pearl Metal plugin loaded, or MLX-LM server depending on Phase 0-C path)
+2. `pearl-gateway` as a sibling process — same one that runs inside the Docker container in Spec A, but here it runs natively on the Mac
+
+Lifecycle:
+
+- `start()`: spawn (1) with the Pearl Metal plugin pre-loaded (`DYLD_INSERT_LIBRARIES`-style or `--plugin` flag depending on chosen backend's invocation contract), then spawn (2) pointing at it. Write the same sidecar shape Spec A defines, with `gateway_url` pointing at the native pearl-gateway. Track both PIDs internally.
+- `stop()`: SIGTERM (2) first, then (1), with bounded waits and SIGKILL fallback. Remove sidecar.
+- `is_running()`, `stats()`: identical contract to vLLM provider; `stats()` reads from the native pearl-gateway's `:8339/metrics`.
+
+**No Docker.** Apple Silicon Docker doesn't pass through Metal; running Pearl in a Mac Docker container would defeat the purpose. Document this explicitly in §7 of this spec; do not attempt a Docker path.
+
+### 7.5 Pearl gateway on Mac
+
+The Pearl `pearl-gateway` process is currently only documented as part of the Docker container. For Mac, we need it to run natively. Two options:
+
+1. Build `pearl-gateway` from source via `uv sync --package pearl-gateway` — same workspace package the Docker image uses. Should work cross-platform since it's pure Python plus py-pearl-mining bindings. Verify.
+2. If (1) fails on Apple Silicon, work with Pearl maintainers (Phase 0-A) to port it — a small amount of work compared to the kernel.
+
+**Phase 3 verifies (1).** This is a Phase 0-A coordination point.
+
+### 7.6 Exit criteria
+
+- [ ] `LlamaCppPearlMetalProvider` registered, detection matrix correct on M1/M2/M3/M4
+- [ ] `jarvis mine init` runs to completion on Apple Silicon
+- [ ] `jarvis mine start` launches subprocess + Pearl gateway on Mac
+- [ ] `jarvis mine status` returns valid `MiningStats` from a real Mac mining session
+- [ ] `jarvis mine doctor` produces honest, actionable output for Mac users
+
+## 8. Phase 4 — Verification & bringup
+
+### 8.1 Hardware matrix
+
+| Chip | Test priority | Expected outcome |
+|---|---|---|
+| M1 / M1 Pro / M1 Max | low — generation 1 GPU may have feature gaps | works but slow |
+| M2 / M2 Pro / M2 Max | medium | works |
+| M2 Ultra | medium | best M2-class hashrate |
+| M3 / M3 Pro / M3 Max | high — first gen with `simdgroup_matrix` | works, meaningful share rate |
+| M4 / M4 Pro / M4 Max | high — current flagship | best non-M-Ultra hashrate |
+
+For each chip in the matrix, run:
+
+1. `jarvis mine init` end-to-end
+2. `jarvis mine start` and run for ≥4 h continuous
+3. Capture and publish: shares submitted, shares accepted, block-find time distribution, GPU temp, system load impact on normal use
+4. Run a parallel `lm-eval-harness` on the mining endpoint to assert inference quality is unaffected
+
+### 8.2 Pearl testnet bringup
+
+Before any mainnet recommendation:
+
+- Mine on Pearl testnet for ≥7 continuous days from at least two Apple Silicon variants
+- Find at least one block on testnet from each variant
+- Verify all blocks accepted by `zk-pow::verify_block` on a reference validator node
+- Report results to Pearl maintainers; gate any mainnet announcement on their sign-off
+
+### 8.3 Documentation deliverables
+
+- `docs/user-guide/mining-apple-silicon.md` — user-facing: prerequisites, install flow, doctor reading guide, performance expectations table, links to share-rate calculators
+- `docs/development/mining-providers.md` — generalized "how to add a new provider" guide using this spec as the canonical worked example
+- An update to `docs/user-guide/mining.md` (Spec A) adding Apple Silicon to the supported-platforms list
+
+### 8.4 Exit criteria
+
+- [ ] Hardware matrix covered
+- [ ] Testnet bringup complete
+- [ ] Documentation merged
+- [ ] Pearl maintainer sign-off obtained
+- [ ] OJ release notes call out Apple Silicon mining as supported
+
+## 9. Risks
+
+| ID | Risk | Likelihood | Impact | Mitigation |
+|---|---|---|---|---|
+| R1 | Pearl validator rejects non-CUDA-mined blocks despite hardware-neutral validator code | low (validator code reviewed) | catastrophic (whole spec invalid) | Phase 0-A explicit confirmation; Phase 0-B oracle reduces likelihood of math drift |
+| R2 | Pearl ships their own Metal port, conflicts with OJ's | medium (depends on Pearl roadmap) | high (rework or fork) | Phase 0-A coordination; default to upstream contribution |
+| R3 | Metal NoisyGEMM is so slow that mining is uneconomical even for hobbyists | medium-high | medium (feature ships but unused) | §4.3 names this as a non-goal; transparency in `mine doctor`; consider M-Ultra-only-by-default in v1 of this spec |
+| R4 | NoisyGEMM correctness bug → invalid blocks → wasted user electricity | low if §6.1.4 testing rigorous | high (trust hit) | Strong parity testing against oracle; testnet bringup before mainnet |
+| R5 | Inference-quality regression — denoised path doesn't fully recover model fidelity | medium | high | §6.2.3 regression tests; eval-harness gate before ship |
+| R6 | Pearl protocol changes between Phase 0 and Phase 4 (multi-month) | medium | medium | Pin Phase 0 ref same as Spec A; renegotiate at each Pearl rev |
+| R7 | Apple changes Metal API in macOS update | low-medium | medium | Use stable MSL features; pin Xcode toolchain |
+| R8 | Upstream Pearl PR rejected | low (Pearl wants this) | medium (forced fork) | Phase 0-A negotiates upstream-vs-fork up front |
+| R9 | `pearl-gateway` doesn't build on Apple Silicon (§7.5) | medium (it's Python — should work, but py-pearl-mining has Rust deps) | low (small fix) | Phase 0 verifies builds; Phase 0-A coordination if not |
+
+## 10. Open questions
+
+Phase 0 answered most of these from the upstream code (annotations below). The remaining open items are ones that require either Pearl maintainer input or empirical measurement on real network conditions.
+
+1. **(Open — coordination)** Is there a Pearl-blessed "small" model for testing? The reference miner uses a 70B model — too big for fast iteration. A 7B or 13B variant for development would dramatically speed up v2/v3 plugin work. *Less critical for v1, since v1 is decoupled from inference and runs `mine()` directly without a model.*
+2. **(Answered — N/A for v1)** ~~Documented fp16 tolerance budget for denoised matmul output~~ — `miner-base/tests/test_noisy_gemm.py:92` does `torch.equal(result, expected)`: the int7×int7→int32 path is **bit-exact**, no fp16 tolerance budget is needed. (May reappear in v3 Metal kernel work if int↔fp16 conversions are introduced for perf.)
+3. **(Answered — yes)** Does `py-pearl-mining` already expose enough of NoisyGEMM in Python that Phase 0-B becomes a thin wrapper? **Yes.** `pearl_mining.mine` runs the entire mining algorithm in pure Rust. Additionally, `miner-base.NoisyGemm` provides a PyTorch reference of the production NoisyGEMM. Phase 0-B's "build a reference oracle" deliverable is now a *thin OJ-side wrapper* that calls upstream — see §13 and `tools/pearl-reference-oracle/` (created in this session).
+4. **(Answered — likely yes; empirically verified for `py-pearl-mining`)** Is `pearl-gateway` cross-platform? Its `pyproject.toml` requires Python ≥ 3.10 and depends on `aiohttp`, `bitcoin-utils`, `blake3`, `numpy`, `prometheus-client`, `pybase64`, `pydantic`, `pyyaml`, `torch==2.11.0`, `py-pearl-mining` — all install on macOS arm64. Empirical install of the workspace was not run in this session; **action item for v1 implementation**: `uv sync` the workspace on macOS-15 and capture the build output.
+5. **(Open — coordination)** Does Pearl gate any difficulty / consensus parameters on hardware introspection? Code review found none. Confirm in Phase 0-A discussion.
+6. **(Open — measurement)** Minimum acceptable hashrate floor for `jarvis mine init` on Apple Silicon. The `MiningCapabilities.estimated_hashrate` field in Spec A §4.4 exists for this. v1 will populate from a calibration run during `mine init`. The *floor* is a policy decision, not a technical one — defer to user-research / community feedback once v1 ships.
+7. **(Open — coordination)** Upstream contribution / CLA / LICENSE. Pearl is ISC; OJ is Apache-2.0; both are permissive and combine cleanly. **CLA TBD via Phase 0-A discussion**, but for v1 this is moot — OJ contributes no code into Pearl's tree, only consumes their published Python packages.
+8. **(Answered — yes)** Apple Silicon CI on GitHub Actions: `macos-14` / `macos-15` runners are arm64 and can install `py-pearl-mining` via the wheel build verified in §1.5.4. OJ's CI can run mining unit tests. Mining the *real* network in CI is still out of scope.
+9. **(Answered — `"llamacpp"`)** OJ's llama.cpp engine_id is `"llamacpp"` (single token, no hyphen). Confirmed at `src/openjarvis/engine/openai_compat_engines.py:9` and `src/openjarvis/engine/_discovery.py:18`. Update §7.3 capability detection to use this key. *(For v1 in §13, this only matters if we add an "informational" mining-aware hint to the existing llamacpp engine — v1 does not require any plugin into the engine.)*
+10. **(Open — measurement, but de-risked)** plonky2 STARK proving latency on Apple Silicon CPU. Spec A §1 already notes proving is seconds-to-minutes of CPU per block (cross-platform, runs unchanged). For v1 the hashrate is so low that block-find latency is dominated by the search, not the proof. Empirical measurement still needed for v2/v3.
+11. **(New — v1 specific)** Does `bitcoin-utils>=0.7.0` (a `pearl-gateway` dependency) have C extensions that need Apple-specific build flags? Likely pure-Python; verify during the v1 install workstream.
+12. **(New — v1 specific)** Will `torch==2.11.0` (the version `miner-base` and `pearl-gateway` pin) install cleanly on macOS arm64? PyTorch generally has arm64 macOS wheels. Verify during v1 install.
+
+## 11. Cross-references
+
+- **[Spec A](2026-05-05-vllm-pearl-mining-integration-design.md)** — the v1 integration this extends. Read §4.4 (the `MiningProvider` ABC), §5.3 (sidecar shape), §8.1–8.2 (telemetry adapter contract), §8.5 (v2 fee/pool seams). All apply unchanged.
+- **Pearl coordination thread (P0-A draft):** [`2026-05-05-pearl-coordination-discussion-draft.md`](2026-05-05-pearl-coordination-discussion-draft.md) — content the user posts on `pearl-research-labs/pearl` to confirm protocol acceptance and align on contribution model.
+- **OJ-side Phase 0 deliverables (created this session):**
+  - `tools/pearl-reference-oracle/` — thin Python wrapper around upstream Pearl bindings + smoke test, runnable on Apple Silicon
+- **Pearl repo paths read in Phase 0 (in priority order):**
+  1. `pearl/zk-pow/src/api/verify.rs` — the validator. Pure Rust, no GPU. **Hardware-neutrality verified.**
+  2. `pearl/zk-pow/src/api/proof.rs` — `PublicProofParams`, `ZKProof`, `PrivateProofParams`, `IncompleteBlockHeader`, `MiningConfiguration`, `MMAType`. Defines what the protocol commits to.
+  3. `pearl/zk-pow/src/ffi/mine.rs` — **the entire hardware-neutral mining function**. Pure Rust. Already exposed to Python.
+  4. `pearl/zk-pow/src/circuit/pearl_noise.rs` — noise generation: `compute_noise_for_indices`, `generate_uniform_random_matrix`, `generate_permutation_matrix`. Hardware-neutral.
+  5. `pearl/py-pearl-mining/src/lib.rs` — PyO3 module. Re-exports `mine`, `verify_plain_proof`, `generate_proof`, `verify_proof`, `warmup_prove`. **Builds on macOS arm64, verified §1.5.4.**
+  6. `pearl/py-pearl-mining/Cargo.toml` — pure Rust deps: `pearl-blake3`, `zk-pow`, `blake3`, `rayon`, `pyo3`, `lazy_static`, `tikv-jemallocator`. No CUDA in tree.
+  7. `pearl/py-pearl-mining/tests/test_python_api.py` — the canonical end-to-end test. Use as the OJ smoke-test template.
+  8. `pearl/miner/miner-base/src/miner_base/noisy_gemm.py` — PyTorch reference of the production NoisyGEMM. The "reference oracle" §5.2 wanted to build is here.
+  9. `pearl/miner/miner-base/src/miner_base/noise_generation.py` — PyTorch noise generation matching `pearl_noise.rs`.
+  10. `pearl/miner/miner-base/src/miner_base/inner_hash.py` — PyTorch inner-hash with XOR reduction.
+  11. `pearl/miner/miner-base/tests/test_noisy_gemm.py` — bit-exact denoising verified at line 92.
+  12. `pearl/miner/miner-base/pyproject.toml` — deps (`torch==2.11.0`, `blake3`, `numpy`, `pearl-gateway`, `py-pearl-mining`); **no platform markers** → installs on Apple Silicon.
+  13. `pearl/miner/pearl-gateway/pyproject.toml` — deps (pure Python + py-pearl-mining + torch); **no platform markers**.
+  14. `pearl/miner/vllm-miner/src/vllm_miner/register.py` — vLLM plugin registration via `vllm.general_plugins` entry point. The pattern Phase 2 (v2 plan) would mirror.
+  15. `pearl/miner/pearl-gemm/csrc/gemm/pearl_gemm_constants.hpp` — protocol scale factors. Verified values:
+      - `kAxEBLScaleFactor = 1<<14 = 16384`
+      - `kEARxBpEBScaleFactor = 1<<12 = 4096`
+      - `kIntToFp16ScaleFactor = 1<<12 = 4096`
+      - `kEBRScaleFactorDenoise = -4` (= -kAxEBLScaleFactor / kIntToFp16ScaleFactor)
+      - `kEALScaleFactorDenoise = -1` (= -kEARxBpEBScaleFactor / kIntToFp16ScaleFactor)
+  16. `pearl/miner/pearl-gemm/setup.py:88` — `COMPUTE_CAPABILITY = "arch=compute_90a,code=sm_90a"`. Confirms CUDA kernel is Hopper-only.
+  17. `pearl/Taskfile.yml` — `build:miner` task is gated to `platforms: [linux, windows]`. **The miner Python install path Pearl ships today is Linux/Windows-only**; OJ's v1 path uses the components that *do* install on macOS, sidestepping this gate.
+- **Pearl paper:** [Proof-of-Useful-Work via matrix multiplication (arXiv:2504.09971)](https://arxiv.org/abs/2504.09971) — read for the math formalization. Less critical now that the PyTorch reference exists upstream.
+- **Apple references (still relevant for v2/v3):**
+  - [Metal Shading Language Specification](https://developer.apple.com/metal/Metal-Shading-Language-Specification.pdf)
+  - [MPS / MPSGraph documentation](https://developer.apple.com/documentation/metalperformanceshadersgraph)
+  - [MLX](https://github.com/ml-explore/mlx) — alternative v2 plugin host
+  - [PyTorch MPS backend docs](https://pytorch.org/docs/stable/notes/mps.html) — relevant for v2 (MPS-accelerated decoupled mining)
+
+## 12. Implementation plan
+
+Two implementation plans now live alongside this spec:
+
+- **v1 plan (decoupled CPU mining via upstream Pearl):** Written via `superpowers:writing-plans` after this Phase 0 update. Tracking issue: [`2026-05-05-apple-silicon-pearl-mining-plan-v1.md`](2026-05-05-apple-silicon-pearl-mining-plan-v1.md).
+- **v2 plan (PyTorch-MPS or MLX/llama.cpp coupled mining):** TBD. Written when v1 ships and we have empirical hashrate data justifying the next investment.
+- **v3 plan (native Metal NoisyGEMM kernel):** TBD. Written only if v2 measurements show the additional kernel work is economically justified.
+
+The original §5–§8 content describing Phases 0–4 of the *kernel-first* approach is preserved as the v3 plan's reference. Do not delete it — when the time comes to write the v3 plan, that content is the starting point.
+
+## 13. Apple Silicon v1 — minimal path
+
+This section defines the v1 design that ships in weeks rather than months. v1 is **decoupled mining**: the user's existing inference workflow (Ollama, MLX-LM, llama.cpp, vLLM-on-CPU, anything) is untouched; mining runs as a separate process via the upstream Pearl miner.
+
+### 13.1 Architecture
+
+```
+                      OpenJarvis user (Apple Silicon)
+                     ┌────────────────────────────────┐
+                     │  jarvis mine start              │
+                     │      ↓                          │
+                     │  CpuPearlProvider (this spec)   │
+                     │      ↓ subprocess.Popen         │
+                     │  ┌──────────────────────────┐   │
+                     │  │ pearl-gateway  (Python)  │   │
+                     │  │   ↑ JSON-RPC :8337       │   │
+                     │  │ pearl-mine-loop (Python) │   │   ← uses py-pearl-mining
+                     │  │   wraps pearl_mining.mine│   │     (pure Rust)
+                     │  └──────────────────────────┘   │
+                     │                                  │
+                     │  Inference (untouched)           │
+                     │  ┌──────────────────────────┐   │
+                     │  │ Ollama / MLX / llamacpp  │   │
+                     │  └──────────────────────────┘   │
+                     └────────────────────────────────┘
+                              ↓
+                       pearld (BYO, same as Spec A)
+```
+
+The mining loop wraps `pearl_mining.mine()` in a process that:
+
+1. Polls `pearl-gateway` for current `IncompleteBlockHeader` + `MiningConfiguration`
+2. Calls `pearl_mining.mine(m, n, k, header, config)` to find a `PlainProof`
+3. Submits the proof back to `pearl-gateway`, which generates the ZK proof and forwards to `pearld`
+4. Loops
+
+This is the *same* control flow vllm-miner runs — just without coupling the matmul to vLLM's inference. Pearl's existing `pearl-gateway` already does the orchestration we need; we just need a small mining loop that uses the CPU `mine()` instead of the CUDA path.
+
+### 13.2 Module layout in OJ
+
+```
+src/openjarvis/mining/
+    cpu_pearl.py             # @MinerRegistry.register("cpu-pearl") — v1 provider
+    _pearl_subprocess.py     # PearlSubprocessLauncher — gateway + miner subprocesses
+                             # Reused for future Apple-MPS / Metal providers
+src/openjarvis/cli/
+    # mine_cmd.py is unchanged; cpu-pearl participates via the provider ABC
+
+tests/mining/test_cpu_pearl.py
+tools/pearl-reference-oracle/
+    README.md                # documentation: oracle exists upstream
+    smoke_test.py            # end-to-end mine + verify smoke test (created in this session)
+```
+
+### 13.3 Optional extra
+
+```toml
+mining-pearl-cpu = [
+    "py-pearl-mining>=0.1",     # the wheel built in §1.5.4
+    "miner-base>=0.1",          # PyTorch reference (used for parity testing)
+    "pearl-gateway>=0.1",       # gateway service
+]
+```
+
+When Pearl publishes these as PyPI wheels, the install is `uv sync --extra mining-pearl-cpu`. Until then, the spec for the implementation plan covers the local-build fallback (clone Pearl at the pinned ref, `maturin build` `py-pearl-mining`, `uv pip install` the workspace packages from local paths).
+
+### 13.4 Capability detection
+
+```python
+# src/openjarvis/mining/cpu_pearl.py
+class CpuPearlProvider(MiningProvider):
+    provider_id = "cpu-pearl"
+
+    @classmethod
+    def detect(cls, hw: HardwareInfo, engine_id: str, model: str) -> MiningCapabilities:
+        # cpu-pearl is engine-independent — it doesn't plug into inference
+        if not _pearl_mining_available():
+            return MiningCapabilities(False, reason="install with `uv sync --extra mining-pearl-cpu`")
+        if not _pearl_gateway_available():
+            return MiningCapabilities(False, reason="pearl-gateway package not installed")
+        if hw.platform not in {"darwin", "linux"}:
+            return MiningCapabilities(False, reason=f"platform '{hw.platform}' not yet supported")
+        # Optional: hardware-specific hashrate estimates
+        return MiningCapabilities(True, estimated_hashrate=_estimate_cpu_hashrate(hw))
+```
+
+The `engine_id` parameter is ignored because v1 is decoupled — mining works with **any** OJ engine, including no engine at all. (A future Apple-coupled provider would inspect `engine_id` to require `"llamacpp"` or `"mlx"`.)
+
+### 13.5 Lifecycle (from Spec A's `MiningProvider` ABC)
+
+- `start(config)`: spawn (1) `pearl-gateway` and (2) `pearl-mine-loop` subprocesses. Wait for gateway readiness on `:8339/metrics`. Write the standard sidecar JSON (Spec A §5.3) with `provider="cpu-pearl"`, gateway URL, and PIDs of both subprocesses.
+- `stop()`: SIGTERM mining loop, then gateway. Bounded waits, SIGKILL fallback.
+- `is_running()`: check sidecar + both PIDs.
+- `stats()`: read from `pearl-gateway`'s `:8339/metrics` exactly as Spec A §8.1 specifies. **Same metrics adapter contract.** No code changes in OJ's gateway-metrics adapter.
+
+### 13.6 Configuration
+
+Inherits Spec A's `[mining]` config schema unchanged. v1 uses:
+
+```toml
+[mining]
+provider           = "cpu-pearl"     # NEW: was "vllm-pearl" in Spec A
+wallet_address     = "prl1q..."
+submit_target      = "solo"
+fee_bps            = 0
+fee_payout_address = ""
+
+[mining.extra]
+gateway_port           = 8337
+metrics_port           = 8339
+pearld_rpc_url         = "http://localhost:44107"
+pearld_rpc_user        = "rpcuser"
+pearld_rpc_password_env = "PEARLD_RPC_PASSWORD"
+# v1-specific: matmul shape for the search loop
+m = 256
+n = 128
+k = 1024
+rank = 32
+```
+
+The `m / n / k / rank` shape can be tuned per Phase 0-A measurement (or per chip). Larger shapes search more space per call but use more memory.
+
+### 13.7 Doctor surface (Apple Silicon)
+
+```
+$ jarvis mine doctor
+Hardware
+  GPU vendor          apple                            ✓
+  Apple chip          M2 Max                           ✓
+  Unified memory      96 GB                            ✓
+Pearl install
+  py-pearl-mining     0.1.0 (cp312-abi3-macos-arm64)   ✓
+  miner-base          0.1.0                            ✓
+  pearl-gateway       0.1.0                            ✓
+Pearl node
+  RPC                 http://localhost:44107           ✓
+  Auth                ok                               ✓
+  Block height        442107 (synced)                  ✓
+Wallet
+  Address format      prl1q...                         ✓
+Provider capability
+  cpu-pearl           SUPPORTED  (est. 0.X share/h on M2 Max)
+Notes
+  - This is decoupled mining: your normal LLM inference is unaffected
+  - Hashrate is far below H100 mining; see docs/user-guide/mining-apple-silicon.md
+  - Metal-accelerated mining: planned for v2; not available yet
+Session
+  Sidecar             absent (not running)
+```
+
+Each row maps to a check function in `mining/_discovery.py`. The "est. share/h" line is populated from a one-time calibration during `mine init` — runs `pearl_mining.mine` in a 30-second loop and extrapolates.
+
+### 13.8 v1 anti-goals
+
+- **No coupling to inference.** The user's MLX-LM / Ollama / llama.cpp inference is untouched. v1 does not introduce a custom matmul. The "use AI = mine" narrative is **explicitly deferred to v2**.
+- **No Metal kernel.** All math is in upstream Rust + PyTorch + Python. Zero MSL written.
+- **No Pearl tree changes.** We consume their published packages; we contribute zero code into Pearl's repo for v1. (Phase 0-A discussion still happens — but it's lower-stakes since we're a downstream consumer in v1, not a contributor.)
+- **No upstream PRs blocking v1 ship.** v1 ships against the Pearl ref pinned in `mining/_constants.py` (Spec A §6) regardless of whether any of our coordination questions are answered.
+
+### 13.9 v1 exit criteria
+
+- [ ] `mining-pearl-cpu` extra installs cleanly on macOS arm64 (M1, M2, M3, M4 — at minimum the chip the spec author owns)
+- [ ] `jarvis mine init` completes successfully on macOS arm64
+- [ ] `jarvis mine start` launches gateway + miner subprocesses; sidecar valid; `mine status` reports live data
+- [ ] `mine doctor` produces honest, actionable output for Mac users
+- [ ] At least one block found on Pearl testnet from at least one Apple Silicon variant
+- [ ] User-facing doc `docs/user-guide/mining-apple-silicon.md` ships, including the honest hashrate caveat
+
+### 13.10 Out of v1, into v2/v3
+
+- **v2 (months):** Re-route `noisy_gemm` math to PyTorch-MPS for Apple Silicon GPU acceleration; integrate as a plugin into MLX-LM or `llama-cpp-python` so inference matmuls produce mining work (preserving the "use AI = mine" narrative). The original §5–§8 plan applies, swapped to use PyTorch MPS instead of raw MSL.
+- **v3 (months — optional, only if v2 perf is insufficient):** Native Metal Shading Language NoisyGEMM kernel as an upstream Pearl contribution. The original §5–§8 plan applies as written.
+
+## 14. Phase 0 deliverables status (this session, 2026-05-05)
+
+Tracking what was actually produced, against the §5 Phase 0 plan and the §1.5 reframing.
+
+| Workstream | Original plan | Status | Deliverable |
+|---|---|---|---|
+| P0-A | Open Pearl GitHub Discussion, get protocol-acceptance confirmation | Draft written; user posts | `docs/design/2026-05-05-pearl-coordination-discussion-draft.md` |
+| P0-B | Build reference oracle from scratch in PyTorch, validate against H100 CUDA | **Reference oracle exists upstream.** Built thin OJ-side wrapper + verified empirically that `pearl_mining.mine` runs on Apple Silicon (78 ms / proof at test difficulty) | `tools/pearl-reference-oracle/` |
+| P0-C | Decide MLX vs llama.cpp Metal | **Deferred to v2.** v1 doesn't need either. | — |
+| Spec update | Capture findings | Done | This document, §1.5, §10–§14 |
+| v1 implementation plan | Plan written via `superpowers:writing-plans` after Phase 0 | Pending | `2026-05-05-apple-silicon-pearl-mining-plan-v1.md` (next deliverable) |
@@ -0,0 +1,91 @@
+# Pearl coordination thread — draft
+
+**For:** Posting on `pearl-research-labs/pearl` GitHub Discussions (Category: General / Q&A).
+**By:** OpenJarvis team (Stanford Hazy Research); contact: [user fills in].
+**Status:** Draft — review and edit before posting.
+
+---
+
+## Suggested title
+
+> Apple Silicon support for Pearl mining — coordination & confirmation
+
+## Suggested body
+
+Hi Pearl team — we're [OpenJarvis](https://github.com/open-jarvis/OpenJarvis), a local-first personal AI agent framework from Stanford Hazy Research. We're working on a `mining` subsystem that lets OJ users mine Pearl through the agent framework. The first integration is the `vllm-miner`-on-H100/H200 path, which is straightforward. The second is Apple Silicon, where the situation is more interesting and we'd like to confirm a few things before we ship.
+
+We have a v1 architecture that ships **today** using only your published Python packages (`py-pearl-mining`, `miner-base`, `pearl-gateway`) without any new code in your tree, plus an aspirational v2/v3 path that does involve potentially upstream contributions. Three asks below, plus a heads-up.
+
+### What we built and verified locally (no protocol changes; all upstream code paths)
+
+We read the Pearl source carefully — particularly:
+
+- `zk-pow/src/api/verify.rs` — the validator
+- `zk-pow/src/ffi/mine.rs` — the pure-Rust `mine()` function
+- `zk-pow/src/circuit/pearl_noise.rs` — noise generation
+- `py-pearl-mining/` — the PyO3 bindings exposing the above to Python
+- `miner/miner-base/src/miner_base/noisy_gemm.py` — the PyTorch NoisyGEMM reference
+
+…and then we built `py-pearl-mining` from source on an Apple Silicon M2 Max (macOS 26.4, Python 3.12, Rust 1.94). It produced `py_pearl_mining-0.1.0-cp312-abi3-macosx_11_0_arm64.whl` in ~56 seconds. We installed it and ran the `mine()` + `verify_plain_proof()` cycle from `tests/test_python_api.py`:
+
+```
+running mine(m=256, n=128, k=1024, rank=32) on Apple Silicon CPU…
+  mine() returned a proof in 0.078s
+  verify_plain_proof: ok=True, msg='Mining solution verified successfully'
+```
+
+So our v1 plan is: ship a CPU-mining mode for OJ users on Apple Silicon (and potentially other non-CUDA platforms) that wraps `pearl_mining.mine()` and your `pearl-gateway` as a subprocess. **We're not modifying anything in Pearl's tree for v1.** Just consuming what you've already published.
+
+### Three asks
+
+**1. Protocol acceptance confirmation.**
+
+Reading the validator path, we believe `verify_block` and `verify_plain_proof` accept any `PlainProof` produced by a correct implementation, regardless of which hardware produced it. The plonky2 STARK and the difficulty check don't reference hardware.
+
+**Could you confirm in writing that blocks mined via the pure-Rust `mine()` path (from a non-CUDA host like Apple Silicon) will be accepted by Pearl validators on testnet and mainnet?** We don't expect surprises here, but it's load-bearing for our spec and we want to record your sign-off before we ship.
+
+**2. Heads-up: your `Taskfile.yml` restricts `build:miner` to `[linux, windows]`.**
+
+That makes total sense for the GPU miner (CUDA + vLLM is Linux-only). But the `py-pearl-mining` and `miner-base` packages don't actually need that restriction — they install fine on macOS. We're working around the gate by installing the individual packages directly. Two questions:
+
+   - Is the `[linux, windows]` restriction load-bearing in some way we don't see (e.g., do you intend `py-pearl-mining` to remain a CUDA-bound dependency long-term)?
+   - Would you be open to a small PR that splits `build:miner-cpu` (cross-platform) from `build:miner-gpu` (Linux + CUDA)? It would help downstream consumers like us — and any hobbyist who wants to experiment with `pearl_mining.mine()` on whatever hardware they own.
+
+**3. PyPI publication of `py-pearl-mining` / `miner-base` / `pearl-gateway`.**
+
+Do you have a roadmap for publishing these as PyPI wheels (`pip install py-pearl-mining` etc.)? Today we'd vendor a pinned commit and `maturin build` locally, which works but is brittle. If a 2026 PyPI publication is plausible, we'd defer the local-build code path; if it's not on the roadmap, we'll plan for the long-term local-build path.
+
+### Aspirational (v2 / v3) — context only, no asks yet
+
+Once v1 ships, we'd like to explore Apple-native acceleration:
+
+- **v2:** Use PyTorch MPS to GPU-accelerate `miner-base.NoisyGemm` on Apple Silicon. Could potentially become a plugin into `mlx-lm` or `llama-cpp-python` so a Mac user's *inference* matmuls do mining work — same "useful work" framing as your vllm-miner. We don't need anything from Pearl for this; we'd build it on top of your existing PyTorch reference.
+- **v3 (only if v2 isn't enough):** A native Metal Shading Language port of NoisyGEMM, paralleling `pearl-gemm/`. That would be a real upstream contribution candidate (`pearl/miner/pearl-gemm-metal/`), and we'd want to coordinate with you before starting kernel work to avoid duplicate effort.
+
+If you're already building Apple Silicon support internally (or have someone planning it), please tell us — we'd rather coordinate than duplicate.
+
+### Logistics
+
+- License compatibility: Pearl is ISC; OpenJarvis is Apache-2.0. We don't see any conflict for either consumption (v1) or contribution (v3), but please flag if you do.
+- CLA: do you require one for upstream contributions? Not blocking v1 — just want to know for v3.
+- Preferred coordination channel: this Discussion thread, a Discord, an email? We're happy to use whatever works for you.
+
+Thanks for building this — Proof-of-Useful-Work via matmul is genuinely interesting and we're excited to bring more (slower!) hardware to the network.
+
+— [user name], on behalf of OpenJarvis
+
+---
+
+## Notes for the user before posting
+
+- Replace `[user fills in]` with your contact info, `[user name]` with your name.
+- The architecture/perf claims are all backed by code + an actual local build; you can stand behind them.
+- "Heads-up" framing on the `Taskfile.yml` is intentional — we're not asking them to *change* it, just flagging the friction point in case they want to.
+- Don't post until OJ Spec A is at least branch-pushed (which it is, PR #310) — it gives Pearl a way to see the broader integration we're building.
+- When their reply lands, update Spec B §10 (open questions 1, 5, 7) and §11 (cross-references → coordination thread URL).
+
+## Possible Pearl responses to anticipate
+
+- **Best case:** "Confirmed, looks great, we don't have an Apple Silicon plan, please do it." — proceed with §13.
+- **Middle case:** "Confirmed, but we have a Metal port in flight." — coordinate, share Spec B §6.1, decide upstream-vs-fork. v1 (CPU) is unaffected.
+- **Worst case:** "We'd prefer downstream non-CUDA mining stay disabled for now." — unlikely given their `pearl-gateway` README explicitly anticipates "plugins for other LLM inference libraries", but if it happens, this becomes a much harder problem and we'd need to revisit.
@@ -0,0 +1,560 @@
+# Spec A — vLLM-Pearl mining integration (v1)
+
+| | |
+|---|---|
+| **Date** | 2026-05-05 |
+| **Status** | Design — pending implementation plan |
+| **Owner** | OpenJarvis team |
+| **Companion spec** | [Spec B — Apple Silicon enablement](2026-05-05-apple-silicon-pearl-mining-design.md) (separate effort, runs in parallel) |
+| **Repos referenced** | `OpenJarvis` (this repo), `pearl-research-labs/pearl` |
+
+## 1. Summary
+
+Add a new sibling subsystem `openjarvis.mining` that lets users run [Pearl](https://github.com/pearl-research-labs/pearl) Proof-of-Useful-Work mining as a property of their local LLM inference. v1 ships solo mining for users who already have an H100/H200 and run vLLM — the only configuration Pearl's reference miner currently supports. The architecture leaves three deliberate seams for v2 (pool support + a 20% OJ fee) and is engine-agnostic by construction so Apple Silicon, AMD, Ollama, llama.cpp, and MLX paths plug in via the registry without a rewrite when Pearl ships the matching plugins.
+
+The narrative thesis: Pearl's `vllm-miner` is a vLLM plugin that swaps quantized linear ops with `NoisyGEMM`, a CUDA kernel that produces both the correct matmul output *and* a PoW commitment. Mining IS inference. For an OJ user already serving prompts on a powerful local GPU, this is a way to capture economic value from compute they were going to do anyway — directly aligned with OJ's Intelligence-Per-Watt thesis rather than against it.
+
+## 2. Scope
+
+### In scope (v1)
+- New `openjarvis.mining` subsystem with `MiningProvider` ABC, `MinerRegistry`, `MiningCapabilities` / `MiningConfig` / `MiningStats` dataclasses
+- `vllm-pearl` provider implementation: orchestrate Pearl's published `vllm-miner` Docker container
+- `[mining]` TOML section in OJ config; `MiningConfig` field in `JarvisConfig`
+- New CLI namespace: `jarvis mine init|start|stop|status|doctor|attach|logs`
+- Runtime sidecar at `~/.openjarvis/runtime/mining.json` for engine ↔ mining handoff
+- Hybrid Docker image acquisition: pull-if-published, otherwise build from a pinned Pearl ref
+- On-demand telemetry via Pearl gateway `:8339/metrics`; `mining_session_id` nullable column on telemetry inference rows
+- v2 seams: `submit_target` tagged-union parsing, zero-valued `fee_bps` / `fees_owed` plumbing, reserved `mining/pools/` location
+- Test strategy that doesn't require an H100 in CI
+- Documentation: `docs/user-guide/mining.md`, `docs/development/mining.md`, `CLAUDE.md` paragraph, `REVIEW.md` bullet
+
+### Out of scope (v1) — deferred or owned elsewhere
+- Pool support and the 20% OJ fee mechanism (own spec, v2)
+- Custody, signing, or routing Pearl funds (anti-goal — must remain zero in v1)
+- Apple Silicon, AMD ROCm, sm89 (RTX 4090) NVIDIA, CPU, MLX, Ollama, llama.cpp, SGLang mining paths (Spec B for Apple; remaining hardware/engine paths blocked on Pearl)
+- Wallet generation, Oyster integration, key custody (paste-only address)
+- pearld lifecycle management (BYO node)
+- Background telemetry collection in OJ's gateway daemon (v1.x; the hook point is reserved)
+- Inference-quality drift detection (v1.x at earliest)
+- `mine doctor --fix` automatic remediation (v1.x stub)
+- Multi-GPU / multi-worker / multi-session per host (v2+)
+
+## 3. Load-bearing decisions from brainstorming
+
+These were the forks where the design could have gone several ways. Recorded so future-readers can audit reasoning rather than re-derive it.
+
+| Decision | What we picked | Why |
+|---|---|---|
+| Target audience for v1 | H100/H200 owners running vLLM (Pearl's only working config today) | Anything broader is blocked on Pearl shipping non-CUDA / non-vLLM plugins. Power-user MVP ships in weeks; pool/fee/Apple are separate specs. |
+| Mining model | Co-located: every inference through the Pearl-flavored vLLM is mining work | Matches Pearl's `vllm-miner` plugin design and OJ's Intelligence-Per-Watt thesis. Side-car deferred until Pearl ships plugins for engines users care about for non-mining inference. |
+| Coupling to Pearl miner process | Wrap-and-launch via Docker | Pearl's Docker image (or Dockerfile) is the most stable contract they expose. (1) "BYO miner" is too thin to be a feature; (3) running Pearl's `uv` workspace natively couples us to their build system. |
+| Module placement | Sibling top-level subsystem `mining/` (peer to `engine/`, `agents/`) | Matches OJ's existing module pattern. `MinerRegistry` is a peer registry. Future non-vLLM providers slot in identically. |
+| Engine attachment | Runtime sidecar JSON at `~/.openjarvis/runtime/mining.json` | Existing vLLM engine class stays untouched. Sidecar is the single source of truth tying mining lifecycle to engine resolution. Inspectable via `cat`. |
+| Config shape | Flat top-level `[mining]` TOML section | Only one provider in v1; nested per-engine config can grow later if multi-provider becomes real. |
+| Wallet handling | Paste-only Pearl Taproot address | Keys are sensitive; Pearl's wallet RPC is unstable surface. v1.x can add Oyster integration once the contract stabilizes. |
+| pearld | BYO; user points OJ at their own node | OJ doesn't orchestrate L1 nodes. Doctor surfaces unreachable cleanly. |
+| Telemetry collection | On-demand reads in v1; persistent collector class shipped unwired (`MiningTelemetryCollector`) | Most users won't enable mining; daemon shouldn't grow surface for them. v1.x lights up the hook with zero API churn. |
+| v1 fee/pool seams | Three seams: `submit_target` parsed (one variant works), `fee_bps`/`fees_owed` plumbed at zero, `mining/pools/` reserved | Cheap to leave; painful to retrofit. Does not pre-decide the v2 API. |
+| Custody | **Anti-goal**: zero. v1 must not accept, sign, or route Pearl funds. | Avoids prematurely binding a legal/regulatory posture. v2 revisits as part of pool design. |
+| Apple Silicon support | Not in v1. Designed-for via the `MiningProvider` ABC + `MiningCapabilities.detect()`. Spec B documents the enablement work. | The Pearl `pearl-gemm` kernel is heavily Hopper-bound (`sm_90a`, WGMMA, TMA, cluster mode, CUTLASS 3.x). A Metal port is real GPU-kernel engineering, not a config flag. |
+
+## 4. Architecture & module layout
+
+### 4.1 New module tree
+
+```
+src/openjarvis/mining/
+    __init__.py          # soft-imports providers (try/except ImportError)
+    _stubs.py            # MiningProvider ABC + dataclasses (MiningCapabilities, MiningConfig, MiningStats, SoloTarget, PoolTarget)
+    _discovery.py        # detect_providers(hardware, engine, model) -> list[MiningCapabilities]
+    _docker.py           # PearlDockerLauncher — shared Docker orchestration (image acquisition + container lifecycle)
+    _collector.py        # MiningTelemetryCollector class — defined but UNWIRED in v1; lit up in v1.x
+    _constants.py        # PEARL_REPO, PEARL_PINNED_REF, PEARL_IMAGE_TAG, OJ default tag
+    vllm_pearl.py        # @MinerRegistry.register("vllm-pearl") — only impl in v1
+    pools/               # RESERVED for v2. Empty in v1 except for an __init__.py with a docstring saying so.
+
+src/openjarvis/cli/
+    mine_cmd.py          # jarvis mine init|start|stop|status|doctor|attach|logs
+
+tests/mining/
+    __init__.py
+    conftest.py          # mining-specific fixtures (synthetic HardwareInfo, sample Prometheus output)
+    fixtures/
+        gateway_metrics_sample.txt   # captured Prometheus output from a real Pearl run
+        config_*.toml                # golden TOML files
+    test_stubs.py
+    test_discovery.py
+    test_docker.py
+    test_collector.py
+    test_vllm_pearl.py
+    test_cli.py
+```
+
+### 4.2 Registry additions
+
+`MinerRegistry` added to `src/openjarvis/core/registry.py` as a peer to `EngineRegistry`, `AgentRegistry`, etc. `tests/conftest.py`'s autouse `_clean_registries` fixture is updated to include `MinerRegistry.clear()`.
+
+`mining/vllm_pearl.py` exposes idempotent `ensure_registered()`:
+
+```python
+def ensure_registered() -> None:
+    if not MinerRegistry.contains("vllm-pearl"):
+        MinerRegistry.register_value("vllm-pearl", VllmPearlProvider)
+```
+
+`mining/__init__.py` soft-imports `vllm_pearl` inside `try / except ImportError` and calls `ensure_registered()`. Standard OJ pattern.
+
+### 4.3 Optional-deps extras
+
+```toml
+mining-pearl       = ["docker>=7.0"]   # v1 requires only the Docker SDK
+# mining-pearl-mlx   = [...]            # future, owned by Spec B
+# mining-pearl-rocm  = [...]            # future
+```
+
+### 4.4 The central ABC
+
+```python
+# src/openjarvis/mining/_stubs.py
+from abc import ABC, abstractmethod
+from dataclasses import dataclass, field
+from openjarvis.core.config import HardwareInfo
+
+@dataclass(slots=True)
+class MiningCapabilities:
+    supported: bool
+    reason: str | None = None              # human-readable: "needs sm90", "no Pearl plugin for engine ollama"
+    estimated_hashrate: float | None = None
+
+@dataclass(slots=True)
+class SoloTarget:
+    pearld_rpc_url: str
+
+@dataclass(slots=True)
+class PoolTarget:
+    url: str
+    worker_id: str | None = None
+
+SubmitTarget = SoloTarget | PoolTarget
+
+@dataclass(slots=True)
+class MiningConfig:
+    provider: str                          # MinerRegistry key
+    wallet_address: str
+    submit_target: SubmitTarget            # parsed from TOML "solo" / "pool:<url>"; v1 accepts only SoloTarget at runtime
+    fee_bps: int = 0                       # v1: 0; v2: 2000 (=20%)
+    fee_payout_address: str | None = None  # v1: ignored; v2: OJ's address
+    extra: dict = field(default_factory=dict)
+
+@dataclass(slots=True)
+class MiningStats:
+    provider_id: str
+    shares_submitted: int = 0
+    shares_accepted: int = 0
+    blocks_found: int = 0
+    hashrate: float = 0.0
+    uptime_seconds: float = 0.0
+    last_share_at: float | None = None
+    last_error: str | None = None
+    payout_target: str = "solo"            # v2 reporting; "solo" in v1
+    fees_owed: int = 0                     # v2 accounting hook; 0 in v1
+
+class MiningProvider(ABC):
+    provider_id: str
+
+    @classmethod
+    @abstractmethod
+    def detect(cls, hw: HardwareInfo, engine_id: str, model: str) -> MiningCapabilities: ...
+
+    @abstractmethod
+    async def start(self, config: MiningConfig) -> None: ...
+    @abstractmethod
+    async def stop(self) -> None: ...
+    @abstractmethod
+    def is_running(self) -> bool: ...
+    @abstractmethod
+    def stats(self) -> MiningStats: ...
+```
+
+## 5. Config schema & engine attachment
+
+### 5.1 TOML schema
+
+```toml
+[mining]
+provider                = "vllm-pearl"               # MinerRegistry key
+wallet_address          = "prl1q..."                 # user's Pearl Taproot address (paste-only)
+submit_target           = "solo"                     # v1: "solo" only; "pool:<url>" raises NotImplementedError at start()
+fee_bps                 = 0                          # v1: 0; v2: 2000
+fee_payout_address      = ""                         # v1: ignored; v2: OJ's address
+
+[mining.extra]
+docker_image_tag         = "openjarvis/pearl-miner:<pinned-ref>"
+model                    = "pearl-ai/Llama-3.3-70B-Instruct-pearl"
+gateway_port             = 8337
+gateway_metrics_port     = 8339
+vllm_port                = 8000
+gpu_memory_utilization   = 0.9
+max_model_len            = 8192
+pearld_rpc_url           = "http://localhost:44107"
+pearld_rpc_user          = "rpcuser"
+pearld_rpc_password_env  = "PEARLD_RPC_PASSWORD"     # name of env var, not the secret
+hf_token_env             = "HF_TOKEN"                # name of env var
+```
+
+Secrets: env-var *names*, never literal values. Matches OJ's existing convention for cloud API keys.
+
+### 5.2 JarvisConfig field
+
+`core/config.py` adds:
+
+```python
+@dataclass(slots=True)
+class JarvisConfig:
+    ...
+    mining: MiningConfig | None = None
+```
+
+The TOML loader reads `[mining]`, parses `submit_target` into `SoloTarget | PoolTarget`, validates against the dataclass, surfaces unknown `extra` keys as warnings. Absent section → `mining = None` → zero behavior change.
+
+### 5.3 Runtime sidecar
+
+`~/.openjarvis/runtime/mining.json` (created on `mine start`, removed on `mine stop`):
+
+```json
+{
+  "provider": "vllm-pearl",
+  "vllm_endpoint": "http://127.0.0.1:8000/v1",
+  "model": "pearl-ai/Llama-3.3-70B-Instruct-pearl",
+  "gateway_url": "http://127.0.0.1:8337",
+  "gateway_metrics_url": "http://127.0.0.1:8339",
+  "container_id": "abc123...",
+  "wallet_address": "prl1q...",
+  "started_at": 1714867200
+}
+```
+
+Sidecar deliberately omits all secrets and process IDs. `container_id` is the authoritative handle (Docker is the source of truth for liveness); `wallet_address` is captured for drift-detection (config-vs-runtime).
+
+### 5.4 Engine handoff flow
+
+1. `jarvis mine start` → `MinerRegistry.get("vllm-pearl").start(config)`.
+2. `VllmPearlProvider.start()` calls `_docker.PearlDockerLauncher.start(config)` and writes the sidecar.
+3. `engine/_discovery.py` checks for `mining.json` on every engine lookup. When present, it auto-registers a `vllm` engine instance pointing at `vllm_endpoint`, named `vllm-pearl-mining`, marked default for mining-aware operations.
+4. `jarvis ask` and the SDK route to that endpoint transparently. The user's normal inference is the mining work.
+
+The vLLM engine class itself (`engine/openai_compat_engines.py`) is **not modified**. The change to `engine/_discovery.py` is small and additive: it inspects for `mining.json` and registers a derived `vllm` instance pointing at the mining endpoint when the sidecar is present. Absent sidecar → unchanged discovery behavior.
+
+### 5.5 Manual mode
+
+Power users running their own Pearl container skip `jarvis mine start` and write the sidecar themselves via `jarvis mine attach --vllm-endpoint=... --gateway-url=...`. Decouples lifecycle from wiring.
+
+## 6. CLI surface, lifecycle & daemon integration
+
+### 6.1 Subcommands
+
+| Command | Purpose |
+|---|---|
+| `jarvis mine init` | Interactive: hardware/Docker checks, prompt for wallet + pearld credentials, write `[mining]`, pull/build image. Does NOT start mining. Pre-checks `>=200 GB` free disk. |
+| `jarvis mine start` | Launch container via the registered provider, write sidecar, print endpoint info. Idempotent if running. |
+| `jarvis mine stop` | Stop container, remove sidecar. Idempotent if not running. |
+| `jarvis mine status` | Read sidecar + query gateway `:8339/metrics`. Print `MiningStats`. |
+| `jarvis mine doctor` | Capability matrix; every check ✓/✗ with reason. Works in any state. |
+| `jarvis mine attach` | Manual mode: write sidecar without launching. |
+| `jarvis mine logs [-f]` | Tail container logs through Docker SDK. |
+
+### 6.2 Doctor output (canonical example)
+
+```
+$ jarvis mine doctor
+Hardware
+  GPU vendor          nvidia                           ✓
+  Compute capability  sm_90a                           ✓
+  VRAM                80 GB                            ✓  (need ≥ 70 GB for Pearl 70B)
+Docker
+  Daemon              running 24.0.7                   ✓
+  GPU runtime         nvidia-container-toolkit         ✓
+Disk
+  Free in HF cache    312 GB                           ✓  (need ≥ 200 GB)
+Image
+  openjarvis/pearl-miner:<ref>   present (built 2026-04-30)   ✓
+Pearl node
+  RPC                 http://localhost:44107           ✓
+  Auth                ok                               ✓
+  Block height        442107 (synced)                  ✓
+Wallet
+  Address format      prl1q...                         ✓
+Provider capability
+  vllm-pearl          SUPPORTED
+Session
+  Sidecar             absent (not running)
+  Container           —
+```
+
+Each row maps to one check function in `mining/_discovery.py`. Failures print actionable reasons (e.g. `✗  reason: needs sm90, you have sm89 (RTX 4090)`).
+
+### 6.3 Lifecycle states
+
+```
+NOT_CONFIGURED  →  CONFIGURED  →  STARTING  →  RUNNING  ⇄  STOPPING  →  STOPPED
+                                       ↘
+                                       FAILED
+```
+
+State derivation rules (no separate state file — derived from config + sidecar + container introspection):
+
+- `NOT_CONFIGURED` — no `[mining]` in config
+- `CONFIGURED` — config present, no sidecar
+- `STARTING` — sidecar with `started_at` < ~30 s ago, container exists but gateway not yet healthy
+- `RUNNING` — sidecar present, container running, gateway responding
+- `FAILED` — sidecar present, but container exited or gateway failing > threshold
+- `STOPPING` — `mine stop` invoked, Docker stop in progress
+- `STOPPED` — `mine stop` complete, sidecar removed
+
+### 6.4 Daemon integration: deliberately minimal in v1
+
+- Docker handles container restart via `--restart=unless-stopped`. OJ does not babysit.
+- Existing `com.openjarvis.gateway` daemon is unchanged.
+- v1.x hook: `MiningTelemetryCollector` (already shipped in v1, unwired) can be added to the gateway as a 30-second-tick async task.
+- launchd/systemd installation surface (`jarvis daemon install`) untouched.
+
+### 6.5 Concurrency
+
+POSIX `flock` on `~/.openjarvis/runtime/mining.lock` prevents racing `mine start` invocations.
+
+### 6.6 `jarvis ask` UX hint
+
+When `[mining]` is configured but no sidecar exists, `cli/hints.py` emits one line: `"mining configured but not running — start it with \`jarvis mine start\`"`. One-line UX nudge, no new infrastructure.
+
+## 7. Pearl Docker integration
+
+### 7.1 Realities from inspecting Pearl's repo
+
+- **Build context = entire Pearl monorepo.** Dockerfile copies root `pyproject.toml`/`uv.lock`, `miner/`, `pearl-blake3/`, `py-pearl-mining/`, `zk-pow/`, `plonky2/`. Building requires the full repo.
+- **Pearl publishes no registry image as of writing.** README documents only `docker buildx build -t vllm_miner . -f miner/vllm-miner/Dockerfile`.
+- **Single container, three ports.** `entrypoint.sh` launches `pearl-gateway` in the background, waits on `:8339/metrics`, then `exec`s `vllm serve`. Ports: `8000` (vLLM), `8337` (miner RPC), `8339` (gateway metrics).
+- **Pinned stack inside the image.** CUDA 12.9.1, vLLM 0.20.0+cu129, Python 3.12, `compute_90a/sm_90a`. Set by Pearl, not by us.
+- **First-launch cost.** vLLM pulls the 70 B model from HF on first serve (~140 GB). Build itself is 30–60 min on first init.
+
+### 7.2 Hybrid image acquisition
+
+| Mode | Behavior | When |
+|---|---|---|
+| **Pre-built pull** | OJ `docker pull`s the configured tag if it resolves in a registry | Default once Pearl publishes; users with private registry; CI |
+| **Build-from-pin** | OJ git-clones Pearl at a pinned ref into `~/.openjarvis/cache/pearl/`, then `docker buildx build` | v1 default (Pearl publishes nothing today) |
+| **BYO image** | User sets `mining.extra.docker_image_tag` to an image they built/pulled themselves | Power users, air-gapped envs |
+
+Selection logic in `_docker.PearlDockerLauncher.ensure_image()`:
+1. If `docker_image_tag` resolves locally → use it.
+2. Else `docker pull <tag>` → on success, use it.
+3. Else if `tag == OJ_DEFAULT_TAG`, fall back to clone-and-build from `PEARL_PINNED_REF`.
+4. Else fail with a clear error pointing at `mine doctor`.
+
+### 7.3 Pearl version pinning
+
+`mining/_constants.py`:
+
+```python
+PEARL_REPO       = "https://github.com/pearl-research-labs/pearl.git"
+PEARL_PINNED_REF = "<sha-or-tag>"            # bumped per OJ release after rev-testing
+PEARL_IMAGE_TAG  = f"openjarvis/pearl-miner:{PEARL_PINNED_REF}"
+```
+
+OJ release notes call out the Pearl ref shipped. Bumping the ref is its own PR with a documented Pearl-rev workflow.
+
+### 7.4 Container launch shape
+
+Via `docker>=7.0` SDK in `_docker.PearlDockerLauncher.start()`:
+
+```python
+container = client.containers.run(
+    image=PEARL_IMAGE_TAG,
+    command=[
+        config.extra["model"],
+        "--host", "0.0.0.0",
+        "--port", str(config.extra["vllm_port"]),
+        "--gpu-memory-utilization", str(config.extra["gpu_memory_utilization"]),
+        "--enforce-eager",
+        "--max-model-len", str(config.extra.get("max_model_len", 8192)),
+    ],
+    name="openjarvis-pearl-miner",
+    detach=True,
+    auto_remove=False,
+    restart_policy={"Name": "unless-stopped"},
+    device_requests=[ DeviceRequest(count=-1, capabilities=[["gpu"]]) ],
+    shm_size="8g",
+    network_mode="host",
+    volumes={
+        str(Path.home() / ".cache/huggingface"): {
+            "bind": "/root/.cache/huggingface",
+            "mode": "rw",
+        },
+    },
+    environment={
+        "PEARLD_RPC_URL":         config.extra["pearld_rpc_url"],
+        "PEARLD_RPC_USER":        config.extra["pearld_rpc_user"],
+        "PEARLD_RPC_PASSWORD":    os.environ[config.extra["pearld_rpc_password_env"]],
+        "PEARLD_MINING_ADDRESS":  config.wallet_address,
+        "HF_TOKEN":               os.environ.get(config.extra.get("hf_token_env", "HF_TOKEN"), ""),
+        "MINER_RPC_TRANSPORT":    "tcp",
+    },
+)
+```
+
+### 7.5 Trade-offs called out
+
+- **`network_mode="host"`** because pearld's RPC at `http://localhost:44107` lives on the host. A user-defined Docker network adds setup steps with no real isolation benefit on a single-tenant miner box. Pragmatism > purity. Note: host networking has Linux semantics; macOS/Windows Docker handle it differently. Acceptable for v1 since H100/H200 + nvidia-container-toolkit constrains the deployment to Linux anyway.
+- **`auto_remove=False`** so a crashed container stays around for `jarvis mine logs` post-mortem.
+- **HF cache mounted from host.** 140 GB weight download is one-time, survives container restarts, visible to other tools.
+- **Secrets via env-var names**, never persisted in the container image, the sidecar, or Docker labels.
+
+### 7.6 Wallet handling boundary
+
+OJ never sees Pearl mnemonic seeds, never imports Oyster keys, never signs Pearl transactions. Only Pearl-secret OJ touches is the pearld RPC password (passed through container env, sourced by name from host env). Mining address is public — fine in plaintext config.
+
+### 7.7 Image lifecycle UX
+
+- `jarvis mine init` triggers `ensure_image()`, streams build/pull output through the CLI with a clear time estimate (`"Building Pearl miner image — first run takes ~45 min on a fast machine"`).
+- `jarvis mine doctor` reports `image: present (tag, age, sha)` or `image: missing (run mine init)`.
+- `jarvis mine prune` (v1.x) cleans old `openjarvis/pearl-miner:*` tags. Manual `docker image rm` works in v1.
+
+## 8. Telemetry hooks & v2 fee/pool seams
+
+### 8.1 Telemetry — read surface
+
+Pearl's container exposes `:8339/metrics` (Prometheus exposition format). v1 reads only this endpoint. Deeper RPC introspection via `:8337` deferred to v2.
+
+### 8.2 Adapter and metric mapping
+
+`mining/vllm_pearl.py::_parse_gateway_metrics()` translates Prometheus lines to `MiningStats`. Metric names are TBD on implementation — verified against captured fixture `tests/mining/fixtures/gateway_metrics_sample.txt`. Expected mapping (fallback: zero-fill any missing field, log a one-shot warning):
+
+| `MiningStats` field | Likely Pearl metric (verify on implementation) |
+|---|---|
+| `shares_submitted` | `pearl_gateway_shares_submitted_total` |
+| `shares_accepted` | `pearl_gateway_shares_accepted_total` |
+| `blocks_found` | `pearl_gateway_blocks_found_total` |
+| `hashrate` | derived rate of `shares_submitted_total` |
+| `uptime_seconds` | `process_start_time_seconds` |
+| `last_share_at` | `pearl_gateway_last_share_timestamp` |
+| `last_error` | derived from `pearl_gateway_errors_total` deltas |
+
+### 8.3 Collection cadence
+
+- **v1: on-demand only.** `jarvis mine status` makes one HTTP GET per call (~10 ms). No background polling.
+- **v1.x: `MiningTelemetryCollector` lit up in the gateway daemon.** The class is shipped in v1 but unwired. v1.x adds a periodic asyncio task; same `MiningStats` schema, same gateway endpoint. Zero API churn.
+
+### 8.4 Intelligence-Per-Watt extension
+
+The `telemetry/store.py` schema gains a nullable `mining_session_id` column on inference rows:
+
+- Tagged when an inference goes through the Pearl-mining endpoint; null otherwise.
+- Untagged rows behave exactly as today — zero impact on the non-mining path.
+- `jarvis telemetry stats --mining` (v1.x) joins to the latest `MiningStats` snapshot and reports `tokens / share`, `joules / share`, `est. PRL / kWh`.
+
+v1 ships the column and the no-op join path. v1.x lights up the reporting. This is the metric the IPW thesis genuinely cares about.
+
+### 8.5 v2 fee/pool seams (three concrete, no more)
+
+**1. `submit_target` parsed into a tagged union; only one variant works.** `SoloTarget` accepted at runtime in v1; `PoolTarget` raises `NotImplementedError("pool support is v2 — track openjarvis#XYZ")`. Reachable only by users who edit their config to opt in.
+
+**2. `fee_bps` / `fee_payout_address` plumbed; zero-valued in v1.** `MiningStats.fees_owed = 0` and `MiningStats.payout_target = "solo"` always in v1. Schema is real; values are zero. No migration in v2.
+
+**3. `mining/pools/` module location reserved.** Empty in v1 except for an `__init__.py` whose docstring says the location is reserved for v2 `PoolClient` work. The v1 spec **does not** define a `PoolClient` ABC — predicting the v2 API precisely creates migration debt. The v2 spec writes against an empty slot.
+
+### 8.6 What v1 deliberately does not lock in
+
+- Pool protocol (PPLNS / PPS / SOLO+ / custom)
+- Custody model (escrow / trustless split-coinbase / settlement contract)
+- OJ pool URL, share format, share difficulty
+- KYC / TOS / payout thresholds
+
+### 8.7 Custody anti-goal
+
+v1 must not introduce any code path where OJ accepts custody of, signs, or routes Pearl funds. Closest v1 comes is reading `wallet_address` (public) and passing it through to the container. v2 revisits.
+
+### 8.8 Single-session assumption (called out, not seamed)
+
+v1 assumes one mining session per host (one sidecar). Multi-GPU / multi-worker fanout is v2+. Sidecar would become a list or directory.
+
+## 9. Failure handling & test strategy
+
+### 9.1 Principles
+
+1. **Fail loud, don't auto-heal.** Docker handles container restarts; `mine doctor` surfaces what's wrong. OJ does not retry mining work, restart pearld, or paper over crashes.
+2. **`mine doctor` is the canonical failure surface.** Every failure mode below maps to one or more rows in doctor output.
+3. **Sidecar is authoritative; config is intent.** Drift surfaces as a warning, not a crash.
+
+### 9.2 Failure mode matrix
+
+| Failure | v1 behavior | Surface |
+|---|---|---|
+| Image missing | `mine start` errors with "run `mine init` to build/pull" | `mine doctor: image: missing` |
+| GPU not reachable in container | Docker error with `nvidia-container-toolkit` hint | `mine doctor: docker.gpu_runtime: ✗` |
+| Disk too low | `mine init` pre-checks `shutil.disk_usage`; errors if < 200 GB free | `mine doctor: disk_free: ✗` |
+| vLLM model load fails (HF auth, OOM, model not found) | Container exits; `mine status` reports `FAILED` with `last_error` from `docker logs` tail | `mine status` + `mine logs` |
+| pearl-gateway can't reach pearld | `:8339/metrics` exposes the error; adapter populates `MiningStats.last_error` | `mine status: last_error` |
+| Container crashes mid-run | Docker `--restart=unless-stopped` restarts; `mine status` shows brief `STARTING` → `RUNNING` | self-healing, logged |
+| Stale sidecar (container died, sidecar not cleaned) | `mine start` validates `container_id`; if Docker says it's gone, removes sidecar and proceeds | one-line warning |
+| Concurrent `mine start` | POSIX `flock` on `~/.openjarvis/runtime/mining.lock`; second invocation errors clearly | clear message |
+| Already-running `mine start` | Idempotent: detect via sidecar + container introspection, print status, exit 0 | informational |
+| Wallet/config drift | Sidecar carries wallet from start time; `mine status` cross-checks and warns on mismatch | warning, not auto-restart |
+| User edits `submit_target = "pool:..."` in v1 | `start()` raises `NotImplementedError` with tracking issue link | clear error |
+| Pearl protocol upgrade (block format / metric names change) | Adapter zero-fills with one-shot warning. `mine doctor` does a best-effort check: it reads the `image: openjarvis/pearl-miner:<ref>` Docker label and compares against `PEARL_PINNED_REF` baked into the OJ release; mismatch surfaces a warning. **OJ does not poll Pearl's GitHub at runtime.** | warning + spec'd Pearl-rev workflow |
+| Inference quality regression from NoisyGEMM | **Out of v1 scope to detect.** Documented risk; v1.x may add automated drift detection. | docs only |
+
+### 9.3 Test strategy
+
+Hard constraint: **OJ's CI has no H100, no GPU, no Pearl image, no pearld.** Almost everything must be testable without those.
+
+| Layer | Pattern | Marker | Runs in CI? |
+|---|---|---|---|
+| `MiningCapabilities.detect()` matrix | Pure unit, parametrized over synthetic `HardwareInfo` | unmarked | yes |
+| `MiningConfig` parsing (TOML → dataclass, including `submit_target` tagged-union) | Unit, golden TOML fixtures | unmarked | yes |
+| Docker launch shape | `unittest.mock.patch("docker.from_env")`; assert `containers.run(...)` kwargs | unmarked | yes |
+| Gateway metrics adapter | `tests/mining/fixtures/gateway_metrics_sample.txt`, parse + assert `MiningStats` | unmarked | yes |
+| Sidecar lifecycle (write/read/stale-cleanup, `flock` acquisition) | `tmp_path`, real filesystem, real `flock` | unmarked | yes |
+| CLI smoke | Click `CliRunner`, mocked `MiningProvider` | unmarked | yes |
+| Container start/stop with real Docker daemon | Real Docker, swap Pearl image for tiny stub `alpine`-based image opening the right ports | new `docker` marker | optional in CI |
+| End-to-end mining (real container, real pearld, real shares) | Real H100 + pearld testnet + pinned Pearl image | `live and nvidia and slow` | **no** — manual pre-release smoke |
+
+**New pytest marker.** `docker` registered alongside `live`, `cloud`, `nvidia`, etc. in `pyproject.toml`. CI matrix optionally runs `-m "docker and not live"` on a Docker-enabled runner.
+
+**Conftest hygiene.** `tests/conftest.py`'s autouse fixture clears `MinerRegistry`. `mining/__init__.py`'s `ensure_registered()` survives the autouse clear via `MinerRegistry.contains(...)`.
+
+**Captured Prometheus fixture.** Real metrics output from a Pearl gateway run, committed to the repo. Pins the metric-name assumptions and is the canary if Pearl renames metrics.
+
+### 9.4 What v1 deliberately does not test
+
+- Mining throughput/economics on a real H100 (Pearl's CI tests their kernels)
+- Inference quality drift from NoisyGEMM (out of v1 scope)
+- Pool share submission paths (v2 spec)
+- Apple Silicon paths (Spec B)
+
+## 10. Documentation deliverables (part of this spec)
+
+- `docs/user-guide/mining.md` — user-facing: prerequisites, init flow, doctor output reading guide, `mine status` interpretation, deliberately-unsupported list (Mac, AMD, sm89, non-vLLM engines)
+- `docs/development/mining.md` — for contributors: `MiningProvider` ABC, registry pattern, how to add a new provider (Spec B is the canonical worked example)
+- One paragraph in `CLAUDE.md` under "Architecture" pointing future-Claude at `mining/` as a sibling subsystem with its own optional-deps discipline
+- `REVIEW.md` gets a new bullet under registry compliance specifically calling out `MinerRegistry`
+
+## 11. Open items to resolve at implementation time
+
+1. **Pearl gateway metric names.** Verify the actual exposition labels by capturing `:8339/metrics` from a running Pearl gateway. Update the adapter mapping and commit the fixture.
+2. **`PEARL_PINNED_REF`.** Pick a specific commit/tag at the start of implementation. Document the rev-bump workflow.
+3. **The `pearl-ai/Llama-3.3-70B-Instruct-pearl` HF model.** Confirm it exists and is gated/ungated; document HF auth requirements.
+4. **Pearl Taproot address regex.** Confirm the prefix and length for `mine doctor`'s address-format check.
+5. **Pearl `:8337` miner RPC TCP port behavior.** Confirm `MINER_RPC_TRANSPORT=tcp` works as documented and binds to `0.0.0.0` not just `127.0.0.1` inside the host network namespace.
+6. **OJ default Docker image tag.** Decide whether to publish to GHCR/Docker Hub once we have a build, or leave users on build-from-pin. Likely v1.x.
+7. **Wallet generation hand-off (v1.x).** Decide whether `mine init` shells out to Pearl's `oyster` for users who want guidance, or stays paste-only.
+8. **Telemetry schema migration approach.** Adding the nullable `mining_session_id` column to `telemetry/store.py` is a SQLite schema change. Decide between (a) `ALTER TABLE` on first start with a guarded `PRAGMA user_version` bump, (b) per-query `try/except` on the column, or (c) creating a sidecar table joined on inference id. Confirm what convention OJ already uses for `telemetry/` schema evolution before picking; default lean is (a).
+
+## 12. Cross-references
+
+- **[Spec B — Apple Silicon enablement](2026-05-05-apple-silicon-pearl-mining-design.md)** — separate effort tracking the Pearl-side and OJ-side work to make Apple Silicon a registered `MiningProvider`. Spec A is engine-agnostic by design; Spec B drops in via `MinerRegistry` without modifying anything in this spec.
+- **Pearl repo:** [`pearl-research-labs/pearl`](https://github.com/pearl-research-labs/pearl) — referenced sub-paths: `miner/vllm-miner/`, `miner/pearl-gemm/`, `miner/pearl-gateway/`, `miner/vllm-miner/Dockerfile`, `miner/vllm-miner/entrypoint.sh`.
+- **Pearl paper:** [Proof-of-Useful-Work via matrix multiplication (arXiv:2504.09971)](https://arxiv.org/abs/2504.09971).
+- **OJ contributing guide:** `docs/development/contributing.md` — registry pattern, `_stubs.py` / `_discovery.py` conventions, `ensure_registered()` discipline, optional-deps soft-import pattern. All followed in this spec.
+
+## 13. Implementation plan
+
+The implementation plan for Spec A is a separate document, written via the `superpowers:writing-plans` skill after this design is approved by the user. It will decompose section 4–9 above into ordered, independently-reviewable steps and call out which steps can be parallelized.
@@ -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.
@@ -0,0 +1,289 @@
+# NVIDIA Pearl Mining Validation Runbook
+
+This runbook is the release gate for the v1 `vllm-pearl` provider. Unit tests
+prove OpenJarvis wiring; this validates that a real H100/H200 host can mine
+through Pearl and serve inference through OpenJarvis.
+
+## Required Host
+
+Run this on a Linux machine with:
+
+- NVIDIA H100 or H200 GPU, compute capability 9.0, at least 70 GB VRAM
+- Current NVIDIA driver with CUDA container support
+- Docker 24+ and `nvidia-container-toolkit`
+- At least 200 GB free disk
+- Reachable `pearld` JSON-RPC endpoint
+- Pearl payout address beginning with `prl1q` or `prl1p`
+- Hugging Face access to `pearl-ai/Llama-3.3-70B-Instruct-pearl`
+
+The validated H100 configuration uses `gpu_memory_utilization = 0.96` with
+`max_model_len = 8192`. Lower memory utilization can fail during vLLM startup
+because the Pearl 70B mining model leaves too little KV cache at 8k context.
+
+Do not run this on macOS, Apple Silicon, AMD, RTX 4090, or CPU-only hosts.
+Those are separate providers.
+
+## Wallet Address Setup
+
+Create the wallet from the Pearl repo root:
+
+```bash
+./bin/oyster -u rpcuser -P rpcpass --create
+```
+
+If you choose the optional public-data encryption prompt, Oyster will require
+that public passphrase on startup via `--walletpass`. Keep private and public
+passphrases out of shell history where possible.
+
+Start Oyster:
+
+```bash
+./bin/oyster \
+  -u rpcuser \
+  -P rpcpass \
+  --walletpass '<public-wallet-passphrase-if-configured>' \
+  &
+```
+
+Then generate a mining address through the wallet RPC:
+
+```bash
+./bin/prlctl \
+  --wallet \
+  --skipverify \
+  -u rpcuser \
+  -P rpcpass \
+  -s localhost:44207 \
+  getnewaddress
+```
+
+Notes:
+
+- `--wallet` is required. Without it, `prlctl` talks to `pearld` instead of
+  Oyster and may look for `Pearld/pearld.conf`.
+- Use `-s localhost:44207`, not `-s https://localhost:44207`. `prlctl` expects
+  host and port, not a URL.
+- `--skipverify` is acceptable for this local validation flow unless you have
+  configured the Oyster RPC certificate path.
+- If a mnemonic has been pasted into logs, chat, or a PR, discard that wallet
+  and create a fresh one before mining.
+
+## Environment
+
+```bash
+git checkout feat/mining-spec-a-only
+uv sync --extra dev --extra mining-pearl-vllm
+
+export PEARLD_RPC_PASSWORD='<pearld-rpc-password>'
+export HF_TOKEN='<huggingface-token>'
+```
+
+Confirm host prerequisites:
+
+```bash
+nvidia-smi
+docker info
+docker run --rm --gpus all nvidia/cuda:12.9.1-base-ubuntu24.04 nvidia-smi
+df -h ~/.cache
+```
+
+Expected:
+
+- `nvidia-smi` shows H100 or H200.
+- Docker can run a CUDA container with GPU access.
+- `~/.cache` or the Hugging Face cache volume has at least 200 GB free.
+
+On shared hosts, select only idle GPUs during `mine init`:
+
+```bash
+uv run jarvis mine init --cuda-visible-devices 0
+```
+
+This writes `[mining.extra].cuda_visible_devices`. `mine start` passes that
+device list to Docker and sets `CUDA_VISIBLE_DEVICES` /
+`NVIDIA_VISIBLE_DEVICES` inside the container. Omit the option only on a
+dedicated host where the miner may use all GPUs.
+
+## Configure Mining
+
+Run:
+
+```bash
+uv run jarvis mine doctor
+```
+
+Before config exists, `doctor` should show hardware and Docker as OK, and
+Pearl node / wallet as unconfigured.
+
+Then initialize:
+
+```bash
+uv run jarvis mine init
+```
+
+Use:
+
+- Wallet: the user's Pearl `prl1q...` or `prl1p...` address
+- `pearld` URL: usually `http://localhost:44107`
+- RPC user: configured `pearld` user, often `rpcuser`
+- Password env: `PEARLD_RPC_PASSWORD`
+- Model: `pearl-ai/Llama-3.3-70B-Instruct-pearl`
+- Image: default unless validating a custom Pearl image
+- CUDA devices: an idle GPU ID such as `0` on shared hosts
+
+Expected:
+
+- `[mining]` and `[mining.extra]` are written to config.
+- Image resolves locally, pulls, or builds from the pinned Pearl ref.
+- First build may take 30-60 minutes.
+
+Run `doctor` again:
+
+```bash
+uv run jarvis mine doctor
+```
+
+Expected:
+
+- Hardware OK
+- Docker OK
+- Disk OK
+- Pearl node RPC OK and synced
+- Wallet format OK
+- `vllm-pearl SUPPORTED`
+- Sidecar absent
+
+## Start Mining
+
+```bash
+uv run jarvis mine start
+```
+
+Expected:
+
+- Docker container `openjarvis-pearl-miner` starts.
+- `~/.openjarvis/runtime/mining.json` is written.
+- Sidecar contains `vllm_endpoint`, `gateway_url`, `gateway_metrics_url`, and
+  `container_id`.
+
+Inspect:
+
+```bash
+docker ps --filter name=openjarvis-pearl-miner
+cat ~/.openjarvis/runtime/mining.json
+uv run jarvis mine logs --tail 200
+uv run jarvis mine status
+```
+
+Expected:
+
+- Container is running.
+- vLLM is listening on the configured port, default `8000`.
+- Pearl gateway metrics are available on the configured metrics port, default
+  `8339`.
+- `mine status` exits 0 and prints `provider: vllm-pearl`.
+
+## Verify OpenJarvis Inference Uses Mining Endpoint
+
+Run:
+
+```bash
+uv run jarvis mine doctor
+uv run jarvis ask "Say hello in one sentence."
+```
+
+Expected:
+
+- `doctor` shows sidecar present.
+- Engine discovery registers `vllm-pearl-mining`.
+- The prompt completes through the Pearl/vLLM endpoint.
+- Container logs show vLLM activity during the prompt.
+
+If inference succeeds but mining stats stay zero, continue to the Pearl
+network checks below; vLLM serving alone is not enough to prove mining.
+
+## Verify Pearl Network Submission
+
+Check gateway metrics directly:
+
+```bash
+curl -fsS http://127.0.0.1:8339/metrics | tee /tmp/pearl-gateway-metrics.txt
+uv run jarvis mine status
+```
+
+Expected:
+
+- Metrics endpoint returns Prometheus text.
+- If Pearl exposes share counters, `mine status` maps them correctly.
+- If metric names differ, attach `/tmp/pearl-gateway-metrics.txt` to the PR and
+  update `src/openjarvis/mining/_metrics.py`.
+
+Check `pearld` connectivity using the same RPC configuration used by mining:
+
+```bash
+curl --user "rpcuser:${PEARLD_RPC_PASSWORD}" \
+  --data-binary '{"jsonrpc":"1.0","id":"oj","method":"getblockchaininfo","params":[]}' \
+  -H 'content-type: text/plain;' \
+  http://127.0.0.1:44107
+```
+
+Expected:
+
+- `blocks` and `headers` are present.
+- Node is synced or close enough for mining validation.
+
+Proof of actual earning requires a successful accepted share/block and wallet
+credit. Depending on Pearl network difficulty, this may take longer than the
+smoke test window. Record:
+
+- Runtime duration
+- `mine status` before and after
+- Gateway metrics snapshot
+- Relevant container log tail
+- Wallet balance / transaction evidence if a reward lands
+
+## Stop And Cleanup
+
+```bash
+uv run jarvis mine stop
+docker ps --filter name=openjarvis-pearl-miner
+test ! -e ~/.openjarvis/runtime/mining.json
+```
+
+Expected:
+
+- Container stops.
+- Sidecar is removed.
+- `jarvis ask` no longer routes through `vllm-pearl-mining` unless another
+  mining sidecar is attached.
+
+## Pass Criteria
+
+The NVIDIA provider is considered proven when all are true:
+
+- `mine doctor` reports supported on H100/H200.
+- `mine init` resolves/builds the Pearl image.
+- `mine start` launches the container and writes the sidecar.
+- OpenJarvis inference succeeds through `vllm-pearl-mining`.
+- Pearl gateway metrics are reachable and `mine status` parses them.
+- `pearld` accepts the miner's network path.
+- At least one accepted share/block is observed, or a documented Pearl
+  maintainer confirmation says the observed gateway state is sufficient proof
+  of live mining.
+
+## Failure Artifacts
+
+For any failure, collect:
+
+```bash
+uv run jarvis mine doctor
+uv run jarvis mine status || true
+uv run jarvis mine logs --tail 300 || true
+docker inspect openjarvis-pearl-miner || true
+curl -fsS http://127.0.0.1:8339/metrics || true
+nvidia-smi
+docker info
+```
+
+Attach outputs to the implementation PR or follow-up issue. Do not paste
+`PEARLD_RPC_PASSWORD`, wallet seed material, or Hugging Face tokens.
@@ -0,0 +1,84 @@
+# Adding a Mining Provider
+
+The `openjarvis.mining` subsystem follows the same registry pattern as engines,
+agents, tools, memory, and channels. New mining paths should be provider
+modules, not special cases in the CLI or engine layer.
+
+## Provider Contract
+
+Every provider implements `openjarvis.mining.MiningProvider`:
+
+- `detect(hw, engine_id, model)` is pure capability detection. It must not
+  start subprocesses, hit the network, or mutate state.
+- `start(config)` owns provider lifecycle setup and writes the mining sidecar
+  when it changes inference routing.
+- `stop()` tears down provider-owned processes or containers.
+- `is_running()` answers from provider-owned state.
+- `stats()` returns `MiningStats` using the provider's most stable telemetry
+  surface.
+
+Register providers through `MinerRegistry` and expose idempotent
+`ensure_registered()`:
+
+```python
+from openjarvis.core.registry import MinerRegistry
+
+
+def ensure_registered() -> None:
+    if not MinerRegistry.contains("my-provider"):
+        MinerRegistry.register_value("my-provider", MyProvider)
+```
+
+`tests/conftest.py` clears registries between tests, so test fixtures and CLI
+entry points should call `ensure_registered()` before relying on a provider.
+
+## Optional Dependencies
+
+Provider dependencies belong in scoped extras:
+
+- `mining-pearl-vllm` for the NVIDIA/vLLM Docker provider
+- Future Apple work should use a separate extra such as `mining-pearl-metal`
+  or `mining-pearl-cpu`
+
+Avoid a generic `mining-pearl` extra until there is a shared dependency set
+that every provider actually needs.
+
+## Sidecar Contract
+
+The runtime sidecar lives at `~/.openjarvis/runtime/mining.json`. Engine
+handoff is data-driven:
+
+- If the sidecar has `vllm_endpoint`, engine discovery registers
+  `vllm-pearl-mining`.
+- If a future provider mines alongside the user's normal engine, it should omit
+  `vllm_endpoint`; engine discovery will ignore it.
+
+Do not branch on `provider == "vllm-pearl"` in generic code. Branch on sidecar
+shape or provider capability.
+
+## Apple Silicon Handoff
+
+The Apple Silicon effort should add its own provider module and reuse:
+
+- `MiningProvider`
+- `MinerRegistry`
+- `MiningConfig`
+- `MiningStats`
+- `Sidecar`
+- `jarvis mine doctor` capability iteration
+
+That work should not need to rewrite the NVIDIA provider, CLI group, telemetry
+collector, or engine sidecar handoff.
+
+## NVIDIA Release Gate
+
+The NVIDIA provider is not considered economically proven until the H100/H200
+runbook passes on real hardware. See
+[`mining-nvidia-validation.md`](./mining-nvidia-validation.md) for the required
+commands, artifacts, and pass criteria.
+
+## Model Enablement
+
+New Pearl-compatible language models are tracked separately from provider
+support. See [`pearl-model-enablement.md`](./pearl-model-enablement.md) for the
+conversion and validation checklist.
@@ -0,0 +1,148 @@
+# Pearl Model Enablement
+
+This page tracks the work required to make a new Hugging Face model mineable
+through Pearl's vLLM miner and OpenJarvis.
+
+OpenJarvis can point `vllm-pearl` at a model id, but a raw Hugging Face model is
+not enough. The Pearl vLLM plugin expects a Pearl-compatible quantized model
+whose metadata marks mining layers for 7-bit NoisyGEMM and non-mining layers
+for the vanilla Pearl GEMM path.
+
+## Supported Models
+
+OpenJarvis only supports Pearl models published by the `pearl-ai` Hugging Face
+organization. Private staging artifacts and OpenJarvis-specific conversion
+repos are not user-facing supported mining models.
+
+The current public support set is:
+
+| Raw model | Pearl model | Status |
+|---|---|---|
+| `meta-llama/Llama-3.3-70B-Instruct` | `pearl-ai/Llama-3.3-70B-Instruct-pearl` | Validated default |
+| `google/gemma-4-31B-it` | `pearl-ai/Gemma-4-31B-it-pearl` | Planned until H100/H200 validation passes |
+| `meta-llama/Llama-3.1-8B-Instruct` | `pearl-ai/Llama-3.1-8B-Instruct-pearl` | Planned until H100/H200 validation passes |
+
+## Current Validation Findings
+
+The H100 smoke run validated the default Llama Pearl model end to end through
+`jarvis mine start`, vLLM `/v1/models`, OpenJarvis inference routing, Pearl
+gateway template refresh, and `jarvis mine validate-model`.
+
+`pearl-ai/Gemma-4-31B-it-pearl` and
+`pearl-ai/Llama-3.1-8B-Instruct-pearl` are listed because they are public Pearl
+org artifacts. They remain `planned` in OpenJarvis until we have clean
+H100/H200 validation artifacts for the published repos.
+
+## Enablement Checklist
+
+1. Reproduce the current Llama Pearl model recipe.
+   - Record the compressed-tensors config.
+   - Record which linear layers are 7-bit mining layers.
+   - Record which layers are 8-bit non-mining layers.
+   - Record calibration data and SmoothQuant settings, if used.
+
+2. Convert the target model.
+   - Start with a model Pearl intends to publish under the `pearl-ai` org.
+   - Generate Pearl-compatible quantized weights and metadata.
+   - For Gemma4 artifacts, include the base model's processor metadata required
+     by vLLM's Gemma4 multimodal profiler.
+   - Publish under the planned `pearl-ai/*-pearl` id before enabling it in
+     OpenJarvis.
+
+   OpenJarvis includes an experimental local converter for this work:
+
+   ```bash
+   python scripts/pearl/model_converter.py \
+     meta-llama/Llama-3.1-8B-Instruct \
+     /tmp/pearl-ai-Llama-3.1-8B-Instruct-pearl \
+     --device cuda
+   ```
+
+   The converter copies Hugging Face metadata, emits
+   `quantization_config.quant_method = "pearl"`, writes a safetensors index,
+   converts attention q/k/v and MLP down projections to int8 non-mining layers,
+   and converts the remaining text linear weights to int7 mining layers. Treat
+   its output as a staging artifact until `jarvis mine inspect-model` and
+   `jarvis mine validate-model` pass on H100/H200 hardware.
+
+   Local staging artifacts can be inspected before upload:
+
+   ```bash
+   jarvis mine inspect-model \
+     --model /tmp/pearl-ai-Llama-3.1-8B-Instruct-pearl
+   ```
+
+   To run a local staging artifact through the Docker miner, keep `--model` as
+   the intended served model name and point `--local-model-path` at the
+   converted checkpoint directory:
+
+   ```bash
+   jarvis mine init \
+     --provider vllm-pearl \
+     --wallet-address <prl1...> \
+     --model pearl-ai/Llama-3.1-8B-Instruct-pearl \
+     --local-model-path /tmp/pearl-ai-Llama-3.1-8B-Instruct-pearl \
+     --cuda-visible-devices 1 \
+     --vllm-arg=--language-model-only \
+     --vllm-arg=--skip-mm-profiling
+   jarvis mine start
+   ```
+
+3. Validate the Pearl vLLM plugin path.
+   - Run `jarvis mine inspect-model --model <pearl-model-id>
+     --allow-planned` before starting the miner.
+   - Model loads in Pearl's `vllm-miner` container.
+   - vLLM registers Pearl's quantization plugin.
+   - Mining layers use int7 NoisyGEMM.
+   - Non-mining layers use int8 vanilla Pearl GEMM.
+   - Text generation works with mining enabled and disabled.
+
+4. Validate chain integration.
+   - `pearld` is reachable.
+   - `pearl-gateway` receives work.
+   - NoisyGEMM submits candidate proofs.
+   - Gateway reports metrics.
+   - `jarvis mine status` parses those metrics.
+
+5. Promote the model in OpenJarvis.
+   - Change its registry status from `planned` to `validated`.
+   - Set measured VRAM and context defaults.
+   - Add the model to user docs.
+   - Attach validation logs to the PR.
+
+## OpenJarvis Registry
+
+Model support metadata lives in:
+
+```text
+src/openjarvis/mining/_models.py
+```
+
+`jarvis mine models` renders that registry. Planned models are visible to users
+but blocked by capability detection until the Pearl model artifact and H100/H200
+validation exist.
+
+## Acceptance Criteria
+
+A model is `validated` only when all of these pass on real hardware:
+
+- `jarvis mine inspect-model --model <pearl-model-id> --allow-planned`
+- `jarvis mine init --model <pearl-model-id>`
+- `jarvis mine start`
+- `curl http://127.0.0.1:8000/v1/models`
+- `jarvis ask "Say hello in one sentence."`
+- `jarvis mine status`
+- `jarvis mine validate-model --model <pearl-model-id> --allow-planned --prompt
+  "Say hello in one sentence." --output <artifact>.json`
+- Pearl gateway metrics show the mining path is active.
+- No block/share submission errors appear in gateway or miner logs.
+
+Do not mark a model validated based only on vLLM load success. It must exercise
+Pearl's NoisyGEMM and submission path.
+
+## Tracking
+
+Use the `Pearl Model Validation` GitHub issue template for each candidate model.
+The issue should hold the quantization recipe, hardware details, command output,
+metrics excerpts, and the PR that changes the model status to `validated`.
+Attach the JSON artifact from `jarvis mine validate-model --output` to the issue.
@@ -0,0 +1,52 @@
+# Release Checklist
+
+Before tagging a release, run through this checklist on real machines (not just CI containers).
+
+## Manual smoke tests (~30 min total)
+
+For each platform below, start from a fresh user account / VM snapshot. Run the install one-liner and verify the steps in the table.
+
+| Platform | One-liner | Verify |
+|---|---|---|
+| macOS Intel laptop | `curl -fsSL <url> \| bash` | (1)–(8) below |
+| macOS ARM laptop | same | (1)–(8) |
+| Ubuntu 22.04 fresh VM | same | (1)–(8) |
+| Fedora 40 fresh VM | same | (1)–(8) |
+| WSL2 Ubuntu on Windows | same | (1)–(8) |
+
+### Verification steps
+
+1. **Install completes ≤ 5 min** on typical broadband.
+2. **`jarvis` (no args)** drops into a chat session within 2 s.
+3. **First chat turn returns a response** from `qwen3.5:2b` via Ollama.
+4. **Banner shows background work** ("Setting up in background: …") while it's still going.
+5. **Completion notification fires** between turns when the bg work finishes (Rust extension or a model).
+6. **`jarvis doctor`** exits 0 once all bg work completes; shows the Background tasks table.
+7. **Re-run `curl … | bash`** on the same machine. It completes ≤ 30 s, says `[ok] step already done` for every step.
+8. **`jarvis-uninstall`** removes `~/.openjarvis/` and `~/.local/bin/jarvis*`. Verify with `ls`.
+
+## Cloud quick-path verification
+
+On any one platform:
+
+```bash
+export ANTHROPIC_API_KEY=test-fake-key
+jarvis init --force
+```
+
+Verify init proposes cloud (mentions "anthropic" in the prompt), and the resulting `config.toml` has `[intelligence] provider = "anthropic"`.
+
+## Failure-mode spot checks
+
+Run at least one failure scenario per release; rotate which one.
+
+- Disconnect network mid-install — verify clear error and re-run completes.
+- Delete `~/.openjarvis/config.toml` — verify bare `jarvis` re-runs init.
+- Delete `~/.openjarvis/.venv` — verify re-running curl heals it.
+- `EUID=0 bash install.sh` — verify hard-fail with "don't run as root".
+
+## CI gates (automated, no manual action)
+
+- All pytest tests pass: `uv run pytest tests/`
+- All bats tests pass: see `.github/workflows/bash-tests.yml`
+- Container integration matrix is green: see `.github/workflows/installer-integration.yml`
@@ -9,6 +9,7 @@ These are the areas where active development is happening and contributions are
 - **Energy-aware routing** — using power consumption data from telemetry to optimize for energy efficiency alongside latency and quality
 - **Plugin ecosystem** — community-contributed engines, tools, and agents distributed as Python packages
 - **Federated memory** — memory backends that synchronize across devices
+- **LLM-guided spec search:** Frontier-driven harness learning — a frontier model analyzes your traces and proposes config improvements. See [user guide](../user-guide/llm-guided-spec-search.md) and [architecture](../architecture/learning.md#llm-guided-spec-search-frontier-driven-harness-learning).

 ---

@@ -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.
@@ -75,7 +75,7 @@ npm install
 npm run tauri build
 ```

-The built installer will be in `desktop/src-tauri/target/release/bundle/`.
+The built installer will be in `frontend/src-tauri/target/release/bundle/`.

 ---

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

@@ -1,240 +0,0 @@
-# NeurIPS 2026 Experiment Plan: IPW/IPJ for Local AI
-
-## Overview
-Evaluate and optimize local AI models as OpenClaw agent brains, measuring
-accuracy, latency, cost, energy, and FLOPs across 7 benchmarks.
-
-## Results Storage
-All results stored under `results/neurips-2026/`:
-```
-results/neurips-2026/
-├── baselines/                    # Step 1: Raw model scores
-│   ├── {model}/{benchmark}/      # e.g. qwen-9b/pinchbench/
-│   │   ├── results.jsonl         # Per-task results
-│   │   ├── summary.json          # Aggregate metrics
-│   │   └── telemetry.json        # Energy, power, FLOPs, tokens
-│   └── ...
-├── agent-optimization/           # Step 2a: Agent improvements
-│   ├── gepa/                     # GEPA prompt evolution results
-│   │   ├── generation_{N}/       # Per-generation best prompts
-│   │   └── best_configs/         # Final optimized agent configs
-│   ├── dspy/                     # DSPy optimization results
-│   │   ├── bootstrap/            # BootstrapFewShot results
-│   │   └── mipro/                # MIPROv2 results
-│   └── agent-configs/            # New agent configurations tested
-├── intelligence-optimization/    # Step 2b: Model improvements
-│   ├── sft/                      # Supervised fine-tuning
-│   │   ├── qwen-2b/              # Per-model training runs
-│   │   ├── qwen-9b/
-│   │   └── qwen-27b/
-│   ├── lora/                     # LoRA fine-tuning
-│   │   ├── qwen-2b/
-│   │   ├── qwen-9b/
-│   │   └── qwen-27b/
-│   └── rl/                       # Reinforcement learning (GRPO)
-│       ├── qwen-2b/
-│       ├── qwen-9b/
-│       └── qwen-27b/
-├── optimized-eval/               # Step 3: Full eval with best configs
-│   ├── {model}/{benchmark}/      # Same structure as baselines/
-│   └── ...
-└── analysis/                     # Charts, tables, comparisons
-    ├── pareto_frontier.json      # IPW/IPJ data points
-    ├── scaling_curves.json       # Accuracy vs model size
-    ├── cost_comparison.json      # Local vs cloud economics
-    └── figures/                  # Generated plots
-```
-
-## Hardware Stacks
-
-Run eval metrics across three hardware vendor stacks to show
-platform-agnostic IPW/IPJ results:
-
-| Stack | Server-Class | Workstation/Consumer |
-|-------|-------------|---------------------|
-| **NVIDIA** | DGX Spark | RTX 6000 Pro |
-| **AMD** | MI300x, MI355x | — |
-| **Apple** | — | Mac Mini M4, Mac Studio M4 |
-
-Results stored per-stack under each model's directory:
-```
-results/neurips-2026/baselines/{model}/{benchmark}/
-├── nvidia-dgxspark/
-│   ├── results.jsonl
-│   ├── telemetry.json    # NVML energy, GPU util, power
-│   └── summary.json
-├── nvidia-rtx6000pro/
-├── amd-mi300x/
-│   ├── telemetry.json    # ROCm energy, GPU util, power
-│   └── ...
-├── amd-mi355x/
-├── apple-macmini-m4/
-│   ├── telemetry.json    # Apple powermetrics energy
-│   └── ...
-└── apple-macstudio-m4/
-```
-
-OpenJarvis telemetry already supports all three vendors:
- NVIDIA: `telemetry/nvidia_monitor.py` (NVML)
- AMD: `telemetry/amd_monitor.py` (ROCm SMI)
- Apple: `telemetry/apple_monitor.py` (powermetrics)
-
-Key comparisons:
- Same model, same benchmark, different hardware → IPW/IPJ per platform
- DGX Spark vs MI300x vs Mac Studio → server-class efficiency frontier
- RTX 6000 Pro vs Mac Mini M4 → consumer/workstation efficiency frontier
- GGUF models (Kimi, MiniMax) run on all platforms via llama.cpp/MLX
-
-## Models (9 priority + 3 cloud baselines)
-
-### Cloud Baselines
-| ID | Model | Engine |
-|----|-------|--------|
-| claude-opus | Claude Opus 4.6 | cloud |
-| gpt-54 | GPT-5.4 | cloud |
-| gemini-31-pro | Gemini 3.1 Pro | cloud |
-
-### Priority Local Models
-| ID | Model | Active Params | Serving | Hardware |
-|----|-------|---------------|---------|----------|
-| qwen-397b | Qwen3.5-397B-A17B-FP8 | 17B | vLLM | 8x H100 |
-| qwen-27b | Qwen3.5-27B-FP8 | 27B | vLLM | 1-2x H100 |
-| qwen-9b | Qwen3.5-9B | 9B | vLLM/Ollama | 1x GPU |
-| qwen-2b | Qwen3.5-2B | 2B | Ollama | laptop |
-| trinity-large | Trinity-Large-Thinking | 13B | vLLM | 4-8x H100 |
-| nemotron-nano | Nemotron-3-Nano-30B-A3B | 3B | vLLM | 1x GPU |
-| kimi-k25 | Kimi-K2.5 (GGUF) | ~32B | llama.cpp | 2x GPU |
-| minimax-m25 | MiniMax-M2.5 (GGUF) | ~45B | llama.cpp | 2-4x GPU |
-| lfm-1.2b | LFM2.5-1.2B-Instruct | 1.2B | llama.cpp | CPU |
-
-## Benchmarks (7)
-
-| ID | Benchmark | Tasks | Fast Subset | Status |
-|----|-----------|-------|-------------|--------|
-| pinchbench | PinchBench | 23 | 23 (all) | Implemented |
-| taubench | TauBench V2 | 60+40 | 20 A+R | Implemented |
-| gaia | GAIA | 50 | 20 | Implemented |
-| terminalbench | TerminalBench | varies | 20 | Implemented |
-| toolcall15 | ToolCall-15 | 15 | 15 (all) | TODO |
-| livecodebench | LiveCodeBench | ~100 | 20 | TODO |
-| liveresearch | LiveResearchBench | 100 | 10 | TODO |
-
-## Metrics Captured Per Run
- accuracy (benchmark-specific)
- latency_seconds (wall clock per task)
- energy_joules (RAPL + NVML)
- power_watts (average during inference)
- cost_usd (API cost for cloud, amortized HW for local)
- prompt_tokens, completion_tokens
- tool_calls_count
- flops_estimated (2 * active_params * total_tokens)
- gpu_utilization_pct
- throughput_tok_per_sec
-
---
-
-## Step 1: Baseline Sweep
-
-### Phase 1a: Implement missing benchmarks
- [ ] ToolCall-15 integration
- [ ] LiveCodeBench integration
- [ ] LiveResearchBench integration
- [ ] Wire telemetry capture to all eval runs
-
-### Phase 1b: Run cloud baselines (no GPU needed)
- [x] Claude Opus — PinchBench (95.65%), TauBench A+R (86.67%),
-      TauBench Telecom (75%), GAIA (66.67%)
- [x] GPT-5.4 — PinchBench (52-65%), TauBench A+R (81.67%),
-      TauBench Telecom (75%), GAIA (34.29%)
- [x] Gemini 3.1 Pro — PinchBench (78.26%), TauBench A+R (58.33%),
-      TauBench Telecom (77.5%), GAIA (47.06%)
- [ ] All 3 cloud baselines — ToolCall-15, LiveCodeBench, LiveResearchBench
- [ ] All 3 cloud baselines — TerminalBench
-
-### Phase 1c: Run local models (GPU required)
- [x] Qwen-397B — PinchBench (78.26%), TauBench A+R (81.67%)
- [x] Qwen-122B — PinchBench (73.91%), TauBench A+R (80%)
- [x] Qwen-35B — PinchBench (73.91%), TauBench A+R (77.27%)
- [x] Nemotron-Super — PinchBench (78.26%), TauBench A+R (86.67%),
-      TauBench Telecom (70%), GAIA (48.48%)
- [ ] Qwen-27B — all 7 benchmarks
- [ ] Qwen-9B — all 7 benchmarks
- [ ] Qwen-2B — all 7 benchmarks
- [ ] Trinity-Large — all 7 benchmarks
- [ ] Nemotron-Nano — all 7 benchmarks
- [ ] Kimi-K2.5 — all 7 benchmarks
- [ ] MiniMax-M2.5 — all 7 benchmarks
- [ ] LFM-1.2B — all 7 benchmarks
-
-### Phase 1d: Compile baseline results
- [ ] Generate Pareto frontier plots (quality vs cost, vs energy, vs FLOPs)
- [ ] Generate scaling curves (accuracy vs active params per benchmark)
- [ ] Compute IPW/IPJ for every (model, benchmark) pair
-
---
-
-## Step 2: Optimization
-
-### Phase 2a: Agent optimization
- [ ] GEPA: evolve system prompts for monitor_operative on fast benchmarks
- [ ] GEPA: evolve system prompts for native_openhands on fast benchmarks
- [ ] DSPy BootstrapFewShot: optimize few-shot examples per benchmark
- [ ] DSPy MIPROv2: optimize full prompt pipeline
- [ ] Agent architecture search: test new agent configs
- [ ] Tool selection optimization: find minimal effective tool sets
- [ ] Evaluate optimized agents on all 9 models × fast benchmarks
-
-### Phase 2b: Intelligence optimization
-Training data:
- GeneralThought-430K-filtered (reasoning traces)
- neulab/agent-data-collection (agentic traces)
- GLM-4.7-flash SFT traces (168K + 57K)
-
-Training targets:
- [ ] Qwen-2B: full SFT on agentic traces
- [ ] Qwen-2B: LoRA on agentic traces
- [ ] Qwen-9B: full SFT on agentic traces
- [ ] Qwen-9B: LoRA on agentic traces
- [ ] Qwen-27B: LoRA on agentic traces
- [ ] Qwen-2B: GRPO RL on benchmark outcomes
- [ ] Qwen-9B: GRPO RL on benchmark outcomes
- [ ] Evaluate all trained checkpoints on fast benchmarks
-
---
-
-## Step 3: Full Evaluation
-
- [ ] Select best Agent config from Step 2a
- [ ] Select best Intelligence checkpoints from Step 2b
- [ ] Run complete 9 × 7 matrix with optimized configs
- [ ] Compute all metrics (accuracy, latency, energy, cost, tokens, FLOPs)
- [ ] Generate final comparison tables and figures
- [ ] Write up results section
-
---
-
-## Current Progress
-
-### Completed
- PinchBench harness: fixed and validated (PR #124, #139, #140)
- TauBench V2 native integration (PR #162)
- tool_choice + SQLite fixes (PR #163)
- Gemini thought_signature support
- Nemotron SGLang serving
- 8 models evaluated on PinchBench
- 7 models evaluated on TauBench A+R
- 4 models evaluated on TauBench Telecom
- 4 models evaluated on GAIA
-
-### In Progress
- Qwen 35B: TauBench telecom + GAIA running
- ToolCall-15 integration: TODO
- LiveCodeBench integration: TODO
- LiveResearchBench integration: TODO
- Telemetry wiring: TODO
-
-### Blocked
- Qwen 397B telecom + GAIA: needs 8 GPUs
- Trinity-Large: not yet served
- Small models (2B, 9B): configs not yet created
- GGUF models (Kimi, MiniMax): need llama.cpp/Ollama serving setup
@@ -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())
@@ -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.
@@ -1057,3 +1097,59 @@ OpenJarvis respects the following environment variables:
 - [Architecture Overview](../architecture/overview.md) — Understand how the pieces fit together
 - [Intelligence Primitive](../architecture/intelligence.md) — Model identity and generation defaults
 - [Learning & Traces](../architecture/learning.md) — Router policies and the trace-driven feedback loop
+
+---
+
+## Learning & spec search
+
+LLM-guided spec search uses a frontier model to automatically improve your local agent configuration. See the [user guide](../user-guide/llm-guided-spec-search.md) for a full walkthrough.
+
+### `[learning.spec_search]`
+
+| Key | Type | Default | Description |
+|-----|------|---------|-------------|
+| `enabled` | bool | `true` | Gate the entire spec-search subsystem |
+| `autonomy_mode` | string | `"tiered"` | `auto`, `tiered`, or `manual` |
+| `teacher_model` | string | `"claude-opus-4-6"` | Frontier model for diagnosis and planning |
+| `max_cost_per_session_usd` | float | `5.0` | Per-session teacher API budget |
+| `max_tool_calls_per_diagnosis` | int | `30` | Max teacher tool calls in diagnosis phase |
+
+### `[learning.spec_search.triggers]`
+
+| Key | Type | Default | Description |
+|-----|------|---------|-------------|
+| `scheduled_enabled` | bool | `true` | Enable daily scheduled sessions |
+| `scheduled_cron` | string | `"0 3 * * *"` | Cron expression for scheduled trigger |
+| `scheduled_min_new_traces` | int | `20` | Minimum new traces to trigger |
+| `cluster_enabled` | bool | `true` | Enable failure cluster trigger |
+| `cluster_check_interval_minutes` | int | `60` | How often to check for clusters |
+| `cluster_min_size` | int | `5` | Minimum traces in a cluster |
+| `cluster_failure_threshold` | float | `0.3` | Feedback <= this counts as failure |
+
+### `[learning.spec_search.gate]`
+
+| Key | Type | Default | Description |
+|-----|------|---------|-------------|
+| `min_improvement` | float | `0.0` | Minimum overall score improvement to accept |
+| `max_regression` | float | `0.05` | Maximum per-cluster score drop before rejecting |
+| `benchmark_subsample_size` | int | `50` | Tasks per gate run |
+| `full_benchmark` | bool | `false` | Disable subsampling (slower, more accurate) |
+
+### `[learning.spec_search.benchmark]`
+
+| Key | Type | Default | Description |
+|-----|------|---------|-------------|
+| `synthesis_feedback_threshold` | float | `0.7` | Min feedback for benchmark traces |
+| `max_benchmark_size` | int | `200` | Max tasks in the benchmark |
+| `auto_refresh` | bool | `true` | Auto-mine new high-feedback traces |
+| `max_synthesis_cost_usd_per_refresh` | float | `2.0` | Cost cap per benchmark refresh |
+
+### `[learning.spec_search.tier_overrides]`
+
+Override the default risk tier for any operation. Keys are operation names, values are tier strings (`auto`, `review`, `manual`).
+
+```toml
+[learning.spec_search.tier_overrides]
+# patch_system_prompt = "auto"     # promote to auto after trust
+# replace_system_prompt = "auto"
+```
@@ -0,0 +1,136 @@
+# Installation
+
+## Platform-specific guides
+
+| Platform | One-liner | Detailed guide |
+|---|---|---|
+| **macOS** | `curl -fsSL https://open-jarvis.github.io/OpenJarvis/install.sh \| bash` | [macOS install](macos.md) |
+| **Linux** | `curl -fsSL https://open-jarvis.github.io/OpenJarvis/install.sh \| bash` | [Linux install](linux.md) |
+| **WSL2 on Windows** | `curl -fsSL https://open-jarvis.github.io/OpenJarvis/install.sh \| bash` (run inside Ubuntu) | [WSL2 install](wsl2.md) |
+| **Native Windows** | `irm https://open-jarvis.github.io/OpenJarvis/install.ps1 \| iex` | [Native Windows install](windows-native.md) |
+| **Desktop GUI** | Download from the [latest release](https://github.com/open-jarvis/OpenJarvis/releases) | — |
+
+The bash and PowerShell installers do the same thing on their respective hosts. The rest of this page documents the bash installer in detail; the [native Windows guide](windows-native.md) is the equivalent reference for PowerShell.
+
+## Bash installer
+
+```bash
+curl -fsSL https://open-jarvis.github.io/OpenJarvis/install.sh | bash
+```
+
+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
+
+| Phase | Step | Where |
+|---|---|---|
+| Foreground | Install `uv` (Python package manager) | `~/.cargo/bin/` or `~/.local/bin/` |
+| Foreground | Clone OpenJarvis repo | `~/.openjarvis/src/` |
+| Foreground | Create Python 3.11 venv | `~/.openjarvis/.venv/` |
+| Foreground | `uv pip install -e .` (editable install) | venv |
+| Foreground | Install Ollama | system default |
+| Foreground | Start `ollama serve` | systemd-user / launchd / nohup |
+| Foreground | Pull `qwen3.5:2b` (~1.5 GB) | Ollama's model store |
+| Foreground | Write `config.toml` (auto-detected hardware + engine + model) | `~/.openjarvis/config.toml` |
+| Foreground | Symlink `jarvis` and `jarvis-uninstall` | `~/.local/bin/` |
+| Foreground | Add `~/.local/bin` to PATH if missing (with on-screen notice) | `~/.bashrc` or `~/.zshrc` |
+| Background | Install Rust toolchain via rustup | `~/.cargo/` |
+| Background | Build the maturin extension (memory + security features) | venv |
+| Background | Pull hardware-tier and tier+1 models | Ollama's model store |
+
+## What the installer does NOT touch
+
+- Your existing Python installations
+- Your `~/.bashrc` / `~/.zshrc` other than appending one PATH line (with on-screen notice)
+- Your existing Ollama models
+- Any other tool or dotfile
+
+## Idempotent re-runs
+
+Re-running the curl line is safe. The installer reads `~/.openjarvis/.state/install-state.json` and skips completed steps. If your venv got nuked, re-running heals it.
+
+## Cloud quick-path
+
+If any of these env vars are set when you install or run `jarvis init`, the installer/init proposes cloud as the default and writes the matching provider into `config.toml`:
+
+- `OPENROUTER_API_KEY`
+- `ANTHROPIC_API_KEY`
+- `OPENAI_API_KEY`
+- `GOOGLE_API_KEY` (or `GEMINI_API_KEY`)
+
+Local-first remains the default when no key is in env. Precedence is OpenRouter > Anthropic > OpenAI > Google.
+
+## Flags
+
+| Flag | Effect |
+|---|---|
+| `--minimal` | Skip the foreground model pull. First chat will need to wait for the bg pull to finish. |
+| `--no-bg-orchestrator` | Don't detach the background work pipeline. (Mostly for testing.) |
+| `--force` | Re-run all steps even if `install-state.json` says they're done. |
+
+## Environment overrides
+
+| Variable | Default | Purpose |
+|---|---|---|
+| `OPENJARVIS_HOME` | `$HOME/.openjarvis` | Install location. |
+| `OPENJARVIS_REPO_URL` | `https://github.com/open-jarvis/OpenJarvis.git` | Source repo for the clone step. |
+
+## Uninstall
+
+```bash
+jarvis-uninstall
+```
+
+Removes `~/.openjarvis/`, `~/.local/bin/jarvis`, and `~/.local/bin/jarvis-uninstall`. Leaves Ollama, uv, and the Rust toolchain in place (they may be used by other tools); the script prints removal hints.
+
+## Updating
+
+```bash
+jarvis update
+```
+
+Pulls the latest source, refreshes the editable install, and rebuilds the Rust extension in the background. Models are not touched.
+
+## Troubleshooting
+
+### "command not found: jarvis"
+
+`~/.local/bin` isn't on your PATH. Run `source ~/.bashrc` (or `~/.zshrc`) or open a new terminal.
+
+### "memory features unavailable"
+
+Rust extension hasn't finished building yet (or failed). Check status:
+
+```bash
+jarvis doctor
+```
+
+Manually retry:
+
+```bash
+~/.openjarvis/.scripts/install-rust.sh && ~/.openjarvis/.scripts/build-extension.sh
+```
+
+### A bigger model failed to download
+
+Check status and retry:
+
+```bash
+jarvis doctor
+~/.openjarvis/.scripts/pull-model.sh qwen3.5:9b
+```
+
+### Behind a corporate proxy
+
+Set `HTTPS_PROXY` and `CURL_CA_BUNDLE` in your environment before running the installer.
@@ -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.

@@ -121,7 +121,7 @@ npm install
 npm run tauri build
 ```

-The built installer will be in `desktop/src-tauri/target/release/bundle/`.
+The built installer will be in `frontend/src-tauri/target/release/bundle/`.

 ---

@@ -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
@@ -0,0 +1,30 @@
+# Linux Install
+
+```bash
+curl -fsSL https://open-jarvis.github.io/OpenJarvis/install.sh | bash
+```
+
+Tested on: Ubuntu 22.04 / 24.04, Fedora 40, Debian 12, Arch.
+
+## Prerequisites
+
+Most distros ship `git` and `curl`. If yours doesn't:
+
+```bash
+# Debian / Ubuntu
+sudo apt install git curl
+
+# Fedora / RHEL
+sudo dnf install git curl
+
+# Arch
+sudo pacman -S git curl
+```
+
+## NVIDIA / AMD GPU
+
+The installer auto-detects via `nvidia-smi` / `rocm-smi`. Datacenter cards (A100, H100, MI300+) get vLLM as the recommended engine; consumer cards get Ollama (NVIDIA) or Lemonade (AMD).
+
+## See also
+
+- [Full installer reference](install.md)
@@ -1,421 +1,26 @@
---
-title: macOS Installation Guide
-description: Complete step-by-step guide to installing OpenJarvis on macOS with llama.cpp, including common pitfalls and fixes
-search:
-  boost: 2
---
-
-# macOS Installation Guide
-
-This guide walks through a complete OpenJarvis installation on macOS using **llama.cpp** as
-the inference engine. It covers every step from scratch — including pitfalls not documented
-elsewhere — and is suitable for both Apple Silicon and Intel Macs.
-
-!!! tip "Prefer Ollama?"
-    If you want the fastest possible setup, use [Ollama](installation.md#ollama-recommended)
-    instead. This guide is for users who want to run GGUF models directly with llama.cpp,
-    or who want a deeper understanding of the full stack.
-
---
-
-## What You'll Install
-
-| Tool | Purpose |
-|------|---------|
-| Homebrew | macOS package manager — installs everything else |
-| uv | Python version and dependency manager |
-| Git | Clones the OpenJarvis repo |
-| Node.js | Required for the browser UI |
-| Rust | Compiles the OpenJarvis security and memory extension |
-| llama.cpp | Local inference engine that runs GGUF model files |
-| OpenJarvis | The framework itself |
-| A GGUF model | The actual AI model (downloaded separately) |
-
---
-
-## Step-by-Step Installation
-
-### Step 1 — Install Homebrew
-
-Homebrew is the standard macOS package manager. Everything else in this guide is installed
-through it.
+# macOS Install

 ```bash
-/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
+curl -fsSL https://open-jarvis.github.io/OpenJarvis/install.sh | bash
 ```

-If you already have Homebrew, skip this step.
+Works on Intel and Apple Silicon. The installer auto-detects your CPU/GPU.

---
+## Prerequisites

-### Step 2 — Install uv
+If you've never run `git` or `curl` on this Mac, macOS will prompt you to install the Xcode Command Line Tools the first time you run them. Accept the prompt; that gives you both.

-`uv` replaces pip, virtualenv, and pyenv in one tool. OpenJarvis uses it to manage Python
-versions, virtual environments, and project dependencies.
+If you'd rather pre-install:

 ```bash
-brew install uv
+xcode-select --install
 ```

---
+## Apple Silicon notes

-### Step 3 — Install Git
+- The installer picks `mlx` as the recommended engine via the standard hardware-detect path, but the foreground default is still Ollama for compatibility. Switch later with `jarvis init --force` and pick `mlx` if you've installed `mlx-lm`.
+- Unified memory is reported as "VRAM" by the installer — that's intentional; on Apple Silicon, system RAM is what GPU-accelerated models can use.

-Git is used to clone the OpenJarvis source code. It may already be present if you have
-Xcode Command Line Tools installed.
+## See also

-```bash
-brew install git
-```
-
---
-
-### Step 4 — Install Node.js
-
-Node.js is required to build and run the browser frontend. Without it you can still use
-the CLI, but not the web UI.
-
-```bash
-brew install node
-```
-
---
-
-### Step 5 — Install Rust
-
-OpenJarvis includes a Rust extension that provides security scanning, memory indexing,
-rate limiting, and tool execution. It must be compiled from source.
-
-```bash
-curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
-```
-
-After the installer finishes, reload your shell so `rustc` is available:
-
-```bash
-source "$HOME/.cargo/env"
-```
-
-Verify:
-
-```bash
-rustc --version
-```
-
---
-
-### Step 6 — Install llama.cpp
-
-llama.cpp is the inference engine that loads and runs GGUF model files. It is not a model
-itself — think of it as a media player and the `.gguf` file as the content.
-
-```bash
-brew install llama.cpp
-```
-
---
-
-### Step 7 — Clone the OpenJarvis repo
-
-Run this from your home directory or any neutral parent folder.
-
-```bash
-cd ~
-git clone https://github.com/open-jarvis/OpenJarvis.git
-cd OpenJarvis
-```
-
-!!! warning "Do not clone from inside an existing OpenJarvis folder"
-    A common mistake is running `git clone` while already inside the repo, creating deeply
-    nested duplicates (`OpenJarvis/OpenJarvis/OpenJarvis`). Always clone from `~` or a
-    neutral parent directory.
-
---
-
-### Step 8 — Pin Python to 3.12
-
-!!! warning "Critical step — do not skip"
-    OpenJarvis requires Python 3.10–3.13. Its Rust extension uses PyO3, which does not yet
-    support Python 3.14. If `uv` has Python 3.14 available, it will use it by default,
-    causing the Rust extension build to fail silently and resulting in ~250 test failures
-    with `ModuleNotFoundError: No module named 'openjarvis_rust'`.
-
-Pin the project to Python 3.12:
-
-```bash
-echo "3.12" > .python-version
-uv python install 3.12
-rm -rf .venv
-uv venv
-```
-
-**Restart your terminal**, then verify:
-
-```bash
-uv run python --version
-# Must show: Python 3.12.x
-```
-
-!!! tip "Why restart the terminal?"
-    Without restarting, the shell may still reference the old virtual environment. This is
-    the most common reason the version pin appears not to work.
-
---
-
-### Step 9 — Install Python dependencies
-
-```bash
-uv sync --extra dev --extra server
-```
-
-The `--extra server` flag adds the FastAPI backend required for the browser UI.
-
---
-
-### Step 10 — Build the Rust extension
-
-This compiles the Rust extension and installs it into the virtual environment. It provides
-security scanning, memory indexing, MCP tool execution, and rate limiting. This step takes
-a few minutes on first run.
-
-```bash
-uv run maturin develop -m rust/crates/openjarvis-python/Cargo.toml
-```
-
-Verify it built correctly:
-
-```bash
-uv run python -c "import openjarvis_rust; print('Rust extension OK')"
-```
-
---
-
-### Step 11 — Install frontend dependencies
-
-```bash
-cd frontend && npm install && cd ..
-```
-
---
-
-### Step 12 — Download a model
-
-OpenJarvis needs a GGUF model file to run inference. First install the Hugging Face CLI,
-then download your chosen model.
-
-```bash
-uv tool install huggingface_hub
-```
-
-!!! note "The CLI command is `hf`, not `huggingface-cli`"
-    When installed via `uv tool`, the Hugging Face CLI is invoked as `hf`.
-
-=== "Qwen3 4B (~2.5 GB)"
-
-    Faster, lower RAM requirement. Good for most everyday tasks.
-
-    ```bash
-    hf download bartowski/Qwen_Qwen3-4B-GGUF \
-      --include "Qwen_Qwen3-4B-Q4_K_M.gguf" \
-      --local-dir ~/models
-    ```
-
-=== "Qwen3 8B (~4.7 GB)"
-
-    Better reasoning and instruction following. Requires more RAM.
-
-    ```bash
-    hf download bartowski/Qwen_Qwen3-8B-GGUF \
-      --include "Qwen_Qwen3-8B-Q4_K_M.gguf" \
-      --local-dir ~/models
-    ```
-
-!!! warning "Use the `Qwen_` prefix"
-    bartowski's Qwen3 repos use the `Qwen_` prefix (e.g. `Qwen_Qwen3-4B-GGUF`). Using
-    the shorter name without the prefix returns a "repository not found" error.
-
-!!! tip "Apple Silicon vs Intel"
-    On Apple Silicon, both models benefit from Metal GPU acceleration when using the MLX
-    engine. On Intel, inference runs on CPU — the 4B model is recommended for speed.
-
---
-
-### Step 13 — Configure OpenJarvis
-
-Run the init command to detect your hardware and generate a config file:
-
-```bash
-uv run jarvis init
-```
-
-Then open the config and set the default model to match the filename you downloaded:
-
-```bash
-nano ~/.openjarvis/config.toml
-```
-
-Find the `default_model` line and update it, for example:
-
-```toml
-default_model = "Qwen_Qwen3-4B-Q4_K_M.gguf"
-```
-
---
-
-### Step 14 — Verify the installation
-
-```bash
-uv run jarvis doctor
-```
-
-A healthy setup looks like this:
-
-```
-✓  Python version         3.12.x
-✓  Config file            ~/.openjarvis/config.toml
-✓  Config parsing         Config loaded successfully
-✓  Engine: llamacpp       Reachable
-✓  Models: llamacpp       Qwen_Qwen3-4B-Q4_K_M.gguf
-✓  Default model          Qwen_Qwen3-4B-Q4_K_M.gguf (on llamacpp)
-```
-
-!!! note "Warnings for other engines are normal"
-    The `!` warnings for engines like `ollama`, `vllm`, and `lmstudio` simply mean those
-    backends are not running. You only need `llamacpp` to be reachable.
-
---
-
-## Running OpenJarvis
-
-### CLI
-
-Start llama-server in one terminal, then run queries in another:
-
-```bash
-# Terminal 1 — start the inference engine
-llama-server -m ~/models/Qwen_Qwen3-4B-Q4_K_M.gguf -c 4096 -t 8
-
-# Terminal 2 — ask a question
-cd ~/OpenJarvis
-uv run jarvis ask "What is the capital of France?"
-```
-
-### Browser UI
-
-```bash
-# Terminal 1 — inference engine
-llama-server -m ~/models/Qwen_Qwen3-4B-Q4_K_M.gguf -c 4096 -t 8
-
-# Terminal 2 — backend
-cd ~/OpenJarvis && uv run jarvis serve --port 8000
-
-# Terminal 3 — frontend
-cd ~/OpenJarvis/frontend && npm run dev
-```
-
-Then open [http://localhost:5173](http://localhost:5173).
-
-### Skip typing `uv run` every time
-
-Activate the virtual environment for your current terminal session:
-
-```bash
-source ~/OpenJarvis/.venv/bin/activate
-```
-
-Your prompt will show `(openjarvis)` when active, and you can type `jarvis ask "..."` directly.
-
---
-
-## Performance Tips
-
-These tips apply when using llama.cpp for CPU inference.
-
-| Flag | Effect |
-|------|--------|
-| `-c 4096` | Reduces context window from the 32,768 default, freeing RAM for faster inference |
-| `-t 8` | Uses all available CPU threads (default is only 4) — adjust to your machine's thread count |
-| `Q4_K_M` quantization | Best balance of size, speed, and quality for CPU inference |
-
-On Apple Silicon, switching to the [MLX engine](../architecture/engine.md) gives
-significantly better performance than llama.cpp for most models.
-
---
-
-## Common Errors
-
-### `No such file or directory` when loading model
-
-The path `path/to/model.gguf` in examples is a placeholder. Replace it with your actual
-model path, e.g.:
-
-```bash
-llama-server -m ~/models/Qwen_Qwen3-4B-Q4_K_M.gguf
-```
-
---
-
-### `No module named 'openjarvis_rust'`
-
-The Rust extension did not build correctly, or was built against the wrong Python version.
-
-1. Confirm Python 3.12 is active: `uv run python --version`
-2. Rebuild: `uv run maturin develop -m rust/crates/openjarvis-python/Cargo.toml`
-
-If the version shows 3.14, go back to [Step 8](#step-8--pin-python-to-312).
-
---
-
-### `PyO3 version error — Python 3.14 too new`
-
-```
-error: the configured Python interpreter version (3.14) is newer than
-PyO3's maximum supported version (3.13)
-```
-
-PyO3 0.23.5 supports Python up to 3.13. Follow [Step 8](#step-8--pin-python-to-312) to
-pin to 3.12, then delete `.venv`, recreate it, and restart your terminal before retrying.
-
---
-
-### `Repository not found` when downloading model
-
-bartowski's Qwen3 repos use the `Qwen_` prefix. Use:
-
-```
-bartowski/Qwen_Qwen3-4B-GGUF   ✓
-bartowski/Qwen3-4B-GGUF        ✗
-```
-
---
-
-### `No inference engine available`
-
-llama-server is not running. Start it in a separate terminal before running any `jarvis`
-commands, and wait until you see `model loaded` in the output.
-
---
-
-### Python version still shows 3.14 after recreating the venv
-
-Close the terminal completely and reopen it. The old venv path is cached in the shell
-environment and persists across commands until the session ends.
-
---
-
-### `zsh: command not found: huggingface-cli`
-
-When installed via `uv tool`, the CLI is invoked as `hf`, not `huggingface-cli`:
-
-```bash
-hf download ...   # ✓
-huggingface-cli download ...   # ✗
-```
-
---
-
-## Next Steps
-
- [Quick Start](quickstart.md) — Run your first query and explore agents and tools
- [Configuration](configuration.md) — Customize engine hosts, model routing, memory, and more
- [Architecture](../architecture/overview.md) — Understand how OpenJarvis is structured
+- [Full installer reference](install.md)
@@ -7,6 +7,11 @@ search:

 # Quick Start

+!!! tip "Running `jarvis` commands"
+    Every `jarvis ...` example below assumes you have either activated the project venv
+    (`source .venv/bin/activate`) or are prefixing each command with `uv run`. A bare
+    `jarvis init --preset ...` from a fresh clone will fail with `command not found`.
+
 ## What You Can Build

 OpenJarvis is a modular AI assistant framework. Here's what developers build with it:
@@ -14,7 +19,7 @@ OpenJarvis is a modular AI assistant framework. Here's what developers build wit
 === "Chat with Any Model"

    ```bash
-    jarvis ask "Explain quantum entanglement" -m qwen3:8b
+    jarvis ask "Explain quantum entanglement" -m qwen3.5:4b   # use qwen3.5:9b or larger on GPU
    ```

 === "Agent + Tools"
@@ -30,6 +35,13 @@ OpenJarvis is a modular AI assistant framework. Here's what developers build wit
    jarvis ask "How do I configure the engine?"
    ```

+    !!! warning "Requires the Rust extension"
+        `jarvis memory index` and `jarvis memory search` import `openjarvis_rust`. If you
+        skipped the `uv run maturin develop -m rust/crates/openjarvis-python/Cargo.toml`
+        step in [Installation](installation.md), these commands fail with
+        `ModuleNotFoundError: No module named 'openjarvis_rust'`. Build the extension
+        once and any preset (including `deep-research`) will work.
+
 === "5-Line Python SDK"

    ```python
@@ -123,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"
@@ -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).
@@ -0,0 +1,34 @@
+# WSL2 Install
+
+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
+
+In an admin PowerShell:
+
+```powershell
+wsl --install
+```
+
+Then open the Ubuntu (or Debian) shell that gets installed.
+
+## Install OpenJarvis
+
+```bash
+curl -fsSL https://open-jarvis.github.io/OpenJarvis/install.sh | bash
+```
+
+About 3 minutes. Type `jarvis` to start.
+
+## WSL-specific notes
+
+- The installer detects WSL via `/proc/sys/kernel/osrelease` and uses `nohup ollama serve &` instead of systemd to start the Ollama daemon (WSL2 doesn't ship systemd by default).
+- The first time you run `jarvis`, the WSL kernel may show a "process running in background" notification — that's the bg-orchestrator detaching. It's expected.
+- Models are stored in WSL's filesystem (`~/.openjarvis/`), not your Windows drive. To free up space later: `jarvis-uninstall` removes everything.
+
+## See also
+
+- [Full installer reference](install.md)
@@ -9,25 +9,30 @@ hide:

 # Personal AI, On Personal Devices

-<p align="center">
-  <a href="https://github.com/open-jarvis/OpenJarvis/releases"><img src="https://img.shields.io/github/downloads/open-jarvis/OpenJarvis/total?label=Desktop%20Downloads&logo=github&color=blue" alt="Desktop Downloads"></a>
-  <a href="https://pypistats.org/packages/openjarvisai"><img src="https://img.shields.io/pypi/dm/OpenJarvisAI?label=PyPI%20Installs/month&logo=python&color=blue" alt="PyPI Downloads"></a>
-  <a href="https://github.com/open-jarvis/OpenJarvis"><img src="https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/open-jarvis/OpenJarvis/main/.github/clone-stats/badge.json" alt="Git Clones"></a>
-  <a href="https://github.com/open-jarvis/OpenJarvis"><img src="https://img.shields.io/github/stars/open-jarvis/OpenJarvis?style=social" alt="GitHub Stars"></a>
-</p>
-
 <p class="hero-tagline">
 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.

 ---

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

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

 ---
@@ -176,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)**

@@ -208,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}, 
 }
 ```

@@ -232,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.
@@ -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 = "";
@@ -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,
@@ -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>
--- a/Show More
+++ b/Show More
				`@@ -1 +0,0 @@`
				`{"root":["./src/App.tsx","./src/main.tsx","./src/components/AdminPanel.tsx","./src/components/EnergyDashboard.tsx","./src/components/LearningCurve.tsx","./src/components/MemoryBrowser.tsx","./src/components/TraceDebugger.tsx","./src/components/UpdateChecker.tsx","./src/hooks/useTauriApi.ts"],"version":"5.7.3"}`