AnishSarkar22 · Oct 25, 2026 · Oct 22, 2026 · Oct 22, 2026 · Oct 22, 2026 · Oct 22, 2026
@@ -1 +1 @@
-../../surfsense_backend/.venv/lib/python3.12/site-packages/fastapi/.agents/skills/fastapi
+../../surfsense_local/backend/.venv/lib/python3.12/site-packages/fastapi/.agents/skills/fastapi
@@ -1,11 +1,11 @@
 ---
 name: frontend-workflow
-description: Frontend and UI work in surfsense_web and surfsense_local/frontend — building, refactoring, styling, animating, or reviewing React and Next.js components, shadcn/ui, color tokens and themes, visual polish, and motion. Load this first for any UI task, including adding or changing a shadcn/ui component (dialog, button, dropdown, form, sidebar, table) in a tree with components.json — it owns the color palette, polish rules, and the precedence order, then routes to the separate shadcn skill for component wiring and the CLI. Use for any frontend component, page, style, animation, hover state, icon, layout, or UI review task.
+description: Frontend and UI work in www and surfsense_local/frontend — building, refactoring, styling, animating, or reviewing React and Next.js components, shadcn/ui, color tokens and themes, visual polish, and motion. Load this first for any UI task, including adding or changing a shadcn/ui component (dialog, button, dropdown, form, sidebar, table) in a tree with components.json — it owns the color palette, polish rules, and the precedence order, then routes to the separate shadcn skill for component wiring and the CLI. Use for any frontend component, page, style, animation, hover state, icon, layout, or UI review task.
 ---
 
 # Frontend Workflow
 
-Single entry point for frontend work in `surfsense_web` and
+Single entry point for frontend work in `www` and
 `surfsense_local/frontend`. Both are React + Tailwind + shadcn/ui with their own
 `components.json`. Detect which tree the task touches, and treat that tree's
 `package.json`, `components.json`, and styling setup as authoritative. All

@@ -1,7 +1,7 @@
 # Base UI in the desktop frontend
 
 `surfsense_local/frontend` builds its `components/ui/` on Base UI (shadcn
-`base-nova`). `surfsense_web` is still on Radix (`new-york`): none of this
+`base-nova`). `www` is still on Radix (`new-york`): none of this
 applies there.
 
 These are the rules that compile fine and still break. Check

@@ -4,7 +4,7 @@ One term per concept, so the app says the same thing everywhere. Terms marked wi
 
 ## Stays in English
 
-SurfSense, Studio, Markdown, llama.cpp, GGUF, Hugging Face, API, MCP, the HTTP sign-in schemes Bearer and Basic, and every model and provider name.
+SurfSense, Studio, Markdown, llama.cpp, GGUF, Hugging Face, API, MCP, MCP's transports SSE and Streamable HTTP, the HTTP sign-in schemes Bearer and Basic, the package managers Scoop, AUR, Snap Store, Flatpak, Nix and apt, and every model and provider name.
 
 `workspace` is the one product word languages disagree on, and each keeps its own habit: German and Brazilian Portuguese write Workspace, because both say it routinely and the translation is three times as wide in the sidebar; Japanese writes ワークスペース, since `マイWorkspace` reads as a mistake; the rest translate it.
 
@@ -61,6 +61,8 @@ SurfSense, Studio, Markdown, llama.cpp, GGUF, Hugging Face, API, MCP, the HTTP s
 | server (a model server) | サーバー | 서버 | 服务器 | सर्वर | Server | servidor | serveur | servidor | сервер |
 | provider | プロバイダー | 제공업체 | 提供商 | प्रोवाइडर | Anbieter | proveedor | fournisseur | provedor | провайдер |
 | this computer | このコンピューター | 이 컴퓨터 | 这台电脑 | यह कंप्यूटर | dieser Computer | este equipo | cet ordinateur | este computador | этот компьютер |
+| license key (the user’s key, which the app sends to SurfSense’s plugin service to be checked) | ライセンスキー | 라이선스 키 | 许可证密钥 | लाइसेंस कुंजी | Lizenzschlüssel | clave de licencia | clé de licence | chave de licença | лицензионный ключ |
+| usage statistics (the opt-in daily and weekly report of counts in ranges) | 利用統計 | 사용 통계 | 使用统计 | उपयोग आंकड़े | Nutzungsstatistiken | estadísticas de uso | statistiques d’utilisation | estatísticas de uso | статистика использования |
 | retry | 再試行 | 다시 시도 | 重试 | फिर से कोशिश करें | Erneut versuchen | Reintentar | Réessayer | Tentar novamente | Повторить |
 | plugin (an MCP server whose tools the agent can use) | プラグイン | 플러그인 | 插件 | प्लगइन | Plugin | plugin | plugin | plugin | плагин |
 | third-party (a plugin SurfSense does not publish) | サードパーティ | 서드파티 | 第三方 | थर्ड-पार्टी | Drittanbieter- | de terceros | tiers | de terceiros | сторонний |
@@ -76,8 +78,10 @@ SurfSense, Studio, Markdown, llama.cpp, GGUF, Hugging Face, API, MCP, the HTTP s
 | subscription (using a ChatGPT plan instead of a key) | サブスクリプション | 구독 | 订阅 | सब्सक्रिप्शन | Abo | suscripción | abonnement | assinatura | подписка |
 | terminal (where the user runs `claude`, the command that stays in English) | ターミナル | 터미널 | 终端 | टर्मिनल | Terminal | terminal (una) | terminal | terminal | терминал |
 | header (an HTTP header a plugin's server reads, such as its key in `x-api-key`) | ヘッダー | 헤더 | 请求头 | हेडर | Header | encabezado | en-tête | cabeçalho | заголовок |
+| package manager (installs and updates SurfSense in place of its own updater) | パッケージマネージャー | 패키지 관리자 | 软件包管理器 | पैकेज मैनेजर | Paketmanager | gestor de paquetes | gestionnaire de paquets | gerenciador de pacotes | менеджер пакетов |
 | OAuth app (a user's own, registered with a provider) | OAuthアプリ | OAuth 앱 | OAuth 应用 | OAuth ऐप | OAuth-App | app OAuth | app OAuth | app OAuth | приложение OAuth |
 | client ID (of an OAuth app) | クライアントID | 클라이언트 ID | 客户端 ID | क्लाइंट आईडी | Client-ID | ID de cliente | ID client | ID do cliente | ID клиента |
+| link (a web address the user adds as a source) | リンク | 링크 | 链接 | लिंक | Link | enlace | lien | link | ссылка |
 | client secret (of an OAuth app) | クライアントシークレット | 클라이언트 시크릿 | 客户端密钥 | क्लाइंट सीक्रेट | Client-Secret | secreto de cliente | secret client | segredo do cliente | секрет клиента |
 | scope (an OAuth permission) | スコープ | 범위 | 权限范围 | स्कोप | Scope | ámbito | portée | escopo | область доступа |
 | callback address (where a provider sends the browser back) | コールバックアドレス | 콜백 주소 | 回调地址 | कॉलबैक पता | Callback-Adresse | dirección de callback | adresse de rappel | endereço de callback | адрес обратного вызова |

@@ -25,14 +25,9 @@
 /surfsense_local/RELEASE.md                     @CREDO23 @AnishSarkar22
 /.github/workflows/release-local.yml            @CREDO23 @AnishSarkar22
 
-/surfsense_backend/app/license/                 @CREDO23
-/surfsense_backend/app/mailer/                  @CREDO23
-/surfsense_backend/app/payments/                @CREDO23
-/surfsense_backend/app/sunset.py                @CREDO23
-/surfsense_backend/app/capabilities/            @AnishSarkar22 @MODSetter
-/surfsense_backend/app/proprietary/             @AnishSarkar22 @MODSetter
-/plugins/remote/proprietary/                    @AnishSarkar22 @MODSetter
-/plugins/registry/                              @AnishSarkar22 @MODSetter
+/backend/license/                               @CREDO23
+/backend/mailer/                                @CREDO23
+/backend/plugins/proprietary/                   @AnishSarkar22 @MODSetter
+/backend/plugins/registry/                      @AnishSarkar22 @MODSetter
 
-/surfsense_web/                                 @AnishSarkar22
-/surfsense_mcp/                                 @CREDO23
+/www/                                           @AnishSarkar22
@@ -9,7 +9,7 @@ body:
         Fill this in and a bot checks your server, then comments with what to fix or what happens next. To fix something, edit the issue and it checks again.
 
         **We support** remote MCP servers on a public HTTPS address:
-        - **Transport:** Streamable HTTP, or the older HTTP+SSE.
+        - **Transport:** Streamable HTTP only. Servers on the older HTTP+SSE can't be listed.
         - **Sign-in:** none, a key each user pastes, or OAuth.
 
         Local (stdio) servers can't be listed yet.

@@ -65,7 +65,7 @@ jobs:
         uses: actions/cache@v5
         with:
           path: surfsense_local/electron/audiocpp
-          key: audiocpp-${{ runner.os }}-${{ hashFiles('surfsense_local/electron/scripts/audiocpp/*.mjs', 'surfsense_local/electron/scripts/msvc-runtime.mjs', 'surfsense_local/electron/scripts/pinned-download.mjs') }}
+          key: audiocpp-${{ runner.os }}-${{ hashFiles('surfsense_local/electron/scripts/audiocpp/**/*.mjs', 'surfsense_local/electron/scripts/msvc-runtime.mjs', 'surfsense_local/electron/scripts/pinned-download.mjs') }}
 
       - name: Install GCC 13
         # audio.cpp requires it, and 22.04 has GCC 11. This job, not the
@@ -88,9 +88,11 @@ jobs:
       - name: Gate on the app's Linux floor
         if: runner.os == 'Linux' && steps.cache.outputs.cache-hit != 'true'
         working-directory: surfsense_local/electron/audiocpp
-        # The floor is glibc 2.34, RHEL 9, whose libgcc_s is GCC 11's: nothing
-        # after GCC_7.0.0. The runner's libstdc++ is the PPA's, newer than a
-        # user's, so only this gate, not the voicing test, catches a dynamic one.
+        # glibc 2.34 and RHEL 9's GCC 11 libgcc_s, nothing after GCC_7.0.0:
+        # stricter than the app's Linux floor, glibc 2.35 and GCC 12's libstdc++,
+        # which the backend and llama.cpp set (docs/architecture/packaging.md).
+        # The runner's libstdc++ is the PPA's, newer than a user's, so only this
+        # gate, not the voicing test, catches a dynamic one.
         run: |
           files=$(for f in audiocpp_server *.so*; do [ -L "$f" ] || echo "$f"; done)
           too_new=$(for f in $files; do objdump -T "$f"; done | grep -oE '(GLIBC|GCC)_[0-9.]+[0-9]' | sort -Vu | while read -r v; do

@@ -0,0 +1,152 @@
+# Build opencv-python-headless with only the modules the app calls, from the
+# sdist uv.lock pins and the switches in surfsense_local/backend/scripts/opencv/,
+# check that every cv2 call the app and its parsers make answers byte for byte
+# as PyPI's wheel does, and hand the wheel to the desktop release as an
+# artifact. PyPI's wheel adds video, DNN and the other modules, FFmpeg (Homebrew's
+# GPL build on macOS) and, on Linux, OpenBLAS, none of which the app runs. A pull
+# request that changes the scripts or the lock runs it too.
+name: Build OpenCV
+
+on:
+  workflow_call:
+  pull_request:
+    paths:
+      - surfsense_local/backend/scripts/opencv/**
+      - surfsense_local/backend/uv.lock
+      - .github/workflows/build-opencv.yml
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    name: ${{ matrix.name }}
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          # Pinned: opencv-python's setup.py names Visual Studio 2022's generator,
+          # and windows-latest moved to Visual Studio 2026.
+          - os: windows-2022
+            name: Windows x64
+          - os: macos-15
+            name: macOS arm64
+          # Hosts upstream's manylinux_2_28 image (pins.py), which builds it.
+          - os: ubuntu-22.04
+            name: Linux x64
+    defaults:
+      run:
+        shell: bash
+        working-directory: surfsense_local/backend
+    env:
+      # As the release: uv's own Python, never one found on PATH.
+      UV_PYTHON_PREFERENCE: only-managed
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          # Nothing after the checkout talks to git; the build runs in a container.
+          persist-credentials: false
+
+      - name: Setup uv
+        uses: astral-sh/setup-uv@v8.1.0
+        with:
+          enable-cache: true
+          python-version: "3.12"
+
+      - id: pin
+        name: Read the pinned sdist
+        run: uv run --no-project scripts/opencv/pins.py >> "$GITHUB_OUTPUT"
+
+      # A release that changes neither the pin nor the build reuses the last checked wheel.
+      - id: cache
+        uses: actions/cache@v5
+        with:
+          path: ${{ runner.temp }}/opencv/dist
+          key: opencv-${{ runner.os }}-${{ steps.pin.outputs.sha256 }}-${{ hashFiles('surfsense_local/backend/scripts/opencv/pins.py', 'surfsense_local/backend/scripts/opencv/recipe.py', 'surfsense_local/backend/scripts/opencv/build_wheel.py', 'surfsense_local/backend/scripts/opencv/setup_patch.py') }}
+
+      - name: Install NASM
+        # libjpeg-turbo's x86 SIMD needs it, and the recipe refuses to build without.
+        if: runner.os == 'Windows' && steps.cache.outputs.cache-hit != 'true'
+        run: |
+          choco install nasm --no-progress -y
+          echo "C:/Program Files/NASM" >> "$GITHUB_PATH"
+
+      - name: Build (Windows, macOS)
+        if: runner.os != 'Linux' && steps.cache.outputs.cache-hit != 'true'
+        run: uv run --no-project scripts/opencv/build_wheel.py "$RUNNER_TEMP/opencv"
+
+      - name: Build (Linux)
+        # Upstream's own image: its compiler built PyPI's wheel, and its glibc
+        # 2.28 sits under the app's floor. As root, since the image's own user
+        # cannot write the runner's folders.
+        if: runner.os == 'Linux' && steps.cache.outputs.cache-hit != 'true'
+        run: |
+          docker run --rm -u root -v "$GITHUB_WORKSPACE:/io:ro" -v "$RUNNER_TEMP:/work" \
+            "${{ steps.pin.outputs.linux_image }}" \
+            /opt/python/cp312-cp312/bin/python /io/surfsense_local/backend/scripts/opencv/build_wheel.py /work/opencv
+          sudo chown -R "$(id -u):$(id -g)" "$RUNNER_TEMP/opencv"
+
+      # Cheap, so a cached wheel is checked again too: the cache key does not
+      # cover this workflow, where a floor can move.
+      - name: Gate on the app's Linux floor
+        if: runner.os == 'Linux'
+        working-directory: ${{ runner.temp }}
+        # glibc 2.34 and RHEL 9's GCC 11 libgcc_s and libstdc++, nothing after
+        # GCC_7.0.0, GLIBCXX_3.4.29 or CXXABI_1.3.13: stricter than the app's
+        # Linux floor, glibc 2.35 and GCC 12's libstdc++, which the backend and
+        # llama.cpp set (docs/architecture/packaging.md).
+        # The module links only the C and C++ runtimes and, as upstream's does,
+        # the system's zlib.
+        run: |
+          rm -rf opencv-gate && unzip -q opencv/dist/*.whl -d opencv-gate
+          files=$(find opencv-gate -name '*.so*' -type f)
+          too_new=$(for f in $files; do objdump -T "$f"; done | grep -oE '(GLIBC|GLIBCXX|CXXABI|GCC)_[0-9.]+[0-9]' | sort -Vu | while read -r v; do
+            case "$v" in
+              GLIBC_*) floor=GLIBC_2.34 ;;
+              GLIBCXX_*) floor=GLIBCXX_3.4.29 ;;
+              CXXABI_*) floor=CXXABI_1.3.13 ;;
+              GCC_*) floor=GCC_7.0.0 ;;
+            esac
+            [ "$(printf '%s\n%s\n' "$v" "$floor" | sort -V | tail -1)" = "$floor" ] || echo "$v"
+          done)
+          if [ -n "$too_new" ]; then
+            for f in $files; do objdump -T "$f" | grep -wF "$too_new" | sed "s|^|$f: |"; done
+            exit 1
+          fi
+          needs=$(for f in $files; do objdump -p "$f" | awk '$1 == "NEEDED" {print $2}'; done | sort -u)
+          echo "$needs"
+          outside=$(echo "$needs" | grep -vE '^(libc|libm|libdl|libpthread|librt|libstdc\+\+|libgcc_s|libz|ld-linux-x86-64)\.so' || true)
+          if [ -n "$outside" ]; then echo "links $outside"; exit 1; fi
+
+      - name: Gate on the app's macOS floor
+        if: runner.os == 'macOS'
+        working-directory: ${{ runner.temp }}
+        # 13.3, as the native runtimes; upstream's wheel says 13.0. Every library
+        # it loads is the system's: no Homebrew, so no FFmpeg.
+        run: |
+          rm -rf opencv-gate && unzip -q opencv/dist/*.whl -d opencv-gate
+          bad=0
+          for f in $(find opencv-gate -name '*.so' -o -name '*.dylib'); do
+            minos=$(otool -l "$f" | awk '$1 == "minos" {print $2; exit}')
+            if [ "$(printf '%s\n%s\n' "$minos" 13.3 | sort -V | tail -1)" != "13.3" ]; then
+              echo "$f needs macOS $minos"; bad=1
+            fi
+            outside=$(otool -L "$f" | tail -n +2 | awk '{print $1}' | grep -vE '^(/usr/lib/|/System/Library/)' || true)
+            if [ -n "$outside" ]; then echo "$f links $outside"; bad=1; fi
+          done
+          exit $bad
+
+      # Under PyPI's wheel and then this one, with the backend's locked numpy,
+      # RapidOCR and onnxruntime: every call site's cv2 call on fixed images,
+      # and RapidOCR reading rendered text as the app configures it. Run on a
+      # cached wheel too: the lock can move numpy or RapidOCR without it.
+      - name: Gate on every call answering as PyPI's wheel does
+        run: uv run --no-project scripts/opencv/check_same_outputs.py "$RUNNER_TEMP/opencv/dist" "$RUNNER_TEMP/opencv-check"
+
+      - uses: actions/upload-artifact@v7
+        with:
+          name: opencv-${{ runner.os }}
+          path: ${{ runner.temp }}/opencv/dist/*.whl
+          if-no-files-found: error
+          retention-days: 7
@@ -75,9 +75,11 @@ jobs:
       - name: Gate on the app's Linux floor
         if: runner.os == 'Linux' && steps.cache.outputs.cache-hit != 'true'
         working-directory: surfsense_local/electron/sdcpp
-        # The floor is glibc 2.34, RHEL 9, whose libgcc_s is GCC 11's: nothing
-        # after GCC_7.0.0. Only the Vulkan backend may need the system's Vulkan
-        # loader, which comes with the GPU driver.
+        # glibc 2.34 and RHEL 9's GCC 11 libgcc_s, nothing after GCC_7.0.0:
+        # stricter than the app's Linux floor, glibc 2.35 and GCC 12's libstdc++,
+        # which the backend and llama.cpp set (docs/architecture/packaging.md).
+        # Only the Vulkan backend may need the system's Vulkan loader, which
+        # comes with the GPU driver.
         run: |
           files=$(for f in sd-server *.so*; do [ -L "$f" ] || echo "$f"; done)
           too_new=$(for f in $files; do objdump -T "$f"; done | grep -oE '(GLIBC|GCC)_[0-9.]+[0-9]' | sort -Vu | while read -r v; do

@@ -3,7 +3,7 @@ name: Code Quality Checks
 # Checks that belong to no product, on every PR: file hygiene, docs and
 # secrets. A PR touching only docs/, .github/ or scripts/ starts neither
 # product workflow, so these must not live in one. Each product lints, scans
-# and tests itself: docker-tests.yml and desktop-tests.yml.
+# and tests itself in its own workflow, such as desktop-tests.yml.
 
 on:
   pull_request:
@@ -98,7 +98,7 @@ jobs:
             pre-commit-security-
 
       # Secrets are a leak wherever they land, so this scans every PR. bandit
-      # is per product: docker-tests.yml and desktop-tests.yml run their own.
+      # is per product: desktop-tests.yml runs its own.
       - name: Scan changed files for secrets
         run: |
           if git show-ref --verify --quiet refs/heads/${{ github.base_ref }}; then
@@ -129,7 +129,7 @@ jobs:
       # The checkout is the pull request merged into its base, its first parent.
       - name: Refuse changes to proprietary code
         run: |
-          changed=$(git diff --name-only HEAD^1 HEAD -- surfsense_backend/app/proprietary plugins/remote/proprietary)
+          changed=$(git diff --name-only HEAD^1 HEAD -- backend/plugins/proprietary)
           if [ -n "$changed" ]; then
             echo "::error::Only SurfSense's maintainers change proprietary/ (Business Source License 1.1). See CONTRIBUTING.md."
             echo "$changed"
Original file line number	Diff line number	Diff line change
		@@ -1 +1 @@
		../../surfsense_backend/.venv/lib/python3.12/site-packages/fastapi/.agents/skills/fastapi
		../../surfsense_local/backend/.venv/lib/python3.12/site-packages/fastapi/.agents/skills/fastapi